@aperant/framework 0.19.0 → 0.20.0

package/src/cli/features/surface-map.mjs

@@ -0,0 +1,192 @@
+/**
+ * surface-map.mjs — feature-surface qualification + area suggestion for the
+ * features-reconcile delta ledger (replaces registry-audit.mjs's
+ * `detectFeatureKind`/`inferArea`).
+ *
+ * Dependency-free: node:-builtins only (in fact, zero imports) — this module
+ * sits inside the bare-node CI entry's import closure (ID-08).
+ *
+ * THE MAPPING TABLE (ID-06) — this header IS the contract:
+ *
+ * | Path family                                                        | kind             | area resolution                                    |
+ * |--------------------------------------------------------------------|------------------|----------------------------------------------------|
+ * | packages/ui/src/sections/<a>/** /*.tsx                             | ui-component     | alias(<a>) — deterministic                          |
+ * | packages/ui/src/{components,design-system}/** /*.tsx               | ui-component     | 'chrome' (existing precedent in chrome.json)        |
+ * | packages/ui/src/hooks/use-*.ts{,x}                                 | hook             | token-match against known areas, else null          |
+ * | apps/desktop/src/renderer/src/** /*.tsx                            | ui-component     | token-match (features/settings/** → settings), else null |
+ * | apps/web/src/app/<seg>/**                                          | ui-component     | alias(<seg>) when it names a known area, else null  |
+ * | apps/desktop/src/main/ipc-handlers/*.ts                            | ipc-channel      | token-match (inbox-*-handlers → inbox), else null   |
+ * | packages/backend/convex/** /*.ts                                   | backend-function | token-match, else null                              |
+ * | packages/core/src/{services,pipeline,workflows,providers,inbox,terminal,credentials}/** /*.ts | core-service | first path segment / token-match, else null |
+ *
+ * Exclusions (always, checked BEFORE any family match): test files
+ * (`\.(test|spec)\.`), `__tests__/` dirs, `.stories.` files, `_generated/`
+ * dirs.
+ *
+ * Area rules:
+ *   - AREA_ALIASES = { terminal: 'terminals', conductor: 'showrunner' } is
+ *     applied at EVERY resolution site.
+ *   - `hooks` / `ipc` / `services` are NEVER emitted as areas (the junk-drawer
+ *     failure mode is structurally impossible) — they are filtered even if a
+ *     caller supplies them in `knownAreas`.
+ *   - `area: null` means "the writer agent must assign it" — `--check` and
+ *     `--write` fail closed on a null area.
+ *   - Token-match compares path tokens (split on `/ - _ .`) against the
+ *     caller-supplied `knownAreas` list, alias-normalized, with a simple
+ *     plural tolerance (`competitor` matches `competitors`).
+ */
+
+export const AREA_ALIASES = Object.freeze({
+	terminal: 'terminals',
+	conductor: 'showrunner',
+})
+
+/** Pseudo-areas that must never be suggested (retired junk drawers). */
+const JUNK_AREAS = new Set(['hooks', 'ipc', 'services'])
+
+/** Apply the alias map to a raw area token. */
+export function applyAreaAlias(area) {
+	if (typeof area !== 'string') return area
+	return AREA_ALIASES[area] ?? area
+}
+
+/**
+ * Always-on exclusions: test files, __tests__ dirs, storybook stories,
+ * generated code.
+ */
+export function isExcludedPath(norm) {
+	if (/\.(test|spec)\./.test(norm)) return true
+	if (/(^|\/)__tests__\//.test(norm)) return true
+	if (/\.stories\./.test(norm)) return true
+	if (/(^|\/)_generated\//.test(norm)) return true
+	return false
+}
+
+/**
+ * Normalize the caller-supplied known-area list: strings only, junk areas
+ * dropped (they are never legal suggestions even if a stale file exists).
+ */
+function normalizeKnownAreas(knownAreas) {
+	const out = new Set()
+	for (const a of knownAreas || []) {
+		if (typeof a !== 'string' || !a) continue
+		if (JUNK_AREAS.has(a)) continue
+		out.add(a)
+	}
+	return out
+}
+
+/**
+ * Token-match a set of path tokens against the known-area set.
+ * A token `t` matches area `a` when alias(t) === a or alias(t) + 's' === a.
+ * Returns the first matching area (token order), or null.
+ */
+function tokenMatchArea(tokens, knownSet) {
+	for (const raw of tokens) {
+		if (!raw) continue
+		const t = applyAreaAlias(raw.toLowerCase())
+		if (JUNK_AREAS.has(t)) continue
+		if (knownSet.has(t)) return t
+		if (knownSet.has(`${t}s`)) return `${t}s`
+	}
+	return null
+}
+
+/**
+ * Split a path fragment into candidate tokens: segments, kebab/underscore/dot
+ * parts, and camelCase words (convex files are camelCase — roadmapItems.ts).
+ */
+function tokenize(fragment) {
+	const tokens = []
+	for (const seg of fragment.split('/')) {
+		if (!seg) continue
+		tokens.push(seg)
+		for (const part of seg.split(/[-_.]/)) {
+			if (!part) continue
+			if (part !== seg) tokens.push(part)
+			for (const camel of part.split(/(?=[A-Z])/)) {
+				if (camel && camel !== part) tokens.push(camel)
+			}
+		}
+	}
+	return tokens
+}
+
+/**
+ * Qualify a repo-relative file path as a feature surface.
+ *
+ * @param {string} filepath — repo-relative path (posix or win separators)
+ * @param {string[]} [knownAreas] — existing registry area names (callers pass
+ *   the `.aperant/features/*.json` basenames); used only for token-match
+ *   families. Deterministic families (sections, design-system) need none.
+ * @returns {{ kind: string, suggestedArea: string | null } | null}
+ *   null when the path does not qualify at all.
+ */
+export function qualifiesAsFeatureSurface(filepath, knownAreas = []) {
+	if (!filepath || typeof filepath !== 'string') return null
+	const norm = filepath.replace(/\\/g, '/').replace(/^\.\//, '')
+	if (isExcludedPath(norm)) return null
+	const knownSet = normalizeKnownAreas(knownAreas)
+
+	// packages/ui/src/sections/<a>/**/*.tsx → ui-component, alias(<a>) deterministic
+	let m = /^packages\/ui\/src\/sections\/([^/]+)\/.+\.tsx$/.exec(norm)
+	if (m) {
+		const area = applyAreaAlias(m[1])
+		return { kind: 'ui-component', suggestedArea: JUNK_AREAS.has(area) ? null : area }
+	}
+
+	// packages/ui/src/{components,design-system}/**/*.tsx → ui-component, chrome
+	if (/^packages\/ui\/src\/(components|design-system)\/.+\.tsx$/.test(norm)) {
+		return { kind: 'ui-component', suggestedArea: 'chrome' }
+	}
+
+	// packages/ui/src/hooks/use-*.ts{,x} → hook, token-match
+	m = /^packages\/ui\/src\/hooks\/(use-[A-Za-z0-9-]+)\.tsx?$/.exec(norm)
+	if (m) {
+		const tokens = tokenize(m[1]).filter((t) => t !== 'use')
+		return { kind: 'hook', suggestedArea: tokenMatchArea(tokens, knownSet) }
+	}
+
+	// apps/desktop/src/renderer/src/**/*.tsx → ui-component, token-match
+	m = /^apps\/desktop\/src\/renderer\/src\/(.+)\.tsx$/.exec(norm)
+	if (m) {
+		return { kind: 'ui-component', suggestedArea: tokenMatchArea(tokenize(m[1]), knownSet) }
+	}
+
+	// apps/web/src/app/<seg>/** → ui-component, alias(<seg>) when known
+	m = /^apps\/web\/src\/app\/([^/]+)\/.+\.tsx?$/.exec(norm)
+	if (m) {
+		const seg = applyAreaAlias(m[1])
+		const area = !JUNK_AREAS.has(seg) && knownSet.has(seg) ? seg : null
+		return { kind: 'ui-component', suggestedArea: area }
+	}
+
+	// apps/desktop/src/main/ipc-handlers/*.ts → ipc-channel, token-match
+	m = /^apps\/desktop\/src\/main\/ipc-handlers\/([^/]+)\.ts$/.exec(norm)
+	if (m) {
+		return { kind: 'ipc-channel', suggestedArea: tokenMatchArea(tokenize(m[1]), knownSet) }
+	}
+
+	// packages/backend/convex/**/*.ts → backend-function, token-match
+	m = /^packages\/backend\/convex\/(.+)\.ts$/.exec(norm)
+	if (m) {
+		return { kind: 'backend-function', suggestedArea: tokenMatchArea(tokenize(m[1]), knownSet) }
+	}
+
+	// packages/core/src/{services,pipeline,workflows,providers,inbox,terminal,credentials}/**/*.ts
+	// → core-service; first path segment / token-match.
+	m =
+		/^packages\/core\/src\/(services|pipeline|workflows|providers|inbox|terminal|credentials)\/(.+)\.ts$/.exec(
+			norm,
+		)
+	if (m) {
+		// The family segment itself is the first candidate token (pipeline →
+		// pipeline, terminal → terminals via alias, inbox → inbox); junk
+		// segments (services) and non-area segments (workflows, providers,
+		// credentials) fall through to token-match on the rest of the path.
+		const tokens = [m[1], ...tokenize(m[2])]
+		return { kind: 'core-service', suggestedArea: tokenMatchArea(tokens, knownSet) }
+	}
+
+	return null
+}

package/src/cli/features/write-root.mjs

@@ -0,0 +1,140 @@
+/**
+ * write-root.mjs — BUG-025b worktree write-redirect resolution (ID-11).
+ *
+ * Moved verbatim from the retired legacy audit command so the mutating
+ * features-reconcile verbs (--draft / --write) keep the exact 4-layer
+ * behaviour: registry writes historically leaked generated `*.json` into main
+ * when the executor invoked the CLI from a worktree-isolated task. The fix
+ * applies a 4-step resolution order (see resolveWriteRoot below):
+ *   (1) cwd IS a worktree root → write there (current behaviour)
+ *   (2) --task-id maps to an active non-terminal worktree task →
+ *       redirect writes to that worktree's `.aperant/features/`
+ *   (3) multiple active worktree-isolated tasks + no --task-id → error
+ *   (4) `--no-worktree-redirect` opt-out preserves layer (1) behaviour
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
+
+const TERMINAL_PHASES = new Set(['completed', 'cancelled', 'closed', 'shipped', 'merged'])
+
+/**
+ * BUG-025b — resolve where the mutating features-reconcile verbs should write.
+ * See module header for the 4-step order. Returns `{ writeRoot, redirect_notice }`
+ * on success or a synthetic error envelope (`{ error: { ... } }`) on the
+ * ambiguous-worktree case.
+ *
+ * @internal — exported for unit testing.
+ *
+ * @param {{projectDir: string, taskId?: string | null, noRedirect?: boolean}} args
+ * @returns {{writeRoot?: string, redirect_notice?: string | null, error?: {kind: string, message: string, active_worktree_tasks: string[]}}}
+ */
+export function resolveWriteRoot({ projectDir, taskId, noRedirect }) {
+	const root = resolve(projectDir)
+	if (noRedirect === true) {
+		return { writeRoot: root, redirect_notice: null }
+	}
+	// Layer (1): cwd IS a worktree root. Worktrees have `git rev-parse
+	// --git-dir` != `git rev-parse --git-common-dir`. Falling through to
+	// the existing behaviour writes to this worktree's .aperant/features.
+	// Fast path: git sets GIT_DIR and GIT_COMMON_DIR in the environment
+	// when running inside a worktree hook context — if both are set and
+	// differ, we are in a worktree. This env-var check is ONLY valid at
+	// Layer (1) where we ask "is this process in a worktree?"; it must
+	// NOT be used to validate an untrusted external path (Layer 2 below).
+	const envDir = process.env.GIT_DIR
+	const envCommonDir = process.env.GIT_COMMON_DIR
+	if (envDir && envCommonDir) {
+		if (resolve(envDir) !== resolve(envCommonDir)) {
+			return { writeRoot: root, redirect_notice: null }
+		}
+	} else if (isWorktreeRoot(root)) {
+		return { writeRoot: root, redirect_notice: null }
+	}
+	// Layer (2): --task-id maps to an active non-terminal worktree-isolated
+	// task → redirect.
+	const stateActive = readActiveTasks(root)
+	if (taskId) {
+		const task = stateActive[taskId]
+		if (
+			task &&
+			!TERMINAL_PHASES.has(task.lifecycle_phase) &&
+			typeof task.worktree_path === 'string' &&
+			existsSync(task.worktree_path)
+		) {
+			const resolvedWorktree = resolve(task.worktree_path)
+			const worktreesDir = resolve(root, '.aperant', 'worktrees') + sep
+			const isUnderProject = resolvedWorktree.startsWith(root + sep) || resolvedWorktree === root
+			const isUnderWorktrees = resolvedWorktree.startsWith(worktreesDir)
+			// Accept only paths under the project root, under .aperant/worktrees/,
+			// or confirmed as a real git worktree by git itself. Rejects arbitrary
+			// paths injected via a tampered state.json while preserving test
+			// fixtures that use ad-hoc worktree paths outside the project tree.
+			if (!isUnderProject && !isUnderWorktrees && !isWorktreeRoot(resolvedWorktree)) {
+				return { writeRoot: root, redirect_notice: null }
+			}
+			return {
+				writeRoot: resolvedWorktree,
+				redirect_notice: `features-reconcile redirected writes to worktree ${resolvedWorktree} (--task-id ${taskId})`,
+			}
+		}
+	}
+	// Layer (3): multiple active worktree-isolated tasks AND no --task-id
+	// → actionable error. Single-worktree case is OK to default to root
+	// (the executor will set up the worktree's registry on first scan).
+	const activeWorktreeTasks = Object.entries(stateActive).filter(([_id, t]) => {
+		return (
+			t &&
+			!TERMINAL_PHASES.has(t.lifecycle_phase) &&
+			typeof t.worktree_path === 'string' &&
+			existsSync(t.worktree_path)
+		)
+	})
+	if (!taskId && activeWorktreeTasks.length > 1) {
+		return {
+			error: {
+				kind: 'ambiguous-worktree-context',
+				message: 'ambiguous worktree context; pass --task-id <id> or --no-worktree-redirect',
+				active_worktree_tasks: activeWorktreeTasks.map(([id]) => id),
+			},
+		}
+	}
+	// Default: current behaviour (write into cwd).
+	return { writeRoot: root, redirect_notice: null }
+}
+
+export function isWorktreeRoot(projectDir) {
+	try {
+		const dirRes = spawnSync('git', ['rev-parse', '--git-dir'], {
+			cwd: projectDir,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		const commonRes = spawnSync('git', ['rev-parse', '--git-common-dir'], {
+			cwd: projectDir,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
+		if (dirRes.status !== 0 || commonRes.status !== 0) return false
+		return (dirRes.stdout || '').trim() !== (commonRes.stdout || '').trim()
+	} catch {
+		return false
+	}
+}
+
+export function readActiveTasks(projectDir) {
+	// state-fork-fix: read the AUTHORITATIVE main board — readActiveTasks finds
+	// each task's worktree_path for the BUG-025b feature-write redirect, so it
+	// MUST read main or the redirect-target lookup itself forks. (The feature
+	// WRITE path / resolveWriteRoot stays untouched.)
+	const statePath = join(resolveMainRepoRoot(projectDir), '.aperant', 'state.json')
+	if (!existsSync(statePath)) return {}
+	try {
+		const parsed = JSON.parse(readFileSync(statePath, 'utf-8'))
+		return parsed?.active_tasks ?? {}
+	} catch {
+		return {}
+	}
+}

package/src/cli/gate/gates/features-reconciled.mjs

@@ -0,0 +1,70 @@
+/**
+ * @internal
+ * features-reconciled — blocking gate for `apt:ship` (ID-10).
+ *
+ * Runs the features-reconcile 4-clause checker IN-PROCESS (no shell-out)
+ * against the task's worktree (when present), verifying the write-then-verify
+ * ordering: apt-ship §0.0 materializes pending deltas BEFORE the §0 gate
+ * check reaches this gate.
+ *
+ * Deliberately has NO applies_to_profile — unlike verify-approved /
+ * review-clean, this gate runs under BOTH profiles so QUICK/DEBUG-shipped PRs
+ * are covered too (per gate/registry.mjs, omitting applies_to_profile means
+ * the gate applies universally).
+ *
+ * Deliberately returns NO inputs[] — the deltas/receipts/area dir contents
+ * are dynamic and the check is cheap, so the verdict is never cached.
+ */
+
+import { existsSync } from 'node:fs'
+import { checkReconciled, draftRepairCommand } from '../../features/reconcile.mjs'
+import { registerGate } from '../registry.mjs'
+
+const gate = {
+	id: 'features-reconciled',
+	description: 'feature-registry deltas reconciled (coverage + schema + integrity + no orphans)',
+	severity: 'blocking',
+	skills: ['ship'],
+	async check(ctx) {
+		const worktree = ctx.taskRecord?.worktree_path
+		const checkRoot =
+			typeof worktree === 'string' && worktree && existsSync(worktree) ? worktree : ctx.sharedRoot
+		const base = ctx.taskRecord?.base_branch ?? 'main'
+		let result
+		try {
+			result = checkReconciled({ root: checkRoot, base, taskId: ctx.taskId })
+		} catch (e) {
+			return {
+				status: 'fail',
+				reason: `features-reconcile check threw: ${e.message}`,
+				evidence: { checkRoot, base },
+			}
+		}
+		if (result.status === 'skip') {
+			return {
+				status: 'skip',
+				reason: `features-reconcile skipped: ${result.reason} (docs_policy opt-out)`,
+				evidence: { checkRoot, policy: result.policy ?? null },
+			}
+		}
+		if (result.status === 'ok') {
+			return {
+				status: 'pass',
+				reason: `feature registry reconciled (${result.qualifying_files?.length ?? 0} qualifying file(s) covered; schema valid)`,
+				evidence: { checkRoot, base: result.base },
+			}
+		}
+		const findings = result.findings ?? []
+		return {
+			status: 'fail',
+			reason:
+				`feature registry NOT reconciled — ${findings.length} finding(s). ` +
+				`Repair: ${draftRepairCommand(ctx.taskId)} (fill dispositions), then ` +
+				`node packages/framework/bin/apt-tools.mjs features-reconcile . --write --task-id ${ctx.taskId}`,
+			evidence: { checkRoot, base: result.base, findings },
+		}
+	},
+}
+
+registerGate(gate)
+export default gate

package/src/cli/gate/gates/index.mjs

@@ -18,6 +18,7 @@ import './verify-approved.mjs'
 import './review-clean.mjs'
 import './followups-adjudicated.mjs'
 import './gitignore-in-sync.mjs'
+import './features-reconciled.mjs'
 import './consistency-check.mjs'
 import './tdd-iron-law.mjs'
 import './r-persona-alignment.mjs'

package/src/cli/help.mjs

@@ -38,7 +38,7 @@ Commands:
   task close-merged <dir> [--task <id>] [--narrate-only] [--dry-run]   Sweep shipped-pending-merge tasks for confirmed merges (--narrate-only returns pending_narration[] entries read-only without closing).
   task narration-drain <dir> --task <task-id>     Remove a row from state.pending_narration[] under withFileLock (called by /apt:close-task --narrate-only after a successful narrator spawn)
   task complete-subtask <dir> --task-id <id> --subtask-id <sid|a+b+c> [--commit <sha>] [--notes <text>]  Atomic plan ↔ build-progress sync
-  features-audit <dir> [--task-id <id>] [--no-worktree-redirect] [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files (BUG-025b: --task-id redirects writes to active task's worktree)
+  features-reconcile <dir> (--draft|--write|--check|--gc) [--task-id <id>] [--subtask-id <id>] [--base <ref>] [--dry-run] [--warn-only] [--max-age-days <n>] [--no-worktree-redirect]  Feature-registry delta ledger: --draft scaffolds a per-writer delta from the base..HEAD diff, --write materializes deltas into area JSONs + a receipt, --check verifies coverage/schema/integrity/orphans, --gc prunes merged receipts (BUG-025b: --task-id redirects writes to active task's worktree)
   docs-audit <dir> [--diff-files <csv>|--since <ref>|--dry-run] [--policy <path>] [--format json|md]  Audit documented surfaces for docs-drift
 
   lock claim <dir> --subtask <id>       Claim exclusive lock on a subtask

package/src/cli/release-notes/ship-autodraft.mjs

@@ -6,8 +6,8 @@
  * should grow a `Release note: …` line OR ship should block.
  *
  * This module is intentionally pure — the apt-ship SKILL.md body shells
- * `apt-tools features-audit . --diff-since <base> --json` and feeds the
- * envelope here. Keeping the decision pure makes TD-4 trivial: fixture in,
+ * `apt-tools features-reconcile . --draft --dry-run --base "$base"` and feeds
+ * the envelope here. Keeping the decision pure makes TD-4 trivial: fixture in,
  * decision out, no I/O.
  */
 

package/src/cli/variant/gallery.mjs

@@ -12,6 +12,10 @@
  *     no privilege for that).  Picking happens by running a terminal
  *     command — the gallery's job is to make the letter obvious and the
  *     command copy-pasteable.
+ *   - Each card links to its variant file via a plain relative anchor
+ *     with target="_blank", so the user can open any variant full-size
+ *     in a new tab straight from the gallery (relative hrefs resolve
+ *     against the gallery's own file:// URL — no server needed).
  *   - Responsive grid: 1 column on narrow, 2 on medium, N on wide.
  *   - Each variant iframe is rendered at full device-width-feel, not a
  *     thumbnail, so the user can actually read the content.
@@ -80,11 +84,11 @@ export function renderGallery(input) {
 				`              <div class="truncate text-xs text-slate-400">${description}</div>`,
 				'            </div>',
 				'          </div>',
-				`          <code class="shrink-0 rounded bg-slate-800 px-2 py-1 text-xs text-slate-300">${filename}</code>`,
+				`          <a href="${filename}" target="_blank" rel="noopener" title="Open variant ${letter} in a new tab" class="shrink-0 rounded bg-slate-800 px-2 py-1 text-xs text-slate-300 hover:bg-slate-700 hover:text-slate-100"><code>${filename}</code> ↗</a>`,
 				'        </header>',
 				`        <iframe src="${filename}" title="Variant ${letter}" loading="lazy" class="block h-[720px] w-full bg-white"></iframe>`,
 				'        <footer class="flex items-center justify-between gap-3 border-t border-slate-800 px-4 py-3">',
-				`          <div class="text-xs text-slate-500">Pick this one:</div>`,
+				`          <a href="${filename}" target="_blank" rel="noopener" class="text-xs font-medium ${ACCENT} hover:underline">Open full size ↗</a>`,
 				`          <code class="rounded bg-slate-800 px-2 py-1 text-xs text-slate-100">/apt:mockup --pick ${letter.toLowerCase()}</code>`,
 				'        </footer>',
 				'      </article>',
@@ -112,7 +116,7 @@ export function renderGallery(input) {
 		'        <div>',
 		`          <div class="text-xs uppercase tracking-[0.2em] text-slate-500">Variant gallery · iteration ${iterationEsc}</div>`,
 		`          <h1 class="mt-1 text-2xl font-semibold text-slate-100">${featureEsc}</h1>`,
-		`          <p class="mt-1 text-sm text-slate-400">${variants.length} parallel generations. Open this page via <code>file://</code>, scan the iframes, pick the letter that lands.</p>`,
+		`          <p class="mt-1 text-sm text-slate-400">${variants.length} parallel generations. Open this page via <code>file://</code>, scan the iframes, click “Open full size” to view any variant in its own tab, then pick the letter that lands.</p>`,
 		'        </div>',
 		'        <div class="flex flex-col gap-2 text-xs text-slate-400 sm:items-end">',
 		`          <div>Directory: <code class="text-slate-300">${taskDirEsc}/mockups/</code></div>`,

package/templates/aperant-claude-md-appendix.md

@@ -23,9 +23,9 @@ The feature registry (`.aperant/features/`) is a living inventory of every inter
 feature in the app. It's the source of truth for what to verify and review.
 
 - **Created by:** `/apt:scan` (initial scan or full refresh)
-- **Updated by:** `/apt:execute` post-step (`apt-tools features-audit --apply-stubs` auto-registers new UI/core/hook/IPC files per the docs-coherence policy)
+- **Updated by:** per-writer DELTAS committed with the work (`apt-tools features-reconcile --draft` at the executor/quick/debug commit step), materialized into the area JSONs + a durable receipt by `/apt:ship` §0.0 (`--write`)
 - **Consumed by:** `/apt:verify-proof` (generates test cases from registry)
-- **Checked by:** `/apt:review` Pass 6 (flags unregistered new components, applies stubs for auto-update policies)
+- **Checked by:** the blocking `features-reconciled` ship gate, `/apt:review` Pass 6 (`features-reconcile --check`), and the always-on `features-reconcile` CI check on every PR
 
 Run `/apt:scan` after setting up Aperant on a brownfield project, or after major changes.
 

package/workflows/scan-features.md

@@ -171,7 +171,7 @@ After all agents complete (or at the end of each wave), verify each expected out
    if (!result.success) { /* re-launch with error message */ }
    ```
 4. For orchestrators running in pure-markdown context (no TS runtime), perform a **lightweight structural check**: parse the JSON and verify the top-level keys include `area`, `route`, `components`, `last_scanned`, `features`, and that `features` is an array where each entry has `id`, `name`, `component`, `sub_features`. Flag deviations in the output report.
-5. On validation failure, the orchestrator may: (a) re-launch the agent with the validation error as feedback, OR (b) mark the file as non-conforming and note it in REGISTRY.md. Prefer (a) up to 2 retries, then fall back to (b).
+5. On validation failure, re-launch the agent with the validation error as feedback, up to 2 retries. After 2 failed retries the orchestrator MUST mark the file as **must-fix** in REGISTRY.md (the `## Non-conforming files (must fix)` section) AND report it as a failure line in the final scan output — a non-conforming file is NEVER silently accepted (`features-reconcile --check` clause (b) will fail red on it until fixed).
 </step>
 
 <step name="synthesize_registry">
@@ -283,16 +283,22 @@ Next: /apt:verify-proof {area} — verify features with visual evidence
 
 ### How other skills update the registry
 
-**`/apt:execute` post-step:**
-After completing a task that adds or modifies UI features, the executor should:
-1. Check if `.aperant/features/REGISTRY.md` exists
-2. If yes: read the relevant `{area}.json` file
-3. Add new entries for any features that were created
-4. Update `wired` status for any features that were connected
-5. Update `last_scanned` timestamp
-
-This is a lightweight update — NOT a full rescan. The executor reads its own diff
-to know what changed.
+**`/apt:execute` post-step (delta-emit contract):**
+After each subtask commit, the executor emits a per-writer registry DELTA
+instead of editing area JSONs directly:
+1. `apt-tools features-reconcile . --draft --task-id <id> --subtask-id <sid>`
+   scaffolds `.aperant/features/deltas/<id>-<sid>.json` from the diff.
+2. The executor enriches the scaffold in-window: fills dispositions
+   (`upsert` / `remove` / `wiring-transition` / `no-semantic-change` + reason),
+   assigns any `area: null`, and writes real `sub_features` with
+   `wired`/`handler`/`test_hint`.
+3. The delta is committed with the work; `/apt:ship` §0.0 materializes all
+   pending deltas into the area JSONs + a durable receipt (`--write`), and the
+   `features-reconciled` ship gate + the always-on CI check verify coverage.
+
+This is a lightweight capture — NOT a full rescan. The executor reads its own
+diff to know what changed; area JSONs are only ever written by the
+materializer (or this full-scan workflow).
 
 **`/apt:verify-proof` pre-step:**
 Before generating tests, verify-proof should:

package/dist/cli/cli-wrappers/features-audit.d.mts

@@ -1,2 +0,0 @@
-export { cmdFeaturesAudit as cliFeaturesAudit } from "../commands/features-audit.mjs";
-//# sourceMappingURL=features-audit.d.mts.map

package/dist/cli/cli-wrappers/features-audit.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"features-audit.d.mts","sourceRoot":"","sources":["../../../src/cli/cli-wrappers/features-audit.mjs"],"names":[],"mappings":""}

package/dist/cli/cli-wrappers/features-audit.mjs

@@ -1,8 +0,0 @@
-/**
- * cli-wrappers/features-audit.mjs — Layer 2 wrapper for the features-audit cmd.
- *
- * Today this is a passthrough — DISPATCH calls wrap() directly.
- * Re-exporting keeps the file-per-cmd structural seam.
- */
-export { cmdFeaturesAudit as cliFeaturesAudit } from '../commands/features-audit.mjs';
-//# sourceMappingURL=features-audit.mjs.map

package/dist/cli/cli-wrappers/features-audit.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"features-audit.mjs","sourceRoot":"","sources":["../../../src/cli/cli-wrappers/features-audit.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,IAAI,gBAAgB,EAAE,MAAM,gCAAgC,CAAA"}

package/dist/cli/commands/features-audit.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"features-audit.d.mts","sourceRoot":"","sources":["../../../src/cli/commands/features-audit.mjs"],"names":[],"mappings":"AAoCA;;;;;;;;;;GAUG;AACH,qEAHW;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAC,GAChE;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,qBAAqB,EAAE,MAAM,EAAE,CAAA;KAAC,CAAA;CAAC,CA0E3I;AAoCD,8GAqFC"}