@aperant/framework 0.17.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

@@ -29,6 +29,7 @@ Commands:
   risk-check <dir> --paths <p1> [--operation <type>]  Classify file paths by risk level
 
   task create <dir> --description <text> [--scope <s>] [--milestone <id>] [--phase <id>] [--roadmap-ref-url <url>] [--depends-on <refs>] [--track <T>] [--autonomy <N>]  Create isolated task
+  task ensure <dir> --description <text> --intent <create-new|require-existing|self-managed|none> [--track <T>] [--autonomy <N>] [--scope <s>] [--id <id>]  Deterministic idempotent allocator: create-new provisions a per-task worktree (idempotent on re-run), require-existing resolves the active task without minting, none/self-managed allocate nothing
   task list <dir> [--scope <s>] [--blocked-by <id>]  List active tasks (optionally filtered)
   task get <dir> --id <task-id>         Get task details and artifacts
   task update <dir> --id <id> [--lifecycle-phase <p>] [--pr-url <url>] [--subtasks-total <N>] [--depends-on <refs>]  Update non-linkage task state; --pr-url may arm ci-watch per ci_watch.after_ship
@@ -37,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
@@ -136,6 +137,35 @@ Commands:
   ci-watch start|stop|status|tick <dir> [--pr <N>] [...]   /apt:watch-ci primitives — see SKILL.md for full flag matrix
   ci-watch sweep <dir> --orphaned [--dry-run]              BUG-027: enumerate ci-watches state files, query gh per PR, remove terminal-state (MERGED|CLOSED) entries (manual GC; rate-limited)
 
