fix(#3561): route /gsd-map-codebase --fast to a scan.md path the runtime can resolve (#3562)

* test(#3561): failing-first coverage for the --fast dangling dispatch

/gsd-map-codebase --fast routes to "the scan workflow" in prose, but
commands/gsd/map-codebase.md names no resolvable path and its
execution_context includes only map-codebase.md, so scan.md is never
loaded. Same class as epic #1891's F8/F9: dispatch keyed on a token
that never arrives.

Adds workflowPathRefs() to command-contract-helpers.cjs — one shared
pure resolver for the three reference shapes this repo uses (eager
@-include, lazy absolute-ish path, lazy parent-relative steps//modes/
path). Placing it in the helpers module keeps the lint script and the
test suite reading the same definition, which is what that module
exists for; #3560 consumes the same function rather than re-deriving it.

Tests 16/17 are RED until the routing fix lands.

Refs #3561

* fix(#3561): route --fast to a scan.md path the runtime can resolve

commands/gsd/map-codebase.md documented --fast and told the agent to
"run the scan workflow", but named no path and included only
map-codebase.md in execution_context, so gsd-core/workflows/scan.md was
never loaded and the single-agent scan was improvised.

Names the path in the routing line so it is read on demand, rather than
adding an eager @-include: --fast is the minority path and the
progressive-disclosure split (#717) exists to keep the common full-map
invocation from paying for it. The accompanying test pins that choice —
execution_context must still carry exactly one @-ref.

skills/gsd-map-codebase/SKILL.md is regenerated, not hand-edited.

Closes #3561

* fix(#3561): bound the .md match and bind the regression test to the --fast line

Two majors from the isolated adversarial review.

Both resolver regexes ended at a literal .md with no trailing boundary,
so a longer extension was truncated into a plausible-looking but wrong
path: workflows/foobar.mdx returned workflows/foobar.md. Adds a
(?![A-Za-z0-9_]) lookahead to both shapes so .mdx and .md5 are rejected
outright rather than silently rewritten.

The regression test scanned the whole command file, so it did not bind
to the defect — the reviewer showed that an unrelated comment mentioning
scan.md anywhere made it pass while the dispatch defect was still
present. It now extracts the "- If it is `--fast`" bullet and scans that
line alone, and a new test drives a synthetic pre-fix fixture to prove
the false-pass path is closed.

Refs #3561

* chore(#3561): backfill changeset pr number to 3562

---------

Co-authored-by: sim <sim@local>

tests/command-contract.test.cjs

@@ -32,6 +32,7 @@ const {
   CANONICAL_TOOLS,
   parseFrontmatter,
   executionContextRefs,
+  workflowPathRefs,
 } = require('../scripts/command-contract-helpers.cjs');
 
 const commandFiles = fs
@@ -114,6 +115,174 @@ describe('command contract: execution_context @-refs on own line (ADR-0002)', ()
   }
 });
 
+describe('#3561 — workflowPathRefs resolver', () => {
+  test('eager @-include', () => {
+    assert.deepEqual(
+      workflowPathRefs('@~/.claude/gsd-core/workflows/x.md'),
+      ['workflows/x.md'],
+    );
+  });
+
+  test('lazy tilde path', () => {
+    assert.deepEqual(
+      workflowPathRefs('read `~/.claude/gsd-core/workflows/x.md` now'),
+      ['workflows/x.md'],
+    );
+  });
+
+  test('repo-relative path', () => {
+    assert.deepEqual(
+      workflowPathRefs('see gsd-core/workflows/x.md'),
+      ['workflows/x.md'],
+    );
+  });
+
+  test('bare workflows path', () => {
+    assert.deepEqual(
+      workflowPathRefs('see workflows/x.md'),
+      ['workflows/x.md'],
+    );
+  });
+
+  test('parent-relative steps path', () => {
+    assert.deepEqual(
+      workflowPathRefs('run execute-phase/steps/post-merge-gate.md'),
+      ['workflows/execute-phase/steps/post-merge-gate.md'],
+    );
+  });
+
+  test('parent-relative modes path', () => {
+    assert.deepEqual(
+      workflowPathRefs('use discuss-phase/modes/power.md'),
+      ['workflows/discuss-phase/modes/power.md'],
+    );
+  });
+
+  test('empty content yields no refs', () => {
+    assert.deepEqual(workflowPathRefs(''), []);
+  });
+
+  test('unrelated prose yields no refs', () => {
+    assert.deepEqual(workflowPathRefs('nothing to see here'), []);
+  });
+
+  test('whitespace-only yields no refs', () => {
+    assert.deepEqual(workflowPathRefs('   \n\t \n'), []);
+  });
+
+  test('de-duplicates repeated refs', () => {
+    const refs = workflowPathRefs('workflows/x.md and again workflows/x.md');
+    assert.deepEqual(refs, ['workflows/x.md']);
+    assert.equal(refs.length, 1);
+  });
+
+  test('CRLF-tolerant', () => {
+    assert.deepEqual(
+      workflowPathRefs('workflows/a.md\r\nworkflows/b.md'),
+      ['workflows/a.md', 'workflows/b.md'],
+    );
+  });
+
+  test('ignores non-workflow md paths', () => {
+    assert.deepEqual(
+      workflowPathRefs('docs/GUIDE.md README.md references/r.md'),
+      [],
+    );
+  });
+
+  test('surfaces a ref whose target is absent', () => {
+    assert.deepEqual(
+      workflowPathRefs('workflows/does-not-exist.md'),
+      ['workflows/does-not-exist.md'],
+    );
+  });
+
+  test('does not emit a traversing path', () => {
+    const refs = workflowPathRefs('workflows/../../etc/passwd.md');
+    for (const ref of refs) {
+      assert.ok(!ref.includes('..'), `traversal path leaked: ${ref}`);
+    }
+  });
+
+  test('tolerates an overlong path', () => {
+    const content = 'workflows/' + 'a'.repeat(5000) + '.md';
+    assert.doesNotThrow(() => workflowPathRefs(content));
+  });
+
+  test('rejects a .mdx path', () => {
+    assert.deepEqual(workflowPathRefs('workflows/foobar.mdx'), []);
+  });
+
+  test('rejects a .md5 path', () => {
+    assert.deepEqual(workflowPathRefs('workflows/foo.md5'), []);
+  });
+
+  test('still accepts a .md path followed by punctuation', () => {
+    assert.deepEqual(
+      workflowPathRefs('see workflows/x.md, then stop'),
+      ['workflows/x.md'],
+    );
+  });
+
+  test('binds to the --fast line, not the whole file', () => {
+    const syntheticFile = [
+      '- If it is `--fast`: strip the flag, run the scan workflow.',
+      '<!-- see gsd-core/workflows/scan.md -->',
+    ].join('\n');
+    const fastLine = syntheticFile
+      .split(/\r?\n/)
+      .find(line => /^-\s*If it is\s*`--fast`/.test(line));
+    assert.ok(fastLine, 'setup error: synthetic fixture missing --fast routing line');
+    assert.ok(
+      !workflowPathRefs(fastLine).includes('workflows/scan.md'),
+      'regression guard: the --fast routing line itself names no resolvable path — ' +
+      'an unrelated comment elsewhere in the file must not make this test pass',
+    );
+  });
+});
+
+describe('#3561 — /gsd-map-codebase --fast routes to a loadable workflow', () => {
+  const mapCodebasePath = path.join(COMMANDS_DIR, 'map-codebase.md');
+  const mapCodebaseContent = fs.readFileSync(mapCodebasePath, 'utf-8');
+
+  test('map-codebase: --fast routing names a loadable scan.md', () => {
+    const fastLine = mapCodebaseContent
+      .split(/\r?\n/)
+      .find(line => /^-\s*If it is\s*`--fast`/.test(line));
+    assert.ok(
+      fastLine,
+      '#3561: commands/gsd/map-codebase.md has no "--fast" routing bullet ' +
+      '(expected a line matching /^-\\s*If it is\\s*`--fast`/) — the routing logic is missing entirely',
+    );
+    const refs = workflowPathRefs(fastLine);
+    assert.ok(
+      refs.includes('workflows/scan.md'),
+      '#3561: --fast routes to the scan workflow but the routing line names no path ' +
+      'the runtime can resolve, so scan.md is never loaded',
+    );
+  });
+
+  test('full map does not eagerly load scan.md', () => {
+    const refs = executionContextRefs(mapCodebaseContent);
+    assert.equal(refs.length, 1);
+    assert.equal(refs[0].normalized, 'workflows/map-codebase.md');
+  });
+});
+
+describe('#3561 — every workflow path referenced by a command exists on disk', () => {
+  for (const { name, full } of commandFiles) {
+    test(`${name}: all workflowPathRefs paths exist on disk`, () => {
+      const refs = workflowPathRefs(fs.readFileSync(full, 'utf-8'));
+      for (const ref of refs) {
+        assert.ok(
+          fs.existsSync(path.join(GSD_ROOT, ref)),
+          `${name}: referenced workflow path "${ref}" does not exist under ${GSD_ROOT}`,
+        );
+      }
+    });
+  }
+});
+
 
 // ────────────────────────────────────────────────────────────────────────
 // Folded from tests/bug-3168-task-to-agent-rename.test.cjs — consolidation epic #1969 (B3 #1972)