@aperant/framework 0.7.4 → 0.8.0

package/src/cli/ci-watch/stop-matrix.mjs

@@ -5,11 +5,17 @@
  *   { action, counts_toward_budget, reason }
  *
  * No I/O, no fs, no gh CLI shell-outs — caller pre-fetches `checks` (the
- * payload from `gh pr checks --json name,bucket,state,conclusion,detailsUrl`)
+ * payload from `gh pr checks --json name,bucket,state,link,workflow,completedAt`)
  * and `prMetadata` (`gh pr view --json state,reviewDecision`) and passes them
  * in. The orchestrator in commands/ci-watch.mjs handles the side effects
  * implied by the action.
  *
+ * Primary per-check signal is `state` (uppercase per gh-CLI: SUCCESS,
+ * FAILURE, CANCELLED, TIMED_OUT, SKIPPED, IN_PROGRESS, QUEUED, PENDING,
+ * NEUTRAL). The legacy lowercase per-check field that gh dropped circa
+ * 2.65 is kept as a soft fallback for in-memory test fixtures only —
+ * production gh payloads no longer expose it (FRAMEWORK-BUG-016).
+ *
  * Predicate order matters — short-circuits go first (merged/closed/green/cap
  * fire before any per-check inspection). See spec.md §9 table for the full
  * ordering.
