@smartmemory/compose 0.3.7 → 0.4.0

package/lib/guard-enrol.js

@@ -0,0 +1,254 @@
+import { execFile as defaultExecFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { access, lstat as defaultLstat, mkdtemp as defaultMkdtemp, readFile as defaultReadFile, rm as defaultRm, stat as defaultStat, writeFile as defaultWriteFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  CUSTODY_TIMEOUT_MS, custodyBackend as defaultCustodyBackend, custodySign as defaultCustodySign,
+  GUARD_DIR, HINT_ENROL, PRIVATE_DIR, PUBKEY_PATH, SIGNER_PATH, SUDO_ENV,
+  SUDOERS_PATH, SUDO_LOCAL_PATH,
+} from './guard-custody.js';
+import { guardDescriptors as defaultGuardDescriptors } from '../server/stratum-client.js';
+
+const require = createRequire(import.meta.url);
+const sshsig = await import(require.resolve('@smartmemory/stratum/dist/guard/sshsig.js'));
+const { parseAllowedSigners, sshFingerprint, verifySshsig } = sshsig;
+const DESCRIPTOR_NAMESPACE = 'stratum-guard-descriptors';
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGED_SIGNER = path.resolve(MODULE_DIR, '..', 'scripts', 'guard-sign', 'compose-guard-sign.sh');
+
+export const PRINCIPAL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export const SUDOERS_TEXT = (principal) =>
+  `Defaults!${SIGNER_PATH} timestamp_timeout=0\n${principal} ALL=(root) ${SIGNER_PATH}\n`;
+
+function spawnWithInput(execFile, file, args, options, bytes) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (error, stdout = '', stderr = '') => {
+      if (settled) return;
+      settled = true;
+      resolve({ error, stdout, stderr });
+    };
+    try {
+      const child = execFile(file, args, options, done);
+      child?.stdin?.end(bytes);
+      child?.on?.('error', (error) => done(error));
+    } catch (error) {
+      done(error);
+    }
+  });
+}
+
+function firstLine(value, fallback = 'command failed') {
+  return String(value || '').split(/\r?\n/, 1)[0] || fallback;
+}
+
+/** Check every existing ancestor without following a symlink at any level. */
+export async function validateAncestry(target, deps = {}) {
+  const lstat = deps.lstat ?? defaultLstat;
+  const stat = deps.stat ?? defaultStat;
+  let current = path.resolve(target);
+  for (;;) {
+    let lst;
+    try {
+      lst = await lstat(current);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        const parent = path.dirname(current);
+        if (parent === current) return { ok: false, offending: { path: current, reason: 'missing' } };
+        current = parent;
+        continue;
+      }
+      return { ok: false, offending: { path: current, reason: firstLine(error?.message) } };
+    }
+    if (lst.isSymbolicLink()) return { ok: false, offending: { path: current, reason: 'symlink' } };
+    let info;
+    try { info = await stat(current); } catch (error) {
+      return { ok: false, offending: { path: current, reason: firstLine(error?.message) } };
+    }
+    if (info.uid !== 0) return { ok: false, offending: { path: current, reason: 'not root-owned' } };
+    if ((info.mode & 0o022) !== 0) return { ok: false, offending: { path: current, reason: 'group or world writable' } };
+    const parent = path.dirname(current);
+    if (parent === current) return { ok: true, offending: null };
+    current = parent;
+  }
+}
+
+/** Resolve the package's reviewable source trust root, never an environment path. */
+export async function locateTrustRoot(deps = {}) {
+  const packageJson = deps.packageJsonPath ?? require.resolve('@smartmemory/stratum/package.json');
+  const packageRoot = deps.packageRoot ?? path.dirname(packageJson);
+  const exists = deps.exists ?? (async (file) => access(file).then(() => true, () => false));
+  const source = path.join(packageRoot, 'contracts', 'guard-signers.allowed');
+  if (await exists(source)) return { kind: 'source', path: source, checkoutRoot: packageRoot };
+  const dist = path.join(packageRoot, 'dist', 'contracts', 'guard-signers.allowed');
+  if (await exists(dist)) return { kind: 'dist', path: dist, checkoutRoot: null };
+  throw new Error(`could not locate Stratum guard trust root under ${packageRoot}`);
+}
+
+/** Produce a whole-file parsed trust-root candidate, never a partial append. */
+export function candidateTrustRoot(current, principal, publicKeyLine) {
+  if (!PRINCIPAL_RE.test(principal)) throw new Error(`invalid principal ${JSON.stringify(principal)}; expected ${PRINCIPAL_RE}`);
+  if (typeof publicKeyLine !== 'string' || /[^\x20-\x7e]/.test(publicKeyLine.trim())) {
+    throw new Error('public key line must be printable ASCII');
+  }
+  const key = parseAllowedSigners(`candidate ${publicKeyLine.trim()}\n`)[0];
+  if (!key) throw new Error('public key line did not contain a signer');
+  const signers = parseAllowedSigners(current);
+  const present = signers.some((entry) => entry.fingerprint === key.fingerprint);
+  const line = `${principal} ${publicKeyLine.trim()}`;
+  const text = present ? current : `${current}${current && !current.endsWith('\n') ? '\n' : ''}${line}\n`;
+  const parsed = parseAllowedSigners(text);
+  return { present, text, candidate: text, line, fingerprint: key.fingerprint, signers: parsed };
+}
+
+export function installPlan(principal) {
+  if (!PRINCIPAL_RE.test(principal)) throw new Error(`invalid principal ${JSON.stringify(principal)}; expected ${PRINCIPAL_RE}`);
+  return [
+    `install root-owned signer: ${SIGNER_PATH}`,
+    `create root-owned signing key: ${PRIVATE_DIR}/signing-key`,
+    `publish public key: ${PUBKEY_PATH}`,
+    `install sudoers rule: ${SUDOERS_PATH}`,
+    `enable Touch ID for sudo: ${SUDO_LOCAL_PATH}`,
+    `add signer principal to Stratum trust root: ${principal}`,
+    `root installation script:\n${installScript(principal)}`,
+  ];
+}
+
+const SIGNER_HEREDOC_DELIMITER = 'COMPOSE_GUARD_SIGNER_SCRIPT';
+
+/**
+ * Exact root-side installation payload. It is intentionally shell-only and
+ * idempotent.
+ *
+ * Every `${…}` interpolated into this template is either a constant path
+ * exported by guard-custody.js (GUARD_DIR, PRIVATE_DIR, SIGNER_PATH,
+ * PUBKEY_PATH, SUDOERS_PATH, SUDO_LOCAL_PATH — never a runtime/user-supplied
+ * string) or shell text already embedded via a quoted heredoc (`sudoers`,
+ * `signerScript`) rather than interpolated inline. The packaged signer's
+ * module-directory path is never interpolated into the script at all: its
+ * bytes are read here and written to SIGNER_PATH via a quoted heredoc, so a
+ * compose install path containing a space or shell metacharacter cannot break
+ * or inject into the root shell.
+ */
+export function installScript(principal, deps = {}) {
+  if (!PRINCIPAL_RE.test(principal)) throw new Error(`invalid principal ${JSON.stringify(principal)}; expected ${PRINCIPAL_RE}`);
+  const sudoers = SUDOERS_TEXT(principal).trimEnd();
+  const readSigner = deps.readSigner ?? (() => readFileSync(PACKAGED_SIGNER, 'utf8'));
+  const signerScript = readSigner();
+  if (signerScript.includes(SIGNER_HEREDOC_DELIMITER)) {
+    throw new Error(`packaged signer script contains the heredoc delimiter ${SIGNER_HEREDOC_DELIMITER}; choose a different delimiter`);
+  }
+  return `set -eu\numask 022\nPATH=/usr/bin:/bin:/usr/sbin\nexport PATH\n/bin/mkdir -p /Library/Compose/guard/private/tmp\n/bin/chmod 0755 /Library/Compose ${GUARD_DIR}\n/bin/chmod 0700 ${PRIVATE_DIR} ${PRIVATE_DIR}/tmp\n/bin/cat > ${SIGNER_PATH} <<'${SIGNER_HEREDOC_DELIMITER}'\n${signerScript.trimEnd()}\n${SIGNER_HEREDOC_DELIMITER}\n/usr/sbin/chown root:wheel ${SIGNER_PATH}\n/bin/chmod 0755 ${SIGNER_PATH}\nif [ ! -f ${PRIVATE_DIR}/signing-key ]; then\n  /usr/bin/ssh-keygen -t ed25519 -N '' -q -f ${PRIVATE_DIR}/signing-key -C compose-guard\nfi\n/usr/sbin/chown root:wheel ${PRIVATE_DIR}/signing-key ${PRIVATE_DIR}/signing-key.pub\n/bin/chmod 0600 ${PRIVATE_DIR}/signing-key\n/bin/cp ${PRIVATE_DIR}/signing-key.pub ${PUBKEY_PATH}\n/usr/sbin/chown root:wheel ${PUBKEY_PATH}\n/bin/chmod 0644 ${PUBKEY_PATH}\n_sudoers_tmp=${SUDOERS_PATH}.tmp.$$\n/bin/cat > "$_sudoers_tmp" <<'COMPOSE_GUARD_SUDOERS'\n${sudoers}\nCOMPOSE_GUARD_SUDOERS\n/usr/sbin/visudo -cf "$_sudoers_tmp"\n/usr/bin/install -o root -g wheel -m 0440 "$_sudoers_tmp" ${SUDOERS_PATH}\n/bin/rm -f "$_sudoers_tmp"\nif [ ! -f ${SUDO_LOCAL_PATH} ]; then\n  /bin/cat > ${SUDO_LOCAL_PATH} <<'COMPOSE_GUARD_PAM'\nauth sufficient pam_tid.so\nCOMPOSE_GUARD_PAM\nelif ! /usr/bin/grep -Eq '^[[:space:]]*auth[[:space:]]+sufficient[[:space:]]+pam_tid\\.so' ${SUDO_LOCAL_PATH}; then\n  /bin/cat >> ${SUDO_LOCAL_PATH} <<'COMPOSE_GUARD_PAM'\nauth sufficient pam_tid.so\nCOMPOSE_GUARD_PAM\nfi\n/usr/sbin/chown root:wheel ${SUDO_LOCAL_PATH}\n/bin/chmod 0644 ${SUDO_LOCAL_PATH}\necho 'ok directories'\necho 'ok signer'\necho 'ok key'\necho 'ok sudoers'\necho 'ok pam_tid'\n`;
+}
+
+/** Sign and cryptographically verify a durable fixture against exactly one public key. */
+export async function roundTrip({ custodySign, publicKeyLine, deps = {} }) {
+  const mkdtemp = deps.mkdtemp ?? defaultMkdtemp;
+  const writeFile = deps.writeFile ?? defaultWriteFile;
+  const readFile = deps.readFile ?? defaultReadFile;
+  const rm = deps.rm ?? defaultRm;
+  const dir = await mkdtemp(path.join(tmpdir(), 'compose-guard-enrol-'));
+  const file = path.join(dir, 'descriptors.json');
+  const bytes = Buffer.from('{"version":1,"descriptors":[]}\n');
+  try {
+    await writeFile(file, bytes, { mode: 0o600 });
+    const signed = await custodySign({ bytes, namespace: DESCRIPTOR_NAMESPACE });
+    if (!signed?.ok) throw new Error(signed?.message || 'fixture signature was not approved');
+    await writeFile(`${file}.sig`, signed.armored, { mode: 0o600 });
+    const signer = parseAllowedSigners(`fixture ${publicKeyLine.trim()}\n`)[0];
+    if (!signer) throw new Error('public key line did not contain a signer');
+    verifySshsig(await readFile(file), await readFile(`${file}.sig`, 'utf8'), DESCRIPTOR_NAMESPACE, [signer.publicKey]);
+    return { dir, file, sig: `${file}.sig`, namespace: DESCRIPTOR_NAMESPACE, fingerprint: signer.fingerprint, cleanup: () => rm(dir, { recursive: true, force: true }) };
+  } catch (error) {
+    await rm(dir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export async function rebuildStratumDist(checkoutRoot, deps = {}) {
+  const { error, stderr } = await spawnWithInput(deps.execFile ?? defaultExecFile, 'npm', ['run', 'build'], { cwd: checkoutRoot, timeout: CUSTODY_TIMEOUT_MS }, Buffer.alloc(0));
+  if (error) throw new Error(`Stratum build failed: ${firstLine(stderr || error.message)}`);
+}
+
+function result(status, lines, extra = {}) { return { status, lines, ...extra }; }
+
+/** Complete, deliberately ordered enrolment ceremony. Every side effect is injectable. */
+export async function runEnrol({ principal = process.env.USER || process.env.USERNAME || '' } = {}, deps = {}) {
+  // The plan must always reach a human before the root step runs — a silent
+  // no-op emitter would let any in-process caller (including a bare
+  // `runGuardEnrol()`) reach `sudo -k /bin/sh -s` with the plan never shown.
+  // So the emitter is mandatory, checked before the backend check, before any
+  // spawn or filesystem access.
+  if (typeof deps.emit !== 'function') {
+    return result('refused', ['enrol requires a line emitter so the plan is shown before the root step'], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  }
+  const backend = (deps.custodyBackend ?? defaultCustodyBackend)();
+  if (backend !== 'sudo') return result('refused', ['enrol requires the sudo custody backend on macOS'], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  if (!PRINCIPAL_RE.test(principal)) return result('refused', [`invalid principal ${JSON.stringify(principal)}; expected ${PRINCIPAL_RE}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+
+  const ancestry = deps.validateAncestry ?? validateAncestry;
+  const installTargets = [GUARD_DIR, SIGNER_PATH, PUBKEY_PATH, PRIVATE_DIR, SUDOERS_PATH, SUDO_LOCAL_PATH];
+  for (const target of installTargets) {
+    const checked = await ancestry(target, deps);
+    if (!checked.ok) return result('refused', [`unsafe install ancestry at ${checked.offending.path}: ${checked.offending.reason}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  }
+  // `installScript` now reads the packaged signer from disk and can throw (a
+  // missing/unreadable signer, or a heredoc-delimiter collision); `emit` is
+  // caller-supplied and can throw too. Neither has spawned or written
+  // anything yet, so a failure here must still return the refused envelope,
+  // not reject the promise.
+  let script;
+  try {
+    script = installScript(principal, deps);
+    const emit = deps.emit;
+    for (const line of installPlan(principal)) emit(line);
+    emit('root installation follows:');
+  } catch (error) {
+    return result('refused', [`enrol preparation failed: ${firstLine(error.message)}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  }
+  const lines = [];
+  const rootStep = await spawnWithInput(deps.execFile ?? defaultExecFile, '/usr/bin/sudo', ['-k', '/bin/sh', '-s'], { env: SUDO_ENV(), timeout: CUSTODY_TIMEOUT_MS, maxBuffer: 1 << 20 }, script);
+  if (rootStep.error) return result('refused', [...lines, `root installation failed: ${firstLine(rootStep.stderr || rootStep.error.message)}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  lines.push(...String(rootStep.stdout || '').split(/\r?\n/).filter((line) => line.startsWith('ok ')));
+
+  for (const target of installTargets) {
+    const checked = await ancestry(target, deps);
+    if (!checked.ok) return result('refused', [...lines, `unsafe installed ancestry at ${checked.offending.path}: ${checked.offending.reason}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  }
+  const readFile = deps.readFile ?? defaultReadFile;
+  let publicKeyLine;
+  try { publicKeyLine = (await readFile(PUBKEY_PATH, 'utf8')).trim(); } catch (error) {
+    return result('refused', [...lines, `could not read enrolled public key: ${firstLine(error.message)}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  }
+
+  let fixture;
+  try {
+    fixture = await roundTrip({ custodySign: deps.custodySign ?? defaultCustodySign, publicKeyLine, deps });
+  } catch (error) {
+    return result('refused', [...lines, `round-trip signature failed: ${firstLine(error.message)}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  }
+  try {
+    const trust = await (deps.locateTrustRoot ?? locateTrustRoot)(deps);
+    const current = await readFile(trust.path, 'utf8');
+    const candidate = candidateTrustRoot(current, principal, publicKeyLine);
+    if (trust.kind !== 'source') {
+      return result('refused', [...lines, `add this line to ${trust.path} in a Stratum source release:`, candidate.line], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+    }
+    if (!candidate.present) await (deps.writeFile ?? defaultWriteFile)(trust.path, candidate.text, 'utf8');
+    await (deps.rebuildStratumDist ?? rebuildStratumDist)(trust.checkoutRoot, deps);
+    const inspected = await (deps.guardDescriptors ?? defaultGuardDescriptors)(fixture.file);
+    const expected = `verified: signed by ${principal} (${fixture.fingerprint})`;
+    if (inspected?.status !== 'ok' || !String(inspected?.signature || '').startsWith(expected) || inspected?.group_or_world_writable !== false) {
+      return result('refused', [...lines, `final Stratum verification failed: ${inspected?.signature || 'no verifier verdict'}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+    }
+    return result('done', [...lines, `enrolled ${principal} (${fixture.fingerprint})`, 'done'], { fingerprint: fixture.fingerprint });
+  } catch (error) {
+    return result('refused', [...lines, `enrolment failed: ${firstLine(error?.message)}`], { code: 'upgrade_descriptor_unavailable', hint: HINT_ENROL });
+  } finally {
+    await fixture.cleanup();
+  }
+}

package/lib/health-score.js

@@ -6,7 +6,7 @@
  *   - Review findings from parallel_review's ReviewResult (canonical — STRAT-CLAUDE-EFFORT-PARITY)
  *   - Test pass/fail from coverage_check result
  *   - Contract compliance from Stratum ensure results
- *   - Doc freshness from lib/staleness.js
+ *   - Doc freshness from lib/lineage.js (findStaleArtifacts)
  *   - Plan completion from plan_completion ensure builtin
  *   - Runtime errors from build_step_done violations
  */

package/lib/ideabox-cli.js

@@ -0,0 +1,315 @@
+/**
+ * lib/ideabox-cli.js — `compose ideabox …`, writing to the record store.
+ *
+ * COMP-PLAN-IDEA-UNIFY S3b-1 (D18), rebased onto the shared operations in S3b-2
+ * (D20).
+ *
+ * Lifted out of a ~300-line inline `else if` block in `bin/compose.js` with no
+ * named symbol, in a 3,400-line file. The move is not cosmetic: it is what lets
+ * the cutover be driven in-process by a test instead of only through a
+ * subprocess, and the cutover is the part that needed testing most.
+ *
+ * WHAT THIS MODULE IS NOW
+ * -----------------------
+ * Argument parsing, presentation, and exit codes. Nothing else. Every mutation
+ * lives in `fluid/ideabox-ops.js`, which the REST API calls too — including the
+ * two invariants that used to be spelled out here and would have had to be
+ * re-remembered by every new surface:
+ *
+ *   1. the migration gate runs before any write, and
+ *   2. the projection is rewritten only after the record is durable.
+ *
+ * A surface that does not implement an invariant cannot forget it. That is the
+ * whole reason the ops module exists; see its header for the failure it prevents.
+ *
+ * Behaviour is preserved deliberately, including output wording, exit codes and
+ * flag parsing, because a cutover that also redesigns the commands cannot be
+ * reviewed: any difference becomes ambiguous between "intended" and
+ * "regression". The exceptions are documented — `normalizeTags` in the ops
+ * module, the killed-idea promote refusal (D22), and the new `resurrect`
+ * subcommand (D23).
+ */
+
+import { existsSync } from 'node:fs';
+
+import {
+  ideaboxContext,
+  addIdea,
+  addDiscussion,
+  killIdea,
+  promoteIdea,
+  resurrectIdea,
+  setPriority,
+  updateIdea,
+  IdeaboxConflict,
+  IdeaboxInvalid,
+  IdeaboxNotFound,
+} from './fluid/ideabox-ops.js';
+import { toMarkdownDate } from './fluid/ideabox-dates.js';
+import { KIND } from './fluid/provider.js';
+import { ensureIdeaboxMigrated } from './fluid/ideabox-migrate.js';
+import { writeIdeaboxProjection } from './fluid/render-ideabox.js';
+
+const USAGE = [
+  'Usage: compose ideabox <subcommand>',
+  '',
+  'Subcommands:',
+  '  add "<title>"                Add a new idea',
+  '  list                         List all ideas',
+  '  promote <ID>                 Mark idea as PROMOTED (creates feature folder)',
+  '  kill <ID> "<reason>"         Move idea to Killed Ideas',
+  '  resurrect <ID>               Return a killed idea to the live set',
+  '  pri <ID> <P0|P1|P2>          Set priority',
+  '  discuss <ID> "<comment>"     Add a discussion comment',
+  '  triage [--lens <name>]       Walk untriaged ideas and assign priorities',
+  '  render                       Rewrite the ideabox file from the records',
+];
+
+const PRIORITIES = ['P0', 'P1', 'P2'];
+const flagValue = (args, name) => {
+  const i = args.indexOf(name);
+  return i !== -1 ? args[i + 1] : undefined;
+};
+
+/** Status enum → the legacy display label the list output has always used. */
+const displayStatus = (record) => {
+  if (record.status === 'promoted') return 'PROMOTED';
+  if (record.status === 'discussing') return 'DISCUSSING';
+  return 'NEW';
+};
+
+const displayPriority = (record) => record.priority ?? '—';
+
+/**
+ * Turn an op failure into the terminal's contract: a message on stderr and a
+ * non-zero exit. Only the ops' own typed failures are handled — anything else
+ * is a bug or a broken store, and swallowing those into a tidy exit code is how
+ * a corrupt project looks healthy.
+ */
+function reportOpFailure(err) {
+  if (err instanceof IdeaboxNotFound || err instanceof IdeaboxInvalid || err instanceof IdeaboxConflict) {
+    console.error(err.message);
+    return 1;
+  }
+  throw err;
+}
+
+/**
+ * @param {string} cwd project root
+ * @param {string[]} args argv after `ideabox`
+ * @param {object} [opts]
+ * @param {object} [opts.config] already-loaded `.compose/compose.json`
+ * @returns {Promise<number>} process exit code
+ */
+export async function runIdeaboxCommand(cwd, args, opts = {}) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') {
+    for (const line of USAGE) console.log(line);
+    return 0;
+  }
+
+  const ctx = await ideaboxContext(cwd, { config: opts.config, origin: 'cli:ideabox' });
+  const { provider, ideaboxPath } = ctx;
+
+  try {
+    switch (sub) {
+      case 'add': {
+        const title = args.slice(1).find((a) => !a.startsWith('-')) || args[1];
+        if (!title) {
+          console.error('Usage: compose ideabox add "<title>" [--source "..."] [--desc "..."] [--cluster "..."]');
+          return 1;
+        }
+        const { record, createdCluster } = await addIdea(ctx, {
+          title,
+          body: flagValue(args, '--desc') ?? '',
+          source: flagValue(args, '--source') ?? '',
+          tags: flagValue(args, '--tags') ?? [],
+          cluster: flagValue(args, '--cluster') ?? null,
+        });
+        if (createdCluster) console.log(`Created cluster ${createdCluster.handle}: ${createdCluster.title}`);
+        console.log(`Added ${record.handle}: ${record.title}`);
+        return 0;
+      }
+
+      case 'list': {
+        // Read-only paths still migrate: `list` on an upgraded project must show
+        // the user's real ideas, not an empty store. It is the same import
+        // either way, and running it lazily on first read rather than first
+        // write means the upgrade happens at the least destructive moment
+        // available.
+        if (!existsSync(ideaboxPath) && !(await provider.listRecords({ kind: KIND.IDEA })).length) {
+          console.log('No ideabox found. Run: compose ideabox add "<title>"');
+          return 0;
+        }
+        await ensureIdeaboxMigrated(provider, ideaboxPath);
+        const ideas = await provider.listRecords({ kind: KIND.IDEA });
+        if (ideas.length === 0) {
+          console.log('No ideas yet.');
+          return 0;
+        }
+
+        const live = ideas.filter((i) => i.status !== 'killed');
+        const killed = ideas.filter((i) => i.status === 'killed');
+        const order = { P0: 0, P1: 1, P2: 2, '—': 3 };
+
+        for (const status of ['NEW', 'DISCUSSING', 'PROMOTED']) {
+          const group = live.filter((i) => displayStatus(i) === status);
+          if (!group.length) continue;
+          group.sort((a, b) => (order[displayPriority(a)] ?? 3) - (order[displayPriority(b)] ?? 3));
+          console.log(`\n[${status}]`);
+          for (const idea of group) {
+            const pri = displayPriority(idea) !== '—' ? ` [${displayPriority(idea)}]` : '';
+            const tags = idea.tags.length ? ` ${idea.tags.join(' ')}` : '';
+            console.log(`  ${idea.handle}${pri}  ${idea.title}${tags}`);
+          }
+        }
+
+        if (killed.length) {
+          console.log(`\n[KILLED] (${killed.length})`);
+          for (const idea of killed) {
+            console.log(`  ${idea.handle}  ${idea.title}  — ${idea.killed?.reason ?? ''}`);
+          }
+        }
+        return 0;
+      }
+
+      case 'promote': {
+        const id = args[1];
+        if (!id) {
+          console.error('Usage: compose ideabox promote <ID> [<FEATURE-CODE>]');
+          return 1;
+        }
+        const { record, featureCode, featurePath, createdFeature } =
+          await promoteIdea(ctx, id, args[2] || '');
+        if (createdFeature) console.log(`Created feature folder: ${featurePath}/`);
+        console.log(`Promoted ${record.handle} → ${featureCode}`);
+        return 0;
+      }
+
+      case 'kill': {
+        const id = args[1];
+        if (!id) {
+          console.error('Usage: compose ideabox kill <ID> "<reason>"');
+          return 1;
+        }
+        const reason = args[2] || '';
+        const { record, alreadyKilled } = await killIdea(ctx, id, reason);
+        if (alreadyKilled) {
+          console.log(`${record.handle} was already killed on ${toMarkdownDate(record.killed?.at)}: ${record.killed?.reason ?? ''}`);
+        } else {
+          console.log(`Killed ${record.handle}: ${reason}`);
+        }
+        return 0;
+      }
+
+      case 'resurrect': {
+        const id = args[1];
+        if (!id) {
+          console.error('Usage: compose ideabox resurrect <ID>');
+          return 1;
+        }
+        const { record } = await resurrectIdea(ctx, id);
+        console.log(`Resurrected ${record.handle}: ${record.title}`);
+        return 0;
+      }
+
+      case 'pri': {
+        const id = args[1];
+        const priority = args[2];
+        if (!id || !priority) {
+          console.error('Usage: compose ideabox pri <ID> <P0|P1|P2>');
+          return 1;
+        }
+        if (!PRIORITIES.includes(priority.toUpperCase()) && priority !== '—') {
+          console.error(`Invalid priority: ${priority}. Use P0, P1, P2 or —`);
+          return 1;
+        }
+        const { record } = await setPriority(ctx, id, priority);
+        console.log(`Set ${record.handle} priority → ${priority}`);
+        return 0;
+      }
+
+      case 'discuss': {
+        const id = args[1];
+        const comment = args[2];
+        if (!id || !comment) {
+          console.error('Usage: compose ideabox discuss <ID> "<comment>"');
+          return 1;
+        }
+        await addDiscussion(ctx, id, { text: comment, author: 'human' });
+        console.log(`[${new Date().toISOString().slice(0, 10)}] human: ${comment}`);
+        return 0;
+      }
+
+      case 'triage': {
+        const lensName = flagValue(args, '--lens');
+        await ensureIdeaboxMigrated(provider, ideaboxPath);
+        const ideas = await provider.listRecords({ kind: KIND.IDEA });
+        const untriaged = ideas.filter((i) => !i.priority && i.status === 'new');
+        if (!untriaged.length) {
+          console.log('No untriaged ideas.');
+          return 0;
+        }
+
+        if (lensName) {
+          const { loadLens } = await import('./ideabox.js');
+          if (!loadLens(cwd, lensName)) {
+            console.warn(`Lens not found: docs/product/ideabox-priority-${lensName}.md`);
+          } else {
+            console.log(`Using lens: ${lensName}`);
+          }
+        }
+
+        const { createInterface } = await import('node:readline');
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+        let changed = false;
+        try {
+          for (const idea of untriaged) {
+            console.log(`\n${idea.handle}: ${idea.title}`);
+            if (idea.body) console.log(`  ${idea.body.slice(0, 120)}`);
+            if (lensName) console.log(`  [lens: ${lensName}]`);
+            const answer = (await ask('  Priority [P0/P1/P2/skip]: ')).trim().toUpperCase();
+            if (PRIORITIES.includes(answer)) {
+              // The record write only. Triage is a bulk pass, so it renders once
+              // at the end rather than rewriting the whole file per answer.
+              await provider.updateRecord(idea.handle, { priority: answer });
+              changed = true;
+              console.log(`  Set ${idea.handle} → ${answer}`);
+            } else {
+              console.log('  Skipped');
+            }
+          }
+        } finally {
+          rl.close();
+        }
+
+        if (changed) {
+          await writeIdeaboxProjection(provider, ideaboxPath);
+          console.log('\nSaved.');
+        }
+        return 0;
+      }
+
+      case 'render': {
+        // The repair path. Every mutation writes the record before the
+        // projection, so a failed render leaves durable canon and a stale file;
+        // this is how the file catches up without touching a record. Also the
+        // fix for a projection that was interrupted, and the way back from any
+        // hand edit.
+        await ensureIdeaboxMigrated(provider, ideaboxPath);
+        await writeIdeaboxProjection(provider, ideaboxPath);
+        console.log(`Rendered ${ideaboxPath}`);
+        return 0;
+      }
+
+      default:
+        console.error(`Unknown ideabox subcommand: ${sub}`);
+        console.error('Run: compose ideabox --help');
+        return 1;
+    }
+  } catch (err) {
+    return reportOpFailure(err);
+  }
+}