@aperant/framework 0.6.2

package/src/cli/gate/gates/verify-approved.mjs

@@ -0,0 +1,62 @@
+/**
+ * @internal
+ * G4 verify-approved — blocking gate for `apt:ship`.
+ *
+ * Requires {task_dir}/qa_signoff.json to exist, parse, and carry
+ * verdict === "approved". The ship skill's existing prose only asked the
+ * agent to "confirm" approval; this gate enforces it deterministically.
+ *
+ * NOTE: the file may use either `verdict` (newer) or `status` (older) field
+ * name for the QA result. We accept both for forwards/backwards compatibility,
+ * but only the string "approved" passes — "approved-with-notes" fails
+ * because ship-time deserves the strongest signal.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { registerGate } from '../registry.mjs'
+
+const gate = {
+	id: 'verify-approved',
+	description: 'qa_signoff.json exists with verdict === "approved"',
+	severity: 'blocking',
+	skills: ['ship'],
+	async check(ctx) {
+		const path = join(ctx.taskDir, 'qa_signoff.json')
+		const inputs = [path]
+		if (!existsSync(path)) {
+			return {
+				status: 'fail',
+				reason: `qa_signoff.json missing at ${path}`,
+				inputs,
+			}
+		}
+		let doc
+		try {
+			doc = JSON.parse(readFileSync(path, 'utf-8'))
+		} catch (err) {
+			return {
+				status: 'fail',
+				reason: `qa_signoff.json does not parse: ${err.message}`,
+				inputs,
+			}
+		}
+		const verdict = doc.verdict ?? doc.status ?? null
+		if (verdict !== 'approved') {
+			return {
+				status: 'fail',
+				reason: `qa_signoff.json verdict is "${verdict}" (expected "approved")`,
+				evidence: { verdict },
+				inputs,
+			}
+		}
+		return {
+			status: 'pass',
+			reason: 'qa_signoff.json.verdict === "approved"',
+			inputs,
+		}
+	},
+}
+
+registerGate(gate)
+export default gate

package/src/cli/gate/registry.mjs

@@ -0,0 +1,103 @@
+/**
+ * @internal
+ * gate/registry.mjs — first-class gate subsystem (C2).
+ *
+ * Gates are composable, deterministic predicates that a skill MUST satisfy
+ * before it may do any other work. Each registered gate exports:
+ *
+ *   {
+ *     id:          string,                // e.g. "plan-exists"
+ *     description: string,                // human-readable one-liner
+ *     severity:    'blocking' | 'warn',   // blocking gates halt the skill
+ *     skills:      string[],              // skills this gate fires for
+ *     check:       async (ctx) => GateVerdict
+ *   }
+ *
+ * A GateVerdict is:
+ *
+ *   {
+ *     status:   'pass' | 'fail' | 'warn' | 'skip',
+ *     reason:   string,
+ *     evidence?: object,                  // gate-specific structured data
+ *     inputs?:  string[]                  // absolute paths the gate read
+ *                                         // (used as cache keys in cache.mjs)
+ *   }
+ *
+ * The registry is a module-scope singleton. Tests can reset it via
+ * `__resetRegistryForTests()`. Built-in gates self-register through the
+ * `gates/index.mjs` barrel, which is imported eagerly by the CLI dispatcher.
+ */
+
+const registry = new Map()
+
+/**
+ * Register a gate. Re-registering the same id replaces the previous entry
+ * (supports hot-reload in tests and monkey-patching).
+ *
+ * @internal
+ */
+export function registerGate(gate) {
+	if (!gate || typeof gate !== 'object') {
+		throw new Error('registerGate: gate must be an object')
+	}
+	if (typeof gate.id !== 'string' || !gate.id) {
+		throw new Error('registerGate: gate.id must be a non-empty string')
+	}
+	if (typeof gate.description !== 'string') {
+		throw new Error(`registerGate(${gate.id}): description must be a string`)
+	}
+	if (gate.severity !== 'blocking' && gate.severity !== 'warn') {
+		throw new Error(
+			`registerGate(${gate.id}): severity must be "blocking" or "warn" (got ${gate.severity})`,
+		)
+	}
+	if (!Array.isArray(gate.skills) || gate.skills.length === 0) {
+		throw new Error(`registerGate(${gate.id}): skills must be a non-empty array`)
+	}
+	if (typeof gate.check !== 'function') {
+		throw new Error(`registerGate(${gate.id}): check must be a function`)
+	}
+	registry.set(gate.id, gate)
+	return gate
+}
+
+/**
+ * List all registered gates, optionally filtered to those that fire for a
+ * specific skill. Returns a shallow copy so callers can safely mutate.
+ *
+ * @internal
+ */
+export function listGates({ skill } = {}) {
+	const all = Array.from(registry.values())
+	if (!skill) return all
+	return all.filter((g) => g.skills.includes(skill))
+}
+
+/**
+ * Lookup gates that fire for a specific skill. Convenience wrapper over
+ * listGates({ skill }).
+ *
+ * @internal
+ */
+export function getGatesForSkill(skill) {
+	return listGates({ skill })
+}
+
+/**
+ * Lookup a single gate by id. Returns undefined when unknown.
+ *
+ * @internal
+ */
+export function getGate(id) {
+	return registry.get(id)
+}
+
+/**
+ * Test-only helper — drop every registered gate so a fresh import sequence
+ * starts from an empty registry. Not part of the public surface.
+ *
+ * @internal
+ */
+export function __resetRegistryForTests() {
+	registry.clear()
+}

