@ijfw/memory-server 1.5.0 → 1.5.1

package/src/cross-orchestrator-cli.js

@@ -62,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,
@@ -69,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)
@@ -219,68 +227,19 @@ 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;
@@ -313,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;
@@ -449,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') {
@@ -514,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) {
@@ -606,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];
@@ -696,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,
@@ -2353,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') {
@@ -2367,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') {
@@ -2411,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);
   }
 }
@@ -2981,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',
   });
 
@@ -3355,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());

package/src/cross-orchestrator.js

@@ -1184,9 +1184,22 @@ function buildCycleSummary(iteration, prior) {
 //                     this convergence cycle. Aborts a lens once its
 //                     cumulative cost in this run exceeds the cap. Defaults
 //                     to env IJFW_AUDIT_BUDGET_USD_PER_LENS.
+//   autoFix        v1.5.1 C2 (T27) — opt-in. When truthy, after a non-PASS
+//                  convergence the consensus code-fixer (recovery/code-fixer.js)
+//                  fires on HIGH findings that 2+ lenses agreed on. `true`
+//                  uses defaults; an object is forwarded to runConsensusFix
+//                  (minLenses, dryRun, verifyCmd, maxAutoFixFiles, ...).
+//                  Mutates the working tree + writes per-finding atomic
+//                  commits — off by default.
+//                  SAFETY BOUNDARY (R5-1.10): the fixer can only modify files
+//                  inside `projectRoot` (path containment — out-of-root
+//                  findings are refused) and `maxAutoFixFiles` (default 10,
+//                  ceiling 50) caps the distinct files one run may touch;
+//                  beyond the cap it stops + reports rather than mass-rewrite.
+//                  `dryRun: true` reports what it WOULD fix without writing.
 // Returns:
 //   { verdict, iterations, findings, divergence?, stalled?, perIteration,
-//     timedOutTotal?, lensesOverBudget?, lensCosts }
+//     timedOutTotal?, lensesOverBudget?, lensCosts, autoFix? }
 export async function runPhaseEConverge({
   commitRange,
   lenses = DEFAULT_LENSES,
@@ -1198,6 +1211,11 @@ export async function runPhaseEConverge({
   totalTimeoutMs,     // v1.5.0 audit-MED-trident-M6 — cumulative timeout
   perLensBudgetUsd,   // v1.5.0 audit-MED-trident-M5 — per-lens USD cap
   keepaliveOnTick,    // v1.5.0 wire-W1.B — caller-supplied keepalive heartbeat
+  autoFix = false,    // v1.5.1 C2 (T27) — when truthy, fire the consensus
+                      // code-fixer on 2+-lens-agreed HIGH findings after a
+                      // non-PASS convergence. Accepts `true` (defaults) or an
+                      // options object { minLenses, dryRun, verifyCmd, ... }
+                      // forwarded to recovery/code-fixer.js#runConsensusFix.
   env = process.env,
 } = {}) {
   if (typeof dispatch !== 'function') {
@@ -1488,6 +1506,37 @@ export async function runPhaseEConverge({
       // break the orchestrator return value.
     }
 
+    // v1.5.1 C2 (T27) — consensus code-fixer wire-up. This is the call site
+    // T27 was designed for: "when 2+ lenses agree on the same HIGH, the fixer
+    // fires automatically." The convergence loop is the canonical Trident
+    // path; once it settles on a non-PASS verdict, extract the consensus HIGH
+    // findings from `perIteration` and run recovery/code-fixer.js's atomic
+    // per-finding fix loop over them. Opt-in (`autoFix`) because it mutates
+    // the working tree + writes commits — never the default for a read-only
+    // audit. PASS verdicts are skipped (nothing to fix). Failure here is
+    // surfaced on `enriched.autoFix` but NEVER changes the convergence
+    // verdict — the fixer is a downstream remediation, not a gate.
+    if (autoFix && enriched.verdict !== VERDICT_PASS) {
+      try {
+        const { runConsensusFix } = await import('./recovery/code-fixer.js');
+        const fixOpts = (autoFix && typeof autoFix === 'object') ? autoFix : {};
+        const fixResult = await runConsensusFix({
+          perIteration,
+          projectRoot: _resolvedProjectDir,
+          dispatch,
+          commitRange,
+          lenses,
+          ...fixOpts,
+        });
+        enriched.autoFix = fixResult;
+      } catch (err) {
+        enriched.autoFix = {
+          triggered: false,
+          reason: `code-fixer error: ${err && err.message ? err.message : String(err)}`,
+        };
+      }
+    }
+
     return enriched;
   }
 

package/src/dispatch/extension.js

@@ -18,7 +18,7 @@
  *                             session-start hook so org/user-scoped extensions
  *                             become available in every project session.
  *
- * TODO(v1.5.0-major S01 — IJFW_PARENT_PROJECT_ROOT env passthrough):
+ * DEFERRED (harness-dependency — IJFW_PARENT_PROJECT_ROOT env passthrough):
  *   The Agent({ isolation: 'worktree' }) spawn path lives in the Claude Code
  *   harness (Task tool / SDK), NOT in this MCP server's dispatch flow. When the
  *   harness eventually exposes a hook for env passthrough on worktree dispatch,

package/src/hardware-signer.js

@@ -14,8 +14,10 @@
  *
  * Backend resolution is FAIL-CLOSED (SEC-L-02): unknown backend names throw
  * rather than silently fall through to software. This means a manifest with
- * `publisher_key_backend: 'libfido2'` (not yet implemented in v1.4.3) is a
- * hard error at sign-time, not a quiet downgrade to a weaker backend.
+ * `publisher_key_backend: 'libfido2'` (a direct-FIDO2 backend deferred to a
+ * future release — the ssh-agent backend already covers FIDO2 tokens via the
+ * agent socket) is a hard error at sign-time, not a quiet downgrade to a
+ * weaker backend.
  *
  * Identity selection (SEC-H-03): when the ssh-agent backend signs, the
  * agent is asked to enumerate identities. The expected public-key blob is

package/src/lib/ui-review-runner.js

@@ -1,8 +1,10 @@
-// ui-review-runner.js -- v1.5.0 wire-W1.D + W1.E.
+// ui-review-runner.js -- v1.5.0 wire-W1.D + W1.E (v1.5.1 W2.A: intake wired).
 //
-// Production wire-up for the 7 design libs (uispec-intake, uispec-drift,
+// Production wire-up for the 6 design libs (uispec-intake, uispec-drift,
 // a11y-contract, lighthouse-pillar, playwright-baseline, sketches-gc) plus
 // the 7-pillar visual audit declared in `claude/agents/ijfw-ui-auditor.md`.
+// All 6 are imported below; the import list IS the canonical wiring count —
+// docstring and imports must move together (v1.5.1 W2.A audit finding).
 //
 // Before W1.D these libraries shipped with isolated tests but ZERO callers.
 // The auditor agent's "wave dispatch one subagent per pillar" was declared
@@ -38,6 +40,7 @@ import {
 import { evaluateLighthouse, LIGHTHOUSE_THRESHOLDS } from './lighthouse-pillar.js';
 import { compareToBaseline } from './playwright-baseline.js';
 import { runSketchesGc } from './sketches-gc.js';
+import { fromImage, fromFigma } from './uispec-intake.js';
 
 // Pillar order is canonical -- the auditor agent spec enumerates them in
 // this exact sequence. The runner emits per-pillar sections in the same
@@ -374,13 +377,16 @@ const GRADERS = Object.freeze({
  * @param {object} [args.peerInputs]      { axe, lighthouse, playwright } -- optional pre-computed peer-tool outputs
  * @param {boolean} [args.write]          when true, write UI-REVIEW.md (default true)
  * @param {boolean} [args.gcSketches]     when true, run sketches-gc as the finalizer (default false)
+ * @param {string}  [args.fromImage]      when set, run uispec-intake.fromImage and attach the stub to the result + UI-REVIEW.md "Intake" section.
+ * @param {string}  [args.fromFigma]      when set, run uispec-intake.fromFigma (same surfacing as fromImage).
  * @returns {Promise<{
  *   topVerdict: 'PASS'|'FLAG'|'BLOCK',
  *   pillarVerdicts: Record<string, string>,
  *   verdicts: Array<{pillar, verdict, findings, startedAt, finishedAt}>,
  *   reviewPath: string|null,
  *   reviewMarkdown: string,
- *   parallel: { minStart: number, maxStart: number, minFinish: number, maxFinish: number, parallelism: number }
+ *   parallel: { minStart: number, maxStart: number, minFinish: number, maxFinish: number, parallelism: number },
+ *   intake: { kind: 'image'|'figma', ok: boolean, stub: object|null, error: string|null }|null
  * }>}
  */
 export async function runUiReview({
@@ -390,6 +396,8 @@ export async function runUiReview({
   peerInputs = {},
   write = true,
   gcSketches = false,
+  fromImage: fromImagePath = null,
+  fromFigma: fromFigmaUrl = null,
 } = {}) {
   if (typeof uiSpecPath !== 'string' || uiSpecPath.length === 0) {
     throw new TypeError('runUiReview: uiSpecPath is required');
@@ -410,6 +418,20 @@ export async function runUiReview({
   const spec = parseUISpec(rawSpec);
   spec.__rawText = rawSpec;
 
+  // v1.5.1 W2.A: optional uispec-intake pre-fill. When the caller supplies
+  // --from-image or --from-figma we run the intake helper and surface the
+  // resulting stub on the review (rendered into UI-REVIEW.md and returned
+  // structurally). This does NOT mutate the parsed spec used for grading —
+  // intake is purely a pre-fill hint for the user's next UI-SPEC edit.
+  let intake = null;
+  if (fromImagePath) {
+    const res = fromImage(fromImagePath, { projectRoot });
+    intake = { kind: 'image', ok: res.ok, stub: res.stub, error: res.error };
+  } else if (fromFigmaUrl) {
+    const res = await fromFigma(fromFigmaUrl);
+    intake = { kind: 'figma', ok: res.ok, stub: res.stub, error: res.error };
+  }
+
   const files = walkSourceFiles(scopes, projectRoot);
 
   // W1.E: 7 graders in parallel via Promise.all. Concurrency witness is a
@@ -475,6 +497,7 @@ export async function runUiReview({
     sourceScope: scopes,
     verdicts,
     topVerdict,
+    intake,
   });
 
   let reviewPath = null;
@@ -488,7 +511,7 @@ export async function runUiReview({
     try { runSketchesGc({ root: join(projectRoot, '.planning', 'sketches') }); } catch {}
   }
 
-  return { topVerdict, pillarVerdicts, verdicts, reviewPath, reviewMarkdown, parallel };
+  return { topVerdict, pillarVerdicts, verdicts, reviewPath, reviewMarkdown, parallel, intake };
 }
 
 function computeTopVerdict(verdicts) {
@@ -503,7 +526,7 @@ function computeTopVerdict(verdicts) {
   return top;
 }
 
-function renderReview({ uiSpecPath, sourceScope, verdicts, topVerdict }) {
+function renderReview({ uiSpecPath, sourceScope, verdicts, topVerdict, intake = null }) {
   const date = new Date().toISOString().slice(0, 10);
   const scopeStr = Array.isArray(sourceScope) ? sourceScope.join(',') : String(sourceScope);
   const lines = [
@@ -512,9 +535,27 @@ function renderReview({ uiSpecPath, sourceScope, verdicts, topVerdict }) {
     `**Spec:** ${uiSpecPath}  **Source scope:** ${scopeStr}`,
     `**Top-level verdict:** ${topVerdict}`,
     '',
-    '## Per-pillar verdicts',
-    '',
   ];
+  if (intake) {
+    lines.push('## Intake (uispec-intake)');
+    lines.push('');
+    lines.push(`- **Source kind:** ${intake.kind}`);
+    lines.push(`- **Status:** ${intake.ok ? 'ok' : 'error'}`);
+    if (intake.error) lines.push(`- **Error:** ${intake.error}`);
+    if (intake.stub && intake.stub.advisory) lines.push(`- **Advisory:** ${intake.stub.advisory}`);
+    if (intake.stub && intake.stub.source) {
+      const src = intake.stub.source;
+      if (src.path) lines.push(`- **Path:** ${src.path}`);
+      if (src.url) lines.push(`- **URL:** ${src.url}`);
+      if (src.bytes != null) lines.push(`- **Bytes:** ${src.bytes}`);
+      if (src.dimensions) lines.push(`- **Dimensions:** ${src.dimensions.width}x${src.dimensions.height}`);
+      if (src.fileKey) lines.push(`- **Figma file key:** ${src.fileKey}`);
+      if (src.name) lines.push(`- **Figma file name:** ${src.name}`);
+    }
+    lines.push('');
+  }
+  lines.push('## Per-pillar verdicts');
+  lines.push('');
   for (const v of verdicts) {
     const title = PILLAR_TITLES[v.pillar] || v.pillar;
     lines.push(`### ${title} — ${v.verdict}`);