+  produce start <dir> --outcome "<o>" [--run-id <id>]      /apt:produce M1 — freeze an immutable acceptance setpoint under .aperant/produce/<run-id>/ (idempotent-reuse on --run-id, never overwrites); emits produce.run.started + produce.setpoint.frozen
+  produce add-milestone <dir> --run-id <id> --title "<t>" [--id <mid>]   Append produce.roadmap.milestone_added + refresh the derived roadmap.json projection cache
+  produce set-milestone-status <dir> --run-id <id> --milestone <mid> --status <planned|in_progress|done> [--verdict-path <p>]   Append produce.roadmap.milestone_status_changed; --status done is the M2 two-gate adjudication (visible oracle AND blind probe)
+  produce status <dir> --run-id <id>                       Re-project the roadmap from the append-only event log (no in-memory authority)
+  produce tick <dir> --run-id <id>                         Run exactly ONE wake tick — re-project from disk, emit produce.tick, compute next_action + next_tick_hint, then exit (no loop)
+  produce record-implementer <dir> --run-id <id> --milestone <mid> --implementer-family <fam>   /apt:produce M2 — record the implementer family (the cross-family disjointness anchor)
+  produce resolve-probe-family <dir> --run-id <id> [--milestone <mid>] [--implementer-family <fam>] [--host-family <fam>] [--available-families a,b,c]   M2 — resolve a probe/oracle family DISJOINT from the implementer + a LIVE model (never hardcoded); available:false when none
+  produce oracle prepare <dir> --run-id <id> --milestone <mid> --verdict-path <p>   M2 — extract verify-proof's v2 verdict (must be approved) + tests[] evidence into a cross-family judge payload
+  produce oracle record <dir> --run-id <id> --milestone <mid> --verdict <pass|fail> --oracle-family <fam>   M2 — record produce.oracle.judged (refused when oracle_family === implementer)
+  produce probe freeze <dir> --run-id <id> --milestone <mid> --probe-file <p> --author-family <fam>   M2 — freeze an immutable held-out probe set (hash + family only; refused when author_family === implementer)
+  produce probe record <dir> --run-id <id> --milestone <mid> --result <pass|fail> --probe-family <fam> --head-sha <sha>   M2 — record produce.probe.run (result/family/sha only; refused when probe_family === implementer)
+  produce probe sweep <dir> --run-id <id> [--sample N]     M2 — deterministic rotating sample of already-done milestones to blind-re-probe against HEAD
+  produce canary <dir> --run-id <id>                       M2 — green-on-visible MINUS green-on-blind + per-milestone breakdown (the reward-hacking canary)
+  produce declare-criteria <dir> --run-id <id> --milestone <mid> --criterion "<text>" [--criterion-id <cid>] [--scope-change "<reason>"]   /apt:produce M3 — open one acceptance criterion (V += 1); rejected after descent unless --scope-change justifies the increase (anti-windup)
+  produce progress <dir> --run-id <id>                     M3 — re-read the Lyapunov V-series from the log: open-criteria count strictly decreasing across shipped milestones + any un-sanctioned-increase violations (flags, never rejects)
+  produce saga enter <dir> --run-id <id> --milestone <mid> --phase <plan|execute|verify|review|ship>   /apt:produce M4 — append produce.saga.phase_entered (separate fold from the roadmap projection)
+  produce saga complete <dir> --run-id <id> --milestone <mid> --phase <plan|execute|verify|review|ship>   M4 — append produce.saga.phase_completed
+  produce saga compensate <dir> --run-id <id> --milestone <mid> --phase <p> [--reason "<r>"]   M4 — fire the FORWARD compensator (verify|review|ship ships a revert + reopens + re-plans; NEVER rolls back a merged PR); records the descriptor, does not execute it
+  produce saga resolve-reviewer <dir> --run-id <id> --milestone <mid> [--host-family <fam>] [--available-families a,b,c]   M4 — resolve a REVIEW-phase reviewer family DISJOINT from the implementer + a LIVE model (reuses resolveProbeFamily; never hardcoded); available:false when none
+  produce saga review <dir> --run-id <id> --milestone <mid> --verdict <pass|fail> --reviewer-family <fam>   M4 — record produce.saga.reviewed (refused when reviewer_family === implementer)
+  produce saga status <dir> --run-id <id>                  M4 — re-project per-milestone saga phase state + pending compensation from the log (no roadmap status mutation)
+  produce ttl select <dir> --run-id <id> --head-sha <sha> [--sample N]   M4 — deterministic rotating sample of OLD done milestones STALE against HEAD (reuses the M2 rotation; a milestone re-verified against current HEAD is excluded as fresh)
+  produce ttl reverify <dir> --run-id <id> --milestone <mid> --result <pass|fail> --probe-family <fam> --head-sha <sha>   M4 — cross-family re-verify; --result fail appends ttl.reverified + ttl.regression_detected + fires the FORWARD compensator (ships a revert, not a rollback)
+  produce schedule <dir> --run-id <id> [--wip N]           /apt:produce M5 — WSJF-rank the ready milestones (cost-of-delay / job-size) + a WIP-limited pick; dependency-aware readiness (blocked / cycle), M4-regression re-entry; read-only
+  produce claim declare <dir> --run-id <id> --profile <p> --claim-file <path> [--claim-id <id>]   /apt:produce M6 — validate + freeze an immutable Claim Envelope to claims/<claim-id>.json (interop, not a 4th store); rejects a global/unbounded scope, empty preconditions, or missing expiry fail-closed; logs produce.claim.declared (content_hash only)
+  produce claim list <dir> --run-id <id>                   M6 — re-project the claim ledger (declared − expired) folded from the append-only log; produce.claim.* never enters the roadmap projection
+  produce claim expire <dir> --run-id <id> --claim-id <id> [--reason "<r>"]   M6 — append produce.claim.expired; the claim drops out of the ledger's active set (anti-corrosion manual expiry)
+  produce claim consume <dir> --run-id <id> [--milestone <mid>]   M6 — emit the STRUCTURED delta {claim_id, targets:[{kind, requirement, ref?}]} derived from resolution_verifier (never a lesson-text paste); skips expired / HEAD-invalidated / precondition-unmatched claims
+
   followups check <dir> --task-id <id>                      G45: derive the expected follow-up universe (Out of Scope ∪ raw review rows ∪ qa findings) + report missing/unadjudicated/unfixed/undispositioned rows; exit 1 when the ledger is dishonest
   followups disposition <dir> --task-id <id> --row <row-id> --kind <filed_task|executed_commit|parked_note|dropped_by_user> --ref <ref> [--reason <text>]   G45: flip a ledger row to dispositioned (atomic; dropped_by_user requires --reason)
   followups policy <dir> --task-id <id>                     G45: effective disposition policy (ask|file|chain + max_chain_depth) from config.followups when set, else autonomy-derived

package/src/cli/install/legacy-paths.mjs

@@ -108,6 +108,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt-personas.md',
 			'agents/apt-plan.md',
 			'agents/apt-pr-review.md',
+			'agents/apt-produce.md',
 			'agents/apt-prototype.md',
 			'agents/apt-quick.md',
 			'agents/apt-release-notes.md',
@@ -153,6 +154,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'commands/apt-personas.md',
 			'commands/apt-plan.md',
 			'commands/apt-pr-review.md',
+			'commands/apt-produce.md',
 			'commands/apt-prototype.md',
 			'commands/apt-quick.md',
 			'commands/apt-release-notes.md',