package/src/cli/git/identity.mjs

@@ -0,0 +1,52 @@
+/**
+ * identity.mjs — git user/branch auto-detection helpers (C29).
+ */
+
+import { execSync } from 'node:child_process'
+
+/**
+ * Auto-detect the current user's git identity. Returns null if git config is unset.
+ */
+export function getGitIdentity(targetDir) {
+	try {
+		const name = execSync('git config user.name 2>/dev/null', {
+			cwd: targetDir,
+			encoding: 'utf-8',
+		}).trim()
+		const email = execSync('git config user.email 2>/dev/null', {
+			cwd: targetDir,
+			encoding: 'utf-8',
+		}).trim()
+		if (!name || !email) return null
+		return { name, email }
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Default owner string for roadmap phases when `--owner` is not passed.
+ * Uses the current user's git identity name so solo developers are attributed
+ * automatically. Team-mode skills can override by passing `--owner` explicitly
+ * (typically after prompting against team.json members).
+ */
+export function getDefaultOwner(targetDir) {
+	const identity = getGitIdentity(targetDir)
+	return identity?.name || 'TBD'
+}
+
+/**
+ * Auto-detect the current git branch. Returns null if not in a git repo or detached HEAD.
+ */
+export function getCurrentBranch(targetDir) {
+	try {
+		const branch = execSync('git rev-parse --abbrev-ref HEAD 2>/dev/null', {
+			cwd: targetDir,
+			encoding: 'utf-8',
+		}).trim()
+		if (!branch || branch === 'HEAD') return null
+		return branch
+	} catch {
+		return null
+	}
+}

package/src/cli/git/remote.mjs

@@ -0,0 +1,92 @@
+/**
+ * git/remote.mjs — public-remote detection for the C35 policy gate.
+ *
+ * Rationale: `apt init` defaults to the `solo` share policy — nothing leaves
+ * the user's machine unless they explicitly opt in via /apt:setup or by
+ * editing .aperant/config.json. But if the repo already has a public remote
+ * (github.com, gitlab.com, bitbucket.org on https or ssh) AND the user later
+ * turns on any share.* toggle, files they may have assumed were private will
+ * become world-readable.
+ *
+ * This helper detects the public-host case deterministically so init can emit
+ * an advisory `publicRemoteWarning` block and /apt:setup can surface a
+ * louder confirmation question. Self-hosted GitLab / Gitea / enterprise
+ * GitHub (github.acme.com) report isPublic=false — users on those hosts
+ * know their threat model; we only flag the "oops, this is literally the
+ * public internet" case.
+ *
+ * Regex choice:
+ *   - https://github.com/, https://gitlab.com/, https://bitbucket.org/
+ *   - git@github.com:, git@gitlab.com:, git@bitbucket.org:
+ *   - any trailing path (the repo slug) matches — we only care about host.
+ *
+ * Spec cross-ref: spec.md §6.
+ *
+ * @internal
+ */
+
+import { execFileSync } from 'node:child_process'
+
+/**
+ * @typedef {Object} PublicRemoteInfo
+ * @property {boolean} isPublic  True when origin points at one of the known
+ *                               public-internet hosts.
+ * @property {string|null} url   The raw remote URL as git reported it, or
+ *                               null if origin is unset / unreachable.
+ * @property {string|null} host  The host string when public (e.g. 'github.com'),
+ *                               otherwise null.
+ */
+
+const PUBLIC_HOSTS = ['github.com', 'gitlab.com', 'bitbucket.org']
+const HTTPS_RE = /^https:\/\/(github\.com|gitlab\.com|bitbucket\.org)\//
+const SSH_RE = /^git@(github\.com|gitlab\.com|bitbucket\.org):/
+
+/**
+ * Detect whether the current repo's `origin` remote points at a public host.
+ * Never throws — unreachable / missing / non-git returns a safe fallback.
+ *
+ * @param {string} targetDir  Project directory.
+ * @returns {PublicRemoteInfo}
+ *
+ * @internal
+ */
+export function detectPublicRemote(targetDir) {
+	let url
+	try {
+		url = execFileSync('git', ['remote', 'get-url', 'origin'], {
+			cwd: targetDir,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		}).trim()
+	} catch {
+		return { isPublic: false, url: null, host: null }
+	}
+
+	if (!url) return { isPublic: false, url: null, host: null }
+
+	const httpsMatch = url.match(HTTPS_RE)
+	if (httpsMatch) {
+		return { isPublic: true, url, host: httpsMatch[1] }
+	}
+	const sshMatch = url.match(SSH_RE)
+	if (sshMatch) {
+		return { isPublic: true, url, host: sshMatch[1] }
+	}
+
+	// Detect-but-not-flagged: private / self-hosted / SSH to a non-major host.
+	// Return the URL for diagnostics but isPublic=false.
+	return { isPublic: false, url, host: null }
+}
+
+/**
+ * Helper: list public-host strings the detector recognizes. Exposed so the
+ * setup skill can present the list to users ("we flag github.com, gitlab.com,
+ * bitbucket.org").
+ *
+ * @returns {ReadonlyArray<string>}
+ *
+ * @internal
+ */
+export function listKnownPublicHosts() {
+	return PUBLIC_HOSTS
+}

package/src/cli/git/worktree-detect.mjs

@@ -0,0 +1,55 @@
+/**
+ * worktree-detect.mjs — git worktree detection (C29).
+ *
+ * Returns coordination-relevant info so locks can target the main repo's
+ * .aperant/locks/ across worktrees. Keep the shape stable — project.mjs's
+ * getSharedLockDir consumes it.
+ */
+
+import { execSync } from 'node:child_process'
+import { resolve } from 'node:path'
+
+/**
+ * Detect if we're inside a git worktree and return coordination-relevant info.
+ * This prevents worktree-in-worktree nesting and ensures locks coordinate
+ * across worktrees by using the git common dir.
+ */
+export function detectWorktree(projectDir) {
+	const targetDir = resolve(projectDir)
+	try {
+		const gitDir = execSync('git rev-parse --git-dir 2>/dev/null', {
+			cwd: targetDir,
+			encoding: 'utf-8',
+		}).trim()
+		const gitCommonDir = execSync('git rev-parse --git-common-dir 2>/dev/null', {
+			cwd: targetDir,
+			encoding: 'utf-8',
+		}).trim()
+		const topLevel = execSync('git rev-parse --show-toplevel 2>/dev/null', {
+			cwd: targetDir,
+			encoding: 'utf-8',
+		}).trim()
+
+		// If git-dir !== git-common-dir, we're in a worktree
+		const isWorktree = resolve(targetDir, gitDir) !== resolve(targetDir, gitCommonDir)
+
+		// Main repo root is the parent of git-common-dir (which is <main>/.git)
+		const mainRepoRoot = isWorktree ? resolve(resolve(targetDir, gitCommonDir), '..') : topLevel
+
+		return {
+			is_worktree: isWorktree,
+			git_dir: resolve(targetDir, gitDir),
+			git_common_dir: resolve(targetDir, gitCommonDir),
+			worktree_root: topLevel,
+			main_repo_root: mainRepoRoot,
+		}
+	} catch {
+		return {
+			is_worktree: false,
+			git_dir: null,
+			git_common_dir: null,
+			worktree_root: null,
+			main_repo_root: null,
+		}
+	}
+}

package/src/cli/graph/depends-on.mjs

@@ -0,0 +1,98 @@
+/**
+ * depends-on.mjs — task dependency-graph helpers (C29).
+ */
+
+import { parseTaskRef } from './task-ref.mjs'
+
+/**
+ * Build a Map<task_id, depends_on[]> over all known tasks (active + completed)
+ * in a loaded state object. Depends_on entries are kept as scoped refs where
+ * available, but the cycle detector works on task_ids alone, so we normalize
+ * to bare task_ids here. Cross-scope edges are preserved (the detector just
+ * treats them as graph edges).
+ */
+export function buildDependsOnMap(state) {
+	const map = new Map()
+	const active = state?.active_tasks || {}
+	for (const [id, task] of Object.entries(active)) {
+		const deps = Array.isArray(task?.depends_on) ? task.depends_on : []
+		const normalized = deps
+			.map((d) => {
+				const parsed = parseTaskRef(d, task?.scope || 'project')
+				return parsed ? parsed.task_id : null
+			})
+			.filter(Boolean)
+		map.set(id, normalized)
+	}
+	const completed = Array.isArray(state?.completed_tasks) ? state.completed_tasks : []
+	for (const task of completed) {
+		if (!task?.id) continue
+		const deps = Array.isArray(task?.depends_on) ? task.depends_on : []
+		const normalized = deps
+			.map((d) => {
+				const parsed = parseTaskRef(d, task?.scope || 'project')
+				return parsed ? parsed.task_id : null
+			})
+			.filter(Boolean)
+		if (!map.has(task.id)) map.set(task.id, normalized)
+	}
+	return map
+}
+
+/**
+ * DFS-based cycle detector (mirror of src/helpers/cycle.ts detectCycle).
+ * Given a depends_on adjacency map and a proposed new edge, returns a cycle
+ * path (array of task_ids) if the edge would close one, or null otherwise.
+ */
+export function detectDependsOnCycle(dependsOnByTaskId, newEdge) {
+	const adj = new Map()
+	for (const [id, deps] of dependsOnByTaskId.entries()) {
+		adj.set(id, [...deps])
+	}
+	const existing = adj.get(newEdge.from) || []
+	if (!existing.includes(newEdge.to)) {
+		adj.set(newEdge.from, [...existing, newEdge.to])
+	}
+	const stack = [{ node: newEdge.to, path: [newEdge.to] }]
+	const visited = new Set()
+	while (stack.length > 0) {
+		const { node, path } = stack.pop()
+		if (node === newEdge.from) return [...path, newEdge.from]
+		if (visited.has(node)) continue
+		visited.add(node)
+		const nexts = adj.get(node) || []
+		for (const next of nexts) {
+			stack.push({ node: next, path: [...path, next] })
+		}
+	}
+	return null
+}
+
+/**
+ * BFS over the reverse depends_on graph to collect the transitive set of
+ * tasks blocked (directly or indirectly) by `targetId`. Used by
+ * `task list --blocked-by`.
+ */
+export function collectBlockedByTaskIds(dependsOnByTaskId, targetId) {
+	const reverse = new Map()
+	for (const [id, deps] of dependsOnByTaskId.entries()) {
+		for (const dep of deps) {
+			const arr = reverse.get(dep) || []
+			arr.push(id)
+			reverse.set(dep, arr)
+		}
+	}
+	const visited = new Set()
+	const out = []
+	const queue = [...(reverse.get(targetId) || [])]
+	while (queue.length > 0) {
+		const current = queue.shift()
+		if (visited.has(current)) continue
+		visited.add(current)
+		out.push(current)
+		for (const next of reverse.get(current) || []) {
+			if (!visited.has(next)) queue.push(next)
+		}
+	}
+	return out
+}

package/src/cli/graph/task-ref.mjs

@@ -0,0 +1,38 @@
+/**
+ * task-ref.mjs — task reference parsing/formatting (C29).
+ *
+ * Mirror of src/helpers/task-ref.ts. Keep the two in sync.
+ */
+
+/**
+ * Parse a task reference. Accepts:
+ *   - "task-id" (bare) — resolves to { scope: currentScope, task_id }
+ *   - "scope:task-id" — resolves to { scope, task_id }
+ * URLs (http:// / https://) belong in `roadmap_ref_url`, not depends_on;
+ * if handed one, we treat it as a bare id with no colon-splitting.
+ * Returns null on invalid (empty, just a scope, colon-only).
+ */
+export function parseTaskRef(ref, currentScope) {
+	if (typeof ref !== 'string') return null
+	const trimmed = ref.trim()
+	if (!trimmed) return null
+	// Reject URL forms — depends_on is local-refs-only.
+	if (/^https?:\/\//i.test(trimmed)) return null
+	const colonIdx = trimmed.indexOf(':')
+	if (colonIdx === -1) {
+		return { scope: currentScope || 'project', task_id: trimmed }
+	}
+	const scope = trimmed.slice(0, colonIdx).trim()
+	const taskId = trimmed.slice(colonIdx + 1).trim()
+	if (!scope || !taskId) return null
+	return { scope, task_id: taskId }
+}
+
+/**
+ * Stringify a { scope, task_id } pair back to "scope:task_id" form.
+ * Used when we need to normalize depends_on entries for storage.
+ */
+export function formatTaskRefLocal(resolved) {
+	if (!resolved || !resolved.scope || !resolved.task_id) return ''
+	return `${resolved.scope}:${resolved.task_id}`
+}

package/src/cli/help.mjs

@@ -0,0 +1,134 @@
+/**
+ * cli/help.mjs — apt-tools --help text (C29).
+ */
+
+import { getVersion } from './util/io.mjs'
+
+export function printHelp() {
+	const help = `${getVersion()}
+
+Usage: apt-tools <command> [args]
+
+Commands:
+  init <project-dir>                    Initialize framework in a project
+  uninstall <project-dir> [--purge] [--dry-run] [--yes] [--runtime <id>]
+                                        Reverse install — removes runtime files tracked by apt-file-manifest.json, strips the APT section from CLAUDE.md/AGENTS.md. Preserves .aperant/ state unless --purge.
+  state <project-dir>                   Read framework state
+  config <project-dir>                  Read framework config
+  config upgrade-gitignore <dir> [--dry-run]  Migrate .aperant/.gitignore to R6 layout (non-destructive)
+  config upgrade-layout <dir> [--dry-run]     Migrate .aperant/ folder layout to C36 shape (moves + rewrites gitignore)
+  audit privacy <dir> [--scrub]         C35: diff tracked .aperant/* vs share policy (exit 2 on violations; --scrub prints filter-repo commands + checklist, never executes)
+  audit visibility-signals <dir>         C35: structured JSON signals for /apt:setup's visibility mini-flow
+  state-update <dir> --field --value    Update a state field
+  detect-project <project-dir>          Scan project for init classification
+  init-state <dir> --config <json>      Write config + state after init flow
+  commit <message> --files <f1> <f2>    Commit files with message
+  risk-check <dir> --paths <p1> [--operation <type>]  Classify file paths by risk level
+
+  task create <dir> --description <text> [--scope <s>] [--milestone <id>] [--phase <id>] [--roadmap-ref-url <url>] [--depends-on <refs>] [--track <T>] [--autonomy <N>]  Create isolated task
+  task list <dir> [--scope <s>] [--blocked-by <id>]  List active tasks (optionally filtered)
+  task get <dir> --id <task-id>         Get task details and artifacts
+  task update <dir> --id <id> [--lifecycle-phase <p>] [--subtasks-total <N>] [--depends-on <refs>]  Update non-linkage task state
+  task move <dir> --id <id> [--to-scope <s>] [--to-milestone <id>] [--to-phase <id>] [--to-roadmap-ref-url <url>] [--reason <text>] [--force]  Reassign scope/milestone/phase with history
+  task close <dir> --id <task-id> [--verdict <v>]  Close task and move to completed
+  task complete-subtask <dir> --task-id <id> --subtask-id <sid|a+b+c> [--commit <sha>] [--notes <text>]  Atomic plan ↔ build-progress sync
+  features-audit <dir> [--diff-files <csv>|--since <ref>] [--apply-stubs] [--format json|md]  Audit features registry for unregistered feature-qualifying files
+  docs-audit <dir> [--diff-files <csv>|--since <ref>|--dry-run] [--policy <path>] [--format json|md]  Audit documented surfaces for docs-drift
+
+  lock claim <dir> --subtask <id>       Claim exclusive lock on a subtask
+  lock release <dir> --subtask <id>     Release a lock (must be owner)
+  lock check <dir> --subtask <id>       Check lock status and staleness
+  lock heartbeat <dir> --subtask <id>   Update lock heartbeat timestamp
+  lock cleanup <dir>                    Remove all stale locks
+
+  tokens record <dir> --task-id <id> [--transcript <path> | --input N --output N] [--session-id <id>] [--agent <a>] [--model <id>] [--provider <id>]
+                                          C11: append per-session token actuals to .aperant/tasks/{id}/tokens.json + mirror summary onto state.active_tasks[id].tokens
+  tokens tally <dir> --task-id <id>       C11: emit TaskCostSummary for the task (reads tokens.json)
+  tokens compare <dir> --task-id <id> [--baseline <path>]  C11: emit { aperant, baseline, ratio } (baseline JSON optional; C23 hook)
+  tokens list <dir> [--scope <s>] [--since YYYY-MM-DD]  C11: scan all tasks' tokens.json, sorted desc by last_updated
+
+  event append <dir> --type <t> --subtask <id> [--data <json>]  Append event to log
+  event list <dir> [--type <t>] [--subtask <id>]                List events with optional filters
+  event rebuild-state <dir>             Rebuild state.json from event log
+
+  wave analyze <dir> [--plan <path>] [--wave <N>]              Analyze subtask dependencies into parallel waves
+  coverage-check validate <dir> [--plan <path>] [--spec <path>]  Validate requirement-to-verification coverage
+
+  route <dir> --input "text" [--flags]    Deterministic request classifier (returns JSON routing decision)
+  statusline <dir> [--json|--ansi|--plain]  C22: single-line status summary (NO_COLOR/FORCE_COLOR/isTTY gated). --json emits envelope.
+
+  gate list [--skill <skill>]                                              C2: list registered hard gates (optionally filtered by skill)
+  gate check <dir> --task-id <id> --skill <skill> [--force --reason <r>]   C2: run the gate set for <skill>; exits 1 on blocking failures unless --force (audit-logged)
+
+  design-scan <project-dir> [--out <path>] [--root <subdir>]   C27: scan UI source for design tokens (colors, spacing, typography, radii, shadows) → .aperant/design/tokens.json
+  taste-infer <target> [--out <path>] [--add-to-library <slug>] [--timeout <ms>] [--no-synthesize] [--root <subdir>] [--force] [--no-screenshots]   C43: reverse-engineer design language from a URL or repo into a fresh DESIGN.md (static extraction; LLM only for semantic clustering)
+
+  design-template list [--library-dir <path>]                  C42: list every shipped DESIGN.md template (slug, name, description, origin, source)
+  design-template show <slug> [--library-dir <path>]           C42: print a single entry's DESIGN.md + parsed frontmatter + provenance
+  design-template add <slug> [--project-dir <path>] [--force] [--library-dir <path>]   C42: copy a library entry into <project-dir>/DESIGN.md (refuses overwrite without --force)
+  design-template submit <path> [--as <slug>] [--library-dir <path>] [--force]          C42: validate + copy a candidate DESIGN.md into the library with provenance.origin: community
+
+  author-skill <name> [--description <text>] [--dry-run] [--framework-root <path>]   C4: scaffold a new SKILL.md + structural test under packages/framework/ (test-first skill authoring)
+
+  standards <project-dir> [--profile <name>] [--json] [--no-color]   C20: zero-orchestration read-only bundle (constitution + profile + feature registry + design tokens + taste)
+
+  worktree create <dir> --subtask <id> --branch <name>  Create isolated worktree for a subtask
+  worktree remove <dir> --subtask <id> [--force]        Remove a subtask worktree
+  worktree list <dir>                                   List active worktrees under .aperant/worktrees/
+
+  detect-worktree <project-dir>          Check if running inside a git worktree
+  template <name>                        Output a template (agents-greenfield, agents-brownfield, config, state, gitignore)
+
+  bootstrap detect <project-dir> [--force-greenfield|--force-brownfield]   C47: recon (D-02 allowlist) + greenfield/brownfield compound heuristic (D-03)
+  bootstrap scaffold <project-dir> [--force]                                C47: write a PROJECT.md (7-section D-06 template) — refuses to overwrite without --force
+  bootstrap derive-sidecar <project-dir>                                    C47: derive .aperant/product-context.json from PROJECT.md (D-01; one-way)
+  bootstrap run <project-dir> [--force-greenfield|--force-brownfield] [--skip-sidecar] [--force]   C47: one-shot detect → scaffold → sidecar (used by apt-tools init auto-chain, D-04)
+
+  personas scan <project-dir>                                               C48: deterministic role-signal scan (identifiers, route prefixes, RBAC, validator enums)
+  personas rubric <project-dir>                                             C48: emit the tier-rubric prompt (D-05) the SKILL.md body hands to the host LLM
+  personas read <project-dir>                                               C48: emit current .aperant/personas.json envelope + runs count
+  personas write <project-dir> --mode <fresh|extend|from-app> [--payload <path>] [--force]   C48: persist personas (D-06/D-10; --force overrides cloud-canonical guard)
+  personas record-run <project-dir> --status <pending|running|completed|failed> [--candidates-found N] [--phase <s>] [--error <msg>]   C48: append entry to .aperant/personas-runs.json (D-09)
+
+  create-docs plan <project-dir> [--output-dir <path>]                       C49: compose features + personas + product-context → D-02 StructurePlan (no writes)
+  create-docs render-nav <project-dir> [--output-dir <path>] [--print]       C49: regenerate docs/product/README.md navigation index (D-07); --print returns markdown instead of writing
+  create-docs read <project-dir> [--output-dir <path>]                       C49: list existing docs/product/*.md files (used by D-05 diff-and-confirm)
+  create-docs run <project-dir> [--output-dir <path>] [--force]              C49: one-shot plan + existing-output read + next-steps envelope the apt-docs-author agent consumes
+
+  terminal spawn --worktree <p> --task <id> [--instructions <s>] [--cli claude-code] [--yolo]   terminal-spawn: open a sibling Aperant terminal via Electron-main IPC
+  terminal list                          List sessions known to AperantIpcServer
+  terminal status --session <id>          Get one session's metadata
+  terminal health                         Smoke-test the IPC socket (returns version + pid)
+  check [<project-dir>] [--skills-root <path>]  router-0.3.0: validate every canonical apt-<slug>/SKILL.md against SkillFrontmatterSchema + cross-reference gate IDs
+  check-version <project-dir>            Compare installed vs framework skill versions
+  toolchain-detect <project-dir>          Detect project toolchain (linter, formatter, typecheck, test, build)
+  health-check <project-dir>             Detect dirty state, stale locks, orphaned events, version drift
+  host-detect                            Detect which AI CLI is running and its capability matrix
+  reconcile <project-dir>               Resolve orchestration preferences against host capabilities
+
+  migrate-pr-reviews <project-dir>       Migrate legacy .aperant/reviews/ → .aperant/pr-reviews/pr-{N}/rounds/{R}/ (idempotent)
+
+  validate-evidence <findings-dir> --worktree <path>   Enforce the Evidence Rule (literal substring + multi-file check); mutates findings markdown in place
+
+  wfrun validate <workflow.yaml>                         C17: parse + schema-check a declarative YAML workflow (exits 0 on success)
+  wfrun plan <workflow.yaml> [--input k=v …]             C17: resolve DAG waves + inputs, emit run-plan JSON (no side effects)
+  wfrun run <workflow.yaml> [--input k=v …] [--project-dir <path>]   C17: plan + execute tool-only workflows inline, write .aperant/wfrun/{run-id}/{manifest,plan,result}.json
+
+  pr-review init-pr <dir> --pr <N> [--head-ref <ref>] [--base-ref <ref>]  Seed .aperant/pr-reviews/pr-{N}/pr-state.json
+  pr-review acquire-lock <dir> --pr <N> --owner <id> [--ttl-ms <ms>]      Take PR-level lock (exit 2 if busy)
+  pr-review release-lock <dir> --pr <N> --owner <id>                      Clear lock (owner must match)
+  pr-review start-round <dir> --pr <N> --head-sha <sha>                    Increment rounds_completed + pin head SHA (exit 2 if exhausted)
+  pr-review close-round <dir> --pr <N> --round <R>                         Snapshot state into rounds/{R}/pr-state-snapshot.json + clear lock
+  pr-review get-state <dir> --pr <N>                                       Emit current live pr-state.json
+  pr-review detect-authorship <dir> --pr <N> [--gh-json <path>] [--viewer-login <login>] [--base-repo-owner <login>]  Detect authorship_mode via gh CLI
+  pr-review record-comment <dir> --pr <N> --round <R> --url <url> --body-hash <sha256> [--review-id <id>] [--posted-at <iso>]  Append entry to comment_timeline (Phase 6b)
+  pr-review audit-fixer <dir> --review-dir <path> --iteration <N> --fixer <name> --worktree <path> --status-line <str>  Audit fixer output against git state; exits 0 with JSON envelope (verdict: verified|hallucinated|skipped)
+
+Flags:
+  --version                             Print version and exit
+  --help                                Print usage and exit
+
+All output is JSON.`
+
+	process.stdout.write(help + '\n')
+}