@aperant/framework 0.6.4 → 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/modes.mjs

@@ -0,0 +1,215 @@
+/**
+ * commands/modes.mjs — `apt-tools modes list` (Pocock adoption ST-13, AC12).
+ *
+ * Power-user discoverability tool. Returns a JSON envelope with one
+ * record per discovered skill, exposing modes / flags / content-formats /
+ * config-driven behavior so a power user can build a mental model of
+ * the framework without reading 30 SKILL.md files.
+ *
+ * Adding a new skill auto-appears in `modes list` output without any
+ * code changes — the discovery is filesystem-scan-based (mirrors the
+ * router's eager skill-discover module).
+ *
+ * CLI:
+ *   apt-tools modes list [project-dir]
+ *
+ * Output envelope:
+ *   { status: 'ok', command: 'modes-list',
+ *     skills: [{ name, modes, flags, content_formats, config_keys, file_path }] }
+ *
+ * Field semantics:
+ *   - name             — frontmatter `name` (e.g. "apt:plan")
+ *   - modes            — frontmatter `execution_modes` (array)
+ *   - flags            — parsed from frontmatter `argument-hint`
+ *   - content_formats  — frontmatter `produces` (optional array; [] when absent)
+ *   - config_keys      — hardcoded skill→config-paths map maintained inline
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import { ok } from '../util/result.mjs'
+
+const FRONTMATTER_RE = /^---\s*([\s\S]*?)\s*---/
+
+/**
+ * Hardcoded skill→config-paths map. Maintained inline so adding a new
+ * config-dependent skill is a one-line change.
+ *
+ * Per AC12, this is the mapping `modes list` consumes to enumerate
+ * which config keys a skill cares about. Skills that don't touch
+ * config are omitted (their config_keys is `[]`).
+ *
+ * @type {Record<string, string[]>}
+ */
+const SKILL_CONFIG_KEYS = {
+	'apt:execute': ['coding.tdd_default', 'tdd.iron_law'],
+	'apt:triage': [
+		'task_tracking.backend',
+		'task_tracking.publish_to_tracker',
+		'task_tracking.tracker_url',
+		'task_tracking.tracker_label_vocabulary',
+	],
+	'apt:prototype': ['coding.prototype_discipline'],
+	'apt:verify': ['verification.evidence_capture', 'verification.max_iterations'],
+	'apt:verify-proof': ['verification.open_report', 'verification.report_formats'],
+	'apt:review': ['pipeline.skip_review'],
+	'apt:ship': ['pipeline.auto_branch', 'pipeline.branch_prefix'],
+	'apt:setup': ['*'], // setup edits config — wildcard surface
+	'apt:run': ['parallelization.enabled', 'parallelization.max_agents'],
+}
+
+/**
+ * Parse the `argument-hint` frontmatter field for `--flag` tokens.
+ * Returns a deduplicated array.
+ *
+ * @param {string|undefined} hint
+ * @returns {string[]}
+ */
+function parseFlags(hint) {
+	if (typeof hint !== 'string') return []
+	const flags = new Set()
+	for (const m of hint.matchAll(/--[a-z][a-z0-9-]*/gi)) {
+		flags.add(m[0])
+	}
+	return [...flags]
+}
+
+/**
+ * Walk a skills root and return every apt-<slug>/SKILL.md it contains.
+ *
+ * @param {string} root
+ */
+function walkSkillRoot(root) {
+	if (!existsSync(root)) return []
+	let stat
+	try {
+		stat = statSync(root)
+	} catch {
+		return []
+	}
+	if (!stat.isDirectory()) return []
+	let entries
+	try {
+		entries = readdirSync(root, { withFileTypes: true })
+	} catch {
+		return []
+	}
+	const out = []
+	for (const entry of entries) {
+		if (!entry.name.startsWith('apt')) continue
+		if (!entry.isDirectory()) continue
+		const skillFile = join(root, entry.name, 'SKILL.md')
+		if (existsSync(skillFile)) out.push(skillFile)
+	}
+	return out
+}
+
+/**
+ * Parse a single SKILL.md into a modes-list record. Returns null if
+ * the frontmatter is unparseable.
+ *
+ * @param {string} file
+ */
+function readSkillForModes(file) {
+	let text
+	try {
+		text = readFileSync(file, 'utf-8')
+	} catch {
+		return null
+	}
+	const m = text.match(FRONTMATTER_RE)
+	if (!m) return null
+	let parsed
+	try {
+		parsed = parseYaml(m[1])
+	} catch {
+		return null
+	}
+	if (parsed === null || typeof parsed !== 'object') return null
+
+	const name = typeof parsed.name === 'string' ? parsed.name : null
+	if (name === null) return null
+
+	const modes = Array.isArray(parsed.execution_modes)
+		? parsed.execution_modes.filter((m) => typeof m === 'string')
+		: []
+	const flags = parseFlags(parsed['argument-hint'])
+	const content_formats = Array.isArray(parsed.produces)
+		? parsed.produces.filter((p) => typeof p === 'string')
+		: []
+	// config_keys: prefer frontmatter `config_keys:` field when present; fall back
+	// to the hardcoded SKILL_CONFIG_KEYS map so skills not yet migrated still work.
+	const config_keys = Array.isArray(parsed.config_keys)
+		? parsed.config_keys.filter((k) => typeof k === 'string')
+		: SKILL_CONFIG_KEYS[name] || []
+
+	return {
+		name,
+		modes,
+		flags,
+		content_formats,
+		config_keys,
+		file_path: file,
+	}
+}
+
+/**
+ * CLI entry: `apt-tools modes <subcommand> [project-dir]`.
+ *
+ * Subcommands: `list` (the only v1 subcommand).
+ *
+ * The trusted-skill-roots discovery follows the same pattern as the
+ * router's skill-discover module, but at minimum scans
+ * `packages/framework/skills/` relative to the framework checkout. For
+ * project-installed skills, the project's `.aperant/deps/.../skills`
+ * tree is also scanned when present.
+ */
+export function cmdModes(subcommand, projectDir, _extraArgs) {
+	const cmd = subcommand || 'list'
+	if (cmd !== 'list') {
+		return ok({
+			status: 'error',
+			command: 'modes',
+			error: `Unknown subcommand: ${cmd}. Use 'list'.`,
+		})
+	}
+
+	// Project-dir is optional for modes list — defaults to cwd.
+	const absProjectDir = projectDir ? resolve(projectDir) : process.cwd()
+
+	// Compute trusted skill roots. The framework's own skills root
+	// (relative to this file) is always included; project-installed
+	// roots (.aperant/deps/...) are added when present.
+	const roots = new Set()
+	// Framework checkout root: this file is at
+	// .../packages/framework/src/cli/commands/modes.mjs → 5 levels up
+	// to the framework root, then skills/.
+	const frameworkRoot = resolve(new URL('../../../skills', import.meta.url).pathname)
+	if (existsSync(frameworkRoot)) roots.add(frameworkRoot)
+	const projectSkillRoot = join(absProjectDir, 'packages/framework/skills')
+	if (existsSync(projectSkillRoot)) roots.add(projectSkillRoot)
+	const installedRoot = join(absProjectDir, '.aperant/deps/node_modules/@aperant/framework/skills')
+	if (existsSync(installedRoot)) roots.add(installedRoot)
+
+	const seen = new Set()
+	const skills = []
+	for (const root of roots) {
+		for (const file of walkSkillRoot(root)) {
+			const record = readSkillForModes(file)
+			if (!record) continue
+			if (seen.has(record.name)) continue // first-writer-wins
+			seen.add(record.name)
+			skills.push(record)
+		}
+	}
+	skills.sort((a, b) => a.name.localeCompare(b.name))
+
+	return ok({
+		status: 'ok',
+		command: 'modes-list',
+		project_dir: absProjectDir,
+		skills,
+		scanned_roots: [...roots],
+	})
+}

package/src/cli/commands/route.mjs

@@ -439,7 +439,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			{
 				status: 'error',
 				command: 'route',
-				error_code: 'envelope_overflow',
+				error_code: 'skill_description_too_long',
 				reason: e instanceof Error ? e.message : String(e),
 			},
 			1,