@aperant/framework 0.7.4 → 0.8.1

package/src/cli/commands/init.mjs

@@ -3,8 +3,9 @@
  * rewrite, 2026-04).
  *
  * Replaces the previous Claude-only `cp -r` installer with the per-runtime
- * transform pipeline (src/cli/install/pipeline.mjs). All 14 runtime targets
- * supported via `--<runtime>` flags or `--all`. Default with no flags in
+ * transform pipeline (src/cli/install/pipeline.mjs). Registered runtime
+ * targets are supported via `--<runtime>` flags or `--all`. Default with no
+ * flags in
  * non-TTY mode → `--claude` (backward compat — existing skills invoke
  * `apt-tools init <dir>` with no flags). Default in TTY → interactive prompt
  * with auto-detection markers.
@@ -40,12 +41,13 @@ import { buildAperantGitignoreTemplate } from '../config/upgrade-gitignore.mjs'
 import { detectPublicRemote } from '../git/remote.mjs'
 import { detectArchetype } from '../install/archetype.mjs'
 import { installKernel } from '../install/install-kernel.mjs'
+import { MANIFEST_FILENAME } from '../install/manifest.mjs'
 import {
 	discoverCanonicalFiles,
 	runInstall,
 	writeLastInstallSummary,
 } from '../install/pipeline.mjs'
