@aperant/framework 0.16.0 → 0.19.0

package/src/cli/produce/done-gate.mjs

@@ -0,0 +1,238 @@
+/**
+ * @internal
+ * produce/done-gate.mjs — the real two-gate done adjudication + canary (M2,
+ * ID-M2-04 / AC8-AC11).
+ *
+ * A milestone flips to `done` ONLY when the VISIBLE oracle AND the BLIND probe
+ * both agree — otherwise it stays open and the reward-hacking canary logs the
+ * gap. The Showrunner still cannot self-attest: `done` is reachable ONLY through
+ * recorded external evidence + a blind cross-family probe (ID-03 preserved). Any
+ * missing / same-family / stale seal fails closed.
+ *
+ * The CLI is deterministic — it reads recorded evidence (verify-proof's verdict
+ * file + the recorded `produce.oracle.judged` / `produce.probe.run` /
+ * `produce.probe.frozen` seals) and computes the gate. The (LLM) oracle-judge +
+ * probe-run steps are driven cross-family by the skill; the CLI records + gates.
+ */
+
+import {
+	appendProduceEvent,
+	readImplementerFamily,
+	readProduceRunEventsMatching,
+} from './events.mjs'
+import { prepareOracleInput } from './evidence-oracle.mjs'
+import { normalizeFamily } from './probe-family.mjs'
+import { projectRoadmap, writeProjectionCache } from './projection.mjs'
+
+/** The last event matching `matchOp` for a milestone, or null. */
+function latestForMilestone(projectDir, runId, milestoneId, matchOp) {
+	const events = readProduceRunEventsMatching(projectDir, runId, matchOp)
+	let last = null
+	for (const e of events) {
+		if (e.data && e.data.milestone_id === milestoneId) last = e
+	}
+	return last
+}
+
+/** Whether any event matching `matchOp` (with a cross-family predicate) exists. */
+function anyForMilestone(projectDir, runId, milestoneId, matchOp, predicate) {
+	const events = readProduceRunEventsMatching(projectDir, runId, matchOp)
+	return events.some((e) => e.data && e.data.milestone_id === milestoneId && predicate(e.data))
+}
+
+/**
+ * Evaluate the RECORDED gate seals for a milestone (no verify-proof file read —
+ * that live half is added by `adjudicateDone`). Pure read.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {string} milestoneId
+ * @returns {{
+ *   implementer_family: string | null,
+ *   oracle_pass_cross_family: boolean,
+ *   probe_pass_cross_family: boolean,
+ *   frozen_cross_family: boolean,
+ *   blind_gate: boolean,
+ * }}
+ */
+export function evaluateRecordedGates(projectDir, runId, milestoneId) {
+	const implementer = readImplementerFamily(projectDir, runId, milestoneId)
+	const impl = implementer ? normalizeFamily(implementer) : null
+
+	const oracle = latestForMilestone(
+		projectDir,
+		runId,
+		milestoneId,
+		(op) => op === 'produce.oracle.judged',
+	)
+	const oracle_pass_cross_family =
+		!!impl &&
+		!!oracle &&
+		oracle.data.verdict === 'pass' &&
+		normalizeFamily(oracle.data.oracle_family) !== impl
+
+	const probeRun = latestForMilestone(
+		projectDir,
+		runId,
+		milestoneId,
+		(op) => op === 'produce.probe.run',
+	)
+	const probe_pass_cross_family =
+		!!impl &&
+		!!probeRun &&
+		probeRun.data.result === 'pass' &&
+		normalizeFamily(probeRun.data.probe_family) !== impl
+
+	const frozen_cross_family =
+		!!impl &&
+		anyForMilestone(
+			projectDir,
+			runId,
+			milestoneId,
+			(op) => op === 'produce.probe.frozen',
+			(d) => normalizeFamily(d.author_family) !== impl,
+		)
+
+	return {
+		implementer_family: implementer,
+		oracle_pass_cross_family,
+		probe_pass_cross_family,
+		frozen_cross_family,
+		blind_gate: probe_pass_cross_family && frozen_cross_family,
+	}
+}
+
+/**
+ * Adjudicate a milestone `done` (ID-M2-04). `done` accepted iff:
+ *   visible_gate = verify-proof verdict === 'approved' AND recorded
+ *     produce.oracle.judged.verdict === 'pass' with oracle_family !== implementer;
+ *   blind_gate = recorded produce.probe.run.result === 'pass' with
+ *     probe_family !== implementer AND a produce.probe.frozen exists with
+ *     author_family !== implementer.
+ * visible && blind → append produce.oracle.verdict{done} +
+ *   produce.roadmap.milestone_status_changed{done} + refresh the cache → ok.
+ * visible && !blind → append produce.oracle.probe_gap → err (stays open).
+ * !visible → err not-adjudicable. Absent implementer → err fail-closed.
+ *
+ * @param {{ projectDir: string, runId: string, milestoneId: string, verdictPath: string }} args
+ * @returns {{ ok: true, milestone_id: string, roadmap: object }
+ *   | { ok: false, reason: string, visible_gate: boolean, blind_gate: boolean, detail?: object }}
+ */
+export function adjudicateDone({ projectDir, runId, milestoneId, verdictPath }) {
+	const gates = evaluateRecordedGates(projectDir, runId, milestoneId)
+	if (!gates.implementer_family)
+		return { ok: false, reason: 'no_recorded_implementer', visible_gate: false, blind_gate: false }
+
+	// The live half of the visible gate: verify-proof's v2 verdict === 'approved'.
+	const prepared = prepareOracleInput(verdictPath)
+	const visible_gate = prepared.approved && gates.oracle_pass_cross_family
+	const blind_gate = gates.blind_gate
+
+	if (!visible_gate)
+		return {
+			ok: false,
+			reason: 'not_adjudicable',
+			visible_gate,
+			blind_gate,
+			detail: {
+				verify_proof_verdict: prepared.verdict,
+				verify_proof_approved: prepared.approved,
+				oracle_pass_cross_family: gates.oracle_pass_cross_family,
+			},
+		}
+
+	if (!blind_gate) {
+		// Visible passed, blind failed — the reward-hacking near-miss. Log the
+		// canary event; the milestone STAYS OPEN (AC9).
+		appendProduceEvent(projectDir, 'produce.oracle.probe_gap', {
+			run_id: runId,
+			milestone_id: milestoneId,
+		})
+		return {
+			ok: false,
+			reason: 'probe_gap',
+			visible_gate,
+			blind_gate,
+			detail: {
+				probe_pass_cross_family: gates.probe_pass_cross_family,
+				frozen_cross_family: gates.frozen_cross_family,
+			},
+		}
+	}
+
+	// Both gates agree — the ONLY path to done. Record the verdict + flip status.
+	appendProduceEvent(projectDir, 'produce.oracle.verdict', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		verdict: 'done',
+	})
+	appendProduceEvent(projectDir, 'produce.roadmap.milestone_status_changed', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		status: 'done',
+	})
+	const roadmap = writeProjectionCache(projectDir, runId)
+	return { ok: true, milestone_id: milestoneId, roadmap }
+}
+
+/**
+ * The reward-hacking canary (ID-M2-06 / AC10): green-on-visible MINUS
+ * green-on-blind over the run's milestones, from RECORDED seals. Each
+ * `produce.oracle.probe_gap` is one visible-pass + blind-fail near-miss. The
+ * metric surfaces the divergence — it does not average it away.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{
+ *   run_id: string,
+ *   green_on_visible: number,
+ *   green_on_blind: number,
+ *   gap: number,
+ *   probe_gap_events: number,
+ *   per_milestone: Array<{ milestone_id: string, title: string, status: string, visible: boolean, blind: boolean, probe_gaps: number }>,
+ * }}
+ */
+export function computeCanary(projectDir, runId) {
+	const roadmap = projectRoadmap(projectDir, runId)
+	const gapEvents = readProduceRunEventsMatching(
+		projectDir,
+		runId,
+		(op) => op === 'produce.oracle.probe_gap',
+	)
+	const gapCountByMilestone = new Map()
+	for (const e of gapEvents) {
+		const id = e.data && typeof e.data.milestone_id === 'string' ? e.data.milestone_id : null
+		if (id) gapCountByMilestone.set(id, (gapCountByMilestone.get(id) || 0) + 1)
+	}
+
+	let greenOnVisible = 0
+	let greenOnBlind = 0
+	const perMilestone = roadmap.milestones.map((m) => {
+		const gates = evaluateRecordedGates(projectDir, runId, m.id)
+		// The recorded (append-log) half of the visible gate — a recorded
+		// cross-family oracle pass. In the production flow the oracle is recorded
+		// only after verify-proof `approved` (the skill gates `oracle prepare` on
+		// it), so this is the durable visible-gate signal for the canary.
+		const visible = gates.oracle_pass_cross_family
+		const blind = gates.blind_gate
+		if (visible) greenOnVisible += 1
+		if (blind) greenOnBlind += 1
+		return {
+			milestone_id: m.id,
+			title: m.title,
+			status: m.status,
+			visible,
+			blind,
+			probe_gaps: gapCountByMilestone.get(m.id) || 0,
+		}
+	})
+
+	return {
+		run_id: runId,
+		green_on_visible: greenOnVisible,
+		green_on_blind: greenOnBlind,
+		gap: greenOnVisible - greenOnBlind,
+		probe_gap_events: gapEvents.length,
+		per_milestone: perMilestone,
+	}
+}

