@aperant/framework 0.17.0 → 0.19.0

package/dist/cli/produce/saga.mjs

@@ -0,0 +1,290 @@
+/**
+ * @internal
+ * produce/saga.mjs — the plan→execute→verify→review→ship saga + FORWARD
+ * compensators (M4, ID-M4-01 / ID-M4-02, the ID-10 semantic).
+ *
+ * The loop is modeled as a saga: each phase declares a FORWARD compensator via
+ * `resolveCompensator(phase)`. The load-bearing invariant is that EVERY
+ * compensator carries `rolls_back_merged_pr: false` — a compensator is always a
+ * forward compensating transaction. A failed verify/review/ship SHIPS A REVERT
+ * (a new forward commit/branch) + reopens the task + re-plans; it NEVER un-merges
+ * history other agents/humans already built on. plan/execute are pre-merge and
+ * simply reopen + re-plan (no revert), still `rolls_back_merged_pr: false`.
+ *
+ * The CLI RECORDS the phase transitions + the forward-compensator DESCRIPTOR; it
+ * NEVER executes the revert / reopen / re-plan (that dispatch is OOS — the CLI
+ * records + computes, the skill/dispatch acts, exactly as M2 records
+ * oracle/probe results while the skill drives the LLM steps).
+ *
+ * `projectSaga` folds `produce.saga.*` ONLY into per-milestone phase state — a
+ * SEPARATE fold PARALLEL to the roadmap projection (projection.mjs still folds
+ * `produce.roadmap.*` ONLY, so the M1/M2/M3 blindness invariant holds: a saga
+ * compensation never mutates a milestone's `done` roadmap status).
+ */
+import { appendProduceEvent, readImplementerFamily, readProduceRunEventsMatching, } from './events.mjs';
+import { normalizeFamily, resolveProbeFamily } from './probe-family.mjs';
+/** The ordered saga phases (ID-M4-01). Mirrors ALLOWED_SAGA_PHASES in event-schema.mjs. */
+export const SAGA_PHASES = ['plan', 'execute', 'verify', 'review', 'ship'];
+/**
+ * The declared FORWARD-compensator table (ID-M4-02). EVERY descriptor carries
+ * `rolls_back_merged_pr: false` — a compensator is always forward. plan/execute
+ * are pre-merge (reopen + re-plan, no revert); verify/review/ship SHIP A REVERT
+ * + reopen + re-plan. The CLI records the descriptor kind; it never emits a
+ * rollback / history-rewrite instruction.
+ */
+const COMPENSATORS = {
+    plan: {
+        kind: 'rewrite_plan',
+        reopens_task: true,
+        ships_revert: false,
+        rolls_back_merged_pr: false,
+    },
+    execute: {
+        kind: 'discard_branch_replan',
+        reopens_task: true,
+        ships_revert: false,
+        rolls_back_merged_pr: false,
+    },
+    verify: {
+        kind: 'revert_reopen_replan',
+        reopens_task: true,
+        ships_revert: true,
+        rolls_back_merged_pr: false,
+    },
+    review: {
+        kind: 'revert_reopen_replan',
+        reopens_task: true,
+        ships_revert: true,
+        rolls_back_merged_pr: false,
+    },
+    ship: {
+        kind: 'revert_reopen_replan',
+        reopens_task: true,
+        ships_revert: true,
+        rolls_back_merged_pr: false,
+    },
+};
+/**
+ * Resolve the declared FORWARD compensator for a saga phase. Returns a fresh
+ * copy (the table is never handed out mutable) or null for an out-of-vocabulary
+ * phase (fail-closed). The returned descriptor ALWAYS has
+ * `rolls_back_merged_pr: false` (ID-M4-02).
+ *
+ * @param {string} phase
+ * @returns {{ kind: string, reopens_task: boolean, ships_revert: boolean, rolls_back_merged_pr: boolean } | null}
+ */
+export function resolveCompensator(phase) {
+    const descriptor = COMPENSATORS[phase];
+    if (!descriptor)
+        return null;
+    return { ...descriptor };
+}
+/**
+ * Append `produce.saga.phase_entered` for a milestone's saga phase. Validates
+ * the phase against SAGA_PHASES fail-closed (an out-of-vocabulary phase appends
+ * nothing).
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string }} args
+ * @returns {{ ok: true, phase: string } | { ok: false, reason: string }}
+ */
+export function enterPhase(projectDir, { runId, milestoneId, phase }) {
+    if (!SAGA_PHASES.includes(phase))
+        return { ok: false, reason: 'invalid_phase' };
+    appendProduceEvent(projectDir, 'produce.saga.phase_entered', {
+        run_id: runId,
+        milestone_id: milestoneId,
+        phase,
+    });
+    return { ok: true, phase };
+}
+/**
+ * Append `produce.saga.phase_completed` for a milestone's saga phase. Validates
+ * the phase against SAGA_PHASES fail-closed.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string }} args
+ * @returns {{ ok: true, phase: string } | { ok: false, reason: string }}
+ */
+export function completePhase(projectDir, { runId, milestoneId, phase }) {
+    if (!SAGA_PHASES.includes(phase))
+        return { ok: false, reason: 'invalid_phase' };
+    appendProduceEvent(projectDir, 'produce.saga.phase_completed', {
+        run_id: runId,
+        milestone_id: milestoneId,
+        phase,
+    });
+    return { ok: true, phase };
+}
+/**
+ * Fire the FORWARD compensator for a failed saga phase (ID-M4-02). Resolves the
+ * declared compensator, then appends `produce.saga.compensated {run_id,
+ * milestone_id, phase, compensator: <descriptor.kind>, reason}` — carrying the
+ * descriptor KIND, never a rollback instruction. Validates the phase fail-closed.
+ * The CLI records the forward compensator; it does NOT execute the revert/reopen/
+ * re-plan (OOS dispatch) and NEVER mutates the roadmap milestone status.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, phase: string, reason?: string }} args
+ * @returns {{ ok: true, phase: string, compensator: object } | { ok: false, reason: string }}
+ */
+export function compensatePhase(projectDir, { runId, milestoneId, phase, reason }) {
+    if (!SAGA_PHASES.includes(phase))
+        return { ok: false, reason: 'invalid_phase' };
+    const compensator = resolveCompensator(phase);
+    appendProduceEvent(projectDir, 'produce.saga.compensated', {
+        run_id: runId,
+        milestone_id: milestoneId,
+        phase,
+        compensator: compensator.kind,
+        reason: reason || `compensate_${phase}`,
+    });
+    return { ok: true, phase, compensator };
+}
+/**
+ * Record a provider-diverse review verdict (ID-M4-04 / ID-08). The review-path
+ * analog of evidence-oracle.mjs::recordOracleVerdict. REFUSES fail-closed when
+ * the reviewer family equals the recorded implementer family (a same-family
+ * reviewer rubber-stamps its own family's work) or when no implementer family is
+ * recorded (ID-M2-02). On acceptance appends `produce.saga.reviewed {run_id,
+ * milestone_id, reviewer_family, verdict}`.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, verdict: string, reviewerFamily: string }} args
+ * @returns {{ ok: true, verdict: string, reviewer_family: string, implementer_family: string }
+ *   | { ok: false, reason: string, implementer_family?: string | null }}
+ */
+export function recordReview(projectDir, { runId, milestoneId, verdict, reviewerFamily }) {
+    if (verdict !== 'pass' && verdict !== 'fail')
+        return { ok: false, reason: 'invalid_verdict' };
+    if (!reviewerFamily)
+        return { ok: false, reason: 'no_reviewer_family' };
+    const implementerFamily = readImplementerFamily(projectDir, runId, milestoneId);
+    if (!implementerFamily)
+        return { ok: false, reason: 'no_recorded_implementer', implementer_family: null };
+    // Cross-family enforcement (normalized so claude-code === claude).
+    if (normalizeFamily(reviewerFamily) === normalizeFamily(implementerFamily))
+        return { ok: false, reason: 'same_family_reviewer', implementer_family: implementerFamily };
+    appendProduceEvent(projectDir, 'produce.saga.reviewed', {
+        run_id: runId,
+        milestone_id: milestoneId,
+        reviewer_family: reviewerFamily,
+        verdict,
+    });
+    return {
+        ok: true,
+        verdict,
+        reviewer_family: reviewerFamily,
+        implementer_family: implementerFamily,
+    };
+}
+/**
+ * Resolve a REVIEW-phase reviewer family DISJOINT from the recorded implementer
+ * (ID-M4-04 / ID-08), a THIN wrapper over the M2 `resolveProbeFamily` — NO
+ * duplicated cross-family / partner-map / model-resolution logic. Reads the
+ * implementer family from the recorded `produce.milestone.implemented` trail
+ * (fail-closed when absent). Returns the resolution with `probe_family` surfaced
+ * as `reviewer_family`. Provider is an OUTPUT; the model is resolved LIVE (null
+ * for self-resolving families) — never a hardcoded id.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, hostFamily?: string | null, availableFamilies?: string[] }} args
+ * @returns {{ available: boolean, reviewer_family: string | null, implementer_family: string | null,
+ *   transport_hint: object | null, model: string | null, source: string | null, reason: string | null }}
+ */
+export function resolveReviewer(projectDir, { runId, milestoneId, hostFamily, availableFamilies }) {
+    const implementerFamily = readImplementerFamily(projectDir, runId, milestoneId);
+    if (!implementerFamily) {
+        return {
+            available: false,
+            reviewer_family: null,
+            implementer_family: null,
+            transport_hint: null,
+            model: null,
+            source: null,
+            reason: 'no_recorded_implementer',
+        };
+    }
+    const resolution = resolveProbeFamily({ implementerFamily, hostFamily, availableFamilies });
+    // Surface the disjoint probe family as the reviewer family (same selection).
+    const { probe_family, ...rest } = resolution;
+    return { ...rest, reviewer_family: probe_family, implementer_family: implementerFamily };
+}
+/**
+ * Fold the run's `produce.saga.*` events into per-milestone saga state — a
+ * SEPARATE fold parallel to the roadmap projection (the roadmap projection folds
+ * `produce.roadmap.*` ONLY, so saga events never enter the roadmap the Showrunner
+ * re-reads each tick — blindness preserved, ID-M4-01). Deterministic: two folds
+ * of the same log yield the identical saga state; `updated_at` is the last folded
+ * event's timestamp.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{
+ *   run_id: string,
+ *   milestones: Array<{
+ *     milestone_id: string,
+ *     current_phase: string | null,
+ *     phase_status: 'entered' | 'completed' | null,
+ *     phases: Record<string, 'entered' | 'completed'>,
+ *     last_compensated: { phase: string | null, compensator: string | null, reason: string | null } | null,
+ *     reviewed: { reviewer_family: string | null, verdict: string | null } | null,
+ *   }>,
+ *   updated_at: string | null,
+ * }}
+ */
+export function projectSaga(projectDir, runId) {
+    const events = readProduceRunEventsMatching(projectDir, runId, (op) => op.startsWith('produce.saga.'));
+    const byId = new Map();
+    const order = [];
+    let updatedAt = null;
+    const ensure = (id) => {
+        if (!byId.has(id)) {
+            byId.set(id, {
+                milestone_id: id,
+                current_phase: null,
+                phase_status: null,
+                phases: {},
+                last_compensated: null,
+                reviewed: null,
+            });
+            order.push(id);
+        }
+        return byId.get(id);
+    };
+    for (const e of events) {
+        const d = e.data || {};
+        const id = typeof d.milestone_id === 'string' ? d.milestone_id : null;
+        if (!id)
+            continue;
+        const m = ensure(id);
+        const phase = typeof d.phase === 'string' ? d.phase : null;
+        if (e.op === 'produce.saga.phase_entered' && phase) {
+            m.current_phase = phase;
+            m.phase_status = 'entered';
+            m.phases[phase] = 'entered';
+        }
+        else if (e.op === 'produce.saga.phase_completed' && phase) {
+            m.current_phase = phase;
+            m.phase_status = 'completed';
+            m.phases[phase] = 'completed';
+        }
+        else if (e.op === 'produce.saga.compensated') {
+            m.last_compensated = {
+                phase,
+                compensator: typeof d.compensator === 'string' ? d.compensator : null,
+                reason: typeof d.reason === 'string' ? d.reason : null,
+            };
+        }
+        else if (e.op === 'produce.saga.reviewed') {
+            m.reviewed = {
+                reviewer_family: typeof d.reviewer_family === 'string' ? d.reviewer_family : null,
+                verdict: typeof d.verdict === 'string' ? d.verdict : null,
+            };
+        }
+        if (typeof e.t === 'string')
+            updatedAt = e.t;
+    }
+    return { run_id: runId, milestones: order.map((id) => byId.get(id)), updated_at: updatedAt };
+}
+//# sourceMappingURL=saga.mjs.map

