@aperant/framework 0.6.4 → 0.6.6

package/src/cli/coordination/auto-emit-artifact-ready.mjs

@@ -0,0 +1,96 @@
+/**
+ * @internal
+ * auto-emit-artifact-ready.mjs — code-enforced plan-ready signal.
+ *
+ * Promotes the `artifact.ready{kind:'plan'}` emit from a markdown contract
+ * in `skills/apt-plan/adapters/conductor.md` to a framework-level
+ * postcondition of `apt-tools commit`. This closes the Conductor v2 gap
+ * exposed during live verification 2026-05-15: the planner's QUICK /
+ * SIMPLE track is hard-exempt from "new interaction discipline"
+ * (Pocock Fast Path Guarantee ID-05), so the markdown emit step was
+ * never executed for tasks router-classified as simple. The fleet
+ * never saw artifact.ready, the PlanReadyCard never auto-promoted.
+ *
+ * The fix lives in `framework` rather than the skill so:
+ *   - it works for QUICK + STANDARD + DEEP + COMPLEX uniformly
+ *   - it doesn't violate the Fast Path Guarantee (a passive log emit
+ *     is not interaction discipline)
+ *   - it's the same code path every CLI consumer (Claude Code, Gemini,
+ *     OpenCode, Codex) traverses via `apt-tools commit`
+ *
+ * Conditions for emit (ALL must hold — otherwise no-op):
+ *   1. `APERANT_TERMINAL_ID` is set in process.env (Conductor PTY context).
+ *   2. The committed files include a path matching
+ *      `.aperant/tasks/{task-id}/implementation_plan.json`.
+ *
+ * The emit re-uses the same `event-schema` validator and JSONL writer
+ * `commands/event.mjs` already uses, so the envelope structure stays
+ * byte-identical with manually-emitted ones.
+ */
+
+import { createHash } from 'node:crypto'
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs'
+import { hostname } from 'node:os'
+import { join } from 'node:path'
+import { validateConductorEvent } from './event-schema.mjs'
+
+const PLAN_PATH_RE = /^(?:\.\/)?\.aperant\/tasks\/([^/]+)\/implementation_plan\.json$/
+
+let _incarnationCounter = 0
+
+/**
+ * @param {{ files: string[], projectRoot: string }} input
+ * @returns {{ emitted: false, reason: string } | { emitted: true, envelope: object, file: string }}
+ */
+export function maybeAutoEmitPlanReady({ files, projectRoot }) {
+	const terminalId = process.env.APERANT_TERMINAL_ID
+	if (!terminalId) return { emitted: false, reason: 'APERANT_TERMINAL_ID unset' }
+
+	const match = files.map((f) => f.replace(/\\/g, '/').match(PLAN_PATH_RE)).find((m) => m !== null)
+	if (!match) return { emitted: false, reason: 'no implementation_plan.json in committed files' }
+	const taskId = match[1]
+
+	const planRelPath = `.aperant/tasks/${taskId}/implementation_plan.json`
+	const absolutePath = join(projectRoot, planRelPath)
+
+	let hash
+	try {
+		const body = readFileSync(absolutePath)
+		hash = createHash('sha256').update(body).digest('hex')
+	} catch (err) {
+		return { emitted: false, reason: `plan file unreadable: ${(err && err.message) || err}` }
+	}
+
+	const data = {
+		kind: 'plan',
+		path: planRelPath,
+		hash,
+		request_id: `plan-${taskId}-${Date.now()}`,
+		task_id: taskId,
+		terminal_id: terminalId,
+	}
+
+	const validation = validateConductorEvent('artifact.ready', data)
+	if (!validation.ok) {
+		return { emitted: false, reason: `schema violation: ${validation.error}` }
+	}
+
+	const envelope = {
+		t: new Date().toISOString(),
+		agent: `${hostname()}-${process.pid}`,
+		pid: process.pid,
+		hostname: hostname(),
+		incarnation: ++_incarnationCounter,
+		op: 'artifact.ready',
+		task: taskId,
+		data,
+	}
+
+	const eventsDir = join(projectRoot, '.aperant', 'events')
+	mkdirSync(eventsDir, { recursive: true })
+	const dayFile = `${new Date().toISOString().slice(0, 10)}.jsonl`
+	const fullPath = join(eventsDir, dayFile)
+	appendFileSync(fullPath, `${JSON.stringify(envelope)}\n`, 'utf-8')
+
+	return { emitted: true, envelope, file: dayFile }
+}

