@aperant/framework 0.6.7 → 0.7.3

package/src/cli/commands/pr-review-audit-fixer.mjs

@@ -668,10 +668,14 @@ export function decideVerdict({ statusLine, fixesApplied, diffFiles }) {
 	}
 }
 
-function readFixesAppliedForFixer(reviewDir, iteration, fixer) {
-	// Try the group-specific naming first (fixes-applied-group{N}.md) for
-	// fixer-{N}, then fall back to the unscoped fixes-applied.md which the
-	// self-reviewer writes to self-review.md separately.
+export function readFixesAppliedForFixer(reviewDir, iteration, fixer) {
+	// BUG-030: strict-ordered candidate list. Parallel fixers write to
+	// distinct fixer-named markdowns (fixes-applied-fixer-{N}.md AND/OR
+	// fixes-applied-{fixer}.md); the legacy group-named form remains for
+	// backward-compat with reviews started before this fix. fixes-applied.md
+	// (unscoped) stays last as the legacy single-fixer fallback. NO broad
+	// glob — false-positives on the wrong fixer's file are what caused the
+	// `hallucinated` flake (4 sightings in 3 days per spec-gaps).
 	const iterDir = join(reviewDir, 'iterations', String(iteration))
 	const candidates = []
 	if (fixer === 'self-reviewer') {
@@ -681,7 +685,9 @@ function readFixesAppliedForFixer(reviewDir, iteration, fixer) {
 		const match = /^fixer-(\d+)$/.exec(fixer)
 		if (match) {
 			candidates.push(join(iterDir, `fixes-applied-group${match[1]}.md`))
+			candidates.push(join(iterDir, `fixes-applied-fixer-${match[1]}.md`))
 		}
+		candidates.push(join(iterDir, `fixes-applied-${fixer}.md`))
 		candidates.push(join(iterDir, 'fixes-applied.md'))
 	}
 	for (const c of candidates) {
@@ -802,7 +808,14 @@ export function cmdPrReviewAuditFixer(projectDir, extraArgs) {
 
 	const worktreeArg = flags.get('worktree')
 	if (!worktreeArg) return err('Required: --worktree <path>')
-	const worktree = resolve(worktreeArg)
+	// BUG-015: resolve relative to the passed projectDir (not process.cwd()).
+	// Callers invoke audit-fixer from a non-worktree cwd (the main repo) with
+	// a relative --worktree like `../worktrees/foo`; resolving against cwd
+	// returned a bogus path that didn't exist, causing the audit to see zero
+	// staged files and false-positive `hallucinated`. The existing `cwd:
+	// worktree` at the spawn site (line 437-473) already scopes git
+	// invocations correctly, so no `git -C` change is needed.
+	const worktree = resolve(projectDir, worktreeArg)
 
 	const statusLineArg = flags.get('status-line')
 	// Missing / empty status line is fail-closed to hallucinated, not a

package/src/cli/commands/route.mjs

@@ -26,16 +26,36 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { getTaskIsolationConfig, getTrustedSkillSources } from '../config/load.mjs'
 import '../gate/gates/index.mjs'
 import * as gateRegistry from '../gate/registry.mjs'
 import { detectHost, SUPPORTED_HOSTS } from '../host/detect.mjs'
+import { detectSourceWorkspaceDrift } from '../route/drift-detect.mjs'
 import { buildEnvelope } from '../route/envelope.mjs'
 import { discoverSkills } from '../route/skill-discover.mjs'
 import { executionModesList, isValidExecutionMode } from '../task/execution-mode.mjs'
 import { err, exitWith, ok } from '../util/result.mjs'
 
+/**
+ * Read the installed kernel's own version from its package.json.
+ * Same pattern as commands/check-version.mjs:108-109 — `__dirname` of
+ * the running module resolves to the installed kernel for npm-installed
+ * users and to the source workspace for in-monorepo runs. Returns null
+ * on any I/O / parse failure (drift-detect treats null as "skip").
+ */
+function readInstalledKernelVersion() {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url))
+		const pkgPath = resolve(here, '..', '..', '..', 'package.json')
+		const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+		return typeof pkg?.version === 'string' ? pkg.version : null
+	} catch {
+		return null
+	}
+}
+
 /**
  * Read the shared update-check cache (written by the SessionStart hook
  * via apt-check-update-worker.js) and extract the fields /apt's SKILL.md
@@ -254,7 +274,23 @@ export function cmdRoute(projectDir, extraArgs) {
 	const task_isolation = getTaskIsolationConfig(targetDir)
 
 	const updateCheck = readUpdateCheckCache()
-	const update_check = updateCheck ? { ...updateCheck } : null
+	let update_check = updateCheck ? { ...updateCheck } : null
+
+	// FRAMEWORK-BUG-017 rung 1: in-band detection of workspace-ahead-of-
+	// installed-kernel drift. Catches the self-host contributor case
+	// where the SessionStart worker can't see the local same-PR fix yet.
+	// Workspace wins when both signals fire (workspace is the source of
+	// truth for self-host).
+	const installedKernelVersion = readInstalledKernelVersion()
+	const drift = detectSourceWorkspaceDrift(targetDir, installedKernelVersion)
+	if (drift) {
+		update_check = {
+			update_available: true,
+			installed_version: drift.installed_version,
+			latest_version: drift.source_version,
+			reason: 'workspace source ahead of installed kernel — run /apt:update --from-source',
+		}
+	}
 
 	// ---------------- Deterministic branches (zero-behavior-change) ----------------
 	// These fire regardless of host detection status — missing host is not

package/src/cli/commands/task.mjs

@@ -14,7 +14,11 @@
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { getTaskIsolationConfig, loadProjectConfig } from '../config/load.mjs'
+import {
+	getTaskIsolationConfig,
+	loadMergedProjectConfig,
+	loadProjectConfig,
+} from '../config/load.mjs'
 import { findMostRecentEventForTask } from '../coordination/event-log.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { getGitIdentity } from '../git/identity.mjs'
@@ -127,9 +131,16 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 				// a later roadmap add-milestone/add-phase may populate it.
 			}
 
-			// Load config for date format preference
-			const configPath = join(targetDir, '.aperant', 'config.json')
-			const config = existsSync(configPath) ? JSON.parse(readFileSync(configPath, 'utf-8')) : {}
+			// AUDIT-001: read through the merged loader so local-only
+			// overrides for preferences.date_format / preferences.time_format
+			// win over the shared config.json fallback.
+			// Guard: malformed config.local.json must not crash task creation.
+			let config
+			try {
+				config = loadMergedProjectConfig(targetDir) ?? {}
+			} catch {
+				config = {}
+			}
 			// User-supplied --id bypasses the collision guard (caller owns the
 			// uniqueness contract). Generated ids run through a numeric-counter
 			// disambiguator that appends -2, -3, … when the candidate already
@@ -982,7 +993,50 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					state.last_activity = new Date().toISOString()
 					atomicWriteJson(statePath, state)
 					if (prUrlForCiWatch) {
-						ciWatchResult = armCiWatchAfterPrUrl(targetDir, task, prUrlForCiWatch)
+						// BUG-027 (a): pre-arm gh check. If the PR is already
+						// MERGED/CLOSED, skip arming so we don't leak a new
+						// watcher state file we'll immediately have to GC. gh
+						// rate-limit / offline / ENOENT falls back to arm (mirror
+						// the existing rate_limited/offline patterns at lines
+						// 1322/1326) — non-fatal so a transient gh failure
+						// doesn't prevent legitimate watcher arming.
+						const ghFixture = process.env.APT_GH_FIXTURE_JSON
+						let terminalState = null
+						if (ghFixture) {
+							try {
+								const parsed = JSON.parse(ghFixture)
+								if (parsed?.state === 'MERGED' || parsed?.state === 'CLOSED') {
+									terminalState = parsed.state
+								}
+							} catch {
+								/* malformed fixture → fall through to arm */
+							}
+						} else {
+							try {
+								const res = spawnSync('gh', ['pr', 'view', prUrlForCiWatch, '--json', 'state'], {
+									cwd: targetDir,
+									encoding: 'utf-8',
+								})
+								if (res.status === 0 && res.stdout) {
+									const parsed = JSON.parse(res.stdout)
+									if (parsed?.state === 'MERGED' || parsed?.state === 'CLOSED') {
+										terminalState = parsed.state
+									}
+								}
+								/* non-zero exit / ENOENT / parse error → fall through to arm */
+							} catch {
+								/* never block arming on gh transport error */
+							}
+						}
+						if (terminalState) {
+							ciWatchResult = {
+								ci_watch_armed: false,
+								ci_watch_skip_reason: 'pr-terminal-state',
+								ci_watch: null,
+							}
+						} else {
+							ciWatchResult = armCiWatchAfterPrUrl(targetDir, task, prUrlForCiWatch)
+						}
 					}
 
 					regenerateTaskIndex(targetDir)
