fix(#2903): use the command form that actually works in reader-facing docs (#3047)

* fix(#2903): use the command form that actually works in reader-facing docs

Docs told readers to type the colon form, which no runtime registers -- 18 of
19 runtimes use slash-hyphen and the 19th uses shell-var -- so anyone copying an
example got an unrecognized command. Swept 178 occurrences across 53 files,
locale mirrors included so they do not re-diverge from English.

The colon form is a source-authoring token, not a user-facing one: install-time
converters key on it to produce the hyphen form runtimes actually register. So
the sweep is scoped, and three things are deliberately left alone:

- ADRs, which are a historical record; editing their prose falsifies what was
  written at the time.
- The legacy release-notes archive, pending a maintainer decision on whether it
  follows the same historical carve-out. Excluding it keeps a later reversal
  additive rather than a revert.
- Source artifacts under commands, workflows and agents, where the colon form is
  load-bearing. Rewriting those would break the installed-skill guarantee across
  every runtime -- the single largest hazard here.

The plugin namespace form is a real, separate token and survives untouched.

Adds a lint enforcing exactly that boundary, since the correct form genuinely
differs by directory and nothing previously caught the drift.

Also fixes a hardcoded colon form in the capability-matrix generator. The sweep
alone would have left the generated matrix disagreeing with the template that
produces it, so the fix is at the source and the output regenerated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#2903): stop the sweep misquoting source frontmatter

Adversarial review caught three lines where the sweep rewrote a citation of the
literal YAML name: key from a source command file. That key genuinely is the
colon form -- this change's own carve-out logic says source-authoring tokens keep
it -- so the docs ended up misquoting the real files. One of the three is an
acceptance-checklist assertion, which the sweep turned into a false statement.

Restored the three citations to match their sources verbatim, surgically: where a
line carried both a name: citation and a real reader-facing slash command, only
the citation reverted and the command stayed corrected.

The guard needed the same distinction, or it would have flagged the restoration
and reddened the build: a gsd:<cmd> token preceded by name: is a citation of a
source token and is now permitted. The exemption is deliberately narrow -- a bare
gsd:<cmd> anywhere else still fails -- with a test pinning that narrowness.

Also makes the detection case-insensitive. Review found /GSD:next slipped through
silently; no such casing exists in the tree today, so this closes a latent gap
rather than fixing a live one.

Swept the whole tree for further corrupted citations: none beyond the three.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(#2903): retire the stale-next invariant and sweep next like every other command

Maintainer decision on a genuine conflict between two contracts.

Invariant #3054 banned the literal /gsd-next from user-facing docs because it
named a retired workflow-advance command. But commands/gsd/next.md is a live
command -- the state-aware smart-entry launcher -- and this issue requires docs
to use the hyphen form every runtime actually registers. Both could not hold for
this one command, so docs had been sidestepping the ban by keeping the colon
form, which is exactly the defect this issue exists to remove.

FEATURES.md already recorded the reassignment: the hyphen form "is not the
retired workflow-advance command; it is reserved for the state-aware smart-entry
launcher. Workflow advancement remains under /gsd-progress --next." With that
reassignment the invariant's premise is obsolete and the guard now contradicts
the documented command form, so it is retired with a comment recording why
rather than deleted silently.

next is now swept like every other command, and the earlier exemption added to
the new guard is removed so nothing is special-cased.

Four citations of the literal name: frontmatter key stay in colon form, because
the source file really does carry name: gsd:next and a doc quoting it must
reproduce it verbatim. Two of those lines were reworded to say which side is the
frontmatter key and which is the slash command, since they previously conflated
the two.

Verified the retired scan would now genuinely fail against this tree -- the
conflict was real and resolved, not dodged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(#2903): backfill changeset pr number

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

docs/reference/capability-manifest.md

@@ -182,7 +182,7 @@ For a minimal `role: "runtime"` example, see [ADR-1016 §Decision 8](../adr/1016
 
 ## Reviewer body (`role: "reviewer"`, or on any role)
 
-[ADR-2782](../adr/2782-reviewer-lane-capability-surface.md) introduces the *reviewer lane*: one external CLI or model endpoint that `/gsd:review` hands a plan to for independent review.
+[ADR-2782](../adr/2782-reviewer-lane-capability-surface.md) introduces the *reviewer lane*: one external CLI or model endpoint that `/gsd-review` hands a plan to for independent review.
 
 To declare one, follow [Ship a reviewer lane in your capability](../how-to/ship-a-reviewer-lane.md). This section is the field reference behind that guide.
 
@@ -227,7 +227,7 @@ An unknown field inside a `reviewer` body is a **non-fatal warning on stderr, ne
   "role": "reviewer",
   "version": "1.8.0",
   "title": "CodeRabbit",
-  "description": "CodeRabbit CLI — cross-AI /gsd:review reviewer lane only; not a GSD install target (no runtime body, no artifacts).",
+  "description": "CodeRabbit CLI — cross-AI /gsd-review reviewer lane only; not a GSD install target (no runtime body, no artifacts).",
   "tier": "full",
   "requires": [],
   "engines": { "gsd": ">=1.8.0" },

docs/reference/capability-matrix.md

@@ -105,7 +105,7 @@ emission), so their extension-point and hook-kind cells are `—`.
 ### Reviewer capabilities (role: reviewer) — 5
 
 Reviewer capabilities declare a cross-AI **reviewer lane** — one external CLI or
-model endpoint `/gsd:review` hands a plan to (ADR-2782 D3). They are not install
+model endpoint `/gsd-review` hands a plan to (ADR-2782 D3). They are not install
 targets: they emit no skills, agents, hooks or surface files, so their
 extension-point and hook-kind cells are `—`. A host that is *also* a reviewer
 (Claude, Codex, Cursor, OpenCode, Qwen, Antigravity) keeps one manifest and

docs/reference/context-md.md

@@ -1,6 +1,6 @@
 # CONTEXT.md schema reference
 
-A per-phase `CONTEXT.md` is GSD Core's carrier for implementation decisions captured during `/gsd:discuss-phase`. It is the primary upstream input for both the research and planning agents. This page documents its structure. See [docs index](../README.md).
+A per-phase `CONTEXT.md` is GSD Core's carrier for implementation decisions captured during `/gsd-discuss-phase`. It is the primary upstream input for both the research and planning agents. This page documents its structure. See [docs index](../README.md).
 
 ---
 
@@ -107,7 +107,7 @@ A CONTEXT.md where decisions survive into plans is considered compliant. A CONTE
 
 ## SPEC.md integration
 
-When `/gsd:spec-phase` has been run before discussing a phase, the `check_spec` step finds the `*-SPEC.md` file and activates `<spec_lock>`:
+When `/gsd-spec-phase` has been run before discussing a phase, the `check_spec` step finds the `*-SPEC.md` file and activates `<spec_lock>`:
 
 ```markdown
 <spec_lock>

docs/reference/plan-md.md

@@ -14,7 +14,7 @@ Plans live inside phase directories at:
 
 For example: `.planning/phases/03-post-feed/03-02-PLAN.md` (Phase 3, Plan 2).
 
-Plans are produced by the `gsd-planner` agent (spawned by `/gsd:plan-phase`) and consumed by `execute-phase`. A phase typically contains between one and four plans; plans within a phase are assigned to execution waves so that independent work runs in parallel.
+Plans are produced by the `gsd-planner` agent (spawned by `/gsd-plan-phase`) and consumed by `execute-phase`. A phase typically contains between one and four plans; plans within a phase are assigned to execution waves so that independent work runs in parallel.
 
 ---
 
@@ -219,7 +219,7 @@ Full emission rules, anti-patterns ("the system is ready" is not checkable; do n
 
 **Autonomy:** inserting a `checkpoint:decision` means the plan contains a checkpoint, so its frontmatter must set `autonomous: false`.
 
-**Override:** `/gsd:plan-phase --no-reversibility-gates` (`REVERSIBILITY_GATES=false`) suppresses checkpoint insertion for intentionally-unattended runs. Ratings are still recorded and `costly` items are still flagged — the override changes what stops the run, not what the plan remembers.
+**Override:** `/gsd-plan-phase --no-reversibility-gates` (`REVERSIBILITY_GATES=false`) suppresses checkpoint insertion for intentionally-unattended runs. Ratings are still recorded and `costly` items are still flagged — the override changes what stops the run, not what the plan remembers.
 
 Full taxonomy, emission rules, and anti-patterns (chiefly: rating everything `one-way` produces checkpoint fatigue; prefer *removing* irreversibility over gating it): see `gsd-core/references/planner-reversibility.md`.
 

docs/reference/planning-artifacts.md

@@ -198,7 +198,7 @@ actuals:
   commits: 7
 ```
 
-`tokens` uses the **same scale as the estimate**, not a harness-reported token count — an executor subagent cannot read its own consumption, and a ratio between two different measurement methods would measure the methods rather than the miss. `/gsd:extract-learnings` pairs each phase's estimate with its actuals via `gsd_run query estimate-calibrate`, writes `.planning/estimation-calibration.json`, and the planner applies the resulting factor to subsequent estimates. Additive and optional: a summary without `actuals` simply contributes no calibration sample.
+`tokens` uses the **same scale as the estimate**, not a harness-reported token count — an executor subagent cannot read its own consumption, and a ratio between two different measurement methods would measure the methods rather than the miss. `/gsd-extract-learnings` pairs each phase's estimate with its actuals via `gsd_run query estimate-calibrate`, writes `.planning/estimation-calibration.json`, and the planner applies the resulting factor to subsequent estimates. Additive and optional: a summary without `actuals` simply contributes no calibration sample.
 
 ### `<NN>-VERIFICATION.md`
 
@@ -245,7 +245,7 @@ actuals:
 | `status` | enum | Scheduler-agnostic lifecycle state (see below). |
 | `expected_artifacts` | string[] | Paths the job is expected to produce; verified before the plan is closed. |
 | `verification_command` | string | Command that verifies the job's output before close-out. |
-| `resume_command` | string | Exact command to resume GSD reconciliation (re-enter the loop to re-check the job), e.g. `/gsd:execute-phase <phase>`. This is a GSD reconciliation entry point, not a scheduler resubmit. |
+| `resume_command` | string | Exact command to resume GSD reconciliation (re-enter the loop to re-check the job), e.g. `/gsd-execute-phase <phase>`. This is a GSD reconciliation entry point, not a scheduler resubmit. |
 | `submitted_at` | string | ISO 8601 submission timestamp. |
 | `terminal_details` | object \| null | Failure/terminal-state detail; `null` while non-terminal. |
 

docs/reference/review-verification-capabilities.md

@@ -62,9 +62,9 @@ In that output, `configured` reflects config/default resolution, while `active`
 
 Direct command workflows self-gate the same way:
 
-- `/gsd:code-review` resolves the active `execute:post` hook whose `ref.skill == "code-review"`.
-- `/gsd:secure-phase` resolves the active `verify:post` hook whose `ref.skill == "secure-phase"`.
-- `/gsd:validate-phase` resolves the active `verify:post` hook whose `ref.skill == "validate-phase"`.
+- `/gsd-code-review` resolves the active `execute:post` hook whose `ref.skill == "code-review"`.
+- `/gsd-secure-phase` resolves the active `verify:post` hook whose `ref.skill == "secure-phase"`.
+- `/gsd-validate-phase` resolves the active `verify:post` hook whose `ref.skill == "validate-phase"`.
 
 ## Authoring Notes