@aperant/framework 0.17.0 → 0.20.0

package/src/cli/commands/event.mjs

@@ -6,7 +6,7 @@ import { appendFileSync, mkdirSync, readdirSync, readFileSync, writeFileSync } f
 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 { validateShowrunnerEvent } from '../coordination/event-schema.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, ok } from '../util/result.mjs'
@@ -28,8 +28,8 @@ const VALID_EVENT_TYPES = [
 	'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
+	// Phase 2.5 — Showrunner-readable ops emitted by APT skills so the
+	// Showrunner'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',
@@ -40,9 +40,9 @@ const VALID_EVENT_TYPES = [
 	'budget.exceeded',
 	'terminal.enrolled',
 	'terminal.unenrolled',
-	'conductor.intent',
-	'conductor.cross_check',
-	'conductor.realignment',
+	'showrunner.intent',
+	'showrunner.cross_check',
+	'showrunner.realignment',
 ]
 
 const CI_WATCH_EVENT_TYPES = new Set([
@@ -52,7 +52,7 @@ const CI_WATCH_EVENT_TYPES = new Set([
 	'ci-watch.stopped',
 ])
 
-const CONDUCTOR_EVENT_TYPES = new Set([
+const SHOWRUNNER_EVENT_TYPES = new Set([
 	'phase.changed',
 	'artifact.ready',
 	'awaiting-input',
@@ -61,9 +61,9 @@ const CONDUCTOR_EVENT_TYPES = new Set([
 	'budget.exceeded',
 	'terminal.enrolled',
 	'terminal.unenrolled',
-	'conductor.intent',
-	'conductor.cross_check',
-	'conductor.realignment',
+	'showrunner.intent',
+	'showrunner.cross_check',
+	'showrunner.realignment',
 ])
 
 /**
@@ -142,22 +142,22 @@ export function cmdEvent(subcommand, projectDir, extraArgs) {
 				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
+			// Phase 2.5 — Showrunner-readable events route to the per-day JSONL
+			// path with the canonical envelope the Showrunner'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
+			// so APT skills running in a Showrunner-spawned PTY automatically
 			// tag their events with the originating terminal.
-			if (CONDUCTOR_EVENT_TYPES.has(type)) {
+			if (SHOWRUNNER_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
+				// runs at the framework store seam and the core showrunner
 				// writer; gating here catches CLI emitters (APT skills).
-				const validation = validateConductorEvent(type, data)
+				const validation = validateShowrunnerEvent(type, data)
 				if (!validation.ok) {
 					return err(`Schema violation for ${type}: ${validation.error}`)
 				}

package/src/cli/commands/features-reconcile.mjs

@@ -0,0 +1,157 @@
+/**
+ * commands/features-reconcile.mjs — CLI entry point for the feature-registry
+ * delta ledger (replaces the retired append-only registry-audit writer).
+ *
+ * Exactly ONE verb per invocation:
+ *   --draft  — scaffold/refresh a per-writer delta from `git diff
+ *              --name-status <base>..HEAD` (renames preserved; deletions
+ *              pre-filled `remove`; modifications marked needs-disposition).
+ *   --write  — the single ordered idempotent materializer (7 steps, ID-03):
+ *              deltas → post-images → validate → atomic area replace →
+ *              receipt → delete consumed deltas → regenerate REGISTRY.md.
+ *   --check  — read-only 4-clause verifier (ID-05): base..HEAD coverage with
+ *              blob fingerprints, area schema validity, per-area latest-
+ *              receipt integrity, no orphan consumed deltas.
+ *   --gc     — prune receipts present on origin/main AND older than
+ *              --max-age-days (default 30). Fetch failure → warned no-op.
+ *
+ * Flags: --task-id, --subtask-id (draft), --base <ref> (draft/check; an
+ * explicit ref is normalized via `merge-base HEAD <ref>` — see resolveBase;
+ * default merge-base HEAD origin/main), --dry-run (draft), --warn-only
+ * (check), --max-age-days (gc), --no-worktree-redirect.
+ *
+ * BUG-025b: the mutating verbs (--draft/--write) resolve their write root via
+ * features/write-root.mjs so registry writes land in the active task's
+ * worktree, never leak onto main. --write self-stages its committable writes
+ * (self-stage.mjs contract) so the caller's next commit picks them up.
+ */
+
+import { resolve } from 'node:path'
+import { selfStageCommittableWrites } from '../artifacts/self-stage.mjs'
+import { checkReconciled, draftDelta, gcReceipts, materialize } from '../features/reconcile.mjs'
+import { resolveWriteRoot } from '../features/write-root.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+const VERBS = ['draft', 'write', 'check', 'gc']
+
+export function cmdFeaturesReconcile(projectDir, extraArgs) {
+	if (!projectDir) {
+		return err(
+			'Usage: apt-tools features-reconcile <project-dir> (--draft|--write|--check|--gc) [flags]',
+		)
+	}
+	const root = resolve(projectDir)
+	const flags = parseFlags(extraArgs)
+	const verbs = VERBS.filter((v) => flags.has(v))
+	if (verbs.length !== 1) {
+		return err('features-reconcile requires exactly ONE of --draft | --write | --check | --gc', 1, {
+			command: 'features-reconcile',
+		})
+	}
+	const verb = verbs[0]
+
+	const taskIdFlag = flags.get('task-id')
+	const taskId = typeof taskIdFlag === 'string' && taskIdFlag.trim() ? taskIdFlag.trim() : null
+	const subtaskIdFlag = flags.get('subtask-id')
+	const subtaskId =
+		typeof subtaskIdFlag === 'string' && subtaskIdFlag.trim() ? subtaskIdFlag.trim() : null
+	const baseFlag = flags.get('base')
+	const base = typeof baseFlag === 'string' && baseFlag.trim() ? baseFlag.trim() : null
+	const noRedirect = flags.get('no-worktree-redirect') === true
+
+	// BUG-025b: only the MUTATING verbs redirect writes into the task worktree.
+	let writeRoot = root
+	let redirectNotice = null
+	if (verb === 'draft' || verb === 'write') {
+		const resolved = resolveWriteRoot({ projectDir: root, taskId, noRedirect })
+		if (resolved.error) {
+			return err(resolved.error.message, 1, {
+				command: 'features-reconcile',
+				kind: resolved.error.kind,
+				active_worktree_tasks: resolved.error.active_worktree_tasks,
+			})
+		}
+		writeRoot = resolved.writeRoot
+		redirectNotice = resolved.redirect_notice
+		if (redirectNotice) {
+			// Surface the redirect once on stderr so the executor's log carries
+			// the audit trail without polluting stdout JSON.
+			process.stderr.write(`[features-reconcile] ${redirectNotice}\n`)
+		}
+	}
+	const common = {
+		status: 'ok',
+		command: 'features-reconcile',
+		verb,
+		write_root: writeRoot,
+		...(redirectNotice ? { redirect_notice: redirectNotice } : {}),
+	}
+
+	if (verb === 'draft') {
+		if (!taskId) {
+			return err(
+				'features-reconcile --draft requires --task-id <id> (the delta path is per-writer)',
+				1,
+				{
+					command: 'features-reconcile',
+				},
+			)
+		}
+		const res = draftDelta({
+			root: writeRoot,
+			base,
+			taskId,
+			subtaskId,
+			dryRun: flags.get('dry-run') === true,
+		})
+		if (!res.ok) return err(res.error, 1, { command: 'features-reconcile', verb })
+		return ok({
+			...common,
+			delta_path: res.deltaPath,
+			wrote: res.wrote,
+			qualifying: res.qualifying,
+			base: res.base,
+			delta: res.delta,
+		})
+	}
+
+	if (verb === 'write') {
+		const res = materialize({ root: writeRoot, taskId })
+		if (res.status === 'error') {
+			return exitWith({ ...res, command: 'features-reconcile', verb, write_root: writeRoot }, 1)
+		}
+		let self_stage = null
+		if (res.status === 'ok' && Array.isArray(res.changed_paths) && res.changed_paths.length > 0) {
+			// Finally wiring the self-stage.mjs header contract: the write's
+			// committable outputs (areas + receipt + REGISTRY.md + deleted-delta
+			// paths) are staged so the ship-step commit picks them up.
+			self_stage = selfStageCommittableWrites(writeRoot, res.changed_paths)
+		}
+		return ok({
+			...common,
+			...res,
+			status: res.status,
+			...(self_stage ? { self_stage } : {}),
+		})
+	}
+
+	if (verb === 'check') {
+		const res = checkReconciled({
+			root,
+			base,
+			warnOnly: flags.get('warn-only') === true,
+			taskId,
+		})
+		const envelope = { ...common, ...res, status: res.status }
+		if (res.status === 'fail') return exitWith(envelope, 1)
+		return ok(envelope)
+	}
+
+	// verb === 'gc'
+	const maxAgeFlag = flags.get('max-age-days')
+	const maxAgeDays =
+		typeof maxAgeFlag === 'string' && /^\d+$/.test(maxAgeFlag) ? Number(maxAgeFlag) : 30
+	const res = gcReceipts({ root, maxAgeDays })
+	return ok({ ...common, ...res, status: res.status, max_age_days: maxAgeDays })
+}

package/src/cli/commands/health-check.mjs

@@ -16,8 +16,8 @@ const __dirname = dirname(__filename)
 
 /**
  * SECURITY: validate a component path string from `.aperant/features/*.json`
- * before passing it to git. The registry is on-disk JSON authored by
- * features-audit; pre-fix the orphan walker spliced this string into a
+ * before passing it to git. The registry is on-disk JSON written by the
+ * features-reconcile materializer; pre-fix the orphan walker spliced this string into a
  * shell command (`execSync(\`git rev-parse HEAD:${comp} 2>/dev/null\`)`),
  * making a malicious entry like `foo.ts; rm -rf $HOME` a command-injection
  * vector against any user who ran `apt-tools health-check`. The fix

package/src/cli/commands/merge-integrate.mjs

@@ -8,7 +8,7 @@
  * exist, else stable by task id), and probes each branch's mergeability against
  * the CURRENT base via the EXACT same `git merge-tree` detection the `detect`
  * subcommand uses (#395). It emits a structured integration report the
- * conductor renders and the `apt:merge-conflict-resolution` flow consumes for
+ * showrunner renders and the `apt:merge-conflict-resolution` flow consumes for
  * any conflicted branch.
  *
  * READ-ONLY, like `detect`/`markers`: NO `git merge`, NO `git rebase`, NO index
@@ -33,7 +33,7 @@
  *   apt-tools merge integrate <project-dir> --batch <batch-id>  [--base <ref>]
  *
  * --tasks   Explicit canonical task-id list (what `fan-out resolve` returns and
- *           the conductor already holds). Primary form.
+ *           the showrunner already holds). Primary form.
  * --batch   Recover the task-id list from the batch's worker rows
  *           `.aperant/team-status/fanout-<batch>-<task>.json` (the agent-id
  *           format fan-out.mjs spawns workers with: `fanout-${batch}-${task}`).
@@ -291,7 +291,7 @@ export function mergeIntegrate(targetDir, extraArgs) {
 		const task = state?.active_tasks?.[id] || null
 
 		// Tasks with no shipped branch can't be integrated — record them so the
-		// conductor sees why, but never block the rest of the batch.
+		// showrunner sees why, but never block the rest of the batch.
 		if (!task) {
 			needsHuman++
 			tasks.push({ task_id: id, status: 'unknown', reason: 'task not found in state.json' })