@aperant/framework 0.6.5 → 0.6.6

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/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/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 }
+}

package/src/cli/route/skill-discover.mjs

@@ -29,6 +29,7 @@ import {
 } from 'node:fs'
 import { isAbsolute, join, relative, resolve } from 'node:path'
 import { parse as parseYaml } from 'yaml'
+import { sanitizeAptVersionForYamlParse } from '../install/version-header.mjs'
 import { SkillFrontmatterSchema } from '../skill-author/contract.mjs'
 
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/
@@ -126,7 +127,7 @@ function readSkill(file) {
 	}
 	let parsed
 	try {
-		parsed = parseYaml(m[1])
+		parsed = parseYaml(sanitizeAptVersionForYamlParse(m[1]))
 	} catch (err) {
 		return {
 			ok: false,

package/src/cli/task/ids.mjs

@@ -9,8 +9,7 @@ import { join, resolve } from 'node:path'
  * Supported formats: YY-MM-DD (default, sorts chronologically), DD-MM-YY, MM-DD-YY
  * Uses hyphens as separators for filesystem safety.
  */
-export function formatDateForTask(dateFormat) {
-	const now = new Date()
+export function formatDateForTask(dateFormat, now = new Date()) {
 	const yy = String(now.getFullYear()).slice(2)
 	const mm = String(now.getMonth() + 1).padStart(2, '0')
 	const dd = String(now.getDate()).padStart(2, '0')
@@ -27,20 +26,23 @@ export function formatDateForTask(dateFormat) {
 
 /**
  * Generate a short task ID from description + timestamp.
- * Format: {date}_{slug}-{4-char-hash}
- * Date comes first so tasks sort chronologically in file explorers.
+ * Format: {slug}_{date}
+ * Slug comes first so task lists scan by verb instead of by date.
  * Date format is configurable via preferences.date_format in config.
+ * Same-day same-slug collisions are disambiguated by the caller
+ * (see commands/task.mjs) via a numeric -2, -3, … suffix; this
+ * generator never emits a counter or a random hash.
  */
-export function generateTaskId(description, config) {
-	const slug = description
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, '-')
-		.replace(/^-|-$/g, '')
-		.slice(0, 40)
+export function generateTaskId(description, config, now = new Date()) {
+	const slug =
+		description
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, '-')
+			.slice(0, 40)
+			.replace(/^-|-$/g, '') || 'task'
 	const dateFormat = config?.preferences?.date_format || 'YY-MM-DD'
-	const date = formatDateForTask(dateFormat)
-	const hash = Math.random().toString(36).slice(2, 6)
-	return `${date}_${slug}-${hash}`
+	const date = formatDateForTask(dateFormat, now)
+	return `${slug}_${date}`
 }
 
 export function getTaskDir(projectDir, taskId) {