@aperant/framework 0.6.3 → 0.6.5

package/src/cli/commands/triage.mjs

@@ -0,0 +1,277 @@
+/**
+ * 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'])
+
+/**
+ * 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}` })
+	}
+	const TASK_ID_RE = /^[0-9]{2}-[0-9]{2}-[0-9]{2}_[a-z0-9-]+-[a-z0-9]{4}$/
+	if (!TASK_ID_RE.test(taskId)) {
+		return err(`--id must match pattern <YY-MM-DD_slug-XXXX> (e.g. 24-01-15_fix-login-a3b2)`, 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()
+}

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/design/frontmatter-schema.mjs

@@ -83,7 +83,9 @@ export const TypographySchema = z
 	.object({
 		families: TypographyFamiliesSchema,
 		scale: z.array(PixelOrRem).min(3), // at least {body, heading, display}
-		weights: z.array(z.number().int().positive()).optional(),
+		weights: z
+			.union([z.array(z.number().int().positive()), z.record(z.string(), z.number().positive())])
+			.optional(),
 		lineHeight: z.record(z.string(), NonEmptyString).optional(),
 	})
 	.passthrough()

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

@@ -31,6 +31,7 @@ Commands:
   task update <dir> --id <id> [--lifecycle-phase <p>] [--subtasks-total <N>] [--depends-on <refs>]  Update non-linkage task state
   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

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