gsd-remix 1.0.0

package/sdk/src/query/check-auto-mode.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Unit tests for `check.auto-mode` (decision-routing audit §3.5).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { checkAutoMode } from './check-auto-mode.js';
+
+describe('checkAutoMode', () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = join(tmpdir(), `gsd-auto-mode-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(projectDir, '.planning'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('returns defaults when config.json is missing', async () => {
+    const { data } = await checkAutoMode([], projectDir);
+    expect(data).toEqual({
+      active: false,
+      source: 'none',
+      auto_chain_active: false,
+      auto_advance: false,
+    });
+  });
+
+  it('active true when only auto_advance is set', async () => {
+    await writeFile(
+      join(projectDir, '.planning', 'config.json'),
+      JSON.stringify({ workflow: { auto_advance: true } }),
+      'utf-8',
+    );
+    const { data } = await checkAutoMode([], projectDir);
+    expect(data).toMatchObject({
+      active: true,
+      source: 'auto_advance',
+      auto_advance: true,
+      auto_chain_active: false,
+    });
+  });
+
+  it('active true when only _auto_chain_active is set', async () => {
+    await writeFile(
+      join(projectDir, '.planning', 'config.json'),
+      JSON.stringify({ workflow: { _auto_chain_active: true } }),
+      'utf-8',
+    );
+    const { data } = await checkAutoMode([], projectDir);
+    expect(data).toMatchObject({
+      active: true,
+      source: 'auto_chain',
+      auto_advance: false,
+      auto_chain_active: true,
+    });
+  });
+
+  it('uses source both when both flags are true', async () => {
+    await writeFile(
+      join(projectDir, '.planning', 'config.json'),
+      JSON.stringify({ workflow: { auto_advance: true, _auto_chain_active: true } }),
+      'utf-8',
+    );
+    const { data } = await checkAutoMode([], projectDir);
+    expect(data).toMatchObject({
+      active: true,
+      source: 'both',
+      auto_advance: true,
+      auto_chain_active: true,
+    });
+  });
+});

package/sdk/src/query/check-auto-mode.ts

@@ -0,0 +1,50 @@
+/**
+ * Consolidated auto-advance flags (`check.auto-mode`).
+ *
+ * Replaces paired `config-get workflow.auto_advance` + `config-get workflow._auto_chain_active`
+ * for checkpoint and auto-advance gates. See `.planning/research/decision-routing-audit.md` §3.5.
+ *
+ * Semantics match `execute-phase.md`: automation applies when **either** the ephemeral chain flag
+ * or the persistent user preference is true (`active === true`).
+ */
+
+import { CONFIG_DEFAULTS, loadConfig } from '../config.js';
+import type { QueryHandler } from './utils.js';
+
+export type AutoModeSource = 'auto_chain' | 'auto_advance' | 'both' | 'none';
+
+function resolveSource(
+  autoChainActive: boolean,
+  autoAdvance: boolean,
+): { active: boolean; source: AutoModeSource } {
+  if (autoChainActive && autoAdvance) {
+    return { active: true, source: 'both' };
+  }
+  if (autoChainActive) {
+    return { active: true, source: 'auto_chain' };
+  }
+  if (autoAdvance) {
+    return { active: true, source: 'auto_advance' };
+  }
+  return { active: false, source: 'none' };
+}
+
+export const checkAutoMode: QueryHandler = async (_args, projectDir) => {
+  const config = await loadConfig(projectDir);
+  const wf: Record<string, unknown> = {
+    ...CONFIG_DEFAULTS.workflow,
+    ...(config.workflow as unknown as Record<string, unknown>),
+  };
+  const autoAdvance = Boolean(wf.auto_advance ?? false);
+  const autoChainActive = Boolean(wf._auto_chain_active ?? false);
+  const { active, source } = resolveSource(autoChainActive, autoAdvance);
+
+  return {
+    data: {
+      active,
+      source,
+      auto_chain_active: autoChainActive,
+      auto_advance: autoAdvance,
+    },
+  };
+};

package/sdk/src/query/check-completion.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Unit tests for `check.completion` (decision-routing audit §3.7).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { checkCompletion } from './check-completion.js';
+
+describe('checkCompletion', () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = join(tmpdir(), `gsd-check-completion-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(projectDir, '.planning', 'phases'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('throws when scope arg is missing', async () => {
+    await expect(checkCompletion([], projectDir)).rejects.toThrow();
+  });
+
+  it('throws when scope is invalid', async () => {
+    await expect(checkCompletion(['invalid', '1'], projectDir)).rejects.toThrow();
+  });
+
+  it('throws when phase number is missing for phase scope', async () => {
+    await expect(checkCompletion(['phase'], projectDir)).rejects.toThrow();
+  });
+
+  describe('phase scope', () => {
+    it('returns complete true when all plans have summaries', async () => {
+      const phaseDir = join(projectDir, '.planning', 'phases', '01-foundation');
+      await mkdir(phaseDir, { recursive: true });
+      await writeFile(join(phaseDir, '01-01-PLAN.md'), '---\nphase: 1\n---\n', 'utf-8');
+      await writeFile(join(phaseDir, '01-02-PLAN.md'), '---\nphase: 1\n---\n', 'utf-8');
+      await writeFile(join(phaseDir, '01-01-SUMMARY.md'), '# Summary', 'utf-8');
+      await writeFile(join(phaseDir, '01-02-SUMMARY.md'), '# Summary', 'utf-8');
+
+      const { data } = await checkCompletion(['phase', '1'], projectDir);
+      const d = data as Record<string, unknown>;
+      expect(d.complete).toBe(true);
+      expect(d.plans_total).toBe(2);
+      expect(d.plans_with_summaries).toBe(2);
+      expect((d.missing_summaries as string[]).length).toBe(0);
+    });
+
+    it('returns complete false when not all plans have summaries', async () => {
+      const phaseDir = join(projectDir, '.planning', 'phases', '02-core');
+      await mkdir(phaseDir, { recursive: true });
+      await writeFile(join(phaseDir, '02-01-PLAN.md'), '---\nphase: 2\n---\n', 'utf-8');
+      await writeFile(join(phaseDir, '02-02-PLAN.md'), '---\nphase: 2\n---\n', 'utf-8');
+      await writeFile(join(phaseDir, '02-01-SUMMARY.md'), '# Summary', 'utf-8');
+
+      const { data } = await checkCompletion(['phase', '2'], projectDir);
+      const d = data as Record<string, unknown>;
+      expect(d.complete).toBe(false);
+      expect(d.plans_total).toBe(2);
+      expect(d.plans_with_summaries).toBe(1);
+      expect((d.missing_summaries as string[]).length).toBe(1);
+    });
+
+    it('includes debt rollup fields', async () => {
+      const phaseDir = join(projectDir, '.planning', 'phases', '03-api');
+      await mkdir(phaseDir, { recursive: true });
+
+      const { data } = await checkCompletion(['phase', '3'], projectDir);
+      const d = data as Record<string, unknown>;
+      const debt = d.debt as Record<string, unknown>;
+      expect(debt).toBeDefined();
+      expect(typeof debt.uat_gaps).toBe('number');
+      expect(typeof debt.verification_failures).toBe('number');
+      expect(typeof debt.human_needed).toBe('boolean');
+    });
+
+    it('returns verification_status from VERIFICATION.md when present', async () => {
+      const phaseDir = join(projectDir, '.planning', 'phases', '04-ui');
+      await mkdir(phaseDir, { recursive: true });
+      await writeFile(join(phaseDir, '04-01-PLAN.md'), '---\nphase: 4\n---\n', 'utf-8');
+      await writeFile(join(phaseDir, '04-01-SUMMARY.md'), '# Summary', 'utf-8');
+      await writeFile(
+        join(phaseDir, 'VERIFICATION.md'),
+        '---\nstatus: passed\n---\n\n| ID | Description | Status |\n|---|---|---|\n| T-01 | Auth works | PASS |',
+        'utf-8',
+      );
+
+      const { data } = await checkCompletion(['phase', '4'], projectDir);
+      const d = data as Record<string, unknown>;
+      expect(d.verification_status).not.toBeNull();
+    });
+  });
+
+  describe('milestone scope', () => {
+    it('returns milestone completion fields', async () => {
+      await writeFile(
+        join(projectDir, '.planning', 'ROADMAP.md'),
+        '# Roadmap\n\n## Phase 01: Foundation\n\n## Phase 02: Core\n',
+        'utf-8',
+      );
+
+      const { data } = await checkCompletion(['milestone', 'v1.0'], projectDir);
+      const d = data as Record<string, unknown>;
+      expect(typeof d.complete).toBe('boolean');
+      expect(typeof d.phase_count).toBe('number');
+      expect(typeof d.phases_complete).toBe('number');
+      expect(Array.isArray(d.phases_incomplete)).toBe(true);
+    });
+  });
+});

package/sdk/src/query/check-completion.ts

@@ -0,0 +1,182 @@
+/**
+ * Phase or milestone completion rollup (`check.completion`).
+ *
+ * Replaces repeated PLAN/SUMMARY counting and verification checks in
+ * `transition.md`, `complete-milestone.md`, `execute-phase.md`.
+ * See `.planning/research/decision-routing-audit.md` §3.7.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { normalizePhaseName, planningPaths } from './helpers.js';
+import { findPhase } from './phase.js';
+import { roadmapAnalyze } from './roadmap.js';
+import type { QueryHandler } from './utils.js';
+
+const VALID_SCOPES = new Set(['phase', 'milestone']);
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+function countFailLines(content: string): number {
+  return (content.match(/\|\s*FAIL\s*\|/gi) || []).length;
+}
+
+async function readFileSafe(filePath: string): Promise<string | null> {
+  try {
+    return await readFile(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function deriveVerificationStatus(content: string | null): string | null {
+  if (!content) return null;
+  const failCount = countFailLines(content);
+  if (failCount > 0) return 'fail';
+  const passMatch = content.match(/\|\s*PASS\s*\|/gi);
+  if (passMatch && passMatch.length > 0) return 'pass';
+  // Frontmatter status field fallback
+  const statusMatch = content.match(/^status:\s*(\S+)/im);
+  if (statusMatch) return statusMatch[1].toLowerCase();
+  return 'missing';
+}
+
+function deriveUatStatus(content: string | null): string | null {
+  if (!content) return null;
+  const failCount = (content.match(/\|\s*FAIL\s*\|/gi) || []).length;
+  if (failCount > 0) return 'fail';
+  return 'pass';
+}
+
+// ─── Phase scope ───────────────────────────────────────────────────────────
+
+async function checkPhaseCompletion(phaseArg: string, projectDir: string): Promise<Record<string, unknown>> {
+  const phaseRes = await findPhase([phaseArg], projectDir);
+  const pdata = phaseRes.data as Record<string, unknown>;
+  const found = Boolean(pdata.found);
+
+  const plans = (pdata.plans as string[] | undefined) ?? [];
+  const summaries = (pdata.summaries as string[] | undefined) ?? [];
+  const plans_total = plans.length;
+
+  // Derive which plans are missing a summary
+  const summaryIds = new Set(
+    summaries
+      .map(s => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', ''))
+      .filter(Boolean),
+  );
+  const plans_with_summaries = plans.filter(p => {
+    const planId = p.replace('-PLAN.md', '').replace('PLAN.md', '');
+    return summaryIds.has(planId);
+  }).length;
+  const missing_summaries = plans
+    .filter(p => {
+      const planId = p.replace('-PLAN.md', '').replace('PLAN.md', '');
+      return !summaryIds.has(planId);
+    });
+
+  // Read VERIFICATION.md and UAT.md if phase was found
+  let verificationContent: string | null = null;
+  let uatContent: string | null = null;
+
+  if (found && pdata.directory) {
+    const phaseDirFull = join(projectDir, pdata.directory as string);
+    if (existsSync(phaseDirFull)) {
+      try {
+        const files = (await readdir(phaseDirFull)).sort((a, b) => a.localeCompare(b));
+        const verFile = files.includes('VERIFICATION.md')
+          ? 'VERIFICATION.md'
+          : files.find(f => f.endsWith('-VERIFICATION.md'));
+        const uatFile = files.includes('UAT.md') ? 'UAT.md' : files.find(f => f.endsWith('-UAT.md'));
+        if (verFile) verificationContent = await readFileSafe(join(phaseDirFull, verFile));
+        if (uatFile) uatContent = await readFileSafe(join(phaseDirFull, uatFile));
+      } catch {
+        // Phase dir unreadable — treat as no files
+      }
+    }
+  }
+
+  const verification_status = deriveVerificationStatus(verificationContent);
+  const uat_status = deriveUatStatus(uatContent);
+
+  const uat_gaps = uatContent ? countFailLines(uatContent) : 0;
+  const verification_failures = verificationContent ? countFailLines(verificationContent) : 0;
+
+  const complete =
+    plans_total > 0 &&
+    missing_summaries.length === 0 &&
+    verification_status !== 'fail';
+
+  return {
+    complete,
+    plans_total,
+    plans_with_summaries,
+    missing_summaries,
+    verification_status,
+    uat_status,
+    debt: {
+      uat_gaps,
+      verification_failures,
+      human_needed: false,
+    },
+  };
+}
+
+// ─── Milestone scope ───────────────────────────────────────────────────────
+
+async function checkMilestoneCompletion(projectDir: string): Promise<Record<string, unknown>> {
+  const analysis = await roadmapAnalyze([], projectDir);
+  const adata = analysis.data as { phases?: Array<Record<string, unknown>> };
+  const phases = adata.phases ?? [];
+
+  const phase_count = phases.length;
+  const completePhases = phases.filter(
+    p => p.roadmap_complete === true || p.disk_status === 'complete',
+  );
+  const phases_complete = completePhases.length;
+  const phases_incomplete = phases
+    .filter(p => p.roadmap_complete !== true && p.disk_status !== 'complete')
+    .map(p => String(normalizePhaseName(String(p.number))));
+
+  const blockers: string[] = [];
+
+  const complete = phase_count > 0 && phases_complete === phase_count;
+
+  return {
+    complete,
+    phase_count,
+    phases_complete,
+    phases_incomplete,
+    blockers,
+  };
+}
+
+// ─── Handler ───────────────────────────────────────────────────────────────
+
+export const checkCompletion: QueryHandler = async (args, projectDir) => {
+  const scope = args[0];
+  if (!scope) {
+    throw new GSDError('scope required for check completion (phase|milestone)', ErrorClassification.Validation);
+  }
+  if (!VALID_SCOPES.has(scope)) {
+    throw new GSDError(
+      `invalid scope "${scope}" — must be "phase" or "milestone"`,
+      ErrorClassification.Validation,
+    );
+  }
+
+  if (scope === 'phase') {
+    const phaseNum = args[1];
+    if (!phaseNum) {
+      throw new GSDError('phase number required for check completion phase', ErrorClassification.Validation);
+    }
+    const result = await checkPhaseCompletion(phaseNum, projectDir);
+    return { data: result };
+  }
+
+  // milestone scope
+  const result = await checkMilestoneCompletion(projectDir);
+  return { data: result };
+};

package/sdk/src/query/check-gates.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Unit tests for `check.gates` (decision-routing audit §3.2).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { checkGates } from './check-gates.js';
+
+describe('checkGates', () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = join(tmpdir(), `gsd-check-gates-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(projectDir, '.planning', 'phases'), { recursive: true });
+    // Write a clean STATE.md
+    await writeFile(
+      join(projectDir, '.planning', 'STATE.md'),
+      '---\nstatus: active\n---\n\n# Project State\n\nStatus: active\n',
+      'utf-8',
+    );
+  });
+
+  afterEach(async () => {
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('throws when workflow name arg is missing', async () => {
+    await expect(checkGates([], projectDir)).rejects.toThrow();
+  });
+
+  it('returns passed true when no blockers exist', async () => {
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.passed).toBe(true);
+    expect(d.blockers).toEqual([]);
+  });
+
+  it('returns blocker when .continue-here.md is present in root', async () => {
+    await writeFile(join(projectDir, '.continue-here.md'), '# Continue here', 'utf-8');
+
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.passed).toBe(false);
+    const blockers = d.blockers as Array<Record<string, unknown>>;
+    expect(blockers.length).toBeGreaterThan(0);
+    expect(blockers[0].gate).toBe('continue-here');
+    expect(blockers[0].severity).toBe('blocking');
+  });
+
+  it('returns blocker when STATE.md has status: failed', async () => {
+    await writeFile(
+      join(projectDir, '.planning', 'STATE.md'),
+      '---\nstatus: failed\n---\n\n# Project State\n',
+      'utf-8',
+    );
+
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.passed).toBe(false);
+    const blockers = d.blockers as Array<Record<string, unknown>>;
+    const stateBlocker = blockers.find(b => b.gate === 'state-error');
+    expect(stateBlocker).toBeDefined();
+  });
+
+  it('returns blocker when STATE.md has status: error', async () => {
+    await writeFile(
+      join(projectDir, '.planning', 'STATE.md'),
+      '---\nstatus: error\n---\n\n# Project State\n',
+      'utf-8',
+    );
+
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.passed).toBe(false);
+    const blockers = d.blockers as Array<Record<string, unknown>>;
+    const stateBlocker = blockers.find(b => b.gate === 'state-error');
+    expect(stateBlocker).toBeDefined();
+  });
+
+  it('includes warnings shape in result', async () => {
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(Array.isArray(d.warnings)).toBe(true);
+  });
+
+  it('returns verification-debt warning when phase VERIFICATION.md has FAIL rows', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '01-foundation');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(
+      join(phaseDir, 'VERIFICATION.md'),
+      '| T-01 | Auth works | FAIL |\n| T-02 | User model | PASS |\n',
+      'utf-8',
+    );
+
+    const { data } = await checkGates(['execute-phase', '--phase', '1'], projectDir);
+    const d = data as Record<string, unknown>;
+    const warnings = d.warnings as Array<Record<string, unknown>>;
+    const debtWarning = warnings.find(w => w.gate === 'verification-debt');
+    expect(debtWarning).toBeDefined();
+  });
+});

package/sdk/src/query/check-gates.ts

@@ -0,0 +1,112 @@
+/**
+ * Safety gate consolidation (`check.gates`).
+ *
+ * Checks blocking conditions before proceeding with a workflow — replaces
+ * per-workflow gate logic in `next.md`, `execute-phase.md`, `discuss-phase.md`.
+ * See `.planning/research/decision-routing-audit.md` §3.2.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { normalizePhaseName, planningPaths } from './helpers.js';
+import { findPhase } from './phase.js';
+import type { QueryHandler } from './utils.js';
+
+interface Blocker {
+  gate: string;
+  file: string;
+  severity: 'blocking';
+  anti_patterns: string[];
+}
+
+interface Warning {
+  gate: string;
+  phase: string;
+  items: string[];
+  message: string;
+}
+
+async function readFileSafe(filePath: string): Promise<string | null> {
+  try {
+    return await readFile(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+export const checkGates: QueryHandler = async (args, projectDir) => {
+  const workflow = args[0];
+  if (!workflow) {
+    throw new GSDError('workflow name required for check gates', ErrorClassification.Validation);
+  }
+
+  // Parse optional --phase flag
+  let phaseNum: string | null = null;
+  const phaseIdx = args.indexOf('--phase');
+  if (phaseIdx !== -1 && args[phaseIdx + 1]) {
+    phaseNum = args[phaseIdx + 1];
+  }
+
+  const blockers: Blocker[] = [];
+  const warnings: Warning[] = [];
+  const paths = planningPaths(projectDir);
+
+  // Gate 1: .continue-here.md in project root
+  const continueHerePath = join(projectDir, '.continue-here.md');
+  if (existsSync(continueHerePath)) {
+    blockers.push({
+      gate: 'continue-here',
+      file: '.continue-here.md',
+      severity: 'blocking',
+      anti_patterns: ['continue-here.md present — another session may be in progress'],
+    });
+  }
+
+  // Gate 2: STATE.md error/failed status
+  const stateContent = await readFileSafe(paths.state);
+  if (stateContent) {
+    const hasErrorStatus =
+      /^status:\s*(error|failed)/im.test(stateContent) ||
+      /##\s*Error/i.test(stateContent);
+    if (hasErrorStatus) {
+      blockers.push({
+        gate: 'state-error',
+        file: '.planning/STATE.md',
+        severity: 'blocking',
+        anti_patterns: ['STATE.md status is error/failed'],
+      });
+    }
+  }
+
+  // Gate 3: Verification debt — check VERIFICATION.md in phase dir if phase provided
+  if (phaseNum) {
+    const phaseRes = await findPhase([phaseNum], projectDir);
+    const pdata = phaseRes.data as Record<string, unknown>;
+    if (pdata.found && pdata.directory) {
+      const phaseDirFull = join(projectDir, pdata.directory as string);
+      const verPath = join(phaseDirFull, 'VERIFICATION.md');
+      const verContent = await readFileSafe(verPath);
+      if (verContent) {
+        const failLines = verContent.match(/\|\s*FAIL\s*\|[^\n]*/gi) || [];
+        if (failLines.length > 0) {
+          warnings.push({
+            gate: 'verification-debt',
+            phase: normalizePhaseName(phaseNum),
+            items: failLines.map(l => `FAIL: ${l.trim()}`),
+            message: `${failLines.length} FAIL row(s) in VERIFICATION.md`,
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    data: {
+      passed: blockers.length === 0,
+      blockers,
+      warnings,
+    },
+  };
+};