@aperant/framework 0.17.0 → 0.19.0

package/dist/cli/commands/produce.mjs

@@ -0,0 +1,1345 @@
+/**
+ * commands/produce.mjs — `/apt:produce` M1 CLI substrate.
+ *
+ * Subcommands (mirrors commands/roadmap.mjs's (subcommand, projectDir, extraArgs)
+ * shape): start | add-milestone | set-milestone-status | status | tick.
+ *
+ * M1 is the outer-loop SKELETON: it freezes an immutable acceptance setpoint,
+ * seeds + projects the roadmap crash-safely from the append-only event log, and
+ * advances one wake tick per invocation. It does NOT adjudicate "done" — that
+ * is external-oracle-gated and deferred to M2 (ID-03).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { createCoordinationStore } from '../coordination/store.mjs';
+import { freezeProbeSet, recordProbeRun, selectSweepSample } from '../produce/blind-probe.mjs';
+import { consumeClaims, freezeClaim, projectClaims } from '../produce/claim.mjs';
+import { adjudicateDone, computeCanary } from '../produce/done-gate.mjs';
+import { appendProduceEvent, readImplementerFamily, readProduceRunEventsMatching, } from '../produce/events.mjs';
+import { prepareOracleInput, recordOracleVerdict } from '../produce/evidence-oracle.mjs';
+import { closeCriteriaForShippedMilestone, computeOpenCriteria, computeProgress, evaluateDeclareGuard, mintCriterionId, } from '../produce/ledger.mjs';
+import { resolveProbeFamily } from '../produce/probe-family.mjs';
+import { projectRoadmap, writeProjectionCache } from '../produce/projection.mjs';
+import { mintRunId, relativeSetpointPath, resolveRunDir, slugFromOutcome, } from '../produce/run-id.mjs';
+import { compensatePhase, completePhase, enterPhase, projectSaga, recordReview, resolveReviewer, SAGA_PHASES, } from '../produce/saga.mjs';
+import { computeSchedule, resolveWipLimit } from '../produce/scheduler.mjs';
+import { freezeSetpoint, readSetpoint } from '../produce/setpoint.mjs';
+import { listRegressions, recordTtlReverify, selectTtlReverifySample, } from '../produce/verification-ttl.mjs';
+import { parseFlags } from '../util/args.mjs';
+import { err, ok } from '../util/result.mjs';
+/**
+ * Top-level dispatcher.
+ *
+ * @param {string} subcommand
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ */
+export async function cmdProduce(subcommand, projectDir, extraArgs) {
+    if (!subcommand)
+        return err('Usage: apt-tools produce <start|add-milestone|set-milestone-status|status|tick|declare-criteria|progress|record-implementer|resolve-probe-family|oracle|probe|canary|saga|ttl|schedule|claim> <project-dir>');
+    if (!projectDir)
+        return err(`Usage: apt-tools produce ${subcommand} <project-dir>`);
+    const flags = parseFlags(extraArgs);
+    switch (subcommand) {
+        case 'start':
+            return cmdStart(projectDir, flags);
+        case 'add-milestone':
+            return cmdAddMilestone(projectDir, flags);
+        case 'set-milestone-status':
+            return cmdSetMilestoneStatus(projectDir, flags);
+        case 'status':
+            return cmdStatus(projectDir, flags);
+        case 'tick':
+            return cmdTick(projectDir, flags);
+        // M3 — the Lyapunov acceptance-criteria ledger: declare an open criterion
+        // behind the write-time anti-windup guard (ID-M3-03 / ID-M3-04), and the
+        // read-time monotone-progress report (ID-M3-02 — flags, never rejects).
+        case 'declare-criteria':
+            return cmdDeclareCriteria(projectDir, flags);
+        case 'progress':
+            return cmdProgress(projectDir, flags);
+        // M2 — the cross-family disjointness anchor (ID-M2-02) + resolver (ST2).
+        case 'record-implementer':
+            return cmdRecordImplementer(projectDir, flags);
+        case 'resolve-probe-family':
+            return cmdResolveProbeFamily(projectDir, flags);
+        // M2 — two-level subcommands: `produce oracle <prepare|record>` (ST3) +
+        // `produce probe <freeze|record|sweep>` (ST4). `projectDir` here holds the
+        // sub-subcommand; the real dir is extraArgs[0].
+        case 'oracle':
+            return cmdOracle(projectDir, extraArgs);
+        case 'probe':
+            return cmdProbe(projectDir, extraArgs);
+        // M2 — the reward-hacking canary (ID-M2-06 / ST5).
+        case 'canary':
+            return cmdCanary(projectDir, flags);
+        // M4 — the saga phase model + FORWARD compensators + provider-diverse
+        // review, a two-level subcommand (same shape as oracle/probe: the
+        // sub-subcommand arrives as `projectDir`, the real dir is extraArgs[0]).
+        case 'saga':
+            return cmdSaga(projectDir, extraArgs);
+        // M4 — the verification-TTL: a rotating re-verify of OLD done milestones
+        // against HEAD (`ttl select`) + the cross-family re-verify RUN that flags +
+        // compensates regressions (`ttl reverify`). Two-level (same shape as saga).
+        case 'ttl':
+            return cmdTtl(projectDir, extraArgs);
+        // M5 — the WSJF/WIP scheduler: a read-only ranking of the ready milestones
+        // + a WIP-limited pick (dependency-aware, regression-aware). Single-level
+        // (mirrors cmdStatus/cmdCanary read-only shape); emits nothing (ID-M5-06).
+        case 'schedule':
+            return cmdSchedule(projectDir, flags);
+        // M6 — the Claim Envelope lifecycle, a two-level subcommand (same shape as
+        // oracle/probe/saga/ttl: the sub-subcommand arrives as `projectDir`, the
+        // real dir is extraArgs[0]).
+        case 'claim':
+            return cmdClaim(projectDir, extraArgs);
+        default:
+            return err(`Unknown produce subcommand: ${subcommand}`);
+    }
+}
+/** Require a frozen run; returns { setpoint } or an err() envelope. */
+function requireRun(projectDir, runId, cmd) {
+    if (!runId)
+        return { error: err(`produce ${cmd} requires --run-id <id>`) };
+    const setpoint = readSetpoint(resolveRunDir(projectDir, runId));
+    if (!setpoint)
+        return {
+            error: err(`produce ${cmd}: no frozen setpoint for run ${runId} — run produce start first`),
+        };
+    return { setpoint };
+}
+/** Resolve a string flag or null. */
+function strFlag(flags, name) {
+    const v = flags.get(name);
+    return typeof v === 'string' ? v : null;
+}
+/**
+ * `produce start . --outcome "<o>" [--run-id <id>]` — freeze the acceptance
+ * setpoint and, on a fresh freeze, emit produce.run.started +
+ * produce.setpoint.frozen. Re-running with the same --run-id is idempotent
+ * reuse (never overwrites — ID-02).
+ */
+function cmdStart(projectDir, flags) {
+    const outcome = strFlag(flags, 'outcome');
+    const explicitRunId = strFlag(flags, 'run-id');
+    let runId = explicitRunId;
+    if (!runId) {
+        if (!outcome)
+            return err('produce start requires --outcome "<text>" (or --run-id <id> to reuse an existing run)');
+        runId = mintRunId(outcome);
+    }
+    const runDir = resolveRunDir(projectDir, runId);
+    const existing = readSetpoint(runDir);
+    if (!existing && !outcome)
+        return err(`produce start --run-id ${runId} has no frozen setpoint yet; pass --outcome "<text>" to freeze it`);
+    const outcomeForFreeze = existing ? existing.outcome : outcome;
+    const { reused, setpoint } = freezeSetpoint(runDir, { run_id: runId, outcome: outcomeForFreeze });
+    const setpointPath = relativeSetpointPath(runId);
+    // Emit the run-start + setpoint-frozen events only on a FRESH freeze;
+    // idempotent reuse never re-logs (ID-02).
+    if (!reused) {
+        const store = createCoordinationStore(projectDir);
+        store.appendEvent({
+            op: 'produce.run.started',
+            task: runId,
+            data: { run_id: runId, setpoint_hash: setpoint.setpoint_hash },
+        });
+        store.appendEvent({
+            op: 'produce.setpoint.frozen',
+            task: runId,
+            data: {
+                run_id: runId,
+                setpoint_hash: setpoint.setpoint_hash,
+                setpoint_path: setpointPath,
+            },
+        });
+    }
+    return ok({
+        status: 'ok',
+        command: 'produce-start',
+        reused,
+        run_id: runId,
+        outcome: setpoint.outcome,
+        frozen_at: setpoint.frozen_at,
+        setpoint_path: setpointPath,
+        setpoint_hash: setpoint.setpoint_hash,
+    });
+}
+/**
+ * `produce add-milestone . --run-id <id> --title "<t>" [--id <mid>]
+ * [--depends-on a,b,c] [--priority <int>] [--size <positive int>]` — append
+ * produce.roadmap.milestone_added, then refresh the derived roadmap.json cache.
+ * The milestone id is minted with a random suffix when not supplied so N
+ * concurrent auto-id writers never collide (parent TD-06 / subtask 4).
+ *
+ * M5 (ID-M5-03): --depends-on / --priority / --size ride as ADDITIVE OPTIONAL
+ * data fields on the EXISTING event (no schema change — run_id/milestone_id/title
+ * stay the only required fields). An M1-style add (no new flags) is
+ * byte-identical: the event carries none of the extra fields.
+ */
+function cmdAddMilestone(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const title = strFlag(flags, 'title');
+    const gate = requireRun(projectDir, runId, 'add-milestone');
+    if (gate.error)
+        return gate.error;
+    if (!title)
+        return err('produce add-milestone requires --title "<text>"');
+    const milestoneId = strFlag(flags, 'id') || `${slugFromOutcome(title)}-${Math.random().toString(36).slice(2, 8)}`;
+    const data = { run_id: runId, milestone_id: milestoneId, title };
+    // Additive scheduling meta (M5) — only stamped when the flag is present, so an
+    // M1-style add stays byte-identical (ID-M5-03).
+    const dependsOnRaw = strFlag(flags, 'depends-on');
+    if (dependsOnRaw) {
+        const deps = dependsOnRaw
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (deps.length > 0)
+            data.depends_on = deps;
+    }
+    const priorityRaw = strFlag(flags, 'priority');
+    if (priorityRaw !== null) {
+        const p = Number.parseInt(priorityRaw, 10);
+        if (Number.isFinite(p))
+            data.priority = p;
+    }
+    const sizeRaw = strFlag(flags, 'size');
+    if (sizeRaw !== null) {
+        const s = Number.parseInt(sizeRaw, 10);
+        if (Number.isFinite(s) && s > 0)
+            data.size = s;
+    }
+    appendProduceEvent(projectDir, 'produce.roadmap.milestone_added', data);
+    // The event log is the authority; the cache is a derived convenience,
+    // folded + persisted under a single-writer lock (never lost-update).
+    const roadmap = writeProjectionCache(projectDir, runId);
+    return ok({
+        status: 'ok',
+        command: 'produce-add-milestone',
+        run_id: runId,
+        milestone_id: milestoneId,
+        title,
+        roadmap,
+    });
+}
+/**
+ * `produce set-milestone-status . --run-id <id> --milestone <mid> --status <s>`
+ * — append produce.roadmap.milestone_status_changed. `--status done` is the M2
+ * two-gate adjudication (ID-M2-04) — accepted ONLY when the visible oracle AND
+ * the blind probe both agree; a bare done with no recorded external evidence is
+ * STILL refused (the Showrunner never self-attests, ID-03). `planned` /
+ * `in_progress` are byte-identical to M1.
+ */
+function cmdSetMilestoneStatus(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const status = strFlag(flags, 'status');
+    const gate = requireRun(projectDir, runId, 'set-milestone-status');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce set-milestone-status requires --milestone <mid>');
+    if (!status)
+        return err('produce set-milestone-status requires --status <planned|in_progress|done>');
+    // M2 — `done` is the two-gate adjudication over recorded external evidence,
+    // replacing M1's blanket reject (ID-M2-04). See cmdSetMilestoneDone.
+    if (status === 'done')
+        return cmdSetMilestoneDone(projectDir, runId, milestoneId, flags);
+    if (status !== 'planned' && status !== 'in_progress')
+        return err(`produce set-milestone-status: invalid --status "${status}". Allowed: planned | in_progress | done.`);
+    const before = projectRoadmap(projectDir, runId);
+    if (!before.milestones.some((m) => m.id === milestoneId))
+        return err(`produce set-milestone-status: milestone ${milestoneId} not found in run ${runId}`);
+    appendProduceEvent(projectDir, 'produce.roadmap.milestone_status_changed', {
+        run_id: runId,
+        milestone_id: milestoneId,
+        status,
+    });
+    const roadmap = writeProjectionCache(projectDir, runId);
+    return ok({
+        status: 'ok',
+        command: 'produce-set-milestone-status',
+        run_id: runId,
+        milestone_id: milestoneId,
+        milestone_status: status,
+        roadmap,
+    });
+}
+/**
+ * `produce status . --run-id <id>` — read-only re-projection of the roadmap
+ * from the append-only event log (no in-memory authority — ID-01 / AC2). Does
+ * NOT write the cache (pure read).
+ */
+function cmdStatus(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'status');
+    if (gate.error)
+        return gate.error;
+    const roadmap = projectRoadmap(projectDir, runId);
+    return ok({
+        status: 'ok',
+        command: 'produce-status',
+        run_id: runId,
+        setpoint_hash: gate.setpoint.setpoint_hash,
+        roadmap,
+    });
+}
+/**
+ * `produce tick . --run-id <id> [--wip N]` — run EXACTLY ONE wake tick: re-project
+ * the roadmap from disk (ID-01), compute the M5 WSJF/WIP schedule, emit
+ * produce.tick + ONE produce.schedule.computed, set next_action to the scheduler's
+ * top pick, and return a reschedule hint, then EXIT. There is no polling loop and
+ * no self-scheduling timer — the recurring beat is delivered by the host (ID-05).
+ *
+ * next_action is scheduler-driven but SHAPE-PRESERVING (ID-M5-08): an in_progress
+ * milestone → continue_milestone (unconditional — always continue in-flight work,
+ * regardless of WIP); else the top WSJF ready pick under the WIP budget →
+ * start_milestone; else idle (carrying the schedule's reason). It is advisory;
+ * the Showrunner never self-attests a milestone done (external-oracle-gated, M2 —
+ * ID-03).
+ */
+function cmdTick(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'tick');
+    if (gate.error)
+        return gate.error;
+    // Re-read the roadmap from the append-only log — no in-memory authority.
+    const roadmap = projectRoadmap(projectDir, runId);
+    // M5 — fold the WSJF/WIP schedule (dependency-aware, regression-aware) under
+    // the resolved WIP budget. A pure read; the tick is the ONLY writer below.
+    const wipLimit = resolveWipLimit(projectDir, flags);
+    const schedule = computeSchedule(projectDir, runId, { wipLimit });
+    appendProduceEvent(projectDir, 'produce.tick', { run_id: runId });
+    // One recorded schedule fact per tick (ID-M5-06) — content-blind (picked ids +
+    // wip_limit only; the roadmap projection never folds produce.schedule.*).
+    appendProduceEvent(projectDir, 'produce.schedule.computed', {
+        run_id: runId,
+        picked: schedule.pick.map((p) => p.milestone_id).join(','),
+        wip_limit: String(wipLimit),
+    });
+    // Scheduler-driven next_action, shape-preserving (ID-M5-08). Continue an
+    // in-flight milestone unconditionally; else start the top WSJF ready pick under
+    // the WIP budget; else idle with the schedule's reason.
+    const inProgress = roadmap.milestones.find((m) => m.status === 'in_progress');
+    let nextAction;
+    if (inProgress) {
+        nextAction = {
+            kind: 'continue_milestone',
+            milestone_id: inProgress.id,
+            title: inProgress.title,
+            status: inProgress.status,
+        };
+    }
+    else if (schedule.pick.length > 0) {
+        const top = schedule.pick[0];
+        nextAction = {
+            kind: 'start_milestone',
+            milestone_id: top.milestone_id,
+            title: top.title,
+            status: top.status,
+        };
+    }
+    else {
+        nextAction = { kind: 'idle', reason: schedule.reason };
+    }
+    const envelope = {
+        status: 'ok',
+        command: 'produce-tick',
+        run_id: runId,
+        roadmap,
+        next_action: nextAction,
+        // M5 (ID-M5-08) — the full WSJF/WIP schedule object, an ADDITIVE field.
+        schedule,
+        next_tick_hint: 'One tick per invocation — reschedule via the host beat (cron-capable host → CronCreate; ' +
+            `non-cron host → re-run \`apt-tools produce tick . --run-id ${runId}\` when you return). No in-skill loop (ID-05).`,
+    };
+    // M4 (ID-M4-05) — an OPTIONAL --head-sha surfaces the additive per-tick TTL
+    // re-verify sample (the rotating STALE done milestones to re-verify this beat,
+    // AC13 "each tick"). When ABSENT the tick output is BYTE-IDENTICAL to M1/M2/M3
+    // (no field) and next_action is unchanged. Still exactly one tick, no loop.
+    const headSha = strFlag(flags, 'head-sha');
+    if (headSha) {
+        const sampleRaw = strFlag(flags, 'sample');
+        const sample = sampleRaw ? Number.parseInt(sampleRaw, 10) : 1;
+        envelope.ttl_reverify = selectTtlReverifySample(projectDir, runId, { headSha, sample });
+    }
+    return ok(envelope);
+}
+/**
+ * `produce declare-criteria . --run-id <id> --milestone <mid> --criterion "<text>"
+ * [--criterion-id <cid>] [--scope-change "<reason>"]` — open one acceptance
+ * criterion bound to a milestone (V += 1), gated by the write-time Lyapunov
+ * anti-windup guard (ID-M3-03). Before descent, declaration is FREE (the baseline
+ * scope-definition window). After descent (≥1 criterion already closed), it is
+ * REJECTED fail-closed (exit 1, nothing appended) unless --scope-change
+ * "<reason>" justifies the increase — the ONLY sanctioned post-descent V rise
+ * (ID-M3-04). When --scope-change is present, the command appends
+ * produce.scope.changed FIRST, then produce.criteria.declared — atomic
+ * self-justifying growth on the trail.
+ */
+function cmdDeclareCriteria(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const criterion = strFlag(flags, 'criterion');
+    const gate = requireRun(projectDir, runId, 'declare-criteria');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce declare-criteria requires --milestone <mid>');
+    if (!criterion)
+        return err('produce declare-criteria requires --criterion "<text>"');
+    // The milestone must exist in the run's roadmap (fail-closed).
+    const roadmap = projectRoadmap(projectDir, runId);
+    if (!roadmap.milestones.some((m) => m.id === milestoneId))
+        return err(`produce declare-criteria: milestone ${milestoneId} not found in run ${runId}`);
+    const scopeChangeReason = strFlag(flags, 'scope-change');
+    const criterionId = strFlag(flags, 'criterion-id') || mintCriterionId(criterion);
+    // Write-time Lyapunov anti-windup guard — the ONLY hard enforcement (ID-M3-03).
+    const guard = evaluateDeclareGuard(projectDir, runId, { hasScopeChange: !!scopeChangeReason });
+    if (!guard.allowed)
+        return err('Lyapunov violation: adding an open acceptance criterion after the run began closing criteria requires --scope-change "<reason>" (ID-M3-03/ID-M3-04)', 1, {
+            command: 'produce-declare-criteria',
+            run_id: runId,
+            milestone_id: milestoneId,
+            in_descent: guard.in_descent,
+        });
+    // Self-justifying growth: the scope-change lands FIRST, then the criterion
+    // (atomic — every post-descent increase carries its own logged justification).
+    if (scopeChangeReason)
+        appendProduceEvent(projectDir, 'produce.scope.changed', {
+            run_id: runId,
+            milestone_id: milestoneId,
+            reason: scopeChangeReason,
+        });
+    appendProduceEvent(projectDir, 'produce.criteria.declared', {
+        run_id: runId,
+        milestone_id: milestoneId,
+        criterion_id: criterionId,
+        text: criterion,
+    });
+    return ok({
+        status: 'ok',
+        command: 'produce-declare-criteria',
+        run_id: runId,
+        milestone_id: milestoneId,
+        criterion_id: criterionId,
+        open_count: computeOpenCriteria(projectDir, runId),
+        scope_changed: !!scopeChangeReason,
+    });
+}
+/**
+ * Read the LATEST recorded implementer family for a run across ALL milestones
+ * (used by `resolve-probe-family` when neither --implementer-family nor
+ * --milestone is supplied). Returns null when none is recorded (fail-closed).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {string | null}
+ */
+function latestImplementerFamilyForRun(projectDir, runId) {
+    const events = readProduceRunEventsMatching(projectDir, runId, (op) => op === 'produce.milestone.implemented');
+    let family = null;
+    for (const e of events) {
+        const d = e.data || {};
+        if (typeof d.implementer_family === 'string' && d.implementer_family.length > 0) {
+            family = d.implementer_family;
+        }
+    }
+    return family;
+}
+/**
+ * `produce record-implementer . --run-id <id> --milestone <mid>
+ * --implementer-family <fam>` — record who implemented a milestone (ID-M2-02).
+ * This is the recorded disjointness anchor every cross-family check reads. The
+ * Showrunner records it once per milestone at implementation time; the CLI
+ * never dispatches execute in M2 (that is the post-M2 closed loop).
+ */
+function cmdRecordImplementer(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const implementerFamily = strFlag(flags, 'implementer-family');
+    const gate = requireRun(projectDir, runId, 'record-implementer');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce record-implementer requires --milestone <mid>');
+    if (!implementerFamily)
+        return err('produce record-implementer requires --implementer-family <fam>');
+    appendProduceEvent(projectDir, 'produce.milestone.implemented', {
+        run_id: runId,
+        milestone_id: milestoneId,
+        implementer_family: implementerFamily,
+    });
+    return ok({
+        status: 'ok',
+        command: 'produce-record-implementer',
+        run_id: runId,
+        milestone_id: milestoneId,
+        implementer_family: implementerFamily,
+    });
+}
+/**
+ * `produce resolve-probe-family . --run-id <id> [--implementer-family <fam>]
+ * [--milestone <mid>] [--host-family <fam>] [--available-families a,b,c]` —
+ * resolve a probe/oracle family DISJOINT from the implementer, with the model
+ * resolved LIVE via the reused spar primitive (no baked model id — ID-M2-07).
+ *
+ * The implementer family is taken from --implementer-family, else read from the
+ * recorded `produce.milestone.implemented` trail (by --milestone, else the
+ * latest for the run). If neither is present, adjudication is impossible — you
+ * cannot enforce disjointness against an unknown implementer (ID-M2-02,
+ * fail-closed).
+ */
+function cmdResolveProbeFamily(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'resolve-probe-family');
+    if (gate.error)
+        return gate.error;
+    const milestoneId = strFlag(flags, 'milestone');
+    let implementerFamily = strFlag(flags, 'implementer-family');
+    if (!implementerFamily) {
+        implementerFamily = milestoneId
+            ? readImplementerFamily(projectDir, runId, milestoneId)
+            : latestImplementerFamilyForRun(projectDir, runId);
+    }
+    if (!implementerFamily)
+        return err('produce resolve-probe-family: no implementer family — pass --implementer-family <fam> or record it first via `produce record-implementer` (ID-M2-02, fail-closed).', 1, { command: 'produce-resolve-probe-family', run_id: runId });
+    const hostFamily = strFlag(flags, 'host-family');
+    const availRaw = strFlag(flags, 'available-families');
+    const availableFamilies = availRaw
+        ? availRaw
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : undefined;
+    const resolution = resolveProbeFamily({
+        implementerFamily,
+        hostFamily,
+        availableFamilies,
+    });
+    return ok({
+        status: 'ok',
+        command: 'produce-resolve-probe-family',
+        run_id: runId,
+        milestone_id: milestoneId ?? null,
+        implementer_family: implementerFamily,
+        host_family: hostFamily ?? null,
+        ...resolution,
+    });
+}
+/**
+ * `produce oracle <prepare|record> <project-dir> ...` — two-level dispatch. The
+ * sub-subcommand arrives as the outer `projectDir` param (see cmdProduce); the
+ * real project dir is `args[0]` and the flags follow it.
+ *
+ * @param {string} subsub
+ * @param {string[]} args
+ */
+function cmdOracle(subsub, args) {
+    const realProjectDir = Array.isArray(args) ? args[0] : undefined;
+    if (!realProjectDir || realProjectDir.startsWith('--'))
+        return err('Usage: apt-tools produce oracle <prepare|record> <project-dir> [flags]');
+    const flags = parseFlags(args.slice(1));
+    switch (subsub) {
+        case 'prepare':
+            return cmdOraclePrepare(realProjectDir, flags);
+        case 'record':
+            return cmdOracleRecord(realProjectDir, flags);
+        default:
+            return err(`Unknown produce oracle subcommand: ${subsub}. Expected prepare | record.`);
+    }
+}
+/**
+ * `produce oracle prepare . --run-id <id> --milestone <mid> --verdict-path <path>`
+ * — extract verify-proof's v2 verdict + tests[] evidence into a cross-family
+ * judge payload. Rejects (exit 1) when the verdict is not EXACTLY `approved`
+ * (ID-M2-05) so the skill never judges evidence a failed/unreadable gate never
+ * produced. The skill drives the actual cross-family judge LLM call; this only
+ * extracts.
+ */
+function cmdOraclePrepare(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const verdictPath = strFlag(flags, 'verdict-path');
+    const gate = requireRun(projectDir, runId, 'oracle prepare');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce oracle prepare requires --milestone <mid>');
+    if (!verdictPath)
+        return err('produce oracle prepare requires --verdict-path <path>');
+    const prepared = prepareOracleInput(verdictPath);
+    if (!prepared.approved)
+        return err(`produce oracle prepare: verify-proof verdict is not 'approved' (got: ${prepared.verdict ?? 'missing/unreadable'}) — not adjudicable (ID-M2-05, fail-closed).`, 1, {
+            command: 'produce-oracle-prepare',
+            run_id: runId,
+            milestone_id: milestoneId,
+            verdict: prepared.verdict,
+            reason: prepared.reason,
+        });
+    return ok({
+        status: 'ok',
+        command: 'produce-oracle-prepare',
+        run_id: runId,
+        milestone_id: milestoneId,
+        verdict: prepared.verdict,
+        tests: prepared.tests,
+        judge_input: prepared.judge_input,
+    });
+}
+/**
+ * `produce oracle record . --run-id <id> --milestone <mid> --verdict <pass|fail>
+ * --oracle-family <fam>` — record the cross-family evidence-quality judge's
+ * verdict. Refused fail-closed when the oracle family equals the recorded
+ * implementer family, or when no implementer family is recorded (ID-08 / ID-M2-02).
+ */
+function cmdOracleRecord(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const verdict = strFlag(flags, 'verdict');
+    const oracleFamily = strFlag(flags, 'oracle-family');
+    const gate = requireRun(projectDir, runId, 'oracle record');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce oracle record requires --milestone <mid>');
+    if (!verdict)
+        return err('produce oracle record requires --verdict <pass|fail>');
+    if (!oracleFamily)
+        return err('produce oracle record requires --oracle-family <fam>');
+    const res = recordOracleVerdict(projectDir, { runId, milestoneId, verdict, oracleFamily });
+    if (!res.ok)
+        return err(`produce oracle record refused: ${res.reason}`, 1, {
+            command: 'produce-oracle-record',
+            run_id: runId,
+            milestone_id: milestoneId,
+            reason: res.reason,
+            implementer_family: res.implementer_family ?? null,
+        });
+    return ok({
+        status: 'ok',
+        command: 'produce-oracle-record',
+        run_id: runId,
+        milestone_id: milestoneId,
+        verdict: res.verdict,
+        oracle_family: res.oracle_family,
+        implementer_family: res.implementer_family,
+    });
+}
+/**
+ * `produce probe <freeze|record|sweep> <project-dir> ...` — two-level dispatch
+ * (same shape as cmdOracle: the sub-subcommand arrives as `projectDir`).
+ *
+ * @param {string} subsub
+ * @param {string[]} args
+ */
+function cmdProbe(subsub, args) {
+    const realProjectDir = Array.isArray(args) ? args[0] : undefined;
+    if (!realProjectDir || realProjectDir.startsWith('--'))
+        return err('Usage: apt-tools produce probe <freeze|record|sweep> <project-dir> [flags]');
+    const flags = parseFlags(args.slice(1));
+    switch (subsub) {
+        case 'freeze':
+            return cmdProbeFreeze(realProjectDir, flags);
+        case 'record':
+            return cmdProbeRecord(realProjectDir, flags);
+        case 'sweep':
+            return cmdProbeSweep(realProjectDir, flags);
+        default:
+            return err(`Unknown produce probe subcommand: ${subsub}. Expected freeze | record | sweep.`);
+    }
+}
+/**
+ * `produce probe freeze . --run-id <id> --milestone <mid> --probe-file <path>
+ * --author-family <fam>` — freeze an immutable held-out probe set authored by a
+ * family ≠ the implementer. The probe CONTENT is read from --probe-file (the
+ * skill wrote it in the disjoint author family) and stored in the frozen file
+ * ONLY — never the event log (ID-M2-03). Reads the recorded implementer family
+ * to enforce the cross-family rule (fail-closed if absent).
+ */
+function cmdProbeFreeze(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const probeFile = strFlag(flags, 'probe-file');
+    const authorFamily = strFlag(flags, 'author-family');
+    const gate = requireRun(projectDir, runId, 'probe freeze');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce probe freeze requires --milestone <mid>');
+    if (!probeFile)
+        return err('produce probe freeze requires --probe-file <path>');
+    if (!authorFamily)
+        return err('produce probe freeze requires --author-family <fam>');
+    if (!existsSync(probeFile))
+        return err(`produce probe freeze: --probe-file not found: ${probeFile}`);
+    // Read the probe content the skill authored. JSON when parseable, else raw
+    // text — the content is stored verbatim and never enters the event log.
+    const raw = readFileSync(probeFile, 'utf-8');
+    let content;
+    try {
+        content = JSON.parse(raw);
+    }
+    catch {
+        content = raw;
+    }
+    const implementerFamily = readImplementerFamily(projectDir, runId, milestoneId);
+    if (!implementerFamily)
+        return err('produce probe freeze: no recorded implementer family — record it first via `produce record-implementer` (ID-M2-02, fail-closed).', 1, { command: 'produce-probe-freeze', run_id: runId, milestone_id: milestoneId });
+    const res = freezeProbeSet(projectDir, runId, milestoneId, {
+        content,
+        authorFamily,
+        implementerFamily,
+    });
+    if (!res.ok)
+        return err(`produce probe freeze refused: ${res.reason}`, 1, {
+            command: 'produce-probe-freeze',
+            run_id: runId,
+            milestone_id: milestoneId,
+            reason: res.reason,
+        });
+    return ok({
+        status: 'ok',
+        command: 'produce-probe-freeze',
+        run_id: runId,
+        milestone_id: milestoneId,
+        reused: res.reused,
+        probe_set_hash: res.probe_set_hash,
+        author_family: res.author_family,
+    });
+}
+/**
+ * `produce probe record . --run-id <id> --milestone <mid> --result <pass|fail>
+ * --probe-family <fam> --head-sha <sha>` — record a blind-probe run result
+ * (result/family/head_sha only — never content). Refused fail-closed when the
+ * probe family equals the recorded implementer family (ID-08).
+ */
+function cmdProbeRecord(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const result = strFlag(flags, 'result');
+    const probeFamily = strFlag(flags, 'probe-family');
+    const headSha = strFlag(flags, 'head-sha');
+    const gate = requireRun(projectDir, runId, 'probe record');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce probe record requires --milestone <mid>');
+    if (!result)
+        return err('produce probe record requires --result <pass|fail>');
+    if (!probeFamily)
+        return err('produce probe record requires --probe-family <fam>');
+    if (!headSha)
+        return err('produce probe record requires --head-sha <sha>');
+    const res = recordProbeRun(projectDir, { runId, milestoneId, result, probeFamily, headSha });
+    if (!res.ok)
+        return err(`produce probe record refused: ${res.reason}`, 1, {
+            command: 'produce-probe-record',
+            run_id: runId,
+            milestone_id: milestoneId,
+            reason: res.reason,
+        });
+    return ok({
+        status: 'ok',
+        command: 'produce-probe-record',
+        run_id: runId,
+        milestone_id: milestoneId,
+        result: res.result,
+        probe_family: res.probe_family,
+        head_sha: res.head_sha,
+    });
+}
+/**
+ * `produce probe sweep . --run-id <id> [--sample N]` — return a deterministic
+ * rotating sample of already-done milestones selected for blind re-probing
+ * against HEAD (US-6). Read-only — selection, not a run.
+ */
+function cmdProbeSweep(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'probe sweep');
+    if (gate.error)
+        return gate.error;
+    const sampleRaw = strFlag(flags, 'sample');
+    const sample = sampleRaw ? Number.parseInt(sampleRaw, 10) : 1;
+    const swept = selectSweepSample(projectDir, runId, { sample });
+    return ok({
+        status: 'ok',
+        command: 'produce-probe-sweep',
+        ...swept,
+    });
+}
+/**
+ * The M2 `--status done` path — the two-gate adjudication (ID-M2-04). Delegates
+ * to `adjudicateDone`: `done` flips ONLY when the visible oracle (verify-proof
+ * `approved` + recorded cross-family oracle pass) AND the blind probe (recorded
+ * cross-family probe pass + a cross-family frozen set) both agree. A
+ * visible-pass + blind-fail logs `produce.oracle.probe_gap` and stays open; a
+ * bare done with no recorded external evidence is refused — the Showrunner never
+ * self-attests (ID-03). `--verdict-path` supplies verify-proof's verdict file.
+ */
+function cmdSetMilestoneDone(projectDir, runId, milestoneId, flags) {
+    const verdictPath = strFlag(flags, 'verdict-path');
+    const res = adjudicateDone({ projectDir, runId, milestoneId, verdictPath });
+    if (res.ok) {
+        // M3 (ID-M3-05) — the shipped milestone's still-open acceptance criteria
+        // close as a CONSEQUENCE of the ship, so V strictly decreases. Wired
+        // ADDITIVELY here (done-gate.mjs is untouched): a criteria-less milestone
+        // closes zero and is byte-identical to M2.
+        const closed = closeCriteriaForShippedMilestone(projectDir, runId, milestoneId);
+        return ok({
+            status: 'ok',
+            command: 'produce-set-milestone-status',
+            run_id: runId,
+            milestone_id: milestoneId,
+            milestone_status: 'done',
+            roadmap: res.roadmap,
+            closed_criteria: closed,
+        });
+    }
+    // Refused — the milestone stays open. Frame the reason honestly (done is
+    // external-oracle-gated: it requires recorded external evidence + a blind
+    // cross-family probe; the Showrunner never self-attests, ID-03).
+    const messages = {
+        no_recorded_implementer: 'no recorded implementer family — done is external-oracle-gated: record the implementer + a cross-family oracle + blind probe first (the Showrunner never self-attests, ID-03).',
+        not_adjudicable: 'not adjudicable — done is external-oracle-gated: it requires verify-proof `approved` AND a cross-family oracle pass (ID-03).',
+        probe_gap: 'probe_gap — the visible oracle passed but the held-out blind cross-family probe FAILED; the milestone stays open and a produce.oracle.probe_gap canary event was logged (AC9).',
+    };
+    return err(`produce set-milestone-status --status done refused: ${messages[res.reason] ?? res.reason}`, 1, {
+        command: 'produce-set-milestone-status',
+        run_id: runId,
+        milestone_id: milestoneId,
+        rejected_reason: res.reason,
+        visible_gate: res.visible_gate,
+        blind_gate: res.blind_gate,
+        detail: res.detail ?? null,
+    });
+}
+/**
+ * `produce progress . --run-id <id>` — the read-time monotone-progress report
+ * (M3, ID-M3-02 / AC6). Re-reads the ledger from the append-only log on every
+ * invocation (no in-memory authority — ID-01) and returns the V-series across
+ * shipped-milestone checkpoints, `strictly_decreasing`, and any hard
+ * `lyapunov_violations` (an un-sanctioned post-descent increase, detected
+ * defensively from the fold). It FLAGS — it never rejects (the rejection is the
+ * write-time guard in `declare-criteria`); a flat ship is a soft stall.
+ */
+function cmdProgress(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'progress');
+    if (gate.error)
+        return gate.error;
+    return ok({
+        status: 'ok',
+        command: 'produce-progress',
+        ...computeProgress(projectDir, runId),
+    });
+}
+/**
+ * `produce canary . --run-id <id>` — the reward-hacking canary (ID-M2-06):
+ * green-on-visible MINUS green-on-blind over the run's milestones (from recorded
+ * seals), with a per-milestone breakdown. Each `produce.oracle.probe_gap` is one
+ * visible-pass + blind-fail near-miss. Read-only.
+ */
+function cmdCanary(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'canary');
+    if (gate.error)
+        return gate.error;
+    const canary = computeCanary(projectDir, runId);
+    return ok({
+        status: 'ok',
+        command: 'produce-canary',
+        ...canary,
+    });
+}
+/**
+ * `produce schedule . --run-id <id> [--wip N]` — the M5 WSJF/WIP scheduler
+ * (ID-M5-01/AC1). READ-ONLY: re-projects the roadmap + ledger + regressions from
+ * the append-only log, folds them into a WSJF-ranked ready_queue, a dependency-
+ * aware blocked list, the in_progress WIP accounting, and a WIP-limited pick of
+ * the top wip_available ready milestones. Emits NO event (a pure read, mirroring
+ * status/progress/canary). WIP resolves --wip flag → config produce.wip →
+ * default 1.
+ */
+function cmdSchedule(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'schedule');
+    if (gate.error)
+        return gate.error;
+    const wipLimit = resolveWipLimit(projectDir, flags);
+    const schedule = computeSchedule(projectDir, runId, { wipLimit });
+    return ok({
+        status: 'ok',
+        command: 'produce-schedule',
+        ...schedule,
+    });
+}
+/**
+ * `produce saga <enter|complete|compensate|status> <project-dir> ...` — two-level
+ * dispatch (same shape as cmdOracle/cmdProbe: the sub-subcommand arrives as the
+ * outer `projectDir` param; the real dir is `args[0]` and the flags follow it).
+ *
+ * @param {string} subsub
+ * @param {string[]} args
+ */
+function cmdSaga(subsub, args) {
+    const realProjectDir = Array.isArray(args) ? args[0] : undefined;
+    if (!realProjectDir || realProjectDir.startsWith('--'))
+        return err('Usage: apt-tools produce saga <enter|complete|compensate|review|resolve-reviewer|status> <project-dir> [flags]');
+    const flags = parseFlags(args.slice(1));
+    switch (subsub) {
+        case 'enter':
+            return cmdSagaEnter(realProjectDir, flags);
+        case 'complete':
+            return cmdSagaComplete(realProjectDir, flags);
+        case 'compensate':
+            return cmdSagaCompensate(realProjectDir, flags);
+        case 'review':
+            return cmdSagaReview(realProjectDir, flags);
+        case 'resolve-reviewer':
+            return cmdSagaResolveReviewer(realProjectDir, flags);
+        case 'status':
+            return cmdSagaStatus(realProjectDir, flags);
+        default:
+            return err(`Unknown produce saga subcommand: ${subsub}. Expected enter | complete | compensate | review | resolve-reviewer | status.`);
+    }
+}
+/** Require the milestone to exist in the run's roadmap (fail-closed). */
+function requireSagaMilestone(projectDir, runId, milestoneId, cmd) {
+    const roadmap = projectRoadmap(projectDir, runId);
+    if (!roadmap.milestones.some((m) => m.id === milestoneId))
+        return err(`produce saga ${cmd}: milestone ${milestoneId} not found in run ${runId}`);
+    return null;
+}
+/**
+ * `produce saga enter . --run-id <id> --milestone <mid> --phase <p>` — append
+ * produce.saga.phase_entered for a milestone's saga phase (phase ∈ SAGA_PHASES,
+ * validated fail-closed). A SEPARATE fold from the roadmap projection (blindness).
+ */
+function cmdSagaEnter(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const phase = strFlag(flags, 'phase');
+    const gate = requireRun(projectDir, runId, 'saga enter');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce saga enter requires --milestone <mid>');
+    if (!phase)
+        return err(`produce saga enter requires --phase <${SAGA_PHASES.join('|')}>`);
+    const missing = requireSagaMilestone(projectDir, runId, milestoneId, 'enter');
+    if (missing)
+        return missing;
+    const res = enterPhase(projectDir, { runId, milestoneId, phase });
+    if (!res.ok)
+        return err(`produce saga enter: invalid --phase "${phase}". Allowed: ${SAGA_PHASES.join(' | ')}.`, 1, { command: 'produce-saga-enter', run_id: runId, milestone_id: milestoneId });
+    return ok({
+        status: 'ok',
+        command: 'produce-saga-enter',
+        run_id: runId,
+        milestone_id: milestoneId,
+        phase,
+    });
+}
+/**
+ * `produce saga complete . --run-id <id> --milestone <mid> --phase <p>` — append
+ * produce.saga.phase_completed for a milestone's saga phase.
+ */
+function cmdSagaComplete(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const phase = strFlag(flags, 'phase');
+    const gate = requireRun(projectDir, runId, 'saga complete');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce saga complete requires --milestone <mid>');
+    if (!phase)
+        return err(`produce saga complete requires --phase <${SAGA_PHASES.join('|')}>`);
+    const missing = requireSagaMilestone(projectDir, runId, milestoneId, 'complete');
+    if (missing)
+        return missing;
+    const res = completePhase(projectDir, { runId, milestoneId, phase });
+    if (!res.ok)
+        return err(`produce saga complete: invalid --phase "${phase}". Allowed: ${SAGA_PHASES.join(' | ')}.`, 1, { command: 'produce-saga-complete', run_id: runId, milestone_id: milestoneId });
+    return ok({
+        status: 'ok',
+        command: 'produce-saga-complete',
+        run_id: runId,
+        milestone_id: milestoneId,
+        phase,
+    });
+}
+/**
+ * `produce saga compensate . --run-id <id> --milestone <mid> --phase <p>
+ * [--reason "<r>"]` — fire the FORWARD compensator for a failed saga phase
+ * (ID-M4-02). Records produce.saga.compensated carrying the descriptor KIND. The
+ * verify/review/ship compensator SHIPS A REVERT + reopens + re-plans; EVERY
+ * compensator is `rolls_back_merged_pr: false` — never a merged-PR rollback. The
+ * CLI records the descriptor; it does NOT execute the revert (OOS dispatch) and
+ * NEVER mutates the roadmap milestone status.
+ */
+function cmdSagaCompensate(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const phase = strFlag(flags, 'phase');
+    const reason = strFlag(flags, 'reason');
+    const gate = requireRun(projectDir, runId, 'saga compensate');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce saga compensate requires --milestone <mid>');
+    if (!phase)
+        return err(`produce saga compensate requires --phase <${SAGA_PHASES.join('|')}>`);
+    const missing = requireSagaMilestone(projectDir, runId, milestoneId, 'compensate');
+    if (missing)
+        return missing;
+    const res = compensatePhase(projectDir, { runId, milestoneId, phase, reason });
+    if (!res.ok)
+        return err(`produce saga compensate: invalid --phase "${phase}". Allowed: ${SAGA_PHASES.join(' | ')}.`, 1, { command: 'produce-saga-compensate', run_id: runId, milestone_id: milestoneId });
+    return ok({
+        status: 'ok',
+        command: 'produce-saga-compensate',
+        run_id: runId,
+        milestone_id: milestoneId,
+        phase,
+        reason: reason ?? null,
+        compensator: res.compensator,
+    });
+}
+/**
+ * `produce saga resolve-reviewer . --run-id <id> --milestone <mid>
+ * [--host-family <fam>] [--available-families a,b,c]` — resolve a REVIEW-phase
+ * reviewer family DISJOINT from the recorded implementer (ID-M4-04 / ID-08), a
+ * THIN wrapper over the reused resolveProbeFamily (no duplicated cross-family or
+ * model-resolution logic). The model is resolved LIVE (never a hardcoded id);
+ * available:false when no disjoint family exists (single-family setup) or when no
+ * implementer family is recorded (fail-closed).
+ */
+function cmdSagaResolveReviewer(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const gate = requireRun(projectDir, runId, 'saga resolve-reviewer');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce saga resolve-reviewer requires --milestone <mid>');
+    const hostFamily = strFlag(flags, 'host-family');
+    const availRaw = strFlag(flags, 'available-families');
+    const availableFamilies = availRaw
+        ? availRaw
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : undefined;
+    const resolution = resolveReviewer(projectDir, {
+        runId,
+        milestoneId,
+        hostFamily,
+        availableFamilies,
+    });
+    return ok({
+        status: 'ok',
+        command: 'produce-saga-resolve-reviewer',
+        run_id: runId,
+        milestone_id: milestoneId,
+        host_family: hostFamily ?? null,
+        ...resolution,
+    });
+}
+/**
+ * `produce saga review . --run-id <id> --milestone <mid> --verdict <pass|fail>
+ * --reviewer-family <fam>` — record the cross-family review verdict
+ * (produce.saga.reviewed). REFUSED fail-closed when the reviewer family equals
+ * the recorded implementer family, or when no implementer family is recorded
+ * (ID-M4-04 / ID-08 — the review-path analog of `oracle record`).
+ */
+function cmdSagaReview(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const verdict = strFlag(flags, 'verdict');
+    const reviewerFamily = strFlag(flags, 'reviewer-family');
+    const gate = requireRun(projectDir, runId, 'saga review');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce saga review requires --milestone <mid>');
+    if (!verdict)
+        return err('produce saga review requires --verdict <pass|fail>');
+    if (!reviewerFamily)
+        return err('produce saga review requires --reviewer-family <fam>');
+    const res = recordReview(projectDir, { runId, milestoneId, verdict, reviewerFamily });
+    if (!res.ok)
+        return err(`produce saga review refused: ${res.reason}`, 1, {
+            command: 'produce-saga-review',
+            run_id: runId,
+            milestone_id: milestoneId,
+            reason: res.reason,
+            implementer_family: res.implementer_family ?? null,
+        });
+    return ok({
+        status: 'ok',
+        command: 'produce-saga-review',
+        run_id: runId,
+        milestone_id: milestoneId,
+        verdict: res.verdict,
+        reviewer_family: res.reviewer_family,
+        implementer_family: res.implementer_family,
+    });
+}
+/**
+ * `produce saga status . --run-id <id>` — read-only re-projection of the saga
+ * fold from the append-only log (no in-memory authority — AC4). Reports the
+ * per-milestone phase state + any pending compensation, WITHOUT mutating the
+ * roadmap milestone status. Also reports V read-only via computeProgress for
+ * context (light M3 ledger reuse — no structural coupling).
+ */
+function cmdSagaStatus(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'saga status');
+    if (gate.error)
+        return gate.error;
+    const saga = projectSaga(projectDir, runId);
+    return ok({
+        status: 'ok',
+        command: 'produce-saga-status',
+        run_id: runId,
+        saga,
+        v_open_now: computeProgress(projectDir, runId).v_open_now,
+        // M4 — the TTL regression trail for context (read-only; no coupling).
+        ttl_regressions: listRegressions(projectDir, runId),
+    });
+}
+/**
+ * `produce ttl <select|reverify> <project-dir> ...` — two-level dispatch (same
+ * shape as cmdSaga/cmdOracle/cmdProbe: the sub-subcommand arrives as the outer
+ * `projectDir` param; the real dir is `args[0]` and the flags follow it).
+ *
+ * @param {string} subsub
+ * @param {string[]} args
+ */
+function cmdTtl(subsub, args) {
+    const realProjectDir = Array.isArray(args) ? args[0] : undefined;
+    if (!realProjectDir || realProjectDir.startsWith('--'))
+        return err('Usage: apt-tools produce ttl <select|reverify> <project-dir> [flags]');
+    const flags = parseFlags(args.slice(1));
+    switch (subsub) {
+        case 'select':
+            return cmdTtlSelect(realProjectDir, flags);
+        case 'reverify':
+            return cmdTtlReverify(realProjectDir, flags);
+        default:
+            return err(`Unknown produce ttl subcommand: ${subsub}. Expected select | reverify.`);
+    }
+}
+/**
+ * `produce ttl select . --run-id <id> --head-sha <sha> [--sample N]` — return a
+ * deterministic rotating sample of already-done milestones STALE against HEAD
+ * (reuses selectSweepSample; fresh milestones excluded). Read-only — selection,
+ * not a run. Requires --head-sha (staleness fails closed without it).
+ */
+function cmdTtlSelect(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const headSha = strFlag(flags, 'head-sha');
+    const gate = requireRun(projectDir, runId, 'ttl select');
+    if (gate.error)
+        return gate.error;
+    if (!headSha)
+        return err('produce ttl select requires --head-sha <sha>');
+    const sampleRaw = strFlag(flags, 'sample');
+    const sample = sampleRaw ? Number.parseInt(sampleRaw, 10) : 1;
+    const selected = selectTtlReverifySample(projectDir, runId, { headSha, sample });
+    return ok({
+        status: 'ok',
+        command: 'produce-ttl-select',
+        ...selected,
+    });
+}
+/**
+ * `produce ttl reverify . --run-id <id> --milestone <mid> --result <pass|fail>
+ * --probe-family <fam> --head-sha <sha>` — record a cross-family TTL re-verify
+ * run. Refused fail-closed when the probe family equals the recorded implementer
+ * family (ID-08). On `fail` it appends produce.ttl.reverified +
+ * produce.ttl.regression_detected AND fires the FORWARD compensator (a revert +
+ * reopen + re-plan; NEVER a merged-PR rollback — ID-M4-03). A `pass` refreshes
+ * verification against the new HEAD and logs no regression.
+ */
+function cmdTtlReverify(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const milestoneId = strFlag(flags, 'milestone');
+    const result = strFlag(flags, 'result');
+    const probeFamily = strFlag(flags, 'probe-family');
+    const headSha = strFlag(flags, 'head-sha');
+    const gate = requireRun(projectDir, runId, 'ttl reverify');
+    if (gate.error)
+        return gate.error;
+    if (!milestoneId)
+        return err('produce ttl reverify requires --milestone <mid>');
+    if (!result)
+        return err('produce ttl reverify requires --result <pass|fail>');
+    if (!probeFamily)
+        return err('produce ttl reverify requires --probe-family <fam>');
+    if (!headSha)
+        return err('produce ttl reverify requires --head-sha <sha>');
+    const res = recordTtlReverify(projectDir, { runId, milestoneId, result, probeFamily, headSha });
+    if (!res.ok)
+        return err(`produce ttl reverify refused: ${res.reason}`, 1, {
+            command: 'produce-ttl-reverify',
+            run_id: runId,
+            milestone_id: milestoneId,
+            reason: res.reason,
+        });
+    return ok({
+        status: 'ok',
+        command: 'produce-ttl-reverify',
+        run_id: runId,
+        milestone_id: milestoneId,
+        result: res.result,
+        probe_family: res.probe_family,
+        head_sha: res.head_sha,
+        regression: res.regression,
+        compensator: res.compensator,
+    });
+}
+/**
+ * `produce claim <declare|list|expire|consume> <project-dir> ...` — two-level
+ * dispatch (same shape as cmdSaga/cmdTtl: the sub-subcommand arrives as the outer
+ * `subsub` param; the real dir is `args[0]` and the flags follow it). The Claim
+ * Envelope lifecycle (M6): declare freezes + logs a validated envelope, list
+ * re-projects the ledger, expire logs `produce.claim.expired`, consume emits the
+ * structured delta.
+ *
+ * @param {string} subsub
+ * @param {string[]} args
+ */
+function cmdClaim(subsub, args) {
+    const realProjectDir = Array.isArray(args) ? args[0] : undefined;
+    if (!realProjectDir || realProjectDir.startsWith('--'))
+        return err('Usage: apt-tools produce claim <declare|list|expire|consume> <project-dir> [flags]');
+    const flags = parseFlags(args.slice(1));
+    switch (subsub) {
+        case 'declare':
+            return cmdClaimDeclare(realProjectDir, flags);
+        case 'list':
+            return cmdClaimList(realProjectDir, flags);
+        case 'expire':
+            return cmdClaimExpire(realProjectDir, flags);
+        case 'consume':
+            return cmdClaimConsume(realProjectDir, flags);
+        default:
+            return err(`Unknown produce claim subcommand: ${subsub}. Expected declare | list | expire | consume.`);
+    }
+}
+/**
+ * `produce claim declare . --run-id <id> --profile <p> --claim-file <path>
+ * [--claim-id <id>]` — read + parse the claim file, VALIDATE + freeze it to
+ * claims/<claim-id>.json exclusive-create, and log `produce.claim.declared`
+ * (content_hash only). An invalid envelope is REFUSED fail-closed with its reason.
+ */
+function cmdClaimDeclare(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const profile = strFlag(flags, 'profile');
+    const claimFile = strFlag(flags, 'claim-file');
+    const claimId = strFlag(flags, 'claim-id');
+    const gate = requireRun(projectDir, runId, 'claim declare');
+    if (gate.error)
+        return gate.error;
+    if (!profile)
+        return err('produce claim declare requires --profile <id>');
+    if (!claimFile)
+        return err('produce claim declare requires --claim-file <path>');
+    if (!existsSync(claimFile))
+        return err(`produce claim declare: claim file not found: ${claimFile}`);
+    let envelope;
+    try {
+        envelope = JSON.parse(readFileSync(claimFile, 'utf-8'));
+    }
+    catch {
+        return err(`produce claim declare: claim file is not valid JSON: ${claimFile}`);
+    }
+    const res = freezeClaim(projectDir, runId, { profile, envelope, claimId: claimId ?? undefined });
+    if (!res.ok)
+        return err(`produce claim declare refused: ${res.reason}`, 1, {
+            command: 'produce-claim-declare',
+            run_id: runId,
+            reason: res.reason,
+        });
+    return ok({
+        status: 'ok',
+        command: 'produce-claim-declare',
+        run_id: runId,
+        claim_id: res.claim_id,
+        profile: res.profile,
+        content_hash: res.content_hash,
+        reused: res.reused,
+    });
+}
+/**
+ * `produce claim list . --run-id <id>` — read-only re-projection of the claim
+ * ledger (declared − expired) folded from the append-only log (no in-memory
+ * authority). The `produce.claim.*` ops never enter the roadmap projection.
+ */
+function cmdClaimList(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'claim list');
+    if (gate.error)
+        return gate.error;
+    const ledger = projectClaims(projectDir, runId);
+    return ok({ status: 'ok', command: 'produce-claim-list', ...ledger });
+}
+/**
+ * `produce claim expire . --run-id <id> --claim-id <id> [--reason "<r>"]` —
+ * append `produce.claim.expired`; the claim leaves the ledger's active set
+ * (anti-corrosion manual expiry). Records the descriptor; the content file stays.
+ */
+function cmdClaimExpire(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const claimId = strFlag(flags, 'claim-id');
+    const reason = strFlag(flags, 'reason') || 'manual_expiry';
+    const gate = requireRun(projectDir, runId, 'claim expire');
+    if (gate.error)
+        return gate.error;
+    if (!claimId)
+        return err('produce claim expire requires --claim-id <id>');
+    appendProduceEvent(projectDir, 'produce.claim.expired', {
+        run_id: runId,
+        claim_id: claimId,
+        reason,
+    });
+    return ok({
+        status: 'ok',
+        command: 'produce-claim-expire',
+        run_id: runId,
+        claim_id: claimId,
+        reason,
+    });
+}
+/**
+ * `produce claim consume . --run-id <id> [--milestone <mid>]` — emit the
+ * STRUCTURED delta `{claim_id, targets:[{kind, requirement, ref?}]}` for each
+ * consumable active claim (derived from resolution_verifier — never a lesson-text
+ * paste), skipping expired / HEAD-invalidated / precondition-unmatched claims.
+ * Appends one `produce.claim.consumed {run_id, claim_id, target_kind, target_ref?}`
+ * per emitted target for the forensic trail (target_kind only, never content).
+ */
+function cmdClaimConsume(projectDir, flags) {
+    const runId = strFlag(flags, 'run-id');
+    const gate = requireRun(projectDir, runId, 'claim consume');
+    if (gate.error)
+        return gate.error;
+    const milestone = strFlag(flags, 'milestone');
+    const ctx = milestone ? { milestone, milestone_id: milestone } : {};
+    const result = consumeClaims(projectDir, runId, ctx);
+    // Forensic trail: one produce.claim.consumed per emitted target (ID-M6-07 —
+    // target_kind only, never claim content).
+    for (const c of result.consumed) {
+        for (const t of c.targets) {
+            const data = { run_id: runId, claim_id: c.claim_id, target_kind: t.kind };
+            if (typeof t.ref === 'string' && t.ref)
+                data.target_ref = t.ref;
+            appendProduceEvent(projectDir, 'produce.claim.consumed', data);
+        }
+    }
+    return ok({ status: 'ok', command: 'produce-claim-consume', run_id: runId, ...result });
+}
+//# sourceMappingURL=produce.mjs.map