feat(#1877): restructure hive-forge into pr/issue sub-verbs

Group issue/PR operations under `pr` and `issue` parent commands
(`hive-forge pr close 42`, `issue create …`, `pr status --pr 42`) per the
operator decision — kind-namespaced verbs replace the flat surface.

- new `verbs::pr_cmd` / `verbs::issue_cmd` parent commands wrap the existing
  per-verb modules (reuse their Args + run fns) under `#[command(subcommand)]`.
- kind-validation (the win over the old generic verbs): the generics that work
  on both (view/comment/comments/close/labels/assign/timeline) call
  `assert_kind` first, so `pr close <issue>` / `issue close <pr>` are rejected
  with a 'use the other command' message. PR-only / issue-only verbs are
  kind-correct by construction. `number` exposed `pub(crate)` on the shared
  verbs so the wrappers can probe it.
- every flat kind verb (`close`, `pr-create`, `pr-status`, `issue-edit`, …)
  kept as a `#[command(hide = true)]` back-compat alias — still parses, dropped
  from --help; removed in a later sweep once usage migrates. (`pr`/`issue`
  bare-show become `pr show` / `issue show` — the names are now parents.)
- docs/tools/forge.md documents the new surface + the deprecated aliases.

cargo build/clippy/fmt clean, 54 tests pass; --help surface + alias parsing
smoke-tested.

hive-forge/src/main.rs

@@ -47,39 +47,54 @@ struct Cli {
 
 #[derive(Subcommand)]
 enum Verb {
+    // The kind verbs below are hidden back-compat aliases of the new
+    // `pr <verb>` / `issue <verb>` forms (`pr-close` -> `pr close`, bare
+    // `close` -> `pr close` / `issue close`, etc.). They still parse but are
+    // dropped from `--help`; a later change removes them once usage migrates.
     /// Dump title + body + all comments for an issue or PR.
+    #[command(hide = true)]
     View(verbs::view::Args),
-    /// Print key fields of an issue as JSON.
-    Issue(verbs::issue::Args),
+    /// Issue-scoped commands: `issue <show|create|edit|view|comment|comments|close|labels|assign|timeline> …`.
+    Issue(verbs::issue_cmd::Args),
     /// Create an issue. Prints the issue URL on success.
+    #[command(hide = true)]
     IssueCreate(verbs::issue_create::Args),
     /// Edit an issue's title, body, state, or milestone.
+    #[command(hide = true)]
     IssueEdit(verbs::issue_edit::Args),
-    /// Print key fields of a PR as JSON.
-    Pr(verbs::pr::Args),
+    /// PR-scoped commands: `pr <show|status|create|merge|reviews|commits|diff|view|comment|comments|close|labels|assign|timeline> …`.
+    Pr(verbs::pr_cmd::Args),
     /// List a PR's commits as JSON (sha, message, author date, author).
     /// Survives rebase-rewritten shas — message + author date let a
     /// caller match the rows against linear `main` history.
+    #[command(hide = true)]
     PrCommits(verbs::pr_commits::Args),
     /// Create a pull request. Prints the PR URL on success.
+    #[command(hide = true)]
     PrCreate(verbs::pr_create::Args),
     /// Post a comment on an issue or PR.
+    #[command(hide = true)]
     Comment(verbs::comment::Args),
     /// List all comments on an issue or PR.
+    #[command(hide = true)]
     Comments(verbs::comments::Args),
     /// Print the body (or full JSON) of a single comment by id.
     CommentShow(verbs::comment_show::Args),
     /// Edit an existing comment by id.
     CommentEdit(verbs::comment_edit::Args),
     /// Assign or unassign a user on an issue or PR.
+    #[command(hide = true)]
     Assign(verbs::assign::Args),
     /// Close an issue or PR.
+    #[command(hide = true)]
     Close(verbs::close::Args),
     /// List, add, or remove labels on an issue or PR.
+    #[command(hide = true)]
     Labels(verbs::labels::Args),
     /// PR health view: mergeable state, CI checks, requested reviewers +
     /// review verdicts, last-comment time (`--pr <n>`). `--sha` is a
     /// CI-only fast path. Exit code is a merge-readiness verdict.
+    #[command(hide = true)]
     PrStatus(verbs::pr_status::Args),
     /// Clone a forge repo (default `-r`/`HIVE_FORGE_REPO`) with
     /// credentials auto-injected. Pairs with `pr-create --agit`.
@@ -113,21 +128,25 @@ enum Verb {
     /// Merge a PR (`--method merge|rebase`, default merge). Refuses unless
     /// mergeable + CI not red + no changes requested (`--force` overrides).
     /// Deletes the head branch unless `--keep-branch`. No squash option.
+    #[command(hide = true)]
     PrMerge(verbs::pr_merge::Args),
     /// List a PR's reviews, or submit one: `--approve` /
     /// `--request-changes` / `--comment` (with `-m` for the body).
+    #[command(hide = true)]
     PrReviews(verbs::pr_reviews::Args),
     /// List branches, optionally filtered.
     Branches(verbs::branches::Args),
     /// Print the tree SHA at a branch or commit.
     TreeSha(verbs::tree_sha::Args),
     /// Print the unified diff for a PR.
+    #[command(hide = true)]
     Diff(verbs::diff::Args),
     /// Get or set this user's watch subscription on a repo.
     Subscription(verbs::subscription::Args),
     /// List timeline events on an issue or PR (closes, label adds,
     /// assignments, commit refs, pushes, etc.) — the audit trail
     /// `view` + `comments` don't surface.
+    #[command(hide = true)]
     Timeline(verbs::timeline::Args),
     /// Upload a file as an attachment to an issue.
     AttachIssue(verbs::attach::IssueArgs),
@@ -152,10 +171,10 @@ fn main() -> Result<()> {
     let client = client::Client::from_env(cli.repo, cli.json).context("initialize forge client")?;
     match cli.verb {
         Verb::View(a) => verbs::view::run(&client, a),
-        Verb::Issue(a) => verbs::issue::run(&client, a),
+        Verb::Issue(a) => verbs::issue_cmd::run(&client, a),
         Verb::IssueCreate(a) => verbs::issue_create::run(&client, a),
         Verb::IssueEdit(a) => verbs::issue_edit::run(&client, a),
-        Verb::Pr(a) => verbs::pr::run(&client, a),
+        Verb::Pr(a) => verbs::pr_cmd::run(&client, a),
         Verb::PrCommits(a) => verbs::pr_commits::run(&client, a),
         Verb::PrCreate(a) => verbs::pr_create::run(&client, a),
         Verb::Comment(a) => verbs::comment::run(&client, a),