@aperant/framework 0.6.5 → 0.6.7

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-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

@@ -71,6 +71,7 @@ import { cmdPrReview } from './commands/pr-review.mjs'
 import { cmdPrecompactHook } from './commands/precompact-hook.mjs'
 import { cmdProductContext } from './commands/product-context.mjs'
 import { cmdProfile } from './commands/profile.mjs'
+import { cmdReleaseNotes } from './commands/release-notes.mjs'
 import { cmdRiskCheck } from './commands/risk-check.mjs'
 import { cmdRoadmap } from './commands/roadmap.mjs'
 import { cmdRoute } from './commands/route.mjs'
@@ -253,6 +254,7 @@ export const DISPATCH = {
 	'variant-pick': (args) => wrap(cmdVariantPick)(args[1], args[2], args.slice(3)),
 	worktree: (args) => wrap(cmdWorktree)(args[1], args[2], args.slice(3)),
 	audit: (args) => wrap(cmdAudit)(args[1], args[2], args.slice(3)),
+	'release-notes': (args) => wrap(cmdReleaseNotes)(args[1], args[2], args.slice(3)),
 	team: (args) => wrap(cmdTeam)(args[1], args[2], args.slice(3)),
 	active: (args) => wrap(cmdActive)(args[1], args[2], args.slice(3)),
 	roadmap: (args) => wrap(cmdRoadmap)(args[1], args[2], args.slice(3)),

package/src/cli/gate/gates/review-clean.mjs

@@ -4,7 +4,9 @@
  *
  * Skipped when {task_dir}/review.json is absent (review is optional for some
  * tracks). When it is present, fails if any finding has
- * severity ∈ {"critical", "warning"} AND resolved !== true.
+ * severity ∈ {"critical", "warning"} AND neither `resolved === true` nor
+ * `fixed === true`. The reviewer skill writes resolution as `fixed: true`
+ * paired with `fix_commit`; `resolved: true` is a legacy alias.
  *
  * The findings array may be under `findings` or `issues` depending on the
  * reviewer format — we accept either.
@@ -47,7 +49,7 @@ const gate = {
 				? doc.issues
 				: []
 		const unresolved = findings.filter(
-			(f) => BLOCKING_SEVERITIES.has(f?.severity) && f?.resolved !== true,
+			(f) => BLOCKING_SEVERITIES.has(f?.severity) && f?.resolved !== true && f?.fixed !== true,
 		)
 		if (unresolved.length > 0) {
 			return {

package/src/cli/help.mjs

@@ -28,7 +28,7 @@ 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)
@@ -131,5 +131,5 @@ Flags:
 
 All output is JSON.`
 
-	process.stdout.write(help + '\n')
+	process.stdout.write(`${help}\n`)
 }

package/src/cli/install/update-chips.mjs

@@ -60,6 +60,63 @@ export function readUpdateCache() {
 	}
 }
 
+/** Semver-shape pattern: MAJOR.MINOR.PATCH with optional pre-release and build metadata. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+
+/**
+ * Read the worker's cache file with TTL and schema validation. Returns
+ * `{ fresh: true, cache }` when the cache exists, parses, declares
+ * `schema_version === 1`, and was written within `ttlMs` milliseconds.
+ * Returns `{ fresh: false }` when missing, stale, or schema mismatch.
+ *
+ * Security: `latest_version` and `installed_version` inside
+ * `cache.framework` are validated as semver strings. Invalid values are
+ * dropped (set to null) so they never propagate into shell-interpolated
+ * contexts.
+ *
+ * ENOENT and JSON parse errors stay silent (expected when the cache is
+ * missing or being rewritten). Unexpected errors are logged to stderr.
+ *
+ * @param {number} ttlMs  Maximum age in milliseconds before cache is treated as stale.
+ * @returns {{ fresh: true, cache: Record<string, unknown> } | { fresh: false }}
+ */
+export function readFreshUpdateCache(ttlMs) {
+	const path = updateCachePath()
+	if (!existsSync(path)) return { fresh: false }
+	let data
+	try {
+		data = JSON.parse(readFileSync(path, 'utf-8'))
+	} catch (err) {
+		// SyntaxError = malformed JSON (expected); anything else is unexpected.
+		if (!(err instanceof SyntaxError)) {
+			console.error('[update-cache] read failed:', err.message)
+		}
+		return { fresh: false }
+	}
+	try {
+		if (!data || typeof data !== 'object') return { fresh: false }
+		if (data.schema_version !== 1) return { fresh: false }
+		if (typeof data.checked_at !== 'string') return { fresh: false }
+		const age = Date.now() - new Date(data.checked_at).getTime()
+		if (!Number.isFinite(age) || age < 0 || age >= ttlMs) return { fresh: false }
+		// Validate semver fields in framework block — reject non-semver strings.
+		const fw = data.framework && typeof data.framework === 'object' ? data.framework : {}
+		const sanitized = { ...data, framework: { ...fw } }
+		for (const field of ['latest_version', 'installed_version']) {
+			if (
+				typeof sanitized.framework[field] === 'string' &&
+				!SEMVER_RE.test(sanitized.framework[field])
+			) {
+				sanitized.framework[field] = null
+			}
+		}
+		return { fresh: true, cache: sanitized }
+	} catch (err) {
+		console.error('[update-cache] read failed:', err.message)
+		return { fresh: false }
+	}
+}
+
 /**
  * Build the chip string array for a given cache. Empty array when there
  * are no chips to show. Order: stale_files first (most urgent), then