fix(#1522): enforce canonical verification before phase transition (#1548)

* fix: require fresh phase verification before transition * no-mistakes(review): Fix canonical verification closeout gates * no-mistakes(review): Fix verify-work frontmatter promotion command * no-mistakes(review): Fix stale verification gates * no-mistakes(review): Fix canonical verification routing gates * no-mistakes(review): Fix verification dependency and runtime routing gates * no-mistakes(review): Block stale verification bypasses * fix: handle large init manager outputs in verification workflows * chore: update changeset pr number * fix(verify-work): use fresh verification.status for stale gate The stale check after UAT used phase_completion.verification_status from session-start INIT while human_needed promotion already queried fresh verification.status. Align the stale gate with the canonical query so mid-session verification refresh is not ignored. * fix(init): skip roadmap-checked phases when selecting next_phase Roadmap-only phases without a disk directory were still promoted to next_phase when their checkbox was already checked. Exclude checkboxComplete phases so progress routing does not point at work the roadmap already marks done. * fix: gaps_found not overridden by stale, transition uses canonical verification - verification.cts: check gaps_found before stale so gap-closure routing is not masked by a newer summary mtime - phase.cts: remove redundant findStaleVerificationSummary — readVerificationStatus already handles stale detection - transition.md: replace raw grep on file content with verification.status query to avoid false-positive blocks from body text matching * ci: retrigger tests after rebase * fix(transition): replace gsd_run advisory check with awk frontmatter extraction The runtime launcher is not defined until the update_roadmap_and_state step bash block (~line 165). The early verify_completion block used gsd_run to query verification.status, which violated the runtime-launcher-parity test: 'preamble appears AFTER the first gsd_run reference'. Replace the gsd_run call with an awk-based frontmatter extractor that reads only the status: field between the two --- fences. This avoids both the preamble-ordering constraint and the original false-positive grep bug where body text like 'previous_status: gaps_found' would match a full-text regex. The phase.complete gate at update_roadmap_and_state is the canonical enforcement point; this early check is advisory only. Also update workflow-size-baseline.json for the updated transition.md size. Fixes: runtime-launcher-parity test (B) Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com> * fix: re-check verification under planning lock in phase complete Move readVerificationStatus into withPlanningLock so stale verification cannot slip through when a SUMMARY.md is written between the gate and the roadmap/state mutation. Return the blocked status from the lock callback and emit the error after release to avoid leaving .lock behind. * fix(transition): gate on canonical verification.status including stale Replace awk frontmatter read with verification.status query so transition blocks when summaries are newer than VERIFICATION.md, matching phase.complete and other workflows (autonomous, progress, verify-work). * Fix workflow verification gates for yolo transition and stale routing Require VERIFY_STATUS passed before yolo/interactive transition advance. Route stale verification recovery to verify-work, matching canonical projection. * fix(transition): use verification.status query for stale-aware advisory check The awk-based check read raw frontmatter status: passed, which misses the stale case where summaries are newer than the VERIFICATION.md file even though the frontmatter still says passed. The stale status is computed from file modification times, not stored in frontmatter. Move the preamble to the verify_completion bash block (the first block with a gsd_run call) so gsd_run query verification.status can be used for the advisory check. This gives the full readVerificationStatus logic including mtime-based staleness detection, matching the enforcement gate at phase.complete. Capture full JSON (VERIFY_JSON) so next_action can be included in the advisory output alongside the status. Also update workflow-size-baseline.json for the updated transition.md size. Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com> * ci: trigger test matrix for 525b946 Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com> * fix(transition): restore awk frontmatter extraction for pre-shim verification check The gsd_run launcher shim is not defined until line ~163 of transition.md, so the verification debt check at line ~80 cannot use gsd_run. Restore the awk-based frontmatter extraction that correctly reads status without needing the runtime, and restore the shim at its proper location before phase.complete. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(#1522): clarify transition verification gate wording * fix(#1522): update transition workflow size baseline * fix(#1522): update workflow-size-baseline after rebase onto next Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com> * fix(#1522): guard findStaleVerificationSummary FS calls + thread opts.fs seam (review) Address review blocker B1 on #1548: findStaleVerificationSummary ran fs.readdirSync and two fs.statSync calls unguarded between readVerificationStatus's try/catch sections, so a TOCTOU race (a SUMMARY listed by scanPhasePlans then removed before statSync) or any FS error threw uncaught into callers NOT under the planning lock (init.manager / init.progress / uat-predicate). Wrap the body in try/catch degrading to 'not stale', and thread the injectable opts.fs seam (add statSync to FsLike, pass fsImpl from the caller) for parity with readVerificationStatus's no-throw contract and testability. Also adds the Verification Module glossary entry to CONTEXT.md (review B3). --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Tom Boucher <trekkie@nomorestars.com>
2026-06-24 12:19:10 -05:00
parent eef8f9b8c3
commit 77c7b4fc9d
36 changed files with 1354 additions and 209 deletions
--- a/src/init.cts
+++ b/src/init.cts
@@ -40,6 +40,10 @@ import { validatePath, loadTrustedGlobalRoots } from './security.cjs';
 import { getGlobalSkillDir, getGlobalSkillDisplayPath, getGlobalSkillsBase } from './runtime-homes.cjs';
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
 import frontmatterMod = require('./frontmatter.cjs');
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
+import verificationMod = require('./verification.cjs');
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- uat-predicate.cjs is an export= CommonJS module
+import uatPredicateMod = require('./uat-predicate.cjs');
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- agent-install-check.cjs is an export= CommonJS module
 import agentInstallCheck = require('./agent-install-check.cjs');
 const { checkAgentsInstalled } = agentInstallCheck;
@@ -72,6 +76,8 @@ const {

 const { determinePhaseStatus } = commandsMod;
 const { extractFrontmatter } = frontmatterMod;
+const { readVerificationStatus } = verificationMod;
+const { evaluateUatPassed } = uatPredicateMod;

 // Unused but imported for structural parity
 void stripShippedMilestones;
@@ -87,6 +93,75 @@ function listPhasePlanFiles(phaseDir: string): string[] {
  return (scanPhasePlans(phaseDir) as unknown as Record<string, string[]>)['planFiles'];
 }

+interface PhaseCompletionProjection {
+  implementation_complete: boolean;
+  verification_status: string;
+  verification_passed: boolean;
+  phase_complete: boolean;
+  completion_status: string;
+  verification_next_action: string;
+  verification_next_command: string;
+}
+
+function verificationNextCommand(
+  status: string,
+  phaseNumber: string,
+  slashRuntime: string,
+): string {
+  if (status === 'gaps_found') {
+    return `${formatGsdSlash('plan-phase', slashRuntime) as string} ${phaseNumber} --gaps`;
+  }
+  if (status === 'human_needed' || status === 'stale') {
+    return `${formatGsdSlash('verify-work', slashRuntime) as string} ${phaseNumber}`;
+  }
+  if (status === 'missing' || status === 'unknown') {
+    return `${formatGsdSlash('execute-phase', slashRuntime) as string} ${phaseNumber}`;
+  }
+  return '';
+}
+
+function projectCompletionStatus(
+  implementationComplete: boolean,
+  verificationPassed: boolean,
+): string {
+  if (implementationComplete && verificationPassed) return 'complete';
+  if (implementationComplete) return 'executed';
+  return 'incomplete';
+}
+
+function buildPhaseCompletionProjection(
+  cwd: string,
+  phaseNumber: string,
+  phaseDir: string | null,
+  planCount: number,
+  summaryCount: number,
+  slashRuntime: string,
+): PhaseCompletionProjection {
+  const implementationComplete = planCount > 0 && summaryCount >= planCount;
+  const phaseFullDir = phaseDir ? path.join(cwd, phaseDir) : '';
+  const verificationStatus = implementationComplete
+    ? readVerificationStatus(phaseFullDir)
+    : { status: 'not_required', next_action: '', next_command: '' };
+  const projectedVerificationStatus = verificationStatus.status;
+  const projectedVerificationAction = verificationStatus.next_action;
+  const verificationPassed = projectedVerificationStatus === 'passed';
+  const phaseComplete = implementationComplete && verificationPassed;
+
+  return {
+    implementation_complete: implementationComplete,
+    verification_status: projectedVerificationStatus,
+    verification_passed: verificationPassed,
+    phase_complete: phaseComplete,
+    completion_status: projectCompletionStatus(implementationComplete, verificationPassed),
+    verification_next_action: projectedVerificationAction,
+    verification_next_command: verificationNextCommand(
+      projectedVerificationStatus,
+      phaseNumber,
+      slashRuntime,
+    ),
+  };
+}
+
 function getLatestCompletedMilestone(cwd: string): { version: string; name: string } | null {
  const milestonesPath = path.join(planningRoot(cwd), 'MILESTONES.md');
  const content = platformReadSync(milestonesPath);
@@ -802,6 +877,7 @@ function cmdInitVerifyWork(cwd: string, phase: string, raw: boolean): void {
  }

  const config = loadConfig(cwd);
+  const _slashRuntime = resolveRuntime(cwd);
  let phaseInfo = findPhaseInternal(cwd, phase) as unknown as Record<string, unknown> | null;

  if (phaseInfo?.['archived']) {
@@ -833,6 +909,23 @@ function cmdInitVerifyWork(cwd: string, phase: string, raw: boolean): void {
    }
  }

+  const phaseDir = (phaseInfo?.['directory'] as string | null | undefined) || null;
+  const planCount = (phaseInfo?.['plans'] as unknown[] | undefined)?.length || 0;
+  const summaryCount = (phaseInfo?.['summaries'] as unknown[] | undefined)?.length || 0;
+  const completion = buildPhaseCompletionProjection(
+    cwd,
+    (phaseInfo?.['phase_number'] as string | undefined) || phase,
+    phaseDir,
+    planCount,
+    summaryCount,
+    _slashRuntime,
+  );
+  const uatReport = phaseDir
+    ? evaluateUatPassed(path.join(cwd, phaseDir), {
+        policy: { requireVerification: true },
+      })
+    : null;
+
  const result: Record<string, unknown> = {
    planner_model: resolveModelInternal(cwd, 'gsd-planner'),
    checker_model: resolveModelInternal(cwd, 'gsd-plan-checker'),
@@ -840,11 +933,17 @@ function cmdInitVerifyWork(cwd: string, phase: string, raw: boolean): void {
    commit_docs: config.commit_docs,

    phase_found: !!phaseInfo,
-    phase_dir: phaseInfo?.['directory'] || null,
+    phase_dir: phaseDir,
    phase_number: phaseInfo?.['phase_number'] || null,
    phase_name: phaseInfo?.['phase_name'] || null,

    has_verification: phaseInfo?.['has_verification'] || false,
+    phase_completion: {
+      ...completion,
+      uat_passed: uatReport?.passed ?? false,
+      uat_blockers: uatReport?.blockers ?? [],
+      ready_to_transition: completion.phase_complete && (uatReport?.passed ?? false),
+    },
  };

  output(withProjectRoot(cwd, result), raw);
@@ -1279,6 +1378,14 @@ function cmdInitManager(cwd: string, raw: boolean): void {
    let hasResearch = false;
    let lastActivity: string | null = null;
    let isActive = false;
+    let completion = buildPhaseCompletionProjection(
+      cwd,
+      phaseNum,
+      null,
+      planCount,
+      summaryCount,
+      _slashRuntime,
+    );

    try {
      const dirs = _phaseDirEntries.filter(isDirInMilestone);
@@ -1286,6 +1393,7 @@ function cmdInitManager(cwd: string, raw: boolean): void {

      if (dirMatch) {
        const fullDir = path.join(phasesDir, dirMatch);
+        const phaseDirRel = toPosixPath(path.relative(cwd, fullDir));
        const phaseFiles = fs.readdirSync(fullDir);
        planCount = listPhasePlanFiles(fullDir).length;
        summaryCount = listPhaseSummaryFiles(fullDir).length;
@@ -1293,8 +1401,17 @@ function cmdInitManager(cwd: string, raw: boolean): void {
        hasResearch = phaseFiles.some(
          (f) => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md',
        );
+        completion = buildPhaseCompletionProjection(
+          cwd,
+          phaseNum,
+          phaseDirRel,
+          planCount,
+          summaryCount,
+          _slashRuntime,
+        );

-        if (summaryCount >= planCount && planCount > 0) diskStatus = 'complete';
+        if (completion.phase_complete) diskStatus = 'complete';
+        else if (completion.implementation_complete) diskStatus = 'executed';
        else if (summaryCount > 0) diskStatus = 'partial';
        else if (planCount > 0) diskStatus = 'planned';
        else if (hasResearch) diskStatus = 'researched';
@@ -1321,7 +1438,7 @@ function cmdInitManager(cwd: string, raw: boolean): void {
    }

    const roadmapComplete = _checkboxStates.get(phaseNum) || false;
-    if (roadmapComplete && diskStatus !== 'complete') {
+    if (roadmapComplete && completion.phase_complete && diskStatus !== 'complete') {
      diskStatus = 'complete';
    }

@@ -1336,6 +1453,7 @@ function cmdInitManager(cwd: string, raw: boolean): void {
      plan_count: planCount,
      summary_count: summaryCount,
      roadmap_complete: roadmapComplete,
+      ...completion,
      last_activity: lastActivity,
      is_active: isActive,
    });
@@ -1351,24 +1469,44 @@ function cmdInitManager(cwd: string, raw: boolean): void {
    }
  }

+  function normalizePhaseNumber(value: string): string {
+    return value
+      .split('.')
+      .map((part) => {
+        const match = /^(\d+)([A-Z]?)$/i.exec(part);
+        if (!match) return part;
+        return `${Number(match[1])}${match[2].toUpperCase()}`;
+      })
+      .join('.');
+  }
+
  const completedNums = new Set(
-    phases.filter((p) => p['disk_status'] === 'complete').map((p) => p['number'] as string),
+    phases
+      .filter((p) => p['phase_complete'] === true)
+      .map((p) => normalizePhaseNumber(p['number'] as string)),
  );
+  const phaseMap = new Map(phases.map((p) => [normalizePhaseNumber(p['number'] as string), p]));

  const _allCompletedPattern = /-\s*\[x\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s]/gi;
  let _allMatch: RegExpExecArray | null;
  while ((_allMatch = _allCompletedPattern.exec(rawContent)) !== null) {
-    completedNums.add(_allMatch[1]);
+    const phaseNum = normalizePhaseNumber(_allMatch[1]);
+    const phase = phaseMap.get(phaseNum);
+    if (!phase || phase['phase_complete'] === true) {
+      completedNums.add(phaseNum);
+    }
  }

-  const phaseMap = new Map(phases.map((p) => [p['number'] as string, p]));
-
  function reaches(from: string, to: string, visited = new Set<string>()): boolean {
-    if (visited.has(from)) return false;
-    visited.add(from);
-    const p = phaseMap.get(from);
+    const normalizedFrom = normalizePhaseNumber(from);
+    const normalizedTo = normalizePhaseNumber(to);
+    if (visited.has(normalizedFrom)) return false;
+    visited.add(normalizedFrom);
+    const p = phaseMap.get(normalizedFrom);
    if (!p || !p['dep_phases'] || (p['dep_phases'] as string[]).length === 0) return false;
-    if ((p['dep_phases'] as string[]).includes(to)) return true;
+    if ((p['dep_phases'] as string[]).some((dep) => normalizePhaseNumber(dep) === normalizedTo)) {
+      return true;
+    }
    return (p['dep_phases'] as string[]).some((dep) => reaches(dep, to, visited));
  }

@@ -1383,8 +1521,8 @@ function cmdInitManager(cwd: string, raw: boolean): void {
    ) {
      phase['deps_satisfied'] = true;
    } else {
-      const depNums = (phase['depends_on'] as string).match(/\d+(?:\.\d+)*/g) || [];
-      phase['deps_satisfied'] = depNums.every((n) => completedNums.has(n));
+      const depNums = (phase['depends_on'] as string).match(/\d+[A-Z]?(?:\.\d+)*/gi) || [];
+      phase['deps_satisfied'] = depNums.every((n) => completedNums.has(normalizePhaseNumber(n)));
      phase['dep_phases'] = depNums;
    }
  }
@@ -1418,7 +1556,15 @@ function cmdInitManager(cwd: string, raw: boolean): void {
    if (phase['disk_status'] === 'complete') continue;
    if (/^999(?:\.|$)/.test(phase['number'] as string)) continue;

-    if (phase['disk_status'] === 'planned' && phase['deps_satisfied']) {
+    if (phase['disk_status'] === 'executed') {
+      recommendedActions.push({
+        phase: phase['number'],
+        phase_name: phase['name'],
+        action: 'verify',
+        reason: `Implementation complete; verification ${phase['verification_status'] as string}`,
+        command: phase['verification_next_command'],
+      });
+    } else if (phase['disk_status'] === 'planned' && phase['deps_satisfied']) {
      recommendedActions.push({
        phase: phase['number'],
        phase_name: phase['name'],
@@ -1477,7 +1623,7 @@ function cmdInitManager(cwd: string, raw: boolean): void {
  });

  const nonBacklogPhases = phases.filter((p) => !/^999(?:\.|$)/.test(p['number'] as string));
-  const completedCount = nonBacklogPhases.filter((p) => p['disk_status'] === 'complete').length;
+  const completedCount = nonBacklogPhases.filter((p) => p['phase_complete'] === true).length;

  const sanitizeFlags = (rawVal: unknown): string => {
    const val = typeof rawVal === 'string' ? rawVal : '';
@@ -1511,7 +1657,7 @@ function cmdInitManager(cwd: string, raw: boolean): void {
    phase_count: phases.length,
    completed_count: completedCount,
    in_progress_count: phases.filter((p) =>
-      ['partial', 'planned', 'discussed', 'researched'].includes(p['disk_status'] as string),
+      ['executed', 'partial', 'planned', 'discussed', 'researched'].includes(p['disk_status'] as string),
    ).length,
    recommended_actions: filteredActions,
    waiting_signal: waitingSignal,
@@ -1534,6 +1680,7 @@ function cmdInitProgress(cwd: string, raw: boolean): void {
  }
  const config = loadConfig(cwd);
  const milestone = getMilestoneInfo(cwd) as unknown as Record<string, unknown>;
+  const _slashRuntime = resolveRuntime(cwd);

  const phasesDir = path.join(planningDir(cwd), 'phases');
  const phases: Record<string, unknown>[] = [];
@@ -1593,31 +1740,43 @@ function cmdInitProgress(cwd: string, raw: boolean): void {
      const hasResearch = phaseFiles.some(
        (f) => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md',
      );
+      const phaseDirRel = toPosixPath(
+        path.relative(cwd, path.join(planningDir(cwd), 'phases', dir)),
+      );
+      const completion = buildPhaseCompletionProjection(
+        cwd,
+        phaseNumber,
+        phaseDirRel,
+        plans.length,
+        summaries.length,
+        _slashRuntime,
+      );

      const status =
-        summaries.length >= plans.length && plans.length > 0
+        completion.phase_complete
          ? 'complete'
-          : plans.length > 0
-            ? 'in_progress'
-            : hasResearch
-              ? 'researched'
-              : 'pending';
+          : completion.implementation_complete
+            ? 'executed'
+            : plans.length > 0
+              ? 'in_progress'
+              : hasResearch
+                ? 'researched'
+                : 'pending';

      const phaseInfo: Record<string, unknown> = {
        number: phaseNumber,
        name: phaseName,
-        directory: toPosixPath(
-          path.relative(cwd, path.join(planningDir(cwd), 'phases', dir)),
-        ),
+        directory: phaseDirRel,
        status,
        plan_count: plans.length,
        summary_count: summaries.length,
        has_research: hasResearch,
+        ...completion,
      };

      phases.push(phaseInfo);

-      if (!currentPhase && (status === 'in_progress' || status === 'researched')) {
+      if (!currentPhase && (status === 'executed' || status === 'in_progress' || status === 'researched')) {
        currentPhase = phaseInfo;
      }
      if (!nextPhase && status === 'pending') {
@@ -1634,7 +1793,15 @@ function cmdInitProgress(cwd: string, raw: boolean): void {
      const checkboxComplete =
        roadmapCheckboxStates.get(num) === true ||
        roadmapCheckboxStates.get(stripped) === true;
-      const status = checkboxComplete ? 'complete' : 'not_started';
+      const completion = buildPhaseCompletionProjection(
+        cwd,
+        num,
+        null,
+        0,
+        0,
+        _slashRuntime,
+      );
+      const status = 'not_started';
      const phaseInfo: Record<string, unknown> = {
        number: num,
        name: name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''),
@@ -1643,9 +1810,11 @@ function cmdInitProgress(cwd: string, raw: boolean): void {
        plan_count: 0,
        summary_count: 0,
        has_research: false,
+        roadmap_complete: checkboxComplete,
+        ...completion,
      };
      phases.push(phaseInfo);
-      if (!nextPhase && !currentPhase && status !== 'complete') {
+      if (!nextPhase && !currentPhase && !checkboxComplete) {
        nextPhase = phaseInfo;
      }
    }
@@ -1674,7 +1843,9 @@ function cmdInitProgress(cwd: string, raw: boolean): void {
    phases,
    phase_count: phases.length,
    completed_count: phases.filter((p) => p['status'] === 'complete').length,
-    in_progress_count: phases.filter((p) => p['status'] === 'in_progress').length,
+    in_progress_count: phases.filter((p) =>
+      ['executed', 'in_progress'].includes(p['status'] as string),
+    ).length,

    current_phase: currentPhase,
    next_phase: nextPhase,