@aperant/framework 0.6.5 → 0.6.7

package/src/cli/commands/event.mjs

@@ -6,6 +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 { createCoordinationStore } from '../coordination/store.mjs'
 import { detectWorktree } from '../git/worktree-detect.mjs'
 import { parseFlags } from '../util/args.mjs'
@@ -27,6 +28,21 @@ 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
+	// 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([
@@ -36,6 +52,20 @@ const CI_WATCH_EVENT_TYPES = new Set([
 	'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.
@@ -110,6 +140,44 @@ 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
+			// 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

package/src/cli/commands/init.mjs

@@ -82,8 +82,14 @@ const TRANSFORM_LOADERS = new Map(
  * a missing runtimes flag should block (no flag, no `--yes`) or not
  * (flag passed, or `--yes`).
  *
+ * 0.6.7 — `--force-runtimes` (Bug 2 fix) bypasses the `upgrade_noop`
+ * short-circuit so `/apt:update` can re-stamp runtime manifests even
+ * when `.aperant/config.json` is at the current schema. Strictly
+ * additive: callers without the flag still get the no-op short-circuit
+ * (preserves `init-upgrade-drift.test.ts` case (a)).
+ *
  * @param {string[]} args
- * @returns {{ runtimes: string[], runtimes_explicit: boolean, target: string|null, interactive: boolean, skipBootstrap: boolean, visibility?: 'solo'|'team', autonomy?: 0|1|2|3, accept_new_defaults: boolean, yes: boolean }}
+ * @returns {{ runtimes: string[], runtimes_explicit: boolean, target: string|null, interactive: boolean, skipBootstrap: boolean, visibility?: 'solo'|'team', autonomy?: 0|1|2|3, accept_new_defaults: boolean, yes: boolean, forceRuntimes: boolean }}
  */
 export function parseInstallFlags(args) {
 	const flagSet = new Set(args.filter((a) => a.startsWith('--')))
@@ -96,12 +102,16 @@ export function parseInstallFlags(args) {
 	// C47 D-04 — opt out of the PROJECT.md auto-chain. Forwarded as
 	// `answers.skipBootstrap` into both interview paths.
 	const skipBootstrap = flagSet.has('--skip-bootstrap')
+	// 0.6.7 (Bug 2 fix) — opt-in bypass of the upgrade_noop short-circuit
+	// so /apt:update can re-stamp runtime files on a no-drift upgrade.
+	const forceRuntimes = flagSet.has('--force-runtimes')
 
 	const classFlags = parseClassFlags(args)
 
 	const base = {
 		target,
 		skipBootstrap,
+		forceRuntimes,
 		visibility: classFlags.visibility,
 		autonomy: classFlags.autonomy,
 		accept_new_defaults: classFlags.accept_new_defaults,
@@ -326,6 +336,33 @@ function applyCollapsedClassAToMigration(
 	}
 }
 
+/**
+ * Resolve the effective runtimes list from flags, with fallback to
+ * `suggestRuntimes` and a final fallback to `['claude']`.
+ *
+ * Shared by the `nonInteractiveAnswers` upgrade path and the
+ * `--force-runtimes` synthesis block in `cmdInit` to avoid duplication.
+ *
+ * Emits a one-line stderr warning when the final fallback fires (no
+ * explicit flags and `suggestRuntimes` returned empty) so the choice is
+ * visible without breaking automated callers.
+ *
+ * @param {string} targetDir
+ * @param {ReturnType<typeof parseInstallFlags>} parsedFlags
+ * @returns {string[]}
+ */
+function selectRuntimes(targetDir, parsedFlags) {
+	if (parsedFlags.runtimes_explicit) return parsedFlags.runtimes
+	const suggested = new Set(suggestRuntimes(targetDir))
+	if (suggested.size === 0) {
+		process.stderr.write(
+			'[apt-tools] No runtime specified and config has no suggestRuntimes; defaulting to claude.\n',
+		)
+		suggested.add('claude')
+	}
+	return [...suggested]
+}
+
 /**
  * Non-TTY / scripted path — derive answers from flags + sensible defaults,
  * gated by the Class A/B classifier (spec R2 + R3).
@@ -427,9 +464,7 @@ function nonInteractiveAnswers(targetDir, canonicalRoot, archetype, parsedFlags)
 		const visibility = migration.migrated?.share?.visibility === 'team' ? 'team' : 'solo'
 		const autonomyDefault = migration.migrated?.autonomy?.default ?? 1
 		const xverify = migration.migrated?.multi_model?.cross_verification?.tools ?? []
-		const suggested = new Set(suggestRuntimes(targetDir))
-		if (suggested.size === 0) suggested.add('claude')
-		const runtimes = parsedFlags.runtimes_explicit ? parsedFlags.runtimes : [...suggested]
+		const runtimes = selectRuntimes(targetDir, parsedFlags)
 		return {
 			runtimes,
 			autonomyDefault,
@@ -599,6 +634,12 @@ async function interactiveInterview(targetDir, version, canonicalRoot, archetype
 			migration.applied_defaults.length === 0 &&
 			migration.auto_added.length === 0
 		if (noDrift) {
+			// 0.6.7 (Bug 2 fix) — `--force-runtimes` bypasses the TTY
+			// "Nothing to do." outro so the runtime walker re-stamps every
+			// manifest; cmdInit's force-runtimes synthesis path takes over.
+			if (parsedFlags.forceRuntimes) {
+				return { upgrade_noop: true, skipBootstrap, migration }
+			}
 			process.stdout.write(`\n${aperantBanner(version)}\n\n`)
 			clack.intro('install')
 			clack.note(`Already up to date — v${version}`, 'No drift')
@@ -907,6 +948,22 @@ function applyInterviewAnswers(config, answers) {
 	}
 	config.project_type =
 		answers.archetype.type === 'brownfield' ? 'unknown' : config.project_type || 'unknown'
+
+	// Onboarding marker (task 15-05-26_apt-setup-onboarding-marker-7q9c).
+	// `/apt:setup` dispatches on this marker to decide review-mode vs full
+	// Batch 1-8 flow — file existence alone cannot disambiguate "fresh seed
+	// from template" from "fully tuned by setup" because templates/config.json
+	// ships with every key populated. Only the fresh-seed branch reaches this
+	// function (finishInit:1331); the upgrade branch (finishInit:1338-1357)
+	// writes answers.migration.migrated directly and never calls
+	// applyInterviewAnswers, so legacy unmarked configs correctly stay
+	// unmarked on upgrade. --yes / --accept-new-defaults walk this same fresh
+	// path but do NOT walk Batch 1-8 questions, so completed stays false.
+	config.onboarding = {
+		completed: false,
+		seeded_from_template: true,
+		seeded_at: new Date().toISOString(),
+	}
 }
 
 /**
@@ -1061,7 +1118,13 @@ export async function cmdInit(projectDir, extraArgs = []) {
 		// idempotent — preserves PROJECT.md, refreshes sidecar from it).
 		// In TTY mode clack already rendered "Nothing to do." to stdout,
 		// so suppress the JSON envelope (matches the cancelled path).
-		if (answers?.upgrade_noop) {
+		//
+		// 0.6.7 (Bug 2 fix) — `--force-runtimes` bypasses this short-circuit
+		// so `/apt:update` can re-stamp every runtime manifest even when
+		// `.aperant/config.json` is at the current schema. We synthesize a
+		// real InstallAnswers shape from the existing config so
+		// installRuntimes + finishInit run their normal upgrade path.
+		if (answers?.upgrade_noop && !parsedFlags.forceRuntimes) {
 			if (interactiveTty) return rawText('', 0)
 			const bootstrap = answers.skipBootstrap
 				? { status: 'skipped', reason: '--skip-bootstrap flag' }
@@ -1077,7 +1140,36 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			})
 		}
 
-		const results = await installRuntimes(answers.runtimes, canonicalRoot, installTarget, version)
+		// 0.6.7 (Bug 2 fix) — when forceRuntimes is set on a no-drift run,
+		// synthesize a real InstallAnswers shape from the existing config so
+		// the runtime walker re-stamps every manifest. Visibility/autonomy/
+		// cross-verification are read from answers.migration.migrated (already
+		// in memory from nonInteractiveAnswers — avoids a second config read);
+		// runtimes resolved via selectRuntimes helper shared with the upgrade path.
+		let effectiveAnswers = answers
+		if (answers?.upgrade_noop && parsedFlags.forceRuntimes) {
+			const existing = answers.migration?.migrated || {}
+			const runtimes = selectRuntimes(installTarget, parsedFlags)
+			effectiveAnswers = {
+				runtimes,
+				autonomyDefault: existing?.autonomy?.default ?? 1,
+				visibility: existing?.share?.visibility === 'team' ? 'team' : 'solo',
+				crossVerificationTools: existing?.multi_model?.cross_verification?.tools ?? [],
+				scanNow: false,
+				skipBootstrap: answers.skipBootstrap,
+				archetype: detectArchetype(installTarget),
+				agent_runtime: detectAgentRuntime(),
+				applied_defaults: [],
+				explicit_inputs: collectExplicitInputs(parsedFlags),
+			}
+		}
+
+		const results = await installRuntimes(
+			effectiveAnswers.runtimes,
+			canonicalRoot,
+			installTarget,
+			version,
+		)
 
 		// Provision the project-local kernel BEFORE finishInit runs its JSON
 		// output — that way the "structure" summary can reflect the kernel
@@ -1089,14 +1181,14 @@ export async function cmdInit(projectDir, extraArgs = []) {
 			installTarget,
 			canonicalRoot,
 			version,
-			answers.runtimes,
+			effectiveAnswers.runtimes,
 			results,
-			answers,
+			effectiveAnswers,
 			interactiveTty,
 			kernelResult,
 		)
 		if (interactiveTty) {
-			await renderOutro(answers, results, version, kernelResult)
+			await renderOutro(effectiveAnswers, results, version, kernelResult)
 			// TTY mode: envelope was persisted to disk + suppressed from stdout
 			// because the clack outro already rendered the user-facing summary.
 			// Return the rawText shape with empty payload so wrap() routes us

package/src/cli/commands/modes.mjs

@@ -28,6 +28,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { parse as parseYaml } from 'yaml'
+import { sanitizeAptVersionForYamlParse } from '../install/version-header.mjs'
 import { ok } from '../util/result.mjs'
 
 const FRONTMATTER_RE = /^---\s*([\s\S]*?)\s*---/
@@ -122,7 +123,7 @@ function readSkillForModes(file) {
 	if (!m) return null
 	let parsed
 	try {
-		parsed = parseYaml(m[1])
+		parsed = parseYaml(sanitizeAptVersionForYamlParse(m[1]))
 	} catch {
 		return null
 	}

package/src/cli/commands/release-notes.mjs

@@ -0,0 +1,187 @@
+/**
+ * commands/release-notes.mjs — `apt-tools release-notes <sub>` (subtask 2-3
+ * of persona-aware-changelog-and-release-note_16-05-26).
+ *
+ * Deterministic I/O surface for the apt:release-notes skill. NEVER calls
+ * an LLM. The SKILL.md body invokes the host LLM to author the note text
+ * and hands the structured payload to this CLI for persistence + compile.
+ *
+ * Sub-verb menu:
+ *
+ *   apt-tools release-notes draft <project-dir> --pr <n> --note "<text>"
+ *       [--persona <id>] [--output-dir <path>] [--commits <sha,sha,...>]
+ *       [--date <YYYY-MM-DD>]
+ *     → write `<output_dir>/_unreleased/PR-<n>.md`. Idempotent.
+ *
+ *   apt-tools release-notes compile <project-dir> --tag <tag>
+ *       [--output-dir <path>]
+ *     → read every `_unreleased/PR-*.md`, filter by persona_filter, write
+ *       `<output_dir>/<tag>.md`, clear `_unreleased/` only on success.
+ *
+ *   apt-tools release-notes publish <project-dir> --tag <tag>
+ *       [--output-dir <path>] [--dry-run]
+ *     → read `<output_dir>/<tag>.md` + shell `gh release create/edit`.
+ *
+ * Return shape: always `{ status, command, ... }`. The wrap() helper in
+ * dispatch.mjs translates `{ status: 'error' }` envelopes into exit-1.
+ */
+
+import { resolve } from 'node:path'
+
+import { compileTag } from '../release-notes/compile.mjs'
+import { writeDraft } from '../release-notes/draft.mjs'
+import { publishTag } from '../release-notes/publish.mjs'
+import { getFlagValue } from '../util/common-flags.mjs'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * Dispatch shape (mirrors `audit`): `release-notes: (args) =>
+ * wrap(cmdReleaseNotes)(args[1], args[2], args.slice(3))` — args[1] is the
+ * sub-verb, args[2] is the project dir.
+ *
+ * @param {string | undefined} subcommand
+ * @param {string | undefined} projectDirArg
+ * @param {string[] | undefined} extraArgs
+ */
+export async function cmdReleaseNotes(subcommand, projectDirArg, extraArgs) {
+	const args = extraArgs ?? []
+	if (!subcommand) {
+		return err(
+			'Usage: apt-tools release-notes <draft|compile|publish> <project-dir> [flags]\n' +
+				'  draft     write docs/releases/_unreleased/PR-<n>.md\n' +
+				'  compile   read fragments → docs/releases/<tag>.md, clear _unreleased/\n' +
+				'  publish   shell gh release create/edit',
+		)
+	}
+	const projectDir = resolve(projectDirArg && projectDirArg.length > 0 ? projectDirArg : '.')
+
+	switch (subcommand) {
+		case 'draft':
+			return runDraft(projectDir, args)
+		case 'compile':
+			return runCompile(projectDir, args)
+		case 'publish':
+			return runPublish(projectDir, args)
+		default:
+			return err(
+				`apt-tools release-notes: unknown subcommand "${subcommand}". Known: draft, compile, publish.`,
+			)
+	}
+}
+
+/**
+ * draft — write a single PR fragment.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runDraft(projectDir, args) {
+	const prRaw = getFlagValue(args, '--pr')
+	const note = getFlagValue(args, '--note')
+	const persona = getFlagValue(args, '--persona')
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const commitsFlag = getFlagValue(args, '--commits')
+	const dateFlag = getFlagValue(args, '--date')
+
+	if (!prRaw) {
+		return err('release-notes draft: --pr <number> is required')
+	}
+	const pr = Number.parseInt(prRaw, 10)
+	if (!Number.isFinite(pr) || pr <= 0) {
+		return err(`release-notes draft: --pr must be a positive integer (got "${prRaw}")`)
+	}
+	if (!note || note.trim().length === 0) {
+		return err('release-notes draft: --note "<text>" is required (and must be non-empty)')
+	}
+
+	const commits = commitsFlag
+		? commitsFlag
+				.split(',')
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0)
+		: null
+
+	const result = writeDraft({
+		projectDir,
+		pr,
+		note,
+		persona,
+		outputDir: outputDirFlag,
+		commits,
+		date: dateFlag,
+	})
+
+	return ok({
+		status: 'ok',
+		command: 'release-notes-draft',
+		projectDir,
+		pr,
+		written: result.written,
+		reason: result.reason,
+		path: result.path,
+	})
+}
+
+/**
+ * compile — produce the per-tag narrative file from accumulated fragments.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runCompile(projectDir, args) {
+	const tag = getFlagValue(args, '--tag')
+	if (!tag) {
+		return err('release-notes compile: --tag <tag> is required')
+	}
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const result = compileTag({ projectDir, tag, outputDir: outputDirFlag })
+	return ok({
+		status: 'ok',
+		command: 'release-notes-compile',
+		projectDir,
+		tag,
+		written: result.written,
+		path: result.path,
+		fragments_total: result.fragmentsTotal,
+		fragments_in_body: result.fragmentsInBody,
+		fragments_in_triage: result.fragmentsInTriage,
+		fragments_filtered: result.fragmentsFiltered,
+		cleared_unreleased: result.clearedUnreleased,
+	})
+}
+
+/**
+ * publish — shell `gh release create/edit`. Returns a graceful
+ * `{status: 'skipped', reason: 'gh-not-found'}` when gh is unavailable.
+ *
+ * @param {string} projectDir
+ * @param {string[]} args
+ */
+function runPublish(projectDir, args) {
+	const tag = getFlagValue(args, '--tag')
+	if (!tag) {
+		return err('release-notes publish: --tag <tag> is required')
+	}
+	const outputDirFlag = getFlagValue(args, '--output-dir')
+	const dryRun = args.includes('--dry-run')
+	const result = publishTag({ projectDir, tag, outputDir: outputDirFlag, dryRun })
+	if (result.status === 'skipped') {
+		return ok({
+			status: 'skipped',
+			command: 'release-notes-publish',
+			projectDir,
+			tag,
+			reason: result.reason,
+			notes_path: result.notesPath ?? null,
+		})
+	}
+	return ok({
+		status: 'ok',
+		command: 'release-notes-publish',
+		projectDir,
+		tag,
+		mode: result.mode,
+		dry_run: dryRun,
+		notes_path: result.notesPath,
+	})
+}