feat: Phase 2 caller migration — gsd-sdk query in workflows, agents, commands (#2179)

* feat: Phase 2 caller migration — gsd-sdk query in workflows (#2122)

Cherry-picked orchestration rewrites from feat/sdk-foundation (#2008, 4018fee) onto current main, resolving conflicts to keep upstream worktree guards and post-merge test gate. SDK stub registry omitted (out of Phase 2 scope per #2122).

Refs: #2122 #2008
Made-with: Cursor

* docs: add gsd-sdk query migration blurb

Made-with: Cursor

* docs(workflows): extend Phase 2 gsd-sdk query caller migration

- Swap node gsd-tools.cjs for gsd-sdk query in review, plan-phase, execute-plan,
  ship, extract_learnings, ai-integration-phase, eval-review, next, thread
- Document graphify CJS-only in gsd-planner; dual-path in CLI-TOOLS and ARCHITECTURE
- Update tests: workstreams gsd-sdk path, thread frontmatter.get, workspace init.*,
  CRLF-safe autonomous frontmatter parse
- CHANGELOG: Phase 2 caller migration scope

Made-with: Cursor

* docs(phase2): USER-GUIDE + remaining gsd-sdk query call sites

- USER-GUIDE: dual-path CLI section; state validate/sync use full CJS path
- Commands: debug (config-get+tdd), quick (security note), intel Task prompt
- Agent: gsd-debug-session-manager resolve-model via jq
- Workflows: milestone-summary, forensics, next, complete-milestone/verify-work
  (audit-open CJS notes), discuss-phase, progress, verify-phase, add/insert/remove
  phase, transition, manager, quick workflow; remove-phase commit without --files
- Test: quick-session-management accepts frontmatter.get
- CHANGELOG: Phase 2 follow-up bullet

Made-with: Cursor

* docs(phase2): align gsd-sdk query examples in commands and agents

- init.* query names; frontmatter.get uses positional field name
- state.* handlers use positional args; commit uses positional paths
- CJS-only notes for from-gsd2 and graphify; learnings.query wording
- CHANGELOG: Phase 2 orchestration doc pass

Made-with: Cursor

* docs(phase2): normalize gsd-sdk query commit to positional file paths

- Strip --files from commit examples in workflows, references, commands
- Keep commit-to-subrepo ... --files (separate handler)
- git-planning-commit.md: document positional args
- Tests: new-project commit line, state.record-session, gates CRLF, roadmap.analyze
- CHANGELOG [Unreleased]

Made-with: Cursor

* feat(sdk): gsd-sdk query parity with gsd-tools and PR 2179 registry fixes

- Route query via longest-prefix match and dotted single-token expansion; fall back
  to runGsdToolsQuery (same argv as node gsd-tools.cjs) for full CLI coverage.
- Parse gsd-sdk query permissively so gsd-tools flags (--json, --verify, etc.) are
  not rejected by strict parseArgs.
- resolveGsdToolsPath: honor GSD_TOOLS_PATH; prefer bundled get-shit-done copy
  over project .claude installs; export runGsdToolsQuery from the SDK.
- Fix gsd-tools audit-open (core.output; pass object for --json JSON).
- Register summary-extract as alias of summary.extract; fix audit-fix workflow to
  call audit-uat instead of invalid init.audit-uat (PR review).

Updates QUERY-HANDLERS.md and CHANGELOG [Unreleased].

Made-with: Cursor

* fix(sdk): Phase 2 scope — Trek-e review (#2179, #2122)

- Remove gsd-sdk query passthrough to gsd-tools.cjs; drop GSD_TOOLS_PATH
- Consolidate argv routing in resolveQueryArgv(); update USAGE and QUERY-HANDLERS
- Surface @file: read failures in GSDTools.parseOutput
- execute-plan: defer Task Commit Protocol to gsd-executor
- stale-colon-refs: skip .planning/ and root CLAUDE.md (gitignored overlays)
- CHANGELOG [Unreleased]: maintainer review and routing notes

Made-with: Cursor

tests/autonomous-allowed-tools.test.cjs

@@ -18,7 +18,7 @@ describe('commands/gsd/autonomous.md allowed-tools', () => {
     const content = fs.readFileSync(filePath, 'utf-8');
 
     // Extract the YAML frontmatter block between the first pair of --- delimiters
-    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     assert.ok(frontmatterMatch, 'autonomous.md must have YAML frontmatter');
 
     const frontmatter = frontmatterMatch[1];

tests/claude-md.test.cjs

@@ -69,7 +69,10 @@ describe('new-project workflow includes CLAUDE.md generation', () => {
     const content = fs.readFileSync(workflowPath, 'utf-8');
     assert.ok(content.includes('generate-claude-md'));
     // Codex fix: workflow now uses $INSTRUCTION_FILE (AGENTS.md for Codex, CLAUDE.md otherwise)
-    assert.ok(content.includes('--files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md "$INSTRUCTION_FILE"'));
+    assert.ok(
+      content.includes('.planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md "$INSTRUCTION_FILE"'),
+      'final roadmap commit should stage ROADMAP, STATE, REQUIREMENTS, and instruction file'
+    );
   });
 
   test('new-project artifacts reference instruction file variable', () => {

tests/forensics.test.cjs

@@ -141,8 +141,8 @@ describe('forensics workflow', () => {
   test('workflow updates STATE.md', () => {
     const content = fs.readFileSync(workflowPath, 'utf-8');
     assert.ok(
-      content.includes('state record-session'),
-      'should update STATE.md via gsd-tools'
+      content.includes('state record-session') || content.includes('state.record-session'),
+      'should update STATE.md via state record-session (CJS or gsd-sdk query)'
     );
   });
 

tests/gates-taxonomy.test.cjs

@@ -89,7 +89,7 @@ describe('gates taxonomy (#1715)', () => {
   test('gsd-plan-checker.md references gates.md in required_reading block', () => {
     const planChecker = path.join(ROOT, 'agents', 'gsd-plan-checker.md');
     const content = fs.readFileSync(planChecker, 'utf-8');
-    const match = content.match(/<required_reading>\n([\s\S]*?)\n<\/required_reading>/);
+    const match = content.match(/<required_reading>\r?\n([\s\S]*?)\r?\n<\/required_reading>/);
     assert.ok(
       match,
       'gsd-plan-checker.md must have a <required_reading> block'
@@ -103,7 +103,7 @@ describe('gates taxonomy (#1715)', () => {
   test('gsd-verifier.md references gates.md in required_reading block', () => {
     const verifier = path.join(ROOT, 'agents', 'gsd-verifier.md');
     const content = fs.readFileSync(verifier, 'utf-8');
-    const match = content.match(/<required_reading>\n([\s\S]*?)\n<\/required_reading>/);
+    const match = content.match(/<required_reading>\r?\n([\s\S]*?)\r?\n<\/required_reading>/);
     assert.ok(
       match,
       'gsd-verifier.md must have a <required_reading> block'

tests/gsd-tools-path-refs.test.cjs

@@ -38,20 +38,24 @@ describe('command files: gsd-tools path references (#1766)', () => {
       'Violations:\n' + violations.join('\n'));
   });
 
-  test('workstreams.md uses standard gsd-tools.cjs path', () => {
+  test('workstreams.md documents gsd-sdk query or legacy gsd-tools.cjs', () => {
     const content = fs.readFileSync(
       path.join(COMMANDS_DIR, 'workstreams.md'), 'utf-8'
     );
-    const nodeLines = content.split('\n').filter(l => /node\s/.test(l));
 
-    assert.ok(nodeLines.length > 0,
-      'workstreams.md should contain node invocations');
+    assert.ok(
+      /gsd-sdk\s+query/.test(content) || /gsd-tools\.cjs/.test(content),
+      'workstreams.md should document gsd-sdk query or gsd-tools.cjs'
+    );
 
-    for (const line of nodeLines) {
-      assert.ok(
-        line.includes('gsd-tools.cjs'),
-        'Each node invocation must reference gsd-tools.cjs, got: ' + line.trim()
-      );
+    const lines = content.split('\n');
+    for (const line of lines) {
+      if (/node\s/.test(line)) {
+        assert.ok(
+          line.includes('gsd-tools.cjs'),
+          'Each node invocation must reference gsd-tools.cjs, got: ' + line.trim()
+        );
+      }
     }
   });
 });

tests/milestone-summary.test.cjs

@@ -107,8 +107,8 @@ describe('milestone-summary workflow', () => {
   test('workflow updates STATE.md', () => {
     const content = fs.readFileSync(workflowPath, 'utf-8');
     assert.ok(
-      content.includes('state record-session'),
-      'should update STATE.md via gsd-tools'
+      content.includes('state record-session') || content.includes('state.record-session'),
+      'should update STATE.md via state record-session (CJS or gsd-sdk query)'
     );
   });
 

tests/quick-session-management.test.cjs

@@ -57,8 +57,8 @@ describe('quick session management (#2155)', () => {
 
   test('quick command list uses frontmatter get for status', () => {
     assert.ok(
-      quickCmd.includes('frontmatter get'),
-      'list should use frontmatter get to read status'
+      quickCmd.includes('frontmatter get') || quickCmd.includes('frontmatter.get'),
+      'list should use frontmatter get / frontmatter.get to read status'
     );
   });
 

tests/stale-colon-refs.test.cjs

@@ -20,10 +20,11 @@ const ROOT = path.resolve(__dirname, '..');
 
 /**
  * Recursively collect files matching the given extensions, excluding
- * CHANGELOG.md, node_modules/, .git/, and dist/.
+ * CHANGELOG.md, node_modules/, .git/, dist/, local planning overlays, and
+ * root CLAUDE.md (gitignored local IDE overlay — see repo .gitignore).
  */
 function collectFiles(dir, extensions, results = []) {
-  const EXCLUDED_DIRS = new Set(['node_modules', '.git', 'dist', '.claude', '.worktrees']);
+  const EXCLUDED_DIRS = new Set(['node_modules', '.git', 'dist', '.claude', '.worktrees', '.planning']);
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -36,6 +37,9 @@ function collectFiles(dir, extensions, results = []) {
     if (entry.isDirectory()) {
       collectFiles(full, extensions, results);
     } else if (entry.isFile()) {
+      if (entry.name === 'CLAUDE.md' && path.resolve(dir) === path.resolve(ROOT)) {
+        continue;
+      }
       const ext = path.extname(entry.name);
       if (extensions.has(ext) && entry.name !== 'CHANGELOG.md') {
         results.push(full);

tests/thread-session-management.test.cjs

@@ -66,8 +66,8 @@ describe('thread session management (#2156)', () => {
 
   test('thread command list reads frontmatter status', () => {
     assert.ok(
-      threadCmd.includes('frontmatter get'),
-      'list mode should read status via frontmatter get'
+      threadCmd.includes('frontmatter get') || threadCmd.includes('frontmatter.get'),
+      'list mode should read status via frontmatter get / frontmatter.get'
     );
   });
 

tests/verifier-deferred-items.test.cjs

@@ -36,8 +36,8 @@ describe('verifier deferred-items filtering (#1624)', () => {
     test('Step 9b references roadmap analyze for cross-referencing', () => {
       verifierContent = verifierContent || fs.readFileSync(verifierPath, 'utf-8');
       assert.ok(
-        verifierContent.includes('roadmap analyze'),
-        'Step 9b should reference "roadmap analyze" command for loading full milestone data'
+        verifierContent.includes('roadmap analyze') || verifierContent.includes('roadmap.analyze'),
+        'Step 9b should reference roadmap analyze (CJS or gsd-sdk query) for loading full milestone data'
       );
     });
 

tests/workspace.test.cjs

@@ -338,7 +338,10 @@ describe('workspace command files', () => {
 
   test('new-workspace workflow exists', () => {
     const content = fs.readFileSync(path.join(baseDir, 'get-shit-done/workflows/new-workspace.md'), 'utf8');
-    assert.ok(content.includes('init new-workspace'));
+    assert.ok(
+      content.includes('init new-workspace') || content.includes('init.new-workspace'),
+      'expected init new-workspace (CJS) or gsd-sdk query init.new-workspace'
+    );
     assert.ok(content.includes('WORKSPACE.md'));
     assert.ok(content.includes('git worktree add'));
     assert.ok(content.includes('git clone'));
@@ -346,12 +349,18 @@ describe('workspace command files', () => {
 
   test('list-workspaces workflow exists', () => {
     const content = fs.readFileSync(path.join(baseDir, 'get-shit-done/workflows/list-workspaces.md'), 'utf8');
-    assert.ok(content.includes('init list-workspaces'));
+    assert.ok(
+      content.includes('init list-workspaces') || content.includes('init.list-workspaces'),
+      'expected init list-workspaces or gsd-sdk query init.list-workspaces'
+    );
   });
 
   test('remove-workspace workflow exists', () => {
     const content = fs.readFileSync(path.join(baseDir, 'get-shit-done/workflows/remove-workspace.md'), 'utf8');
-    assert.ok(content.includes('init remove-workspace'));
+    assert.ok(
+      content.includes('init remove-workspace') || content.includes('init.remove-workspace'),
+      'expected init remove-workspace or gsd-sdk query init.remove-workspace'
+    );
     assert.ok(content.includes('git worktree remove'));
   });
 });