@@ -1006,6 +1060,12 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						updateOut.ci_watch_armed = ciWatchResult.ci_watch_armed
 						updateOut.ci_watch_skip_reason = ciWatchResult.ci_watch_skip_reason
 						if (ciWatchResult.ci_watch) updateOut.ci_watch = ciWatchResult.ci_watch
+						// FRAMEWORK-BUG-018 Track 1: surface `scheduler_handle` at the top
+						// level so `apt-ship/SKILL.md` §7.2 can read it via
+						// `.scheduler_handle // empty` without dotting through `.ci_watch.*`.
+						// `null` today (no production path populates it); Track 2 lands
+						// non-null values without re-plumbing the envelope shape.
+						updateOut.scheduler_handle = ciWatchResult.scheduler_handle ?? null
 					}
 					updateResult = ok(updateOut)
 				},
@@ -1217,6 +1277,46 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 			// `gh pr view`, and close the ones GitHub says merged. Per spec §B1.
 			const onlyTaskId = flags.get('task') || null
 			const dryRun = flags.has('dry-run')
+			const narrateOnly = flags.has('narrate-only')
+
+			// FRAMEWORK-BUG-020 — `--narrate-only` is read-only enumeration of
+			// the pending_narration[] ledger. No `gh pr view`, no `task close`
+			// spawn, no ledger writes. The skill body (apt-close-task §4) drains
+			// per row via `task narration-drain` AFTER a successful narrator
+			// spawn — at-least-once semantics is safe because the narrator is
+			// anchor-replace idempotent (agents/apt-team-docs-narrator.md §6/§2).
+			if (narrateOnly) {
+				if (!existsSync(statePath)) {
+					return ok({
+						status: 'ok',
+						command: 'task-close-merged',
+						mode: 'narrate-only',
+						closed: [],
+						skipped: [],
+						errors: [],
+					})
+				}
+				const stateBlob = JSON.parse(readFileSync(statePath, 'utf-8'))
+				const ledger = Array.isArray(stateBlob.pending_narration) ? stateBlob.pending_narration : []
+				const filtered = onlyTaskId
+					? ledger.filter((row) => row && row.task_id === onlyTaskId)
+					: ledger
+				return ok({
+					status: 'ok',
+					command: 'task-close-merged',
+					mode: 'narrate-only',
+					closed: filtered.map((row) => ({
+						task_id: row.task_id,
+						scope: row.scope ?? null,
+						phase_id: row.phase_id ?? null,
+						closed_at: row.closed_at ?? null,
+						pr_number: row.pr_number ?? null,
+						narration_pending: true,
+					})),
+					skipped: [],
+					errors: [],
+				})
+			}
 
 			if (!existsSync(statePath)) {
 				return ok({
@@ -1433,6 +1533,30 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					mergedAt: parsed.mergedAt ?? null,
 				})
 
+				// BUG-027 (b): tear down any armed ci-watch state for this PR.
+				// `doStop` is idempotent (returns `not-found` for missing state
+				// files), so calling unconditionally here is safe. Without this
+				// the watcher state file leaks past PR-terminal-state and
+				// downstream operations (ci-watch sweep, health-check) flag it
+				// as orphaned. Failure is logged into errors[] as a warning;
+				// the merge close itself has already succeeded.
+				try {
+					const prNumber = parsed.number ?? extractPrNumber(task.pr_url)
+					if (prNumber !== null) {
+						cmdCiWatch('stop', targetDir, [
+							'--pr',
+							String(prNumber),
+							'--reason',
+							'task-closed-merged',
+						])
+					}
+				} catch (e) {
+					errors.push({
+						id,
+						reason: `ci-watch-stop-failed: ${e?.message ?? String(e)}`,
+					})
+				}
+
 				// Append a pending_narration[] ledger entry on successful merged close
 				// so /apt:close-task --narrate-only can drain it later. The ledger is
 				// additive-only; failure to write must never undo the close above
@@ -1675,6 +1799,7 @@ function armCiWatchAfterPrUrl(targetDir, task, prUrl) {
 			ci_watch_armed: true,
 			ci_watch_skip_reason: null,
 			ci_watch: envelope,
+			scheduler_handle: envelope.scheduler_handle ?? null,
 		}
 	}
 	if (envelope.status === 'busy' && envelope.reason === 'already-armed') {
@@ -1682,12 +1807,14 @@ function armCiWatchAfterPrUrl(targetDir, task, prUrl) {
 			ci_watch_armed: true,
 			ci_watch_skip_reason: 'already-armed',
 			ci_watch: envelope,
+			scheduler_handle: envelope.scheduler_handle ?? null,
 		}
 	}
 	return {
 		ci_watch_armed: false,
 		ci_watch_skip_reason: envelope.reason || 'start-failed',
 		ci_watch: envelope,
+		scheduler_handle: envelope.scheduler_handle ?? null,
 	}
 }
 

