@aperant/framework 0.6.3 → 0.6.5

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/pr-review-audit-fixer.mjs

@@ -117,7 +117,8 @@ function extractTopLevelSection(markdown, heading) {
 }
 
 /**
- * Parse a fixes-applied.md produced by apt-pr-review-fixer. Returns
+ * Parse a fixes-applied.md produced by apt-pr-review-fixer OR a
+ * self-review.md produced by apt-pr-review-self-reviewer. Returns
  * `{ fixes: Array<{id, title, file, verification}>, skipped: Array<{id}>, exists: true }`.
  * Non-existent or empty report returns `{ exists: false, fixes: [], skipped: [] }`.
  *
@@ -125,24 +126,57 @@ function extractTopLevelSection(markdown, heading) {
  * `### <id>` block. We strip any trailing `(created)` / `(modify)` etc
  * annotation the fixer template shows as free-form text so the intersect
  * step can match against `git diff --name-only` output cleanly.
+ *
+ * Dual-schema support (PR #95 Defect 2):
+ *  - Fixer reports use `## Fixes Applied` with `### <ID> — title` headers
+ *    (e.g. `### QUA-001 — title`). Real finding ids carry through.
+ *  - Self-reviewer reports use `## Fixes Applied by Self-Reviewer` with
+ *    `### Fix N: description` headers. These have no real finding id, so
+ *    we synthesize `self-reviewer-fix-${N}` to satisfy the
+ *    `report.fixes.length > 0` guard in decideVerdict rule 3 while
+ *    letting the diff-intersect step (the real check) decide the verdict.
+ *
+ * The two heading texts are disjoint — fixers emit one, self-reviewers
+ * emit the other. If both somehow appear in the same file (not expected
+ * in practice), both are parsed and fixer entries come first.
  */
 export function parseFixesAppliedMarkdown(md) {
 	if (!md || typeof md !== 'string' || !md.trim()) {
-		return { exists: false, fixes: [], skipped: [] }
+		return { exists: false, fixes: [], skipped: [], schema: 'fixer' }
 	}
 	const fixesSection = extractTopLevelSection(md, 'Fixes Applied')
+	const selfReviewerSection = extractTopLevelSection(md, 'Fixes Applied by Self-Reviewer')
 	const skippedSection = extractTopLevelSection(md, 'Skipped')
-	const fixes = parseFixEntries(fixesSection)
+	const fixes = [
+		...parseFixEntries(fixesSection),
+		...parseSelfReviewerFixEntries(selfReviewerSection),
+	]
 	const skipped = parseSkippedEntries(skippedSection)
-	return { exists: true, fixes, skipped }
+	// Detect which heading was present; fixer takes precedence when both appear.
+	const schema = fixesSection ? 'fixer' : 'self-reviewer'
+	return { exists: true, fixes, skipped, schema }
 }
 
