docs(work): refresh stale JSDoc headers in cli + prd-ship

Two stale-comment fixes surfaced after the dispatch handoff fix:

cli.mjs: the top-of-file JSDoc listed only 3 of 8 subcommands
(rebuild-state, status, next) and missed ready / blocked /
dispatch / decompose / prd-ship. Rewrote the header to describe
all 8 subcommands + their flags + the explicit-runCli routing
pattern that replaces the older side-effect-on-import approach
(established when the dispatch handoff broke and got fixed in
bb643b8).

prd-ship.mjs: the JSDoc claimed allowed transitions were
"<approved|in-review|draft> -> shipped", but the code refuses
draft (throws "still draft — flip to approved (human review)
before shipping"). Corrected the doc to "<approved|in-review>
-> shipped" + clarified that draft -> approved is the human step
deliberately kept outside the command's scope.

No behaviour change — comments only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

scripts/work/cli.mjs

@@ -1,11 +1,25 @@
 #!/usr/bin/env node
 /**
- * pnpm work — CLI for the local work-system.
+ * pnpm work — CLI for the local work-system. Routes subcommands to their
+ * respective modules (state-builder, dispatch, decompose, prd-ship). Each
+ * subcommand module also exposes a `runCli(args)` entry point that this
+ * file calls directly; the sibling modules NEVER run as a side effect of
+ * being imported.
  *
  * Subcommands:
- *   rebuild-state   Rewrites docs/work/_state.json from the current markdown
+ *   rebuild-state      Rewrites docs/work/_state.json from the current markdown
- *   status          Prints a tree of all epics + their stories
+ *   status             Prints a tree of all epics + their stories
- *   next            Prints the first non-done story in the first non-done epic
+ *   next               Prints the first ready story (or "All done" / "Blocked: ...")
+ *   ready              Prints every ready story
+ *   blocked            Prints every blocked story + what each is waiting on
+ *   dispatch           Print the next dispatch plan; with --execute invokes
+ *                      sandcastle to run the implementer + reviewer pair
+ *   decompose <id>     Validate an approved PRD + print the decompose plan;
+ *                      with --execute invokes sandcastle's decomposer agent
+ *                      to write the epic folder + per-story files
+ *   prd-ship <id>      Flip a PRD's status to `shipped` (run after its
+ *                      seed epic completes); --commits / --auto-commits
+ *                      optional; idempotent on already-shipped
  */
 import fs from "node:fs";
 import path from "node:path";

scripts/work/prd-ship.mjs

@@ -3,11 +3,12 @@
  *
  * Invoked when an epic completes and its seed PRD's implementation is fully
  * landed. Writes back to the PRD's frontmatter:
- *   - status: <approved|in-review|draft> -> shipped
+ *   - status: <approved|in-review> -> shipped
  *   - shipped: <ISO date> (today, UTC)
  *   - shipping-commits: [<sha1>, <sha2>, ...] (optional)
  *
- * Refuses to flip from `draft` (must go through human review first).
+ * Refuses to flip from `draft` (must go through human review first —
+ * draft -> approved is the human step, NOT automated by this command).
  * Refuses to flip if already `shipped` (idempotent fail-soft).
  *
  * Usage: