@aperant/framework 0.19.0 → 0.20.0

package/src/cli/features/reconcile.mjs

@@ -0,0 +1,1169 @@
+/**
+ * reconcile.mjs — the features-reconcile engine: diff-driven delta drafting,
+ * the 7-step ordered idempotent materializer, the 4-clause read-only checker,
+ * and squash-safe receipt GC.
+ *
+ * DEPENDENCY-FREE (ID-08): this module's import closure is exclusively
+ * node:-builtins + the sibling pure feature modules + docs-audit/policy.mjs
+ * (node:fs/node:path only). It must NEVER import util/io.mjs or
+ * util/atomic-write.mjs (their closure pulls proper-lockfile) — the bare-node
+ * CI entry `bin/features-reconcile-check.mjs` runs with NO node_modules.
+ * A closure-walker test locks this purity.
+ *
+ * TRUST MODEL (ID-04): receipt trust for --check is IN-TREE PRESENCE plus
+ * hash matching — NEVER head-sha ancestry. This repo squash-merges, so branch
+ * heads are never ancestors of main. GC trusts `git cat-file -e
+ * origin/main:<receipt>` presence + a >30d created_at age.
+ */
+
+import { execFileSync } from 'node:child_process'
+import {
+	closeSync,
+	existsSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeSync,
+} from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { loadDocsPolicy, matchSurfaceToPolicy } from '../docs-audit/policy.mjs'
+import { validateAreaShape } from './area-shape.mjs'
+import {
+	CHANGE_KINDS,
+	canonicalJson,
+	DRAFT_ONLY_DISPOSITION,
+	isValidIsoDatetime,
+	mergeDeltas,
+	parseDeltaFile,
+	sha256Bytes,
+	validateDelta,
+} from './delta.mjs'
+import { qualifiesAsFeatureSurface } from './surface-map.mjs'
+
+export const FEATURES_DIR = '.aperant/features'
+export const DELTAS_DIR = `${FEATURES_DIR}/deltas`
+export const RECEIPTS_DIR = `${FEATURES_DIR}/receipts`
+export const MATERIALIZER_VERSION = 1
+
+/** The exact repair command surfaced in every coverage failure. */
+export function draftRepairCommand(taskId) {
+	return `node packages/framework/bin/apt-tools.mjs features-reconcile . --draft --task-id ${taskId || '<task-id>'}`
+}
+const WRITE_REPAIR = 'node packages/framework/bin/apt-tools.mjs features-reconcile . --write'
+
+// ---------------------------------------------------------------------------
+// small pure helpers (no npm deps — see module header)
+// ---------------------------------------------------------------------------
+
+/** tmp+rename atomic JSON write, tab-indented + trailing LF (deterministic bytes). */
+function atomicWriteJsonPure(targetPath, data) {
+	atomicWriteTextPure(targetPath, `${JSON.stringify(data, null, '\t')}\n`)
+}
+
+function atomicWriteTextPure(targetPath, text) {
+	mkdirSync(dirname(targetPath), { recursive: true })
+	const tmpPath = `${targetPath}.tmp.${process.pid}.${Date.now()}`
+	let fd = null
+	try {
+		fd = openSync(tmpPath, 'wx')
+		writeSync(fd, text, 0, 'utf-8')
+		fsyncSync(fd)
+		closeSync(fd)
+		fd = null
+		renameSync(tmpPath, targetPath)
+	} catch (err) {
+		if (fd !== null) {
+			try {
+				closeSync(fd)
+			} catch {
+				/* already closed */
+			}
+		}
+		try {
+			unlinkSync(tmpPath)
+		} catch {
+			/* tmp may not exist */
+		}
+		throw err
+	}
+}
+
+function git(root, args) {
+	try {
+		return execFileSync('git', args, {
+			cwd: root,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		}).trim()
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Resolve the diff base COMMIT. An explicit ref is normalized through
+ * `git merge-base HEAD <ref>` — NOT used verbatim — for two reasons:
+ *   (1) the ship gate / apt-ship pass a base BRANCH (`base_branch: 'main'`);
+ *       once main advances past the fork point, `git diff main..HEAD`
+ *       compares SNAPSHOTS and reports main-side changes reversed (phantom
+ *       modifications/deletions the task never made) → false-red coverage
+ *       findings on every stale branch. merge-base pins the fork point.
+ *   (2) a garbage/unresolvable ref previously flowed into diffNameStatus,
+ *       whose catch returned [] — an EMPTY diff → clause (a) vacuously green
+ *       (fail-open). merge-base fails → null → callers fail CLOSED.
+ * merge-base(HEAD, X) === X whenever X is already an ancestor of HEAD, so the
+ * CI workflow's precomputed merge-base and sha-based callers are byte-identical.
+ * No explicit ref → merge-base HEAD origin/main (local main fallback).
+ */
+export function resolveBase(root, baseFlag) {
+	if (baseFlag && typeof baseFlag === 'string') {
+		return git(root, ['merge-base', 'HEAD', baseFlag])
+	}
+	const originMain = git(root, ['merge-base', 'HEAD', 'origin/main'])
+	if (originMain) return originMain
+	const localMain = git(root, ['merge-base', 'HEAD', 'main'])
+	if (localMain) return localMain
+	return null
+}
+
+/** Blob fingerprint of a path at a rev (`HEAD` or the base). null when absent. */
+function blobAt(root, rev, path) {
+	return git(root, ['rev-parse', `${rev}:${path}`])
+}
+
+/** Parse `git diff --name-status -z base..HEAD` preserving rename pairs. */
+export function diffNameStatus(root, base) {
+	let out
+	try {
+		out = execFileSync('git', ['diff', '--name-status', '-z', `${base}..HEAD`], {
+			cwd: root,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+	} catch {
+		return []
+	}
+	const parts = out.split('\0').filter((p) => p.length > 0)
+	const entries = []
+	for (let i = 0; i < parts.length; ) {
+		const status = parts[i]
+		if (status.startsWith('R') || status.startsWith('C')) {
+			entries.push({ status: status[0], from: parts[i + 1], to: parts[i + 2] })
+			i += 3
+		} else {
+			entries.push({ status: status[0], path: parts[i + 1] })
+			i += 2
+		}
+	}
+	return entries
+}
+
+function listTopLevelAreaFiles(root) {
+	const dir = join(root, FEATURES_DIR)
+	if (!existsSync(dir)) return []
+	return readdirSync(dir, { withFileTypes: true })
+		.filter((d) => d.isFile() && d.name.endsWith('.json'))
+		.map((d) => join(dir, d.name))
+		.sort()
+}
+
+function listDeltaFiles(root) {
+	const dir = join(root, DELTAS_DIR)
+	if (!existsSync(dir)) return []
+	return readdirSync(dir, { withFileTypes: true })
+		.filter((d) => d.isFile() && d.name.endsWith('.json'))
+		.map((d) => join(dir, d.name))
+		.sort()
+}
+
+function listReceiptFiles(root) {
+	const dir = join(root, RECEIPTS_DIR)
+	if (!existsSync(dir)) return []
+	return readdirSync(dir, { withFileTypes: true })
+		.filter((d) => d.isFile() && d.name.endsWith('.json'))
+		.map((d) => join(dir, d.name))
+		.sort()
+}
+
+function readJsonSafe(path) {
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Structural receipt validator (N1): clause (a) coverage and clause (c)
+ * integrity TRUST receipt contents, so a malformed receipt must be EXCLUDED
+ * from trust rather than silently consumed.
+ */
+export function validateReceiptShape(data) {
+	if (!data || typeof data !== 'object' || Array.isArray(data)) return false
+	if (typeof data.head !== 'string' || !data.head) return false
+	if (typeof data.materializer_version !== 'number') return false
+	if (!Array.isArray(data.consumed_delta_hashes)) return false
+	for (const c of data.consumed_delta_hashes) {
+		// A [null] (or path/sha-less) entry would crash the clause-(d) orphan
+		// scan (`c.sha256`) — entries must be {path, sha256} of non-empty strings.
+		if (!c || typeof c !== 'object') return false
+		if (typeof c.path !== 'string' || !c.path) return false
+		if (typeof c.sha256 !== 'string' || !c.sha256) return false
+	}
+	if (!Array.isArray(data.files)) return false
+	for (const f of data.files) {
+		if (!f || typeof f !== 'object') return false
+		if (typeof f.path !== 'string' || !f.path) return false
+		if (!CHANGE_KINDS.includes(f.change)) return false
+		if (typeof f.blob_sha !== 'string' || !f.blob_sha) return false
+	}
+	if (
+		!data.area_hashes ||
+		typeof data.area_hashes !== 'object' ||
+		Array.isArray(data.area_hashes)
+	) {
+		return false
+	}
+	for (const v of Object.values(data.area_hashes)) {
+		if (typeof v !== 'string' || !v) return false
+	}
+	return true
+}
+
+/**
+ * Read every in-tree receipt (newest last by created_at, filename tiebreak).
+ * Malformed receipts are EXCLUDED from the trusted set and surfaced in
+ * `malformed` so --check can fail loudly instead of trusting them (N1).
+ */
+function readReceipts(root) {
+	const receipts = []
+	const malformed = []
+	for (const path of listReceiptFiles(root)) {
+		const data = readJsonSafe(path)
+		if (validateReceiptShape(data)) receipts.push({ path, data })
+		else malformed.push({ path })
+	}
+	receipts.sort((a, b) => {
+		const ca = String(a.data.created_at ?? '')
+		const cb = String(b.data.created_at ?? '')
+		if (ca !== cb) return ca < cb ? -1 : 1
+		return a.path < b.path ? -1 : 1
+	})
+	return { receipts, malformed }
+}
+
+function knownAreaNames(root) {
+	return listTopLevelAreaFiles(root).map((p) => basename(p, '.json'))
+}
+
+function slugify(name) {
+	const slug = name
+		.replace(/\.[a-z]+$/i, '')
+		.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+	return slug || 'feature'
+}
+
+/** Relative path of an absolute file under root (posix separators). */
+function relTo(root, absPath) {
+	return absPath.slice(root.length + 1).replace(/\\/g, '/')
+}
+
+/** docs_policy consult (ID-13): are area-JSON writes allowed? */
+function areaPolicyOptOut(root) {
+	const policy = loadDocsPolicy(root)
+	const probe = matchSurfaceToPolicy(`${FEATURES_DIR}/probe.json`, policy)
+	return probe !== 'auto-update' ? (probe ?? 'unmatched') : null
+}
+
+// ---------------------------------------------------------------------------
+// --draft
+// ---------------------------------------------------------------------------
+
+/**
+ * Scaffold (or idempotently re-scaffold) a per-writer delta from
+ * `git diff --name-status <base>..HEAD`.
+ *
+ * - renames preserved (`change: "renamed"` + previous_path/previous_blob_sha)
+ * - deletions pre-filled `remove` with the BASE blob fingerprint
+ * - additions pre-filled `upsert` + a minimal upsert operation
+ * - modifications marked `needs-disposition` (draft-only sentinel)
+ * - re-runs refresh fingerprints but PRESERVE agent-authored dispositions,
+ *   areas, reasons, and all operations[].
+ *
+ * @param {{root: string, base?: string, taskId?: string, subtaskId?: string, dryRun?: boolean}} opts
+ * @returns {{ ok: boolean, deltaPath?: string, delta?: Record<string, any>, wrote?: boolean,
+ *             qualifying?: number, base?: string, error?: string }}
+ */
+export function draftDelta({ root: rootIn, base: baseFlag, taskId, subtaskId, dryRun = false }) {
+	const root = resolve(rootIn)
+	if (!taskId || typeof taskId !== 'string') {
+		return { ok: false, error: 'draftDelta requires --task-id (the delta path is per-writer)' }
+	}
+	const base = resolveBase(root, baseFlag)
+	if (!base) {
+		return {
+			ok: false,
+			error:
+				'cannot resolve diff base (unresolvable --base ref, or no origin/main / main); pass --base <ref>',
+		}
+	}
+	const known = knownAreaNames(root)
+	const entries = diffNameStatus(root, base)
+	const files = []
+	const autoOps = []
+	for (const entry of entries) {
+		if (entry.status === 'D') {
+			const q = qualifiesAsFeatureSurface(entry.path, known)
+			if (!q) continue
+			files.push({
+				path: entry.path,
+				change: 'deleted',
+				blob_sha: blobAt(root, base, entry.path) ?? '',
+				area: q.suggestedArea,
+				disposition: 'remove',
+			})
+			continue
+		}
+		if (entry.status === 'R' || entry.status === 'C') {
+			const qNew = qualifiesAsFeatureSurface(entry.to, known)
+			if (qNew) {
+				files.push({
+					path: entry.to,
+					change: 'renamed',
+					previous_path: entry.from,
+					previous_blob_sha: blobAt(root, base, entry.from) ?? '',
+					blob_sha: blobAt(root, 'HEAD', entry.to) ?? '',
+					area: qNew.suggestedArea,
+					disposition: DRAFT_ONLY_DISPOSITION,
+				})
+				continue
+			}
+			// Renamed OUT of every qualifying family — the old surface is gone;
+			// treat like a deletion of the previous path.
+			const qOld = qualifiesAsFeatureSurface(entry.from, known)
+			if (qOld) {
+				files.push({
+					path: entry.from,
+					change: 'deleted',
+					blob_sha: blobAt(root, base, entry.from) ?? '',
+					area: qOld.suggestedArea,
+					disposition: 'remove',
+				})
+			}
+			continue
+		}
+		// A / M (and anything else git reports on a surviving path).
+		const q = qualifiesAsFeatureSurface(entry.path, known)
+		if (!q) continue
+		const added = entry.status === 'A'
+		files.push({
+			path: entry.path,
+			change: added ? 'added' : 'modified',
+			blob_sha: blobAt(root, 'HEAD', entry.path) ?? '',
+			area: q.suggestedArea,
+			disposition: added ? 'upsert' : DRAFT_ONLY_DISPOSITION,
+		})
+		if (added && q.suggestedArea) {
+			const featureId = slugify(basename(entry.path))
+			autoOps.push({
+				op: 'upsert',
+				area: q.suggestedArea,
+				feature_id: featureId,
+				value: {
+					id: featureId,
+					name: basename(entry.path),
+					component: entry.path,
+					sub_features: [],
+				},
+			})
+		}
+	}
+
+	const deltaName = subtaskId ? `${taskId}-${subtaskId}.json` : `${taskId}.json`
+	const deltaPath = join(root, DELTAS_DIR, deltaName)
+	let delta = {
+		task_id: taskId,
+		...(subtaskId ? { subtask_id: subtaskId } : {}),
+		base,
+		created_at: new Date().toISOString(),
+		files,
+		operations: autoOps,
+	}
+
+	// Idempotent re-draft: refresh fingerprints, preserve agent enrichment.
+	if (existsSync(deltaPath)) {
+		const prior = readJsonSafe(deltaPath)
+		if (prior && typeof prior === 'object') {
+			const priorFiles = new Map((prior.files ?? []).map((f) => [f.path, f]))
+			const mergedFiles = files.map((fresh) => {
+				const old = priorFiles.get(fresh.path)
+				if (!old) return fresh
+				return {
+					...fresh,
+					// Agent-authored fields survive the re-draft; the draft only
+					// refreshes fingerprints + change kind.
+					area: old.area ?? fresh.area,
+					disposition:
+						old.disposition && old.disposition !== DRAFT_ONLY_DISPOSITION
+							? old.disposition
+							: fresh.disposition,
+					...(old.reason !== undefined ? { reason: old.reason } : {}),
+				}
+			})
+			const priorOps = Array.isArray(prior.operations) ? prior.operations : []
+			const priorOpKeys = new Set(
+				priorOps.map((o) => `${o.op} ${o.area} ${o.feature_id} ${o.sub_feature_id ?? ''}`),
+			)
+			const keptAutoOps = autoOps.filter(
+				(o) => !priorOpKeys.has(`${o.op} ${o.area} ${o.feature_id} ${o.sub_feature_id ?? ''}`),
+			)
+			delta = {
+				...prior,
+				task_id: taskId,
+				...(subtaskId ? { subtask_id: subtaskId } : {}),
+				base,
+				files: mergedFiles,
+				operations: [...priorOps, ...keptAutoOps],
+			}
+		}
+	}
+
+	const validation = validateDelta(delta, { mode: 'draft' })
+	if (!validation.ok) {
+		return { ok: false, error: `draft failed validation: ${validation.errors.join('; ')}` }
+	}
+	if (!dryRun) {
+		if (files.length === 0 && !existsSync(deltaPath)) {
+			// Nothing qualifying and no prior delta — do not write an empty file.
+			return {
+				ok: true,
+				deltaPath: relTo(root, deltaPath),
+				delta,
+				wrote: false,
+				qualifying: 0,
+				base,
+			}
+		}
+		atomicWriteJsonPure(deltaPath, delta)
+	}
+	return {
+		ok: true,
+		deltaPath: relTo(root, deltaPath),
+		delta,
+		wrote: !dryRun && (files.length > 0 || existsSync(deltaPath)),
+		qualifying: files.length,
+		base,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// --write (the ID-03 7-step ordered idempotent materializer)
+// ---------------------------------------------------------------------------
+
+function receiptTimestamp(now) {
+	return now.toISOString().replace(/[-:]/g, '').replace(/\.\d+/, '')
+}
+
+/**
+ * Apply merged operations + files[] bookkeeping to in-memory post-images.
+ * `stampDate` (YYYY-MM-DD) is derived DETERMINISTICALLY from the consumed
+ * deltas' `created_at` (FIX 2 / AC5) — never from wall-clock `now` — so a
+ * crash-before-receipt replay on a LATER day still writes byte-identical
+ * area files.
+ */
+function computePostImages(root, mergedOps, mergedFiles, stampDate) {
+	const areasDir = join(root, FEATURES_DIR)
+	const images = new Map() // area name → { data, touched }
+	const conflicts = []
+	const load = (area) => {
+		if (images.has(area)) return images.get(area)
+		const path = join(areasDir, `${area}.json`)
+		const existing = existsSync(path) ? readJsonSafe(path) : null
+		const data = existing ?? {
+			area,
+			route: '(cross-cutting)',
+			components: [],
+			last_scanned: stampDate,
+			features: [],
+		}
+		if (!Array.isArray(data.features)) data.features = []
+		if (!Array.isArray(data.components)) data.components = []
+		const image = { data, touched: false }
+		images.set(area, image)
+		return image
+	}
+
+	for (const op of mergedOps) {
+		const image = load(op.area)
+		const features = image.data.features
+		const idx = features.findIndex((f) => f?.id === op.feature_id)
+		if (op.op === 'upsert') {
+			if (idx >= 0) features[idx] = op.value
+			else features.push(op.value)
+			image.touched = true
+		} else if (op.op === 'add-group') {
+			if (idx >= 0) {
+				if (canonicalJson(features[idx]) !== canonicalJson(op.value)) {
+					conflicts.push({
+						kind: 'add-group-collision',
+						message: `${op.source ?? ''}: add-group collides with existing divergent group ${op.area}/${op.feature_id}`,
+						sources: [op.source].filter(Boolean),
+					})
+				}
+				// byte-equal existing group → idempotent no-op
+			} else {
+				features.push(op.value)
+				image.touched = true
+			}
+		} else if (op.op === 'patch-sub-feature') {
+			const group = idx >= 0 ? features[idx] : null
+			const sub = group?.sub_features?.find((s) => s?.id === op.sub_feature_id)
+			if (!sub) {
+				conflicts.push({
+					kind: 'patch-missing-entity',
+					message: `${op.source ?? ''}: patch-sub-feature targets missing ${op.area}/${op.feature_id}/${op.sub_feature_id} — ids are never auto-generated (ID-02 g)`,
+					sources: [op.source].filter(Boolean),
+				})
+				continue
+			}
+			Object.assign(sub, op.patch)
+			image.touched = true
+		} else if (op.op === 'remove') {
+			if (op.sub_feature_id) {
+				const group = idx >= 0 ? features[idx] : null
+				if (group?.sub_features) {
+					const before = group.sub_features.length
+					group.sub_features = group.sub_features.filter((s) => s?.id !== op.sub_feature_id)
+					if (group.sub_features.length !== before) image.touched = true
+				}
+			} else if (idx >= 0) {
+				features.splice(idx, 1)
+				image.touched = true
+			}
+			// removing an already-missing entity is an idempotent no-op (replay safety)
+		}
+	}
+
+	// files[] bookkeeping — keep each area's components list current.
+	for (const f of mergedFiles) {
+		if (!f.area) continue
+		const image = load(f.area)
+		const components = image.data.components
+		const ensure = (p) => {
+			if (!components.includes(p)) {
+				components.push(p)
+				image.touched = true
+			}
+		}
+		const drop = (p) => {
+			const i = components.indexOf(p)
+			if (i >= 0) {
+				components.splice(i, 1)
+				image.touched = true
+			}
+		}
+		if (f.change === 'deleted' || f.disposition === 'remove') drop(f.path)
+		else if (f.change === 'renamed') {
+			drop(f.previous_path)
+			if (f.disposition !== 'no-semantic-change') ensure(f.path)
+		} else if (f.disposition === 'upsert' || f.disposition === 'wiring-transition') ensure(f.path)
+	}
+
+	for (const [, image] of images) {
+		if (image.touched) image.data.last_scanned = stampDate
+	}
+	return { images, conflicts }
+}
+
+/**
+ * materialize — the single ordered idempotent writer (ID-03 / AC5):
+ *   (1) parse all deltas → (2) post-images in memory → (3) validate every
+ *   post-image → (4) atomic tmp+rename area replace → (5) write receipt →
+ *   (6) delete ONLY consumed deltas → (7) regenerate REGISTRY.md wholly from
+ *   the JSONs.
+ *
+ * Crash-after-receipt recovery: a re-run detects deltas whose sha256 appears
+ * in an in-tree receipt's consumed_delta_hashes with matching area_hashes and
+ * completes the cleanup without rewriting.
+ *
+ * @returns envelope-ready object; never throws for expected failure classes.
+ */
+export function materialize({ root: rootIn, taskId, now = new Date() }) {
+	const root = resolve(rootIn)
+
+	// ID-13/AC20 — docs_policy opt-out wins before anything is touched.
+	const optOut = areaPolicyOptOut(root)
+	if (optOut) {
+		return { status: 'skip', reason: 'policy-opt-out', policy: optOut }
+	}
+
+	// Crash-after-receipt cleanup (step 5→6 tail): consume-marked deltas whose
+	// receipt's area_hashes still match the on-disk areas are deleted here.
+	const { receipts } = readReceipts(root)
+	const cleanedUp = []
+	let deltaFiles = listDeltaFiles(root)
+	for (const deltaPath of deltaFiles) {
+		let raw
+		try {
+			raw = readFileSync(deltaPath)
+		} catch {
+			continue
+		}
+		const sha = sha256Bytes(raw)
+		const consumingReceipt = receipts.find((r) =>
+			(r.data.consumed_delta_hashes ?? []).some((c) => c.sha256 === sha),
+		)
+		if (!consumingReceipt) continue
+		const areaHashes = consumingReceipt.data.area_hashes ?? {}
+		const allMatch = Object.entries(areaHashes).every(([area, hash]) => {
+			const areaPath = join(root, FEATURES_DIR, `${area}.json`)
+			if (!existsSync(areaPath)) return false
+			return sha256Bytes(readFileSync(areaPath)) === hash
+		})
+		if (allMatch) {
+			unlinkSync(deltaPath)
+			cleanedUp.push(relTo(root, deltaPath))
+		}
+	}
+	deltaFiles = listDeltaFiles(root)
+
+	// Step 1 — parse all deltas fail-closed (strict mode).
+	const parsed = []
+	const invalid = []
+	for (const path of deltaFiles) {
+		const res = parseDeltaFile(path, { mode: 'strict' })
+		if (res.ok) parsed.push({ source: relTo(root, path), path, delta: res.delta })
+		else invalid.push({ path: relTo(root, path), errors: res.errors })
+	}
+	if (invalid.length > 0) {
+		return {
+			status: 'error',
+			kind: 'invalid-deltas',
+			invalid,
+			repair: draftRepairCommand(taskId),
+		}
+	}
+
+	if (parsed.length === 0) {
+		// Zero-delta mode — regenerate REGISTRY.md only; NO receipt. N2:
+		// changed_paths reflects ACTUAL byte changes (a content-identical
+		// regeneration is skipped) so apt-ship §0.0 never attempts an empty
+		// commit.
+		const reg = regenerateRegistryMd(root, now)
+		return {
+			status: 'ok',
+			materialized: 0,
+			receipt: null,
+			consumed_deltas: [],
+			cleaned_up: cleanedUp,
+			registry_regenerated: true,
+			changed_paths: [...(reg.changed ? [relTo(root, reg.path)] : []), ...cleanedUp],
+		}
+	}
+
+	// Step 2a — merge deltas per the ID-02 conflict matrix against the pre-image.
+	const areasDir = join(root, FEATURES_DIR)
+	const lookup = {
+		getFeature: (area, fid) => {
+			const data = readJsonSafe(join(areasDir, `${area}.json`))
+			return data?.features?.find?.((f) => f?.id === fid) ?? null
+		},
+		getSubFeature: (area, fid, sid) => {
+			const data = readJsonSafe(join(areasDir, `${area}.json`))
+			return (
+				data?.features?.find?.((f) => f?.id === fid)?.sub_features?.find?.((s) => s?.id === sid) ??
+				null
+			)
+		},
+	}
+	const mergedRes = mergeDeltas(
+		parsed.map(({ source, delta }) => ({ source, delta })),
+		lookup,
+	)
+	if (!mergedRes.ok) {
+		return {
+			status: 'error',
+			kind: 'hard-conflict',
+			conflicts: mergedRes.conflicts,
+			repair: draftRepairCommand(taskId),
+		}
+	}
+
+	// Step 2b — post-images in memory. The last_scanned stamp derives from the
+	// consumed deltas' created_at (max, sliced to YYYY-MM-DD) — deterministic
+	// under replay (FIX 2 / AC5). Wall-clock `now` is the documented fallback
+	// ONLY when no consumed delta carries created_at (hand-written deltas).
+	const createdAts = parsed
+		.map(({ delta }) => delta.created_at)
+		// Strict validation already enforces real ISO 8601; this SEMANTIC filter
+		// is the belt so a garbage date on a legacy/hand-written delta that
+		// slipped past validation (e.g. 2026-99-99T99:99:99Z — shape-valid,
+		// calendar-invalid) can never max-sort above real dates (ST11).
+		.filter((v) => isValidIsoDatetime(v))
+		.sort()
+	const stampDate =
+		createdAts.length > 0
+			? createdAts[createdAts.length - 1].slice(0, 10)
+			: now.toISOString().slice(0, 10)
+	const { images, conflicts } = computePostImages(
+		root,
+		mergedRes.operations,
+		mergedRes.files,
+		stampDate,
+	)
+	if (conflicts.length > 0) {
+		return { status: 'error', kind: 'hard-conflict', conflicts, repair: draftRepairCommand(taskId) }
+	}
+
+	// Step 3 — validate EVERY post-image before ANY write.
+	const invalidImages = []
+	for (const [area, image] of images) {
+		const res = validateAreaShape(image.data)
+		if (!res.ok) invalidImages.push({ area, errors: res.errors })
+	}
+	if (invalidImages.length > 0) {
+		return { status: 'error', kind: 'invalid-post-image', invalid: invalidImages }
+	}
+
+	// Step 4 — atomic tmp+rename replace of touched area files.
+	const touchedAreas = [...images.entries()].filter(([, image]) => image.touched)
+	for (const [area, image] of touchedAreas) {
+		atomicWriteJsonPure(join(areasDir, `${area}.json`), image.data)
+	}
+
+	// Step 5 — write the receipt (ID-04 shape; fingerprints carried VERBATIM).
+	const areaHashes = {}
+	for (const [area] of touchedAreas) {
+		areaHashes[area] = sha256Bytes(readFileSync(join(areasDir, `${area}.json`)))
+	}
+	const receiptTaskId = taskId || parsed[0].delta.task_id || 'unknown'
+	const receipt = {
+		head: git(root, ['rev-parse', 'HEAD']),
+		materializer_version: MATERIALIZER_VERSION,
+		task_id: receiptTaskId,
+		created_at: now.toISOString(),
+		consumed_delta_hashes: parsed.map(({ source, path }) => ({
+			path: source,
+			sha256: sha256Bytes(readFileSync(path)),
+		})),
+		files: mergedRes.files.map((f) => ({
+			path: f.path,
+			change: f.change,
+			area: f.area,
+			disposition: f.disposition,
+			blob_sha: f.blob_sha,
+			...(f.previous_path !== undefined ? { previous_path: f.previous_path } : {}),
+			...(f.previous_blob_sha !== undefined ? { previous_blob_sha: f.previous_blob_sha } : {}),
+		})),
+		area_hashes: areaHashes,
+	}
+	const receiptName = `${receiptTimestamp(now)}-${receiptTaskId}.json`
+	const receiptPath = join(root, RECEIPTS_DIR, receiptName)
+	atomicWriteJsonPure(receiptPath, receipt)
+
+	// Step 6 — delete ONLY the deltas named in the receipt.
+	for (const { path } of parsed) {
+		unlinkSync(path)
+	}
+
+	// Step 7 — regenerate REGISTRY.md wholly from the JSONs.
+	const reg = regenerateRegistryMd(root, now)
+
+	return {
+		status: 'ok',
+		materialized: touchedAreas.length,
+		areas: touchedAreas.map(([area]) => area),
+		receipt: relTo(root, receiptPath),
+		consumed_deltas: parsed.map(({ source }) => source),
+		cleaned_up: cleanedUp,
+		registry_regenerated: true,
+		changed_paths: [
+			...touchedAreas.map(([area]) => `${FEATURES_DIR}/${area}.json`),
+			relTo(root, receiptPath),
+			...(reg.changed ? [relTo(root, reg.path)] : []),
+			...parsed.map(({ source }) => source),
+			...cleanedUp,
+		],
+	}
+}
+
+/** Wired-state buckets for the REGISTRY.md table. */
+function tallyArea(data) {
+	let groups = 0
+	let subs = 0
+	let wired = 0
+	let stubbed = 0
+	let unwired = 0
+	for (const group of data.features ?? []) {
+		groups += 1
+		for (const sub of group?.sub_features ?? []) {
+			subs += 1
+			if (sub?.wired === true) wired += 1
+			else if (sub?.wired === 'stubbed' || sub?.wired === 'partial') stubbed += 1
+			else unwired += 1
+		}
+	}
+	return { groups, subs, wired, stubbed, unwired }
+}
+
+/**
+ * Regenerate REGISTRY.md WHOLLY from the area JSONs (never patched in place).
+ * Non-conforming files are listed loudly — never silently skipped.
+ *
+ * @returns {{ path: string, changed: boolean }} — `changed:false` when the
+ *   regeneration was content-identical (timestamp line ignored) and the
+ *   existing file was kept byte-for-byte (N2).
+ */
+export function regenerateRegistryMd(root, now = new Date()) {
+	const rows = []
+	const nonConforming = []
+	const totals = { groups: 0, subs: 0, wired: 0, stubbed: 0, unwired: 0 }
+	for (const path of listTopLevelAreaFiles(root)) {
+		const name = basename(path, '.json')
+		const data = readJsonSafe(path)
+		const valid = data ? validateAreaShape(data) : { ok: false, errors: ['unparseable JSON'] }
+		if (!valid.ok) {
+			nonConforming.push({ name, errors: valid.errors })
+			continue
+		}
+		const t = tallyArea(data)
+		totals.groups += t.groups
+		totals.subs += t.subs
+		totals.wired += t.wired
+		totals.stubbed += t.stubbed
+		totals.unwired += t.unwired
+		rows.push({ name, route: data.route, last_scanned: data.last_scanned, ...t })
+	}
+	rows.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+	const pct = (n, d) => (d > 0 ? `${Math.round((n / d) * 100)}%` : '—')
+	const lines = [
+		'# Feature Registry',
+		'',
+		`Last reconciled: ${now.toISOString()}`,
+		'Regenerated wholly from `.aperant/features/*.json` by `apt-tools features-reconcile --write`.',
+		'Schema: `@aperant/framework/schemas` → `FeatureRegistrySchema` (zod-validated; twin: `area-shape.mjs`)',
+		'',
+		'## Areas',
+		'',
+		'| Area | Route | Groups | Sub-features | Wired | Stubbed | Unwired | Wired % |',
+		'|------|-------|-------:|-------------:|------:|--------:|--------:|--------:|',
+		...rows.map(
+			(r) =>
+				`| ${r.name} | \`${r.route}\` | ${r.groups} | ${r.subs} | ${r.wired} | ${r.stubbed} | ${r.unwired} | ${pct(r.wired, r.subs)} |`,
+		),
+		`| **TOTAL** | | **${totals.groups}** | **${totals.subs}** | **${totals.wired}** | **${totals.stubbed}** | **${totals.unwired}** | **${pct(totals.wired, totals.subs)}** |`,
+		'',
+		'## Coverage Summary',
+		'',
+		`- **Total feature areas:** ${rows.length}`,
+		`- **Total feature groups:** ${totals.groups}`,
+		`- **Total sub-features:** ${totals.subs}`,
+		`- **Wired (connected to backend):** ${totals.wired} / ${totals.subs}`,
+		`- **Stubbed / partial:** ${totals.stubbed} / ${totals.subs}`,
+		`- **Unwired (pure mock/display-only):** ${totals.unwired} / ${totals.subs}`,
+	]
+	if (nonConforming.length > 0) {
+		lines.push('', '## Non-conforming files (must fix)', '')
+		for (const nc of nonConforming) {
+			lines.push(
+				`- \`${nc.name}.json\` — ${nc.errors[0]}${nc.errors.length > 1 ? ` (+${nc.errors.length - 1} more)` : ''}`,
+			)
+		}
+	}
+	lines.push(
+		'',
+		'## Files',
+		'',
+		...rows.map((r) => `- \`${r.name}.json\` — last_scanned ${r.last_scanned}`),
+		'',
+	)
+	const registryPath = join(root, FEATURES_DIR, 'REGISTRY.md')
+	const next = lines.join('\n')
+	// N2: skip a content-identical regeneration (ignoring only the
+	// `Last reconciled:` timestamp line) so callers can report REAL byte
+	// changes and apt-ship §0.0 never attempts an empty commit.
+	const TS_LINE = /^Last reconciled: .*$/m
+	if (existsSync(registryPath)) {
+		const prior = readFileSync(registryPath, 'utf-8')
+		if (prior.replace(TS_LINE, '') === next.replace(TS_LINE, '')) {
+			return { path: registryPath, changed: false }
+		}
+	}
+	atomicWriteTextPure(registryPath, next)
+	return { path: registryPath, changed: true }
+}
+
+// ---------------------------------------------------------------------------
+// --check (the ID-05 read-only 4-clause verifier)
+// ---------------------------------------------------------------------------
+
+/**
+ * checkReconciled — four read-only clauses (AC7/AC8). Judges ONLY base..HEAD
+ * deltas — never absolute registry completeness. Trust = in-tree presence +
+ * blob-fingerprint matching (squash-safe; NO git ancestry calls anywhere).
+ *
+ * @returns {Record<string, any>} envelope-ready result: status ('ok'|'fail'|
+ *   'warn'|'skip'), findings[], coverage_ok, schema_valid, integrity_ok,
+ *   orphans_ok, base, qualifying_files, pending_deltas, receipts.
+ */
+export function checkReconciled({ root: rootIn, base: baseFlag, warnOnly = false, taskId }) {
+	const root = resolve(rootIn)
+
+	const optOut = areaPolicyOptOut(root)
+	if (optOut) {
+		return { status: 'skip', reason: 'policy-opt-out', policy: optOut, findings: [] }
+	}
+
+	const findings = []
+	const base = resolveBase(root, baseFlag)
+
+	// Pending deltas: strict-parse. An invalid pending delta (incl. the
+	// needs-disposition sentinel) is itself a failure — it can never cover.
+	const deltaFiles = listDeltaFiles(root)
+	const pendingDeltas = []
+	for (const path of deltaFiles) {
+		const res = parseDeltaFile(path, { mode: 'strict' })
+		if (res.ok) {
+			pendingDeltas.push({ path, delta: res.delta })
+		} else {
+			findings.push({
+				clause: 'coverage',
+				file: relTo(root, path),
+				message: `invalid pending delta: ${res.errors.join('; ')}`,
+				repair: draftRepairCommand(taskId),
+			})
+		}
+	}
+	const { receipts, malformed } = readReceipts(root)
+	// N1: a malformed receipt is EXCLUDED from coverage/integrity/orphan trust
+	// and surfaced as a finding — never silently consumed.
+	for (const m of malformed) {
+		findings.push({
+			clause: 'receipts',
+			file: relTo(root, m.path),
+			message:
+				'malformed receipt (missing head/materializer_version/files fingerprints/area_hashes/consumed_delta_hashes) — excluded from coverage and integrity',
+			repair: `re-materialize via ${WRITE_REPAIR} or remove the malformed receipt`,
+		})
+	}
+
+	// Clause (a) — disposition coverage over base..HEAD, fingerprint-matched.
+	const listings = []
+	for (const { path, delta } of pendingDeltas) {
+		for (const f of delta.files ?? []) listings.push({ ...f, from: relTo(root, path) })
+	}
+	for (const r of receipts) {
+		for (const f of r.data.files ?? []) listings.push({ ...f, from: relTo(root, r.path) })
+	}
+	const known = knownAreaNames(root)
+	const qualifying = []
+	if (base) {
+		for (const entry of diffNameStatus(root, base)) {
+			if (entry.status === 'D') {
+				if (qualifiesAsFeatureSurface(entry.path, known)) {
+					qualifying.push({
+						path: entry.path,
+						requiredBlob: blobAt(root, base, entry.path),
+						kind: 'deleted',
+					})
+				}
+			} else if (entry.status === 'R' || entry.status === 'C') {
+				if (qualifiesAsFeatureSurface(entry.to, known)) {
+					qualifying.push({
+						path: entry.to,
+						requiredBlob: blobAt(root, 'HEAD', entry.to),
+						kind: 'current',
+					})
+				} else if (qualifiesAsFeatureSurface(entry.from, known)) {
+					qualifying.push({
+						path: entry.from,
+						requiredBlob: blobAt(root, base, entry.from),
+						kind: 'deleted',
+					})
+				}
+			} else if (qualifiesAsFeatureSurface(entry.path, known)) {
+				qualifying.push({
+					path: entry.path,
+					requiredBlob: blobAt(root, 'HEAD', entry.path),
+					kind: 'current',
+				})
+			}
+		}
+	} else {
+		findings.push({
+			clause: 'coverage',
+			file: '(repo)',
+			message:
+				'cannot resolve diff base (unresolvable --base ref, or no origin/main / main); pass --base <ref>',
+			repair: 'features-reconcile . --check --base <ref>',
+		})
+	}
+	for (const q of qualifying) {
+		// FIX 1: the covering listing must be KIND-COMPATIBLE, never just
+		// path+blob. A prior receipt's HEAD-blob listing would otherwise cover
+		// a DELETION in the next PR (that receipt's HEAD blob === this PR's
+		// base blob). Rules:
+		//   - kind 'deleted'  → only a deletion listing (change 'deleted' or
+		//     disposition 'remove') with blob_sha === the BASE blob covers;
+		//   - kind 'current'  → only a NON-deleted listing (added/modified/
+		//     renamed — the qualifying builder emits renames as 'current' on
+		//     the NEW path, mirrored here) with blob_sha === the HEAD blob.
+		const covered = listings.some((l) => {
+			if (l.path !== q.path || !q.requiredBlob || l.blob_sha !== q.requiredBlob) return false
+			if (q.kind === 'deleted') return l.change === 'deleted' || l.disposition === 'remove'
+			// 'current': any NON-deleted listing (a remove-DISPOSITION on a
+			// still-existing file is a deregistration, not a deletion — its
+			// HEAD-anchored blob legitimately covers the edit).
+			return l.change !== 'deleted'
+		})
+		if (!covered) {
+			findings.push({
+				clause: 'coverage',
+				file: q.path,
+				message: `feature-qualifying change has no covering delta or receipt with a matching blob fingerprint (${q.kind === 'deleted' ? 'base blob' : 'HEAD blob'})`,
+				repair: draftRepairCommand(taskId),
+			})
+		}
+	}
+
+	// Clause (b) — schema validity of every top-level area JSON.
+	let schemaValid = true
+	for (const path of listTopLevelAreaFiles(root)) {
+		const data = readJsonSafe(path)
+		const res = data ? validateAreaShape(data) : { ok: false, errors: ['unparseable JSON'] }
+		if (!res.ok) {
+			schemaValid = false
+			findings.push({
+				clause: 'schema',
+				file: relTo(root, path),
+				message:
+					res.errors.slice(0, 3).join('; ') +
+					(res.errors.length > 3 ? ` (+${res.errors.length - 3} more)` : ''),
+				repair: 'fix the area file so it passes FeatureRegistrySchema (see area-shape.mjs)',
+			})
+		}
+	}
+
+	// Clause (c) — per-area LATEST-receipt integrity, only when NO deltas pending.
+	let integrityOk = true
+	if (pendingDeltas.length === 0 && deltaFiles.length === 0 && receipts.length > 0) {
+		for (const path of listTopLevelAreaFiles(root)) {
+			const area = basename(path, '.json')
+			// The latest receipt whose area_hashes names THIS area — validating
+			// only the globally newest receipt would leave other areas unchecked.
+			const latest = [...receipts]
+				.reverse()
+				.find((r) => r.data.area_hashes && area in r.data.area_hashes)
+			if (!latest) continue // pre-receipt legacy area — exempt
+			const recorded = latest.data.area_hashes[area]
+			const current = sha256Bytes(readFileSync(path))
+			if (recorded !== current) {
+				integrityOk = false
+				findings.push({
+					clause: 'integrity',
+					file: relTo(root, path),
+					message: `area file bytes differ from its latest receipt (${basename(latest.path)}) — manual edit after materialization?`,
+					repair: `${draftRepairCommand(taskId)} then ${WRITE_REPAIR}`,
+				})
+			}
+		}
+	}
+
+	// Clause (d) — no orphan consumed deltas (crash-tail state).
+	let orphansOk = true
+	for (const path of deltaFiles) {
+		let sha
+		try {
+			sha = sha256Bytes(readFileSync(path))
+		} catch {
+			continue
+		}
+		const consumed = receipts.some((r) =>
+			(r.data.consumed_delta_hashes ?? []).some((c) => c.sha256 === sha),
+		)
+		if (consumed) {
+			orphansOk = false
+			findings.push({
+				clause: 'orphans',
+				file: relTo(root, path),
+				message: 'delta already consumed by an in-tree receipt but still on disk (crash tail)',
+				repair: WRITE_REPAIR,
+			})
+		}
+	}
+
+	const coverageFindings = findings.filter((f) => f.clause === 'coverage')
+	const ok = findings.length === 0
+	return {
+		status: ok ? 'ok' : warnOnly ? 'warn' : 'fail',
+		base,
+		qualifying_files: qualifying.map((q) => q.path),
+		pending_deltas: pendingDeltas.length,
+		receipts: receipts.length,
+		coverage_ok: coverageFindings.length === 0,
+		schema_valid: schemaValid,
+		integrity_ok: integrityOk,
+		orphans_ok: orphansOk,
+		findings,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// --gc (squash-safe receipt GC)
+// ---------------------------------------------------------------------------
+
+/**
+ * gcReceipts — prune ONLY receipts that (1) exist on origin/main AND (2) are
+ * older than maxAgeDays by created_at. A fetch failure degrades to a warned
+ * NO-OP — never a deletion.
+ */
+export function gcReceipts({ root: rootIn, maxAgeDays = 30, now = new Date() }) {
+	const root = resolve(rootIn)
+	try {
+		execFileSync('git', ['fetch', 'origin', 'main'], {
+			cwd: root,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+		})
+	} catch {
+		return {
+			status: 'ok',
+			pruned: [],
+			kept: listReceiptFiles(root).length,
+			warning: 'git fetch origin main failed — gc is a no-op',
+		}
+	}
+	const cutoffMs = now.getTime() - maxAgeDays * 24 * 60 * 60 * 1000
+	const pruned = []
+	let kept = 0
+	for (const path of listReceiptFiles(root)) {
+		const rel = relTo(root, path)
+		const data = readJsonSafe(path)
+		const createdAt = data?.created_at ? Date.parse(data.created_at) : Number.NaN
+		const oldEnough = Number.isFinite(createdAt) && createdAt < cutoffMs
+		let onMain = false
+		try {
+			execFileSync('git', ['cat-file', '-e', `origin/main:${rel}`], {
+				cwd: root,
+				stdio: ['ignore', 'ignore', 'ignore'],
+			})
+			onMain = true
+		} catch {
+			onMain = false
+		}
+		if (oldEnough && onMain) {
+			unlinkSync(path)
+			pruned.push(rel)
+		} else {
+			kept += 1
+		}
+	}
+	return { status: 'ok', pruned, kept }
+}