package/src/cli/produce/events.mjs

@@ -0,0 +1,131 @@
+/**
+ * @internal
+ * produce/events.mjs — append + read the run-scoped produce event trail (M1).
+ *
+ * Writes go through `createCoordinationStore(dir).appendEvent` → the O_APPEND
+ * `.aperant/events/*.jsonl` log, schema-gated by event-schema.mjs (ID-04). The
+ * append is atomic across concurrent writers (POSIX O_APPEND under PIPE_BUF),
+ * so N parallel `add-milestone` writers never lose updates (parent TD-06).
+ *
+ * Reads fold the run's `produce.roadmap.*` events across the day buckets from
+ * the run's start day (setpoint.json.frozen_at) to today (UTC), filtered by
+ * `data.run_id`. Bounded + deterministic (ID-06).
+ */
+
+import { readLifecycleEventsForDay } from '../coordination/event-log.mjs'
+import { createCoordinationStore } from '../coordination/store.mjs'
+import { resolveRunDir } from './run-id.mjs'
+import { readSetpoint } from './setpoint.mjs'
+
+/** The op-prefix the projection folds. */
+export const ROADMAP_OP_PREFIX = 'produce.roadmap.'
+
+/**
+ * Append one produce event through the schema-gated, O_APPEND coordination
+ * store. `data.run_id` also tags the event's top-level `task` field so the
+ * forensic trail is queryable by run. Returns the store's append result (null
+ * on schema violation — fail-closed).
+ *
+ * @param {string} projectDir
+ * @param {string} op
+ * @param {Record<string, unknown>} data
+ */
+export function appendProduceEvent(projectDir, op, data) {
+	const store = createCoordinationStore(projectDir)
+	const runId = data && typeof data.run_id === 'string' ? data.run_id : null
+	return store.appendEvent({ op, task: runId, data: data || {} })
+}
+
+/** Inclusive list of 'YYYY-MM-DD' UTC day buckets from startDay to endDay. */
+function dayBucketsInclusive(startDay, endDay) {
+	const cur = new Date(`${startDay}T00:00:00.000Z`)
+	const end = new Date(`${endDay}T00:00:00.000Z`)
+	// Inverted / malformed range → just today's bucket (defensive).
+	if (Number.isNaN(cur.getTime()) || Number.isNaN(end.getTime()) || cur > end) return [endDay]
+	const out = []
+	while (cur <= end) {
+		out.push(cur.toISOString().slice(0, 10))
+		cur.setUTCDate(cur.getUTCDate() + 1)
+		// Safety cap — a real run's window is days, not a decade.
+		if (out.length > 3660) break
+	}
+	return out
+}
+
+/**
+ * Fold the run's produce events matching `opMatches(op)` in chronological
+ * (append) order. The window starts at the setpoint's frozen day and ends today
+ * (UTC). Events are filtered to `data.run_id === runId`.
+ *
+ * This is the shared reader over the run's day-bucket window. `matchOp` selects
+ * which produce ops to fold — the roadmap projection folds ONLY the
+ * `produce.roadmap.*` prefix (see `readProduceEventsForRun`), while the M2
+ * oracle/probe consumers select `produce.milestone.implemented` /
+ * `produce.probe.*` / `produce.oracle.*`. It reads ONLY the append-only event
+ * log — it NEVER opens the frozen probe-content file (probe-blindness, ID-M2-03).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {(op: string) => boolean} matchOp
+ * @returns {Array<{ op: string, data: Record<string, unknown>, t?: string }>}
+ */
+export function readProduceRunEventsMatching(projectDir, runId, matchOp) {
+	const setpoint = readSetpoint(resolveRunDir(projectDir, runId))
+	const today = new Date().toISOString().slice(0, 10)
+	const startDay =
+		setpoint && typeof setpoint.frozen_at === 'string' ? setpoint.frozen_at.slice(0, 10) : today
+	const out = []
+	for (const day of dayBucketsInclusive(startDay, today)) {
+		for (const e of readLifecycleEventsForDay(projectDir, day)) {
+			if (typeof e.op !== 'string') continue
+			if (!matchOp(e.op)) continue
+			if (!e.data || e.data.run_id !== runId) continue
+			out.push(e)
+		}
+	}
+	return out
+}
+
+/**
+ * Fold the run's `produce.roadmap.*` events in chronological (append) order.
+ * The projection consumes ONLY this reader, so the roadmap the Showrunner
+ * re-reads each tick can never surface a `produce.probe.*` / `produce.oracle.*`
+ * event (structural probe-blindness, AC5).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {Array<{ op: string, data: Record<string, unknown>, t?: string }>}
+ */
+export function readProduceEventsForRun(projectDir, runId) {
+	return readProduceRunEventsMatching(projectDir, runId, (op) => op.startsWith(ROADMAP_OP_PREFIX))
+}
+
+/**
+ * Read the recorded implementer family for a run + milestone from the
+ * append-only `produce.milestone.implemented` trail (ID-M2-02 — the recorded
+ * disjointness anchor the cross-family rule is enforced against). Returns the
+ * LATEST recorded `implementer_family` for the milestone, or null when none is
+ * recorded (fail-closed — you cannot enforce disjointness against an unknown
+ * implementer).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {string} milestoneId
+ * @returns {string | null}
+ */
+export function readImplementerFamily(projectDir, runId, milestoneId) {
+	const events = readProduceRunEventsMatching(
+		projectDir,
+		runId,
+		(op) => op === 'produce.milestone.implemented',
+	)
+	let family = null
+	for (const e of events) {
+		const d = e.data || {}
+		if (d.milestone_id !== milestoneId) continue
+		if (typeof d.implementer_family === 'string' && d.implementer_family.length > 0) {
+			family = d.implementer_family
+		}
+	}
+	return family
+}

