@aperant/framework 0.7.0 → 0.7.3

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,
 		}
 	},

package/src/cli/gate/gates/verify-approved.mjs

@@ -3,22 +3,54 @@
  * G4 verify-approved — blocking gate for `apt:ship`.
  *
  * Requires {task_dir}/qa_signoff.json to exist, parse, and carry
- * verdict === "approved". The ship skill's existing prose only asked the
- * agent to "confirm" approval; this gate enforces it deterministically.
+ * verdict === "approved" (BUG-013: normalized via parseQaSignoff — case
+ * and underscore/hyphen variants collapse to canonical). BUG-012: also
+ * accepts `approved-with-notes` when config.qa.approved_with_notes_threshold
+ * is set AND every dimension score meets the threshold (best-effort when
+ * dimensions are missing or in an unknown shape).
  *
- * NOTE: the file may use either `verdict` (newer) or `status` (older) field
- * name for the QA result. We accept both for forwards/backwards compatibility,
- * but only the string "approved" passes — "approved-with-notes" fails
- * because ship-time deserves the strongest signal.
+ * Accepts both `verdict` (newer) and `status` (older) field names — that
+ * normalization is delegated to parseQaSignoff.
  */
 
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { parseQaSignoff } from '../../consistency/parse-qa.mjs'
 import { registerGate } from '../registry.mjs'
 
