@aperant/framework 0.17.0 → 0.20.0

package/src/cli/produce/verification-ttl.mjs

@@ -0,0 +1,191 @@
+/**
+ * @internal
+ * produce/verification-ttl.mjs — verification-TTL: a rotating sample of OLD done
+ * milestones re-verified against HEAD each tick, regressions flagged +
+ * compensated (M4, ID-M4-03 / AC13).
+ *
+ * Verification is not permanent — a milestone marked `done` at HEAD-sha `A` can
+ * silently regress as HEAD advances to `B` (a later milestone's change breaks an
+ * earlier one). This module gives verification a TTL:
+ *
+ *   - `selectTtlReverifySample` REUSES M2's `selectSweepSample` for the rotating
+ *     done-milestone candidates (do NOT invent a parallel rotation) and annotates
+ *     staleness against the supplied HEAD sha — a done milestone is STALE when its
+ *     last recorded `produce.ttl.reverified`/`produce.probe.run` head_sha ≠ the
+ *     current HEAD (or it has never been re-verified since done); a milestone last
+ *     re-verified against the current HEAD is EXCLUDED as FRESH.
+ *   - `recordTtlReverify` REUSES the M2 cross-family guard (refuses a same-family
+ *     re-verify), appends `produce.ttl.reverified`, and on `fail` ALSO appends
+ *     `produce.ttl.regression_detected` AND fires the FORWARD compensator via
+ *     saga.mjs::compensatePhase({phase:'verify'}) — a revert-branch + reopen +
+ *     re-plan, NEVER a merged-PR rollback (ID-M4-03).
+ *
+ * `ttl.reverified` is a DISTINCT op from `probe.run` (a scheduled post-`done` TTL
+ * re-check vs a first-time done-gate probe) so the forensic trail stays clean —
+ * only the ROTATION and the CROSS-FAMILY GUARD are reused. This module records +
+ * computes; the actual re-verify RUN + the revert-ship/reopen/re-plan EXECUTION
+ * is the OOS dispatch layer.
+ */
+
+import { selectSweepSample } from './blind-probe.mjs'
+import {
+	appendProduceEvent,
+	readImplementerFamily,
+	readProduceRunEventsMatching,
+} from './events.mjs'
+import { normalizeFamily } from './probe-family.mjs'
+import { projectRoadmap } from './projection.mjs'
+import { compensatePhase } from './saga.mjs'
+
+/**
+ * Build the per-milestone latest-recorded head_sha map from the
+ * `produce.ttl.reverified` + `produce.probe.run` events (both carry `head_sha`).
+ * Chronological fold — the last recorded run for a milestone wins.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {Map<string, { head_sha: string, at: string | null }>}
+ */
+function latestReverifyByMilestone(projectDir, runId) {
+	const events = readProduceRunEventsMatching(
+		projectDir,
+		runId,
+		(op) => op === 'produce.ttl.reverified' || op === 'produce.probe.run',
+	)
+	const map = new Map()
+	for (const e of events) {
+		const d = e.data || {}
+		const id = typeof d.milestone_id === 'string' ? d.milestone_id : null
+		const sha = typeof d.head_sha === 'string' ? d.head_sha : null
+		if (!id || !sha) continue
+		map.set(id, { head_sha: sha, at: typeof e.t === 'string' ? e.t : null })
+	}
+	return map
+}
+
+/**
+ * Select a DETERMINISTIC rotating sample of already-`done` milestones STALE
+ * against HEAD (ID-M4-03 / AC7). REUSES `selectSweepSample` for the rotation
+ * order (fewest/oldest last-probe-run first), then annotates each candidate with
+ * staleness against `headSha` and FILTERS OUT the FRESH ones (last re-verified
+ * against the current HEAD). Returns the first `sample` STALE candidates. An
+ * absent HEAD sha fails closed (nothing selected).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {{ headSha: string, sample?: number }} args
+ * @returns {{ run_id: string, head_sha: string | null, sample_size: number,
+ *   selected: Array<{ milestone_id: string, title: string, last_reverify_head_sha: string | null, last_reverify_at: string | null, stale: boolean }> }}
+ */
+export function selectTtlReverifySample(projectDir, runId, { headSha, sample = 1 } = {}) {
+	if (!headSha) return { run_id: runId, head_sha: null, sample_size: 0, selected: [] }
+
+	// The FULL rotation-ordered pool of done milestones (reuse selectSweepSample;
+	// pass the done count so it returns every done milestone in rotation order).
+	const doneCount = projectRoadmap(projectDir, runId).milestones.filter(
+		(m) => m.status === 'done',
+	).length
+	const pool = selectSweepSample(projectDir, runId, { sample: doneCount || 1 }).selected
+
+	const latest = latestReverifyByMilestone(projectDir, runId)
+	const n = Number.isFinite(sample) && sample > 0 ? Math.floor(sample) : 1
+
+	const stale = []
+	for (const candidate of pool) {
+		const last = latest.get(candidate.milestone_id) || null
+		// STALE when never re-verified since done, or last re-verified against a sha
+		// ≠ the current HEAD. FRESH (last re-verify head_sha === HEAD) is excluded.
+		const isStale = !last || last.head_sha !== headSha
+		if (!isStale) continue
+		stale.push({
+			milestone_id: candidate.milestone_id,
+			title: candidate.title,
+			last_reverify_head_sha: last?.head_sha ?? null,
+			last_reverify_at: last?.at ?? null,
+			stale: true,
+		})
+	}
+
+	const selected = stale.slice(0, n)
+	return { run_id: runId, head_sha: headSha, sample_size: selected.length, selected }
+}
+
+/**
+ * Record a scheduled TTL re-verify RUN against HEAD (ID-M4-03). REUSES the M2
+ * cross-family guard (refuses a same-family re-verify, or when no implementer
+ * family is recorded). Appends `produce.ttl.reverified {run_id, milestone_id,
+ * head_sha, result}`; on `result === 'fail'` ALSO appends
+ * `produce.ttl.regression_detected` AND fires the FORWARD compensator via
+ * saga.mjs::compensatePhase({phase:'verify', reason:'ttl_regression@<sha>'}) — a
+ * revert-branch + reopen + re-plan, NEVER a merged-PR rollback. A `pass`
+ * refreshes verification against the new HEAD and logs no regression.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, result: string, probeFamily: string, headSha: string }} args
+ * @returns {{ ok: true, result: string, probe_family: string, head_sha: string, regression: boolean, compensator: object | null }
+ *   | { ok: false, reason: string }}
+ */
+export function recordTtlReverify(
+	projectDir,
+	{ runId, milestoneId, result, probeFamily, headSha },
+) {
+	if (result !== 'pass' && result !== 'fail') return { ok: false, reason: 'invalid_result' }
+	if (!headSha) return { ok: false, reason: 'no_head_sha' }
+	if (!probeFamily) return { ok: false, reason: 'no_probe_family' }
+
+	const implementerFamily = readImplementerFamily(projectDir, runId, milestoneId)
+	if (!implementerFamily) return { ok: false, reason: 'no_recorded_implementer' }
+	// Cross-family enforcement (normalized so claude-code === claude).
+	if (normalizeFamily(probeFamily) === normalizeFamily(implementerFamily))
+		return { ok: false, reason: 'same_family_reverify' }
+
+	appendProduceEvent(projectDir, 'produce.ttl.reverified', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		head_sha: headSha,
+		result,
+	})
+
+	let regression = false
+	let compensator = null
+	if (result === 'fail') {
+		// The regression flags the milestone AND fires the FORWARD compensator — a
+		// revert-branch + reopen + re-plan, never a merged-PR rollback (ID-M4-03).
+		appendProduceEvent(projectDir, 'produce.ttl.regression_detected', {
+			run_id: runId,
+			milestone_id: milestoneId,
+			head_sha: headSha,
+		})
+		const comp = compensatePhase(projectDir, {
+			runId,
+			milestoneId,
+			phase: 'verify',
+			reason: `ttl_regression@${headSha}`,
+		})
+		regression = true
+		compensator = comp.ok ? comp.compensator : null
+	}
+
+	return { ok: true, result, probe_family: probeFamily, head_sha: headSha, regression, compensator }
+}
+
+/**
+ * Read-only fold of the run's `produce.ttl.regression_detected` events (for saga
+ * status / canary context). Chronological order.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {Array<{ milestone_id: string | null, head_sha: string | null, t: string | null }>}
+ */
+export function listRegressions(projectDir, runId) {
+	const events = readProduceRunEventsMatching(
+		projectDir,
+		runId,
+		(op) => op === 'produce.ttl.regression_detected',
+	)
+	return events.map((e) => ({
+		milestone_id: e.data && typeof e.data.milestone_id === 'string' ? e.data.milestone_id : null,
+		head_sha: e.data && typeof e.data.head_sha === 'string' ? e.data.head_sha : null,
+		t: typeof e.t === 'string' ? e.t : null,
+	}))
+}

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/roadmap/showrunner-view.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type declarations for the .mjs showrunner-view helper.
+ * Hand-authored — the import path points at src/.mjs directly.
+ */
+
+export interface ShowrunnerRoadmapView {
+	scopes: Array<{ scope: string; roadmap: unknown }>
+}
+
+export function buildShowrunnerRoadmapView(projectRoot: string): ShowrunnerRoadmapView

