@aperant/framework 0.17.0 → 0.19.0

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

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

package/src/cli/roadmap/showrunner-view.d.ts

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

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

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

package/dist/cli/roadmap/conductor-view.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"conductor-view.d.mts","sourceRoot":"","sources":["../../../src/cli/roadmap/conductor-view.mjs"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,uDAHW,MAAM,GACJ;IAAE,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAAE,CAUlE"}

package/dist/cli/roadmap/conductor-view.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"conductor-view.mjs","sourceRoot":"","sources":["../../../src/cli/roadmap/conductor-view.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,WAAW;IACpD,MAAM,MAAM,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAA;IAC7C,MAAM,GAAG,GAAG,EAAE,CAAA;IACd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,mBAAmB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAA;QACvD,IAAI,OAAO,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAA;AACvB,CAAC"}

package/src/cli/roadmap/conductor-view.d.ts

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