fix(3054): align docs anchors and structured stale-command checks

.changeset/fix-3054-doc-anchor-and-token-check.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 3114
+---
+**`/gsd-progress --next` doc migration is fully consistent** — command docs now use clear `--next` wording, FEATURES TOC anchors match renamed headings, and regression tests enforce stale-command detection via structured slash-command token checks.

docs/COMMANDS.md

@@ -416,7 +416,7 @@ Show status, next steps, and automatically advance to the next logical workflow
 | `--do "task description"` | Analyze freeform intent and dispatch to the most appropriate GSD command |
 | `--forensic` | Append a 6-check integrity audit after the standard report (STATE consistency, orphaned handoffs, deferred scope drift, memory-flagged pending work, blocking todos, uncommitted code) |
 
-**Auto-routing behavior (absorbed from `/gsd-progress --next`):**
+**Auto-routing behavior (`--next`):**
 - No project → suggests `/gsd-new-project`
 - Phase needs discussion → runs `/gsd-discuss-phase`
 - Phase needs planning → runs `/gsd-plan-phase`

docs/FEATURES.md

@@ -120,7 +120,7 @@
   - [Autonomous Audit-to-Fix](#98-autonomous-audit-to-fix)
   - [Improved Prompt Injection Scanner](#99-improved-prompt-injection-scanner)
   - [Stall Detection in Plan-Phase](#100-stall-detection-in-plan-phase)
-  - [Hard Stop Safety Gates in /gsd-progress --next](#101-hard-stop-safety-gates-in-gsd-next)
+  - [Hard Stop Safety Gates in /gsd-progress --next](#101-hard-stop-safety-gates-in-gsd-progress---next)
   - [Adaptive Model Preset](#102-adaptive-model-preset)
   - [Post-Merge Hunk Verification](#103-post-merge-hunk-verification)
 - [v1.35.0 Features](#v1350-features)
@@ -2023,7 +2023,7 @@ Test suite that scans all agent, workflow, and command files for embedded inject
   - [Autonomous Audit-to-Fix](#98-autonomous-audit-to-fix)
   - [Improved Prompt Injection Scanner](#99-improved-prompt-injection-scanner)
   - [Stall Detection in Plan-Phase](#100-stall-detection-in-plan-phase)
-  - [Hard Stop Safety Gates in /gsd-progress --next](#101-hard-stop-safety-gates-in-gsd-next)
+  - [Hard Stop Safety Gates in /gsd-progress --next](#101-hard-stop-safety-gates-in-gsd-progress---next)
   - [Adaptive Model Preset](#102-adaptive-model-preset)
   - [Post-Merge Hunk Verification](#103-post-merge-hunk-verification)
 

tests/bug-3054-stale-gsd-next-references.test.cjs

@@ -15,6 +15,16 @@ function walkMd(dir, out = []) {
   return out;
 }
 
+function extractSlashCommandTokens(markdown) {
+  const tokenRe = /\/gsd-[a-z0-9-]+/gi;
+  const tokens = new Set();
+  let m;
+  while ((m = tokenRe.exec(markdown)) !== null) {
+    tokens.add(m[0]);
+  }
+  return tokens;
+}
+
 describe('bug #3054: user-facing docs should not reference removed /gsd-next command', () => {
   test('docs, workflows, and README surfaces use /gsd-progress --next instead', () => {
     const root = path.join(__dirname, '..');
@@ -27,7 +37,8 @@ describe('bug #3054: user-facing docs should not reference removed /gsd-next com
     const offenders = [];
     for (const file of files) {
       const content = fs.readFileSync(file, 'utf8');
-      if (content.includes('/gsd-next')) offenders.push(path.relative(root, file));
+      const tokens = extractSlashCommandTokens(content);
+      if (tokens.has('/gsd-next')) offenders.push(path.relative(root, file));
     }
 
     assert.deepStrictEqual(offenders, [], `stale /gsd-next references remain in: ${offenders.join(', ')}`);