fullstack-critic 1.0.0 → 1.0.2

package/README.md

@@ -14,20 +14,17 @@ Claude Code, Gemini CLI, GitHub Copilot, Cursor, Qoder, Antigravity, or any assi
 
 ## Install & run (no AI required)
 
-> **Status: not yet on the public npm registry.** `npx fullstack-critic` and
-> `npm i -g fullstack-critic` will `404` until this repo is published (`npm publish`).
-> Until then, install **from this folder** — the commands below are tested and work.
+Published on npm as **`fullstack-critic`** (v1.0.0). Install globally, or run with
+zero install via `npx` (verified working):
 
 ```bash
-# From inside this folder — install the CLI globally so `critic` works in any project:
-npm install -g .            # or:  npm link
-# or install by path from anywhere:
-npm install -g C:\path\to\fullstack-critic
-
-# No install at all — run straight from the folder:
-node bin\fullstack-critic.js review .          # Windows
-node bin/fullstack-critic.js review .          # macOS / Linux
-npx --yes /path/to/fullstack-critic review .   # npx against a local folder/git
+npm install -g fullstack-critic     # or: pnpm add -g / yarn global add / bun add -g
+npx fullstack-critic review .       # zero-install, one-shot
+
+# Working from a clone instead (offline / developing the critic itself):
+npm install -g .                                        # from inside the cloned folder
+node bin/fullstack-critic.js review .                   # no install at all
+npx --yes /path/to/fullstack-critic review .            # npx against a local folder/git
 ```
 
 ```bash

package/bin/fullstack-critic.js

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
 'use strict';
-const code = require('../src/cli').run(process.argv.slice(2));
-process.exitCode = Number.isFinite(code) ? code : 0;
+const out = require('../src/cli').run(process.argv.slice(2));
+if (out && typeof out.then === 'function') {
+  // Async commands (e.g. `watch --dash`) resolve after the process is already
+  // kept alive by the watcher; a pending promise simply never resolves.
+  out
+    .then((code) => { process.exitCode = Number.isFinite(code) ? code : 0; })
+    .catch((err) => { process.stderr.write(`${(err && err.stack) || err}\n`); process.exitCode = 1; });
+} else {
+  process.exitCode = Number.isFinite(out) ? out : 0;
+}

package/docs/GETTING_STARTED.md

@@ -17,31 +17,23 @@ It ships two ways to use it:
 
 ## Install
 
-The CLI is a zero-dependency Node package (Node ≥ 18).
+The CLI is a zero-dependency Node package (Node ≥ 18), published on npm as
+**`fullstack-critic`** (v1.0.0).
 
-> **Not published to the public npm registry yet.** So `npx fullstack-critic` and
-> `npm i -g fullstack-critic` return **404** until this repo is published with `npm publish`.
-> Use one of the tested local methods below instead.
+```bash
+# Recommended — from the public registry:
+npm install -g fullstack-critic     # or: pnpm add -g / yarn global add / bun add -g
+npx fullstack-critic review .       # zero-install, one-shot
+```
 
 ```bash
-# A) Global install from this folder — makes `critic` available in every project:
+# Or work from a clone (offline / developing the critic itself):
 cd fullstack-critic
-npm install -g .          # equivalent: npm link
-
-# B) Install by absolute path from anywhere:
-npm install -g C:\path\to\fullstack-critic
-
-# C) No install — run straight from the folder:
-node bin/fullstack-critic.js review .
-
-# D) pnpm / yarn equivalents:
-pnpm add -g ./fullstack-critic
-yarn global add file:./fullstack-critic
+npm install -g .                    # equivalent: npm link
+node bin/fullstack-critic.js review .   # no install at all
+pnpm add -g ./fullstack-critic     # pnpm / yarn equivalents
 ```
 
-> To make `npx fullstack-critic` / `npm i -g fullstack-critic` work for everyone,
-> a maintainer must run `npm publish` from this folder first (see “Publishing”).
-
 Once installed it provides the `critic` (and `fullstack-critic`) command.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstack-critic",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A free, universal principal-engineer critic. Attach it to any project or run it as a background watcher over any in-progress workflow. Reviews 100% of resources — code, packages, and dependencies — across 12 dimensions and emits an evidence-based report with a fix / optimize / delete / add action plan.",
   "keywords": [
     "code-review",

package/src/analyzer.js

@@ -42,6 +42,7 @@ function scanFile(file) {
   // Whole-file suppression: a `critic-ignore-file` marker in the header (for rule-definition files).
   if (/critic-ignore-file/.test(lines.slice(0, 2).join('\n'))) return { findings, lines: lines.length, scannable: true };
   const perRule = {};
+  const ctx = { rel: file.rel };
 
   for (const rule of LINE_RULES) {
     if (!ruleApplies(rule, file.ext)) continue;
@@ -50,7 +51,7 @@ function scanFile(file) {
       const line = lines[i];
       if (!rule.test.test(line)) continue;
       if (/critic-ignore/.test(line)) continue; // inline suppression: `// critic-ignore` (like eslint-disable-line)
-      if (rule.skipIf && rule.skipIf(line)) continue;
+      if (rule.skipIf && rule.skipIf(line, ctx)) continue;
       perRule[rule.id]++;
       if (perRule[rule.id] > CAP_PER_RULE) continue;
       findings.push({
@@ -92,6 +93,22 @@ function scanFile(file) {
       fix: 'Split along responsibility boundaries.', verify: 'each module has one reason to change', confirmed: true,
     });
   }
+  // React: list rendering without a key prop (reconciliation + focus bugs).
+  if (['.jsx', '.tsx', '.js'].includes(file.ext)) {
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/\.map\s*\(\s*\(?([A-Za-z$_][\w$]*)\)?\s*=>\s*\(?\s*<[A-Za-z]/);
+      if (m && !/\bkey\s*=|\{\.\.\.[a-z]|critic-ignore/.test(lines.slice(i, i + 4).join(' '))) {
+        findings.push({
+          ruleId: 'missing-list-key', severity: 'LOW', category: 'fix', dimension: 'Frontend',
+          title: 'List rendered without a key prop', file: file.rel, line: i + 1,
+          problem: `.map() returns JSX without an explicit key (var ${m[1]}).`,
+          evidence: snippet(lines[i]), impact: 'Wrong item reconciliation, lost focus/state on reorder.',
+          fix: 'Add key={item.id} (stable identity, not the array index).',
+          verify: 'React dev console shows no key warnings for this list.', confirmed: 'suspected',
+        });
+      }
+    }
+  }
   return { findings, lines: lines.length, scannable: true };
 }
 
@@ -157,6 +174,54 @@ function structuralFindings(root, files, ctx) {
       fix: 'Add purpose, stack, setup, run, and test instructions.', verify: 'a new contributor can run the app from README alone.', confirmed: true,
     });
   }