package/src/cli/commands/validate-evidence.mjs

@@ -166,7 +166,12 @@ export function isAnnotationLine(line, sourceWindow) {
  */
 export function parseFindingsMarkdown(markdown) {
 	const findings = []
-	const headerRx = /^## Finding:\s*([A-Z]+-\d+)\s*--\s*(.+)$/gm
+	// BUG-032: widen to accept H2|H3, optional `Finding:` prefix, and any of
+	// ASCII `--`, em-dash `—`, or en-dash `–` as the id/title separator. The
+	// validator-agent's consolidated `validated.md` shape uses H3 + em-dash
+	// with no `Finding:` prefix; the specialist shape uses H2 + `Finding:` +
+	// ASCII `--`. Both must round-trip through the same parser.
+	const headerRx = /^#{2,3}\s+(?:Finding:\s*)?([A-Z]+-\d+)\s*(?:--|—|–)\s*(.+)$/gm
 	const matches = [...markdown.matchAll(headerRx)]
 	for (let i = 0; i < matches.length; i++) {
 		const m = matches[i]
@@ -202,23 +207,45 @@ function parseFindingBlock(body, id, title, start, end) {
 	// FRAMEWORK-BUG-001 surfaced by /apt:pr-review on PR #68 in 2026-04).
 	// `(?:-\d+)?` consumes the trailing range so it doesn't leak into the
 	// file capture.
+	// BUG-032: the validator-agent's `validated.md` carries the cited path
+	// in `- **Original**:` instead of `- **File**:`. Map either spelling
+	// onto `file`/`line`; specialist shape continues to write to `file`.
+	const fileField = fields.file ?? fields.original
 	let file = null
 	let line = null
-	if (fields.file) {
-		const fileMatch = /^`?([^`:]+?)(?::(\d+)(?:-\d+)?)?`?\s*$/.exec(fields.file)
+	let lineRangeFromField = null
+	if (fileField) {
+		const fileMatch = /^`?([^`:]+?)(?::(\d+)(?:-(\d+))?)?`?\s*$/.exec(fileField)
 		if (fileMatch) {
 			file = fileMatch[1].trim()
 			line = fileMatch[2] ? Number(fileMatch[2]) : null
+			if (fileMatch[2] && fileMatch[3]) {
+				lineRangeFromField = [Number(fileMatch[2]), Number(fileMatch[3])]
+			}
 		}
 	}
 
 	// Description block: everything between `### Description` and the next `###`.
 	const description = extractSection(body, 'Description') ?? ''
 
-	// Evidence code block: first triple-backticked block after `### Evidence`.
+	// Evidence code block: first triple-backticked block after `### Evidence`
+	// (specialist shape). BUG-032: validator-consolidated `validated.md`
+	// shape carries evidence as a `- **Evidence**:` field whose value is the
+	// fenced block immediately following the field line. Fall back to the
+	// first fenced block after that field marker when the section heading
+	// form yields nothing.
 	const evidenceSection = extractSection(body, 'Evidence') ?? ''
+	let evidence
 	const fenced = /```[^\n]*\n([\s\S]*?)```/.exec(evidenceSection)
-	const evidence = fenced ? fenced[1] : evidenceSection
+	if (fenced) {
+		evidence = fenced[1]
+	} else if (evidenceSection) {
+		evidence = evidenceSection
+	} else {
+		const fieldEvidenceRx = /-\s*\*\*Evidence\*\*:\s*(?:\n+)```[^\n]*\n([\s\S]*?)```/i
+		const fieldFenced = fieldEvidenceRx.exec(body)
+		evidence = fieldFenced ? fieldFenced[1] : (fields.evidence ?? '')
+	}
 
 	// Suggested Fix section (prose + optional fenced snippets). Unlike
 	// Evidence we keep the whole section — snippets AND surrounding
@@ -231,9 +258,11 @@ function parseFindingBlock(body, id, title, start, end) {
 	const rangeMatch = /Lines? examined[^\d]*(\d+)\s*-\s*(\d+)/i.exec(contextSection)
 	const lineRange = rangeMatch
 		? [Number(rangeMatch[1]), Number(rangeMatch[2])]
-		: line
-			? [line, line]
-			: null
+		: lineRangeFromField
+			? lineRangeFromField
+			: line
+				? [line, line]
+				: null
 
 	// Cross-file evidence (optional): `### Cross-File Evidence` block.
 	// Each file gets a `- **File**: path` + fenced snippet.
@@ -294,11 +323,64 @@ export function detectReferencedFiles(finding) {
 	return [...tokens].sort()
 }
 
+/**
+ * BUG-014 fuzzy-evidence helpers — token-set Jaccard + line-anchor count.
+ *
+ * Tokenize on word characters so whitespace, punctuation, and operator
+ * spacing don't perturb similarity. Same tokenizer runs on both sides so
+ * the ratio is symmetric.
+ */
+export function tokenizeForJaccard(text) {
+	if (!text) return []
+	return (
+		String(text)
+			.toLowerCase()
+			.match(/[a-z0-9_$]+/g) ?? []
+	)
+}
+
+export function jaccardSimilarity(a, b) {
+	const setA = new Set(tokenizeForJaccard(a))
+	const setB = new Set(tokenizeForJaccard(b))
+	if (setA.size === 0 && setB.size === 0) return 1
+	if (setA.size === 0 || setB.size === 0) return 0
+	let intersection = 0
+	for (const t of setA) if (setB.has(t)) intersection++
+	const union = setA.size + setB.size - intersection
+	return intersection / union
+}
+
+/**
+ * Count evidence lines that appear as literal substrings of the cited
+ * file range (after `normalizeForLiteralMatch`). Used as the
+ * anchor-count mitigation against token-stuffing under fuzzy mode.
+ */
+export function countExactLineAnchors(evidenceLines, target) {
+	const normTarget = normalizeForLiteralMatch(target)
+	let count = 0
+	for (const line of evidenceLines) {
+		const normLine = normalizeForLiteralMatch(line)
+		if (!normLine) continue
+		if (normTarget.includes(normLine)) count++
+	}
+	return count
+}
+
 /**
  * Check a single finding against the literal-substring rule. Returns
  * a decision object; caller applies it to the markdown.
+ *
+ * Optional `opts.allowApprox` enables BUG-014 opt-in fuzzy fallback —
+ * when the literal check fails, compute Jaccard ≥ `approxFloor` on the
+ * cited range AND require ≥2 exact line anchors in the cited range
+ * (token-stuffing mitigation). On success, emit downgraded status
+ * `dismissed_evidence_approx_confirmed` unless `opts.llmValidatorConfirmed`
+ * is also set, in which case status becomes `confirmed_valid_approx`.
  */
-export function checkFinding(finding, worktreeRoot) {
+export function checkFinding(finding, worktreeRoot, opts = {}) {
+	const allowApprox = Boolean(opts.allowApprox)
+	const approxFloor = typeof opts.approxFloor === 'number' ? opts.approxFloor : 0.85
+	const llmValidatorConfirmed = Boolean(opts.llmValidatorConfirmed)
 	// Rule 1: evidence must be a literal substring of the cited file range.
 	if (!finding.file) {
 		return {
@@ -361,6 +443,10 @@ export function checkFinding(finding, worktreeRoot) {
 	const normTarget = normalizeForLiteralMatch(target)
 	const normWholeEvidence = normalizeForLiteralMatch(keptLines.join('\n'))
 
+	// Capture the first literal-mismatch reason so the fuzzy fallback can
+	// reuse it as the rejection note when fuzzy ALSO fails.
+	let literalRejectNote = null
+
 	if (normTarget.includes(normWholeEvidence)) {
 		// Fast path: the kept evidence (joined back) is still a literal
 		// contiguous substring of the cited range. This is the common
@@ -370,17 +456,43 @@ export function checkFinding(finding, worktreeRoot) {
 		// (e.g. `code line A\n// ... 10 more\ncode line B`). Match each
 		// kept line individually against the cited range. Every kept
 		// line must appear; any miss is a paraphrase / fabrication and
-		// the whole finding is rejected.
+		// the whole finding is rejected — unless the caller opted into
+		// fuzzy fallback (BUG-014).
 		for (const line of keptLines) {
 			const normLine = normalizeForLiteralMatch(line)
 			if (!normLine) continue
 			if (!normTarget.includes(normLine)) {
-				return {
-					status: 'dismissed_evidence_not_literal',
-					note: `Evidence not found as literal substring of ${finding.file} lines ${safeStart}-${safeEnd}: line "${normLine.slice(0, 120)}" missing from cited range.`,
-				}
+				literalRejectNote = `Evidence not found as literal substring of ${finding.file} lines ${safeStart}-${safeEnd}: line "${normLine.slice(0, 120)}" missing from cited range.`
+				break
+			}
+		}
+	}
+
+	// BUG-014: opt-in fuzzy fallback. Default behaviour (allowApprox=false)
+	// preserves the anti-fabrication guarantee — literal mismatch returns
+	// `dismissed_evidence_not_literal` unchanged. When the caller passes
+	// `--allow-approx-evidence`, attempt Jaccard ≥ floor AND ≥2 exact
+	// line anchors in the cited range (mitigates token-stuffing). On
+	// success, downgrade status to `dismissed_evidence_approx_confirmed`
+	// unless the caller also passed `--llm-validator-confirmed`, in
+	// which case promote to `confirmed_valid_approx`.
+	if (literalRejectNote) {
+		if (!allowApprox) {
+			return { status: 'dismissed_evidence_not_literal', note: literalRejectNote }
+		}
+		const similarity = jaccardSimilarity(keptLines.join('\n'), target)
+		const anchors = countExactLineAnchors(keptLines, target)
+		if (similarity < approxFloor || anchors < 2) {
+			return {
+				status: 'dismissed_evidence_not_literal',
+				note: `${literalRejectNote} Fuzzy fallback also rejected (jaccard=${similarity.toFixed(3)} floor=${approxFloor}, anchors=${anchors}/2).`,
 			}
 		}
+		const approxNote = `Approximate match accepted under --allow-approx-evidence (jaccard=${similarity.toFixed(3)} ≥ ${approxFloor}, anchors=${anchors} ≥ 2).`
+		if (llmValidatorConfirmed) {
+			return { status: 'confirmed_valid_approx', note: approxNote }
+		}
+		return { status: 'dismissed_evidence_approx_confirmed', note: approxNote }
 	}
 
 	// Rule 2: multi-file references require Cross-File Evidence.
@@ -490,6 +602,18 @@ export function cmdValidateEvidence(findingsDir, extraArgs) {
 	const worktreeRoot = resolve(worktree)
 	if (!existsSync(worktreeRoot)) return err(`Worktree not found: ${worktreeRoot}`)
 
+	// BUG-014: opt-in fuzzy-evidence flags. Defaults preserve the
+	// anti-fabrication guarantee — literal substring is still the only
+	// matcher when no flag is set.
+	const allowApprox = flags.get('allow-approx-evidence') === true
+	const approxFloorRaw = flags.get('approx-floor')
+	const approxFloor = typeof approxFloorRaw === 'string' ? Number(approxFloorRaw) : 0.85
+	if (allowApprox && (!Number.isFinite(approxFloor) || approxFloor <= 0 || approxFloor > 1)) {
+		return err(`Invalid --approx-floor value: ${approxFloorRaw} (expected 0 < n ≤ 1)`)
+	}
+	const llmValidatorConfirmed = flags.get('llm-validator-confirmed') === true
+	const checkOpts = { allowApprox, approxFloor, llmValidatorConfirmed }
+
 	const files = readdirSync(dir).filter((f) => f.endsWith('.md'))
 	const summary = {
 		status: 'ok',
@@ -506,13 +630,21 @@ export function cmdValidateEvidence(findingsDir, extraArgs) {
 		const full = join(dir, f)
 		const md = readFileSync(full, 'utf-8')
 		const findings = parseFindingsMarkdown(md)
+
+		// BUG-032: always record the file in `processed_files`. The
+		// previous `continue` on empty findings caused validated.md to
+		// silently no-op when the header regex didn't match, leaving
+		// downstream gates with `processed_files: []` and no audit trail
+		// that the file was even read.
+		summary.processed_files.push({ file: f, findings_count: findings.length })
+
 		if (findings.length === 0) continue
 
 		const decisions = []
 		for (const finding of findings) {
-			const decision = checkFinding(finding, worktreeRoot)
+			const decision = checkFinding(finding, worktreeRoot, checkOpts)
 			decisions.push({ finding, decision })
-			if (decision.status === 'confirmed_valid') {
+			if (decision.status === 'confirmed_valid' || decision.status === 'confirmed_valid_approx') {
 				summary.validated++
 			} else {
 				summary.rejected++
@@ -530,7 +662,16 @@ export function cmdValidateEvidence(findingsDir, extraArgs) {
 		if (rewritten !== md) {
 			writeFileSync(full, rewritten, 'utf-8')
 		}
-		summary.processed_files.push(f)
+	}
+
+	// BUG-032: surface parser-shape drift early. If we read N markdown
+	// files but extracted zero findings, warn on stderr so future schema
+	// changes don't silently no-op the gate.
+	const totalFindings = summary.processed_files.reduce((acc, e) => acc + (e.findings_count ?? 0), 0)
+	if (files.length > 0 && totalFindings === 0) {
+		process.stderr.write(
+			`WARNING: validate-evidence read ${files.length} markdown file(s) but extracted 0 findings — parser shape mismatch?\n`,
+		)
 	}
 
 	return ok(summary)