@@ -31,8 +37,13 @@ const INFRA_FAILURE_CLASSES = new Set(['runner-oom', 'runner-cancelled', 'gh-5xx
 /**
  * @typedef {Object} CheckRow
  * @property {string} [name]
- * @property {string} [conclusion] e.g. 'success' | 'failure' | 'cancelled' | 'timed_out' | 'neutral'
- * @property {string} [state]
+ * @property {string} [state] Primary per-check status (gh-CLI uppercase enum):
+ *   'SUCCESS' | 'FAILURE' | 'CANCELLED' | 'TIMED_OUT' | 'SKIPPED' |
+ *   'IN_PROGRESS' | 'QUEUED' | 'PENDING' | 'NEUTRAL'.
+ * @property {string} [conclusion] Legacy lowercase per-check field
+ *   (deprecated — gh dropped it from `pr checks --json` schema circa 2.65).
+ *   Retained only as a soft fallback for in-memory test fixtures
+ *   (FRAMEWORK-BUG-016).
  * @property {string} [bucket]
  * @property {string} [failure_class] — optional pre-classified hint (test-only seam)
  * @property {string} [log_fingerprint] — optional digest for identical-log detection
@@ -65,7 +76,16 @@ export function classify({ checks, state, prMetadata }) {
 	}
 
 	const failed = rows.filter((c) => isFailing(c))
-	const allGreen = rows.length > 0 && rows.every((c) => c.conclusion === 'success')
+	// FRAMEWORK-BUG-016: `state` is gh-CLI's primary per-check field post-2.65.
+	// SKIPPED rows (workflow `if:` guards that didn't trip) are
+	// success-equivalent — they intentionally did not run and that is OK.
+	// Soft fallback to the legacy lowercase field keeps the in-memory test
+	// fixtures green (production gh payloads never hit it).
+	const isGreenRow = (c) =>
+		c.state === 'SUCCESS' ||
+		c.state === 'SKIPPED' ||
+		(c.state == null && c.conclusion === 'success')
+	const allGreen = rows.length > 0 && rows.every(isGreenRow)
 
 	// 3. All checks green.
 	if (allGreen) {
@@ -193,6 +213,26 @@ export function classify({ checks, state, prMetadata }) {
 }
 
 export function isFailing(check) {
+	// FRAMEWORK-BUG-016 / BUG-025: prefer the uppercase `state` field that gh
+	// 2.65+ exposes. SKIPPED / NEUTRAL / IN_PROGRESS / QUEUED / PENDING /
+	// SUCCESS are explicitly NOT red — SKIPPED in particular must never
+	// burn a fix attempt (workflow `if:` guards routinely skip jobs on PRs
+	// that don't trip them). The legacy lowercase field is a soft fallback
+	// for in-memory test fixtures only.
+	const s = check.state
+	if (
+		s === 'SUCCESS' ||
+		s === 'SKIPPED' ||
+		s === 'NEUTRAL' ||
+		s === 'IN_PROGRESS' ||
+		s === 'QUEUED' ||
+		s === 'PENDING'
+	) {
+		return false
+	}
+	if (s === 'FAILURE' || s === 'CANCELLED' || s === 'TIMED_OUT') {
+		return true
+	}
 	const c = check.conclusion
 	return c === 'failure' || c === 'cancelled' || c === 'timed_out' || c === 'action_required'
 }

package/src/cli/commands/fan-out.mjs

@@ -0,0 +1,129 @@
+/**
+ * commands/fan-out.mjs — FRAMEWORK-BUG-033 capability gap (ID-04 / ID-05).
+ *
+ * Single resolver helper for the `/apt:fan-out` SKILL body. Three input
+ * forms accepted (`--tasks`, `--phases`, `--unblocked`); all resolve to
+ * the canonical `{task_ids, source, batch_id}` shape. The actual
+ * orchestration loop (worktree create, worker spawn, polling) lives in
+ * the SKILL body — this CLI just materializes the batch.
+ *
+ * Subcommands: `resolve`.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok } from '../util/result.mjs'
+
+const ID_PATTERN = /^[a-z0-9_-]+$/i
+
+function generateBatchId() {
+	const d = new Date()
+	const yyyy = d.getUTCFullYear()
+	const mm = String(d.getUTCMonth() + 1).padStart(2, '0')
+	const dd = String(d.getUTCDate()).padStart(2, '0')
+	const hex = Math.random().toString(16).slice(2, 8)
+	return `fanout-${yyyy}${mm}${dd}-${hex}`
+}
+
+function parseIdList(raw) {
+	if (typeof raw !== 'string') return []
+	return raw
+		.split(',')
+		.map((s) => s.trim())
+		.filter(Boolean)
+}
+
+function readState(targetDir) {
+	const statePath = join(targetDir, '.aperant', 'state.json')
+	if (!existsSync(statePath)) return null
+	try {
+		return JSON.parse(readFileSync(statePath, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+function resolveFromPhases(state, phases) {
+	const wanted = new Set(phases)
+	const ids = []
+	for (const [id, task] of Object.entries(state?.active_tasks || {})) {
+		if (!task) continue
+		const key = `${task.milestone_id ?? ''}/${task.phase_id ?? ''}`
+		if (wanted.has(key) && task.lifecycle_phase !== 'closed') {
+			ids.push(id)
+		}
+	}
+	return ids
+}
+
+function resolveUnblocked(state) {
+	const ids = []
+	for (const [id, task] of Object.entries(state?.active_tasks || {})) {
+		if (task?.lifecycle_phase === 'ready-for-agent') ids.push(id)
+	}
+	return ids
+}
+
+export function cmdFanOut(subcommand, projectDir, extraArgs) {
+	if (!subcommand) {
+		return err(
+			'Usage: apt-tools fan-out <resolve> <project-dir> [--tasks <ids> | --phases <m/p,m/p> | --unblocked]',
+		)
+	}
+	switch (subcommand) {
+		case 'resolve': {
+			if (!projectDir) {
+				return err(
+					'Usage: apt-tools fan-out resolve <project-dir> [--tasks <ids> | --phases <m/p,m/p> | --unblocked]',
+				)
+			}
+			const targetDir = resolve(projectDir)
+			const flags = parseFlags(extraArgs)
+
+			const hasTasks = flags.has('tasks')
+			const hasPhases = flags.has('phases')
+			const hasUnblocked = flags.has('unblocked')
+
+			const inputForms = [hasTasks, hasPhases, hasUnblocked].filter(Boolean).length
+			if (inputForms === 0) {
+				return err('One of --tasks, --phases, or --unblocked is required')
+			}
+			if (inputForms > 1) {
+				return err('Only one of --tasks, --phases, or --unblocked may be passed at a time')
+			}
+
+			let taskIds = []
+			let source = ''
+			if (hasTasks) {
+				taskIds = parseIdList(flags.get('tasks'))
+				source = 'tasks'
+				for (const id of taskIds) {
+					if (!ID_PATTERN.test(id)) {
+						return err(`Invalid task id in --tasks: "${id}" (must match /^[a-z0-9_-]+$/i)`)
+					}
+				}
+			} else if (hasPhases) {
+				const state = readState(targetDir)
+				if (!state) return err('No state.json found — cannot resolve --phases')
+				taskIds = resolveFromPhases(state, parseIdList(flags.get('phases')))
+				source = 'phases'
+			} else {
+				const state = readState(targetDir)
+				if (!state) return err('No state.json found — cannot resolve --unblocked')
+				taskIds = resolveUnblocked(state)
+				source = 'unblocked'
+			}
+
+			return ok({
+				status: 'ok',
+				command: 'fan-out-resolve',
+				source,
+				task_ids: taskIds,
+				batch_id: generateBatchId(),
+			})
+		}
+		default:
+			return err(`Unknown fan-out subcommand: ${subcommand}. Available: resolve`)
+	}
+}

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