-function parseFixEntries(section) {
+/**
+ * Parse the body of a `## Fixes Applied by Self-Reviewer` section into
+ * entries shaped like fixer entries (id, title, file, files, verification).
+ *
+ * The self-reviewer agent emits `### Fix N: description` per fix instead
+ * of `### ID — title`, because the reviewer doesn't carry the original
+ * finding ids forward. We synthesize id `self-reviewer-fix-${N}` so the
+ * rest of the audit pipeline (decideVerdict rule 3 guard, audit.json
+ * envelope) stays schema-agnostic. The body shape — `- **File**:` /
+ * `- **Change**:` — is identical to fixer entries, so we reuse
+ * extractFileFields verbatim. Verification is not part of the self-
+ * reviewer schema (their PASS/FAIL signal lives in `## Verification
+ * Results` and is already covered by parseFixerStatusLine), so we leave
+ * `verification: null` and let the gate's diff-intersect step decide.
+ */
+function parseSelfReviewerFixEntries(section) {
 	if (!section) return []
-	// `### <id> — <title>` OR `### <id> -- <title>` OR `### <id>` alone.
-	// The fixer template uses em-dash + space; we tolerate either.
+	// `### Fix 1: description` / `### Fix 2: description`.
 	const entries = []
-	const headerRx = /^###\s+([A-Z]+-\d+)(?:\s*[—-]{1,2}\s*(.+))?$/gm
+	const headerRx = /^###\s+Fix\s+(\d+)(?:\s*:\s*(.+))?$/gm
 	const matches = [...section.matchAll(headerRx)]
 	for (let i = 0; i < matches.length; i++) {
 		const m = matches[i]
@@ -151,10 +185,8 @@ function parseFixEntries(section) {
 		const body = section.slice(start, nextStart)
 		const files = extractFileFields(body)
 		entries.push({
-			id: m[1],
+			id: `self-reviewer-fix-${m[1]}`,
 			title: m[2] ? m[2].trim() : null,
-			// Back-compat: single-path consumers + tests still see `file`
-			// (the first extracted path). New code should prefer `files`.
 			file: files[0] ?? null,
 			files,
 			verification: extractVerificationField(body),
@@ -163,6 +195,48 @@ function parseFixEntries(section) {
 	return entries
 }
 
+function parseFixEntries(section) {
+	if (!section) return []
+	// `### <id> — <title>` OR `### <id> -- <title>` OR `### <id>` alone.
+	// The fixer template uses em-dash + space; we tolerate either.
+	//
+	// PR #95 (2026-05-12) widened the capture to accept combined-id headers
+	// like `### QUA-003 + FIT-001 — title` where one body explains multiple
+	// findings. The locked separator alphabet is `+`, `,`, and ` and ` —
+	// the exact set observed in live fixer reports. We do NOT widen to a
+	// generic `\W+` splitter; the alphabet stays narrow so a typo like
+	// `### QUA-003-foo` cannot be mis-parsed as id `QUA-003`. Combined
+	// headers produce one entry per id, all sharing the same body fields
+	// (files, verification, title).
+	const entries = []
+	const headerRx =
+		/^###\s+([A-Z]+-\d+(?:\s*(?:\+|,|\s+and\s+)\s*[A-Z]+-\d+)*)(?:\s*[—-]{1,2}\s*(.+))?$/gm
+	const idSplitRx = /\s*(?:\+|,|\s+and\s+)\s*/
+	const matches = [...section.matchAll(headerRx)]
+	for (let i = 0; i < matches.length; i++) {
+		const m = matches[i]
+		const start = m.index
+		const nextStart = i + 1 < matches.length ? matches[i + 1].index : section.length
+		const body = section.slice(start, nextStart)
+		const files = extractFileFields(body)
+		const title = m[2] ? m[2].trim() : null
+		const verification = extractVerificationField(body)
+		const ids = m[1].split(idSplitRx)
+		for (const id of ids) {
+			entries.push({
+				id,
+				title,
+				// Back-compat: single-path consumers + tests still see `file`
+				// (the first extracted path). New code should prefer `files`.
+				file: files[0] ?? null,
+				files,
+				verification,
+			})
+		}
+	}
+	return entries
+}
+
 function parseSkippedEntries(section) {
 	if (!section) return []
 	const entries = []
@@ -518,12 +592,14 @@ export function decideVerdict({ statusLine, fixesApplied, diffFiles }) {
 	// fail-closed trap. The report could be scaffolded with headers but
 	// no actual entries.
 	if (claimed.fixed > 0 && report.fixes.length === 0) {
+		const heading =
+			report.schema === 'self-reviewer' ? '## Fixes Applied by Self-Reviewer' : '## Fixes Applied'
 		return {
 			verdict: 'hallucinated',
 			reason:
 				`fixer claimed FIXED=${claimed.fixed} but fixes-applied.md has zero ` +
 				`### <id>` +
-				` entries under ## Fixes Applied`,
+				` entries under ${heading}`,
 			claimed,
 			matched: [],
 			unmatched: [],
@@ -551,10 +627,13 @@ export function decideVerdict({ statusLine, fixesApplied, diffFiles }) {
 	// Main rule: FIXED > 0 AND PASS — intersect claimed files with the
 	// worktree diff. Empty intersection = hallucination.
 	if (claimed.fixed > 0 && claimed.verification === 'PASS') {
-		const claimedFiles = report.fixes.flatMap((f) =>
-			Array.isArray(f.files) ? f.files : f.file ? [f.file] : [],
-		)
-		const { matched, unmatched } = intersectClaimedAndStaged(claimedFiles, diffFiles)
+		const claimedFiles = [
+			...new Set(
+				report.fixes.flatMap((f) => (Array.isArray(f.files) ? f.files : f.file ? [f.file] : [])),
+			),
+		]
+		const { matched: rawMatched, unmatched } = intersectClaimedAndStaged(claimedFiles, diffFiles)
+		const matched = [...new Set(rawMatched)]
 		if (matched.length === 0) {
 			return {
 				verdict: 'hallucinated',

package/src/cli/commands/route.mjs

@@ -138,7 +138,7 @@ const PR_REVIEW_SIGNAL = /(?:\bPR\s*#?\s*\d+|#\d+|\bpull\s*request\s*#?\s*\d+)\b
  * so this keeps the two paths consistent.
  *
  * @param {import('../route/skill-discover.mjs').DiscoveredSkill[]} skills
- * @returns {{ agentOf: (slug: string) => string|null, spawnsAgent: (slug: string) => boolean, knownSlugs: Set<string>, isUserInvocable: (slug: string) => boolean }}
+ * @returns {{ agentOf: (slug: string) => string|null, spawnsAgent: (slug: string) => boolean, taskContextOf: (slug: string) => string|null, defaultTrackOf: (slug: string) => string|null, knownSlugs: Set<string>, isUserInvocable: (slug: string) => boolean }}
  */
 function skillIndex(skills) {
 	const byName = new Map()
@@ -160,6 +160,12 @@ function skillIndex(skills) {
 		spawnsAgent(slug) {
 			return Boolean(byName.get(slug)?.spawns_agent)
 		},
+		taskContextOf(slug) {
+			return byName.get(slug)?.task_context ?? null
+		},
+		defaultTrackOf(slug) {
+			return byName.get(slug)?.default_track ?? null
+		},
 		isUserInvocable(slug) {
 			return userInvocableSlugs.has(slug)
 		},
@@ -322,6 +328,7 @@ export function cmdRoute(projectDir, extraArgs) {
 	if (!isPrReviewFreetext && index.knownSlugs.has(firstWord)) {
 		const shouldSpawn = index.spawnsAgent(firstWord)
 		const gate_preview = previewGatesFor(firstWord)
+		const defaultTrack = index.defaultTrackOf(firstWord)
 		return ok({
 			status: 'ok',
 			command: 'route',
@@ -330,6 +337,8 @@ export function cmdRoute(projectDir, extraArgs) {
 			skill_args: remainingArgs || null,
 			spawn_agent: shouldSpawn,
 			agent: shouldSpawn ? index.agentOf(firstWord) || `apt-${firstWord}` : null,
+			task_context: index.taskContextOf(firstWord),
+			...(defaultTrack ? { default_track: defaultTrack } : {}),
 			host_capabilities,
 			task_isolation,
 			update_check,
@@ -430,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,