package/src/cli/coordination/event-log.mjs

@@ -8,8 +8,19 @@
  * multiple processes running `task update` / `task close` cannot tear each
  * other's lines.
  *
- * This module is `@internal` — consumed only through the CoordinationStore
- * seam (store.appendEvent). Do NOT import from bin/apt-tools.mjs.
+ * Consumption policy:
+ *   - WRITES go through the CoordinationStore seam (`store.appendEvent`).
+ *     This is the policy boundary — concurrent writers must coordinate.
+ *   - READ-ONLY helpers (`readLifecycleEventsForDay`,
+ *     `findMostRecentEventForTask`, `readTaskEventsOverDays`) MAY be
+ *     imported directly. They do not mutate state and the event log is
+ *     append-only, so a stale read is the worst case and is bounded by
+ *     "the next read picks up new appends." Direct read imports keep the
+ *     R6 telemetry surface (PR #115) out of the store seam, which is
+ *     scoped to coordination primitives.
+ *
+ * Do NOT import this module from bin/apt-tools.mjs directly. CLI commands
+ * import the helpers above via their command modules.
  *
  * The existing numbered-JSON event surface in commands/event.mjs is NOT
  * touched — its `rebuild-state` consumer keeps working. The JSONL log is
@@ -86,3 +97,63 @@ export function readLifecycleEventsForDay(projectRoot, day = todayBucket()) {
 	}
 	return out
 }
+
+/**
+ * Read events for a task across the today + yesterday UTC day buckets,
+ * sorted ascending by `t`. Optionally filtered to events whose `op` starts
+ * with `opPrefix`. Covers tasks that span a UTC day boundary without
+ * globbing the whole `.aperant/events/` directory.
+ *
+ * Read-only — does NOT mutate state. Per the original `@internal` policy
+ * this module is reached via `store.appendEvent` for WRITES, but read-only
+ * helpers like this one (and `readLifecycleEventsForDay`) are direct
+ * imports because there is no state to coordinate (PR #115 review finding
+ * FIT-001 — comment updated accordingly).
+ *
+ * @internal
+ */
+export function readTaskEventsOverDays(projectRoot, taskId, opPrefix = null) {
+	function filterAndPush(events, into) {
+		for (const e of events) {
+			if (e.task !== taskId) continue
+			if (opPrefix && e.op !== opPrefix && !e.op.startsWith(opPrefix)) continue
+			into.push(e)
+		}
+	}
+	const today = todayBucket()
+	const yesterday = new Date()
+	yesterday.setUTCDate(yesterday.getUTCDate() - 1)
+	const yest = yesterday.toISOString().slice(0, 10)
+	const out = []
+	// Yesterday first so the combined array stays chronological.
+	filterAndPush(readLifecycleEventsForDay(projectRoot, yest), out)
+	filterAndPush(readLifecycleEventsForDay(projectRoot, today), out)
+	return out
+}
+
+/**
+ * Find the most recent event matching `taskId`, optionally filtered to events
+ * whose `op` starts with `opPrefix`. Looks at today's bucket first; only
+ * reads yesterday's bucket on a today-miss — keeps the common case to a
+ * single file read.
+ *
+ * Used by R6 telemetry to compute `elapsed_ms` between lifecycle transitions
+ * (roundtable 2026-05-14). Returns null when no matching event is found.
+ *
+ * @internal
+ */
+export function findMostRecentEventForTask(projectRoot, taskId, opPrefix = null) {
+	function search(events) {
+		const filtered = events.filter(
+			(e) => e.task === taskId && (!opPrefix || e.op === opPrefix || e.op.startsWith(opPrefix)),
+		)
+		return filtered.length > 0 ? filtered[filtered.length - 1] : null
+	}
+	const today = todayBucket()
+	const todayMatch = search(readLifecycleEventsForDay(projectRoot, today))
+	if (todayMatch) return todayMatch
+	const yesterday = new Date()
+	yesterday.setUTCDate(yesterday.getUTCDate() - 1)
+	const yest = yesterday.toISOString().slice(0, 10)
+	return search(readLifecycleEventsForDay(projectRoot, yest))
+}