package/src/cli/roadmap/{conductor-view.mjs → showrunner-view.mjs}

@@ -1,26 +1,26 @@
 /**
- * conductor-view.mjs — read-only roadmap surface for the Aperant
- * Conductor's `getRoadmap` tool.
+ * showrunner-view.mjs — read-only roadmap surface for the Aperant
+ * Showrunner's `getRoadmap` tool.
  *
- * Wraps `loadRoadmapForScope` + `listRoadmapScopes` so the Conductor sees
+ * Wraps `loadRoadmapForScope` + `listRoadmapScopes` so the Showrunner sees
  * the same overlay-aware view every framework command sees. Direct reads
  * of `.aperant/roadmap/*\/phases/*.json` or `milestones.json` would miss
  * the dual-write overlay (seed_id from legacy blob, etc.) — Codex
  * roundtable correction #3.
  *
- * Step 5 of Conductor v2 ship order.
+ * Step 5 of Showrunner v2 ship order.
  */
 
 import { loadRoadmapForScope } from './io.mjs'
 import { listRoadmapScopes } from './paths.mjs'
 
 /**
- * Build a flat per-scope roadmap snapshot for the Conductor.
+ * Build a flat per-scope roadmap snapshot for the Showrunner.
  *
  * @param {string} projectRoot
  * @returns {{ scopes: Array<{ scope: string, roadmap: unknown }> }}
  */