-import { RUNTIMES, suggestRuntimes } from '../install/runtime-detect.mjs'
+import { getRuntime, RUNTIMES, suggestRuntimes } from '../install/runtime-detect.mjs'
 import { runLegacyCleanup } from '../install/runtime-migrate.mjs'
 import {
 	CLASS_A_SETTINGS,
@@ -392,6 +394,42 @@ function selectRuntimes(targetDir, parsedFlags) {
 	return [...suggested]
 }
 
+/**
+ * Return the runtime ids that should be installed during a no-schema-drift
+ * init. A current config is not enough to prove runtime files exist on this
+ * machine: team repos often carry `.aperant/config.json` but not local
+ * runtime roots/manifests.
+ *
+ * @param {string} targetDir
+ * @param {string[]} runtimeIds
+ * @returns {string[]}
+ */
+function runtimesMissingManifest(targetDir, runtimeIds) {
+	const missing = []
+	for (const id of runtimeIds) {
+		const runtime = getRuntime(id)
+		if (!runtime) continue
+		const manifestPath = join(targetDir, runtime.installRoot, MANIFEST_FILENAME)
+		if (!existsSync(manifestPath)) missing.push(id)
+	}
+	return missing
+}
+
+/**
+ * Current-schema init should still run the runtime installer when the user
+ * explicitly requested runtimes, when --force-runtimes is present, or when
+ * local runtime roots are suggested but have no apt manifest.
+ *
+ * @param {string} targetDir
+ * @param {ReturnType<typeof parseInstallFlags>} parsedFlags
+ * @returns {string[]}
+ */
+function selectNoDriftRuntimeInstallIds(targetDir, parsedFlags) {
+	if (parsedFlags.forceRuntimes) return selectRuntimes(targetDir, parsedFlags)
+	if (parsedFlags.runtimes_explicit) return parsedFlags.runtimes
+	return runtimesMissingManifest(targetDir, suggestRuntimes(targetDir))
+}
+
 /**
  * Non-TTY / scripted path — derive answers from flags + sensible defaults,
  * gated by the Class A/B classifier (spec R2 + R3).
@@ -663,11 +701,16 @@ async function interactiveInterview(targetDir, version, canonicalRoot, archetype
 			migration.applied_defaults.length === 0 &&
 			migration.auto_added.length === 0
 		if (noDrift) {
-			// 0.6.7 (Bug 2 fix) — `--force-runtimes` bypasses the TTY
-			// "Nothing to do." outro so the runtime walker re-stamps every
-			// manifest; cmdInit's force-runtimes synthesis path takes over.
-			if (parsedFlags.forceRuntimes) {
-				return { upgrade_noop: true, skipBootstrap, migration }
+			const runtimeInstallIds = selectNoDriftRuntimeInstallIds(targetDir, parsedFlags)
+			// Runtime repair bypasses the TTY "Nothing to do." outro so the
+			// runtime walker can re-stamp missing manifests first.
+			if (runtimeInstallIds.length > 0) {
+				return {
+					upgrade_noop: true,
+					skipBootstrap,
+					migration,
+					runtime_reinstall_runtimes: runtimeInstallIds,
+				}
 			}
 			process.stdout.write(`\n${aperantBanner(version)}\n\n`)
 			clack.intro('install')
@@ -1158,20 +1201,20 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			)
 		}
 
-		// Upgrade no-drift — short-circuit before installRuntimes.
-		// /apt:update is the right surface for refreshing skills on a
-		// no-drift run; init's job here is to confirm the schema is current.
+		const noDriftRuntimeInstallIds = answers?.upgrade_noop
+			? (answers.runtime_reinstall_runtimes ??
+				selectNoDriftRuntimeInstallIds(installTarget, parsedFlags))
+			: []
+
+		// Upgrade no-drift with no runtime work — short-circuit before
+		// installRuntimes. /apt:update remains the right surface for refreshing
+		// already-manifested skills; init only repairs selected or suggested
+		// runtime roots that lack manifests.
 		// The bootstrap auto-chain still runs (it's deterministic and
 		// idempotent — preserves PROJECT.md, refreshes sidecar from it).
 		// In TTY mode clack already rendered "Nothing to do." to stdout,
 		// so suppress the JSON envelope (matches the cancelled path).
-		//
-		// 0.6.7 (Bug 2 fix) — `--force-runtimes` bypasses this short-circuit
-		// so `/apt:update` can re-stamp every runtime manifest even when
-		// `.aperant/config.json` is at the current schema. We synthesize a
-		// real InstallAnswers shape from the existing config so
-		// installRuntimes + finishInit run their normal upgrade path.
-		if (answers?.upgrade_noop && !parsedFlags.forceRuntimes) {
+		if (answers?.upgrade_noop && noDriftRuntimeInstallIds.length === 0) {
 			if (interactiveTty) return rawText('', 0)
 			const bootstrap = answers.skipBootstrap
 				? { status: 'skipped', reason: '--skip-bootstrap flag' }
@@ -1187,18 +1230,14 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			})
 		}
 
-		// 0.6.7 (Bug 2 fix) — when forceRuntimes is set on a no-drift run,
-		// synthesize a real InstallAnswers shape from the existing config so
-		// the runtime walker re-stamps every manifest. Visibility/autonomy/
-		// cross-verification are read from answers.migration.migrated (already
-		// in memory from nonInteractiveAnswers — avoids a second config read);
-		// runtimes resolved via selectRuntimes helper shared with the upgrade path.
+		// Current-schema runtime install — synthesize a real InstallAnswers
+		// shape from the existing config so installRuntimes + finishInit run
+		// their normal upgrade path.
 		let effectiveAnswers = answers
-		if (answers?.upgrade_noop && parsedFlags.forceRuntimes) {
+		if (answers?.upgrade_noop && noDriftRuntimeInstallIds.length > 0) {
 			const existing = answers.migration?.migrated || {}
-			const runtimes = selectRuntimes(installTarget, parsedFlags)
 			effectiveAnswers = {
-				runtimes,
+				runtimes: noDriftRuntimeInstallIds,
 				autonomyDefault: existing?.autonomy?.default ?? 1,
 				visibility: existing?.share?.visibility === 'team' ? 'team' : 'solo',
 				crossVerificationTools: existing?.multi_model?.cross_verification?.tools ?? [],

package/src/cli/commands/modes.mjs

@@ -54,7 +54,7 @@ const FRONTMATTER_RE = /^---\s*([\s\S]*?)\s*---/
  *
  * @type {Record<string, string[]>}
  */
-const SKILL_CONFIG_KEYS = {
+export const SKILL_CONFIG_KEYS = {
 	'apt:execute': ['coding.tdd_default', 'tdd.iron_law'],
 	'apt:triage': [
 		'task_tracking.backend',
@@ -69,6 +69,9 @@ const SKILL_CONFIG_KEYS = {
 	'apt:ship': ['pipeline.auto_branch', 'pipeline.branch_prefix'],
 	'apt:setup': ['*'], // setup edits config — wildcard surface
 	'apt:run': ['parallelization.enabled', 'parallelization.max_agents'],
+	// FRAMEWORK-BUG-033 capability gap (AC10) — fan-out concurrency cap.
+	// Consumed by the /apt:fan-out SKILL body via cli/config/parallelization.mjs.
+	'apt:fan-out': ['parallelization.max_tasks', 'parallelization.max_agents'],
 }
 
 /**

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

@@ -147,13 +147,24 @@ export function parseFixesAppliedMarkdown(md) {
 	const fixesSection = extractTopLevelSection(md, 'Fixes Applied')
 	const selfReviewerSection = extractTopLevelSection(md, 'Fixes Applied by Self-Reviewer')
 	const skippedSection = extractTopLevelSection(md, 'Skipped')
-	const fixes = [
-		...parseFixEntries(fixesSection),
-		...parseSelfReviewerFixEntries(selfReviewerSection),
-	]
+	const legacyFixerEntries = parseFixEntries(fixesSection)
+	const selfReviewerEntries = parseSelfReviewerFixEntries(selfReviewerSection)
+	// FRAMEWORK-BUG-035: additive `## Fix N` parser path. Scans the whole
+	// document — NOT a `## Fixes Applied` body — so it catches fixer reports
+	// shaped as numbered top-level blocks. Union, not substitution, per spec
+	// ID-03 so legacy `### {ID}` reports keep parsing unchanged.
+	const fixNEntries = parseFixNEntries(md)
+	const fixes = [...legacyFixerEntries, ...selfReviewerEntries, ...fixNEntries]
 	const skipped = parseSkippedEntries(skippedSection)
-	// Detect which heading was present; fixer takes precedence when both appear.
-	const schema = fixesSection ? 'fixer' : 'self-reviewer'
+	// Schema discriminator: when the ONLY entries came from the `## Fix N`
+	// parser path, label it `'fix-n'` so downstream code / debugging can
+	// tell which shape was on disk. Fall back to existing fixer / self-
+	// reviewer labels when those sections were present.
+	let schema
+	if (fixesSection) schema = 'fixer'
+	else if (selfReviewerSection) schema = 'self-reviewer'
+	else if (fixNEntries.length > 0) schema = 'fix-n'
+	else schema = 'fixer'
 	return { exists: true, fixes, skipped, schema }
 }
 
@@ -237,6 +248,71 @@ function parseFixEntries(section) {
 	return entries
 }
 
+/**
+ * FRAMEWORK-BUG-035 — parse `## Fix N` top-level blocks into entries shaped
+ * like `parseFixEntries` output. The bug narrative documents `## Fix N`
+ * as the canonical shape going forward for fixes-applied-fixer-N.md, but
+ * the legacy `### {ID} — title` parser silently dropped every entry on
+ * those reports, surfacing `<none parsed>` and false-positive flipping
+ * the gate to `hallucinated`.
+ *
+ * This parser scans the WHOLE document (not a `## Fixes Applied` body)
+ * because the new shape uses `## Fix N` directly as top-level headers.
+ * Finding-ID extraction priority chain (per spec ID-04):
+ *   1. `- **Finding ID**:` field line
+ *   2. `- **Fix**:`        field line
+ *   3. `- **ID**:`         field line
+ *   4. synthetic `fix-N`   fallback (matches `parseSelfReviewerFixEntries`'s
+ *      `self-reviewer-fix-N` convention; the diff-intersect step in
+ *      `decideVerdict` is the real check, not the id)
+ *
+ * Returns the same `{id, title, file, files, verification}` shape as
+ * `parseFixEntries` so downstream consumers see a uniform array.
+ */
+function parseFixNEntries(markdown) {
+	if (!markdown) return []
+	const entries = []
+	// `^## Fix N$` — top-level heading with the literal word "Fix" + a
+	// number. No trailing description in the header (the canonical shape
+	// per the BUG-034 narrative puts the description inside the body).
+	const headerRx = /^##\s+Fix\s+(\d+)\s*$/gm
+	const matches = [...markdown.matchAll(headerRx)]
+	for (let i = 0; i < matches.length; i++) {
+		const m = matches[i]
+		const start = m.index + m[0].length
+		// Terminate at the next top-level `## ` heading OR EOF. Mirrors
+		// `extractTopLevelSection`'s body slicing.
+		const rest = markdown.slice(start)
+		const nextTopRx = /\n##\s+/m
+		const nxt = nextTopRx.exec(rest)
+		const body = (nxt ? rest.slice(0, nxt.index) : rest).trim()
+		const findingId = extractFindingIdField(body) ?? `fix-${m[1]}`
+		const files = extractFileFields(body)
+		entries.push({
+			id: findingId,
+			title: null,
+			file: files[0] ?? null,
+			files,
+			verification: extractVerificationField(body),
+		})
+	}
+	return entries
+}
+
+/**
+ * Extract the finding ID from a `## Fix N` block body via the priority
+ * chain documented in `parseFixNEntries`. Returns `null` if no field
+ * matched — caller falls back to the synthetic `fix-N` id.
+ */
+function extractFindingIdField(body) {
+	for (const key of ['Finding ID', 'Fix', 'ID']) {
+		const rx = new RegExp(`-\\s*\\*\\*${key}\\*\\*:\\s*([^\\n]+)`, 'i')
+		const m = rx.exec(body)
+		if (m) return m[1].trim()
+	}
+	return null
+}
+
 function parseSkippedEntries(section) {
 	if (!section) return []
 	const entries = []

package/src/cli/commands/roadmap.mjs

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSy
 import { basename, join, resolve } from 'node:path'
 import { selfStageCommittableWrites } from '../artifacts/self-stage.mjs'
 import { getDefaultOwner, getGitIdentity } from '../git/identity.mjs'
+import { runConvexMirror } from '../roadmap/convex-mirror.mjs'
 import {
 	loadRoadmapForScope as ioLoadRoadmapForScope,
 	saveRoadmapForScope as ioSaveRoadmapForScope,
@@ -41,7 +42,7 @@ class RoadmapUsageError extends UsageError {
 	}
 }
 
-export function cmdRoadmap(subcommand, projectDir, extraArgs) {
+export async function cmdRoadmap(subcommand, projectDir, extraArgs) {
 	if (!subcommand)
 		return err(
 			'Usage: apt-tools roadmap <init|render|add-milestone|add-phase|set-phase-status|rollup|delete-phase|delete-milestone|validate-refs|sync> <project-dir>',
@@ -49,14 +50,14 @@ export function cmdRoadmap(subcommand, projectDir, extraArgs) {
 	if (!projectDir) return err('Usage: apt-tools roadmap ' + subcommand + ' <project-dir>')
 
 	try {
-		return cmdRoadmapImpl(subcommand, projectDir, extraArgs)
+		return await cmdRoadmapImpl(subcommand, projectDir, extraArgs)
 	} catch (e) {
 		if (e instanceof RoadmapUsageError) return err(e.message)
 		throw e
 	}
 }
 
-function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
+async function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 	const targetDir = resolve(projectDir)
 	updateTeamMember(targetDir)
 	const roadmapRoot = join(targetDir, '.aperant', 'roadmap')
@@ -904,9 +905,52 @@ function cmdRoadmapImpl(subcommand, projectDir, extraArgs) {
 			})
 		}
 
+		case 'convex-mirror': {
+			// Slice 5 ST14 / AC10 / ID-06. POSTs the rendered narrator prose
+			// to the Next.js /api/roadmap/narrator-mirror endpoint. Markdown
+			// is canonical (ADR-0006); this call is the Convex mirror.
+			const scope = flags.get('scope')
+			const phaseId = flags.get('phase')
+			const anchorId = flags.get('anchor-id')
+			const prosePath = flags.get('prose-path')
+			const mergedPrRaw = flags.get('merged-pr')
+			if (!scope || !phaseId || !anchorId || !prosePath) {
+				return err(
+					'Usage: apt-tools roadmap convex-mirror <project-dir> --scope <s> --phase <p> --anchor-id <a> --prose-path <file> [--merged-pr <n>]',
+				)
+			}
+			let proseBody = ''
+			try {
+				proseBody = readFileSync(prosePath, 'utf-8')
+			} catch (e) {
+				return err(`prose-path read failed: ${e.message}`)
+			}
+			const mergedPr = mergedPrRaw ? Number(mergedPrRaw) : undefined
+			let result
+			try {
+				result = await runConvexMirror(targetDir, {
+					scope,
+					phaseId,
+					anchorId,
+					proseBody,
+					mergedPr,
+				})
+			} catch (e) {
+				return err(e.message)
+			}
+			if (result.status === 'error') {
+				return err(result.message ?? 'convex-mirror error')
+			}
+			return ok({
+				status: result.status,
+				command: 'roadmap-convex-mirror',
+				message: result.message,
+			})
+		}
+
 		default:
 			return err(
-				`Unknown roadmap subcommand: ${subcommand}. Expected: init, render, add-milestone, add-phase, set-phase-status, delete-phase, delete-milestone, validate-refs, sync`,
+				`Unknown roadmap subcommand: ${subcommand}. Expected: init, render, add-milestone, add-phase, set-phase-status, delete-phase, delete-milestone, validate-refs, sync, convex-mirror`,
 			)
 	}
 }

package/src/cli/commands/task.mjs

@@ -264,6 +264,12 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						roadmap_ref_url: roadmapRefUrl,
 						depends_on: dependsOn,
 						outputs,
+						// FRAMEWORK-BUG-033 defect 2 — durable task→agent ownership.
+						// Defaults to null at create time; fan-out workers (or the
+						// `task update --assigned-to <agent-id>` path) populate it
+						// when they claim the task. Persists across short-lived CLI
+						// invocations unlike team-status/{agentId}.json (pid-keyed).
+						assigned_to: flags.has('assigned-to') ? flags.get('assigned-to') : null,
 						lifecycle_phase: 'planning',
 						history: [],
 						created_at: new Date().toISOString(),
@@ -704,6 +710,7 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						const result = applyLifecyclePhaseSideEffect(
 							targetDir,
 							{
+								id: task.id,
 								scope: task.scope || 'project',
 								milestone_id: task.milestone_id,
 								phase_id: task.phase_id,
@@ -933,6 +940,14 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 						}
 						prUrlForCiWatch = url
 					}
+					// FRAMEWORK-BUG-033 defect 2 — durable task→agent ownership.
+					// Mutable owner field; fan-out workers write
+					// `fanout-${batch}-${task}` on claim, conductor reads to
+					// resolve crash recovery (which worker owned T1 when the
+					// conductor died?).
+					if (flags.has('assigned-to')) {
+						task.assigned_to = flags.get('assigned-to')
+					}
 					if (flags.has('subtasks-total'))
 						task.progress.subtasks_total = parseInt(flags.get('subtasks-total'), 10)
 					if (flags.has('subtasks-completed'))

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

@@ -21,9 +21,12 @@
  *      → dismiss.
  *
  * Mutations are written back in place — the findings markdown gets a
- * new `- **Validation Status**: ${status}` line plus a
- * `### Validation Note` block. The command always exits 0; the caller
- * checks the JSON summary on stdout.
+ * trailing `### Validation Metadata` section per finding carrying
+ * `- **Status**: …` and (optionally) `- **Note**: …` fields (the legacy
+ * field-form `- **Validation Status**:` + `### Validation Note` shape is
+ * still READ for back-compat but never re-emitted — see
+ * FRAMEWORK-BUG-034 in `docs/frameworks/spec-gaps.md`). The command
+ * always exits 0; the caller checks the JSON summary on stdout.
  *
  * Usage:
  *   apt-tools validate-evidence <findings-dir> --worktree <path>
@@ -189,10 +192,25 @@ export function parseFindingsMarkdown(markdown) {
 }
 
 function parseFindingBlock(body, id, title, start, end) {
+	// FRAMEWORK-BUG-034: strip any stamper-emitted Validation Status /
+	// Validation Note / Validation Metadata content from the body BEFORE
+	// extracting fields and evidence. The legacy field-form
+	// `- **Validation Status**: ...` line was bleeding into `fields.evidence`
+	// because the `fieldRx` `\s*` after the empty-value `- **Evidence**:`
+	// marker consumed the newline and grabbed the next line as the field's
+	// value. Stripping pre-parse keeps the parser inputs clean regardless of
+	// whether the file was stamped under the old or new shape. The original
+	// body is preserved for `raw` and for the dual-shape `hasValidationStatus`
+	// detector below.
+	const cleanBody = body
+		.replace(/^-\s*\*\*Validation Status\*\*:[^\n]*\n?/gim, '')
+		.replace(/\n?###\s*Validation Note\s*\n[\s\S]*?(?=\n###|$)/i, '')
+		.replace(/\n?###\s*Validation Metadata\s*\n[\s\S]*?(?=\n###|$)/i, '')
+
 	const fields = {}
 	// `- **File**: \`path:line\`` etc.
 	const fieldRx = /^-\s*\*\*([^*]+)\*\*:\s*(.+)$/gm
-	for (const m of body.matchAll(fieldRx)) {
+	for (const m of cleanBody.matchAll(fieldRx)) {
 		const key = m[1].trim().toLowerCase()
 		fields[key] = m[2].trim()
 	}
@@ -226,7 +244,7 @@ function parseFindingBlock(body, id, title, start, end) {
 	}
 
 	// Description block: everything between `### Description` and the next `###`.
-	const description = extractSection(body, 'Description') ?? ''
+	const description = extractSection(cleanBody, 'Description') ?? ''
 
 	// Evidence code block: first triple-backticked block after `### Evidence`
 	// (specialist shape). BUG-032: validator-consolidated `validated.md`
@@ -234,7 +252,13 @@ function parseFindingBlock(body, id, title, start, end) {
 	// 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') ?? ''
+	//
+	// FRAMEWORK-BUG-034: the `fieldEvidenceRx` fallback below is safe as-is
+	// because the writer no longer emits `- **Validation Status**` field-form
+	// lines (see stampFindings comment) AND `parseFindingBlock` strips any
+	// legacy Status / Validation Note text from `cleanBody` above, so the
+	// regex can no longer trip on the stamper's own output.
+	const evidenceSection = extractSection(cleanBody, 'Evidence') ?? ''
 	let evidence
 	const fenced = /```[^\n]*\n([\s\S]*?)```/.exec(evidenceSection)
 	if (fenced) {
@@ -243,7 +267,7 @@ function parseFindingBlock(body, id, title, start, end) {
 		evidence = evidenceSection
 	} else {
 		const fieldEvidenceRx = /-\s*\*\*Evidence\*\*:\s*(?:\n+)```[^\n]*\n([\s\S]*?)```/i
-		const fieldFenced = fieldEvidenceRx.exec(body)
+		const fieldFenced = fieldEvidenceRx.exec(cleanBody)
 		evidence = fieldFenced ? fieldFenced[1] : (fields.evidence ?? '')
 	}
 
@@ -251,10 +275,10 @@ function parseFindingBlock(body, id, title, start, end) {
 	// Evidence we keep the whole section — snippets AND surrounding
 	// sentences both live here — because file tokens in either form are
 	// legitimate evidence that the fix crosses files.
-	const suggestedFix = extractSection(body, 'Suggested Fix') ?? ''
+	const suggestedFix = extractSection(cleanBody, 'Suggested Fix') ?? ''
 
 	// Line range: Evidence Context -> "Lines examined: a-b"
-	const contextSection = extractSection(body, 'Evidence Context') ?? ''
+	const contextSection = extractSection(cleanBody, 'Evidence Context') ?? ''
 	const rangeMatch = /Lines? examined[^\d]*(\d+)\s*-\s*(\d+)/i.exec(contextSection)
 	const lineRange = rangeMatch
 		? [Number(rangeMatch[1]), Number(rangeMatch[2])]
@@ -266,7 +290,7 @@ function parseFindingBlock(body, id, title, start, end) {
 
 	// Cross-file evidence (optional): `### Cross-File Evidence` block.
 	// Each file gets a `- **File**: path` + fenced snippet.
-	const crossFileSection = extractSection(body, 'Cross-File Evidence') ?? ''
+	const crossFileSection = extractSection(cleanBody, 'Cross-File Evidence') ?? ''
 	const crossFileEvidence = []
 	const crossFileRx = /-\s*\*\*File\*\*:\s*`?([^`\n]+?)`?\s*\n+```[^\n]*\n([\s\S]*?)```/g
 	for (const m of crossFileSection.matchAll(crossFileRx)) {
@@ -287,7 +311,14 @@ function parseFindingBlock(body, id, title, start, end) {
 		description,
 		suggestedFix,
 		crossFileEvidence,
-		hasValidationStatus: /\*\*Validation Status\*\*/i.test(body),
+		// FRAMEWORK-BUG-034: detection broadened to recognize BOTH the new
+		// `### Validation Metadata` section (the post-fix writer shape) AND
+		// the legacy `- **Validation Status**:` field-form (back-compat for
+		// any validated.md on disk written before the fix). The flag name
+		// stays `hasValidationStatus` for callers; see spec.md ID-01 for the
+		// "renamed conceptually" rationale.
+		hasValidationStatus:
+			/###\s*Validation Metadata/i.test(body) || /\*\*Validation Status\*\*/i.test(body),
 	}
 }
 
@@ -537,51 +568,45 @@ export function checkFinding(finding, worktreeRoot, opts = {}) {
 }
 
 /**
- * Rewrite a findings markdown in place, stamping each finding with
- * `- **Validation Status**: …` + a `### Validation Note` block.
+ * Rewrite a findings markdown in place, stamping each finding with a
+ * trailing `### Validation Metadata` section carrying Status + Note.
+ *
+ * FRAMEWORK-BUG-034 (2026-05-19, PR #208): the previous writer emitted
+ * `- **Validation Status**:` as a field-form line. The fieldRx in
+ * `parseFindingBlock` (`/^-\s*\*\*([^*]+)\*\*:\s*(.+)$/gm`) lets `\s*`
+ * consume the newline after the empty-value `- **Evidence**:` field,
+ * so on a re-read the inserted Status line is captured as
+ * `fields.evidence` and the literal-substring step dismisses 28/32
+ * findings citing the writer's own stamp as the missing source line.
+ *
+ * Fix shape (per spec.md ID-01): WRITER always emits ONLY the new
+ * `### Validation Metadata` heading shape — the `###` shape can't fall
+ * into the field-cluster regex, so the self-reference loop can't form.
+ * READER side (`parseFindingBlock`) supports BOTH the new section AND
+ * the legacy field-form so any older validated.md on disk still
+ * round-trips. See spec.md ID-01 + ID-02 for the dual-shape rationale.
  */
 function stampFindings(markdown, decisions) {
 	// Work from the end so earlier edits don't shift later offsets.
 	let out = markdown
 	for (let i = decisions.length - 1; i >= 0; i--) {
 		const { finding, decision } = decisions[i]
-		// If the finding already has a Validation Status line, replace
-		// the value; otherwise inject before the first `### Description`
-		// (or at end of body if no such heading).
-		const block = out.slice(finding.start, finding.end)
-		let newBlock
-		if (finding.hasValidationStatus) {
-			newBlock = block.replace(
-				/-\s*\*\*Validation Status\*\*:\s*[^\n]*/i,
-				`- **Validation Status**: ${decision.status}`,
-			)
-			// Replace the note block too, if any.
-			if (decision.note) {
-				if (/###\s*Validation Note/i.test(newBlock)) {
-					newBlock = newBlock.replace(
-						/###\s*Validation Note\s*\n[\s\S]*?(?=\n###|$)/i,
-						`### Validation Note\n${decision.note}\n`,
-					)
-				} else {
-					newBlock = `${newBlock.replace(/\s*$/, '')}\n\n### Validation Note\n${decision.note}\n`
-				}
-			}
-		} else {
-			// Insert "- **Validation Status**: ..." right after the first
-			// `- **...**:` field block.
-			const lastFieldRx = /((?:^-\s*\*\*[^*]+\*\*:.*(?:\n|$))+)/m
-			const match = lastFieldRx.exec(block)
-			const insertion = `- **Validation Status**: ${decision.status}\n`
-			if (match) {
-				const insertAt = match.index + match[0].length
-				newBlock = block.slice(0, insertAt) + insertion + block.slice(insertAt)
-			} else {
-				newBlock = `${block.replace(/\s*$/, '')}\n${insertion}`
-			}
-			if (decision.note) {
-				newBlock = `${newBlock.replace(/\s*$/, '')}\n\n### Validation Note\n${decision.note}\n`
-			}
-		}
+		let block = out.slice(finding.start, finding.end)
+
+		// Strip any legacy field-form Validation Status line. Multiple lines
+		// possible if a previous buggy re-run left several stamps; replaceAll-
+		// style global match keeps this idempotent.
+		block = block.replace(/^-\s*\*\*Validation Status\*\*:[^\n]*\n?/gim, '')
+		// Strip any legacy `### Validation Note` block.
+		block = block.replace(/\n?###\s*Validation Note\s*\n[\s\S]*?(?=\n###|$)/i, '')
+		// Strip any prior `### Validation Metadata` section so we can
+		// re-emit fresh values (idempotency across re-runs, spec ID-02).
+		block = block.replace(/\n?###\s*Validation Metadata\s*\n[\s\S]*?(?=\n###|$)/i, '')
+
+		const lines = [`### Validation Metadata`, `- **Status**: ${decision.status}`]
+		if (decision.note) lines.push(`- **Note**: ${decision.note}`)
+		const section = `${lines.join('\n')}\n`
+		const newBlock = `${block.replace(/\s*$/, '')}\n\n${section}`
 		out = out.slice(0, finding.start) + newBlock + out.slice(finding.end)
 	}
 	return out