fullstack-critic 1.0.0

package/src/cli.js

@@ -0,0 +1,163 @@
+'use strict';
+/**
+ * Command router for the `critic` / `fullstack-critic` binary.
+ * Commands: review · watch · init · audit · help · version
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { analyze } = require('./analyzer');
+const { renderConsole, renderMarkdown } = require('./report');
+const { watch } = require('./watcher');
+const { init } = require('./init');
+const { analyzeDeps } = require('./deps');
+
+// 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
+const FAIL_LEVELS = { never: -1, info: 5, low: 4, medium: 3, high: 2, critical: 1, blocker: 0 };
+
+function parseArgs(argv) {
+  const args = { _: [] , flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { args._.push(...argv.slice(i + 1)); break; }
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      if (key.includes('=')) { const [k, v] = key.split('='); args.flags[k] = v; }
+      else if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) args.flags[key] = argv[++i];
+      else args.flags[key] = true;
+    } else if (a.startsWith('-') && a.length > 1) {
+      const key = a.slice(1);
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) args.flags[key] = argv[++i];
+      else args.flags[key] = true;
+    } else args._.push(a);
+  }
+  return args;
+}
+
+function targetOf(args) {
+  // _[0] is the subcommand; the optional path is _[1].
+  const t = args.flags.target || args._[1] || '.';
+  return path.resolve(t);
+}
+
+function exitCodeFor(result, failOn) {
+  const rank = FAIL_LEVELS[String(failOn || 'critical').toLowerCase()];
+  if (rank == null) return 0;
+  const order = ['BLOCKER', 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
+  for (let i = 0; i < order.length; i++) {
+    if (result.counts[order[i]] > 0) return i <= rank ? 1 : 0;
+  }
+  return 0;
+}
+
+function safeWrite(p, content, label) {
+  try { fs.writeFileSync(p, content); process.stdout.write(`${label} written to ${p}\n`); return true; }
+  catch (e) { process.stderr.write(`could not write ${label} to ${p}: ${e.code || e.message}\n`); return false; }
+}
+
+function cmdReview(args) {
+  const target = targetOf(args);
+  const result = analyze(target, { skipCode: !!args.flags['no-code'] });
+  if (args.flags.json) {
+    const p = typeof args.flags.json === 'string' ? args.flags.json : '.critic-review.json';
+    safeWrite(p, JSON.stringify(result, null, 2), 'JSON');
+  } else if (args.flags.quiet) {
+    // print nothing but the verdict line
+    process.stdout.write(`${result.counts.CRITICAL + result.counts.BLOCKER} blocking · ${result.counts.HIGH} high · ${result.findings.length} total\n`);
+  } else {
+    process.stdout.write(renderConsole(result) + '\n');
+  }
+  if (args.flags.md || args.flags.o) {
+    const p = args.flags.md || args.flags.o;
+    safeWrite(typeof p === 'string' ? p : '.critic-report.md', renderMarkdown(result), 'Report');
+  }
+  return exitCodeFor(result, args.flags['fail-on']);
+}
+
+function cmdWatch(args) {
+  const target = targetOf(args);
+  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,
+  });
+  process.on('SIGINT', () => { w.close(); process.stdout.write('\nstopped watching.\n'); process.exit(0); });
+  return 0;
+}
+
+function cmdInit(args) {
+  const target = path.resolve(args._[1] || '.');
+  init(target);
+  return 0;
+}
+
+function cmdAudit(args) {
+  const target = targetOf(args);
+  const { ecosystems } = analyzeDeps(target);
+  if (!ecosystems.length) { process.stdout.write('No recognised dependency manifests.\n'); return 0; }
+  for (const eco of ecosystems) {
+    const cmd = eco.auditCmd;
+    process.stdout.write(`\n=== ${eco.name} · ${cmd} ===\n`);
+    const r = spawnSafe(cmd, target);
+    if (r == null) { process.stdout.write(`  (skipped: \`${cmd.split(' ')[0]}\` not on PATH)\n`); continue; }
+    const out = (r.stdout || '') + (r.stderr || '');
+    process.stdout.write(abbrev(out, 4000) + '\n');
+    if (r.status != null) process.stdout.write(`  exit ${r.status}\n`);
+  }
+  return 0;
+}
+
+function spawnSafe(cmd, cwd) {
+  try {
+    const r = spawnSync(cmd, { cwd, shell: true, encoding: 'utf8', timeout: 60000 });
+    if (r.error) return null;
+    if (r.status === 1 && /is not recognized|command not found|not found/i.test((r.stderr || '') + (r.stdout || ''))) return null;
+    return r;
+  } catch { return null; }
+}
+function abbrev(s, n) { return s && s.length > n ? s.slice(0, n) + `\n… (${s.length - n} more chars)` : s; }
+
+function help() {
+  process.stdout.write(`
+Full-Stack Critic — universal engineering critic, runs anywhere, reviews 100% of resources.
+
+Usage:
+  critic review [path] [flags]     One-shot full review across all 12 dimensions
+  critic watch  [path] [flags]     Attach to an in-progress workflow; continuous feedback on changes
+  critic init   [path]             Attach the critic to any project (.critic/ + .critic-memory/ + PROJECT_REVIEW.md)
+  critic audit  [path]             Run each detected package manager's native audit (npm audit, pip-audit, govulncheck…)
+
+Flags:
+  --md <path>        Write the full markdown report (default in watch: .critic-report.md)
+  --json <path>      Emit machine-readable findings
+  --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)
+  --quiet            Print only the summary line
+
+Examples:
+  npx fullstack-critic review .
+  critic watch ./my-app --md CRITIC_REPORT.md
+  critic init && critic audit
+`);
+  return 0;
+}
+
+function run(argv) {
+  const args = parseArgs(argv);
+  const cmd = (args._[0] || 'help').toLowerCase();
+  switch (cmd) {
+    case 'review': return cmdReview(args);
+    case 'watch': return cmdWatch(args);
+    case 'init': return cmdInit(args);
+    case 'audit': return cmdAudit(args);
+    case 'version': case '--version': case '-v':
+      process.stdout.write(JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version + '\n'); return 0;
+    case 'help': case '--help': case undefined: return help();
+    default:
+      process.stderr.write(`Unknown command: ${cmd}\n`); return help() || 1;
+  }
+}
+
+module.exports = { run, parseArgs };

package/src/deps.js

@@ -0,0 +1,200 @@
+'use strict';
+/**
+ * Dependency and package-manifest analysis.
+ * Covers every mainstream ecosystem so "100% of resources — packages, dependencies"
+ * is actually inspected, not assumed. Findings carry a category: fix | optimize | delete | add.
+ */
+const fs = require('fs');
+const path = require('path');
+const { exists, readText } = require('./util');
+
+const ECOSYSTEMS = [
+  {
+    name: 'npm',
+    manifest: 'package.json',
+    locks: ['package-lock.json', 'npm-shrinkwrap.json'],
+    altLocks: { yarn: 'yarn.lock', pnpm: 'pnpm-lock.yaml', bun: 'bun.lockb' },
+    auditCmd: 'npm audit --omit=dev',
+    outdatedCmd: 'npm outdated',
+  },
+  { name: 'pip', manifest: 'requirements.txt', lockGlob: /^requirements.*\.(txt|lock)$/i, auditCmd: 'pip-audit', loose: true },
+  { name: 'poetry', manifest: 'pyproject.toml', locks: ['poetry.lock'], auditCmd: 'poetry show --outdated' },
+  { name: 'pipenv', manifest: 'Pipfile', locks: ['Pipfile.lock'], auditCmd: 'pipenv check' },
+  { name: 'go', manifest: 'go.mod', locks: ['go.sum'], auditCmd: 'govulncheck ./...' },
+  { name: 'cargo', manifest: 'Cargo.toml', locks: ['Cargo.lock'], auditCmd: 'cargo audit', bin: 'cargo' },
+  { name: 'composer', manifest: 'composer.json', locks: ['composer.lock'], auditCmd: 'composer audit' },
+  { name: 'bundler', manifest: 'Gemfile', locks: ['Gemfile.lock'], auditCmd: 'bundle audit' },
+  { name: 'maven', manifest: 'pom.xml', locks: [], auditCmd: 'mvn dependency:analyze', loose: true },
+  { name: 'gradle', manifest: 'build.gradle', locks: ['gradle.lockfile'], auditCmd: './gradlew dependencyUpdates', loose: true },
+];
+
+function parseJson(abs) {
+  try { return JSON.parse(readText(abs)); } catch { return null; }
+}
+
+function npmDeps(pkg) {
+  const out = [];
+  for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+    const map = pkg[section] || {};
+    for (const [name, range] of Object.entries(map)) {
+      out.push({ name, range, section });
+    }
+  }
+  return out;
+}
+
+/**
+ * Analyse dependency manifests present under root.
+ * Returns { ecosystems: [...], findings: [...] }.
+ */
+function analyzeDeps(root) {
+  const ecosystems = [];
+  const findings = [];
+  const F = (f) => findings.push(f);
+
+  for (const eco of ECOSYSTEMS) {
+    const manifestPath = path.join(root, eco.manifest);
+    if (!exists(manifestPath)) continue;
+
+    let declared = [];
+    let scripts = {};
+    let hasScriptsField = false;
+    if (eco.name === 'npm') {
+      const pkg = parseJson(manifestPath);
+      if (pkg) {
+        declared = npmDeps(pkg);
+        scripts = pkg.scripts || {};
+        hasScriptsField = Object.prototype.hasOwnProperty.call(pkg, 'scripts');
+      }
+    } else {
+      const text = readText(manifestPath) || '';
+      declared = countLoose(eco.name, text);
+    }
+
+    const lockPresent = (eco.locks || []).filter((l) => exists(path.join(root, l)));
+    const altPresent = eco.altLocks
+      ? Object.entries(eco.altLocks).filter(([, f]) => exists(path.join(root, f))).map(([mgr]) => mgr)
+      : [];
+    const hasLock = lockPresent.length > 0 || altPresent.length > 0;
+
+    ecosystems.push({
+      name: eco.name,
+      manifest: eco.manifest,
+      declaredCount: declared.length,
+      lock: lockPresent[0] || altPresent[0] || null,
+      auditCmd: eco.auditCmd,
+      outdatedCmd: eco.outdatedCmd || null,
+    });
+
+    // --- Findings -----------------------------------------------------------
+    if (declared.length > 0 && !hasLock && !eco.loose) {
+      F({
+        severity: 'HIGH', category: 'add', dimension: 'Infrastructure',
+        title: `${eco.name}: dependencies declared but no lock file committed`,
+        file: eco.manifest, line: 1,
+        problem: 'Without a lock file, installs are not reproducible across machines, CI, and prod.',
+        evidence: `${declared.length} declared dependencies, no ${eco.locks} present.`,
+        impact: 'Different installs produce different trees; a single transitive compromise propagates everywhere.',
+        fix: `Run the install once and commit the generated lock file (${eco.auditCmd ? `then \`${eco.auditCmd}\`` : ''}).`,
+        verify: `Fresh clone then install; confirm the lock file is present and tracked.`,
+      });
+    }
+
+    if (eco.name === 'npm') {
+      for (const d of declared) {
+        const unpinned = d.range === '*' || d.range === 'latest' || d.range === '';
+        const gitOrLocal = /^(git|file:|link:|workspace:)/.test(d.range);
+        if (unpinned) {
+          F({
+            severity: 'MEDIUM', category: 'fix', dimension: 'Infrastructure',
+            title: `Unpinned dependency "${d.name}" (range "${d.range || 'empty'}")`,
+            file: 'package.json', line: 1,
+            problem: 'A wildcard/latest range can pull a breaking or compromised version on any install.',
+            evidence: `"${d.name}": "${d.range}" in ${d.section}`,
+            impact: 'Silent behaviour change or supply-chain exposure at any time.',
+            fix: `Pin "${d.name}" to an exact or caret range of a reviewed version.`,
+            verify: 'npm ls ' + d.name,
+          });
+        } else if (gitOrLocal && d.section === 'dependencies') {
+          F({
+            severity: 'LOW', category: 'fix', dimension: 'Infrastructure',
+            title: `Production dependency "${d.name}" resolves to a non-registry source`,
+            file: 'package.json', line: 1,
+            problem: 'git/file/workspace deps in production bypass registry integrity checks.',
+            evidence: `"${d.name}": "${d.range}"`,
+            impact: 'Cannot be verified by registry audits; may break fresh installs.',
+            fix: 'Publish to a registry or vendor the code; avoid git/file refs in production deps.',
+            verify: 'npm ci on a clean checkout',
+          });
+        }
+      }
+      if (exists(path.join(root, 'package-lock.json')) && exists(path.join(root, 'yarn.lock'))) {
+        F({
+          severity: 'LOW', category: 'delete', dimension: 'Infrastructure',
+          title: 'Multiple package-manager lock files present',
+          file: '.', line: 1,
+          problem: 'Both npm and yarn locks exist; installs can diverge by manager.',
+          evidence: 'package-lock.json and yarn.lock coexist',
+          impact: 'Team/CI drift between resolution trees.',
+          fix: 'Standardise on one manager and delete the other lock.',
+          verify: 'Only one lock file remains.',
+        });
+      }
+    }
+  }
+
+  // Scripts completeness for npm projects.
+  const npkg = exists(path.join(root, 'package.json')) ? parseJson(path.join(root, 'package.json')) : null;
+  if (npkg && hasScriptGate(npkg)) {
+    const s = npkg.scripts || {};
+    const has = (re) => Object.keys(s).some((k) => re.test(k));
+    if (!has(/^test$/i)) {
+      F({ severity: 'MEDIUM', category: 'add', dimension: 'Testing', title: 'No "test" script defined', file: 'package.json', line: 1,
+        problem: 'CI and the critic cannot run tests.', evidence: 'scripts.test missing', impact: 'Regressions ship unverified.',
+        fix: 'Add a test runner and a "test" script.', verify: 'npm test' });
+    }
+    if (!has(/^(lint|lint:.*)$/i)) {
+      F({ severity: 'LOW', category: 'add', dimension: 'Code quality', title: 'No "lint" script defined', file: 'package.json', line: 1,
+        problem: 'No automated style/quality gate.', evidence: 'scripts.lint missing', impact: 'Style and simple-bug drift.',
+        fix: 'Add an ESLint/Ruff-equivalent lint script.', verify: 'npm run lint' });
+    }
+  }
+
+  return { ecosystems, findings };
+}
+
+function hasScriptGate(pkg) { return Object.prototype.hasOwnProperty.call(pkg, 'scripts'); }
+
+// Best-effort declared-dependency count for non-npm manifests.
+function countLoose(name, text) {
+  const lines = text.split(/\r?\n/);
+  let count = 0;
+  if (name === 'pip') {
+    count = lines.filter((l) => /^[A-Za-z0-9_.\-\[\]<>=!~]/.test(l.trim()) && !l.trim().startsWith('#') && /.*/.test(l) && l.trim()).length;
+  } else if (name === 'poetry' || name === 'pipenv') {
+    let inSec = false;
+    for (const l of lines) {
+      if (/^\s*\[.*dependencies.*\]/i.test(l)) { inSec = true; continue; }
+      if (/^\s*\[/.test(l)) { inSec = false; continue; }
+      if (inSec && /^\s*[A-Za-z0-9_.\-]+\s*=/.test(l)) count++;
+    }
+  } else if (name === 'go') {
+    let inReq = false;
+    for (const l of lines) {
+      if (/require\s*\(/.test(l)) { inReq = true; continue; }
+      if (inReq && /^\)/.test(l)) { inReq = false; continue; }
+      if (inReq && /\S+\s+v[\d.]/.test(l)) count++;
+      if (!inReq && /^require\s+\S/.test(l)) count++;
+    }
+  } else if (name === 'cargo' || name === 'composer') {
+    let inSec = false;
+    for (const l of lines) {
+      if (/^\s*\[dependencies\]/i.test(l)) { inSec = true; continue; }
+      if (/^\s*\[/.test(l)) { inSec = false; continue; }
+      if (inSec && /^\s*[A-Za-z0-9_.\-]+\s*=/.test(l)) count++;
+    }
+  }
+  return count;
+}
+
+module.exports = { analyzeDeps, ECOSYSTEMS };

package/src/index.js

@@ -0,0 +1,18 @@
+'use strict';
+/**
+ * Programmatic API so the critic can also be embedded in build scripts, test suites, or CI.
+ *   const critic = require('fullstack-critic');
+ *   const result = critic.analyze('./my-app');
+ *   require('fs').writeFileSync('report.md', critic.renderMarkdown(result));
+ */
+module.exports = {
+  analyze: require('./analyzer').analyze,
+  renderMarkdown: require('./report').renderMarkdown,
+  renderConsole: require('./report').renderConsole,
+  execSummary: require('./report').execSummary,
+  analyzeDeps: require('./deps').analyzeDeps,
+  watch: require('./watcher').watch,
+  init: require('./init').init,
+  DIMENSIONS: require('./analyzer').DIMENSIONS,
+  rules: require('./rules').LINE_RULES,
+};

package/src/init.js

@@ -0,0 +1,80 @@
+'use strict';
+/**
+ * Attach the critic to any project.
+ *  - copies the rubric/knowledge base into ./<project>/.critic/
+ *  - scaffolds ./.project>/.critic-memory/ from the memory templates (session memory)
+ *  - writes a fill-in PROJECT_REVIEW.md at the project root if none exists
+ * Read-only toward the project's own source — it only adds files under the critic's own folders.
+ */
+const fs = require('fs');
+const path = require('path');
+const { exists } = require('./util');
+
+const PKG_ROOT = path.join(__dirname, '..');
+const RUBRIC_FILES = ['CRITIC.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md', 'PROJECT_REVIEW.md'];
+const RUBRIC_DIRS = ['layers', 'memory', 'agent', 'prompts'];
+
+function copyFile(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(src, dest) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  fs.mkdirSync(dest, { recursive: true });
+  for (const e of entries) {
+    const s = path.join(src, e.name);
+    const d = path.join(dest, e.name);
+    if (e.isDirectory()) copyDir(s, d); else copyFile(s, d);
+  }
+}
+
+function init(target, opts = {}) {
+  target = path.resolve(target || '.');
+  const created = [];
+  const criticDir = path.join(target, '.critic');
+
+  fs.mkdirSync(criticDir, { recursive: true });
+  for (const f of RUBRIC_FILES) {
+    const src = path.join(PKG_ROOT, f);
+    if (exists(src)) { copyFile(src, path.join(criticDir, f)); created.push(path.relative(target, path.join(criticDir, f))); }
+  }
+  for (const d of RUBRIC_DIRS) {
+    const src = path.join(PKG_ROOT, d);
+    if (exists(src)) { copyDir(src, path.join(criticDir, d)); }
+  }
+
+  // Session memory scaffold from templates.
+  const memDir = path.join(target, '.critic-memory');
+  const tmplDir = path.join(PKG_ROOT, 'memory', 'templates');
+  if (!exists(memDir) && exists(tmplDir)) {
+    fs.mkdirSync(memDir, { recursive: true });
+    for (const t of fs.readdirSync(tmplDir)) {
+      if (!t.endsWith('.md')) continue;
+      const dest = path.join(memDir, t);
+      if (!exists(dest)) { copyFile(path.join(tmplDir, t), dest); created.push(path.relative(target, dest)); }
+    }
+  }
+
+  // Root PROJECT_REVIEW.md (only if the project has none).
+  const rootPR = path.join(target, 'PROJECT_REVIEW.md');
+  if (!exists(rootPR) && exists(path.join(PKG_ROOT, 'PROJECT_REVIEW.md'))) {
+    copyFile(path.join(PKG_ROOT, 'PROJECT_REVIEW.md'), rootPR);
+    created.push('PROJECT_REVIEW.md');
+  }
+
+  // .gitignore hint so the attach is clean.
+  if (!opts.skipGitignoreHint) {
+    process.stdout.write(
+      `\nAttached critic to ${target}\n` +
+      `  - rubric copied into ./.critic/\n` +
+      `  - memory scaffolded into ./.critic-memory/ (${created.length} file(s) written)\n\n` +
+      `Next: add ".critic/" and ".critic-memory/" to .gitignore (or commit them), fill PROJECT_REVIEW.md,\n` +
+      `then tell your AI: "Read .critic/CRITIC.md and do a full review of this project."\n` +
+      `Or run continuous checks now:  critic watch ${target === process.cwd() ? '.' : ''}\n`
+    );
+  }
+  return { target, created };
+}
+
+module.exports = { init };

package/src/report.js

@@ -0,0 +1,171 @@
+'use strict';
+/**
+ * Renders the analyzer result into (a) a console summary and (b) a full
+ * markdown report whose action plan is grouped by FIX / OPTIMIZE / DELETE / ADD.
+ */
+const { DIMENSIONS } = require('./analyzer');
+
+const SEV_ORDER = ['BLOCKER', 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'INFO'];
+const CATEGORY_LABEL = {
+  fix: 'FIX — correctness & security defects',
+  optimize: 'OPTIMIZE — performance, size & structure',
+  delete: 'DELETE — dead code, debug, duplicates',
+  add: 'ADD — missing tests, config & docs',
+};
+
+function statusFor(dimName, findings) {
+  const ds = findings.filter((f) => f.dimension === dimName);
+  if (!ds.length) return { status: 'REVIEW', note: 'no automated signal — AI/manual pass required' };
+  const worst = SEV_ORDER.find((s) => ds.some((f) => f.severity === s)) || 'INFO';
+  const status = (worst === 'BLOCKER' || worst === 'CRITICAL' || worst === 'HIGH') ? 'FAIL'
+    : (worst === 'MEDIUM' || worst === 'LOW') ? 'WARN' : 'INFO';
+  return { status, note: `${ds.length} finding(s), worst ${worst}` };
+}
+
+function execSummary(result) {
+  const { counts } = result;
+  const blocking = counts.BLOCKER + counts.CRITICAL;
+  if (blocking > 0) return 'Not ready — BLOCKER/CRITICAL findings present.';
+  if (counts.HIGH > 0) return 'Ready with required fixes — HIGH findings must be addressed before ship.';
+  if (counts.MEDIUM > 0) return 'Ready — resolve MEDIUM items on the normal cycle.';
+  return 'Clean — no findings above LOW.';
+}
+
+function renderConsole(result) {
+  const { counts, categoryCounts, coverage } = result;
+  const lines = [];
+  lines.push('');
+  lines.push(`Full-Stack Critic — ${result.coverage ? relName(result.meta.root) : ''}`);
+  lines.push('─'.repeat(64));
+  lines.push(
+    `Scanned ${coverage.filesScanned} files (${coverage.totalLines.toLocaleString()} lines) · ` +
+    `${coverage.filesSkipped} skipped (counted) · ${result.dependencies.length} package ecosystem(s)`
+  );
+  lines.push('');
+  const sevRow = SEV_ORDER.filter((s) => counts[s]).map((s) => `${counts[s]} ${s}`).join('  ·  ');
+  lines.push('Findings: ' + (sevRow || 'none'));
+  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) {
+    lines.push('');
+    lines.push('Top blocking findings:');
+    for (const f of top) lines.push(`  [${f.severity}] ${f.file}:${f.line}  ${f.title}`);
+  }
+  return lines.join('\n');
+}
+
+function renderMarkdown(result) {
+  const { findings, counts, categoryCounts, coverage, dependencies } = result;
+  const out = [];
+  out.push(`# Engineering Review — ${relName(result.meta.root)}`);
+  out.push('');
+  out.push(`_Generated by Full-Stack Critic v${result.meta.cliVersion} · scanned ${coverage.filesScanned} files / ${coverage.totalLines.toLocaleString()} lines · ${coverage.filesSkipped} resources counted-but-skipped · ${result.meta.durationMs} ms._`);
+  out.push('');
+  out.push('## Executive Summary');
+  out.push('');
+  out.push('| Dimension | Status | Note |');
+  out.push('|-----------|--------|------|');
+  for (const d of DIMENSIONS) {
+    const s = statusFor(d, findings);
+    out.push(`| ${d} | ${s.status} | ${s.note} |`);
+  }
+  out.push(`| **Overall** | **${verdictStatus(result)}** | ${execSummary(result)} |`);
+  out.push('');
+
+  // Coverage proof — nothing skipped silently.
+  out.push('## Coverage (100% of resources, explicitly accounted)');
+  out.push('');
+  out.push(`- Files line-scanned: **${coverage.filesScanned}** · total lines: **${coverage.totalLines.toLocaleString()}**`);
+  out.push(`- Resources counted but not line-scanned: **${coverage.filesSkipped}** (dependencies, build output, VCS, binaries, oversized — see below)`);
+  if (dependencies.length) {
+    out.push('- Package ecosystems analysed:');
+    for (const e of dependencies) {
+      out.push(`  - \`${e.name}\` via \`${e.manifest}\` — ${e.declaredCount} declared, lock: ${e.lock ? '`' + e.lock + '`' : '**MISSING**'}, audit: \`${e.auditCmd}\``);
+    }
+  }
+  if (coverage.skipped && coverage.skipped.length) {
+    out.push('- Skipped (sample, up to 50):');
+    for (const s of coverage.skipped.slice(0, 50)) out.push(`  - \`${s.rel}\` — ${s.reason}`);
+  }
+  const skippedDims = coverage.dimensions.filter((d) => !d.touched).map((d) => d.dimension);
+  if (skippedDims.length) {
+    out.push(`- Dimensions with no automated signal (require the AI/manual pass from \`CRITIC.md\`): ${skippedDims.join(', ')}`);
+  }
+  out.push('');
+
+  // Detailed findings grouped by dimension.
+  out.push('## Detailed Findings');
+  out.push('');
+  if (!findings.length) {
+    out.push('No automated findings. Run the AI review pass (`critic init` then “Review this project”) for the qualitative dimensions.');
+  }
+  for (const sev of SEV_ORDER) {
+    const group = findings.filter((f) => f.severity === sev);
+    if (!group.length) continue;
+    out.push(`### ${sev} (${group.length})`);
+    out.push('');
+    for (const f of group) {
+      out.push(`#### ${f.category.toUpperCase()} — ${f.title}`);
+      out.push('');
+      out.push('| Field | Detail |');
+      out.push('|-------|--------|');
+      out.push(`| **Location** | \`${f.file}:${f.line}\` |`);
+      out.push(`| **Dimension** | ${f.dimension} |`);
+      out.push(`| **Confirmed?** | ${f.confirmed === true ? 'confirmed (code seen)' : (f.confirmed === 'suspected' ? 'suspected (pattern-inferred)' : String(f.confirmed))} |`);
+      out.push(`| **Problem** | ${f.problem} |`);
+      out.push(`| **Evidence** | \`${escapeCell(f.evidence)}\` |`);
+      out.push(`| **Impact** | ${f.impact} |`);
+      out.push(`| **Fix** | ${f.fix} |`);
+      out.push(`| **Verify** | ${f.verify} |`);
+      out.push('');
+    }
+  }
+
+  // Action plan — the "what to fix / optimize / delete / add" deliverable.
+  out.push('## Prioritised Action Plan');
+  out.push('');
+  for (const cat of ['fix', 'optimize', 'delete', 'add']) {
+    const group = findings.filter((f) => f.category === cat);
+    if (!group.length) continue;
+    out.push(`### ${CATEGORY_LABEL[cat]} — ${group.length} item(s)`);
+    out.push('');
+    out.push('| # | Sev | Where | Action | Verify |');
+    out.push('|---|-----|-------|--------|--------|');
+    group.forEach((f, i) => {
+      out.push(`| ${i + 1} | ${f.severity} | \`${f.file}:${f.line}\` | ${escapeCell(f.title)} → ${escapeCell(f.fix)} | ${escapeCell(f.verify)} |`);
+    });
+    out.push('');
+  }
+
+  out.push('## Final Verdict');
+  out.push('');
+  out.push(verdictLine(result));
+  out.push('');
+  out.push('_REVIEW is read-only. To apply a category on request, run the AI in FIX mode against a specific finding block above._');
+  return out.join('\n');
+}
+
+function verdictStatus(result) {
+  const { counts } = result;
+  if (counts.BLOCKER + counts.CRITICAL > 0) return 'FAIL';
+  if (counts.HIGH > 0) return 'WARN';
+  return 'PASS';
+}
+function verdictLine(result) {
+  const { counts } = result;
+  if (counts.BLOCKER + counts.CRITICAL > 0) return '**Not ready for production** — clear BLOCKER/CRITICAL findings above (mostly security/correctness).';
+  if (counts.HIGH > 0) return '**Ready with required fixes** — resolve the HIGH findings before shipping.';
+  if (counts.MEDIUM > 0) return '**Ready** — MEDIUM/LOW items scheduled as normal.';
+  return '**Clean** — no significant automated findings; run the AI qualitative pass for full 12-dimension coverage.';
+}
+function escapeCell(s) {
+  return String(s == null ? '' : s).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+function relName(root) {
+  const parts = String(root).replace(/[\\/]+$/, '').split(/[\\/]/);
+  return parts[parts.length - 1] || root;
+}
+
+module.exports = { renderConsole, renderMarkdown, execSummary };