@aperant/framework 0.6.3 → 0.6.5

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,7 +2,7 @@
  * 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'
@@ -11,6 +11,47 @@ 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',
+]
+
+const CI_WATCH_EVENT_TYPES = new Set([
+	'ci-watch.armed',
+	'ci-watch.tick',
+	'ci-watch.fix-pushed',
+	'ci-watch.stopped',
+])
+
+/**
+ * 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 +79,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 +96,20 @@ 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 })
+			}
+
 			// Find next sequence number — scan existing files for highest number
 			const existingFiles = readdirSync(eventsDir).filter((f) => f.endsWith('.json'))
 			let maxId = 0
@@ -169,17 +218,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
 	}

package/src/cli/commands/init.mjs

@@ -15,6 +15,7 @@
  * half is replaced.
  */
 
+import { execSync } from 'node:child_process'
 import {
 	copyFileSync,
 	existsSync,
@@ -222,6 +223,51 @@ function buildRerunWithHint(projectDir, parsedFlags, requiresExplicit) {
 	return `apt-tools init ${projectDir} ${flags.join(' ')}`.trim()
 }
 
+/**
+ * Infer `share.visibility` from the target's git tracking state.
+ *
+ * Repos that already track files inside `.aperant/` or any runtime root
+ * (`.claude/`, `.codex/`, …) are *behaviourally* team-mode: contributors
+ * pull the framework's installed files via git, not via local
+ * `apt-tools init`. Treating them as solo on an upgrade (the old `--yes`
+ * default did exactly this — bumped the schema, silently wrote
+ * `visibility: 'solo'`, and the project-gitignore allow-list flipped)
+ * is a destructive, non-obvious surprise. The 0.6.0/0.6.1 dogfood
+ * incidents both hit this rake.
+ *
+ * Returns:
+ *   - `'team'` when any tracked file lives under `.aperant/` or a runtime
+ *     root.
+ *   - `'solo'` when the dir is a git repo but no such tracked file
+ *     exists.
+ *   - `undefined` when the target isn't a git repo (caller falls back to
+ *     the descriptor default, which preserves greenfield behaviour).
+ *
+ * @param {string} targetDir
+ * @returns {'team'|'solo'|undefined}
+ */
+function inferVisibilityFromGit(targetDir) {
+	try {
+		execSync('git rev-parse --is-inside-work-tree 2>/dev/null', {
+			cwd: targetDir,
+			stdio: ['ignore', 'ignore', 'ignore'],
+		})
+	} catch {
+		return undefined
+	}
+	const probePaths = ['.aperant', ...RUNTIMES.map((r) => r.installRoot)]
+	try {
+		const out = execSync(`git ls-files -- ${probePaths.map((p) => `'${p}'`).join(' ')}`, {
+			cwd: targetDir,
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		}).trim()
+		return out.length > 0 ? 'team' : 'solo'
+	} catch {
+		return 'solo'
+	}
+}
+
 /**
  * Apply Class A defaults that were collapsed under --yes /
  * --accept-new-defaults back into the migrated config so finishInit
@@ -243,21 +289,36 @@ function buildRerunWithHint(projectDir, parsedFlags, requiresExplicit) {
  * writes — keeps the prototype-pollution guard and dot-path semantics in
  * one place.
  *
+ * `overrides` lets callers substitute the descriptor default for a
+ * specific shortKey — used in the upgrade path to honour
+ * `inferVisibilityFromGit`, so a team repo that ran `--yes` doesn't get
+ * silently flipped to solo.
+ *
  * @param {{ migrated: Record<string, unknown>, applied_defaults: Array<{ key: string, value: unknown, why: string, source?: string }> }} migration
  * @param {Array<{ key: string, why: string, default?: unknown }>} collapsedEntries
  * @param {string} source              `--yes` or `--accept-new-defaults`.
  * @param {unknown} templateVersion    Template's version, applied to migrated.
+ * @param {Record<string, unknown>} [overrides]  shortKey → inferred value.
  */
-function applyCollapsedClassAToMigration(migration, collapsedEntries, source, templateVersion) {
+function applyCollapsedClassAToMigration(
+	migration,
+	collapsedEntries,
+	source,
+	templateVersion,
+	overrides = {},
+) {
 	for (const r of collapsedEntries) {
 		const desc = findClassDescriptor(r.key)
 		if (!desc) continue
-		setAt(migration.migrated, desc.key, desc.default)
+		const hasOverride = Object.hasOwn(overrides, desc.shortKey)
+		const value = hasOverride ? overrides[desc.shortKey] : desc.default
+		const recordedSource = hasOverride ? `${source} (inferred from git tracking)` : source
+		setAt(migration.migrated, desc.key, value)
 		migration.applied_defaults.push({
 			key: desc.shortKey,
-			value: desc.default,
+			value,
 			why: r.why,
-			source,
+			source: recordedSource,
 		})
 	}
 	if (templateVersion !== undefined) {
@@ -318,7 +379,24 @@ function nonInteractiveAnswers(targetDir, canonicalRoot, archetype, parsedFlags)
 		// solo-mode — re-introducing the 0.6.0 dogfood bug.
 		let requires = migration.requires_explicit
 		if (parsedFlags.yes && requires.length > 0) {
-			applyCollapsedClassAToMigration(migration, requires, '--yes', templateConfig.version)
+			// Prefer evidence over descriptor defaults: a repo that already
+			// tracks `.aperant/` or any runtime root is team-mode by
+			// behaviour. Without this, `--yes` flips long-tracked repos to
+			// solo on the v3→v4 schema bump (0.6.0/0.6.1 dogfood incidents).
+			// Explicit --solo/--team in parsedFlags wins; only collapse-time
+			// inference runs here.
+			const overrides = {}
+			if (!parsedFlags.visibility && requires.some((r) => r.key === 'visibility')) {
+				const inferred = inferVisibilityFromGit(targetDir)
+				if (inferred !== undefined) overrides.visibility = inferred
+			}
+			applyCollapsedClassAToMigration(
+				migration,
+				requires,
+				'--yes',
+				templateConfig.version,
+				overrides,
+			)
 			requires = []
 		} else if (parsedFlags.accept_new_defaults && requires.length > 0) {
 			// --accept-new-defaults applies template defaults for new Class A