@aperant/framework 0.6.7 → 0.7.3

package/src/cli/commands/vitest-doctor.mjs

@@ -0,0 +1,173 @@
+/**
+ * commands/vitest-doctor.mjs — FRAMEWORK-BUG-026 diagnostic subcommand.
+ *
+ * Globs every `vitest.config.{ts,js,mjs}` under the project root (skipping
+ * node_modules), parses each for the two shim signals the framework
+ * centralizes in `packages/framework/test-utils/vitest.shared.mjs`:
+ *
+ *   - `NODE_ENV='test'`            (process.env.NODE_ENV set OR defineVitestShim active)
+ *   - `oxc.jsx.runtime='automatic'` (jsxAutomaticShim active)
+ *
+ * Reports a matrix and warns when a workspace has JSX-rendering tests
+ * (any `*.test.tsx` under `src/`) but no jsxAutomaticShim coverage —
+ * that's the BUG-026 first-test paper cut.
+ *
+ * Exit codes:
+ *   0 — no warnings (or only informational matrix output)
+ *   1 — at least one workspace has JSX-rendering tests without
+ *       jsxAutomaticShim coverage
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+const VITEST_CONFIG_NAMES = new Set(['vitest.config.ts', 'vitest.config.js', 'vitest.config.mjs'])
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'out', '.next', '.aperant'])
+
+export function cmdVitestDoctor(projectDir, extraArgs) {
+	if (!projectDir) return err('Usage: apt-tools vitest doctor <project-dir> [--format json|md]')
+	const root = resolve(projectDir)
+	if (!existsSync(root)) return err(`project-dir not found: ${root}`)
+	const flags = parseFlags(extraArgs ?? [])
+	const format = (flags.get('format') || 'json').toLowerCase()
+
+	const configs = findVitestConfigs(root)
+	const matrix = configs.map((configPath) => inspectConfig(root, configPath))
+	const warnings = matrix
+		.filter((row) => row.has_jsx_rendering_tests && !row.jsx_automatic_shim)
+		.map((row) => ({
+			workspace: row.workspace,
+			reason:
+				'has JSX-rendering tests under src/ but vitest.config does not enable jsxAutomaticShim',
+		}))
+
+	const envelope = {
+		status: 'ok',
+		command: 'vitest-doctor',
+		project_dir: root,
+		configs_found: matrix.length,
+		matrix,
+		warnings,
+	}
+
+	if (format === 'md') {
+		envelope.markdown = renderMarkdown(matrix, warnings)
+	}
+
+	if (warnings.length > 0) {
+		// Exit code 1 — surface drift so the user knows to wire the shim.
+		return exitWith(envelope, 1)
+	}
+	return ok(envelope)
+}
+
+function findVitestConfigs(root) {
+	const out = []
+	walk(root, root, out)
+	return out
+}
+
+function walk(rootAbs, dirAbs, out) {
+	let names
+	try {
+		names = readdirSync(dirAbs)
+	} catch {
+		return
+	}
+	for (const name of names) {
+		if (SKIP_DIRS.has(name)) continue
+		const abs = join(dirAbs, name)
+		let st
+		try {
+			st = statSync(abs)
+		} catch {
+			continue
+		}
+		if (st.isDirectory()) {
+			walk(rootAbs, abs, out)
+		} else if (st.isFile() && VITEST_CONFIG_NAMES.has(name)) {
+			out.push(abs)
+		}
+	}
+}
+
+function inspectConfig(rootAbs, configPath) {
+	const workspace = relative(rootAbs, configPath)
+	const dir = join(configPath, '..')
+	let body = ''
+	try {
+		body = readFileSync(configPath, 'utf-8')
+	} catch {
+		return {
+			workspace,
+			node_env_shim: false,
+			jsx_automatic_shim: false,
+			has_jsx_rendering_tests: false,
+			error: 'read-failed',
+		}
+	}
+	// NODE_ENV shim: either the literal `process.env.NODE_ENV = 'test'`
+	// pattern OR `defineVitestShim(` (any non-explicit-false arg).
+	const node_env_shim =
+		/process\.env\.NODE_ENV\s*=\s*['"`]test['"`]/.test(body) ||
+		/defineVitestShim\([^)]*\)/.test(body)
+	// jsxAutomaticShim: literal `oxc.jsx.runtime` = 'automatic' OR
+	// `jsxAutomaticShim: true` inside a defineVitestShim() arg.
+	const jsx_automatic_shim =
+		/oxc\s*:\s*\{[^}]*jsx[^}]*runtime\s*:\s*['"`]automatic['"`]/s.test(body) ||
+		/jsxAutomaticShim\s*:\s*true/.test(body)
+	const has_jsx_rendering_tests = workspaceHasJsxRenderingTests(dir)
+	return { workspace, node_env_shim, jsx_automatic_shim, has_jsx_rendering_tests }
+}
+
+function workspaceHasJsxRenderingTests(workspaceDir) {
+	const srcDir = join(workspaceDir, 'src')
+	if (!existsSync(srcDir)) return false
+	return scanForTsxTest(srcDir)
+}
+
+function scanForTsxTest(dirAbs) {
+	let names
+	try {
+		names = readdirSync(dirAbs)
+	} catch {
+		return false
+	}
+	for (const name of names) {
+		if (SKIP_DIRS.has(name)) continue
+		const abs = join(dirAbs, name)
+		let st
+		try {
+			st = statSync(abs)
+		} catch {
+			continue
+		}
+		if (st.isDirectory()) {
+			if (scanForTsxTest(abs)) return true
+		} else if (st.isFile() && /\.test\.tsx$/.test(name)) {
+			return true
+		}
+	}
+	return false
+}
+
+function renderMarkdown(matrix, warnings) {
+	const lines = ['## vitest-doctor matrix', '']
+	lines.push('| workspace | NODE_ENV shim | jsxAutomaticShim | has JSX tests |')
+	lines.push('|-----------|---------------|------------------|---------------|')
+	for (const r of matrix) {
+		lines.push(
+			`| \`${r.workspace}\` | ${r.node_env_shim ? '✓' : '✗'} | ${r.jsx_automatic_shim ? '✓' : '✗'} | ${r.has_jsx_rendering_tests ? '✓' : '—'} |`,
+		)
+	}
+	if (warnings.length > 0) {
+		lines.push('', '## Warnings', '')
+		for (const w of warnings) {
+			lines.push(`- \`${w.workspace}\` — ${w.reason}`)
+		}
+	}
+	return lines.join('\n')
+}

package/src/cli/config/gitignore-drift.mjs

@@ -14,6 +14,7 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { detectWorktree } from '../git/worktree-detect.mjs'
 import { resolveSharePolicy } from './share-policy.mjs'
 import { buildAperantGitignoreTemplate } from './upgrade-gitignore.mjs'
 
@@ -35,11 +36,66 @@ const SKIP_COMMANDS = new Set([
 	'-h',
 ])
 
+/**
+ * BUG-028 — resolve the shared (main-repo) root for the dispatch hook.
+ *
+ * Mirrors `coordination/agent-identity.mjs::resolveSharedRoot` but does NOT
+ * depend on that module. The CoordinationStore seam is `@internal` (R8) —
+ * `bin/apt-tools.mjs` and its dispatch hooks must reach git through
+ * `git/worktree-detect.mjs` directly, not through `coordination/*`.
+ *
+ * @internal
+ */
+function resolveSharedRootForDrift(projectDir) {
+	try {
+		const wt = detectWorktree(projectDir)
+		return wt.is_worktree && wt.main_repo_root ? wt.main_repo_root : projectDir
+	} catch {
+		return projectDir
+	}
+}
+
+/**
+ * BUG-028 — pretty-print the first few missing / extra lines as a
+ * unified-diff snippet for the gate's `reason` field. Capped at
+ * `maxLines` per side so the reason stays short enough for terminal
+ * output. Returns the empty string when both sides match.
+ */
+export function buildGitignoreDiffSummary(expected, actual, maxLines = 3) {
+	const expSet = new Set(String(expected).split('\n'))
+	const actSet = new Set(String(actual).split('\n'))
+	const missing = []
+	for (const line of expSet) {
+		if (line === '') continue
+		if (!actSet.has(line)) {
+			missing.push(line)
+			if (missing.length >= maxLines) break
+		}
+	}
+	const extra = []
+	for (const line of actSet) {
+		if (line === '') continue
+		if (!expSet.has(line)) {
+			extra.push(line)
+			if (extra.length >= maxLines) break
+		}
+	}
+	if (missing.length === 0 && extra.length === 0) return ''
+	const parts = []
+	for (const line of missing) parts.push(`+ ${line}`)
+	for (const line of extra) parts.push(`- ${line}`)
+	return parts.join('\n')
+}
+
 /**
  * Pure comparison primitive — returns whether the on-disk `.aperant/.gitignore`
  * differs from the policy-expected template. Returns `{ drifted: false }` when
  * the `.aperant/` dir or file is absent (nothing to compare).
  *
+ * BUG-028: when drifted, embeds a unified-diff summary (≤3 missing/extra
+ * lines per side) in `reason` so the user sees exactly what drifted
+ * without re-running `apt-tools config upgrade-gitignore --dry-run`.
+ *
  * @internal
  */
 export function checkGitignoreDrift(projectRoot) {
@@ -65,7 +121,16 @@ export function checkGitignoreDrift(projectRoot) {
 	} catch {
 		return { drifted: false, reason: 'read-failed' }
 	}
-	return { drifted: actual !== expected, reason: null }
+	const drifted = actual !== expected
+	if (!drifted) return { drifted: false, reason: null }
+	const diff = buildGitignoreDiffSummary(expected, actual)
+	return {
+		drifted: true,
+		reason: diff
+			? `.aperant/.gitignore drift detected:\n${diff}`
+			: '.aperant/.gitignore drift detected (whitespace-only)',
+		diff,
+	}
 }
 
 /**
@@ -74,15 +139,21 @@ export function checkGitignoreDrift(projectRoot) {
  *   - `command` is not in the hot-path allowlist
  *   - `.aperant/.gitignore` exists AND does not match the expected template
  *
+ * BUG-028: resolves the shared (main-repo) root internally so the same drift
+ * case produces the same verdict regardless of cwd context. Pre-fix this
+ * inspected `cwd` directly, producing a warning from one cwd context and a
+ * clean envelope from another for the same on-disk drift.
+ *
  * Never throws.
  *
  * @internal
  */