package/src/cli/produce/evidence-oracle.mjs

@@ -0,0 +1,133 @@
+/**
+ * @internal
+ * produce/evidence-oracle.mjs — the independent evidence-quality oracle (M2, AC7).
+ *
+ * verify-proof issues a deterministic two-gate verdict over captured evidence;
+ * the evidence-oracle is a SECOND opinion — a cross-family judge deciding
+ * whether that captured evidence actually supports "done" (US-3 / ID-06). The
+ * CLI is deterministic: `prepareOracleInput` extracts the verdict + the tests[]
+ * evidence into a structured judge payload the skill sends to the cross-family
+ * model; `recordOracleVerdict` records the judge's pass/fail, refusing
+ * fail-closed when the oracle family equals the implementer family (the oracle
+ * that judged the work must not be the family that produced it — ID-08).
+ *
+ * The verify-proof verdict is read as the v2 closed-set `approved` ONLY
+ * (ID-M2-05): a legacy middle-band verdict, `needs_human`, `rejected`, or a
+ * missing/unreadable artifact is NOT `approved` → not adjudicable (fail-closed).
+ */
+
+import { readJsonIfExists } from '../util/io.mjs'
+import { appendProduceEvent, readImplementerFamily } from './events.mjs'
+import { normalizeFamily } from './probe-family.mjs'
+
+/** The single verdict verify-proof v2 treats as a pass (ID-M2-05). */
+const APPROVED = 'approved'
+
+/**
+ * Read verify-proof's `verification.json` at `verdictPath` and extract the
+ * v2 verdict + the tests[] {surface, evidence, result} rows into a structured
+ * judge-input payload. The verdict is read from `meta.verdict` (or a top-level
+ * `verdict`) and must be EXACTLY `approved` — anything else (or a
+ * missing/unreadable artifact) is NOT approved (fail-closed).
+ *
+ * @param {string} verdictPath — absolute/relative path to verification.json.
+ * @returns {{
+ *   ok: boolean,
+ *   approved: boolean,
+ *   verdict: string | null,
+ *   reason: string | null,
+ *   tests: Array<{ id: string | null, surface: string | null, evidence: string | null, result: string | null }>,
+ *   judge_input: { verdict: string | null, task_id: string | null, spec: string | null, tests: Array<object> } | null,
+ * }}
+ */
+export function prepareOracleInput(verdictPath) {
+	if (!verdictPath)
+		return {
+			ok: false,
+			approved: false,
+			verdict: null,
+			reason: 'no_verdict_path',
+			tests: [],
+			judge_input: null,
+		}
+
+	const doc = readJsonIfExists(verdictPath)
+	if (!doc || typeof doc !== 'object')
+		return {
+			ok: false,
+			approved: false,
+			verdict: null,
+			reason: 'verdict_unreadable',
+			tests: [],
+			judge_input: null,
+		}
+
+	const meta = doc.meta && typeof doc.meta === 'object' ? doc.meta : {}
+	const verdict =
+		typeof meta.verdict === 'string'
+			? meta.verdict
+			: typeof doc.verdict === 'string'
+				? doc.verdict
+				: null
+
+	const tests = Array.isArray(doc.tests)
+		? doc.tests.map((t) => ({
+				id: t && typeof t.id === 'string' ? t.id : null,
+				surface: t && typeof t.surface === 'string' ? t.surface : null,
+				evidence: t && typeof t.evidence === 'string' ? t.evidence : null,
+				result: t && typeof t.result === 'string' ? t.result : null,
+			}))
+		: []
+
+	// EXACTLY `approved` — the legacy middle-band verdict is NOT
+	// approved (verify-proof v2 deleted it; ID-M2-05).
+	const approved = verdict === APPROVED
+
+	return {
+		ok: approved,
+		approved,
+		verdict,
+		reason: approved ? null : 'verdict_not_approved',
+		tests,
+		judge_input: {
+			verdict,
+			task_id: typeof meta.task_id === 'string' ? meta.task_id : null,
+			spec: typeof meta.spec === 'string' ? meta.spec : null,
+			tests,
+		},
+	}
+}
+
+/**
+ * Record the independent evidence-quality oracle's verdict. REFUSES fail-closed
+ * when the oracle family equals the recorded implementer family (cross-family
+ * enforcement, ID-08) or when no implementer family is recorded (ID-M2-02). On
+ * acceptance appends `produce.oracle.judged {run_id, milestone_id, verdict,
+ * oracle_family}`.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, verdict: string, oracleFamily: string }} args
+ * @returns {{ ok: true, verdict: string, oracle_family: string, implementer_family: string }
+ *   | { ok: false, reason: string, implementer_family?: string | null }}
+ */
+export function recordOracleVerdict(projectDir, { runId, milestoneId, verdict, oracleFamily }) {
+	if (verdict !== 'pass' && verdict !== 'fail') return { ok: false, reason: 'invalid_verdict' }
+	if (!oracleFamily) return { ok: false, reason: 'no_oracle_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(oracleFamily) === normalizeFamily(implementerFamily))
+		return { ok: false, reason: 'same_family_oracle', implementer_family: implementerFamily }
+
+	appendProduceEvent(projectDir, 'produce.oracle.judged', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		verdict,
+		oracle_family: oracleFamily,
+	})
+
+	return { ok: true, verdict, oracle_family: oracleFamily, implementer_family: implementerFamily }
+}