total-recall-brain 3.40.0 → 3.40.2

package/scaffold/.agent/skills/total-recall/plugins/code-quality/core/config.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "code-quality repo configuration",
+  "description": "Repo-layer contract for the code-quality skill. Maintained with `total-recall skill config code-quality …`; config.json is its projection.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "toolchain", "checks"],
+  "properties": {
+    "version": { "const": 3 },
+    "toolchain": { "type": "string", "minLength": 1, "description": "Primary toolchain label shown in reports (javascript, typescript, python, …)" },
+    "repoDescription": { "type": "string", "description": "What quality means in this repo" },
+    "repoRoot": { "type": "string", "description": "Override the repo root (default: three levels above the skill)" },
+    "remoteNode": { "type": "string", "minLength": 1, "description": "Mesh node that runs the gates for the pre-push hook" },
+    "remoteRepo": { "type": "string", "minLength": 1, "description": "Absolute path of the source snapshot on that node (see `code-quality snapshot`)" },
+    "remotePath": { "type": "string", "description": "PATH prefix to use on that node, e.g. /opt/homebrew/bin" },
+    "globalLock": { "type": "boolean", "default": true, "description": "Take the machine-wide lock so only one check runs per host" },
+    "timeoutSeconds": { "type": "integer", "minimum": 1, "description": "Default per-check timeout" },
+    "memory": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "maxOldSpaceMb": { "type": "integer", "minimum": 256 } }
+    },
+    "lock": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "staleAfterMinutes": { "type": "integer", "minimum": 1 } }
+    },
+    "env": {
+      "type": "object",
+      "description": "Environment for every command check; ${REPO_ROOT} and ${env:NAME} expand",
+      "additionalProperties": { "type": "string" }
+    },
+    "sourceExtensions": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^\\.[A-Za-z0-9]+$" }
+    },
+    "checks": {
+      "type": "array",
+      "minItems": 1,
+      "x-collection": "gate",
+      "x-key": "id",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+          "tier": { "type": "string", "enum": ["fast", "full", "remote"], "default": "fast" },
+          "kind": { "type": "string", "enum": ["command", "grep-forbid"] },
+          "description": { "type": "string" },
+          "cmd": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 },
+            "x-command": true
+          },
+          "cwd": { "type": "string" },
+          "env": { "type": "object", "additionalProperties": { "type": "string" } },
+          "parser": { "type": "string", "enum": ["tsc", "eslint-stylish", "eslint-compact", "biome", "flake8", "mypy", "black", "generic"] },
+          "timeoutSeconds": { "type": "integer", "minimum": 1 },
+          "remoteHint": { "type": "string" },
+          "extensions": { "type": "array", "items": { "type": "string", "pattern": "^\\.[A-Za-z0-9]+$" } },
+          "paths": { "type": "array", "items": { "type": "string" } },
+          "ignorePaths": { "type": "array", "items": { "type": "string" } },
+          "patterns": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["pattern"],
+              "properties": {
+                "pattern": { "type": "string", "minLength": 1 },
+                "flags": { "type": "string", "pattern": "^[dgimsuvy]*$" },
+                "code": { "type": "string" },
+                "message": { "type": "string" }
+              }
+            }
+          },
+          "scope": { "type": "string", "enum": ["all", "changed"] },
+          "baseline": { "type": "string" },
+          "fallbackViolationBaseline": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/scaffold/.agent/skills/total-recall/plugins/code-quality/core/detect.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * code-quality / core/detect.mjs — probe a repo and propose a repo config.
+ *
+ * A bootstrap, not the source of truth. It reports what the repo actually has;
+ * the repo's real gate list (conformance suites, contract tests, grep gates for
+ * its own invariants) is repo knowledge added afterwards through the CLI:
+ *
+ *   total-recall skill config code-quality detect            # show the proposal
+ *   total-recall skill config code-quality detect --apply    # record it
+ *   total-recall skill config code-quality gate add id=… tier=fast cmd='["npm","test"]'
+ *
+ * Run directly (`node detect.mjs`) it only prints facts and the proposal.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function detectFacts(repoRoot) {
+  const has = (p) => existsSync(path.join(repoRoot, p));
+  const readText = (p) => { try { return readFileSync(path.join(repoRoot, p), 'utf8'); } catch { return ''; } };
+  const readJson = (p) => { try { return JSON.parse(readText(p)); } catch { return null; } };
+  const pkg = readJson('package.json');
+  const scripts = pkg?.scripts || {};
+  const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}) };
+  return {
+    scripts,
+    packageJson: !!pkg,
+    packageManager: has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : pkg ? 'npm' : null,
+    workspace: has('pnpm-workspace.yaml') || !!pkg?.workspaces,
+    typescript: !!deps.typescript || has('tsconfig.json'),
+    tsProjectRefs: readJson('tsconfig.json')?.references?.length || 0,
+    eslint: !!deps.eslint || ['.eslintrc', '.eslintrc.json', '.eslintrc.cjs', 'eslint.config.js', 'eslint.config.mjs'].some(has),
+    biome: !!deps['@biomejs/biome'] || has('biome.json') || has('biome.jsonc'),
+    python: has('requirements.txt') || has('pyproject.toml') || has('setup.py'),
+    venvPython: has('.venv/bin/python'),
+    flake8: has('.flake8') || has('setup.cfg') || has('tox.ini'),
+    mypy: has('mypy.ini') || has('.mypy_cache'),
+    black: /\[tool\.black\]/.test(readText('pyproject.toml')),
+    ssssScripts: Object.keys(scripts).filter((k) => k.startsWith('ssss')),
+  };
+}
+
+/** Propose a config satisfying core/config.schema.json. */
+export function detect({ repoRoot }) {
+  const facts = detectFacts(repoRoot);
+  const { scripts, packageManager: pm } = facts;
+  const run = (script) => (pm === 'pnpm' ? ['pnpm', 'run', script] : pm === 'yarn' ? ['yarn', script] : ['npm', 'run', script]);
+  const python = facts.venvPython ? '.venv/bin/python' : 'python3';
+  const checks = [];
+
+  if (facts.typescript && scripts.typecheck) {
+    checks.push({ id: 'types', tier: 'fast', cmd: run('typecheck'), parser: 'tsc' });
+  } else if (facts.typescript) {
+    checks.push({ id: 'types', tier: 'fast', cmd: ['npx', 'tsc', facts.tsProjectRefs > 0 ? '--build' : '--noEmit', '--pretty', 'false'], parser: 'tsc' });
+  }
+  if (facts.biome && scripts.lint) checks.push({ id: 'lint', tier: 'fast', cmd: run('lint'), parser: 'generic' });
+  else if (facts.eslint && scripts.lint) checks.push({ id: 'lint', tier: 'fast', cmd: run('lint'), parser: 'eslint-stylish' });
+  if (facts.flake8) checks.push({ id: 'flake8', tier: 'fast', cmd: [python, '-m', 'flake8', '.'], parser: 'flake8' });
+  if (facts.black) checks.push({ id: 'black-check', tier: 'fast', cmd: [python, '-m', 'black', '--check', '.'], parser: 'black' });
+  if (facts.mypy) checks.push({ id: 'mypy', tier: 'fast', cmd: [python, '-m', 'mypy', '.'], parser: 'mypy' });
+  for (const s of facts.ssssScripts) {
+    checks.push({ id: s.replace(/^ssss:/, 'ssss-').replace(/[^a-z0-9-]/g, '-'), tier: s.includes('validate') ? 'fast' : 'full', cmd: run(s), parser: 'generic' });
+  }
+  if (scripts.test) checks.push({ id: 'test', tier: 'full', cmd: run('test'), parser: 'generic' });
+
+  return {
+    version: 3,
+    toolchain: facts.python && !facts.typescript ? 'python' : facts.typescript ? 'typescript' : 'javascript',
+    globalLock: true,
+    lock: { staleAfterMinutes: 45 },
+    sourceExtensions: facts.python ? ['.py'] : ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+    checks,
+  };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+  const { scripts, ...facts } = detectFacts(repoRoot);
+  console.log(`\n code-quality detect — ${repoRoot}\n`);
+  for (const [k, v] of Object.entries(facts)) {
+    const val = Array.isArray(v) ? (v.length ? v.join(', ') : '—') : v === true ? 'yes' : v === false ? 'no' : (v ?? '—');
+    console.log(`  ${k.padEnd(16)} ${val}`);
+  }
+  console.log('\n── proposed config ──');
+  console.log(JSON.stringify(detect({ repoRoot }), null, 2));
+  console.log('\nNothing written. Record it with: total-recall skill config code-quality detect --apply');
+}