-export function emitDriftWarningIfAny(projectRoot, command) {
+export function emitDriftWarningIfAny(cwd, command) {
 	try {
 		if (process.env.APT_SUPPRESS_GITIGNORE_DRIFT === '1') return
 		if (!command || SKIP_COMMANDS.has(command)) return
-		const { drifted } = checkGitignoreDrift(projectRoot)
+		const sharedRoot = resolveSharedRootForDrift(cwd)
+		const { drifted } = checkGitignoreDrift(sharedRoot)
 		if (drifted) {
 			process.stderr.write(
 				'[apt-tools] warning: .aperant/.gitignore is out of sync with share policy — run `apt-tools config upgrade-gitignore . --dry-run` to see the diff.\n',

package/src/cli/config/load.mjs

@@ -2,7 +2,7 @@
  * config/load.mjs — project config loader + task-isolation normalizer (C29).
  */
 
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { cliToInstallRoot } from '../install/cli-to-install-root.mjs'
@@ -31,7 +31,7 @@ export function loadProjectConfig(targetDir) {
  * fallback would mask the user's broken override. See FRAMEWORK-AUDIT-001.
  *
  * @param {string} targetDir
- * @returns {object | null}
+ * @returns {Record<string, any> | null}
  */
 export function loadMergedProjectConfig(targetDir) {
 	const shared = loadProjectConfig(targetDir)
@@ -57,6 +57,192 @@ function deepMerge(a, b) {
 	return out
 }
 
+/**
+ * AUDIT-001 — read+write helpers for `.aperant/config.local.json`.
+ * Used by the 5 deferred fields migrated out of `config.json`:
+ *   - verification.open_report
+ *   - multi_model.cross_verification.tools
+ *   - preferences.date_format
+ *   - preferences.time_format
+ *   - preferences.quick_task_post_verify
+ *
+ * Each field has its own read/write site. The shared helpers below give
+ * those sites a single primitive instead of hand-rolled JSON I/O.
+ */
+function setDottedPath(obj, dotPath, value) {
+	const parts = dotPath.split('.')
+	let cursor = obj
+	for (let i = 0; i < parts.length - 1; i++) {
+		const key = parts[i]
+		if (!cursor[key] || typeof cursor[key] !== 'object' || Array.isArray(cursor[key])) {
+			cursor[key] = {}
+		}
+		cursor = cursor[key]
+	}
+	cursor[parts[parts.length - 1]] = value
+}
+
+function getDottedPath(obj, dotPath) {
+	const parts = dotPath.split('.')
+	let cursor = obj
+	for (const part of parts) {
+		if (cursor === null || cursor === undefined || typeof cursor !== 'object') return undefined
+		cursor = cursor[part]
+	}
+	return cursor
+}
+
+function deleteDottedPath(obj, dotPath) {
+	const parts = dotPath.split('.')
+	let cursor = obj
+	for (let i = 0; i < parts.length - 1; i++) {
+		const key = parts[i]
+		if (!cursor[key] || typeof cursor[key] !== 'object') return false
+		cursor = cursor[key]
+	}
+	const leaf = parts[parts.length - 1]
+	if (leaf in cursor) {
+		delete cursor[leaf]
+		return true
+	}
+	return false
+}
+
+/**
+ * Read a single dotted-path field from the merged config (local overrides
+ * shared). Returns `undefined` when neither file carries the path.
+ *
+ * @internal
+ */
+export function readLocalOrSharedField(targetDir, dotPath) {
+	const merged = loadMergedProjectConfig(targetDir)
+	if (!merged) return undefined
+	return getDottedPath(merged, dotPath)
+}
+
+/**
+ * Write a single dotted-path field into `.aperant/config.local.json`,
+ * creating the file (and intermediate path) when it doesn't exist.
+ *
+ * The shared `config.json` is NOT touched by this helper — that's the
+ * load-bearing AUDIT-001 contract. Callers that need to remove a stale
+ * entry from `config.json` (e.g. the init.mjs migrator) must do so
+ * explicitly.
+ *
+ * @internal
+ */
+export function writeLocalConfigField(targetDir, dotPath, value) {
+	const aperantDir = join(targetDir, '.aperant')
+	mkdirSync(aperantDir, { recursive: true })
+	const localPath = join(aperantDir, 'config.local.json')
+	let local = {}
+	if (existsSync(localPath)) {
+		try {
+			local = JSON.parse(readFileSync(localPath, 'utf-8'))
+			if (local === null || typeof local !== 'object' || Array.isArray(local)) local = {}
+		} catch (e) {
+			throw new Error(`config.local.json parse error: ${e.message}`)
+		}
+	}
+	setDottedPath(local, dotPath, value)
+	writeFileSync(localPath, `${JSON.stringify(local, null, 2)}\n`)
+}
+
+/**
+ * AUDIT-001 — first-run migrator. For each dotted-path entry present in
+ * `.aperant/config.json`, copy the value into `.aperant/config.local.json`
+ * (idempotent — won't overwrite an existing local value) and delete the
+ * entry from `config.json`. Each field's migration is independent —
+ * one failure does NOT block the others (a per-field try/catch wraps
+ * each move).
+ *
+ * Returns an array `[{ field, migrated_value, status }]` for caller
+ * telemetry; `status` is `'migrated' | 'already-local' | 'absent' | 'error'`.
+ *
+ * @internal
+ */
+export function migrateDeferredFieldsToLocalConfig(targetDir, dotPaths) {
+	const results = []
+	const sharedPath = join(targetDir, '.aperant', 'config.json')
+	if (!existsSync(sharedPath)) {
+		for (const dotPath of dotPaths) results.push({ field: dotPath, status: 'absent' })
+		return results
+	}
+	let shared
+	try {
+		shared = JSON.parse(readFileSync(sharedPath, 'utf-8'))
+	} catch {
+		for (const dotPath of dotPaths) results.push({ field: dotPath, status: 'error' })
+		return results
+	}
+	// Pre-load local config ONCE so the already-local check reads from
+	// local-only state (NOT from the merged loader — that would conflate
+	// the shared entry we're about to delete with a real local override).
+	const localPath = join(targetDir, '.aperant', 'config.local.json')
+	let localAtStart = {}
+	if (existsSync(localPath)) {
+		try {
+			localAtStart = JSON.parse(readFileSync(localPath, 'utf-8')) ?? {}
+		} catch {
+			localAtStart = {}
+		}
+	}
+	let sharedMutated = false
+	for (const dotPath of dotPaths) {
+		try {
+			const sharedValue = getDottedPath(shared, dotPath)
+			if (sharedValue === undefined) {
+				results.push({ field: dotPath, status: 'absent' })
+				continue
+			}
+			const existingLocal = getDottedPath(localAtStart, dotPath)
+			// Already-local: the local override already exists. Strip the
+			// stale shared entry but keep the local value as-is (don't
+			// overwrite a user-tuned local with the stale shared default).
+			if (existingLocal !== undefined) {
+				deleteDottedPath(shared, dotPath)
+				sharedMutated = true
+				results.push({ field: dotPath, status: 'already-local', migrated_value: sharedValue })
+				continue
+			}
+			writeLocalConfigField(targetDir, dotPath, sharedValue)
+			deleteDottedPath(shared, dotPath)
+			sharedMutated = true
+			results.push({ field: dotPath, status: 'migrated', migrated_value: sharedValue })
+		} catch (e) {
+			results.push({ field: dotPath, status: 'error', error: e?.message ?? String(e) })
+		}
+	}
+	if (sharedMutated) {
+		try {
+			writeFileSync(sharedPath, `${JSON.stringify(shared, null, 2)}\n`)
+		} catch (e) {
+			// Disk write failed after per-field local writes succeeded.
+			// Log a structured warning so callers can surface the partial state
+			// to the user (config.local.json updated, config.json NOT cleaned up).
+			results.push({
+				field: '__write_shared__',
+				status: 'error',
+				error: `migration_partial_rollback: config.local.json was updated but config.json could not be written (${e?.message ?? String(e)}). Re-run init to retry.`,
+			})
+		}
+	}
+	return results
+}
+
+/**
+ * AUDIT-001 — the 5 deferred fields that move to config.local.json.
+ * Single source of truth used by both the init migrator and the
+ * per-field regression tests.
+ */
+export const AUDIT_001_LOCAL_FIELDS = Object.freeze([
+	'verification.open_report',
+	'multi_model.cross_verification.tools',
+	'preferences.date_format',
+	'preferences.time_format',
+	'preferences.quick_task_post_verify',
+])
+
 /**
  * Return a normalized task_isolation config object with safe fallbacks.
  * Always returns a concrete object even when the project has no config at all,

package/src/cli/consistency/parse-review.mjs

@@ -95,6 +95,12 @@ function normalizeStatus(f) {
 	if (typeof f.status === 'string') {
 		const s = f.status.toLowerCase().trim()
 		if (STATUS_MAP[s]) return STATUS_MAP[s]
+		// BUG-009: reviewer-skill writes `deferred-per-spec`, `deferred-followup`,
+		// etc. for findings that are intentionally not being fixed in the
+		// current scope. Collapse the variant prefix back to canonical
+		// `deferred` so downstream gates (review-clean, ship) treat them
+		// the same as a bare `status: "deferred"`.
+		if (s.startsWith('deferred-')) return 'deferred'
 	}
 	return 'open'
 }

package/src/cli/dispatch.mjs

@@ -41,7 +41,7 @@ import { cmdAuthorSkill } from './commands/author-skill.mjs'
 import { cmdBootstrap } from './commands/bootstrap.mjs'
 import { cmdCheck } from './commands/check.mjs'
 import { cmdCheckVersion } from './commands/check-version.mjs'
-import { cmdCiWatch } from './commands/ci-watch.mjs'
+import { cmdCiWatch, cmdCiWatchSweep } from './commands/ci-watch.mjs'
 import { cmdCommit } from './commands/commit.mjs'
 import { cmdConsistency } from './commands/consistency.mjs'
 import { cmdConstitution } from './commands/constitution.mjs'
@@ -93,6 +93,7 @@ import { cmdValidateEvidence } from './commands/validate-evidence.mjs'
 import { cmdVariantGallery } from './commands/variant-gallery.mjs'
 import { cmdVariantPick } from './commands/variant-pick.mjs'
 import { cmdVariantPool } from './commands/variant-pool.mjs'
+import { cmdVitestDoctor } from './commands/vitest-doctor.mjs'
 import { cmdWave } from './commands/wave.mjs'
 import { cmdWfrun } from './commands/wfrun.mjs'
 import { cmdWorkflow } from './commands/workflow.mjs'
@@ -241,6 +242,21 @@ export const DISPATCH = {
 	'precompact-hook': (args) => wrap(cmdPrecompactHook)(args[1]),
 	'migrate-pr-reviews': (args) => wrap(cmdMigratePrReviews)(args[1]),
 	'validate-evidence': (args) => wrap(cmdValidateEvidence)(args[1], args.slice(2)),
+	vitest: (args) => {
+		// `vitest doctor <project-dir>` — currently the only `vitest`
+		// subcommand. Reserved namespace for future vitest diagnostics.
+		const subcommand = args[1]
+		if (subcommand === 'doctor') {
+			return wrap(cmdVitestDoctor)(args[2], args.slice(3))
+		}
+		return wrap(() => ({
+			envelope: {
+				status: 'error',
+				error: `Usage: apt-tools vitest doctor <project-dir>. Unknown subcommand: ${subcommand ?? '(none)'}`,
+			},
+			exitCode: 1,
+		}))()
+	},
 
 	// ---- (positional dir, args[2] subcommand, slice(3)) shape ----
 	tokens: (args) => wrap(cmdTokens)(args[1], args[2], args.slice(3)),
@@ -261,7 +277,12 @@ export const DISPATCH = {
 	seed: (args) => wrap(cmdSeed)(args[1], args[2], args.slice(3)),
 	workflow: (args) => wrap(cmdWorkflow)(args[1], args[2], args.slice(3)),
 	'pr-review': (args) => wrap(cmdPrReview)(args[1], args[2], args.slice(3)),
-	'ci-watch': (args) => wrap(cmdCiWatch)(args[1], args[2], args.slice(3)),
+	'ci-watch': (args) => {
+		// `sweep` is async; route it to the async sibling so the sync dispatcher
+		// path doesn't return a CommandResult | Promise<CommandResult> union.
+		if (args[1] === 'sweep') return wrap(cmdCiWatchSweep)(args[2], args.slice(3))
+		return wrap(cmdCiWatch)(args[1], args[2], args.slice(3))
+	},
 	'plan-approval': (args) => wrap(cmdPlanApproval)(args[1], args[2], args.slice(3)),
 
 	// ---- Pocock adoption (ST-5, ST-6, ST-10, ST-13) artifact writers + discoverability ----

package/src/cli/gate/gates/gitignore-in-sync.mjs

@@ -22,10 +22,13 @@ const gate = {
 		]
 		const result = checkGitignoreDrift(ctx.sharedRoot)
 		if (result.drifted) {
+			// BUG-028: surface the unified-diff summary in the reason so
+			// users see exactly which template lines drifted without
+			// re-running `apt-tools config upgrade-gitignore --dry-run`.
 			return {
 				status: 'fail',
-				reason: '.aperant/.gitignore has drifted from policy-expected template',
-				evidence: { reason: result.reason ?? null },
+				reason: result.reason ?? '.aperant/.gitignore has drifted from policy-expected template',
+				evidence: { diff: result.diff ?? null },
 				inputs,
 			}
 		}

package/src/cli/gate/gates/review-clean.mjs

@@ -3,24 +3,27 @@
  * G5 review-clean — blocking gate for `apt:ship`.
  *
  * Skipped when {task_dir}/review.json is absent (review is optional for some
- * tracks). When it is present, fails if any finding has
- * severity ∈ {"critical", "warning"} AND neither `resolved === true` nor
- * `fixed === true`. The reviewer skill writes resolution as `fixed: true`
- * paired with `fix_commit`; `resolved: true` is a legacy alias.
- *
- * The findings array may be under `findings` or `issues` depending on the
- * reviewer format — we accept either.
+ * tracks). When it is present, delegates to `parseReview` (DRY with the
+ * consistency rule) which normalizes severities + statuses across all the
+ * shapes the reviewer skill writes: `fixed: true`, `resolved: true`,
+ * `status: "fixed"` (string), and `status: "deferred-*"` variants
+ * (BUG-009). Fails if any post-normalization finding is severity
+ * critical|major AND status is neither `fixed` nor `deferred`.
  */
 
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { parseReview } from '../../consistency/parse-review.mjs'
 import { registerGate } from '../registry.mjs'
 
-const BLOCKING_SEVERITIES = new Set(['critical', 'warning'])
+// Post-normalization severities. `parseReview` maps `warning → major`,
+// so the gate keys off `major` here even though the input may carry
+// `warning`.
+const POST_NORM_BLOCKING = new Set(['critical', 'major'])
 
 const gate = {
 	id: 'review-clean',
-	description: 'review.json has no unresolved critical/warning findings (skipped if absent)',
+	description: 'review.json has no unresolved critical/major findings (skipped if absent)',
 	severity: 'blocking',
 	skills: ['ship'],
 	async check(ctx) {
@@ -43,23 +46,25 @@ const gate = {
 				inputs,
 			}
 		}
-		const findings = Array.isArray(doc.findings)
-			? doc.findings
-			: Array.isArray(doc.issues)
-				? doc.issues
-				: []
-		const unresolved = findings.filter(
-			(f) => BLOCKING_SEVERITIES.has(f?.severity) && f?.resolved !== true && f?.fixed !== true,
+		// BUG-009: delegate to parseReview so this gate sees the SAME
+		// normalized findings the consistency rule does. The pre-fix
+		// inline filter only inspected boolean `fixed`/`resolved`, missing
+		// `status: "fixed"` strings + `summary.findings_remaining: 0`
+		// shapes the reviewer skill writes; this delegation closes that
+		// hole and picks up `deferred-*` variants for free.
+		const { findings: normalized } = parseReview(doc)
+		const unresolved = normalized.filter(
+			(f) => POST_NORM_BLOCKING.has(f.severity) && f.status !== 'fixed' && f.status !== 'deferred',
 		)
 		if (unresolved.length > 0) {
 			return {
 				status: 'fail',
-				reason: `${unresolved.length} unresolved critical/warning finding(s) in review.json`,
+				reason: `${unresolved.length} unresolved critical/major finding(s) in review.json`,
 				evidence: {
 					unresolved: unresolved.map((f) => ({
 						severity: f.severity,
 						id: f.id ?? null,
-						title: f.title ?? f.message ?? null,
+						title: f.title ?? null,
 					})),
 				},
 				inputs,
@@ -67,7 +72,7 @@ const gate = {
 		}
 		return {
 			status: 'pass',
-			reason: `review.json has no unresolved critical/warning findings (${findings.length} total)`,
+			reason: `review.json has no unresolved critical/major findings (${normalized.length} total)`,
 			inputs,
 		}
 	},