package/dist/cli/produce/saga.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga.mjs","sourceRoot":"","sources":["../../../src/cli/produce/saga.mjs"],"names":[],"mappings":"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"}

package/dist/cli/produce/scheduler.d.mts

@@ -0,0 +1,165 @@
+/**
+ * Resolve the WIP cap deterministically (ID-M5-05):
+ * `--wip <n>` flag → `.aperant/config.json :: produce.wip` → default 1. A
+ * non-numeric / negative / bare `--wip` value is ignored (falls through). The
+ * cap is the max number of CONCURRENT in_progress milestones the loop will run.
+ *
+ * @param {string} projectDir
+ * @param {Map<string, string | true>} flags
+ * @returns {number}
+ */
+export function resolveWipLimit(projectDir: string, flags: Map<string, string | true>): number;
+/**
+ * Fold the run's `produce.roadmap.milestone_added` events into the per-milestone
+ * scheduling metadata carried as ADDITIVE optional fields on that event
+ * (ID-M5-03): `depends_on` (string[]), `priority` (int, default 0), `size`
+ * (positive int | null). An M1-style milestone (added with no new flags) folds
+ * to `{ depends_on: [], priority: 0, size: null }` — byte-identical behavior.
+ * First-seen wins (idempotent re-adds never clobber).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {Map<string, { depends_on: string[], priority: number, size: number | null }>}
+ */
+export function readMilestoneMeta(projectDir: string, runId: string): Map<string, {
+    depends_on: string[];
+    priority: number;
+    size: number | null;
+}>;
+/**
+ * CostOfDelay = 5·regression + 3·blocking + 2·open_criteria + priority (all
+ * integer). Absent fields default to 0.
+ *
+ * @param {{ regressionFlag?: number, blockingCount?: number, openCriteria?: number, priority?: number }} args
+ * @returns {number}
+ */
+export function computeCostOfDelay({ regressionFlag, blockingCount, openCriteria, priority, }?: {
+    regressionFlag?: number;
+    blockingCount?: number;
+    openCriteria?: number;
+    priority?: number;
+}): number;
+/**
+ * JobSize = declared_size when positive, else the open-criteria count floored at
+ * 1 (never 0 — a criteria-less, size-less milestone is the smallest job = 1, so
+ * WSJF never divides by zero). ID-M5-01.
+ *
+ * @param {{ declaredSize?: number | null, openCriteria?: number }} args
+ * @returns {number}
+ */
+export function computeJobSize({ declaredSize, openCriteria }?: {
+    declaredSize?: number | null;
+    openCriteria?: number;
+}): number;
+/**
+ * WSJF = CostOfDelay / JobSize. JobSize is guaranteed ≥ 1 (computeJobSize) so
+ * this never divides by zero.
+ *
+ * @param {number} costOfDelay
+ * @param {number} jobSize
+ * @returns {number}
+ */
+export function computeWsjf(costOfDelay: number, jobSize: number): number;
+/**
+ * True iff milestone `milestoneId` has an UNRESOLVED M4 verification-TTL
+ * regression — it appears in `listRegressions` AND its latest recorded
+ * `produce.ttl.reverified` result is not `pass` (ID-M5-07). A subsequent
+ * `--result pass` re-verify resolves it (latest result becomes `pass`).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {string} milestoneId
+ * @returns {boolean}
+ */
+export function hasUnresolvedRegression(projectDir: string, runId: string, milestoneId: string): boolean;
+/**
+ * A ranked ready-queue entry with its WSJF terms exposed.
+ *
+ * @typedef {Object} ScheduleEntry
+ * @property {string} milestone_id
+ * @property {string} title
+ * @property {string} status
+ * @property {number} wsjf
+ * @property {number} cost_of_delay
+ * @property {number} job_size
+ * @property {number} open_criteria
+ * @property {number} blocking_count
+ * @property {number} priority
+ * @property {boolean} regressed
+ */
+/**
+ * The pure schedule combiner (ID-M5-02). Folds the existing projections + the
+ * meta-fold + regressions into a WSJF-ranked `ready_queue`, a `blocked` list
+ * (with `blocked_by` = the not-done deps), the `in_progress` accounting, and a
+ * WIP-limited `pick` of the top `wip_available` ready milestones. Emits NO
+ * event and mutates no module (a pure read).
+ *
+ * Ready-set membership: a `planned` milestone is READY iff every `depends_on`
+ * id resolves to a roadmap milestone with status `done` (an unknown dep fails
+ * closed = unmet); otherwise it goes to `blocked`. A `done` milestone with an
+ * unresolved M4 regression re-enters the ready set tagged regressed:true.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {{ wipLimit?: number }} [opts]
+ * @returns {{
+ *   run_id: string,
+ *   wip_limit: number,
+ *   wip_in_use: number,
+ *   wip_available: number,
+ *   ready_queue: ScheduleEntry[],
+ *   blocked: Array<{ milestone_id: string, title: string, blocked_by: string[] }>,
+ *   in_progress: Array<{ milestone_id: string, title: string }>,
+ *   pick: ScheduleEntry[],
+ *   reason: string,
+ *   cycle: string[] | null,
+ * }}
+ */
+export function computeSchedule(projectDir: string, runId: string, { wipLimit }?: {
+    wipLimit?: number;
+}): {
+    run_id: string;
+    wip_limit: number;
+    wip_in_use: number;
+    wip_available: number;
+    ready_queue: ScheduleEntry[];
+    blocked: Array<{
+        milestone_id: string;
+        title: string;
+        blocked_by: string[];
+    }>;
+    in_progress: Array<{
+        milestone_id: string;
+        title: string;
+    }>;
+    pick: ScheduleEntry[];
+    reason: string;
+    cycle: string[] | null;
+};
+/**
+ * WSJF cost-of-delay weights (ID-M5-01). Fixed integer constants — the ordering
+ * is intentional: a shipped-but-regressed milestone is user-facing breakage
+ * (most urgent) > a milestone blocking many downstream ones > a milestone with
+ * more open value locked behind it > a human-declared priority nudge.
+ */
+export const W_REGRESS: 5;
+export const W_BLOCK: 3;
+export const W_VALUE: 2;
+/** The default WIP cap when neither a flag nor config supplies one (ID-M5-05). */
+export const DEFAULT_WIP_LIMIT: 1;
+/**
+ * A ranked ready-queue entry with its WSJF terms exposed.
+ */
+export type ScheduleEntry = {
+    milestone_id: string;
+    title: string;
+    status: string;
+    wsjf: number;
+    cost_of_delay: number;
+    job_size: number;
+    open_criteria: number;
+    blocking_count: number;
+    priority: number;
+    regressed: boolean;
+};
+//# sourceMappingURL=scheduler.d.mts.map