package/scaffold/.agent/skills/total-recall/plugins/code-quality/core/report-data.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * code-quality / report-data.mjs — the data adapter behind the report UI.
+ *
+ * Reads reports/latest.json exactly as check.mjs wrote it and returns a view
+ * with an honest status. It never runs a gate and never invents a number: every
+ * count comes from the report file, and a missing, unreadable, stale or
+ * partial report can never produce status "clean".
+ *
+ *   node report-data.mjs            print the view as JSON (exit 0 if clean, 1 otherwise)
+ *
+ * Status, most severe first:
+ *   missing         no report file
+ *   unreadable      report file is not valid JSON or has an unknown shape
+ *   infrastructure  a gate failed to spawn or timed out; results are incomplete
+ *   unparsed-failure a gate exited non-zero with no parseable findings
+ *   failed          findings or a failing gate
+ *   zero-scope      a grep gate scanned zero files, or nothing ran
+ *   stale           source changed after the run started, or HEAD moved
+ *   unknown-freshness git could not be read
+ *   partial         clean, but higher-tier gates were skipped
+ *   clean           every gate ran, nothing changed since
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SOURCE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.vue', '.svelte']);
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 20_000 });
+}
+
+/** Returns { head, changed } or null when git cannot be read. */
+function freshness(report) {
+  try {
+    const head = git(report.repoRoot, ['rev-parse', 'HEAD']).trim();
+    const startedMs = Date.parse(report.startedAt);
+    const changed = [];
+    for (const rel of git(report.repoRoot, ['ls-files', '-z']).split('\0')) {
+      if (!rel || !SOURCE_EXTS.has(path.extname(rel))) continue;
+      try {
+        if (statSync(path.join(report.repoRoot, rel)).mtimeMs > startedMs) changed.push(rel);
+      } catch { /* deleted since the run */ }
+    }
+    return { head, changed };
+  } catch {
+    return null;
+  }
+}
+
+export function buildReportView(reportFile, { now = Date.now(), inspectGit = true } = {}) {
+  const base = { reportFile, status: 'missing', reasons: [] };
+  if (!existsSync(reportFile)) {
+    return { ...base, reasons: ['No report file. Run code-quality-check, then reload.'] };
+  }
+  let report;
+  try {
+    report = JSON.parse(readFileSync(reportFile, 'utf8'));
+  } catch (err) {
+    return { ...base, status: 'unreadable', reasons: [`Report is not valid JSON: ${err.message}`] };
+  }
+  if (!report || !Array.isArray(report.checks) || !Array.isArray(report.ranChecks) || !report.startedAt) {
+    return { ...base, status: 'unreadable', reasons: ['Report does not have the code-quality schema (checks, ranChecks, startedAt).'] };
+  }
+
+  const findings = Array.isArray(report.findings) ? report.findings : [];
+  const hard = findings.filter((f) => f.severity !== 'warning' && f.severity !== 'info');
+  const skipped = Array.isArray(report.skippedChecks) ? report.skippedChecks : [];
+  const gates = report.checks.map((c) => ({
+    id: c.id,
+    ok: Boolean(c.ok),
+    exitCode: c.exitCode ?? null,
+    durationMs: c.durationMs ?? null,
+    scanned: typeof c.scanned === 'number' ? c.scanned : null,
+    spawnError: c.spawnError || null,
+    timedOut: Boolean(c.timedOut),
+    findings: findings.filter((f) => f.check === c.id).length,
+  }));
+  for (const s of skipped) gates.push({ id: s.id, skipped: true, tier: s.tier });
+
+  const infra = report.checks.filter((c) => c.spawnError || c.timedOut);
+  const unparsed = report.checks.filter(
+    (c) => !c.ok && !c.spawnError && !c.timedOut && !findings.some((f) => f.check === c.id)
+  );
+  const zeroScope = report.checks.filter((c) => c.scanned === 0);
+  const fresh = inspectGit ? freshness(report) : null;
+  const headMoved = Boolean(fresh && report.gitHead && fresh.head !== report.gitHead);
+
+  const reasons = [];
+  let status = 'clean';
+  const set = (s, why) => { if (status === 'clean' || SEVERITY.indexOf(s) < SEVERITY.indexOf(status)) status = s; reasons.push(why); };
+  const SEVERITY = ['infrastructure', 'unparsed-failure', 'failed', 'zero-scope', 'stale', 'unknown-freshness', 'partial', 'clean'];
+
+  if (infra.length) set('infrastructure', `${infra.map((c) => c.id).join(', ')}: spawn failure or timeout; results are incomplete`);
+  if (unparsed.length) set('unparsed-failure', `${unparsed.map((c) => `${c.id} (exit ${c.exitCode})`).join(', ')}: failed without parseable findings`);
+  if (hard.length || report.checks.some((c) => !c.ok)) {
+    if (!infra.length && !unparsed.length) set('failed', `${hard.length} blocking finding(s)`);
+  }
+  if (report.ranChecks.length === 0) set('zero-scope', 'No gates ran');
+  if (zeroScope.length) set('zero-scope', `${zeroScope.map((c) => c.id).join(', ')}: scanned 0 files`);
+  if (fresh === null && inspectGit) set('unknown-freshness', 'git could not be read; cannot tell whether this report matches the tree');
+  else if (fresh && (fresh.changed.length || headMoved)) {
+    set('stale', headMoved
+      ? `HEAD moved from ${String(report.gitHead).slice(0, 8)} to ${fresh.head.slice(0, 8)}`
+      : `${fresh.changed.length} source file(s) changed after the run started`);
+  }
+  if (skipped.length) set('partial', `Not run (tier ${report.tier}): ${skipped.map((s) => `${s.id}(${s.tier})`).join(', ')}`);
+
+  return {
+    reportFile,
+    status,
+    reasons,
+    clean: status === 'clean',
+    toolchain: report.toolchain,
+    repoRoot: report.repoRoot,
+    tier: report.tier,
+    gitHead: report.gitHead ?? null,
+    currentHead: fresh?.head ?? null,
+    startedAt: report.startedAt,
+    finishedAt: report.finishedAt ?? null,
+    ageMs: report.finishedAt ? Math.max(0, now - Date.parse(report.finishedAt)) : null,
+    durationMs: report.durationMs ?? null,
+    sourceFileCount: report.sourceFileCount ?? null,
+    ranChecks: report.ranChecks,
+    skippedChecks: skipped,
+    gates,
+    totalFindings: report.totalFindings ?? findings.length,
+    blockingFindings: hard.length,
+    changedSinceRun: fresh ? fresh.changed : null,
+    findings: findings.slice(0, 200),
+    findingsTruncated: findings.length > 200,
+  };
+}
+
+export function defaultReportFile() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'reports', 'latest.json');
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const view = buildReportView(process.argv[2] || defaultReportFile());
+  console.log(JSON.stringify(view, null, 2));
+  process.exitCode = view.clean ? 0 : 1;
+}

