@aperant/framework 0.6.4 → 0.6.6

package/src/cli/commands/context.mjs

@@ -0,0 +1,244 @@
+/**
+ * commands/context.mjs — `apt-tools context write` (Pocock adoption ST-5, AC4).
+ *
+ * Upserts a term-block into the project's CONTEXT.md (the persistent
+ * project glossary). Format ported from Pocock's CONTEXT-FORMAT.md
+ * (see packages/framework/templates/context-format.md for the MIT
+ * attribution + field semantics).
+ *
+ * Idempotent: re-running with the same `--term` updates the existing
+ * block in place. Fields not explicitly overridden via flags are
+ * preserved from the prior block.
+ *
+ * CLI:
+ *   apt-tools context write <project-dir>
+ *     --term <bold-term>
+ *     --definition <one-line>
+ *     [--aliases-to-avoid alias1,alias2]
+ *     [--cardinality 'one-to-many' | 'one-to-one' | 'many-to-many']
+ *     [--flagged-ambiguity 'note']
+ *     [--example-dialogue 'example']
+ *
+ * Output: JSON envelope { status: 'ok' | 'error',
+ *                         command: 'context-write',
+ *                         file: <absolute path>,
+ *                         term: <term>,
+ *                         operation: 'created' | 'updated' }.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok } from '../util/result.mjs'
+
+const HEADER = '# Project glossary (CONTEXT.md)'
+const HEADER_NOTE =
+	'<!-- Managed by `apt-tools context write`. Hand-edits are preserved across upserts. -->'
+
+/**
+ * Parse a single term-block out of CONTEXT.md.
+ *
+ * A block looks like:
+ *   ## {Term}
+ *
+ *   {Definition line}
+ *
+ *   - **Aliases to avoid:** ...
+ *   - **Cardinality:** ...
+ *   - **Flagged ambiguities:** ...
+ *   - **Example dialogue:** ...
+ *
+ * Returns `{ definition, aliasesToAvoid, cardinality, flaggedAmbiguity, exampleDialogue }`
+ * with each field as a string or null.
+ *
+ * @param {string} blockText
+ */
+function parseBlock(blockText) {
+	const lines = blockText.split('\n')
+	// First non-empty line after the ## header is the definition.
+	let definition = ''
+	let i = 0
+	while (i < lines.length && lines[i].trim() === '') i++
+	if (i < lines.length && !lines[i].startsWith('- ')) {
+		definition = lines[i].trim()
+		i++
+	}
+	const fields = {
+		aliasesToAvoid: null,
+		cardinality: null,
+		flaggedAmbiguity: null,
+		exampleDialogue: null,
+	}
+	for (; i < lines.length; i++) {
+		const line = lines[i]
+		const m = line.match(/^- \*\*([^*]+):\*\*\s*(.*)$/)
+		if (!m) continue
+		const key = m[1].trim()
+		const value = m[2].trim()
+		switch (key) {
+			case 'Aliases to avoid':
+				fields.aliasesToAvoid = value
+				break
+			case 'Cardinality':
+				fields.cardinality = value
+				break
+			case 'Flagged ambiguities':
+				fields.flaggedAmbiguity = value
+				break
+			case 'Example dialogue':
+				fields.exampleDialogue = value
+				break
+		}
+	}
+	return { definition, ...fields }
+}
+
+/**
+ * Render a term-block to markdown.
+ *
+ * @param {string} term
+ * @param {{
+ *   definition: string,
+ *   aliasesToAvoid: string|null,
+ *   cardinality: string|null,
+ *   flaggedAmbiguity: string|null,
+ *   exampleDialogue: string|null,
+ * }} block
+ */
+function renderBlock(term, block) {
+	const lines = [`## ${term}`, '', block.definition, '']
+	const fields = [
+		['Aliases to avoid', block.aliasesToAvoid],
+		['Cardinality', block.cardinality],
+		['Flagged ambiguities', block.flaggedAmbiguity],
+		['Example dialogue', block.exampleDialogue],
+	]
+	for (const [key, value] of fields) {
+		if (value !== null && value !== undefined && value !== '') {
+			lines.push(`- **${key}:** ${value}`)
+		}
+	}
+	return lines.join('\n')
+}
+
+/**
+ * Find an existing block by term in the source markdown.
+ * Returns `{ start, end, prior }` or `null` if no such block exists.
+ * `start` and `end` are inclusive/exclusive offsets into `source`.
+ *
+ * @param {string} source
+ * @param {string} term
+ */
+function findBlock(source, term) {
+	const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+	const headerRe = new RegExp(`^##\\s+${escaped}\\s*$`, 'm')
+	const m = headerRe.exec(source)
+	if (!m) return null
+	const start = m.index
+	// Find the next ## or # header or EOF. LOG-004: including H1 prevents a
+	// manually-inserted `# Heading` from being absorbed into the block's content.
+	const tail = source.slice(m.index + m[0].length)
+	const nextRe = /^#{1,2}\s+/m
+	const nextMatch = nextRe.exec(tail)
+	const end = nextMatch ? m.index + m[0].length + nextMatch.index : source.length
+	const blockText = source.slice(m.index + m[0].length, end)
+	return { start, end, prior: parseBlock(blockText) }
+}
+
+/**
+ * CLI entry: `apt-tools context <subcommand> <project-dir> [flags]`.
+ *
+ * Only `write` is supported in v1; other subcommands return a usage error.
+ */
+export function cmdContext(subcommand, projectDir, extraArgs) {
+	if (subcommand !== 'write') {
+		return err(
+			'Usage: apt-tools context write <project-dir> --term <term> --definition <line> [--aliases-to-avoid ...] [--cardinality ...] [--flagged-ambiguity ...] [--example-dialogue ...]',
+			1,
+			{ command: 'context' },
+		)
+	}
+	if (!projectDir) {
+		return err(
+			'Usage: apt-tools context write <project-dir> --term <term> --definition <line>',
+			1,
+			{
+				command: 'context-write',
+			},
+		)
+	}
+
+	const flags = parseFlags(extraArgs ?? [])
+	const term = flags.get('term')
+	const definition = flags.get('definition')
+	if (typeof term !== 'string' || term.trim() === '') {
+		return err('--term <bold-term> is required', 1, { command: 'context-write' })
+	}
+	if (typeof definition !== 'string' || definition.trim() === '') {
+		return err('--definition <one-line> is required', 1, { command: 'context-write' })
+	}
+
+	const absProjectDir = resolve(projectDir)
+	if (!existsSync(absProjectDir)) {
+		return err(`project directory not found: ${absProjectDir}`, 1, {
+			command: 'context-write',
+		})
+	}
+
+	const contextPath = resolve(absProjectDir, 'CONTEXT.md')
+	let source = ''
+	if (existsSync(contextPath)) {
+		source = readFileSync(contextPath, 'utf-8')
+	} else {
+		source = `${HEADER}\n\n${HEADER_NOTE}\n\n`
+	}
+	// Ensure the file starts with the header even if it existed pre-Pocock.
+	if (!source.startsWith(HEADER)) {
+		source = `${HEADER}\n\n${HEADER_NOTE}\n\n${source}`
+	}
+
+	const existing = findBlock(source, term)
+	const incoming = {
+		definition,
+		aliasesToAvoid:
+			typeof flags.get('aliases-to-avoid') === 'string' ? flags.get('aliases-to-avoid') : null,
+		cardinality: typeof flags.get('cardinality') === 'string' ? flags.get('cardinality') : null,
+		flaggedAmbiguity:
+			typeof flags.get('flagged-ambiguity') === 'string' ? flags.get('flagged-ambiguity') : null,
+		exampleDialogue:
+			typeof flags.get('example-dialogue') === 'string' ? flags.get('example-dialogue') : null,
+	}
+
+	// Merge: prior block fields are preserved unless explicitly overridden.
+	const merged = existing
+		? {
+				definition: incoming.definition, // definition always overrides
+				aliasesToAvoid: incoming.aliasesToAvoid ?? existing.prior.aliasesToAvoid,
+				cardinality: incoming.cardinality ?? existing.prior.cardinality,
+				flaggedAmbiguity: incoming.flaggedAmbiguity ?? existing.prior.flaggedAmbiguity,
+				exampleDialogue: incoming.exampleDialogue ?? existing.prior.exampleDialogue,
+			}
+		: incoming
+
+	const rendered = renderBlock(term, merged)
+	let updated
+	if (existing) {
+		// Replace the existing block (header + body) with the rendered one.
+		const before = source.slice(0, existing.start).replace(/\n+$/, '')
+		const after = source.slice(existing.end).replace(/^\n+/, '')
+		updated = `${before}\n\n${rendered}\n${after.length > 0 ? `\n${after}` : ''}`
+	} else {
+		// Append a new block at the end.
+		updated = `${source.replace(/\n+$/, '')}\n\n${rendered}\n`
+	}
+
+	writeFileSync(contextPath, updated)
+
+	return ok({
+		status: 'ok',
+		command: 'context-write',
+		file: contextPath,
+		term,
+		operation: existing ? 'updated' : 'created',
+	})
+}

