@ijfw/memory-server 1.4.4 → 1.5.1

package/src/cross-orchestrator-cli.js

@@ -14,6 +14,7 @@ import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { writeAtomic } from './lib/atomic-io.js';
 import { runCrossOp } from './cross-orchestrator.js';
+import { chunkText, mergeFindings, CHUNKER_DEFAULTS } from './cross-audit-chunker.js';
 import { readReceipts, purgeReceipts } from './receipts.js';
 import { renderHeroLine } from './hero-line.js';
 import { ROSTER, isInstalled, isReachable } from './audit-roster.js';
@@ -21,16 +22,27 @@ import { aggregatePortfolioFindings } from './cross-project-search.js';
 import { runImport, runImportAll, listImporters } from './importers/cli.js';
 import { validateToken } from './lib/token.js';
 import { isVersionStringValid } from './lib/npm-view.js';
+import { verifyShasumCrossSource } from './lib/shasum-verify.js';
 import {
   addBlackboardNote,
   blackboardStatus,
   claimArtifact,
+  DEFAULT_CLAIM_TTL_MS,
+  evictOrphanedClaims,
   initBlackboard,
   readBlackboard,
   releaseClaim,
+  updateClaimHeartbeat,
   writeHandoff,
 } from './blackboard.js';
 import { createTeamAssembly, readTeamAssembly } from './team/generator.js';