package/scaffold/.agent/skills/total-recall/plugins/code-quality/core/report.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+/**
+ * code-quality / report.mjs — read the last check report and pick the next work.
+ *
+ * This never runs a checker and never spawns anything. It reads
+ * reports/latest.json, tells you whether that report still describes your
+ * working tree, and orders the remaining findings so you know what to fix next.
+ *
+ * Views:
+ *   report.mjs                 worst files first (default)
+ *   report.mjs worst <skip>    page deeper into the worst-files list
+ *   report.mjs type            group by error code
+ *   report.mjs file <pattern>  everything matching one path
+ *   report.mjs count           totals per code and per check
+ *   report.mjs raw <checkId>   raw tool output for one check
+ *   report.mjs json            machine-readable view with honest status (feeds the UI)
+ */
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { stateDir } from './state.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SKILL_DIR = stateDir();
+const REPORT_JSON = path.join(SKILL_DIR, 'reports', 'latest.json');
+const REPORT_TXT = path.join(SKILL_DIR, 'reports', 'latest.txt');
+const CHECK_CMD = `node ${path.relative(process.cwd(), path.join(__dirname, 'check.mjs')) || 'check.mjs'}`;
+
+const [mode = 'worst', arg] = process.argv.slice(2);
+const MAX_SHOWN = 150;
+
+// `json` is the data feed for the plugin's report UI: the same report, with an
+// honest status, as machine-readable JSON. Exit 0 only when status is clean.
+if (mode === 'json') {
+  const { buildReportView } = await import('./report-data.mjs');
+  const view = buildReportView(REPORT_JSON);
+  console.log(JSON.stringify(view, null, 2));
+  process.exit(view.clean ? 0 : 1);
+}
+
+if (!existsSync(REPORT_JSON)) {
+  console.log(' No report yet.\n');
+  console.log('Run a check as a BACKGROUND job, then come back:');
+  console.log(`   ${CHECK_CMD}`);
+  process.exit(0);
+}
+
+const report = JSON.parse(readFileSync(REPORT_JSON, 'utf8'));
+const startedMs = Date.parse(report.startedAt);
+
+// ─── Staleness: which files changed after the run started? ────────────────────
+
+function changedSinceRun() {
+  let files = [];
+  try {
+    const out = execFileSync('git', ['ls-files', '-z'], {
+      cwd: report.repoRoot, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 20_000
+    });
+    const exts = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.vue', '.svelte']);
+    files = out.split('\0').filter((f) => f && exts.has(path.extname(f)));
+  } catch {
+    return null; // cannot determine — say so rather than implying freshness
+  }
+  const changed = [];
+  for (const rel of files) {
+    try {
+      if (statSync(path.join(report.repoRoot, rel)).mtimeMs > startedMs) changed.push(rel);
+    } catch { /* deleted since */ }
+  }
+  return changed;
+}
+
+const changed = changedSinceRun();
+const ageMin = Math.round((Date.now() - Date.parse(report.finishedAt)) / 60000);
+
+// ─── Header ───────────────────────────────────────────────────────────────────
+
+// Errors block a push; warnings and infos are reported but do not. Showing the
+// split keeps "17 findings" from reading as "17 things I must fix now".
+const sevCount = (report.findings || []).reduce((m, f) => {
+  const k = f.severity === 'warning' || f.severity === 'info' ? f.severity : 'error';
+  m[k] = (m[k] || 0) + 1;
+  return m;
+}, {});
+const sevLabel = ['error', 'warning', 'info']
+  .filter((k) => sevCount[k])
+  .map((k) => `${sevCount[k]} ${k}`)
+  .join(', ');
+console.log(
+  `\n code-quality — ${report.toolchain} — ${report.totalFindings} finding(s)${sevLabel ? ` (${sevLabel})` : ''}`
+);
+console.log(`   ran ${report.ranChecks.join(', ')} at tier=${report.tier} in ${(report.durationMs / 1000).toFixed(1)}s, ${ageMin}min ago`);
+
+if (report.skippedChecks?.length) {
+  console.log(`     NOT run: ${report.skippedChecks.map((c) => `${c.id}(${c.tier})`).join(', ')} — this is partial coverage.`);
+}
+if (report.infrastructureFailure) {
+  const bad = report.checks.filter((c) => c.spawnError || c.timedOut);
+  console.log(`    INFRASTRUCTURE FAILURE — findings below are incomplete:`);
+  for (const c of bad) console.log(`      ${c.id}: ${c.spawnError ? `spawn failed (${c.spawnError})` : 'timed out'}`);
+}
+
+// A gate that exited non-zero but produced no parsed findings means the tool
+// reported a problem in a format the parser did not understand. Silently
+// showing "0 findings" there would be a false clean bill of health.
+const opaque = (report.checks || []).filter(
+  (c) => !c.ok && !c.spawnError && !c.timedOut && !(report.findings || []).some((f) => f.check === c.id)
+);
+if (opaque.length) {
+  console.log(`     FAILED WITHOUT PARSEABLE FINDINGS — the tool objected, the parser did not understand it:`);
+  for (const c of opaque) {
+    console.log(`      ${c.id} (exit ${c.exitCode}) → inspect with: report.mjs raw ${c.id}`);
+  }
+}
+
+if (changed === null) {
+  console.log(`    Could not read git — cannot tell whether this report matches your tree.`);
+} else if (changed.length === 0) {
+  console.log(`    FRESH — no tracked source file has changed since this run started.`);
+} else {
+  console.log(`    STALE for ${changed.length} file(s) edited after the run started:`);
+  for (const f of changed.slice(0, 8)) console.log(`      ${f}`);
+  if (changed.length > 8) console.log(`      … and ${changed.length - 8} more`);
+  console.log(`   Findings in those files may already be fixed. Re-run: ${CHECK_CMD}`);
+}
+console.log('');
+
+// ─── Views ────────────────────────────────────────────────────────────────────
+
+const findings = report.findings || [];
+const byFile = () => {
+  const m = new Map();
+  for (const f of findings) {
+    if (!m.has(f.file)) m.set(f.file, []);
+    m.get(f.file).push(f);
+  }
+  return m;
+};
+const fmt = (f) => `  ${f.file}:${f.line}:${f.col}  ${f.code}  ${f.message}${f.snippet ? `\n      ↳ ${f.snippet}` : ''}`;
+const staleMark = (file) => (changed?.includes(file) ? ' ' : '');
+
+// `raw` reads the stored tool output, not the parsed findings, so it must be
+// reachable when there are zero findings — that is precisely the "failed
+// without parseable findings" case the header just told you to inspect.
+if (mode === 'raw') {
+  if (!existsSync(REPORT_TXT)) { console.error('No raw output stored.'); process.exit(1); }
+  const raw = readFileSync(REPORT_TXT, 'utf8');
+  if (!arg) { console.log(raw.slice(0, 20000)); process.exit(0); }
+  const section = raw.split(/^# /m).find((s) => s.startsWith(arg));
+  console.log(section ? `# ${section}`.slice(0, 40000) : `No raw section for check "${arg}".`);
+  process.exit(section ? 0 : 1);
+}
+
+if (findings.length === 0) {
+  console.log(' No findings.');
+  process.exit(0);
+}
+
+switch (mode) {
+  case 'count': {
+    const codes = {};
+    const checks = {};
+    for (const f of findings) {
+      codes[f.code] = (codes[f.code] || 0) + 1;
+      checks[f.check] = (checks[f.check] || 0) + 1;
+    }
+    console.log(`── by check ──`);
+    for (const [k, n] of Object.entries(checks).sort((a, b) => b[1] - a[1])) console.log(`  ${String(n).padStart(5)}  ${k}`);
+    console.log(`\n── by code ──`);
+    for (const [k, n] of Object.entries(codes).sort((a, b) => b[1] - a[1])) console.log(`  ${String(n).padStart(5)}  ${k}`);
+    break;
+  }
+  case 'type': {
+    const codes = {};
+    for (const f of findings) (codes[f.code] ||= []).push(f);
+    for (const [code, list] of Object.entries(codes).sort((a, b) => b[1].length - a[1].length)) {
+      console.log(`\n ${code} — ${list.length}`);
+      for (const f of list.slice(0, 6)) console.log(fmt(f));
+      if (list.length > 6) console.log(`     … ${list.length - 6} more`);
+    }
+    break;
+  }
+  case 'file': {
+    if (!arg) { console.error('Usage: report.mjs file <pattern>'); process.exit(1); }
+    const hits = findings.filter((f) => f.file.includes(arg));
+    console.log(` ${hits.length} finding(s) matching "${arg}"${staleMark(hits[0]?.file || '')}`);
+    hits.slice(0, MAX_SHOWN).forEach((f) => console.log(fmt(f)));
+    break;
+  }
+  default: {
+    const skip = parseInt(arg, 10) || 0;
+    const files = [...byFile().entries()].sort((a, b) => b[1].length - a[1].length);
+    const page = files.slice(skip, skip + 4);
+    console.log(`── worst files (${skip + 1}–${skip + page.length} of ${files.length}) ──`);
+    for (const [file, list] of page) {
+      console.log(`\n ${file} (${list.length})${staleMark(file)}`);
+      list.slice(0, 40).forEach((f) => console.log(fmt(f)));
+      if (list.length > 40) console.log(`     … ${list.length - 40} more`);
+    }
+    if (files.length > skip + 4) {
+      console.log(`\n  ${files.length - (skip + 4)} more file(s). Next page:`);
+      console.log(`   node ${path.relative(process.cwd(), __filename)} worst ${skip + 4}`);
+    }
+  }
+}
+
+console.log('');

package/scaffold/.agent/skills/total-recall/plugins/code-quality/core/state.mjs

@@ -0,0 +1,20 @@
+/**
+ * Where a repository keeps its code-quality state (config.json, reports, lock).
+ * The runner itself lives in this plugin and is never copied into a repo.
+ * TR_CODE_QUALITY_STATE overrides; otherwise the nearest enclosing
+ * .agent/skills/code-quality directory, or one beside the current directory.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function stateDir(start = process.cwd()) {
+  if (process.env.TR_CODE_QUALITY_STATE) return path.resolve(process.env.TR_CODE_QUALITY_STATE);
+  let dir = path.resolve(start);
+  for (;;) {
+    const candidate = path.join(dir, '.agent', 'skills', 'code-quality');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.join(path.resolve(start), '.agent', 'skills', 'code-quality');
+    dir = parent;
+  }
+}