package/src/cli/coordination/event-schema.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Type declarations for the .mjs validator. Hand-authored because the
+ * import path points at src/.mjs directly (no dist roundtrip).
+ */
+
+export type ValidateResult = { ok: true } | { ok: false; error: string }
+
+export function validateConductorEvent(
+	op: string,
+	data: Record<string, unknown> | undefined | null,
+): ValidateResult
+
+export const CONDUCTOR_VALIDATED_OPS: ReadonlySet<string>

package/src/cli/coordination/event-schema.mjs

@@ -0,0 +1,174 @@
+/**
+ * @internal
+ * event-schema.mjs — single source of truth for conductor event payload shapes.
+ *
+ * Why this lives in `framework`, not `core`:
+ *   `packages/core` depends on `@aperant/framework`. The schema is shared by
+ *   the CLI write path (`commands/event.mjs`), the framework lifecycle write
+ *   seam (`coordination/store.mjs:appendEvent`), and the core IPC write seam
+ *   (`packages/core/src/runtime/orchestration/conductor/event-log.ts`).
+ *   Putting it in the lower layer keeps a single rule table that every
+ *   writer can import.
+ *
+ * Shape: zero-dep plain JS validator returning a `{ ok, error? }` result.
+ *   We deliberately avoid zod here so `.mjs` callers (event.mjs, store.mjs)
+ *   don't need a build step, and so the core TS writer can use the same
+ *   identity-shaped result without translating between zod and a custom
+ *   error type.
+ *
+ * Per Codex roundtable lock 2026-05-15:
+ *   - `phase.changed` is reserved for PTY busy/idle transitions ONLY.
+ *     Plan completion uses `artifact.ready{kind:'plan'}`, not phase.changed.
+ *   - `awaiting-input` / `input-rescinded` MUST carry both terminal_id and
+ *     request_id so the drawer can pair cards strictly.
+ *   - `artifact.ready{kind:'plan'}` is the canonical plan-completion signal
+ *     consumed by the conductor's reviewer queue (Step 5's reviewPlan tool).
+ */
+
+/** Conductor ops the schema enforces. Other ops pass through unchanged. */
+const CONDUCTOR_OPS = new Set([
+	'phase.changed',
+	'artifact.ready',
+	'awaiting-input',
+	'input-rescinded',
+	'heartbeat',
+	'budget.exceeded',
+	'terminal.enrolled',
+	'terminal.unenrolled',
+	'conductor.intent',
+	'conductor.cross_check',
+	'conductor.realignment',
+	// c-4 (action-capable) — gate verdict + boot-replay audit trail
+	'conductor.action.executed',
+	'conductor.action.gate_blocked',
+	'conductor.boot_reconciled',
+])
+
+/** Allowed values for `phase.changed.to` — PTY busy/idle only. */
+const ALLOWED_PHASE_VALUES = new Set(['busy', 'idle'])
+
+/** Allowed values for `artifact.ready.kind`. */
+const ALLOWED_ARTIFACT_KINDS = new Set(['plan', 'spec', 'build', 'review'])
+
+/**
+ * Validate the data payload of a conductor event against the op's contract.
+ *
+ * @param {string} op
+ * @param {Record<string, unknown> | undefined | null} data
+ * @returns {{ ok: true } | { ok: false, error: string }}
+ */
+export function validateConductorEvent(op, data) {
+	if (!CONDUCTOR_OPS.has(op)) return { ok: true }
+	const d = data && typeof data === 'object' ? data : {}
+
+	switch (op) {
+		case 'awaiting-input':
+		case 'input-rescinded':
+			return requireFields(op, d, ['terminal_id', 'request_id'])
+
+		case 'phase.changed': {
+			const r = requireFields(op, d, ['from', 'to', 'terminal_id', 'request_id'])
+			if (!r.ok) return r
+			if (!ALLOWED_PHASE_VALUES.has(String(d.to))) {
+				return {
+					ok: false,
+					error: `phase.changed.to must be one of [${[...ALLOWED_PHASE_VALUES].join(', ')}], got: ${String(
+						d.to,
+					)}. Plan completion must use artifact.ready{kind:'plan'}.`,
+				}
+			}
+			return { ok: true }
+		}
+
+		case 'artifact.ready': {
+			const r = requireFields(op, d, [
+				'kind',
+				'path',
+				'hash',
+				'request_id',
+				'terminal_id',
+				'task_id',
+			])
+			if (!r.ok) return r
+			if (!ALLOWED_ARTIFACT_KINDS.has(String(d.kind))) {
+				return {
+					ok: false,
+					error: `artifact.ready.kind must be one of [${[...ALLOWED_ARTIFACT_KINDS].join(
+						', ',
+					)}], got: ${String(d.kind)}`,
+				}
+			}
+			return { ok: true }
+		}
+
+		case 'conductor.intent':
+			return requireFields(op, d, ['terminal_id', 'request_id', 'action', 'reasoning'])
+
+		case 'conductor.cross_check':
+			return requireFields(op, d, ['terminal_id', 'request_id'])
+
+		case 'conductor.realignment': {
+			const r = requireFields(op, d, ['terminal_id', 'request_id_orig'])
+			if (!r.ok) return r
+			if (d.attempt_n === undefined || d.attempt_n === null)
+				return { ok: false, error: `${op} missing required field(s): attempt_n` }
+			return { ok: true }
+		}
+
+		case 'terminal.enrolled':
+		case 'terminal.unenrolled':
+		case 'heartbeat':
+		case 'budget.exceeded':
+			return requireFields(op, d, ['terminal_id'])
+
+		case 'conductor.action.executed':
+			return requireFields(op, d, ['terminal_id', 'request_id', 'action_kind', 'idempotency_key'])
+
+		case 'conductor.action.gate_blocked':
+			return requireFields(op, d, [
+				'terminal_id',
+				'request_id',
+				'action_kind',
+				'idempotency_key',
+				'blocked_reason',
+			])
+
+		case 'conductor.boot_reconciled': {
+			// Fleet-wide event — numeric fields only. All optional but if
+			// present must be finite numbers (zero allowed).
+			const numFields = ['cleaned_leases', 'replayed', 'start_offset']
+			for (const f of numFields) {
+				if (d[f] === undefined) continue
+				if (typeof d[f] !== 'number' || !Number.isFinite(d[f])) {
+					return {
+						ok: false,
+						error: `${op} field ${f} must be a finite number, got: ${String(d[f])}`,
+					}
+				}
+			}
+			return { ok: true }
+		}
+
+		default:
+			return { ok: true }
+	}
+}
+
+/** Set of ops the schema validates — exported for test enumeration. */
+export const CONDUCTOR_VALIDATED_OPS = CONDUCTOR_OPS
+
+/**
+ * @param {string} op
+ * @param {Record<string, unknown>} d
+ * @param {string[]} fields
+ * @returns {{ ok: true } | { ok: false, error: string }}
+ */
+function requireFields(op, d, fields) {
+	const missing = fields.filter((f) => {
+		const v = d[f]
+		if (typeof v !== 'string' || v.length === 0) return true
+		return false
+	})
+	if (missing.length === 0) return { ok: true }
+	return { ok: false, error: `${op} missing required field(s): ${missing.join(', ')}` }
+}

