fullstack-critic 1.0.0 → 1.0.3

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.3",
   "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');
 }