feat(sdk): golden parity harness and query handler CJS alignment (#2302 Track A) (#2341)

* feat(sdk): golden parity harness and query handler CJS alignment (#2302 Track A) Golden/read-only parity tests and registry alignment, query handler fixes (check-completion, state-mutation, commit, validate, summary, etc.), and WAITING.json dual-write for .gsd/.planning readers. Refs gsd-build/get-shit-done#2341 * fix(sdk): getMilestoneInfo matches GSD ROADMAP (🟡, last bold, STATE fallback) - Recognize in-flight 🟡 milestone bullets like 🚧. - Derive from last **vX.Y Title** before ## Phases when emoji absent. - Fall back to STATE.md milestone when ROADMAP is missing; use last bare vX.Y in cleaned text instead of first (avoids v1.0 from shipped list). - Fixes init.execute-phase milestone_version and buildStateFrontmatter after state.begin-phase (syncStateFrontmatter). * feat(sdk): phase list, plan task structure, requirements extract handlers - Register phase.list-plans, phase.list-artifacts, plan.task-structure, requirements.extract-from-plans (SDK-only; golden-policy exceptions). - Add unit tests; document in QUERY-HANDLERS.md. - writeProfile: honor --output, render dimensions, return profile_path and dimensions_scored. * feat(sdk): centralize getGsdAgentsDir in query helpers Extract agent directory resolution to helpers (GSD_AGENTS_DIR, primary ~/.claude/agents, legacy path). Use from init and docs-init init bundles. docs(15): add 15-CONTEXT for autonomous phase-15 run. * feat(sdk): query CLI CJS fallback and session correlation - createRegistry(eventStream, sessionId) threads correlation into mutation events - gsd-sdk query falls back to gsd-tools.cjs when no native handler matches (disable with GSD_QUERY_FALLBACK=off); stderr bridge warnings - Export createRegistry from @gsd-build/sdk; add sdk/README.md - Update QUERY-HANDLERS.md and registry module docs for fallback + sessionId - Agents: prefer node dist/cli.js query over cat/grep for STATE and plans * fix(sdk): init phase_found parity, docs-init agents path, state field extract - Normalize findPhase not-found to null before roadmap fallback (matches findPhaseInternal) - docs-init: use detectRuntime + resolveAgentsDir for checkAgentsInstalled - state.cjs stateExtractField: horizontal whitespace only after colon (YAML progress guard) - Tests: commit_docs default true; config-get golden uses temp config; golden integration green Refs: #2302 * refactor(sdk): share SessionJsonlRecord in profile-extract-messages CodeRabbit nit: dedupe JSONL record shape for isGenuineUserMessage and streamExtractMessages. * fix(sdk): address CodeRabbit major threads (paths, gates, audit, verify) - Resolve @file: and CLI JSON indirection relative to projectDir; guard empty normalized query command - plan.task-structure + intel extract/patch-meta: resolvePathUnderProject containment - check.config-gates: safe string booleans; plan_checker alias precedence over plan_check default - state.validate/sync: phaseTokenMatches + comparePhaseNum ordering - verify.schema-drift: token match phase dirs; files_modified from parsed frontmatter - audit-open: has_scan_errors, unreadable rows, human report when scans fail - requirements PLANNED key PLAN for root PLAN.md; gsd-tools timeout note - ingest-docs: repo-root path containment; classifier output slug-hash Golden parity test strips has_scan_errors until CJS adds field. * fix: Resolve CodeRabbit security and quality findings - Secure intel.ts and cli.ts against path traversal - Catch and validate git add status in commit.ts - Expand roadmap milestone marker extraction - Fix parsing array-of-objects in frontmatter YAML - Fix unhandled config evaluations - Improve coverage test parity mapping * test: raise planner character extraction limit to 48K * fix(sdk): resolve TS build error in docs-init passing config
2026-04-20 18:09:02 -04:00
parent c8807e38d7
commit c5b1445529
109 changed files with 11588 additions and 1030 deletions
--- a/sdk/src/query/init.ts
+++ b/sdk/src/query/init.ts
@@ -23,7 +23,7 @@ import { join, relative, basename } from 'node:path';
 import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';

-import { loadConfig } from '../config.js';
+import { loadConfig, type GSDConfig } from '../config.js';
 import { resolveModel, MODEL_PROFILES } from './config-query.js';
 import { findPhase } from './phase.js';
 import { roadmapGetPhase, getMilestoneInfo } from './roadmap.js';
@@ -119,10 +119,19 @@ async function getPhaseInfoWithFallback(
 ): Promise<{ phaseInfo: Record<string, unknown> | null; roadmapPhase: Record<string, unknown> | null }> {
  const phaseResult = await findPhase([phase], projectDir);
  let phaseInfo = phaseResult.data as Record<string, unknown> | null;
+  // findPhase returns { found: false } when missing; findPhaseInternal returns null — align for init parity.
+  if (phaseInfo && phaseInfo.found === false) {
+    phaseInfo = null;
+  }

  const roadmapResult = await roadmapGetPhase([phase], projectDir);
  const roadmapPhase = roadmapResult.data as Record<string, unknown> | null;

+  // Match init.cjs: drop archived disk match when the phase is listed in the current ROADMAP
+  if (phaseInfo?.archived && roadmapPhase?.found) {
+    phaseInfo = null;
+  }
+
  // Fallback to ROADMAP.md if no phase directory exists yet
  if ((!phaseInfo || !phaseInfo.found) && roadmapPhase?.found) {
    const phaseName = roadmapPhase.phase_name as string;
@@ -145,6 +154,48 @@ async function getPhaseInfoWithFallback(
  return { phaseInfo, roadmapPhase };
 }

+/**
+ * Phase resolution for `init verify-work` — matches init.cjs cmdInitVerifyWork (archived + fallback).
+ */
+async function getPhaseInfoForVerifyWork(
+  phase: string,
+  projectDir: string,
+): Promise<{ phaseInfo: Record<string, unknown> | null }> {
+  const phaseResult = await findPhase([phase], projectDir);
+  let phaseInfo = phaseResult.data as Record<string, unknown> | null;
+  if (phaseInfo && phaseInfo.found === false) {
+    phaseInfo = null;
+  }
+
+  const roadmapResult = await roadmapGetPhase([phase], projectDir);
+  const roadmapPhase = roadmapResult.data as Record<string, unknown> | null;
+
+  if (phaseInfo?.archived && roadmapPhase?.found) {
+    phaseInfo = null;
+  }
+
+  if (!phaseInfo && roadmapPhase?.found) {
+    const phaseName = roadmapPhase.phase_name as string;
+    phaseInfo = {
+      found: true,
+      directory: null,
+      phase_number: roadmapPhase.phase_number,
+      phase_name: phaseName,
+      phase_slug: phaseName
+        ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+        : null,
+      plans: [],
+      summaries: [],
+      incomplete_plans: [],
+      has_research: false,
+      has_context: false,
+      has_verification: false,
+    };
+  }
+
+  return { phaseInfo };
+}
+
 /**
 * Extract requirement IDs from roadmap section text.
 */
@@ -163,7 +214,7 @@ function extractReqIds(roadmapPhase: Record<string, unknown> | null): string | n
 * Inject project_root, agents_installed, missing_agents, and response_language
 * into an init result object.
 *
- * Port of withProjectRoot from init.cjs lines 32-48.
+ * Port of withProjectRoot from init.cjs lines 32-63.
 *
 * @param projectDir - Absolute project root path
 * @param result - The result object to augment
@@ -186,6 +237,24 @@ export function withProjectRoot(
    result.response_language = responseLang;
  }

+  const projectCode = config?.project_code;
+  if (projectCode) {
+    result.project_code = projectCode;
+  }
+
+  const projectMdPath = join(projectDir, '.planning', 'PROJECT.md');
+  try {
+    if (existsSync(projectMdPath)) {
+      const content = readFileSync(projectMdPath, 'utf-8');
+      const h1Match = content.match(/^#\s+(.+)$/m);
+      if (h1Match) {
+        result.project_title = h1Match[1].trim();
+      }
+    }
+  } catch {
+    /* intentionally empty */
+  }
+
  return result;
 }

@@ -214,7 +283,6 @@ export const initExecutePhase: QueryHandler = async (args, projectDir) => {

  const milestone = await getMilestoneInfo(projectDir);

-  const phaseFound = !!(phaseInfo && phaseInfo.found);
  const phaseNumber = (phaseInfo?.phase_number as string) || null;
  const phaseSlug = (phaseInfo?.phase_slug as string) || null;
  const plans = (phaseInfo?.plans || []) as string[];
@@ -225,6 +293,7 @@ export const initExecutePhase: QueryHandler = async (args, projectDir) => {
  const result: Record<string, unknown> = {
    executor_model: executorModel,
    verifier_model: verifierModel,
+    tdd_mode: config.workflow.tdd_mode ?? false,
    commit_docs: config.commit_docs,
    sub_repos: (config as Record<string, unknown>).sub_repos ?? [],
    parallelization: config.parallelization,
@@ -233,7 +302,7 @@ export const initExecutePhase: QueryHandler = async (args, projectDir) => {
    phase_branch_template: config.git.phase_branch_template,
    milestone_branch_template: config.git.milestone_branch_template,
    verifier_enabled: config.workflow.verifier,
-    phase_found: phaseFound,
+    phase_found: !!phaseInfo,
    phase_dir: (phaseInfo?.directory as string) ?? null,
    phase_number: phaseNumber,
    phase_name: (phaseInfo?.phase_name as string) ?? null,
@@ -292,20 +361,24 @@ export const initPlanPhase: QueryHandler = async (args, projectDir) => {
    getModelAlias('gsd-plan-checker', projectDir),
  ]);

-  const phaseFound = !!(phaseInfo && phaseInfo.found);
  const phaseNumber = (phaseInfo?.phase_number as string) || null;
  const plans = (phaseInfo?.plans || []) as string[];

+  const cfg = config as GSDConfig;
  const result: Record<string, unknown> = {
    researcher_model: researcherModel,
    planner_model: plannerModel,
    checker_model: checkerModel,
+    tdd_mode: config.workflow.tdd_mode ?? false,
    research_enabled: config.workflow.research,
    plan_checker_enabled: config.workflow.plan_check,
    nyquist_validation_enabled: config.workflow.nyquist_validation,
    commit_docs: config.commit_docs,
    text_mode: config.workflow.text_mode,
-    phase_found: phaseFound,
+    auto_advance: !!config.workflow.auto_advance,
+    auto_chain_active: !!cfg._auto_chain_active,
+    mode: cfg.mode ?? 'interactive',
+    phase_found: !!phaseInfo,
    phase_dir: (phaseInfo?.directory as string) ?? null,
    phase_number: phaseNumber,
    phase_name: (phaseInfo?.phase_name as string) ?? null,
@@ -322,6 +395,7 @@ export const initPlanPhase: QueryHandler = async (args, projectDir) => {
    state_path: toPosixPath(relative(projectDir, join(planningDir, 'STATE.md'))),
    roadmap_path: toPosixPath(relative(projectDir, join(planningDir, 'ROADMAP.md'))),
    requirements_path: toPosixPath(relative(projectDir, join(planningDir, 'REQUIREMENTS.md'))),
+    patterns_path: null,
  };

  // Add artifact paths if phase directory exists
@@ -339,6 +413,8 @@ export const initPlanPhase: QueryHandler = async (args, projectDir) => {
      if (uatFile) result.uat_path = toPosixPath(join(phaseInfo.directory as string, uatFile));
      const reviewsFile = files.find(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md');
      if (reviewsFile) result.reviews_path = toPosixPath(join(phaseInfo.directory as string, reviewsFile));
+      const patternsFile = files.find(f => f.endsWith('-PATTERNS.md') || f === 'PATTERNS.md');
+      if (patternsFile) result.patterns_path = toPosixPath(join(phaseInfo.directory as string, patternsFile));
    } catch { /* intentionally empty */ }
  }

@@ -500,7 +576,7 @@ export const initVerifyWork: QueryHandler = async (args, projectDir) => {
  }

  const config = await loadConfig(projectDir);
-  const { phaseInfo } = await getPhaseInfoWithFallback(phase, projectDir);
+  const { phaseInfo } = await getPhaseInfoForVerifyWork(phase, projectDir);

  const [plannerModel, checkerModel] = await Promise.all([
    getModelAlias('gsd-planner', projectDir),
@@ -511,7 +587,7 @@ export const initVerifyWork: QueryHandler = async (args, projectDir) => {
    planner_model: plannerModel,
    checker_model: checkerModel,
    commit_docs: config.commit_docs,
-    phase_found: !!(phaseInfo && phaseInfo.found),
+    phase_found: !!phaseInfo,
    phase_dir: (phaseInfo?.directory as string) ?? null,
    phase_number: (phaseInfo?.phase_number as string) ?? null,
    phase_name: (phaseInfo?.phase_name as string) ?? null,
@@ -949,7 +1025,6 @@ export const initRemoveWorkspace: QueryHandler = async (args, _projectDir) => {

  return { data: result };
 };
-
 // ─── initIngestDocs ───────────────────────────────────────────────────────

 /**
@@ -969,16 +1044,3 @@ export const initIngestDocs: QueryHandler = async (_args, projectDir) => {
  };
  return { data: withProjectRoot(projectDir, result, config as Record<string, unknown>) };
 };
-
-// ─── docsInit ────────────────────────────────────────────────────────────
-
-export const docsInit: QueryHandler = async (_args, projectDir) => {
-  return {
-    data: {
-      project_exists: existsSync(join(projectDir, '.planning', 'PROJECT.md')),
-      roadmap_exists: existsSync(join(projectDir, '.planning', 'ROADMAP.md')),
-      docs_dir: '.planning/docs',
-      project_root: projectDir,
-    },
-  };
-};