package/src/cli/coordination/store.mjs

@@ -32,6 +32,7 @@ import { withFileLock } from '../util/fs-lock.mjs'
 import { atomicWriteJson } from '../util/io.mjs'
 import { getAgentIdentity, resolveSharedRoot } from './agent-identity.mjs'
 import { appendLifecycleEvent } from './event-log.mjs'
+import { validateConductorEvent } from './event-schema.mjs'
 import {
 	listActive as teamStatusListActive,
 	removeSelf as teamStatusRemoveSelf,
@@ -128,9 +129,22 @@ export function createCoordinationStore(projectRoot) {
 		 * @internal — R10 append-only event log. Emits one JSONL line per
 		 * call via appendLifecycleEvent. Best-effort: filesystem errors are
 		 * swallowed so a missing events/ dir never breaks task lifecycle.
+		 *
+		 * Step 1 — schema gate: conductor ops written via the store seam are
+		 * validated against `event-schema.mjs` before they reach disk.
+		 * Schema violations throw (caught here and surfaced via console.warn)
+		 * because a malformed conductor event would silently break the
+		 * drawer's pairing logic — we want it loud, not best-effort.
 		 */
 		appendEvent(evt) {
 			try {
+				if (evt && typeof evt.op === 'string') {
+					const validation = validateConductorEvent(evt.op, evt.data)
+					if (!validation.ok) {
+						console.warn(`[store.appendEvent] schema violation: ${validation.error}`)
+						return null
+					}
+				}
 				return appendLifecycleEvent(projectRoot, evt)
 			} catch {
 				/* best-effort — never block a lifecycle transition on the log */

package/src/cli/dispatch.mjs

@@ -35,14 +35,17 @@
  */
 
 import { cmdActive } from './commands/active.mjs'
+import { cmdAdr } from './commands/adr.mjs'
 import { cmdAudit } from './commands/audit.mjs'
 import { cmdAuthorSkill } from './commands/author-skill.mjs'
 import { cmdBootstrap } from './commands/bootstrap.mjs'
 import { cmdCheck } from './commands/check.mjs'
 import { cmdCheckVersion } from './commands/check-version.mjs'
+import { cmdCiWatch } from './commands/ci-watch.mjs'
 import { cmdCommit } from './commands/commit.mjs'
 import { cmdConsistency } from './commands/consistency.mjs'
 import { cmdConstitution } from './commands/constitution.mjs'
+import { cmdContext } from './commands/context.mjs'
 import { cmdCoverageCheck } from './commands/coverage-check.mjs'
 import { cmdCreateDocs } from './commands/create-docs.mjs'
 import { cmdDesignLint } from './commands/design-lint.mjs'
@@ -83,6 +86,7 @@ import { cmdTerminal } from './commands/terminal.mjs'
 import { cmdTokenBudget } from './commands/token-budget.mjs'
 import { cmdTokens } from './commands/tokens.mjs'
 import { cmdToolchainDetect } from './commands/toolchain-detect.mjs'
+import { cmdTriage } from './commands/triage.mjs'
 import { cmdUninstall } from './commands/uninstall.mjs'
 import { cmdValidateEvidence } from './commands/validate-evidence.mjs'
 import { cmdVariantGallery } from './commands/variant-gallery.mjs'
@@ -231,7 +235,7 @@ export const DISPATCH = {
 	'author-skill': (args) => wrap(cmdAuthorSkill)(args[1], args.slice(2)),
 	'toolchain-detect': (args) => wrap(cmdToolchainDetect)(args[1], args.slice(2)),
 	'host-detect': () => wrap(cmdHostDetect)(),
-	reconcile: (args) => wrap(cmdReconcile)(args[1]),
+	reconcile: (args) => wrap(cmdReconcile)(args[1], args.slice(2)),
 	standards: (args) => wrap(cmdStandards)(args[1], args.slice(2)),
 	'precompact-hook': (args) => wrap(cmdPrecompactHook)(args[1]),
 	'migrate-pr-reviews': (args) => wrap(cmdMigratePrReviews)(args[1]),
@@ -255,8 +259,18 @@ export const DISPATCH = {
 	seed: (args) => wrap(cmdSeed)(args[1], args[2], args.slice(3)),
 	workflow: (args) => wrap(cmdWorkflow)(args[1], args[2], args.slice(3)),
 	'pr-review': (args) => wrap(cmdPrReview)(args[1], args[2], args.slice(3)),
+	'ci-watch': (args) => wrap(cmdCiWatch)(args[1], args[2], args.slice(3)),
 	'plan-approval': (args) => wrap(cmdPlanApproval)(args[1], args[2], args.slice(3)),
 
+	// ---- Pocock adoption (ST-5, ST-6, ST-10, ST-13) artifact writers + discoverability ----
+	context: (args) => wrap(cmdContext)(args[1], args[2], args.slice(3)),
+	adr: (args) => wrap(cmdAdr)(args[1], args[2], args.slice(3)),
+	triage: (args) => wrap(cmdTriage)(args[1], args[2], args.slice(3)),
+	modes: async (args) => {
+		const { cmdModes } = await import('./commands/modes.mjs')
+		return wrap(cmdModes)(args[1], args[2], args.slice(3))
+	},
+
 	// ---- async cmds — wrap() awaits internally; thrown errors → fail() ----
 	'docs-audit': (args) => wrap(cmdDocsAudit)(args[1], args.slice(2)),
 	gate: (args) => wrap(cmdGate)(args[1], args[2], args.slice(3)),

package/src/cli/gate/registry.mjs

@@ -101,3 +101,17 @@ export function getGate(id) {
 export function __resetRegistryForTests() {
 	registry.clear()
 }
+
+/**
+ * Test-only helper — uniformly-named alias for the in-process cmd harness
+ * (run-cmd.mjs). Built-in gates self-register via the `gates/index.mjs`
+ * barrel at module-import time, which ESM evaluates exactly once per
+ * process — so the harness deliberately does NOT call this by default
+ * (clearing here would leave subsequent cmd invocations looking at an empty
+ * registry). Tests that need an empty registry import this name explicitly.
+ *
+ * @internal
+ */
+export function __resetCaches() {
+	registry.clear()
+}

package/src/cli/help.mjs

@@ -28,9 +28,10 @@ Commands:
   task create <dir> --description <text> [--scope <s>] [--milestone <id>] [--phase <id>] [--roadmap-ref-url <url>] [--depends-on <refs>] [--track <T>] [--autonomy <N>]  Create isolated task
   task list <dir> [--scope <s>] [--blocked-by <id>]  List active tasks (optionally filtered)
   task get <dir> --id <task-id>         Get task details and artifacts
-  task update <dir> --id <id> [--lifecycle-phase <p>] [--subtasks-total <N>] [--depends-on <refs>]  Update non-linkage task state
+  task update <dir> --id <id> [--lifecycle-phase <p>] [--pr-url <url>] [--subtasks-total <N>] [--depends-on <refs>]  Update non-linkage task state; --pr-url may arm ci-watch per ci_watch.after_ship
   task move <dir> --id <id> [--to-scope <s>] [--to-milestone <id>] [--to-phase <id>] [--to-roadmap-ref-url <url>] [--reason <text>] [--force]  Reassign scope/milestone/phase with history
   task close <dir> --id <task-id> [--verdict <v>]  Close task and move to completed
+  task narration-drain <dir> --task <task-id>     Remove a row from state.pending_narration[] under withFileLock (called by /apt:close-task --narrate-only after a successful narrator spawn)
   task complete-subtask <dir> --task-id <id> --subtask-id <sid|a+b+c> [--commit <sha>] [--notes <text>]  Atomic plan ↔ build-progress sync
   features-audit <dir> [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files
   docs-audit <dir> [--diff-files <csv>|--since <ref>|--dry-run] [--policy <path>] [--format json|md]  Audit documented surfaces for docs-drift
@@ -130,5 +131,5 @@ Flags:
 
 All output is JSON.`
 
-	process.stdout.write(help + '\n')
+	process.stdout.write(`${help}\n`)
 }

package/src/cli/host/detect.mjs

@@ -193,6 +193,11 @@ export function detectHost(opts = {}) {
 		worktrees: isClaudeCode,
 		background_agents: isClaudeCode || isCodex,
 		structured_prompts: structuredPrompts,
+		// D-03 (post-ship CI watcher) — true for hosts that ship a native
+		// recurring-task primitive the watcher can delegate to (CC's CronCreate,
+		// Pi's pi-schedule-prompt). False elsewhere; on those hosts the user
+		// re-invokes `/apt:watch-ci --tick --pr N` manually.
+		cron: isClaudeCode || cli === 'pi',
 		// True when the framework can ask Electron to spawn a sibling Aperant
 		// terminal (with its own worktree + CLI) over the Unix-domain IPC socket.
 		// Requires TERM_PROGRAM=Aperant + APERANT_IPC_SOCKET to be set by the

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

@@ -0,0 +1,10 @@
+/**
+ * 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

package/src/cli/roadmap/conductor-view.mjs

@@ -0,0 +1,31 @@
+/**
+ * conductor-view.mjs — read-only roadmap surface for the Aperant
+ * Conductor's `getRoadmap` tool.
+ *
+ * Wraps `loadRoadmapForScope` + `listRoadmapScopes` so the Conductor 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.
+ */
+
+import { loadRoadmapForScope } from './io.mjs'
+import { listRoadmapScopes } from './paths.mjs'
+
+/**
+ * Build a flat per-scope roadmap snapshot for the Conductor.
+ *
+ * @param {string} projectRoot
+ * @returns {{ scopes: Array<{ scope: string, roadmap: unknown }> }}
+ */
+export function buildConductorRoadmapView(projectRoot) {
+	const scopes = listRoadmapScopes(projectRoot)
+	const out = []
+	for (const scope of scopes) {
+		const roadmap = loadRoadmapForScope(projectRoot, scope)
+		if (roadmap !== null) out.push({ scope, roadmap })
+	}
+	return { scopes: out }
+}