package/dist/cli/produce/scheduler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.mts","sourceRoot":"","sources":["../../../src/cli/produce/scheduler.mjs"],"names":[],"mappings":"AAuEA;;;;;;;;;GASG;AACH,4CAJW,MAAM,SACN,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GACxB,MAAM,CAelB;AAED;;;;;;;;;;;GAWG;AACH,8CAJW,MAAM,SACN,MAAM,GACJ,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAqBxF;AAED;;;;;;GAMG;AACH,gGAHW;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3F,MAAM,CAclB;AAED;;;;;;;GAOG;AACH,gEAHW;IAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD,MAAM,CAMlB;AAED;;;;;;;GAOG;AACH,yCAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;GAUG;AACH,oDALW,MAAM,SACN,MAAM,eACN,MAAM,GACJ,OAAO,CAgBnB;AAED;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4CAhBW,MAAM,SACN,MAAM,iBACN;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnB;IACR,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC9E,WAAW,EAAE,KAAK,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACxB,CA6GH;AA1TD;;;;;GAKG;AACH,wBAAyB,CAAC,CAAA;AAC1B,sBAAuB,CAAC,CAAA;AACxB,sBAAuB,CAAC,CAAA;AAExB,kFAAkF;AAClF,gCAAiC,CAAC,CAAA;;;;;kBA4JpB,MAAM;WACN,MAAM;YACN,MAAM;UACN,MAAM;mBACN,MAAM;cACN,MAAM;mBACN,MAAM;oBACN,MAAM;cACN,MAAM;eACN,OAAO"}