+import {
+  addTeamRole,
+  checkTeamAssembly,
+  listTeamRoles,
+  removeTeamRole,
+  swapTeamRole,
+} from './team/modify.js';
 import {
   blockSwarmTask,
   buildSwarmPlan,
@@ -50,6 +62,8 @@ import {
 } from './swarm/worktree.js';
 import { renderSwarmDispatchPrompt } from './swarm/dispatch-prompt.js';
 import { syncCodexAgents } from './codex-agents.js';
+// v1.5.1 W2.H — memory benchmark harness (T22). Surfaced via `ijfw metrics --benchmark`.
+import { runBenchmark } from './memory/benchmark.js';
 import {
   DESIGN_ACTIONS,
   auditDesignText,
@@ -57,6 +71,12 @@ import {
   initialDesignMarkdown,
   loadDesignContext,
 } from './design-intelligence.js';
+// v1.5.1 W3.A.4 — registry-driven usage + alias help.
+// SINGLE SOURCE OF TRUTH lives at installer/src/command-registry.js;
+// import sibling-package style, matching extension-installer.js precedent.
+import {
+  COMMAND_REGISTRY,
+} from '../../installer/src/command-registry.js';
 
 // ---------------------------------------------------------------------------
 // Auditor error translator (1.2.5)
@@ -207,84 +227,37 @@ function parseArgs(argv) {
   return out;
 }
 
-const COMMAND_ALIAS_HELP = {
-  workflow: {
-    title: 'IJFW workflow',
-    usage: 'Use the ijfw-workflow skill in agents. Terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare.',
-  },
-  handoff: {
-    title: 'IJFW handoff',
-    usage: 'Use the ijfw-handoff skill in agents, or record swarm handoff text with: ijfw blackboard handoff --message "<summary>".',
-  },
-  compress: {
-    title: 'IJFW compress',
-    usage: 'Use the ijfw-compress skill in agents. Terminal context compression is host-specific and should preserve exact paths, commands, versions, and decisions.',
-  },
-  consolidate: {
-    title: 'IJFW consolidate',
-    usage: 'Use the ijfw-handoff or ijfw-memory-audit skill to consolidate decisions into memory. For swarm state, run: ijfw memory checkpoint <label>.',
-  },
-  'ijfw-audit': {
-    title: 'IJFW audit',
-    usage: 'Run verification with: ijfw preflight. For multi-model review, run: ijfw cross audit <target>.',
-  },
-  'ijfw-execute': {
-    title: 'IJFW execute',
-    usage: 'Use ijfw-workflow in agents, then terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare, ijfw swarm start <task-id>.',
-  },
-  'ijfw-help': {
-    title: 'IJFW help',
-    usage: 'Run: ijfw help. Add --browser for the rendered local guide.',
-  },
-  'ijfw-plan': {
-    title: 'IJFW plan',
-    usage: 'Use ijfw-workflow for planning. Terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare --reviews.',
-  },
-  'ijfw-ship': {
-    title: 'IJFW ship',
-    usage: 'Run: ijfw preflight. Do not publish or tag until your release gate is explicitly cleared.',
-  },
-  'ijfw-verify': {
-    title: 'IJFW verify',
-    usage: 'Run: ijfw preflight. For focused review, run: ijfw cross audit <target>.',
-  },
-  'memory-audit': {
-    title: 'IJFW memory audit',
-    usage: 'Use the ijfw-memory-audit skill in agents. Terminal safety net: ijfw recover status and ijfw memory checkpoint <label>.',
-  },
-  'memory-consent': {
-    title: 'IJFW memory consent',
-    usage: 'Use IJFW memory tools only for explicit project memory. Terminal checkpoint: ijfw memory checkpoint <label>.',
-  },
-  'memory-why': {
-    title: 'IJFW memory why',
-    usage: 'Use ijfw-recall or ijfw-memory-audit in agents to inspect why memory exists. Terminal recovery state: ijfw recover latest.',
-  },
-  metrics: {
-    title: 'IJFW metrics',
-    usage: 'Open the dashboard with: ijfw dashboard start. Agent-side metrics are available through ijfw_metrics.',
-  },
-  mode: {
-    title: 'IJFW mode',
-    usage: 'Inspect configuration with: ijfw config --audit. Statusline mode helpers: ijfw statusline --status, --compose, or --disable.',
-  },
-};
+// v1.5.1 W3.A.4 — COMMAND_ALIAS_HELP is now derived from the command-registry
+// (entries where tier === 'pointer-stub'). Each entry's deprecatedReason
+// becomes the usage line; title is auto-derived from the canonical name.
+// To change the help text or add a new pointer-stub: edit
+// installer/src/command-registry.js.
+const COMMAND_ALIAS_HELP = Object.freeze(Object.fromEntries(
+  COMMAND_REGISTRY
+    .filter(e => e.tier === 'pointer-stub')
+    .map(e => [e.name, {
+      title: `IJFW ${e.name}`,
+      usage: e.deprecatedReason,
+    }])
+));
 
 function parseCrossAlias(mode, args) {
   let only = null;
   let confirm = false;
   let expand = false;
+  let chunk = false;
   const positional = [];
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--confirm') confirm = true;
     else if (arg === '--expand') expand = true;
+    else if (arg === '--chunk') chunk = true; // v1.5.1 H1.6 — wire chunker
     else if (arg === '--with' && args[i + 1]) only = args[++i];
     else if (arg.startsWith('--with=')) only = arg.slice('--with='.length);
     else if (!arg.startsWith('--')) positional.push(arg);
   }
   const target = mode === 'research' ? positional.join(' ').trim() : positional[0];
-  return { cmd: 'cross', mode, target: target || undefined, only, confirm, expand };
+  return { cmd: 'cross', mode, target: target || undefined, only, confirm, expand, chunk };
 }
 
 function parseCommandAlias(args) {
@@ -299,6 +272,16 @@ function parseCommandAlias(args) {
     return parseCrossAlias('research', args);
   }
   if (Object.prototype.hasOwnProperty.call(COMMAND_ALIAS_HELP, name)) {
+    // v1.5.1 W2.H — `ijfw metrics` is a deprecated pointer-stub, but
+    // `ijfw metrics --benchmark` surfaces the memory benchmark harness (T22).
+    // Bare `ijfw metrics` still falls through to the deprecation redirect.
+    if (name === 'metrics' && args.includes('--benchmark')) {
+      const opts = { cmd: 'metrics-benchmark', json: args.includes('--json'), write: true };
+      for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--no-write') opts.write = false;
+      }
+      return opts;
+    }
     return { cmd: 'command-alias', alias: name };
   }
   return null;
@@ -396,6 +379,23 @@ function parseArgsInner(args) {
     return { cmd: 'design', sub: args[1] || 'status' };
   }
 
+  // v1.5.0 wire-W1.D — `ijfw ui-review --spec <path> --scope <dirs>`
+  if (args[0] === 'ui-review') {
+    const opts = { cmd: 'ui-review', spec: null, scope: null, write: true, gcSketches: false, peerInputs: null };
+    for (let i = 1; i < args.length; i++) {
+      const a = args[i];
+      if ((a === '--spec' || a === '-s') && args[i + 1]) { opts.spec = args[++i]; }
+      else if (a.startsWith('--spec=')) opts.spec = a.slice('--spec='.length);
+      else if ((a === '--scope' || a === '-S') && args[i + 1]) { opts.scope = args[++i]; }
+      else if (a.startsWith('--scope=')) opts.scope = a.slice('--scope='.length);
+      else if (a === '--no-write') opts.write = false;
+      else if (a === '--gc-sketches') opts.gcSketches = true;
+      else if ((a === '--peer-inputs') && args[i + 1]) { opts.peerInputs = args[++i]; }
+      else if (a.startsWith('--peer-inputs=')) opts.peerInputs = a.slice('--peer-inputs='.length);
+    }
+    return opts;
+  }
+
   if (args[0] === 'blackboard') {
     return { cmd: 'blackboard', sub: args[1] || 'status' };
   }
@@ -418,8 +418,25 @@ function parseArgsInner(args) {
     return { cmd: 'codex', sub: args[1] || 'doctor' };
   }
 
-  if (args[0] === 'memory' && args[1] === 'checkpoint') {
-    return { cmd: 'memory-checkpoint', label: args[2] || 'manual' };
+  if (args[0] === 'memory') {
+    // `ijfw memory` / `ijfw memory --help` / `ijfw memory -h` → namespace help
+    if (args.length === 1 || args[1] === '--help' || args[1] === '-h') {
+      return { cmd: 'memory-help' };
+    }
+    if (args[1] === 'checkpoint') {
+      return { cmd: 'memory-checkpoint', label: args[2] || 'manual' };
+    }
+    if (args[1] === 'reindex') {
+      // `ijfw memory reindex`        -> M1 backfill (free, obsidian indexing)
+      // `ijfw memory reindex --m2`   -> also run M2 A-Mem auto-link backfill
+      //                                 (budget-gated; needs IJFW_AUTOLINK_*)
+      let m2 = false;
+      for (let i = 2; i < args.length; i++) {
+        if (args[i] === '--m2' || args[i] === '--autolink') m2 = true;
+      }
+      return { cmd: 'memory-reindex', m2 };
+    }
+    return { cmd: 'memory-unknown', sub: args[1] };
   }
 
   if (args[0] === 'recover') {
@@ -464,14 +481,16 @@ function parseArgsInner(args) {
     let only = null;
     let confirm = false;
     let expand = false;
+    let chunk = false;
 
     for (let i = 3; i < args.length; i++) {
       if (args[i] === '--confirm') { confirm = true; }
       else if (args[i] === '--expand') { expand = true; }
+      else if (args[i] === '--chunk') { chunk = true; } // v1.5.1 H1.6 — wire chunker
       else if (args[i] === '--with' && args[i + 1]) { only = args[++i]; }
     }
 
-    return { cmd: 'cross', mode, target, only, confirm, expand };
+    return { cmd: 'cross', mode, target, only, confirm, expand, chunk };
   }
 
   return { cmd: 'unknown', raw: args[0] };
@@ -481,86 +500,32 @@ function parseArgsInner(args) {
 // Commands
 // ---------------------------------------------------------------------------
 
-function printUsage() {
+function printMemoryHelp() {
   console.log(`
-ijfw -- It Just Fucking Works CLI
-Fire 2-4 AIs at any target. Receipts logged. Cache hits tracked. Memory follows you.
+ijfw memory -- project memory namespace
 
 Usage:
-  ijfw install
-  ijfw uninstall
-  ijfw preflight
-  ijfw dashboard [start|stop|status]
-  ijfw design [start|open|status|stop|push|clear|init|plan|audit|critique|polish|normalize|bolder|quieter|handoff]
-  ijfw blackboard [init|status|claim|release|note|handoff]
-  ijfw team [init|status]
-  ijfw swarm [plan|prepare|tasks|prompt|start|complete|block|ready|status]
-  ijfw swarm worktree [create|list|integrate|cleanup]
-  ijfw codex [doctor|sync-agents]
-  ijfw memory checkpoint <label>
-  ijfw recover [status|latest]
-  ijfw cross <mode> <target> [options]
-  ijfw cross project-audit <rule-file> [--dry-run]
-  ijfw import <tool> [--all] [--dry-run] [--force] [--path <p>]
-  ijfw status
-  ijfw doctor
-  ijfw update
-  ijfw receipt last
-  ijfw --purge-receipts
-  ijfw --help
-
-Commands:
-  install           Install IJFW into your AI coding agents.
-  uninstall         Remove IJFW and revert AI-agent configs. Same as: ijfw off
-  preflight         Run the 11-gate quality pipeline (blocking + advisory).
-  dashboard         Control the dashboard server (start, stop, status).
-  design            Control the live visual design companion.
-  blackboard        Coordinate project-local swarm state and artifact claims.
-  team              Assemble project agents, charter, and workflow manifest.
-  swarm             Plan artifact-aware parallel work from the team manifest.
-  recover           Show the latest checkpoint and next recovery step.
-  demo              30-second live tour of the Trident (fires real auditors).
-  cross             Fire external auditors at a target. Try: ijfw cross audit README.md
-  import            Pull memory in from another tool. Try: ijfw import claude-mem --all
-  status            Show recent cross-audit activity. Try: ijfw status
-  doctor            Probe which CLIs and API keys are reachable. Try: ijfw doctor
-  update            Pull latest IJFW + reinstall merge-safely. Try: ijfw update
-  update --check    Non-invasive check. Exits 0 always; prints "update-available: <ver>" when an update exists (grep-safe).
-  receipt last      Print a redacted, shareable block from the last Trident run.
-  --purge-receipts  Clear the cross-runs receipt log. Try: ijfw --purge-receipts
-
-Modes (for ijfw cross):
-  audit           Adversarial review of a file, module, or path
-  research        Multi-source research on a topic
-  critique        Structured counter-argument generation
-  project-audit   Run the same audit across every registered IJFW project
-                  Usage: ijfw cross project-audit <rule-file> [--dry-run]
-
-Options for ijfw cross:
-  --with <id>   Force a specific auditor (comma-separated for multiple)
-  --confirm     Prompt for confirmation before firing
-  --expand      Include extended swarm when available
-
-Global flags:
-  --json    Emit JSON instead of human output. status and doctor auto-JSON
-            on non-TTY (gh-CLI convention); version stays one-line on pipe
-            and only JSON-ifies with explicit --json. Other commands ignore.
-
-Environment:
-  IJFW_AUDIT_BUDGET_USD   Session spend cap (default $2.00). First call is always
-                          allowed (no cap). Cap enforced from the 2nd call on.
-
-Examples:
-  ijfw demo
-  ijfw cross audit README.md
-  ijfw cross research "vector search approaches"
-  ijfw cross critique HEAD~3..HEAD
-  ijfw cross audit CLAUDE.md --with codex,gemini
-  ijfw status
-  ijfw doctor
+  ijfw memory checkpoint <label>   Snapshot current swarm/memory state under <label>.
+                                   <label> defaults to "manual" if omitted.
+  ijfw memory reindex [--m2]       Backfill M1 obsidian indexing (wikilinks,
+                                   #tags, [k:: v] metadata) over the whole
+                                   memory db. Free + idempotent. Add --m2 to
+                                   also run the A-Mem auto-link backfill --
+                                   budget-gated (set IJFW_AUTOLINK_BUDGET_USD
+                                   and IJFW_AUTOLINK_BACKFILL=1).
+
+Related:
+  ijfw recover [status|latest]     Inspect checkpoints and recovery state.
+  ijfw --help                      Top-level user-facing commands.
+  ijfw commands                    Full command surface (all verbs).
 `.trim());
 }
 
+function printUnknownCommand(raw) {
+  console.error(`Unknown command: ${raw}`);
+  console.error('Run `ijfw --help` for the user-facing command list, or `ijfw commands` for the full surface.');
+}
+
 function cmdCommandAlias(alias) {
   const info = COMMAND_ALIAS_HELP[alias];
   if (!info) {
@@ -573,6 +538,41 @@ function cmdCommandAlias(alias) {
   process.exit(0);
 }
 
+// v1.5.1 W2.H — `ijfw metrics --benchmark`: run the memory benchmark harness
+// (T22) against IJFW's own 3-tier store and report recall@k, MRR/NDCG-style
+// retrieval quality, throughput, and p50/p95/p99 latency. See
+// docs/MEMORY-BENCHMARK.md for the axes and how to interpret the numbers.
+async function cmdMetricsBenchmark(opts = {}) {
+  const results = await runBenchmark({
+    root: process.cwd(),
+    write: opts.write !== false,
+  });
+
+  if (wantsJson(opts)) {
+    emitJson(results);
+    return;
+  }
+
+  const q = results.axes.query_warm_fts5;
+  const ing = results.axes.ingest;
+  const recallPairs = Object.entries(q.recall || {});
+  console.log('IJFW memory benchmark (T22)');
+  console.log('');
+  console.log(`  corpus            ${results.corpus.docs} docs / ${results.corpus.queries} queries / ${results.corpus.total_query_samples} timed samples`);
+  console.log(`  ingest throughput ${ing.throughput_rps} rows/s`);
+  console.log(`  ingest latency    p50 ${ing.latency_ms.p50}ms  p95 ${ing.latency_ms.p95}ms  p99 ${ing.latency_ms.p99}ms`);
+  console.log(`  query latency     p50 ${q.latency_ms.p50}ms  p95 ${q.latency_ms.p95}ms  p99 ${q.latency_ms.p99}ms`);
+  console.log(`  recall            ${recallPairs.map(([k, v]) => `${k}=${v.toFixed(3)}`).join('  ')}`);
+  console.log(`  storage           ${results.axes.storage.bytes_per_memory} bytes/memory (${results.axes.storage.rows_indexed} rows)`);
+  console.log(`  cold tier         ${results.axes.query_cold_vector.available ? 'available' : 'reserved (no embedding model)'}`);
+  if (results.artifact_path) {
+    console.log('');
+    console.log(`  artifact          ${results.artifact_path}`);
+  }
+  console.log('');
+  console.log('Axes explained: docs/MEMORY-BENCHMARK.md');
+}
+
 async function cmdStatus(projectDir, opts = {}) {
   const receipts = readReceipts(projectDir);
   const last = receipts[receipts.length - 1];
@@ -663,8 +663,6 @@ async function cmdDemo() {
 
   let result;
   try {
-    // TODO post-merge: perAuditorTimeoutSec, minResponses, quiet are added by Item 2 agent.
-    // Passed through here; current orchestrator silently ignores unknown params.
     result = await runCrossOp({
       mode: 'audit',
       target,
@@ -877,6 +875,15 @@ function cmdPurgeReceipts(projectDir) {
 // ranges, and non-existent paths pass through unchanged.
 const TARGET_FILE_SIZE_CAP = 64 * 1024; // 64 KB -- leaves prompt headroom
 
+// r17.1 — size thresholds for pre-flight advisory. Inputs under WARN are
+// silent; WARN..CAP get a one-line "this might be slow" advisory; CAP..MAX
+// get a "this WILL be truncated, consider chunking" warning before we fire
+// any auditor (so the user can cancel rather than burn wall time). Anything
+// over MAX would be silently truncated by resolveTarget anyway — the
+// pre-flight check makes that loud.
+const TARGET_FILE_SIZE_WARN = 32 * 1024;
+const TARGET_FILE_SIZE_MAX  = 256 * 1024; // beyond this, advise chunking explicitly
+
 export function resolveTarget(raw, opts = {}) {
   const cap = typeof opts.sizeCap === 'number' ? opts.sizeCap : TARGET_FILE_SIZE_CAP;
   if (typeof raw !== 'string' || !raw) return raw;
@@ -921,7 +928,44 @@ export function resolveTarget(raw, opts = {}) {
   return `File: ${raw}\n\n${contents}`;
 }
 
-async function cmdCross({ mode, target, only, confirm, expand }) {
+// v1.5.1 H1.6 — chunked-dispatch helpers (audit finding token-optimization.md
+// HIGH-H4 + trident.md HIGH-1, 2/2 consensus). The chunker has shipped (with
+// tests) since r17.1 but was never wired into the CLI. `--chunk` now triggers
+// per-chunk dispatch through runCrossOp + a final Jaccard-dedupe merge.
+
+/**
+ * Decide whether a target absolute path is large enough to benefit from
+ * chunking. Exported for unit-tests.
+ */
+export function shouldChunkFile(absPath, opts = {}) {
+  const threshold = typeof opts.threshold === 'number' ? opts.threshold : TARGET_FILE_SIZE_CAP;
+  try {
+    const st = statSync(absPath);
+    if (!st.isFile()) return false;
+    return st.size > threshold;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a file and produce the per-chunk target strings the auditors will see.
+ * Each chunk is annotated with its index so cross-chunk findings can be
+ * reconciled. Exported for unit-tests.
+ */
+export function buildChunkedTargets(absPath, rawTarget, opts = {}) {
+  const content = readFileSync(absPath, 'utf8');
+  const chunks = chunkText(content, opts);
+  return chunks.map((c, i) => ({
+    chunkIndex: i,
+    total: chunks.length,
+    bytesStart: c.start,
+    bytesEnd: c.end,
+    target: `File: ${rawTarget} [chunk ${i + 1}/${chunks.length}, bytes ${c.start}-${c.end}]\n\n${c.text}`,
+  }));
+}
+
+async function cmdCross({ mode, target, only, confirm, expand, chunk }) {
   const VALID_MODES = ['audit', 'research', 'critique'];
   if (!mode || !VALID_MODES.includes(mode)) {
     console.error(`ijfw cross requires a mode: ${VALID_MODES.join(', ')}. Example: ijfw cross audit <file>`);
@@ -935,6 +979,114 @@ async function cmdCross({ mode, target, only, confirm, expand }) {
   // Issue #6 fix: substitute file contents for path string when target is a
   // regular file. Keep the raw target for the user-facing echo line.
   const rawTarget = target;
+
+  // r17.1 — pre-flight size advisory. Run BEFORE resolveTarget truncates,
+  // so the user sees the real number and can decide to abort + chunk the
+  // input themselves rather than getting a silently-truncated audit.
+  // r17-M3: resolve relative paths against cwd FIRST, matching the same
+  // resolution resolveTarget() uses. Without this, `ijfw cross audit foo.md`
+  // (a relative path that exists) would skip the advisory because
+  // existsSync(rawTarget) probes against the wrong cwd-anchor.
+  try {
+    let probePath = null;
+    if (typeof rawTarget === 'string' && rawTarget.length < 4096) {
+      const resolved = isAbsolute(rawTarget) ? rawTarget : resolve(process.cwd(), rawTarget);
+      if (existsSync(resolved)) probePath = resolved;
+    }
+    if (probePath) {
+      const st = statSync(probePath);
+      if (st.isFile()) {
+        if (st.size > TARGET_FILE_SIZE_MAX) {
+          console.log('');
+          console.log(`Heads up -- target is ${(st.size / 1024).toFixed(1)} KB, larger than the ${(TARGET_FILE_SIZE_MAX / 1024).toFixed(0)} KB recommended max.`);
+          console.log(`Auditors will see only the first ${(TARGET_FILE_SIZE_CAP / 1024).toFixed(0)} KB (truncated). For full coverage, chunk the target into smaller files and audit each, OR pass --chunk to auto-split (see \`ijfw cross --help\`).`);
+        } else if (st.size > TARGET_FILE_SIZE_CAP) {
+          console.log('');
+          console.log(`Note: target is ${(st.size / 1024).toFixed(1)} KB; auditors will see the first ${(TARGET_FILE_SIZE_CAP / 1024).toFixed(0)} KB and a truncation marker. Findings beyond that point will be missed.`);
+        } else if (st.size > TARGET_FILE_SIZE_WARN) {
+          console.log('');
+          console.log(`Note: target is ${(st.size / 1024).toFixed(1)} KB; expect a slower wall time (gemini in particular may push the 90s budget).`);
+        }
+      }
+    }
+  } catch { /* statSync failure is non-fatal; size advisory is best-effort */ }
+
+  // v1.5.1 H1.6 — chunked dispatch path. When --chunk is set AND the target
+  // is a file larger than the size cap, split via the cross-audit-chunker
+  // (boundary-aware, 10% overlap, Jaccard-dedupe merge) and dispatch each
+  // chunk through runCrossOp separately. Merge findings at the end. Opt-in
+  // because cost scales linearly with chunk count.
+  if (chunk) {
+    let absPath = null;
+    try {
+      if (typeof rawTarget === 'string' && rawTarget.length < 4096) {
+        const resolved = isAbsolute(rawTarget) ? rawTarget : resolve(process.cwd(), rawTarget);
+        if (existsSync(resolved) && statSync(resolved).isFile()) absPath = resolved;
+      }
+    } catch { /* */ }
+
+    if (!absPath) {
+      console.log('');
+      console.log('--chunk requires a file target. Topics, git ranges, and missing paths cannot be chunked.');
+      // Fall through to normal path -- --chunk silently no-ops for non-files
+    } else if (!shouldChunkFile(absPath)) {
+      console.log('');
+      console.log(`--chunk: target is ${(statSync(absPath).size / 1024).toFixed(1)} KB, under the ${(TARGET_FILE_SIZE_CAP / 1024).toFixed(0)} KB chunk threshold; running single-pass audit instead.`);
+      // Fall through to normal path
+    } else {
+      const chunks = buildChunkedTargets(absPath, rawTarget);
+      console.log('');
+      console.log(`--chunk: splitting ${rawTarget} into ${chunks.length} chunks (≈${(CHUNKER_DEFAULTS.chunkSize / 1024).toFixed(0)} KB each, ${(CHUNKER_DEFAULTS.overlap / 1024).toFixed(0)} KB overlap).`);
+      console.log(`Trident dispatches: ${chunks.length} × per-chunk audit. Cost scales linearly.`);
+
+      const perChunkResults = [];
+      const auditorIds = new Set();
+      const projectDir = process.cwd();
+      let firedAny = false;
+      for (const { chunkIndex, total, target: chunkTarget } of chunks) {
+        console.log('');
+        console.log(`[chunk ${chunkIndex + 1}/${total}] dispatching...`);
+        try {
+          const r = await runCrossOp({
+            mode, target: chunkTarget, projectDir,
+            runStamp: new Date().toISOString(), only, confirm, expand,
+          });
+          const findings = Array.isArray(r.merged) ? r.merged : [];
+          perChunkResults.push({ chunkIndex, findings });
+          for (const p of (r.picks || [])) auditorIds.add(p.id);
+          if ((r.picks || []).length > 0) firedAny = true;
+          console.log(`[chunk ${chunkIndex + 1}/${total}] ${findings.length} finding(s) from ${(r.picks || []).length} auditor(s).`);
+        } catch (err) {
+          console.log(`[chunk ${chunkIndex + 1}/${total}] dispatch error: ${err.message}`);
+          perChunkResults.push({ chunkIndex, findings: [] });
+        }
+      }
+
+      const merged = mergeFindings(perChunkResults);
+      console.log('');
+      console.log(`=== Chunked audit complete: ${merged.length} unique finding(s) across ${chunks.length} chunks ===`);
+      console.log(`Auditors fired (union): ${[...auditorIds].join(', ') || '(none)'}`);
+      if (!firedAny) {
+        console.log('No auditors fired -- run `ijfw doctor` to see the install hints.');
+        process.exit(2); // r17.1 — degraded exit code
+      }
+      for (const f of merged) {
+        const sev = (f.severity || 'note').toUpperCase();
+        const cluster = f.clusterSize > 1 ? ` [×${f.clusterSize}]` : '';
+        const tgt = f.target ? ` ${f.target} —` : '';
+        // v1.5.0 wire-W4: widen field fallback to cover description/issue/
+        // detail/note/summary keys auditors emit. Closes the r19 "(no detail)"
+        // dropout that made adjudication a guessing game.
+        const text = f.finding || f.text || f.message ||
+                     f.description || f.issue ||
+                     f.detail || f.details || f.note || f.summary ||
+                     '(no detail)';
+        console.log(`  ${sev}${cluster}${tgt} ${text}`);
+      }
+      return;
+    }
+  }
+
   target = resolveTarget(target);
 
   // Polish 6: pre-flight reachability check. If no auditor is wired, give a
@@ -1006,6 +1158,18 @@ async function cmdCross({ mode, target, only, confirm, expand }) {
   printFindings(mode, merged);
 
   console.log('\nReceipt logged -- run `ijfw status` to see it.');
+
+  // r17.1 — structured exit code so CI scripts + orchestrator-LLM callers
+  // can detect degraded runs without scraping console output.
+  //   exit 0  — all picks contributed productively
+  //   exit 2  — at least one pick didn't contribute (timeout / failure / aborted)
+  //   exit 3  — zero picks contributed productively (INCONCLUSIVE verdict)
+  // exit 1 is reserved for argv / usage errors (already used above).
+  if (auditorResults && Array.isArray(auditorResults)) {
+    const productive = auditorResults.filter(r => r.counted === true || r.status === null || r.status === 'fallback-used');
+    if (productive.length === 0) process.exit(3);
+    if (productive.length < auditorResults.length) process.exit(2);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1314,16 +1478,100 @@ function cmpSemver(a, b) {
 
 function readState() { return readJsonSafe(join(ijfwHome(), 'state.json')) || {}; }
 function readSettings() { return readJsonSafe(join(ijfwHome(), 'settings.json')) || {}; }
-function writeStateFields(updates) {
-  const path = join(ijfwHome(), 'state.json');
-  const state = Object.assign(readState(), updates);
+
+// v1.5.0 audit M11 (F-REL-1): writeStateFields was best-effort — readState +
+// merge + writeAtomic was a TOCTOU window where a parallel `ijfw update`
+// completion could clobber another writer's `last_applied_version`. If the
+// write failed silently, the re-entrancy guard (last_applied_version >=
+// last_latest_seen) would never fire and every subsequent session would
+// nag-loop until manual `ijfw doctor`.
+//
+// Fix: serialise read-modify-write under a sync directory lock so the merge
+// happens against the latest disk state. We use a tiny inlined sync version
+// of `withFsLock` (mkdir-with-EEXIST is atomic on POSIX + NTFS) rather than
+// importing the async `fs-lock.js` — this whole CLI is sync top-to-bottom and
+// converting just-this-callsite to async would force every caller to await.
+//
+// On lock-acquire failure we still attempt the write (better than refusing to
+// persist) and surface the lock failure as a clearer error.
+const STATE_LOCK_DIR = () => join(ijfwHome(), '.state.lock');
+const STATE_LOCK_ACQUIRE_TIMEOUT_MS = 5000;
+const STATE_LOCK_STALE_MS = 30000;
+const STATE_LOCK_BACKOFF_START_MS = 25;
+const STATE_LOCK_BACKOFF_MAX_MS = 250;
+
+function withStateLockSync(fn) {
+  const lockDir = STATE_LOCK_DIR();
+  // Ensure parent exists; tolerate races.
+  try { mkdirSync(dirname(lockDir), { recursive: true, mode: 0o700 }); } catch { /* */ }
+
+  const deadline = Date.now() + STATE_LOCK_ACQUIRE_TIMEOUT_MS;
+  let staleRecoveryUsed = false;
+  let backoff = STATE_LOCK_BACKOFF_START_MS;
+  let acquired = false;
+
+  while (Date.now() < deadline) {
+    try {
+      mkdirSync(lockDir, { recursive: false });
+      acquired = true;
+      break;
+    } catch (err) {
+      if (err && err.code !== 'EEXIST') {
+        // Real FS error (EACCES, ENOENT on parent we couldn't create) —
+        // surface so the caller can fall back to best-effort write.
+        throw err;
+      }
+      // Stale recovery: if the lock dir is older than STATE_LOCK_STALE_MS,
+      // a previous holder crashed mid-write. Remove + retry once.
+      if (!staleRecoveryUsed) {
+        try {
+          const st = statSync(lockDir);
+          if (Date.now() - st.mtimeMs > STATE_LOCK_STALE_MS) {
+            staleRecoveryUsed = true;
+            rmSync(lockDir, { recursive: true, force: true });
+            continue;
+          }
+        } catch { /* lock vanished mid-stat; retry */ }
+      }
+      // Bounded busy-wait. Sync sleep via Atomics is heavy; use a tight loop
+      // with deadline check (typical contention is microseconds in practice).
+      const waitUntil = Date.now() + Math.min(backoff, STATE_LOCK_BACKOFF_MAX_MS, deadline - Date.now());
+      // eslint-disable-next-line no-empty
+      while (Date.now() < waitUntil) {}
+      backoff = Math.min(backoff * 2, STATE_LOCK_BACKOFF_MAX_MS);
+    }
+  }
+
+  if (!acquired) {
+    // Couldn't acquire — fall back to caller's fn anyway. Better to risk a
+    // racy write than to lose the re-entrancy guard entry.
+    try { return fn(); }
+    finally { /* no lock to release */ }
+  }
+
   try {
-    writeAtomic(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
-  } catch (e) {
-    console.error(`could not persist state.json: ${e.message}`);
+    return fn();
+  } finally {
+    try { rmSync(lockDir, { recursive: true, force: true }); } catch { /* */ }
   }
 }
 
+function writeStateFields(updates) {
+  const path = join(ijfwHome(), 'state.json');
+  withStateLockSync(() => {
+    // Re-read INSIDE the lock so we don't merge against a stale snapshot.
+    const state = Object.assign(readState(), updates);
+    try {
+      writeAtomic(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+    } catch (e) {
+      // M11: persist failure is now visible AND surfaces which field would
+      // not propagate. Re-entrancy guard relies on last_applied_version;
+      // log explicitly so `ijfw doctor` / a user reading logs can spot it.
+      console.error(`could not persist state.json (re-entrancy guard may not fire next session): ${e.message}`);
+    }
+  });
+}
+
 function cmdUpdateCheck() {
   const state = readState();
   const current = state.installed_version || '0.0.0';
@@ -1370,6 +1618,19 @@ function cmdUpdateVerify() {
   } else {
     console.log(`  provenance: NOT VERIFIED (audit signatures exited ${sig.status})`);
   }
+  // Second factor: shasum cross-verify (F-SEC-7). Dry-run: report but don't
+  // exit non-zero -- caller is asking "what would happen if I updated?", and
+  // the interactive flow already fails closed on mismatch.
+  const shasumDry = verifyShasumCrossSource(r.version);
+  if (shasumDry.mode === 'verified') {
+    console.log(`  shasum cross-verify: VERIFIED (${shasumDry.npmShasum.slice(0, 12)}...)`);
+  } else if (shasumDry.mode === 'mismatch') {
+    console.log(`  shasum cross-verify: MISMATCH (npm=${shasumDry.npmShasum} release=${shasumDry.releaseShasum}) -- install would be REFUSED`);
+  } else if (shasumDry.mode === 'advisory') {
+    console.log(`  shasum cross-verify: ADVISORY (${shasumDry.message})`);
+  } else {
+    console.log(`  shasum cross-verify: ERROR (${shasumDry.message})`);
+  }
   console.log('Verification complete.');
   process.exit(0);
 }
@@ -1545,6 +1806,37 @@ function cmdUpdateInteractive(opts = {}) {
       return 1;
     }
   }
+  // Shasum cross-verify (F-SEC-7): independent second factor on top of
+  // npm-side signatures. Fetches the GitLab release asset shasum and
+  // compares it against npm's dist.shasum for the same version. Mismatch
+  // means we refuse to install; advisory (release shasum unavailable)
+  // requires explicit --yes to proceed.
+  const shasum = verifyShasumCrossSource(r.version);
+  if (shasum.mode === 'verified') {
+    console.log(`  Shasum: verified (${shasum.npmShasum.slice(0, 12)}...)`);
+  } else if (shasum.mode === 'mismatch') {
+    console.error('  Shasum: MISMATCH -- refusing install.');
+    console.error(`    npm     : ${shasum.npmShasum}`);
+    console.error(`    release : ${shasum.releaseShasum}`);
+    console.error('  The npm tarball does NOT match the GitLab release asset.');
+    console.error('  This could indicate a compromised registry or release. Aborting.');
+    return 1;
+  } else if (shasum.mode === 'error') {
+    console.error(`  Shasum: error -- ${shasum.message}`);
+    console.error('  Refusing install: cannot establish second-factor integrity.');
+    return 1;
+  } else if (shasum.mode === 'advisory') {
+    console.error(`  Shasum: ADVISORY -- ${shasum.message}`);
+    if (!opts.yes) {
+      console.error('  Continuing requires --yes (acknowledge missing release shasum).');
+      return 1;
+    }
+    console.error('  Proceeding due to --yes; release shasum could not be verified.');
+  } else {
+    // Unknown mode: fail closed.
+    console.error(`  Shasum: unknown mode "${shasum.mode}" -- refusing install.`);
+    return 1;
+  }
   // Method dispatch
   const method = state.install_method || 'manual';
   console.log(`  install_method: ${method}`);
@@ -1637,8 +1929,17 @@ function cmdUpdateInteractive(opts = {}) {
     console.error(`Update did not complete (exit ${installRes.status}). State not written.`);
     return 1;
   }
-  // Persist both fields atomically -- single write avoids concurrent-reader inconsistency
-  writeStateFields({ last_applied_version: r.version, installed_version: r.version });
+  // Persist both fields atomically -- single write avoids concurrent-reader inconsistency.
+  // last_good_shasum records the shasum we just successfully cross-verified +
+  // installed (per docs/SECURITY.md "last_good_shasum is a one-way 'what did
+  // we actually install' record"). Only written when shasum was actually
+  // verified (mode === 'verified'); advisory paths leave the previous value
+  // so we don't poison the record with an unverified hash.
+  const stateUpdate = { last_applied_version: r.version, installed_version: r.version };
+  if (shasum && shasum.mode === 'verified' && shasum.npmShasum) {
+    stateUpdate.last_good_shasum = shasum.npmShasum;
+  }
+  writeStateFields(stateUpdate);
   console.log('');
   console.log(`IJFW updated to v${r.version}. Run \`ijfw status\` to confirm.`);
   return 0;
@@ -2017,10 +2318,25 @@ if (isMainModule) {
   }
 
   if (parsed.cmd === 'help') {
-    printUsage();
+    // v1.5.1 W1.D+E: orchestrator-side help is handled by the installer
+    // (`ijfw --help` for the primary surface, `ijfw commands` for full).
+    // Print a pointer instead of the old stale Usage block.
+    console.log('Run `ijfw --help` for the user-facing command list, or `ijfw commands` for the full surface.');
+    process.exit(0);
+  }
+
+  if (parsed.cmd === 'memory-help') {
+    printMemoryHelp();
     process.exit(0);
   }
 
+  if (parsed.cmd === 'memory-unknown') {
+    console.error(`Unknown memory subcommand: ${parsed.sub}`);
+    console.error('');
+    printMemoryHelp();
+    process.exit(1);
+  }
+
   if (parsed.cmd === 'status') {
     cmdStatus(process.cwd(), parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'demo') {
@@ -2031,6 +2347,8 @@ if (isMainModule) {
     cmdCrossProjectAudit(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'command-alias') {
     cmdCommandAlias(parsed.alias);
+  } else if (parsed.cmd === 'metrics-benchmark') {
+    cmdMetricsBenchmark(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'import') {
     cmdImport(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'doctor') {
@@ -2059,6 +2377,8 @@ if (isMainModule) {
     cmdDashboard(parsed.sub);
   } else if (parsed.cmd === 'design') {
     cmdDesign(parsed.sub);
+  } else if (parsed.cmd === 'ui-review') {
+    cmdUiReview(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'blackboard') {
     cmdBlackboard(parsed.sub);
   } else if (parsed.cmd === 'team') {
@@ -2073,11 +2393,13 @@ if (isMainModule) {
     cmdCodex(parsed.sub);
   } else if (parsed.cmd === 'memory-checkpoint') {
     cmdMemoryCheckpoint(parsed.label);
+  } else if (parsed.cmd === 'memory-reindex') {
+    cmdMemoryReindex(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'recover') {
     cmdRecover(parsed.sub);
   } else {
-    console.error(`Unknown command: ${parsed.raw}`);
-    printUsage();
+    // v1.5.1 W1.D+E: clean unknown-command message; no stale usage dump.
+    printUnknownCommand(parsed.raw);
     process.exit(1);
   }
 }
@@ -2158,6 +2480,69 @@ function openDesignUrl(url) {
   return res.status ?? 0;
 }
 
+// v1.5.0 wire-W1.D — `ijfw ui-review` production CLI. Wires the 7-pillar
+// audit runner into a user-facing command. Args:
+//   --spec <UI-SPEC.md path>           required
+//   --scope <comma-sep dirs>           required (e.g. "src,components")
+//   --no-write                         skip writing UI-REVIEW.md (preview mode)
+//   --gc-sketches                      run sketches-gc as the finalizer
+//   --peer-inputs <json-path>          optional axe / lighthouse / playwright
+//                                      pre-computed outputs (JSON file)
+//   --json                             machine-readable output (skip narrative)
+async function cmdUiReview(parsed) {
+  if (!parsed.spec) {
+    console.error('Usage: ijfw ui-review --spec <UI-SPEC.md> --scope <dirs> [--no-write] [--gc-sketches] [--peer-inputs <path>]');
+    process.exit(1);
+  }
+  if (!parsed.scope) {
+    console.error('ui-review: --scope is required (comma-separated dirs, e.g. "src,components")');
+    process.exit(1);
+  }
+  const specPath = isAbsolute(parsed.spec) ? parsed.spec : resolve(process.cwd(), parsed.spec);
+  if (!existsSync(specPath)) {
+    console.error(`ui-review: UI-SPEC not found at ${specPath}`);
+    process.exit(1);
+  }
+
+  let peerInputs = {};
+  if (parsed.peerInputs) {
+    const ppath = isAbsolute(parsed.peerInputs) ? parsed.peerInputs : resolve(process.cwd(), parsed.peerInputs);
+    try { peerInputs = JSON.parse(readFileSync(ppath, 'utf8')); }
+    catch (err) {
+      console.error(`ui-review: failed to read --peer-inputs JSON: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  const { runUiReview } = await import('./lib/ui-review-runner.js');
+  const result = await runUiReview({
+    uiSpecPath: specPath,
+    sourceScope: parsed.scope,
+    projectRoot: process.cwd(),
+    peerInputs,
+    write: parsed.write !== false,
+    gcSketches: !!parsed.gcSketches,
+  });
+
+  if (parsed.json) {
+    console.log(JSON.stringify({
+      topVerdict: result.topVerdict,
+      pillarVerdicts: result.pillarVerdicts,
+      reviewPath: result.reviewPath,
+      parallel: result.parallel,
+    }, null, 2));
+  } else {
+    console.log(`UI review: top-level ${result.topVerdict}`);
+    for (const [pillar, verdict] of Object.entries(result.pillarVerdicts)) {
+      console.log(`  - ${pillar.padEnd(12)} ${verdict}`);
+    }
+    if (result.reviewPath) console.log(`Review written to: ${result.reviewPath}`);
+    console.log(`Parallel grader run: wall=${result.parallel.wallMs}ms parallelism=${result.parallel.parallelism}`);
+  }
+  // Exit code: PASS=0, FLAG=0 (advisory), BLOCK=2 (ship-blocker)
+  process.exit(result.topVerdict === 'BLOCK' ? 2 : 0);
+}
+
 function cmdDesign(sub) {
   const contentDir = join(homedir(), '.ijfw', 'design-companion', 'content');
   mkdirSync(contentDir, { recursive: true });
@@ -2369,8 +2754,11 @@ function cmdTeam(sub) {
   if (sub === 'init' || sub === 'create') {
     const archetype = optionValue(args, ['--archetype', '--type', '-t']);
     const teamName = optionValue(args, ['--name']);
+    // F-FUN-1: --brief lets the Discovery hand-off carry domain signal
+    // when filesystem detection would otherwise collapse to mixed/unknown.
+    const brief = optionValue(args, ['--brief', '-b']) || '';
     const force = args.includes('--force');
-    const result = createTeamAssembly(process.cwd(), { archetype, teamName, force });
+    const result = createTeamAssembly(process.cwd(), { archetype, teamName, brief, force });
     if (!result.ok) {
       if (result.error === 'exists') {
         console.error('Team assembly already exists. Re-run with --force to replace .ijfw/team/charter.json and workflow.json.');
@@ -2405,7 +2793,101 @@ function cmdTeam(sub) {
     process.exit(0);
   }
 
-  console.log('Usage: ijfw team init [--archetype <type>] [--name <team-name>] [--force] | status');
+  // F-FUN-4 (audit-MED-teams-#7): ijfw team list -- enumerate roles.
+  if (sub === 'list') {
+    const result = listTeamRoles(process.cwd());
+    if (!result.ok) {
+      console.error(`team list failed: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`Team: ${result.team_name || '(unnamed)'}`);
+    if (result.project_archetypes.length) console.log(`Archetypes: ${result.project_archetypes.join(', ')}`);
+    console.log(`Roles (${result.roles.length}):`);
+    for (const role of result.roles) {
+      console.log(`  - ${role.name} [${role.role_type}] model=${role.model} effort=${role.effort}`);
+    }
+    process.exit(0);
+  }
+
+  // F-FUN-4: ijfw team add <role-name> --charter <path>
+  if (sub === 'add') {
+    const name = args[0] && !args[0].startsWith('--') ? args[0] : null;
+    const charterPath = optionValue(args, ['--charter', '-c']);
+    if (!charterPath) {
+      console.error('Usage: ijfw team add <role-name> --charter <path-to-role.json>');
+      process.exit(1);
+    }
+    const result = addTeamRole(process.cwd(), { charterPath });
+    if (!result.ok) {
+      console.error(`team add failed: ${result.error}`);
+      if (result.errors) result.errors.forEach((e) => console.error(`  - ${e}`));
+      process.exit(1);
+    }
+    console.log(`Added role: ${result.role.name}`);
+    if (name && name !== result.role.name) {
+      console.log(`  note: charter declared name "${result.role.name}", ignoring CLI argument "${name}"`);
+    }
+    if (result.codex?.ok) console.log(`Codex agents resynced: ${result.codex.count} (${result.codex.skipped ?? 0} unchanged)`);
+    process.exit(0);
+  }
+
+  // F-FUN-4: ijfw team remove <role-name>
+  if (sub === 'remove' || sub === 'rm') {
+    const name = args[0] && !args[0].startsWith('--') ? args[0] : null;
+    if (!name) {
+      console.error('Usage: ijfw team remove <role-name>');
+      process.exit(1);
+    }
+    const result = removeTeamRole(process.cwd(), { name });
+    if (!result.ok) {
+      console.error(`team remove failed: ${result.error}`);
+      if (result.errors) result.errors.forEach((e) => console.error(`  - ${e}`));
+      process.exit(1);
+    }
+    console.log(`Removed role: ${result.removed}`);
+    if (result.codex?.ok) console.log(`Codex agents resynced: ${result.codex.count} (${result.codex.skipped ?? 0} unchanged)`);
+    process.exit(0);
+  }
+
+  // F-FUN-4: ijfw team swap <old-role-name> --charter <path>
+  if (sub === 'swap') {
+    const oldName = args[0] && !args[0].startsWith('--') ? args[0] : null;
+    const charterPath = optionValue(args, ['--charter', '-c']);
+    if (!oldName || !charterPath) {
+      console.error('Usage: ijfw team swap <old-role-name> --charter <path-to-role.json>');
+      process.exit(1);
+    }
+    const result = swapTeamRole(process.cwd(), { oldName, charterPath });
+    if (!result.ok) {
+      console.error(`team swap failed: ${result.error}`);
+      if (result.errors) result.errors.forEach((e) => console.error(`  - ${e}`));
+      process.exit(1);
+    }
+    console.log(`Swapped ${result.swapped.old} -> ${result.swapped.new}`);
+    if (result.codex?.ok) console.log(`Codex agents resynced: ${result.codex.count} (${result.codex.skipped ?? 0} unchanged)`);
+    process.exit(0);
+  }
+
+  // F-FUN-5 (audit-MED-teams-#13): ijfw team check -- standalone validator.
+  if (sub === 'check' || sub === 'validate') {
+    const report = checkTeamAssembly(process.cwd());
+    if (report.ok) {
+      console.log(`Team assembly OK: ${report.role_count} role(s), ${report.artifact_count} artifact(s)`);
+      process.exit(0);
+    }
+    console.error('Team assembly has issues:');
+    if (!report.has_charter || !report.charter.ok) {
+      console.error('  charter.json:');
+      for (const err of report.charter.errors) console.error(`    - ${err}`);
+    }
+    if (!report.has_workflow || !report.workflow.ok) {
+      console.error('  workflow.json:');
+      for (const err of report.workflow.errors) console.error(`    - ${err}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('Usage: ijfw team init [--archetype <type>] [--name <team-name>] [--force] | status | list | add <role> --charter <path> | remove <role> | swap <old> --charter <path> | check');
   process.exit(1);
 }
 
@@ -2483,11 +2965,23 @@ function codexDoctor(projectRoot) {
     fix: 'restore codex/.codex/hooks.json and hook scripts',
   });
 
+  // C11 — the message MUST track the same condition `ok` does. Previously the
+  // message said "ijfw-memory configured" whenever config.toml merely existed,
+  // so a config.toml present-but-missing-the-ijfw-memory-block printed the
+  // [ !! ] failure glyph (ok=false) next to success text. Branch all three
+  // states: file absent, file present-but-unconfigured, file configured.
+  const _codexConfigExists = existsSync(configPath);
+  const _codexMemoryConfigured =
+    _codexConfigExists && readFileSync(configPath, 'utf8').includes('ijfw-memory');
   checks.push({
     name: 'MCP config',
-    ok: existsSync(configPath) && readFileSync(configPath, 'utf8').includes('ijfw-memory'),
+    ok: _codexMemoryConfigured,
     required: true,
-    message: existsSync(configPath) ? 'ijfw-memory configured' : 'missing config.toml',
+    message: _codexMemoryConfigured
+      ? 'ijfw-memory configured'
+      : _codexConfigExists
+        ? 'config.toml present but ijfw-memory not configured'
+        : 'missing config.toml',
     fix: 'run ijfw install or restore codex/.codex/config.toml',
   });
 
@@ -2730,7 +3224,45 @@ function cmdSwarm(sub) {
     process.exit(0);
   }
 
-  console.log('Usage: ijfw swarm plan | prepare [--append] [--reviews] | tasks | prompt <task-id> [--codex] | start <task-id> [--owner <agent>] | complete <task-id> [--message <text>] | block <task-id> --message <why> | ready <task-id> | status');
+  // F-REL-1 (H5.3): orphan eviction. Walks active claims and releases any
+  // whose freshness anchor (claimed_at or heartbeat_at) is older than the
+  // TTL. Default TTL is 30 minutes; override with --ttl-min N.
+  if (sub === 'evict-orphans' || sub === 'evict') {
+    const minRaw = optionValue(args, ['--ttl-min', '--ttl', '-t']);
+    const min = Number.parseFloat(minRaw);
+    const ttlMs = Number.isFinite(min) && min > 0 ? Math.floor(min * 60 * 1000) : DEFAULT_CLAIM_TTL_MS;
+    const result = evictOrphanedClaims(process.cwd(), { ttlMs });
+    if (!result.ok) {
+      console.log(`Swarm evict halted: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`Evicted ${result.count} orphan claim(s) (TTL ${Math.round(ttlMs / 60000)}min)`);
+    for (const item of result.evicted) {
+      console.log(`  ${item.id} (${item.agent} -> ${item.artifact_id}, age ${Math.round(item.age_ms / 1000)}s)`);
+    }
+    process.exit(0);
+  }
+
+  // F-REL-1 (H5.3): manual heartbeat ping. Subagents normally invoke this
+  // via the programmatic surface (updateClaimHeartbeat); the CLI form is
+  // for forensic dogfooding from tests + the dashboard preview.
+  if (sub === 'heartbeat') {
+    const taskOrClaim = args[0];
+    const owner = optionValue(args.slice(1), ['--owner', '-o']);
+    const claimId = optionValue(args.slice(1), ['--claim', '--id']);
+    const input = claimId
+      ? { claim_id: claimId }
+      : { artifact_id: taskOrClaim, agent: owner };
+    const result = updateClaimHeartbeat(process.cwd(), input);
+    if (!result.ok) {
+      console.log(`Heartbeat halted: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`Heartbeat ${result.claim.id} at ${result.claim.heartbeat_at}`);
+    process.exit(0);
+  }
+
+  console.log('Usage: ijfw swarm plan | prepare [--append] [--reviews] | tasks | prompt <task-id> [--codex] | start <task-id> [--owner <agent>] | complete <task-id> [--message <text>] | block <task-id> --message <why> | ready <task-id> | status | evict-orphans [--ttl-min N] | heartbeat <artifact-id> --owner <agent>');
   process.exit(1);
 }
 
@@ -2819,6 +3351,69 @@ function cmdMemoryCheckpoint(label) {
   process.exit(0);
 }
 
+// v1.5.1 R5-1.2 -- `ijfw memory reindex [--m2]`. Closes Trident r5 finding
+// 1.2: memory written during v1.5.0 (before Round-4 Fix-1 wired M1/M2 into
+// the production write path) has empty memory_links / memory_tags /
+// memory_meta. Migration 009 already backfills M1 once on upgrade; this verb
+// is the manual re-run path AND the only way to opt into the M2 (A-Mem
+// auto-link) backfill, which is budget-gated because it makes one LLM call
+// per row.
+async function cmdMemoryReindex(parsed) {
+  const projectRoot = process.cwd();
+  // Lazy import: better-sqlite3 is heavy; only pay for it on this verb.
+  const { openDb, closeDb, dbPathFor } = await import('./memory/fts5.js');
+  const { backfillObsidianIndex } = await import('./memory/obsidian-parser.js');
+  const { backfillAutoLink } = await import('./memory/auto-linker.js');
+
+  let db;
+  try {
+    db = await openDb(projectRoot);
+  } catch (e) {
+    console.error(`Memory db unavailable: ${e.message}`);
+    process.exit(1);
+  }
+
+  try {
+    console.log(`Reindexing memory at ${dbPathFor(projectRoot)}`);
+    // M1 -- always. Free + idempotent obsidian indexing.
+    const m1 = backfillObsidianIndex(db);
+    console.log(
+      `M1 obsidian-index backfill: ${m1.rows} entries re-indexed ` +
+      `(${m1.links} links, ${m1.tags} tags, ${m1.meta} meta` +
+      `${m1.errors ? `, ${m1.errors} errors` : ''}).`,
+    );
+
+    // M2 -- opt-in via --m2. Budget-gated; backfillAutoLink internally
+    // forces past the IJFW_AUTOLINK_BACKFILL opt-in (the --m2 flag IS the
+    // explicit opt-in) but still honours IJFW_AUTOLINK_OFF, the budget cap,
+    // and the API-key requirement.
+    if (parsed.m2) {
+      const m2 = await backfillAutoLink(db, { force: true });
+      if (m2.skipped) {
+        console.log(
+          `M2 auto-link backfill skipped (${m2.reason}). ` +
+          `M2 backfill needs a positive IJFW_AUTOLINK_BUDGET_USD cap and an ` +
+          `API key (IJFW_AUTOLINK_API_KEY or ANTHROPIC_API_KEY).`,
+        );
+      } else {
+        console.log(
+          `M2 auto-link backfill: ${m2.linked}/${m2.rows} entries linked ` +
+          `(${m2.links_added} links, ${m2.neighbor_tags_added} neighbor tags)` +
+          `${m2.stopped_early ? ' -- stopped early (budget / kill switch)' : ''}.`,
+        );
+      }
+    } else {
+      console.log(
+        'M2 auto-link backfill not run. Re-run with --m2 (budget-gated) to ' +
+        'auto-link old entries via the A-Mem LLM pass.',
+      );
+    }
+  } finally {
+    closeDb(db);
+  }
+  process.exit(0);
+}
+
 function cmdRecover(sub) {
   if (sub === 'latest') {
     const latest = latestCheckpoint(process.cwd());