-export function buildConductorRoadmapView(projectRoot) {
+export function buildShowrunnerRoadmapView(projectRoot) {
 	const scopes = listRoadmapScopes(projectRoot)
 	const out = []
 	for (const scope of scopes) {

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"}

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

@@ -1,293 +0,0 @@
-/**
- * commands/features-audit.mjs — CLI entry point for the features-registry
- * audit (C33).
- *
- * Modes:
- *   - report only (default): print `new_components`, `unregistered`, `stub_patches`
- *   - `--apply-stubs`:        additionally write the stub patches to disk.
- *                             This is what the /apt:execute post-step calls.
- *
- * Diff source precedence:
- *   1. `--diff-files <a,b,c>` explicit CSV (highest priority)
- *   2. `--since <ref>` → runs `git diff --name-only <ref>..HEAD`
- *   3. fallback: `git diff HEAD --name-only` (current WIP)
- *
- * BUG-025b worktree-redirect: features-audit historically wrote to the
- * invoking cwd's `.aperant/features/`, leaking generated `*.json` into
- * main when the executor invoked it 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 { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
-import { loadDocsPolicy, matchSurfaceToPolicy } from '../docs-audit/policy.mjs';
-import { applyStubPatches, auditFeatureRegistry } from '../features/registry-audit.mjs';
-import { parseFlags } from '../util/args.mjs';
-import { err, ok } from '../util/result.mjs';
-import { resolveMainRepoRoot } from '../util/state-paths.mjs';
-const TERMINAL_PHASES = new Set(['completed', 'cancelled', 'closed', 'shipped', 'merged']);
-/**
- * BUG-025b — resolve where features-audit should write `*.json`.
- * 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-audit 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 };
-}
-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;
-    }
-}
-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 {};
-    }
-}
-export function cmdFeaturesAudit(projectDir, extraArgs) {
-    if (!projectDir)
-        return err('Usage: apt-tools features-audit <project-dir> [flags]');
-    const root = resolve(projectDir);
-    const flags = parseFlags(extraArgs);
-    // BUG-025b: redirect writes to the active task's worktree when the
-    // caller is in a non-worktree cwd. See resolveWriteRoot for the
-    // 4-step resolution order.
-    const taskIdFlag = flags.get('task-id');
-    const taskId = typeof taskIdFlag === 'string' && taskIdFlag.trim() ? taskIdFlag.trim() : null;
-    const noRedirect = flags.get('no-worktree-redirect') === true;
-    const writeRootResult = resolveWriteRoot({ projectDir: root, taskId, noRedirect });
-    if (writeRootResult.error) {
-        return err(writeRootResult.error.message, 1, {
-            kind: writeRootResult.error.kind,
-            active_worktree_tasks: writeRootResult.error.active_worktree_tasks,
-        });
-    }
-    const writeRoot = writeRootResult.writeRoot;
-    const redirectNotice = writeRootResult.redirect_notice;
-    if (redirectNotice) {
-        // Surface the redirect once on stderr so the executor's log carries
-        // the audit trail without polluting stdout JSON.
-        process.stderr.write(`[features-audit] ${redirectNotice}\n`);
-    }
-    const diffFiles = resolveDiffFiles(root, flags);
-    const applyStubs = flags.has('apply-stubs');
-    const format = (flags.get('format') || 'json').toLowerCase();
-    const result = auditFeatureRegistry({ projectDir: writeRoot, diffFiles });
-    // Honor `.aperant/config.json.docs_policy`: only apply stubs for targets
-    // whose resolved policy is `auto-update`. This closes the skill-vs-code
-    // gap where `apt-execute` §3e-features promised `--apply-stubs` would
-    // no-op on surfaces the user opted out of. Patches whose target matches
-    // `skip` / `flag-drift` (or nothing) are surfaced in `stub_patches` but
-    // never written to disk.
-    let applied_patches = null;
-    let skipped_patches = null;
-    if (applyStubs && result.stub_patches.length > 0) {
-        const policy = loadDocsPolicy(root);
-        const eligible = [];
-        const skipped = [];
-        for (const patch of result.stub_patches) {
-            const policyValue = matchSurfaceToPolicy(patch.target, policy);
-            if (policyValue === 'auto-update') {
-                eligible.push(patch);
-            }
-            else {
-                skipped.push({ target: patch.target, policy: policyValue });
-            }
-        }
-        if (eligible.length > 0) {
-            // BUG-025b: stubs are written to the resolved `writeRoot` (which
-            // may be the active task's worktree) rather than the invoking cwd.
-            applied_patches = applyStubPatches(writeRoot, eligible);
-        }
-        if (skipped.length > 0) {
-            skipped_patches = skipped;
-        }
-    }
-    if (format === 'md') {
-        return ok({
-            status: 'ok',
-            command: 'features-audit',
-            format: 'md',
-            markdown: renderMarkdown(result, applied_patches, skipped_patches),
-            write_root: writeRoot,
-            ...(redirectNotice ? { redirect_notice: redirectNotice } : {}),
-            ...result,
-            ...(applied_patches ? { applied_patches } : {}),
-            ...(skipped_patches ? { skipped_patches } : {}),
-        });
-    }
-    return ok({
-        status: 'ok',
-        command: 'features-audit',
-        write_root: writeRoot,
-        ...(redirectNotice ? { redirect_notice: redirectNotice } : {}),
-        ...result,
-        ...(applied_patches ? { applied_patches } : {}),
-        ...(skipped_patches ? { skipped_patches } : {}),
-    });
-}
-function resolveDiffFiles(root, flags) {
-    const explicit = flags.get('diff-files');
-    if (explicit && typeof explicit === 'string') {
-        return explicit
-            .split(',')
-            .map((s) => s.trim())
-            .filter(Boolean);
-    }
-    const sinceRaw = flags.get('since');
-    const since = typeof sinceRaw === 'string' && /^[A-Za-z0-9/_.-]+$/.test(sinceRaw) && !sinceRaw.startsWith('-')
-        ? sinceRaw
-        : null;
-    try {
-        const args = since ? ['diff', '--name-only', `${since}..HEAD`] : ['diff', 'HEAD', '--name-only'];
-        const out = execFileSync('git', args, {
-            cwd: root,
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-        return out
-            .split('\n')
-            .map((s) => s.trim())
-            .filter(Boolean);
-    }
-    catch {
-        // Not a git repo or HEAD doesn't exist — clean slate.
-        return [];
-    }
-}
-function renderMarkdown(result, applied, skipped) {
-    const lines = ['### Features audit', ''];
-    if (result.new_components.length === 0) {
-        lines.push('_No new feature-qualifying files in diff._');
-    }
-    else {
-        lines.push('**New candidates:**');
-        for (const c of result.new_components) {
-            lines.push(`- \`${c.file}\` — kind: \`${c.kind}\`, area: \`${c.area}\``);
-        }
-    }
-    if (result.unregistered.length > 0) {
-        lines.push('', '**Unregistered:**');
-        for (const u of result.unregistered) {
-            lines.push(`- \`${u.file}\` (area: \`${u.area}\`)`);
-        }
-    }
-    if (applied && applied.length > 0) {
-        lines.push('', '**Applied patches:**');
-        for (const p of applied) {
-            lines.push(`- ${p.target} — ${p.applied ? p.reason : `FAILED: ${p.reason}`}`);
-        }
-    }
-    if (skipped && skipped.length > 0) {
-        lines.push('', '**Skipped patches (policy opt-out):**');
-        for (const s of skipped) {
-            lines.push(`- ${s.target} — policy: \`${s.policy ?? 'unmatched'}\``);
-        }
-    }
-    return lines.join('\n');
-}
-//# sourceMappingURL=features-audit.mjs.map