@aperant/framework 0.6.4 → 0.6.6

package/src/cli/commands/tokens.mjs

@@ -10,10 +10,12 @@
  *   - state.active_tasks[id].tokens   — flat rolled-up summary (downstream).
  *
  * Subcommands:
- *   record   — append one entry from a Claude Code transcript or manual --input/--output.
- *   tally    — emit a TaskCostSummary computed via CostTracker.
- *   compare  — emit { aperant, baseline, ratio } (baseline JSON optional; C23 hook).
- *   list     — scan all .aperant/tasks/{*}/tokens.json and emit a flat sorted list.
+ *   record         — append one entry from a Claude Code transcript or manual --input/--output.
+ *   tally          — emit a TaskCostSummary computed via CostTracker.
+ *   compare        — emit { aperant, baseline, ratio } (baseline JSON optional; C23 hook).
+ *   list           — scan all .aperant/tasks/{*}/tokens.json and emit a flat sorted list.
+ *   phase-summary  — join tokens.json × task.lifecycle.* events by phase
+ *                    (roundtable 2026-05-14 R6 — phase-boundary telemetry).
  *
  * All writes go through atomicWriteJson + withFileLock (R3), state mutations
  * through createCoordinationStore.updateState (R8), and a lifecycle event is
@@ -29,6 +31,7 @@ import { dirname, join, resolve } from 'node:path'
 import { calculateCost } from '../../cost/pricing.mjs'
 import { CostTracker } from '../../cost/tracker.mjs'
 import { parseClaudeCodeTranscript } from '../../cost/transcript.mjs'
+import { readTaskEventsOverDays } from '../coordination/event-log.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { atomicWriteJson } from '../util/io.mjs'
@@ -67,6 +70,12 @@ function nowIso() {
 /**
  * Convert the on-disk JSON entry shape (snake_case + cost_usd) into the
  * canonical CostEntry shape used by CostTracker (camelCase + costUsd).
+ *
+ * R6 (roundtable 2026-05-14): `phase` is an optional per-entry tag indicating
+ * which pipeline phase (planning | executing | verifying | reviewing) the
+ * session belonged to. Carried through to enable `tokens phase-summary` to
+ * group by phase. Older entries lacking `phase` keep working — the field is
+ * additive and downstream consumers tolerate `undefined`.
  */
 function entryToCostEntry(taskId, entry) {
 	return {
@@ -82,6 +91,7 @@ function entryToCostEntry(taskId, entry) {
 		costUsd: typeof entry.cost_usd === 'number' ? entry.cost_usd : 0,
 		timestamp: entry.timestamp,
 		durationMs: entry.duration_ms || 0,
+		phase: entry.phase || null,
 	}
 }
 
@@ -162,6 +172,20 @@ function cmdRecord(targetDir, args) {
 	// DEFAULT_MODEL because there's no transcript to source it from.
 	const modelOverride = flagOf(args, '--model')
 	const providerId = flagOf(args, '--provider') || DEFAULT_PROVIDER
+	// R6 (roundtable 2026-05-14): optional --phase tags this batch of entries
+	// with the lifecycle phase they belong to. When omitted, phase-summary
+	// falls back to inferring phase from lifecycle event timestamps.
+	//
+	// SEC-001 (PR #115 review): whitelist accepted values to keep parity with
+	// --track (which also enforces a four-value allowlist). Unknown values
+	// fail closed rather than persisting arbitrary strings into tokens.json.
+	const phaseFlag = flagOf(args, '--phase')
+	const VALID_PHASES = new Set(['planning', 'executing', 'verifying', 'reviewing'])
+	if (phaseFlag !== null && !VALID_PHASES.has(phaseFlag)) {
+		throw new TokensUsageError(
+			`--phase must be one of: planning, executing, verifying, reviewing (got: ${phaseFlag})`,
+		)
+	}
 
 	if (!transcript && (inputStr === null || outputStr === null)) {
 		throw new TokensUsageError('Provide --transcript <path> OR both --input N --output N')
@@ -195,6 +219,7 @@ function cmdRecord(targetDir, args) {
 				timestamp: p.timestamp || ts,
 				source: 'transcript',
 				transcript_path: transcript,
+				...(phaseFlag ? { phase: phaseFlag } : {}),
 			})
 		}
 	} else {
@@ -222,6 +247,7 @@ function cmdRecord(targetDir, args) {
 			cost_usd: costUsd,
 			timestamp: nowIso(),
 			source: 'manual',
+			...(phaseFlag ? { phase: phaseFlag } : {}),
 		})
 	}
 