+
+  // Packaging hygiene (npm manifests).
+  const pkgPath = path.join(root, 'package.json');
+  if (exists(pkgPath)) {
+    let pkg = null;
+    try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { /* reported by deps parse */ }
+    if (pkg) {
+      if (!Array.isArray(pkg.files) && pkg.private !== true) {
+        F.push({
+          ruleId: 'pkg-no-files-field', severity: 'LOW', category: 'optimize', dimension: 'Infrastructure',
+          title: 'Publishable package has no "files" allowlist', file: 'package.json', line: 1,
+          problem: 'Without "files", npm packs everything not gitignored — tests, docs, env samples.',
+          evidence: `"files" missing; name=${pkg.name || '(unnamed)'}`, impact: 'Bloated tarballs, slower installs, accidental source leakage.',
+          fix: 'Add a "files" array listing dist/src/bin and other publishable paths.', verify: 'npm pack --dry-run lists only intended files.', confirmed: true,
+        });
+      }
+      if (!pkg.engines) {
+        F.push({
+          ruleId: 'pkg-no-engines', severity: 'INFO', category: 'add', dimension: 'Infrastructure',
+          title: 'No "engines" field in package.json', file: 'package.json', line: 1,
+          problem: 'The supported Node range is undocumented for consumers and CI.',
+          evidence: '"engines" missing', impact: 'Runs on unsupported runtimes; env drift.',
+          fix: 'Declare "engines": { "node": ">=18" } (or the real supported range).', verify: 'npm install warns on older Node.', confirmed: true,
+        });
+      }
+    }
+  }
+
+  // SPA / server routing: an Express-style server delivering an SPA without a
+  // history fallback 404s every deep link on hard refresh.
+  const serverRouters = files.filter((f) => /\.(js|ts|mjs|cjs)$/.test(f.ext) && /app\.(get|use)\s*\(|router\.(get|use)\s*\(/.test(readText(f.abs) || ''));
+  const hasApiRoutes = serverRouters.some((f) => /\b(api|\/api)\b|\.use\s*\(/.test(readText(f.abs) || ''));
+  const hasSpa = rels.has('index.html') || files.some((f) => /\.(jsx|tsx|vue|svelte)$/.test(f.ext)) || files.some((f) => /(^|\/)(src|app|pages)\/(index|App)\.(jsx?|tsx?|vue|svelte)$/i.test(f.rel));
+  const hasFallback = serverRouters.some((f) => {
+    const t = readText(f.abs) || '';
+    return /history\(\)|http\.createServerHandler|connect\(\)\.middleware|\*\s*['")]\s|notFound|sendFile\s*\(\s*(path|__dirname|require\.resolve)/i.test(t) && /app\.(get|use)\s*\(\s*['"]?\*|all\s*\(\s*['"]\*|history|fallback/i.test(t);
+  });
+  if (hasApiRoutes && hasSpa && !hasFallback && !isGo && !isRust) {
+    F.push({
+      ruleId: 'spa-no-history-fallback', severity: 'MEDIUM', category: 'fix', dimension: 'Architecture',
+      title: 'SPA served by an API server with no history fallback route', file: '.', line: 1,
+      problem: 'Client-side routes (/settings, /items/5) have no server handler — direct visits and refreshes 404.',
+      evidence: 'express-style routers with api routes + SPA entry files, no catch-all → index.html',
+      impact: 'Broken deep links, failed bookmarks, worse SEO and support load.',
+      fix: 'Mount a last-resort catch-all that serves index.html for non-GET/api paths (e.g. express-history-api-fallback or app.get("*")).',
+      verify: 'refreshing any client route returns 200 with the app.', confirmed: 'suspected',
+    });
+  }
   return F;
 }
 

package/src/cli.js

@@ -11,6 +11,15 @@ const { renderConsole, renderMarkdown } = require('./report');
 const { watch } = require('./watcher');
 const { init } = require('./init');
 const { analyzeDeps } = require('./deps');
+const ui = require('./ui');
+
+// Auto-open the browser only when a human is watching: an interactive stdout and
+// not a CI box. The UI file/server is still produced with --open to force it.
+function shouldOpen(args) {
+  if (args.flags.open) return true;
+  if (args.flags['no-open']) return false;
+  return !!process.stdout.isTTY && !process.env.CI;
+}
 
 // Map a --fail-on level to the worst-order index that still triggers exit 1.
 // order index: BLOCKER=0 CRITICAL=1 HIGH=2 MEDIUM=3 LOW=4 INFO=5
@@ -72,20 +81,68 @@ function cmdReview(args) {
     const p = args.flags.md || args.flags.o;
     safeWrite(typeof p === 'string' ? p : '.critic-report.md', renderMarkdown(result), 'Report');
   }
+  // Built-in per-run dashboard: a fresh, project-scoped HTML file opened in the
+  // browser. Skipped with --no-ui; browser-launch gated by TTY/CI (see shouldOpen).
+  if (!args.flags['no-ui']) {
+    const r = ui.writeStaticAndOpen(result, { open: shouldOpen(args) });
+    if (r.file) process.stdout.write(`\x1b[36mUI report:\x1b[0m ${r.file}\n`);
+    else if (r.error) process.stderr.write(`could not produce UI report: ${r.error}\n`);
+  }
   return exitCodeFor(result, args.flags['fail-on']);
 }
 
-function cmdWatch(args) {
+async function cmdWatch(args) {
   const target = targetOf(args);
+  let observer = null;
+  if (args.flags.dash) {
+    const obs = require('./observatory');
+    const wanted = Number(args.flags.port) || obs.DEFAULT_PORT;
+    process.stdout.write(`\x1b[90m[observatory] ensuring dashboard on port ${wanted}…\x1b[0m\n`);
+    const { port, reused } = await obs.ensureServer({ port: wanted });
+    observer = obs.createAdapter({ port, root: target, cliVersion: readVersion() });
+    await observer.open();
+    if (shouldOpen(args)) obs.openBrowser(`http://127.0.0.1:${port}/`);
+    process.stdout.write(
+      `\x1b[36m[observatory] streaming this watch → http://127.0.0.1:${port}/ \u00b7 ${reused ? 'reused running dashboard' : 'started new dashboard'}\x1b[0m\n`
+    );
+  }
+  // Built-in per-run live dashboard (default). Single process, single project,
+  // re-rendered every pass — no shared history, so nothing to clear between runs.
+  let dash = null;
+  if (!args.flags['no-ui']) {
+    dash = await ui.startLive(target, { port: Number(args.flags['ui-port']) || undefined });
+    if (dash) {
+      if (shouldOpen(args)) require('./observatory').openBrowser(dash.url);
+      process.stdout.write(`\x1b[36mUI (live):\x1b[0m ${dash.url}\n`);
+    }
+  }
+  let passNo = 0;
+  const onPass = (info) => {
+    passNo += 1;
+    if (dash) { try { dash.set(info.result, { passNo, added: info.added, resolved: info.resolved }); } catch (e) { process.stderr.write(`ui set error: ${e.message}\n`); } }
+    if (observer) { try { observer.pass(info); } catch (e) { process.stderr.write(`observatory onPass error: ${e.message}\n`); } }
+  };
   const w = watch(target, {
     debounceMs: Number(args.flags.debounce) || 400,
     report: (args.flags['report-file'] != null) ? (typeof args.flags['report-file'] === 'string' ? args.flags['report-file'] : '.critic-report.md') : '.critic-report.md',
     json: args.flags.json ? (typeof args.flags.json === 'string' ? args.flags.json : '.critic-review.json') : null,
+    onPass: (dash || observer) ? onPass : null,
+  });
+  process.on('SIGINT', () => {
+    if (observer) observer.close('sigint');
+    if (dash) dash.close();
+    w.close();
+    process.stdout.write('\nstopped watching.\n');
+    process.exit(0);
   });
-  process.on('SIGINT', () => { w.close(); process.stdout.write('\nstopped watching.\n'); process.exit(0); });
   return 0;
 }
 
+function readVersion() {
+  try { return JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version; }
+  catch { return 'unknown'; }
+}
+
 function cmdInit(args) {
   const target = path.resolve(args._[1] || '.');
   init(target);
@@ -134,11 +191,18 @@ Flags:
   --fail-on <level>  Exit 1 at this severity: blocker|high|medium|low|never   (review default: critical)
   --no-code          Skip code line-scanning (dependencies + structure only)
   --debounce <ms>    Watch mode settle time (default 400)
+  --dash             Additionally stream this watch into the external 3D Session Observatory
+  --port <n>         Session Observatory port when using --dash (default 4780)
+  --ui-port <n>      Base port for the built-in live dashboard in watch mode (default 4781; walks to a free port)
+  --no-ui            Do not launch the built-in dashboard (review/watch)
+  --open             Force the browser to open even in non-TTY/CI contexts
+  --no-open          Generate the dashboard but do not auto-open a browser window
   --quiet            Print only the summary line
 
 Examples:
   npx fullstack-critic review .
   critic watch ./my-app --md CRITIC_REPORT.md
+  critic watch . --dash            # live 3D mission control of the critic's work
   critic init && critic audit
 `);
   return 0;

package/src/observatory.js

@@ -0,0 +1,204 @@
+'use strict';
+/**
+ * Session Observatory adapter — the opt-in bridge between `critic watch` and a
+ * local 3D Session Observatory dashboard (`--dash`).
+ *
+ * It turns every watch-loop pass into protocol events and streams them to the
+ * observatory server over HTTP `POST /ingest`, so a critic run shows up as a
+ * living orb whose orbital rings are the analysis passes and findings it just
+ * surfaced. Design rules (see plan):
+ *   - Zero behavior change when `--dash` is absent (this module is only loaded
+ *     when the flag is present).
+ *   - Zero dependencies — only Node core (http / child_process / os).
+ *   - Never block or break the workflow over telemetry: every ingest is
+ *     fire-and-forget with errors swallowed.
+ *   - Port policy: reuse a healthy server on the requested port, else spawn one
+ *     (which itself walks to the next free port), and propagate that exact port.
+ */
+const http = require('http');
+const { spawn } = require('child_process');
+
+const DEFAULT_PORT = 4780;
+const PORT_SPAN = 10;
+const MAX_FINDING_EVENTS = 60; // cap so a huge diff can't flood the bus
+
+/* ------------------------------- transport -------------------------------- */
+
+function postEvent(port, event) {
+  return new Promise((resolve) => {
+    let body;
+    try { body = JSON.stringify(event); } catch { return resolve(); }
+    const req = http.request(
+      {
+        host: '127.0.0.1', port, path: '/ingest', method: 'POST', agent: false,
+        headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+        timeout: 2000,
+      },
+      (res) => { res.on('data', () => {}); res.on('end', () => resolve()); }
+    );
+    req.on('error', () => resolve());   // dashboard down → workflow unaffected
+    req.on('timeout', () => { req.destroy(); resolve(); });
+    req.end(body);
+  });
+}
+
+function healthProbe(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/health', timeout: 1000, agent: false }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => { try { resolve(JSON.parse(data)); } catch { resolve(null); } });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/* ------------------------------ server launch ------------------------------ */
+
+function resolveLauncher() {
+  // Prefer a locally installed copy; otherwise let npx fetch it on demand.
+  try {
+    const bin = require.resolve('session-observatory/bin/session-observatory.js');
+    return { cmd: process.execPath, prefix: [bin] };
+  } catch {
+    const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    return { cmd: npx, prefix: ['--yes', 'session-observatory'] };
+  }
+}
+
+function spawnServer(port) {
+  const { cmd, prefix } = resolveLauncher();
+  const args = [...prefix, 'serve', '--port', String(port), '--no-open'];
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    child.on('error', () => { /* npx missing — the poll below just won't find it */ });
+    child.unref();
+    return child;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensure a dashboard is answering, honouring the port policy. Returns
+ * { port, reused, spawned }.
+ */
+async function ensureServer(opts = {}) {
+  const base = Number(opts.port) || DEFAULT_PORT;
+  const existing = await healthProbe(base);
+  if (existing && existing.product === 'session-observatory') {
+    return { port: existing.port || base, reused: true, spawned: null };
+  }
+
+  const spawned = spawnServer(base);
+  // Poll a small window: a fresh server may walk up to a neighbouring free port.
+  for (let attempt = 0; attempt < 12; attempt++) {
+    await sleep(400);
+    for (let p = base; p <= base + PORT_SPAN; p++) {
+      const h = await healthProbe(p);
+      if (h && h.product === 'session-observatory') return { port: h.port || p, reused: false, spawned };
+    }
+  }
+  // Never found — still return the base port so ingest calls fail silently.
+  return { port: base, reused: false, spawned };
+}
+
+/* --------------------------------- adapter -------------------------------- */
+
+function createAdapter(opts = {}) {
+  const port = Number(opts.port) || DEFAULT_PORT;
+  const root = opts.root || process.cwd();
+  const sessionId = opts.sessionId || `critic-${process.pid}`;
+  const cliVersion = opts.cliVersion || 'unknown';
+  const send = (type, payload, metrics) =>
+    postEvent(port, { ts: Date.now(), sessionId, source: 'critic', type, payload: payload || {}, metrics });
+
+  return {
+    sessionId,
+    port,
+
+    open() {
+      return send('session.open', {
+        label: 'fullstack-critic watch',
+        root,
+        pid: process.pid,
+        cli: cliVersion,
+        cwd: process.cwd(),
+      });
+    },
+
+    /**
+     * Called once per watch pass. Emits an analysis background batch, the
+     * finding-added / finding-fixed diff, and a metrics snapshot so the HUD can
+     * show severity counts and a live rss/cpu heartbeat.
+     */
+    pass(info = {}) {
+      const result = info.result;
+      if (!result) return Promise.resolve();
+      const events = [];
+      const meta = result.meta || {};
+      const cov = result.coverage || {};
+      events.push(send('bg.batch', {
+        category: 'analysis', count: 1,
+        durationMs: meta.durationMs || 0, filesScanned: cov.filesScanned || 0,
+      }));
+
+      const added = (info.added || []).slice(0, MAX_FINDING_EVENTS);
+      const resolved = (info.resolved || []).slice(0, MAX_FINDING_EVENTS);
+      for (const f of added) {
+        events.push(send('bg.batch', {
+          category: 'analysis', kind: 'finding-added', count: 1,
+          ruleId: f.ruleId, severity: f.severity, file: f.file, line: f.line, message: f.title,
+        }));
+      }
+      for (const f of resolved) {
+        events.push(send('bg.batch', {
+          category: 'analysis', kind: 'finding-fixed', count: 1,
+          ruleId: f.ruleId, severity: f.severity, file: f.file, line: f.line, message: f.title,
+        }));
+      }
+
+      const counts = result.counts || {};
+      const mem = process.memoryUsage();
+      events.push(send('metrics', {}, {
+        critical: (counts.CRITICAL || 0) + (counts.BLOCKER || 0),
+        high: counts.HIGH || 0,
+        medium: counts.MEDIUM || 0,
+        low: counts.LOW || 0,
+        info: counts.INFO || 0,
+        total: (result.findings || []).length,
+        filesScanned: cov.filesScanned || 0,
+        passMs: meta.durationMs || 0,
+        rssMb: Math.round(mem.rss / 1048576),
+      }));
+      return Promise.all(events);
+    },
+
+    close(reason) {
+      return send('session.close', { reason: reason || 'watch-stopped' });
+    },
+  };
+}
+
+/* ------------------------------ browser open ------------------------------ */
+
+function openBrowser(url) {
+  try {
+    const platform = process.platform;
+    let cmd, args;
+    if (platform === 'win32') { cmd = 'cmd'; args = ['/c', 'start', '""', url.replace(/&/g, '^&')]; }
+    else if (platform === 'darwin') { cmd = 'open'; args = [url]; }
+    else { cmd = 'xdg-open'; args = [url]; }
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { ensureServer, createAdapter, openBrowser, postEvent, healthProbe, DEFAULT_PORT };

package/src/report.js

@@ -47,11 +47,42 @@ function renderConsole(result) {
   lines.push('Action plan: ' +
     `${categoryCounts.fix} fix · ${categoryCounts.optimize} optimize · ${categoryCounts.delete} delete · ${categoryCounts.add} add`);
   lines.push('Verdict: ' + execSummary(result));
-  const top = result.findings.filter((f) => ['BLOCKER', 'CRITICAL', 'HIGH'].includes(f.severity)).slice(0, 12);
-  if (top.length) {
+
+  // Group every finding by dimension so all severity levels — not just blocking —
+  // are visible in the terminal (packaging, routing, API, validation, frontend, backend…).
+  const byDim = {};
+  for (const f of result.findings) (byDim[f.dimension] || (byDim[f.dimension] = [])).push(f);
+  const orderedDims = [
+    ...DIMENSIONS.filter((d) => byDim[d]),
+    ...Object.keys(byDim).filter((d) => !DIMENSIONS.includes(d)),
+  ];
+
+  if (orderedDims.length) {
+    lines.push('');
+    lines.push('Findings by dimension (all severities):');
+    for (const d of orderedDims) {
+      const ds = byDim[d];
+      const parts = SEV_ORDER.filter((s) => ds.some((f) => f.severity === s))
+        .map((s) => `${ds.filter((f) => f.severity === s).length} ${s}`)
+        .join(' · ');
+      lines.push(`  ${d.padEnd(20)} ${parts}`);
+    }
+  }
+
+  const verbose = process.env.CRITIC_VERBOSE ? Number(process.env.CRITIC_VERBOSE) : 1;
+  const PER_DIM_CAP = verbose >= 2 ? Infinity : 15;
+  for (const d of orderedDims) {
+    const ds = byDim[d];
+    lines.push('');
+    lines.push(`${d} — ${ds.length} finding(s)${ds.length > PER_DIM_CAP ? ` (showing ${PER_DIM_CAP}, worst first; --md for all)` : ''}:`);
+    // Findings arrive pre-sorted by severity → file → line; keep that order.
+    for (const f of ds.slice(0, PER_DIM_CAP)) {
+      lines.push(`  [${f.severity}] ${f.file}:${f.line}  ${f.title}`);
+    }
+  }
+  if (result.findings.length) {
     lines.push('');
-    lines.push('Top blocking findings:');
-    for (const f of top) lines.push(`  [${f.severity}] ${f.file}:${f.line}  ${f.title}`);
+    lines.push('Run with --md <file> for the full evidence, impact & fix per finding.');
   }
   return lines.join('\n');
 }

package/src/rules.js

@@ -177,6 +177,121 @@ const LINE_RULES = [
     fix: 'Add keyset/cursor pagination or an explicit LIMIT.',
     verify: 'endpoint returns a bounded page size.',
   },
+
+  // ---- API design ---------------------------------------------------------
+  {
+    id: 'api-numbered-endpoints', severity: 'INFO', category: 'add', dimension: 'API design',
+    title: 'Verb-in-URL endpoint (non-RESTful routing)',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.py', '.rb', '.php', '.java', '.go'],
+    test: /\.(get|post|put|patch|delete|route)\s*\(\s*["'][^"']*\/(create|update|delete|get|fetch|list|add|remove|edit)[A-Za-z]*/i,
+    problem: 'Endpoint path embeds the action verb instead of relying on the HTTP method.',
+    impact: 'Inconsistent contract; harder to version and document.',
+    fix: 'Use method + noun (POST /orders, PATCH /orders/:id, DELETE /orders/:id).',
+    verify: 'route list contains no verb segments.',
+  },
+  {
+    id: 'fetch-unhandled', severity: 'MEDIUM', category: 'fix', dimension: 'API design',
+    title: 'Network call without error handling (.ok/.catch missing)',
+    ext: ['.js', '.ts', '.jsx', '.tsx', '.mjs'],
+    test: /\bfetch\s*\(/,
+    skipIf: (line) => /\.ok\b|\.catch\s*\(|try\s*\{|await\s+safe|\bthen\s*\([^)]*\)\s*\.catch|critic-ignore/.test(line),
+    problem: 'fetch resolves on 4xx/5xx; without .ok or .catch failures are silently ignored.',
+    impact: 'Failed requests render empty/broken UIs instead of error states.',
+    fix: 'Check res.ok and wrap in try/catch, or route through one client that does.',
+    verify: 'a 500 response surfaces the error path in the UI/logs.',
+  },
+
+  // ---- Validation & routing (security-adjacent) ---------------------------
+  {
+    id: 'open-redirect', severity: 'MEDIUM', category: 'fix', dimension: 'Security',
+    title: 'Redirect target built from request input',
+    ext: ['.js', '.ts', '.mjs', '.cjs', '.py', '.rb', '.php'],
+    test: /redirect\s*\([^)]*(req\.(query|params|body)|location\.search|URLSearchParams|get\s*\(\s*["']next)/,
+    problem: 'A user-controlled value decides where the browser is sent.',
+    impact: 'Open redirect — phishing via a trusted domain.',
+    fix: 'Validate against an allowlist of internal paths; reject absolute URLs.',
+    verify: 'redirect to an external host is rejected.',
+  },
+  {
+    id: 'form-no-validation', severity: 'MEDIUM', category: 'fix', dimension: 'Correctness',
+    title: 'Form submit without validation',
+    ext: ['.jsx', '.tsx', '.js', '.ts', '.html', '.vue', '.svelte'],
+    test: /<form\b[^>]*\bonsubmit\s*=/i,
+    skipIf: (line) => /validate|isValid|\.checkValidity|zod|yup|joi|required/i.test(line),
+    problem: 'Submit path accepts whatever the fields contain.',
+    impact: 'Malformed or hostile data reaches the API; server must never be the only gate.',
+    fix: 'Validate on submit and surface field errors (or a schema library).',
+    verify: 'empty/invalid submit is blocked with messages.',
+  },
+  {
+    id: 'novalidate-form', severity: 'LOW', category: 'fix', dimension: 'Correctness',
+    title: 'Form disables browser validation',
+    test: /<form[^>]*novalidate/i,
+    skipIf: (line) => /customValidity|custom-validation|validateForm/i.test(line),
+    problem: 'novalidate turns off built-in required/type checks.',
+    impact: 'Users submit invalid values unless a custom validator fully replaces them.',
+    fix: 'Remove novalidate, or guarantee an equivalent custom validation path.',
+    verify: 'invalid field blocks submit.',
+  },
+
+  // ---- Frontend & a11y ------------------------------------------------------
+  {
+    id: 'a11y-clickable-div', severity: 'MEDIUM', category: 'fix', dimension: 'Frontend',
+    title: 'Click handler on a non-interactive element',
+    ext: ['.jsx', '.tsx', '.html', '.vue', '.svelte'],
+    test: /<(div|span|img|li|p)\b[^>]*\son(Click|KeyPress|KeyDown)\s*=/,
+    skipIf: (line) => /role\s*=|tabIndex/i.test(line),
+    problem: 'Interactive behaviour lives on an element keyboards and screen readers skip.',
+    impact: 'Primary actions unreachable for keyboard/AT users.',
+    fix: 'Use <button> or add role="button" + tabIndex + key handling.',
+    verify: 'the action is triggerable by Tab + Enter.',
+  },
+  {
+    id: 'img-missing-alt', severity: 'LOW', category: 'fix', dimension: 'Frontend',
+    title: 'Image without alt text',
+    ext: ['.jsx', '.tsx', '.html', '.vue', '.svelte'],
+    test: /<img\b(?![^>]*alt\s*=)[^>]*src=/i,
+    problem: '<img> lacks an alt attribute.',
+    impact: 'Screen readers announce nothing; Lighthouse a11y failures.',
+    fix: 'Add meaningful alt, or alt="" for decorative images.',
+    verify: 'axe/Lighthouse a11y passes the images rule.',
+  },
+  {
+    id: 'plain-img-next', severity: 'LOW', category: 'optimize', dimension: 'Frontend',
+    title: 'Plain <img> in Next.js (next/image preferred)',
+    ext: ['.jsx', '.tsx'],
+    test: /<img\s/,
+    skipIf: (line) => /next\/image|<Image\b/i.test(line),
+    problem: 'Hand-written <img> skips automatic resizing, lazy-loading and format negotiation.',
+    impact: 'Wasted bytes and worse LCP — the metric that decides search rank.',
+    fix: 'Use next/image with explicit width/height.',
+    verify: 'Lighthouse image credits improve.',
+  },
+  {
+    id: 'default-props-function', severity: 'LOW', category: 'optimize', dimension: 'Frontend',
+    title: 'defaultProps on function components (deprecated)',
+    ext: ['.jsx', '.tsx'],
+    test: /\.defaultProps\s*=/,
+    problem: 'React removed defaultProps support for function components.',
+    impact: 'Defaults silently stop applying on React 19+.',
+    fix: 'Use ES parameter defaults.',
+    verify: 'no .defaultProps assignments remain.',
+  },
+
+  // ---- Backend on async runtimes -------------------------------------------
+  {
+    id: 'sync-io-in-handler', severity: 'MEDIUM', category: 'fix', dimension: 'Backend',
+    title: 'Synchronous fs call inside a request handler',
+    ext: ['.js', '.ts', '.mjs', '.cjs'],
+    test: /fs\.(readFileSync|writeFileSync|appendFileSync|readdirSync|existsSync|statSync)\s*\(/,
+    // Only flag inside request-handler surfaces (routes/api/serverless handlers),
+    // where the block stalls every other in-flight request; scripts/CLI use sync fs freely.
+    skipIf: (line, ctx) => !(ctx && /(^|[\\/])(routes?|api|controllers?|handlers?|serverless|\.\/(pages|app)\/api|[\\/]pages\/api[\\/])/i.test(ctx.rel || '')),
+    problem: 'Blocking fs freezes the event loop for every other in-flight request.',
+    impact: 'Tail latency spikes and throughput collapse under load.',
+    fix: 'Use fs.promises / the async API, or preload at startup.',
+    verify: 'load test shows unchanged p95 while the file path is hit.',
+  },
 ];
 
 module.exports = { LINE_RULES, PLACEHOLDER };

package/src/ui.js

@@ -0,0 +1,297 @@
+'use strict';
+/**
+ * Built-in per-run critic dashboard. Zero-dependency (Node core only).
+ *
+ * Why this exists: the only previous UI was the opt-in `--dash` bridge into an
+ * external, *shared* Session Observatory server that accumulates every session,
+ * so it visually mixes reports from other projects. This module is instead
+ * single-tenant: each `critic review`/`critic watch` process owns its own state,
+ * scoped to exactly one project. Starting a new run therefore always shows fresh
+ * data (there is nothing to clear because nothing is shared or persisted).
+ *
+ *   - review  -> writeStaticAndOpen(): one self-contained HTML file in a per-run
+ *                 temp path (unique + titled with the project), opened in the OS
+ *                 browser. No server left running; never written into the repo.
+ *   - watch   -> startLive(): an in-memory HTTP server on a verified free port
+ *                 that re-renders on every pass. Live updates; no file in the repo.
+ *
+ * Port policy: probe from a base port and walk to the next bindable port.
+ * Never block or break the workflow: any UI error is swallowed to a warning.
+ */
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const net = require('net');
+const { DIMENSIONS } = require('./analyzer');
+const { execSummary } = require('./report');
+const { openBrowser } = require('./observatory');
+
+const SEV_ORDER = ['BLOCKER', 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
+const UI_BASE_PORT = 4781;   // distinct from the observatory's 4780
+const PORT_SPAN = 15;
+
+function relName(root) {
+  const parts = String(root).replace(/[\\/]+$/, '').split(/[\\/]/);
+  return parts[parts.length - 1] || String(root);
+}
+
+/* ------------------------------ snapshot model ---------------------------- */
+
+function buildSnapshot(result, extra = {}) {
+  const counts = result.counts || {};
+  const cat = result.categoryCounts || {};
+  const cov = result.coverage || {};
+  const findings = result.findings || [];
+
+  const byDim = {};
+  for (const f of findings) (byDim[f.dimension] || (byDim[f.dimension] = [])).push(f);
+  const dimensions = DIMENSIONS.map((d) => {
+    const ds = byDim[d] || [];
+    const worst = SEV_ORDER.find((s) => ds.some((f) => f.severity === s));
+    const status = !ds.length ? 'REVIEW'
+      : (worst === 'BLOCKER' || worst === 'CRITICAL' || worst === 'HIGH') ? 'FAIL'
+        : (worst === 'MEDIUM' || worst === 'LOW') ? 'WARN' : 'INFO';
+    return { dimension: d, status, count: ds.length, worst: worst || '-' };
+  });
+
+  return {
+    empty: false,
+    project: relName((result.meta && result.meta.root) || ''),
+    root: (result.meta && result.meta.root) || '',
+    generatedAt: new Date().toISOString(),
+    cliVersion: (result.meta && result.meta.cliVersion) || 'unknown',
+    durationMs: (result.meta && result.meta.durationMs) || 0,
+    passNo: extra.passNo || 1,
+    addedCount: (extra.added || []).length,
+    resolvedCount: (extra.resolved || []).length,
+    verdict: execSummary(result),
+    counts,
+    categoryCounts: cat,
+    coverage: {
+      filesScanned: cov.filesScanned || 0,
+      totalLines: cov.totalLines || 0,
+      filesSkipped: cov.filesSkipped || 0,
+    },
+    ecosystems: (result.dependencies || []).map((e) => ({
+      name: e.name, manifest: e.manifest, declaredCount: e.declaredCount, lock: e.lock || null,
+    })),
+    dimensions,
+    findings: findings.map((f) => ({
+      file: f.file, line: f.line, severity: f.severity, category: f.category,
+      dimension: f.dimension, title: f.title, problem: f.problem, fix: f.fix, evidence: f.evidence,
+    })),
+  };
+}
+
+function emptySnapshot(root) {
+  return {
+    empty: true, project: relName(root), root, generatedAt: new Date().toISOString(),
+    passNo: 0, counts: {}, categoryCounts: {}, findings: [], dimensions: [], ecosystems: [],
+  };
+}
+
+/* ------------------------------- HTML shell ------------------------------- */
+
+// NOTE: the embedded client script intentionally avoids backticks/${} so it can
+// live inside this file's template literals without clashing with Node's parser.
+function renderHtml(data, opts = {}) {
+  const live = opts.live ? 'true' : 'false';
+  const payload = JSON.stringify(data).replace(/</g, '\\u003c');
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Full-Stack Critic — ${escAttr(data.project)}</title>
+<link rel="icon" href="data:,">
+<style>
+  :root{--bg:#0b1020;--card:#151b2e;--ink:#e6ecff;--mut:#93a0c2;--line:#26304a;--critic:#ff5470;--high:#ff9f43;--med:#ffd166;--low:#8bd450;--info:#63b3ed;--ok:#3ddc97;}
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--ink);font:14px/1.5 system-ui,Segoe UI,Roboto,Arial,sans-serif}
+  header{padding:22px 26px;border-bottom:1px solid var(--line);background:linear-gradient(180deg,#111834,#0b1020)}
+  h1{margin:0;font-size:20px;letter-spacing:.3px}
+  h1 .proj{color:var(--info)}
+  .sub{color:var(--mut);margin-top:6px;font-size:12.5px}
+  main{padding:22px 26px;max-width:1080px;margin:0 auto}
+  .verdict{font-size:16px;font-weight:600;padding:12px 16px;border-radius:10px;background:var(--card);border:1px solid var(--line);margin-bottom:18px}
+  .grid{display:flex;flex-wrap:wrap;gap:10px;margin-bottom:18px}
+  .chip{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:10px 14px;min-width:78px}
+  .chip b{display:block;font-size:22px}
+  .chip span{color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.6px}
+  .sev-CRITICAL,.sev-BLOCKER{color:var(--critic)} .sev-HIGH{color:var(--high)} .sev-MEDIUM{color:var(--med)} .sev-LOW{color:var(--low)} .sev-INFO{color:var(--info)}
+  h2{font-size:14px;text-transform:uppercase;letter-spacing:.8px;color:var(--mut);margin:26px 0 10px}
+  table{width:100%;border-collapse:collapse;background:var(--card);border:1px solid var(--line);border-radius:10px;overflow:hidden}
+  th,td{text-align:left;padding:9px 12px;border-bottom:1px solid var(--line);vertical-align:top}
+  th{color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.5px}
+  tr:last-child td{border-bottom:none}
+  code{background:#0c1226;border:1px solid var(--line);border-radius:5px;padding:1px 6px;color:#cdd8ff;font-size:12px}
+  .tag{display:inline-block;font-size:10.5px;font-weight:700;padding:2px 8px;border-radius:999px;border:1px solid var(--line);text-transform:uppercase;letter-spacing:.4px}
+  .cat-fix{color:var(--critic)} .cat-optimize{color:var(--high)} .cat-delete{color:var(--med)} .cat-add{color:var(--ok)}
+  .st-FAIL{background:rgba(255,84,112,.14);color:var(--critic)} .st-WARN{background:rgba(255,209,102,.14);color:var(--med)} .st-INFO{background:rgba(99,179,237,.14);color:var(--info)} .st-REVIEW{background:rgba(147,160,194,.14);color:var(--mut)}
+  details{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px 14px;margin-bottom:10px}
+  summary{cursor:pointer;font-weight:600}
+  .loc{color:var(--mut);font-size:12px;margin-left:8px}
+  .field{margin:8px 0} .field .k{color:var(--mut);font-size:11px;text-transform:uppercase}
+  footer{color:var(--mut);font-size:11.5px;padding:20px 26px;border-top:1px solid var(--line);margin-top:24px}
+  .pulse{display:inline-block;width:8px;height:8px;border-radius:50%;background:var(--ok);margin-right:6px;animation:p 1.4s infinite}
+  @keyframes p{0%,100%{opacity:.3}50%{opacity:1}}
+</style></head>
+<body>
+<header>
+  <h1>Full-Stack Critic <span class="proj" id="h-proj"></span></h1>
+  <div class="sub" id="h-sub"></div>
+</header>
+<main>
+  <div class="verdict" id="verdict"></div>
+  <div class="grid" id="counts"></div>
+  <h2>12-Dimension Executive Summary</h2>
+  <table id="dims"><thead><tr><th>Dimension</th><th>Status</th><th>Findings</th><th>Worst</th></tr></thead><tbody></tbody></table>
+  <h2>Prioritised Action Plan</h2>
+  <div id="plan"></div>
+  <h2>All Findings</h2>
+  <div id="findings"></div>
+  <h2>Resources & Dependencies</h2>
+  <div id="deps"></div>
+</main>
+<footer id="foot"></footer>
+<script>
+var INITIAL = ${payload};
+var LIVE = ${live};
+var SEV = ['BLOCKER','CRITICAL','HIGH','MEDIUM','LOW','INFO'];
+var CATS = [['fix','FIX — correctness & security'],['optimize','OPTIMIZE — performance & structure'],['delete','DELETE — dead code & debug'],['add','ADD — tests, config & docs']];
+function el(t,c,x){var e=document.createElement(t);if(c)e.className=c;if(x!=null)e.textContent=x;return e;}
+function render(d){
+  document.getElementById('h-proj').textContent = '— ' + (d.project||'');
+  var sub = (d.root||'') + '  ·  ' + (d.generatedAt? new Date(d.generatedAt).toLocaleString():'');
+  if(d.empty){ sub = 'waiting for first analysis pass…'; }
+  else if(LIVE){ sub += '  ·  live pass #' + d.passNo + ' (+'+d.addedCount+' new / -'+d.resolvedCount+' fixed)'; }
+  document.getElementById('h-sub').textContent = sub;
+
+  var v=document.getElementById('verdict'); v.textContent='';
+  if(d.empty){ v.appendChild(el('span',null,'Analysis starting…')); return; }
+  v.appendChild(el('span','pulse'));
+  v.appendChild(el('span',null,d.verdict||''));
+
+  var c=document.getElementById('counts'); c.textContent='';
+  SEV.forEach(function(s){ if(!d.counts[s]) return; var chip=el('div','chip'); chip.appendChild(el('b','sev-'+s,String(d.counts[s]))); chip.appendChild(el('span',null,s)); c.appendChild(chip); });
+  ['fix','optimize','delete','add'].forEach(function(k){ if(!d.categoryCounts[k]) return; var chip=el('div','chip'); chip.appendChild(el('b','cat-'+k,String(d.categoryCounts[k]))); chip.appendChild(el('span',null,'to '+k)); c.appendChild(chip); });
+
+  var tb=document.querySelector('#dims tbody'); tb.textContent='';
+  (d.dimensions||[]).forEach(function(x){ var tr=el('tr'); tr.appendChild(el('td',null,x.dimension)); var st=el('td'); st.appendChild(el('span','tag st-'+x.status,x.status)); tr.appendChild(st); tr.appendChild(el('td',null,String(x.count))); tr.appendChild(el('td','sev-'+(x.worst||''),''),x.worst==='-'?null:x.worst); if(x.worst==='-')tr.lastChild.textContent='—'; tb.appendChild(tr); });
+
+  var p=document.getElementById('plan'); p.textContent='';
+  CATS.forEach(function(pair){
+    var key=pair[0]; var items=(d.findings||[]).filter(function(f){return f.category===key;});
+    if(!items.length) return;
+    var h=el('h3','cat-'+key, pair[1]+' — '+items.length+' item(s)'); p.appendChild(h);
+    var t=el('table'); var thead=el('thead'); var hr=el('tr');
+    ['Sev','Where','Action','Fix'].forEach(function(x){hr.appendChild(el('th',null,x));}); thead.appendChild(hr); t.appendChild(thead);
+    var body=el('tbody');
+    items.slice(0,200).forEach(function(f){ var tr=el('tr'); tr.appendChild(el('td','sev-'+f.severity,f.severity)); tr.appendChild(el('td')).appendChild(el('code',null,f.file+':'+f.line)); tr.appendChild(el('td',null,f.title)); tr.appendChild(el('td',null,f.fix||f.problem||'')); body.appendChild(tr); });
+    t.appendChild(body); p.appendChild(t);
+  });
+
+  var fd=document.getElementById('findings'); fd.textContent='';
+  if(!(d.findings||[]).length){ fd.appendChild(el('p','sub','No automated findings.')); }
+  (d.findings||[]).slice(0,400).forEach(function(f){
+    var det=el('details'); var sum=el('summary'); sum.appendChild(el('span','sev-'+f.severity,'['+f.severity+'] ')); sum.appendChild(document.createTextNode(f.title)); sum.appendChild(el('span','loc',f.file+':'+f.line+'  ·  '+f.dimension+'  ·  '+f.category)); det.appendChild(sum);
+    [['Problem',f.problem],['Evidence',f.evidence],['Fix',f.fix]].forEach(function(pair){ if(!pair[1])return; var div=el('div','field'); div.appendChild(el('div','k',pair[0])); div.appendChild(el('code',null,pair[1])); det.appendChild(div); });
+    fd.appendChild(det);
+  });
+
+  var dp=document.getElementById('deps'); dp.textContent='';
+  var info=el('p','sub','Scanned '+d.coverage.filesScanned+' files · '+Number(d.coverage.totalLines).toLocaleString()+' lines · '+d.coverage.filesSkipped+' counted-but-skipped resources · '+(d.ecosystems||[]).length+' package ecosystem(s).');
+  dp.appendChild(info);
+  if((d.ecosystems||[]).length){ var t=el('table'); var body=el('tbody');
+    d.ecosystems.forEach(function(e){ var tr=el('tr'); tr.appendChild(el('td',null,e.name)); tr.appendChild(el('td')).appendChild(el('code',null,e.manifest)); tr.appendChild(el('td',null,String(e.declaredCount)+' declared')); var lk=el('td'); if(e.lock){lk.appendChild(el('code',null,e.lock));}else{lk.appendChild(el('span','tag st-FAIL','NO LOCKFILE'));} tr.appendChild(lk); body.appendChild(tr); });
+    t.appendChild(body); dp.appendChild(t); }
+
+  document.getElementById('foot').textContent = 'Full-Stack Critic v'+(d.cliVersion||'')+' · read-only REVIEW · this dashboard is scoped to this single run/project ('+(d.root||'')+') and holds no history from other projects.';
+}
+render(INITIAL);
+function offline(){ var v=document.getElementById('verdict'); if(v){ v.textContent=''; v.appendChild(el('span',null,'Dashboard disconnected - the critic watch process is no longer serving. Restart it to resume live updates.')); } }
+if(LIVE){ setInterval(function(){ fetch('/data',{cache:'no-store'}).then(function(r){return r.json();}).then(render).catch(offline); }, 1500); }
+function esc(s){return String(s==null?'':s);}
+</script>
+</body></html>`;
+}
+
+function escAttr(s) {
+  return String(s == null ? '' : s).replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' }[c]));
+}
+
+/* ------------------------------ free port probe --------------------------- */
+
+function pickFreePort(base, span) {
+  const b = Number(base) || UI_BASE_PORT;
+  const s = Number(span) || PORT_SPAN;
+  return new Promise((resolve) => {
+    let p = b;
+    (function test() {
+      if (p > b + s) return resolve(null);
+      const probe = net.createServer();
+      probe.once('error', () => { p++; test(); });
+      probe.once('listening', () => { probe.close(() => resolve(p)); });
+      probe.listen(p, '127.0.0.1');
+    })();
+  });
+}
+
+/* ------------------------------- static (review) -------------------------- */
+
+function writeStaticAndOpen(result, opts = {}) {
+  try {
+    const data = buildSnapshot(result, opts.extra || {});
+    const dir = path.join(os.tmpdir(), 'fullstack-critic');
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = data.generatedAt.replace(/[:.]/g, '-');
+    const file = path.join(dir, `${data.project}-${stamp}.html`);
+    fs.writeFileSync(file, renderHtml(data, { live: false }));
+    const url = 'file:///' + file.replace(/\\/g, '/');
+    if (opts.open !== false) openBrowser(url);
+    return { file, url };
+  } catch (e) {
+    return { error: e.code || e.message };
+  }
+}
+
+/* --------------------------------- live (watch) --------------------------- */
+
+function startLive(root, opts = {}) {
+  let data = emptySnapshot(root);
+  const server = http.createServer((req, res) => {
+    if (req.url === '/data') {
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      return res.end(JSON.stringify(data));
+    }
+    if (req.url === '/health') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      return res.end(JSON.stringify({ product: 'critic-ui', port: server.address() ? server.address().port : 0 }));
+    }
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(renderHtml(data, { live: true }));
+  });
+
+  return pickFreePort(opts.port).then((port) => {
+    if (!port) return null; // no free port in range → skip UI, never break the workflow
+    return new Promise((resolve) => {
+      server.once('error', (e) => {
+        process.stderr.write(`critic UI server unavailable (${e.code || e.message}); watch continues without the dashboard.\n`);
+        resolve(null);
+      });
+      server.once('listening', () => {
+        const bound = server.address().port;
+        resolve({
+          port: bound,
+          url: `http://127.0.0.1:${bound}/`,
+          set: (r, extra) => { data = buildSnapshot(r, extra); },
+          close: () => { try { server.close(); } catch { /* already closed */ } },
+        });
+      });
+      server.listen(port, '127.0.0.1');
+    });
+  });
+}
+
+module.exports = {
+  buildSnapshot, renderHtml, writeStaticAndOpen, startLive, pickFreePort,
+  UI_BASE_PORT, SEV_ORDER,
+};

package/src/util.js

@@ -15,6 +15,12 @@ const SKIP_DIRS = new Set([
   '.critic', '.critic-memory',
 ]);
 
+// Files the critic itself generates. Never re-scanned: otherwise a previous
+// report's example findings would echo back as stale "findings" forever.
+const OUTPUT_FILES = new Set([
+  '.critic-report.md', '.critic-review.json', '.critic-report.html', '.critic-report.json',
+]);
+
 // Extensions that are definitely not scannable text.
 const BINARY_EXT = new Set([
   '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.bmp', '.tiff', '.pdf',
@@ -62,6 +68,10 @@ function walk(root) {
         skipped.push({ rel, reason: 'symbolic link (not followed)' });
         continue;
       }
+      if (OUTPUT_FILES.has(ent.name)) {
+        skipped.push({ rel, reason: 'critic output artifact (self-report, not re-scanned)' });
+        continue;
+      }
       let st;
       try { st = fs.statSync(abs); } catch (e) { skipped.push({ rel, reason: `stat failed (${e.code})` }); continue; }
       const ext = path.extname(ent.name).toLowerCase();
@@ -96,4 +106,4 @@ function exists(p) {
   try { fs.accessSync(p); return true; } catch { return false; }
 }
 
-module.exports = { walk, readText, exists, SKIP_DIRS, MAX_FILE_BYTES };
+module.exports = { walk, readText, exists, SKIP_DIRS, OUTPUT_FILES, MAX_FILE_BYTES };

package/src/watcher.js

@@ -49,12 +49,15 @@ function watch(root, opts = {}) {
     const result = analyze(root);
     const current = new Map(result.findings.map((f) => [keyOf(f), f]));
 
+    let added = [];
+    let resolved = [];
     if (first) {
       process.stdout.write(renderConsole(result) + '\n');
+      added = [...current.values()]; // initial surfacing of everything open
       first = false;
     } else {
-      const added = [...current.values()].filter((f) => !last.has(keyOf(f)));
-      const resolved = [...last.values()].filter((f) => !current.has(keyOf(f)));
+      added = [...current.values()].filter((f) => !last.has(keyOf(f)));
+      resolved = [...last.values()].filter((f) => !current.has(keyOf(f)));
       const time = new Date().toLocaleTimeString();
       if (!added.length && !resolved.length) {
         process.stdout.write(`\x1b[90m[${time}] no change in findings (${result.findings.length} total).\x1b[0m\n`);
@@ -71,6 +74,13 @@ function watch(root, opts = {}) {
     }
     last = current;
 
+    // Optional observatory hook (only present with `--dash`); never let it
+    // break the watch loop.
+    if (opts.onPass) {
+      try { opts.onPass({ result, added, resolved }); }
+      catch (e) { process.stderr.write(`observatory onPass error: ${e.message}\n`); }
+    }
+
     if (opts.report) {
       try { fs.writeFileSync(opts.report, renderMarkdown(result)); }
       catch (e) { process.stderr.write(`could not write report ${opts.report}: ${e.message}\n`); }

package/tests/observatory.test.js

@@ -0,0 +1,111 @@
+'use strict';
+/**
+ * Session Observatory adapter self-tests (zero-dependency, `node --test`).
+ * A throwaway HTTP collector stands in for the observatory server so we can
+ * assert the exact protocol events a `critic watch --dash` run emits — the
+ * mapping contract between the two packages — without importing the server.
+ */
+const test = require('node:test');
+const assert = require('node:assert');
+const http = require('node:http');
+
+const { createAdapter, healthProbe, DEFAULT_PORT } = require('../src/observatory');
+
+function startCollector() {
+  const events = [];
+  const server = http.createServer((req, res) => {
+    if (req.method === 'POST' && req.url === '/ingest') {
+      let body = '';
+      req.on('data', (c) => { body += c; });
+      req.on('end', () => {
+        try { events.push(JSON.parse(body)); } catch { /* ignore malformed */ }
+        res.writeHead(202, { 'content-type': 'application/json' });
+        res.end('{"accepted":1}');
+      });
+      return;
+    }
+    res.writeHead(404); res.end();
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: server.address().port,
+        events,
+        close: () => new Promise((r) => server.close(r)),
+      });
+    });
+  });
+}
+
+const fakeResult = (n) => ({
+  meta: { durationMs: 42 },
+  coverage: { filesScanned: n },
+  counts: { BLOCKER: 0, CRITICAL: 1, HIGH: 2, MEDIUM: 3, LOW: 4, INFO: 5 },
+  findings: [{ file: 'a.js', line: 3, ruleId: 'hardcoded-secret', severity: 'CRITICAL', title: 'secret' }],
+});
+
+test('adapter emits session.open with critic source and root', async () => {
+  const col = await startCollector();
+  const a = createAdapter({ port: col.port, root: '/tmp/proj' });
+  await a.open();
+  assert.strictEqual(col.events.length, 1);
+  const ev = col.events[0];
+  assert.strictEqual(ev.type, 'session.open');
+  assert.strictEqual(ev.source, 'critic');
+  assert.strictEqual(ev.payload.root, '/tmp/proj');
+  assert.ok(ev.sessionId.startsWith('critic-'));
+  await col.close();
+});
+
+test('pass() maps an analysis batch, the finding diff, and severity metrics', async () => {
+  const col = await startCollector();
+  const a = createAdapter({ port: col.port });
+  await a.pass({
+    result: fakeResult(12),
+    added: [{ file: 'a.js', line: 3, ruleId: 'hardcoded-secret', severity: 'CRITICAL', title: 'secret' }],
+    resolved: [{ file: 'b.js', line: 9, ruleId: 'swallowed-error', severity: 'HIGH', title: 'catch' }],
+  });
+  const types = col.events.map((e) => e.type);
+  assert.ok(types.includes('bg.batch') && types.includes('metrics'));
+
+  const analysis = col.events.find((e) => e.type === 'bg.batch' && e.payload.category === 'analysis' && !e.payload.kind);
+  assert.strictEqual(analysis.payload.filesScanned, 12);
+  assert.strictEqual(analysis.payload.durationMs, 42);
+
+  const added = col.events.find((e) => e.payload.kind === 'finding-added');
+  assert.strictEqual(added.payload.ruleId, 'hardcoded-secret');
+  assert.strictEqual(added.payload.severity, 'CRITICAL'); // bus lowercases on ingest
+  const fixed = col.events.find((e) => e.payload.kind === 'finding-fixed');
+  assert.strictEqual(fixed.payload.file, 'b.js');
+
+  const metrics = col.events.find((e) => e.type === 'metrics');
+  assert.strictEqual(metrics.metrics.critical, 1); // CRITICAL + BLOCKER
+  assert.strictEqual(metrics.metrics.high, 2);
+  assert.strictEqual(metrics.metrics.filesScanned, 12);
+  assert.ok(Number.isFinite(metrics.metrics.rssMb) && metrics.metrics.rssMb > 0, 'rss heartbeat present');
+  await col.close();
+});
+
+test('close() emits session.close with a reason', async () => {
+  const col = await startCollector();
+  const a = createAdapter({ port: col.port });
+  await a.close('sigint');
+  const ev = col.events[col.events.length - 1];
+  assert.strictEqual(ev.type, 'session.close');
+  assert.strictEqual(ev.payload.reason, 'sigint');
+  await col.close();
+});
+
+test('ingest failures never reject the producer (dashboard down)', async () => {
+  const a = createAdapter({ port: 1 }); // nothing listening
+  // Should resolve quietly rather than throw.
+  await a.open();
+  await a.pass({ result: fakeResult(1), added: [], resolved: [] });
+  assert.ok(true);
+});
+
+test('healthProbe returns null when no observatory answers', async () => {
+  const h = await healthProbe(1);
+  assert.strictEqual(h, null);
+  assert.strictEqual(DEFAULT_PORT, 4780);
+});