package/src/cli/commands/event.mjs

@@ -2,15 +2,86 @@
  * commands/event.mjs — append-only event log for coordination history (C29).
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { hostname } from 'node:os'
 import { join, resolve } from 'node:path'
 import { readLifecycleEventsForDay } from '../coordination/event-log.mjs'
+import { validateConductorEvent } from '../coordination/event-schema.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { detectWorktree } from '../git/worktree-detect.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, ok } from '../util/result.mjs'
 
+// QUA-003 / PRF-002 — single source of truth for valid event types.
+// VALID_EVENT_TYPES is the authoritative list; CI_WATCH_EVENT_TYPES is the O(1)
+// membership Set used to short-circuit ci-watch.* events to the JSONL path (D-04).
+const VALID_EVENT_TYPES = [
+	'task-claimed',
+	'task-completed',
+	'task-failed',
+	'wave-started',
+	'wave-completed',
+	'install.started',
+	'install.ok',
+	'install.failed',
+	'ci-watch.armed',
+	'ci-watch.tick',
+	'ci-watch.fix-pushed',
+	'ci-watch.stopped',
+	// Phase 2.5 — Conductor-readable ops emitted by APT skills so the
+	// Conductor's readEventLog tool can drive its observe loop. These
+	// events route to JSONL (like ci-watch.*) and carry terminal_id
+	// auto-stamped from APERANT_TERMINAL_ID when present.
+	'phase.changed',
+	'artifact.ready',
+	'awaiting-input',
+	'input-rescinded',
+	'heartbeat',
+	'budget.exceeded',
+	'terminal.enrolled',
+	'terminal.unenrolled',
+	'conductor.intent',
+	'conductor.cross_check',
+	'conductor.realignment',
+]
+
+const CI_WATCH_EVENT_TYPES = new Set([
+	'ci-watch.armed',
+	'ci-watch.tick',
+	'ci-watch.fix-pushed',
+	'ci-watch.stopped',
+])
+
+const CONDUCTOR_EVENT_TYPES = new Set([
+	'phase.changed',
+	'artifact.ready',
+	'awaiting-input',
+	'input-rescinded',
+	'heartbeat',
+	'budget.exceeded',
+	'terminal.enrolled',
+	'terminal.unenrolled',
+	'conductor.intent',
+	'conductor.cross_check',
+	'conductor.realignment',
+])
+
+/**
+ * Append a ci-watch event to the per-day JSONL file (D-04).
+ * O(1) — no directory scan. Creates the events dir if missing.
+ * @param {string} eventsDir
+ * @param {object} payload
+ * @returns {{ jsonlFile: string, jsonlPath: string }}
+ */
+function appendToJsonl(eventsDir, payload) {
+	mkdirSync(eventsDir, { recursive: true })
+	const today = new Date().toISOString().slice(0, 10)
+	const jsonlFile = `${today}.jsonl`
+	const jsonlPath = join(eventsDir, jsonlFile)
+	appendFileSync(jsonlPath, `${JSON.stringify(payload)}\n`, 'utf-8')
+	return { jsonlFile, jsonlPath }
+}
+
 export function cmdEvent(subcommand, projectDir, extraArgs) {
 	if (!subcommand)
 		return err('Usage: apt-tools event <append|list|rebuild-state> <project-dir> [flags]')
@@ -38,18 +109,12 @@ export function cmdEvent(subcommand, projectDir, extraArgs) {
 			//   install.started — { task_id, ecosystem, pid, started_at, log_path }
 			//   install.ok      — { task_id, ecosystem, duration_ms, log_path }
 			//   install.failed  — { task_id, ecosystem, exit_code, duration_ms, reason, log_path }
-			const validTypes = [
-				'task-claimed',
-				'task-completed',
-				'task-failed',
-				'wave-started',
-				'wave-completed',
-				'install.started',
-				'install.ok',
-				'install.failed',
-			]
-			if (!validTypes.includes(type)) {
-				return err(`Invalid event type: ${type}. Valid types: ${validTypes.join(', ')}`)
+			// C28 (post-ship CI watcher D-04) — added ci-watch.{armed,tick,fix-pushed,stopped}
+			// so /apt:watch-ci tick / start / stop can stream events into
+			// .aperant/events/{today}.jsonl. The rebuild-state switch below
+			// silently ignores them (they're informational, not task-lifecycle).
+			if (!VALID_EVENT_TYPES.includes(type)) {
+				return err(`Invalid event type: ${type}. Valid types: ${VALID_EVENT_TYPES.join(', ')}`)
 			}
 
 			let data = {}
@@ -61,6 +126,58 @@ export function cmdEvent(subcommand, projectDir, extraArgs) {
 				}
 			}
 
+			// PRF-002 — ci-watch.* events go to the per-day JSONL path (D-04).
+			// O(1) append; no directory scan needed.
+			if (CI_WATCH_EVENT_TYPES.has(type)) {
+				const event = {
+					type,
+					subtask,
+					worker: `${hostname()}-${process.pid}`,
+					timestamp: new Date().toISOString(),
+					data,
+				}
+				const { jsonlFile } = appendToJsonl(eventsDir, event)
+				return ok({ status: 'ok', command: 'event-append', event_file: jsonlFile, event })
+			}
+
+			// Phase 2.5 — Conductor-readable events route to the per-day JSONL
+			// path with the canonical envelope the Conductor's readEventLog
+			// expects: { t, agent, pid, hostname, incarnation, op, task, data }.
+			// terminal_id is auto-stamped from APERANT_TERMINAL_ID env when set,
+			// so APT skills running in a Conductor-spawned PTY automatically
+			// tag their events with the originating terminal.
+			if (CONDUCTOR_EVENT_TYPES.has(type)) {
+				const terminalId = process.env.APERANT_TERMINAL_ID
+				if (terminalId && data && typeof data === 'object' && !data.terminal_id) {
+					data.terminal_id = terminalId
+				}
+				// Step 1 — schema gate: reject payloads that violate the per-op
+				// contract before the line lands on disk. The same validator
+				// runs at the framework store seam and the core conductor
+				// writer; gating here catches CLI emitters (APT skills).
+				const validation = validateConductorEvent(type, data)
+				if (!validation.ok) {
+					return err(`Schema violation for ${type}: ${validation.error}`)
+				}
+				const envelope = {
+					t: new Date().toISOString(),
+					agent: `${hostname()}-${process.pid}`,
+					pid: process.pid,
+					hostname: hostname(),
+					incarnation: 1,
+					op: type,
+					task: subtask || null,
+					data: data || {},
+				}
+				const { jsonlFile } = appendToJsonl(eventsDir, envelope)
+				return ok({
+					status: 'ok',
+					command: 'event-append',
+					event_file: jsonlFile,
+					event: envelope,
+				})
+			}
+
 			// Find next sequence number — scan existing files for highest number
 			const existingFiles = readdirSync(eventsDir).filter((f) => f.endsWith('.json'))
 			let maxId = 0
@@ -169,17 +286,7 @@ export function cmdEvent(subcommand, projectDir, extraArgs) {
 					const event = JSON.parse(readFileSync(join(eventsDir, f), 'utf-8'))
 
 					// Validate event type before processing (T-11-04 mitigation)
-					const validTypes = [
-						'task-claimed',
-						'task-completed',
-						'task-failed',
-						'wave-started',
-						'wave-completed',
-						'install.started',
-						'install.ok',
-						'install.failed',
-					]
-					if (!validTypes.includes(event.type)) continue
+					if (!VALID_EVENT_TYPES.includes(event.type)) continue
 
 					eventsProcessed++
 

package/src/cli/commands/host-detect.mjs

@@ -22,14 +22,30 @@ export function cmdHostDetect() {
 	})
 }
 
-export function cmdReconcile(projectDir) {
-	if (!projectDir) return err('Usage: apt-tools reconcile <project-dir>')
+/**
+ * Parse `--track <quick|standard|deep>` from positional args. Returns the
+ * lowercased track or null when the flag is absent. Unknown values are
+ * silently ignored to preserve backward-compat — the caller falls back to
+ * global phase_delegation in that case.
+ */
+function parseTrackFlag(args) {
+	if (!Array.isArray(args)) return null
+	const idx = args.indexOf('--track')
+	if (idx === -1 || idx === args.length - 1) return null
+	const val = String(args[idx + 1]).toLowerCase()
+	return val === 'quick' || val === 'standard' || val === 'deep' ? val : null
+}
+
+export function cmdReconcile(projectDir, extraArgs = []) {
+	if (!projectDir)
+		return err('Usage: apt-tools reconcile <project-dir> [--track quick|standard|deep]')
 	const targetDir = resolve(projectDir)
 
 	if (!existsSync(targetDir)) return err(`Directory does not exist: ${targetDir}`)
 
 	const host = detectHost()
 	const { capabilities } = host
+	const track = parseTrackFlag(extraArgs)
 
 	// Read orchestration config — default all fields to 'auto' if missing
 	let orchestrationConfig = {
@@ -37,6 +53,7 @@ export function cmdReconcile(projectDir) {
 		review_mode: 'auto',
 		debate_mode: 'auto',
 	}
+	let perTrack = null
 
 	const configPath = join(targetDir, '.aperant', 'config.json')
 	if (existsSync(configPath)) {
@@ -48,18 +65,22 @@ export function cmdReconcile(projectDir) {
 					review_mode: cfg.orchestration.review_mode ?? 'auto',
 					debate_mode: cfg.orchestration.debate_mode ?? 'auto',
 				}
+				perTrack = cfg.orchestration.per_track ?? null
 			}
 		} catch {
 			// Malformed config — use defaults
 		}
 	}
 
+	// Per-track phase_delegation override (roundtable 2026-05-14 R7):
+	// when --track is passed AND per_track[track] is set, use that as
+	// the requested mode for phase_delegation. Otherwise fall back to
+	// the global value. review_mode and debate_mode are not track-scoped.
+	const requestedPhaseDelegation =
+		track && perTrack?.[track] ? perTrack[track] : orchestrationConfig.phase_delegation
+
 	// Resolve each dimension
-	const pdResult = resolveMode(
-		orchestrationConfig.phase_delegation,
-		capabilities,
-		'phase_delegation',
-	)
+	const pdResult = resolveMode(requestedPhaseDelegation, capabilities, 'phase_delegation')
 	const rmResult = resolveMode(orchestrationConfig.review_mode, capabilities, 'review_mode')
 	const dmResult = resolveMode(orchestrationConfig.debate_mode, capabilities, 'debate_mode')
 
@@ -79,6 +100,11 @@ export function cmdReconcile(projectDir) {
 		resolved,
 	}
 
+	if (track) {
+		result.track = track
+		result.track_source = perTrack && perTrack[track] ? 'per_track' : 'fallback'
+	}
+
 	if (downgrades.length > 0) {
 		result.downgrades = downgrades
 	}