@@ -419,12 +445,135 @@ function cmdList(targetDir, args) {
 	})
 }
 
+/**
+ * Read lifecycle events for a task across today + yesterday (UTC).
+ * Returns events sorted ascending by `t`. Best-effort: missing event log
+ * directories return an empty array — phase-summary degrades gracefully
+ * when telemetry isn't enabled.
+ */
+function readTaskLifecycleEvents(targetDir, taskId) {
+	// Delegates to the shared two-day window helper in event-log.mjs so
+	// tokens.mjs and the lifecycle-event helpers cannot drift on the window
+	// strategy (PR #115 review findings QUA-001 + PRF-001).
+	const events = readTaskEventsOverDays(targetDir, taskId, 'task.lifecycle.')
+	events.sort((a, b) => Date.parse(a.t) - Date.parse(b.t))
+	return events
+}
+
+/**
+ * Infer phase for a token entry by finding the most recent lifecycle event
+ * whose timestamp <= entry timestamp. Returns null when no lifecycle event
+ * precedes the entry (e.g. entries recorded before any lifecycle transition).
+ */
+function inferPhaseForEntry(entryTime, lifecycleEvents) {
+	const entryMs = Date.parse(entryTime)
+	if (!Number.isFinite(entryMs)) return null
+	let match = null
+	for (const evt of lifecycleEvents) {
+		const evtMs = Date.parse(evt.t)
+		// LOG-002 (PR #115 review): a malformed evt.t parses to NaN. `NaN <=
+		// entryMs` is false, which would trip an `else break` and drop all
+		// subsequent valid events. Skip NaN entries instead so a single bad
+		// row can't poison phase inference.
+		if (!Number.isFinite(evtMs)) continue
+		if (evtMs <= entryMs) match = evt
+		else break
+	}
+	return match?.data?.lifecycle_phase ?? null
+}
+
+/**
+ * phase-summary — join tokens.json × task.lifecycle.* events by task_id +
+ * phase. Roundtable 2026-05-14 R6 — provides the A/B baseline needed to
+ * evaluate sequential vs sub-agents mode without per-call profiling.
+ *
+ * Each row: { phase, duration_ms, input_tokens, output_tokens, cost_usd, session_count }.
+ * Duration is summed from lifecycle event `elapsed_ms`. Tokens are summed
+ * from entries whose `phase` is set (or inferred from event timestamps when
+ * the entry has no `phase` tag).
+ */
+function cmdPhaseSummary(targetDir, args) {
+	const taskId = flagOf(args, '--task-id')
+	if (!taskId) throw new TokensUsageError('--task-id is required for tokens phase-summary')
+
+	const tokensPath = tokensFilePath(targetDir, taskId)
+	const doc = readTokensFile(tokensPath)
+	const entries = doc?.entries || []
+
+	const lifecycleEvents = readTaskLifecycleEvents(targetDir, taskId)
+
+	// Per-phase accumulator.
+	const phases = new Map()
+	function bump(phase, patch) {
+		if (!phase) return
+		if (!phases.has(phase)) {
+			phases.set(phase, {
+				phase,
+				duration_ms: 0,
+				input_tokens: 0,
+				output_tokens: 0,
+				cost_usd: 0,
+				session_count: 0,
+			})
+		}
+		const row = phases.get(phase)
+		row.duration_ms += patch.duration_ms || 0
+		row.input_tokens += patch.input_tokens || 0
+		row.output_tokens += patch.output_tokens || 0
+		row.cost_usd += patch.cost_usd || 0
+		row.session_count += patch.session_count || 0
+	}
+
+	// Sum durations from lifecycle events (elapsed_ms attributed to the phase
+	// THIS event represents — i.e. the phase that was just entered. The
+	// elapsed_ms is "time spent in the prior phase before transitioning into
+	// this one." Attribute to the prior phase to keep the model intuitive.
+	let priorPhase = null
+	for (const evt of lifecycleEvents) {
+		const elapsed = evt.data?.elapsed_ms
+		if (priorPhase && typeof elapsed === 'number') {
+			bump(priorPhase, { duration_ms: elapsed })
+		}
+		priorPhase = evt.data?.lifecycle_phase || null
+	}
+
+	// Sum tokens per phase. Prefer entry.phase when set; otherwise infer from
+	// lifecycle event timestamps.
+	for (const entry of entries) {
+		const phase = entry.phase || inferPhaseForEntry(entry.timestamp, lifecycleEvents)
+		if (!phase) continue
+		bump(phase, {
+			input_tokens: entry.input_tokens || 0,
+			output_tokens: entry.output_tokens || 0,
+			cost_usd: typeof entry.cost_usd === 'number' ? entry.cost_usd : 0,
+			session_count: 1,
+		})
+	}
+
+	const rows = Array.from(phases.values()).map((r) => ({
+		...r,
+		cost_usd: Number(r.cost_usd.toFixed(6)),
+	}))
+
+	return ok({
+		status: 'ok',
+		command: 'tokens',
+		action: 'phase-summary',
+		task_id: taskId,
+		entry_count: entries.length,
+		lifecycle_event_count: lifecycleEvents.length,
+		phases: rows,
+	})
+}
+
 /**
  * Top-level dispatcher.
  */
 export function cmdTokens(subcommand, projectDir, extraArgs = []) {
 	if (!subcommand) {
-		return err('Usage: apt-tools tokens <record|tally|compare|list> <project-dir> [flags]')
+		return err(
+			'Usage: apt-tools tokens <record|tally|compare|list|phase-summary> <project-dir> [flags]',
+		)
 	}
 	if (!projectDir) {
 		return err(`Usage: apt-tools tokens ${subcommand} <project-dir> [flags]`)
@@ -444,9 +593,11 @@ export function cmdTokens(subcommand, projectDir, extraArgs = []) {
 				return cmdCompare(targetDir, extraArgs)
 			case 'list':
 				return cmdList(targetDir, extraArgs)
+			case 'phase-summary':
+				return cmdPhaseSummary(targetDir, extraArgs)
 			default:
 				return err(
-					`Unknown tokens subcommand: ${subcommand}. Expected: record, tally, compare, list`,
+					`Unknown tokens subcommand: ${subcommand}. Expected: record, tally, compare, list, phase-summary`,
 				)
 		}
 	} catch (e) {

package/src/cli/commands/triage.mjs

@@ -0,0 +1,286 @@
+/**
+ * commands/triage.mjs — `apt-tools triage` (Pocock adoption ST-10, AC9).
+ *
+ * 5-state triage state machine with extensible metadata for v2 OSS
+ * contributor primitives. Backend-configured: writes to
+ * `.aperant/tasks/{task-id}/triage.json` by default (local-only); other
+ * backends (github-issues, app-inbox) ship as not-implemented stubs.
+ *
+ * Subcommands:
+ *   apt-tools triage init <project-dir> --id <task-id> [--category bug|enhancement] [--extra '{...}']
+ *   apt-tools triage transition <project-dir> --id <task-id> --to <state> [--reason <text>] [--by user|agent]
+ *   apt-tools triage get <project-dir> --id <task-id>
+ *
+ * States: needs-triage | needs-info | ready-for-agent | ready-for-human | wontfix
+ * Categories: bug | enhancement
+ *
+ * Fast Path Guarantee (ID-05): QUICK-routed tasks NEVER enter triage.
+ * The CLI does NOT enforce this directly — the apt:triage SKILL.md
+ * routes around QUICK tasks before invoking the CLI. The CLI is the
+ * mechanical state-machine surface; the routing is the skill body's job.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+const STATES = ['needs-triage', 'needs-info', 'ready-for-agent', 'ready-for-human', 'wontfix']
+
+const CATEGORIES = ['bug', 'enhancement']
+
+// The 8 valid transitions per spec.md AC9. Anything else is rejected.
+const VALID_TRANSITIONS = new Set([
+	'needs-triage->needs-info',
+	'needs-triage->ready-for-agent',
+	'needs-triage->ready-for-human',
+	'needs-triage->wontfix',
+	'needs-info->ready-for-agent',
+	'needs-info->ready-for-human',
+	'needs-info->wontfix',
+	'needs-info->needs-triage',
+])
+
+const BACKENDS = new Set(['local-only', 'github-issues', 'app-inbox'])
+
+// Two task-id shapes coexist:
+//   - Legacy date-first: YY-MM-DD_slug-XXXX (preserved so the ~159
+//     pre-slug-first tasks already on disk keep resolving).
+//   - Current slug-first: slug_YY-MM-DD with optional -N counter
+//     emitted by generateTaskId since the slug-first rename.
+const TASK_ID_RE_LEGACY = /^[0-9]{2}-[0-9]{2}-[0-9]{2}_[a-z0-9-]+-[a-z0-9]{4}$/
+const TASK_ID_RE_SLUG_FIRST = /^[a-z0-9][a-z0-9-]*_[0-9]{2}-[0-9]{2}-[0-9]{2}(-\d+)?$/
+
+/**
+ * Read .aperant/config.json and extract task_tracking.backend.
+ * Defaults to 'local-only' if the file or the key is missing.
+ *
+ * @param {string} absProjectDir
+ * @returns {string}
+ */
+function readBackend(absProjectDir) {
+	const configPath = join(absProjectDir, '.aperant', 'config.json')
+	if (!existsSync(configPath)) return 'local-only'
+	try {
+		const parsed = JSON.parse(readFileSync(configPath, 'utf-8'))
+		const backend = parsed?.task_tracking?.backend
+		if (typeof backend === 'string' && BACKENDS.has(backend)) return backend
+		return 'local-only'
+	} catch {
+		return 'local-only'
+	}
+}
+
+/**
+ * Triage record file path.
+ *
+ * @param {string} absProjectDir
+ * @param {string} taskId
+ */
+function triagePath(absProjectDir, taskId) {
+	return join(absProjectDir, '.aperant', 'tasks', taskId, 'triage.json')
+}
+
+/**
+ * Read the current triage record, or null if it doesn't exist.
+ *
+ * @param {string} path
+ */
+function readTriage(path) {
+	if (!existsSync(path)) return null
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Write a triage record.
+ *
+ * @param {string} path
+ * @param {object} record
+ */
+function writeTriage(path, record) {
+	const dir = dirname(path)
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+	writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`)
+}
+
+/**
+ * Apply the backend mirror step. local-only writes to disk; the other
+ * backends return a not-implemented envelope so callers can handle the
+ * stub gracefully.
+ *
+ * @param {string} backend
+ * @param {string} absProjectDir
+ * @param {string} taskId
+ * @param {object} record
+ * @returns {null | { status: 'not-implemented', backend: string, v2_issue: string }}
+ */
+function mirrorToBackend(backend, absProjectDir, taskId, record) {
+	if (backend === 'local-only') {
+		writeTriage(triagePath(absProjectDir, taskId), record)
+		return null
+	}
+	// v1 stubs: github-issues and app-inbox return not-implemented.
+	return { status: 'not-implemented', backend, v2_issue: '#TBD' }
+}
+
+/**
+ * Entry: `apt-tools triage <subcommand> <project-dir> [flags]`.
+ */
+export function cmdTriage(subcommand, projectDir, extraArgs) {
+	if (!subcommand || !['init', 'transition', 'get'].includes(subcommand)) {
+		return err(
+			'Usage: apt-tools triage <init|transition|get> <project-dir> --id <task-id> [...]',
+			1,
+			{ command: 'triage' },
+		)
+	}
+	if (!projectDir) {
+		return err('project-dir is required', 1, { command: `triage-${subcommand}` })
+	}
+	const absProjectDir = resolve(projectDir)
+	if (!existsSync(absProjectDir)) {
+		return err(`project directory not found: ${absProjectDir}`, 1, {
+			command: `triage-${subcommand}`,
+		})
+	}
+
+	const flags = parseFlags(extraArgs ?? [])
+	const taskId = flags.get('id')
+	if (typeof taskId !== 'string' || taskId.trim() === '') {
+		return err('--id <task-id> is required', 1, { command: `triage-${subcommand}` })
+	}
+	if (!TASK_ID_RE_LEGACY.test(taskId) && !TASK_ID_RE_SLUG_FIRST.test(taskId)) {
+		return err(
+			`--id must match pattern <slug_YY-MM-DD[-N]> (e.g. fix-login_24-01-15) or legacy <YY-MM-DD_slug-XXXX>`,
+			1,
+			{ command: `triage-${subcommand}` },
+		)
+	}
+	const backend = readBackend(absProjectDir)
+
+	if (subcommand === 'init') {
+		// Optional --category, optional --extra (JSON string).
+		const category = flags.get('category')
+		if (category !== undefined && !CATEGORIES.includes(String(category))) {
+			return err(`--category must be one of: ${CATEGORIES.join(' | ')}`, 1, {
+				command: 'triage-init',
+			})
+		}
+		let extra = {}
+		const extraRaw = flags.get('extra')
+		if (typeof extraRaw === 'string' && extraRaw.length > 0) {
+			try {
+				const parsed = JSON.parse(extraRaw)
+				if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+					extra = parsed
+				} else {
+					return err('--extra must be a JSON object string', 1, { command: 'triage-init' })
+				}
+			} catch (e) {
+				return err(`--extra is not valid JSON: ${e.message}`, 1, { command: 'triage-init' })
+			}
+		}
+
+		const existing = readTriage(triagePath(absProjectDir, taskId))
+		if (existing) {
+			return err(`triage record already exists for ${taskId}`, 1, {
+				command: 'triage-init',
+				current_state: existing.state,
+			})
+		}
+
+		const record = {
+			task_id: taskId,
+			state: 'needs-triage',
+			category: typeof category === 'string' ? category : null,
+			transitions: [],
+			extra,
+		}
+		const stub = mirrorToBackend(backend, absProjectDir, taskId, record)
+		if (stub) return exitWith({ command: 'triage-init', ...stub }, 0)
+		return ok({ status: 'ok', command: 'triage-init', backend, record })
+	}
+
+	if (subcommand === 'transition') {
+		const toState = flags.get('to')
+		if (typeof toState !== 'string' || !STATES.includes(toState)) {
+			return err(`--to <state> is required (one of: ${STATES.join(' | ')})`, 1, {
+				command: 'triage-transition',
+			})
+		}
+		// SEC-003: cap --reason to 1000 chars to prevent unbounded disk writes.
+		const rawReason = flags.get('reason')
+		const reason = typeof rawReason === 'string' ? rawReason.slice(0, 1000) : null
+		const by =
+			typeof flags.get('by') === 'string' && ['user', 'agent'].includes(String(flags.get('by')))
+				? String(flags.get('by'))
+				: 'agent'
+
+		const current = readTriage(triagePath(absProjectDir, taskId))
+		if (!current) {
+			return err(`no triage record for ${taskId} — run \`triage init\` first`, 1, {
+				command: 'triage-transition',
+			})
+		}
+
+		const from = current.state
+		const transitionKey = `${from}->${toState}`
+		if (!VALID_TRANSITIONS.has(transitionKey)) {
+			return exitWith(
+				{
+					status: 'rejected',
+					command: 'triage-transition',
+					reason: 'invalid-transition',
+					from,
+					to: toState,
+					valid_from_current: STATES.filter((s) => VALID_TRANSITIONS.has(`${from}->${s}`)),
+				},
+				1,
+			)
+		}
+
+		const transition = {
+			from,
+			to: toState,
+			at: new Date().toISOString(),
+			by,
+			reason,
+		}
+		// SEC-002: Only carry known fields forward — do NOT spread the full
+		// disk-backed `current` object, which could contain arbitrary unknown
+		// keys from a hand-edited triage.json that would silently propagate.
+		const next = {
+			task_id: current.task_id,
+			state: toState,
+			category: current.category,
+			extra: current.extra ?? {},
+			transitions: [...(current.transitions || []), transition],
+		}
+		const stub = mirrorToBackend(backend, absProjectDir, taskId, next)
+		if (stub) return exitWith({ command: 'triage-transition', ...stub }, 0)
+		return ok({
+			status: 'ok',
+			command: 'triage-transition',
+			backend,
+			transition,
+			record: next,
+		})
+	}
+
+	// subcommand === 'get'
+	const path = triagePath(absProjectDir, taskId)
+	const record = readTriage(path)
+	if (!record) {
+		return exitWith({ status: 'not-found', command: 'triage-get', task_id: taskId, file: path }, 0)
+	}
+	return ok({ status: 'ok', command: 'triage-get', record, backend })
+}
+
+// Exported for testing.
+export const _STATES = STATES
+export const _CATEGORIES = CATEGORIES
+export const _VALID_TRANSITIONS = VALID_TRANSITIONS

