@smartmemory/compose 0.3.7 → 0.4.0

package/lib/canon-guard.js

@@ -98,9 +98,14 @@ export function realpathCanonicalize(p) {
  * @param {string} [args.featuresDir='docs/features']
  * @param {(p:string)=>string} [args.canonicalize] - map a path to its real, alias-free form.
  *   The runtime wrapper passes realpathCanonicalize; pure tests inject a stub or omit it.
+ * @param {string} [args.profile] - the caller's MCP profile (COMPOSE_SESSION_PROFILE).
+ *   Only changes the ESCAPE SENTENCE of the deny message, never the verdict:
+ *   `canon_override_grant` is denied to restricted profiles by IMPLEMENTER_DENY /
+ *   REVIEWER_ALLOW, so telling a restricted caller to mint a grant sends it to a
+ *   tool it cannot call. Absent/unknown → the unrestricted wording (fail-open).
  * @returns {{deny: boolean, reason?: string, path?: string}}
  */
-export function decideCanonGuard({ toolName, toolInput, cwd, projectRoot, featuresDir = 'docs/features', canonicalize } = {}) {
+export function decideCanonGuard({ toolName, toolInput, cwd, projectRoot, featuresDir = 'docs/features', canonicalize, profile } = {}) {
   try {
     if (!GUARDED_TOOLS.has(toolName)) return { deny: false };
     const raw = toolInput && (toolInput.file_path ?? toolInput.notebook_path);
@@ -121,16 +126,33 @@ export function decideCanonGuard({ toolName, toolInput, cwd, projectRoot, featur
     const entry = matchEntry(relPosix, { featuresDir, point: 'hook' });
     if (!entry) return { deny: false };
 
+    // Classification only — this function stays pure. The atomic claim happens
+    // in the hook wrapper, because a destructive callback here would make the
+    // verdict depend on how many times it was evaluated.
+    const overrideEligible = entry.overrideEligible !== false;
     const tools = entry.tools.join(', ');
+    // COMP-COVERAGE-GATE C4: canon_override_grant is now denied to restricted
+    // profiles, so pointing one at it would loop it against its own tool gate.
+    const restricted = profile === 'implementer' || profile === 'reviewer';
+    const escape = !overrideEligible
+      ? `This path is the override's own governance state, so it cannot be overridden: a bypass `
+        + `must not be able to authorise rewriting its own record.`
+      : restricted
+        ? `A canon override exists, but canon_override_grant is not available to the '${profile}' `
+          + `profile — the session subject to canon enforcement cannot exempt itself from it. `
+          + `Escalate: report what you need to write and why, and let the orchestrator decide.`
+        : `To do it deliberately anyway, mint a single-use grant with canon_override_grant `
+          + `({ path, reason, operation }) — the bypass is recorded before the grant exists.`;
+
     return {
       deny: true,
       path: relPosix,
+      overrideEligible,
       reason:
-        `${relPosix} is tool-owned canon (COMP-CANON-GUARD). A direct ${toolName} is blocked — ` +
-        `write it through one of: ${tools}. These tools stamp provenance and regenerate the ` +
-        `docs/judgment/** projections from records; a hand-edit is unattributed and overwritten on the next regen. ` +
-        `To override deliberately, use the canon override path (not yet available this slice — remove the path from ` +
-        `the registry hook set if you truly must hand-edit).`,
+        `${relPosix} is tool-owned canon (COMP-CANON-GUARD). A direct ${toolName} is blocked — `
+        + `write it through one of: ${tools}. These tools stamp provenance and regenerate the `
+        + `projections from records; a hand-edit is unattributed and overwritten on the next regen. `
+        + `${escape}`,
     };
   } catch {
     return { deny: false }; // fail open — never wedge the session

package/lib/canon-override.js

@@ -0,0 +1,196 @@
+/**
+ * canon-override.js — the canon override: grant-then-write, ledger-first.
+ *
+ * COMP-CANON-OVERRIDE S2, implementing COMP-CANON-GUARD Decision 4.
+ *
+ * WHAT THIS IS: audit and careless-drift tooling. It makes the cooperative
+ * path logged and the accidental path hard. It is NOT enforcement and must
+ * never be described as such — `Bash` and Codex writes never reach the hook,
+ * and every piece of state here lives in the workspace the agent can write.
+ * A determined actor who forges a token AND its ledger row AND the baseline
+ * passes. See design.md, "The in-workspace ceiling".
+ *
+ * ORDERING IS THE ATOMICITY ANSWER. The bypass row and the attest baseline are
+ * written BEFORE the token is minted, so the failure mode is over-recording,
+ * never under-recording: a token cannot exist without its row. If the write
+ * that follows never happens, a bypass entry exists for a write that did not
+ * occur — deliberately the safe direction.
+ *
+ * SINGLE-USE IS A RENAME, NOT A LOCK. Each grant is its own file, claimed by
+ * renaming it into `consumed/`. Exactly one caller can rename a given path;
+ * every loser gets ENOENT. An earlier draft used one shared JSON file with
+ * temp-write-plus-rename, which gives atomic *publication* but not mutual
+ * exclusion — two readers could each drop the token from their own snapshot
+ * and both succeed.
+ */
+import {
+  mkdirSync, writeFileSync, readFileSync, renameSync, readdirSync, existsSync, appendFileSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { isOverrideEligible } from './canon-registry.js';
+import { baselineFor } from './append-integrity.js';
+
+export const LEDGER_REL = '.compose/canon-overrides.jsonl';
+export const ATTEST_REL = '.compose/canon-overrides-attest.json';
+export const GRANTS_REL = '.compose/data/canon-grants';
+const CONSUMED_SUBDIR = 'consumed';
+
+/** 5 minutes: long enough for a grant-then-write round trip through an agent
+ *  turn, short enough that a forgotten grant is not a standing hole. */
+export const GRANT_TTL_MS = 5 * 60 * 1000;
+
+function typedError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true });
+}
+
+/** Read the bypass ledger as parsed rows. Malformed lines are skipped rather
+ *  than thrown on — a corrupt row must not make every claim fail open. */
+export function readOverrideLedger(cwd) {
+  const path = join(cwd, LEDGER_REL);
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return [];
+    throw err;
+  }
+  const rows = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch { /* skip a corrupt row */ }
+  }
+  return rows;
+}
+
+/**
+ * Mint a single-use, path-scoped grant.
+ *
+ * @param {string} cwd workspace root
+ * @param {{path:string, reason:string, operation?:string, featuresDir?:string}} args
+ *   `actor` is deliberately NOT accepted — it is stamped here per Decision 3.
+ * @returns {{token_id:string, path:string, expires_at:string}}
+ */
+export function mintGrant(cwd, { path, reason, operation, featuresDir = 'docs/features' } = {}) {
+  if (typeof reason !== 'string' || reason.trim() === '') {
+    throw typedError(
+      'CANON_OVERRIDE_REASON',
+      'canon_override_grant: a non-empty reason is required — the bypass row is the whole point',
+    );
+  }
+  if (typeof path !== 'string' || path.trim() === '') {
+    throw typedError('CANON_OVERRIDE_PATH', 'canon_override_grant: path is required');
+  }
+  if (!isOverrideEligible(path, { featuresDir, point: 'hook' })) {
+    throw typedError(
+      'CANON_OVERRIDE_INELIGIBLE',
+      `canon_override_grant: ${path} is not override-eligible. Either it is not guarded at the `
+      + 'write-time hook (nothing is blocking it), or it is the override\'s own governance state, '
+      + 'which is deliberately ungrantable so a bypass cannot authorise rewriting its own record.',
+    );
+  }
+
+  const now = new Date();
+  const tokenId = randomUUID();
+  const row = {
+    ts: now.toISOString(),
+    actor: 'agent',                       // stamped here; never caller-supplied
+    path,
+    reason: reason.trim(),
+    operation: typeof operation === 'string' ? operation : null,
+    token_id: tokenId,
+  };
+
+  // ── Ledger and baseline FIRST ──────────────────────────────────────────────
+  const ledgerPath = join(cwd, LEDGER_REL);
+  ensureDir(dirname(ledgerPath));
+  appendFileSync(ledgerPath, `${JSON.stringify(row)}\n`);
+  writeAttestBaseline(cwd);
+
+  // ── Then the token ─────────────────────────────────────────────────────────
+  const grantsDir = join(cwd, GRANTS_REL);
+  ensureDir(grantsDir);
+  const expiresAt = new Date(now.getTime() + GRANT_TTL_MS).toISOString();
+  writeFileSync(
+    join(grantsDir, `${tokenId}.json`),
+    `${JSON.stringify({
+      token_id: tokenId,
+      path,
+      actor: 'agent',
+      operation: row.operation,
+      issued_at: now.toISOString(),
+      expires_at: expiresAt,
+    }, null, 2)}\n`,
+    { flag: 'wx' },                       // exclusive create: mint is serialized too
+  );
+
+  return { token_id: tokenId, path, expires_at: expiresAt };
+}
+
+/** Re-attest the bypass ledger. Called only from the append path — never as a
+ *  standalone "fix", which would be the laundering step (S5 R1). */
+function writeAttestBaseline(cwd) {
+  const ledgerPath = join(cwd, LEDGER_REL);
+  const bytes = existsSync(ledgerPath) ? readFileSync(ledgerPath) : Buffer.alloc(0);
+  const attestPath = join(cwd, ATTEST_REL);
+  ensureDir(dirname(attestPath));
+  writeFileSync(attestPath, `${JSON.stringify(baselineFor(bytes), null, 2)}\n`);
+}
+
+/**
+ * Claim a live grant for exactly `path`. Returns true if the write may proceed.
+ *
+ * Never throws: the hook's policy is fail-open, and a claim that explodes must
+ * not wedge the session. A false return means "no grant" and the caller denies
+ * on its own terms.
+ */
+export function claimGrant(cwd, path) {
+  try {
+    const grantsDir = join(cwd, GRANTS_REL);
+    if (!existsSync(grantsDir)) return false;
+
+    // A token is only honoured if its row is in the ledger. This is what stops
+    // a raw-written token file from being consumable — the Bash-forgery case.
+    // It binds the two artifacts without pretending to be crypto: an actor who
+    // writes BOTH still passes, which is the documented ceiling.
+    const ledgerTokenIds = new Set(
+      readOverrideLedger(cwd).filter((r) => r?.path === path).map((r) => r?.token_id),
+    );
+    if (ledgerTokenIds.size === 0) return false;
+
+    const now = Date.now();
+    for (const entry of readdirSync(grantsDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      const tokenPath = join(grantsDir, entry.name);
+
+      let token;
+      try { token = JSON.parse(readFileSync(tokenPath, 'utf8')); } catch { continue; }
+      if (token?.path !== path) continue;
+      if (!ledgerTokenIds.has(token?.token_id)) continue;
+
+      // Expiry from the immutable stamp, NOT mtime: a checkout gives a file a
+      // fresh mtime, which would revive a mistakenly committed token.
+      const expiresAt = Date.parse(token?.expires_at ?? '');
+      if (!Number.isFinite(expiresAt) || expiresAt <= now) continue;
+
+      // The claim. Exactly one caller can rename a given path; losers get ENOENT.
+      const consumedDir = join(grantsDir, CONSUMED_SUBDIR);
+      ensureDir(consumedDir);
+      try {
+        renameSync(tokenPath, join(consumedDir, entry.name));
+        return true;
+      } catch {
+        continue;                        // another process won; try the next token
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}

package/lib/canon-registry.js

@@ -30,13 +30,25 @@
 // contract test pins these against the legacy values.
 const TOOLS_FOR_ROADMAP = ['add_roadmap_entry', 'set_feature_status', 'propose_followup'];
 const TOOLS_FOR_CHANGELOG = ['add_changelog_entry'];
+/** The override's governance state is written only by the grant tool itself. */
+const TOOLS_FOR_OVERRIDE = ['canon_override_grant'];
 const TOOLS_FOR_FEATURE_JSON = [
   'add_roadmap_entry',
   'set_feature_status',
   'link_artifact',
   'link_features',
   'record_completion',
+  // COMP-LIFECYCLE-BACKFILL S3-2: writes feature.json through the completion gate via HTTP.
+  'backfill_completion',
   'propose_followup',
+  // COMP-COVERAGE-GATE C2 (2026-08-24): both write feature.json server-side via
+  // _postLifecycle (server/vision-routes.js:366 status write-back, :451
+  // kill→KILLED) and were missing here. `entry.tools` feeds only the
+  // canon-guard deny message ("use one of these tools instead") — no allow/deny
+  // decision reads it — so this widens no enforcement; it stops the rejection
+  // message from omitting two legitimate alternatives.
+  'complete_feature',
+  'kill_feature',
 ];
 
 /**
@@ -82,14 +94,26 @@ function matchJudgment(path) {
   return typeof path === 'string' && path.startsWith('docs/judgment/');
 }
 
+/**
+ * Prefix match on a directory, requiring the separator so that a sibling with
+ * a longer name (`canon-grants-backup/`) cannot masquerade as a child.
+ */
+function matchUnder(dir) {
+  return (path) => typeof path === 'string' && path.startsWith(`${dir}/`);
+}
+
 // ── The registry ─────────────────────────────────────────────────────────────
 
 /**
  * @typedef {object} CanonEntry
  * @property {string} id            — stable identifier
+ * @property {string} display       — human-readable path pattern, for status/help output
  * @property {string} writer        — the module that legitimately produces this path
  * @property {string[]} tools       — typed tools authorised to write it
  * @property {Array<'ship'|'hook'|'pre-commit'>} enforcedBy — points that guard it
+ * @property {boolean} [overrideEligible] — may a canon override be granted FOR
+ *   this path? Absent means yes. Set false for the override's own governance
+ *   state, which must be guarded without being grantable.
  * @property {(path:string, featuresDir:string)=>boolean} matches
  */
 
@@ -97,6 +121,7 @@ function matchJudgment(path) {
 const REGISTRY = [
   {
     id: 'roadmap',
+    display: 'ROADMAP.md',
     writer: 'lib/roadmap-gen.js',
     tools: TOOLS_FOR_ROADMAP,
     enforcedBy: ['ship'],
@@ -104,6 +129,7 @@ const REGISTRY = [
   },
   {
     id: 'changelog',
+    display: 'CHANGELOG.md',
     writer: 'lib/changelog-writer.js',
     tools: TOOLS_FOR_CHANGELOG,
     enforcedBy: ['ship'],
@@ -111,6 +137,7 @@ const REGISTRY = [
   },
   {
     id: 'feature-json',
+    display: '<features>/*/feature.json',
     writer: 'lib/feature-writer.js',
     tools: TOOLS_FOR_FEATURE_JSON,
     enforcedBy: ['ship'],
@@ -118,11 +145,50 @@ const REGISTRY = [
   },
   {
     id: 'judgment',
+    display: 'docs/judgment/**',
     writer: 'lib/judgment-writer.js',
     tools: JUDGMENT_WRITE_TOOLS,
     enforcedBy: ['hook'],
     matches: (path) => matchJudgment(path),
   },
+
+  // ── Governance class (COMP-CANON-OVERRIDE S1) ──────────────────────────────
+  // The override's own state. Guarded like any canon, and additionally
+  // `overrideEligible: false` so the override cannot be turned on itself:
+  // without this, "hook-registered" and "grantable" are the same set, and an
+  // agent could grant a bypass FOR the bypass ledger and then rewrite it
+  // (gate round 2, finding 2). The grant directory is governance state for the
+  // same reason — unregistered, a raw-written token would be consumable with
+  // no ledger row at all (finding 1).
+  //
+  // Runtime-scoped, like every hook guarantee: `Bash` never reaches this.
+  {
+    id: 'override-ledger',
+    display: '.compose/canon-overrides.jsonl',
+    writer: 'lib/canon-override.js',
+    tools: TOOLS_FOR_OVERRIDE,
+    enforcedBy: ['hook'],
+    overrideEligible: false,
+    matches: matchExact('.compose/canon-overrides.jsonl'),
+  },
+  {
+    id: 'override-attest',
+    display: '.compose/canon-overrides-attest.json',
+    writer: 'lib/canon-override.js',
+    tools: TOOLS_FOR_OVERRIDE,
+    enforcedBy: ['hook'],
+    overrideEligible: false,
+    matches: matchExact('.compose/canon-overrides-attest.json'),
+  },
+  {
+    id: 'override-grants',
+    display: '.compose/data/canon-grants/**',
+    writer: 'lib/canon-override.js',
+    tools: TOOLS_FOR_OVERRIDE,
+    enforcedBy: ['hook'],
+    overrideEligible: false,
+    matches: matchUnder('.compose/data/canon-grants'),
+  },
 ];
 
 // ── Public API ───────────────────────────────────────────────────────────────
@@ -149,6 +215,33 @@ export function isGuarded(path, opts) {
   return matchEntry(path, opts) !== null;
 }
 
+/**
+ * True if a canon override may be granted for `path` at `point`.
+ *
+ * Deliberately NOT the same predicate as `isGuarded`. Two paths are guarded
+ * but ungrantable:
+ *   - governance state (`overrideEligible: false`) — else the override could
+ *     authorise rewriting its own audit trail;
+ *   - anything not guarded at THIS point — a grant for a ship-only path is
+ *     meaningless, because the hook already allows it, and would write a
+ *     misleading bypass row.
+ * An unguarded path is likewise ineligible: nothing is blocking it, so there
+ * is nothing to override (the lockout invariant).
+ */
+/**
+ * Human-readable path patterns guarded at `point`, for status and help output.
+ * Derived rather than hand-written: a hardcoded string in `compose guard
+ * status` silently under-reported the guarded set the moment S1 widened it.
+ */
+export function guardedDisplaysFor(point) {
+  return REGISTRY.filter((e) => e.enforcedBy.includes(point)).map((e) => e.display);
+}
+
+export function isOverrideEligible(path, opts) {
+  const entry = matchEntry(path, opts);
+  return entry !== null && entry.overrideEligible !== false;
+}
+
 /** The typed tools authorised to write `path` at `point`, or [] if unguarded. */
 export function toolsForPath(path, opts) {
   const entry = matchEntry(path, opts);
@@ -173,6 +266,17 @@ export function featureCodeForPath(path, { featuresDir }) {
   return middle;
 }
 
+/**
+ * The registry as plain data — `{ id, display, tools }` per entry, deep-copied.
+ *
+ * Exists so COMP-COVERAGE-GATE can cross-check `entry.tools` against the tool
+ * inventory without reaching into `_internals` (which is test-only) and without
+ * being able to mutate the live registry.
+ */
+export function canonEntries() {
+  return REGISTRY.map((e) => ({ id: e.id, display: e.display, tools: [...e.tools] }));
+}
+
 /** The entry ids guarded at `point` (for the contract test + introspection). */
 export function guardedPatternIdsFor(point) {
   return REGISTRY.filter((e) => e.enforcedBy.includes(point)).map((e) => e.id);

package/lib/cli-commands.js

@@ -0,0 +1,144 @@
+/**
+ * cli-commands.js — COMP-AUDIT-13: the single source of truth for compose's
+ * top-level command surface.
+ *
+ * `compose --help` (bin/compose.js) and the Command Index in docs/cli.md are
+ * both rendered from COMMANDS here, so installed capability can never again be
+ * invisible unless a command is missing from this table — and a drift-guard test
+ * (test/cli-commands.test.js) asserts this table matches the real dispatch
+ * branches in bin/compose.js in both directions.
+ *
+ * To add a command: add its `cmd === '<name>'` branch in bin/compose.js AND a
+ * row here. The test fails until both exist.
+ */
+
+/**
+ * @typedef {Object} Command
+ * @property {string} name        Canonical command token (matches `cmd === '<name>'`)
+ * @property {string[]} aliases   Alternate tokens that dispatch the same command
+ * @property {string} group       Display group (must be one of COMMAND_GROUPS)
+ * @property {string} summary     One-line description (help + docs index)
+ */
+
+/** Ordered display groups. */
+export const COMMAND_GROUPS = [
+  'Getting started',
+  'Features & roadmap',
+  'Build & implement',
+  'Lifecycle, gates & review',
+  'Vision, ideas & tracking',
+  'App, integrations & runtime',
+  'Maintenance & info',
+];
+
+/** @type {Command[]} */
+export const COMMANDS = [
+  // Getting started
+  { name: 'init', aliases: [], group: 'Getting started', summary: 'Initialize Compose in the current project' },
+  { name: 'setup', aliases: ['sync'], group: 'Getting started', summary: 'Install/sync global Compose skills' },
+  { name: 'install', aliases: [], group: 'Getting started', summary: 'Legacy bootstrap — runs init + setup' },
+  { name: 'import', aliases: [], group: 'Getting started', summary: 'Scan an existing project and generate a structured analysis' },
+  { name: 'doctor', aliases: [], group: 'Getting started', summary: 'Check external skill dependencies' },
+  { name: 'update', aliases: ['upgrade'], group: 'Getting started', summary: 'Pull latest compose, reinstall deps, refresh global skill' },
+
+  // Features & roadmap
+  { name: 'new', aliases: [], group: 'Features & roadmap', summary: 'Kickoff a product (research, brainstorm, roadmap, scaffold)' },
+  { name: 'feature', aliases: [], group: 'Features & roadmap', summary: 'Add a single feature (folder, design seed, ROADMAP entry)' },
+  { name: 'roadmap', aliases: [], group: 'Features & roadmap', summary: 'Show roadmap status; generate/migrate/check ROADMAP.md' },
+  { name: 'triage', aliases: [], group: 'Features & roadmap', summary: 'Analyze a feature and recommend a build profile' },
+  { name: 'qa-scope', aliases: [], group: 'Features & roadmap', summary: "Show affected routes from a feature's changed files" },
+
+  // Build & implement
+  { name: 'build', aliases: [], group: 'Build & implement', summary: 'Run a feature through the headless lifecycle' },
+  { name: 'fix', aliases: [], group: 'Build & implement', summary: 'Run a bug through the headless bug-fix lifecycle' },
+  { name: 'plan', aliases: [], group: 'Build & implement', summary: 'Plan work into a structured roadmap from a prompt' },
+  { name: 'gsd', aliases: [], group: 'Build & implement', summary: 'Per-task fresh-context dispatch from a blueprint + Boundary Map' },
+  { name: 'pipeline', aliases: [], group: 'Build & implement', summary: 'View and edit the build pipeline' },
+  { name: 'experiment', aliases: [], group: 'Build & implement', summary: 'Run an A/B model experiment from a spec' },
+
+  // Lifecycle, gates & review
+  { name: 'gates', aliases: ['gate'], group: 'Lifecycle, gates & review', summary: 'List and resolve pending gates' },
+  { name: 'loops', aliases: [], group: 'Lifecycle, gates & review', summary: 'Manage iteration loops for a feature' },
+  { name: 'guard', aliases: [], group: 'Lifecycle, gates & review', summary: 'Manage the canon guard and drift detection' },
+  { name: 'validate', aliases: [], group: 'Lifecycle, gates & review', summary: 'Validate feature/project artifacts against contracts' },
+  { name: 'record-completion', aliases: [], group: 'Lifecycle, gates & review', summary: 'Record a completion bound to a commit SHA (flips status to COMPLETE)' },
+  { name: 'lineage', aliases: [], group: 'Lifecycle, gates & review', summary: 'PROV-O artifact lineage: stamp | stale | show' },
+  { name: 'context', aliases: [], group: 'Lifecycle, gates & review', summary: 'Show the build decision log' },
+
+  // Vision, ideas & tracking
+  { name: 'items', aliases: [], group: 'Vision, ideas & tracking', summary: 'List vision items from local state (no server)' },
+  { name: 'ideabox', aliases: [], group: 'Vision, ideas & tracking', summary: 'Capture, review, and promote product ideas' },
+  { name: 'judgment', aliases: [], group: 'Vision, ideas & tracking', summary: "Judgment records: trace a position's causal ancestry" },
+  { name: 'metrics', aliases: [], group: 'Vision, ideas & tracking', summary: 'Report dispatch, settlement, and triage metrics' },
+  { name: 'tracker', aliases: [], group: 'Vision, ideas & tracking', summary: 'Tracker provider status and op-log sync' },
+
+  // App, integrations & runtime
+  { name: 'start', aliases: [], group: 'App, integrations & runtime', summary: 'Start the compose app (UI + API) for this project' },
+  { name: 'remote', aliases: [], group: 'App, integrations & runtime', summary: 'Manage remote access: pair, list, revoke, status' },
+  { name: 'smartmemory', aliases: [], group: 'App, integrations & runtime', summary: 'Sync feature-events/journal/artifacts into SmartMemory' },
+
+  // Maintenance & info
+  { name: 'migrate-state', aliases: [], group: 'Maintenance & info', summary: 'Run pending feature.json state migrations' },
+  { name: 'migrate-anon', aliases: [], group: 'Maintenance & info', summary: 'Promote anonymous ROADMAP rows to typed features (interactive)' },
+  { name: 'hooks', aliases: [], group: 'Maintenance & info', summary: 'Manage Claude Code hooks (install | uninstall | status)' },
+  { name: 'version', aliases: ['--version', '-V'], group: 'Maintenance & info', summary: 'Print compose version, git SHA, and install root' },
+];
+
+/** Every token (names + aliases) that should dispatch to a command. */
+export function allCommandTokens() {
+  return COMMANDS.flatMap((c) => [c.name, ...c.aliases]);
+}
+
+/** A command's display label: `name` plus any aliases, e.g. `setup, sync`. */
+function labelOf(cmd) {
+  return cmd.aliases.length ? `${cmd.name}, ${cmd.aliases.join(', ')}` : cmd.name;
+}
+
+/**
+ * Render the grouped `compose --help` body from COMMANDS.
+ * @returns {string}
+ */
+export function renderHelp() {
+  const lines = ['Usage: compose <command>', ''];
+  const width = Math.max(...COMMANDS.map((c) => labelOf(c).length));
+  for (const group of COMMAND_GROUPS) {
+    const inGroup = COMMANDS.filter((c) => c.group === group);
+    if (!inGroup.length) continue;
+    lines.push(`${group}:`);
+    for (const cmd of inGroup) {
+      lines.push(`  ${labelOf(cmd).padEnd(width)}  ${cmd.summary}`);
+    }
+    lines.push('');
+  }
+  lines.push('Run `compose <command> --help` (or see docs/cli.md) for command details.');
+  return lines.join('\n');
+}
+
+/**
+ * Render the docs/cli.md Command Index — a complete, grouped table generated
+ * from COMMANDS. The completeness test in test/cli-commands.test.js asserts
+ * every command appears in cli.md, so this table cannot silently omit one.
+ * @returns {string}
+ */
+export function renderCommandIndex() {
+  const out = [
+    '## Command Index',
+    '',
+    '<!-- Generated from lib/cli-commands.js (COMP-AUDIT-13). Every shipped command appears here. -->',
+    '',
+  ];
+  for (const group of COMMAND_GROUPS) {
+    const inGroup = COMMANDS.filter((c) => c.group === group);
+    if (!inGroup.length) continue;
+    out.push(`### ${group}`, '', '| Command | Summary |', '|---|---|');
+    for (const cmd of inGroup) {
+      const label = cmd.aliases.length
+        ? `\`compose ${cmd.name}\` (alias: ${cmd.aliases.map((a) => `\`${a}\``).join(', ')})`
+        : `\`compose ${cmd.name}\``;
+      // Escape pipes so a summary like "stamp | stale | show" can't break the table.
+      out.push(`| ${label} | ${cmd.summary.replace(/\|/g, '\\|')} |`);
+    }
+    out.push('');
+  }
+  return out.join('\n');
+}

package/lib/codex-preflight.js

@@ -115,29 +115,40 @@ export async function preflightCodexWorktreeProbe({
   // Unique per-run filename so a file committed in the repo (carried into the
   // detached worktree from HEAD) can never make the probe false-pass.
   const probeName = `codex-probe-${ts}.txt`;
+  let terminationUnconfirmed = false;
   try {
     const prompt =
       `Write a file named ${probeName} in the current working directory whose exact ` +
       `contents are the single line: ${PROBE_SENTINEL}\n` +
       `Do nothing else. This is an environment write-probe.`;
     try {
-      // Bound the agent run — a hang here would otherwise stall the build and skip
-      // the finally cleanup. On timeout the race rejects and we fall to the catch.
-      await Promise.race([
-        stratum.runAgentText('codex', prompt, {
+      // Wait for acknowledged termination before removing the worktree. A
+      // Promise.race timeout could delete it while the agent was still writing.
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), PROBE_AGENT_TIMEOUT_MS);
+      timer.unref?.();
+      try {
+        await stratum.runAgentText('codex', prompt, {
           cwd: wtPath,
+          sandboxMode: 'workspace-write',
+          signal: controller.signal,
           telemetry: {
             site: 'preflight',
             project_cwd: projectCwd,
             build_id: buildId,
             feature_code: featureCode,
           },
-        }),
-        new Promise((_, reject) =>
-          setTimeout(() => reject(new Error(`probe timed out after ${PROBE_AGENT_TIMEOUT_MS}ms`)), PROBE_AGENT_TIMEOUT_MS).unref?.()
-        ),
-      ]);
+        });
+      } finally {
+        clearTimeout(timer);
+      }
     } catch (err) {
+      if (['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(err?.code)) {
+        terminationUnconfirmed = true;
+        err.worktreePath = wtPath;
+        err.message += `; probe worktree retained at ${wtPath}`;
+        throw err;
+      }
       const result = { ok: false, reason: `Codex agent run failed/timed out inside the worktree: ${err?.message ?? err}` };
       writeProbeCache(dataDir, result);
       return result;
@@ -153,10 +164,12 @@ export async function preflightCodexWorktreeProbe({
     writeProbeCache(dataDir, result);
     return result;
   } finally {
-    try {
-      execSync(`git worktree remove "${wtPath}" --force`, { cwd, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe' });
-    } catch {
-      try { execSync(`rm -rf "${wtPath}"`, { encoding: 'utf-8', timeout: 10_000 }); } catch { /* give up */ }
+    if (!terminationUnconfirmed) {
+      try {
+        execSync(`git worktree remove "${wtPath}" --force`, { cwd, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe' });
+      } catch {
+        try { execSync(`rm -rf "${wtPath}"`, { encoding: 'utf-8', timeout: 10_000 }); } catch { /* give up */ }
+      }
     }
   }
 }