+/**
+ * Extract dimension scores from the qa_signoff.json shape. We've seen two
+ * shapes in the wild:
+ *   - Array: `dimensions: [{name: 'security', score: 0.9}, ...]`
+ *   - Object: `dimensions: {security: 0.9, performance: 0.85}` OR
+ *     `dimensions: {security: {score: 0.9}, ...}`
+ * Returns an array of numeric scores, or null when no recognizable shape
+ * is present (best-effort accept per brief).
+ */
+function extractDimensionScores(doc) {
+	const dims = doc.dimensions ?? doc.qa?.dimensions ?? null
+	if (!dims) return null
+	if (Array.isArray(dims)) {
+		const scores = dims
+			.map((d) => (typeof d?.score === 'number' ? d.score : null))
+			.filter((s) => s !== null)
+		return scores.length > 0 ? scores : null
+	}
+	if (typeof dims === 'object') {
+		const scores = []
+		for (const v of Object.values(dims)) {
+			if (typeof v === 'number') scores.push(v)
+			else if (typeof v?.score === 'number') scores.push(v.score)
+		}
+		return scores.length > 0 ? scores : null
+	}
+	return null
+}
+
 const gate = {
 	id: 'verify-approved',
-	description: 'qa_signoff.json exists with verdict === "approved"',
+	description:
+		'qa_signoff.json exists with verdict === "approved" (or "approved-with-notes" when configured)',
 	severity: 'blocking',
 	skills: ['ship'],
 	async check(ctx) {
@@ -41,18 +73,69 @@ const gate = {
 				inputs,
 			}
 		}
-		const verdict = doc.verdict ?? doc.status ?? null
-		if (verdict !== 'approved') {
+
+		// BUG-013: route through parseQaSignoff so the verdict is
+		// case-insensitive AND tolerates `_↔-` (so 'APPROVED', 'Approved',
+		// ' approved ', 'APPROVED_WITH_NOTES' all behave canonically). The
+		// pre-fix gate compared the raw string against `'approved'` which
+		// false-rejected every legitimate variant.
+		const { verdict } = parseQaSignoff(doc)
+
+		if (verdict === 'approved') {
 			return {
-				status: 'fail',
-				reason: `qa_signoff.json verdict is "${verdict}" (expected "approved")`,
-				evidence: { verdict },
+				status: 'pass',
+				reason: 'qa_signoff.json verdict normalized to "approved"',
 				inputs,
 			}
 		}
+
+		// BUG-012: accept `approved-with-notes` when the project has opted
+		// in via config.qa.approved_with_notes_threshold. The threshold is
+		// the minimum per-dimension score required. Best-effort: when
+		// dimensions are missing / in an unknown shape we still accept and
+		// log, rather than hard-failing, so projects that haven't started
+		// scoring dimensions yet aren't blocked.
+		if (verdict === 'approved-with-notes') {
+			const threshold = ctx.config?.qa?.approved_with_notes_threshold
+			if (typeof threshold !== 'number') {
+				return {
+					status: 'fail',
+					reason:
+						'qa_signoff.json verdict is "approved-with-notes" but config.qa.approved_with_notes_threshold is not set',
+					evidence: { verdict, threshold: threshold ?? null },
+					inputs,
+				}
+			}
+			const scores = extractDimensionScores(doc)
+			if (scores === null) {
+				return {
+					status: 'pass',
+					reason: `qa_signoff.json verdict is "approved-with-notes" and threshold ${threshold} is enabled; dimensions missing or unknown-shape — accepting best-effort`,
+					evidence: { verdict, threshold, dimensions_present: false },
+					inputs,
+				}
+			}
+			const failing = scores.filter((s) => s < threshold)
+			if (failing.length > 0) {
+				return {
+					status: 'fail',
+					reason: `qa_signoff.json verdict is "approved-with-notes" but ${failing.length}/${scores.length} dimension score(s) below threshold ${threshold}`,
+					evidence: { verdict, threshold, scores, failing },
+					inputs,
+				}
+			}
+			return {
+				status: 'pass',
+				reason: `qa_signoff.json verdict is "approved-with-notes" and all ${scores.length} dimension score(s) meet threshold ${threshold}`,
+				evidence: { verdict, threshold, scores },
+				inputs,
+			}
+		}
+
 		return {
-			status: 'pass',
-			reason: 'qa_signoff.json.verdict === "approved"',
+			status: 'fail',
+			reason: `qa_signoff.json verdict is "${verdict}" (expected "approved" or "approved-with-notes" with threshold)`,
+			evidence: { verdict },
 			inputs,
 		}
 	},

package/src/cli/help.mjs

@@ -34,7 +34,7 @@ Commands:
   task close-merged <dir> [--task <id>] [--narrate-only] [--dry-run]   Sweep shipped-pending-merge tasks for confirmed merges (--narrate-only returns pending_narration[] entries read-only without closing).
   task narration-drain <dir> --task <task-id>     Remove a row from state.pending_narration[] under withFileLock (called by /apt:close-task --narrate-only after a successful narrator spawn)
   task complete-subtask <dir> --task-id <id> --subtask-id <sid|a+b+c> [--commit <sha>] [--notes <text>]  Atomic plan ↔ build-progress sync
-  features-audit <dir> [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files
+  features-audit <dir> [--task-id <id>] [--no-worktree-redirect] [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files (BUG-025b: --task-id redirects writes to active task's worktree)
   docs-audit <dir> [--diff-files <csv>|--since <ref>|--dry-run] [--policy <path>] [--format json|md]  Audit documented surfaces for docs-drift
 
   lock claim <dir> --subtask <id>       Claim exclusive lock on a subtask
@@ -110,7 +110,9 @@ Commands:
 
   migrate-pr-reviews <project-dir>       Migrate legacy .aperant/reviews/ → .aperant/pr-reviews/pr-{N}/rounds/{R}/ (idempotent)
 
-  validate-evidence <findings-dir> --worktree <path>   Enforce the Evidence Rule (literal substring + multi-file check); mutates findings markdown in place
+  validate-evidence <findings-dir> --worktree <path> [--allow-approx-evidence] [--approx-floor <n>] [--llm-validator-confirmed]   Enforce the Evidence Rule (literal substring + multi-file check); mutates findings markdown in place. BUG-014: --allow-approx-evidence opts into Jaccard + line-anchor fallback (downgrade to dismissed_evidence_approx_confirmed unless --llm-validator-confirmed promotes to confirmed_valid_approx).
+
+  vitest doctor <project-dir> [--format json|md]   BUG-026: walk vitest.config.{ts,js,mjs} files, report NODE_ENV/jsxAutomaticShim matrix, warn when JSX-rendering tests lack jsxAutomaticShim coverage (exits 1 on warnings)
 
   wfrun validate <workflow.yaml>                         C17: parse + schema-check a declarative YAML workflow (exits 0 on success)
   wfrun plan <workflow.yaml> [--input k=v …]             C17: resolve DAG waves + inputs, emit run-plan JSON (no side effects)
@@ -126,6 +128,9 @@ Commands:
   pr-review record-comment <dir> --pr <N> --round <R> --url <url> --body-hash <sha256> [--review-id <id>] [--posted-at <iso>]  Append entry to comment_timeline (Phase 6b)
   pr-review audit-fixer <dir> --review-dir <path> --iteration <N> --fixer <name> --worktree <path> --status-line <str>  Audit fixer output against git state; exits 0 with JSON envelope (verdict: verified|hallucinated|skipped)
 
+  ci-watch start|stop|status|tick <dir> [--pr <N>] [...]   /apt:watch-ci primitives — see SKILL.md for full flag matrix
+  ci-watch sweep <dir> --orphaned [--dry-run]              BUG-027: enumerate ci-watches state files, query gh per PR, remove terminal-state (MERGED|CLOSED) entries (manual GC; rate-limited)
+
 Flags:
   --version                             Print version and exit
   --help                                Print usage and exit