package/src/cli/config/post-merge-sweep.mjs

@@ -2,6 +2,16 @@
  * post-merge-sweep.mjs — dispatch-time passive sweeper for stuck
  * `shipped-pending-merge` tasks (C57 Piece 2).
  *
+ * **Bookkeeping-only contract.** This hook runs the deterministic
+ * close half of the post-merge handoff: poll `gh pr view`, flip
+ * lifecycle_phase from `shipped-pending-merge` to `completed` via
+ * the same `task close` path, strip per-PR authorship overrides,
+ * and append a `pending_narration[]` ledger row. The LLM-side
+ * narration work (registry sync + ROADMAP prose) is explicitly
+ * out of scope here — the user drains the ledger via
+ * `/apt:close-task --narrate-only` (see packages/framework/skills/
+ * apt-close-task/SKILL.md §4) which is where those side effects belong.
+ *
  * AI agents ship a PR and walk away. Tasks then rot in
  * `shipped-pending-merge` because nothing automatic invokes
  * `apt-tools task close-merged`. This hook runs on every `apt-tools`
@@ -11,8 +21,10 @@
  * whose PRs have terminally landed.
  *
  * Non-blocking: never fails the command, never mutates exit code,
- * never throws. Single stderr line on actual sweep kick (not on
- * every dispatch).
+ * never throws. Two stderr lines max per dispatch: the
+ * `Auto-sweeping N pending PR(s)` line on actual sweep kick, plus
+ * the `Post-merge narration pending` banner when the ledger has
+ * un-drained rows. Both lines are gated by `APT_SUPPRESS_MERGE_SWEEP=1`.
  *
  * Silenced by `APT_SUPPRESS_MERGE_SWEEP=1`. Skipped when
  * `APT_INTERNAL_MERGE_SWEEP=1` is set in env (recursion guard for
@@ -90,6 +102,25 @@ export function readShippedCandidates(projectRoot) {
 	return candidates.length === 0 ? null : candidates
 }
 
+/**
+ * Pure preflight — returns the integer length of state.pending_narration[].
+ * Returns 0 on read/parse failure or when the ledger is absent (the banner
+ * is suppressed in that case).
+ *
+ * @internal
+ */
+export function readPendingNarrationCount(projectRoot) {
+	const statePath = join(projectRoot, '.aperant', 'state.json')
+	if (!existsSync(statePath)) return 0
+	try {
+		const state = JSON.parse(readFileSync(statePath, 'utf-8'))
+		const ledger = state?.pending_narration
+		return Array.isArray(ledger) ? ledger.length : 0
+	} catch {
+		return 0
+	}
+}
+
 /**
  * Returns true if the cooldown lock is "fresh" (last sweep too recent).
  * Lock content is `{pid}:{ms-since-epoch}` but we only consult mtime.
@@ -221,9 +252,24 @@ export function maybeSweepShippedMergedTasks(projectRoot, command, options = {})
 			return { kicked: false, reason: 'no-aperant-dir' }
 		}
 
+		// Narration-pending banner — fires on EVERY dispatch cycle when
+		// the ledger has un-drained rows, regardless of whether a sweep is
+		// kicked below. Cheap read, no spawn, no cooldown. Same suppression
+		// env as the sweep banner (APT_SUPPRESS_MERGE_SWEEP=1 hides both).
+		const pendingNarration = readPendingNarrationCount(root)
+		if (pendingNarration > 0) {
+			try {
+				process.stderr.write(
+					`[apt-tools] Post-merge narration pending (${pendingNarration}) — run /apt:close-task --narrate-only to refresh features registry + ROADMAP.\n`,
+				)
+			} catch {
+				/* stderr write failure is non-fatal */
+			}
+		}
+
 		const candidates = readShippedCandidates(root)
 		if (!candidates) {
-			return { kicked: false, reason: 'no-candidates' }
+			return { kicked: false, reason: 'no-candidates', pending_narration: pendingNarration }
 		}
 
 		const lockPath = join(root, '.aperant', '.merge-sweep.lock')

package/src/cli/consistency/registry.mjs

@@ -82,3 +82,17 @@ export function getRule(id) {
 export function __resetRegistryForTests() {
 	registry.clear()
 }
+
+/**
+ * Test-only helper — uniformly-named alias for the in-process cmd harness
+ * (run-cmd.mjs). Built-in rules self-register via the `rules/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/coordination/agent-identity.mjs

@@ -100,3 +100,15 @@ export function getAgentIdentity(projectDir) {
 export function __resetAgentIdentityCacheForTests() {
 	cache.clear()
 }
+
+/**
+ * Test-only helper — uniformly-named alias for the in-process cmd harness
+ * (run-cmd.mjs), which imports `__resetCaches` from each cache host with a
+ * single consistent name. Behaviour is identical to
+ * `__resetAgentIdentityCacheForTests`.
+ *
+ * @internal
+ */
+export function __resetCaches() {
+	cache.clear()
+}