total-recall-brain 3.44.0 → 3.46.0

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

@@ -12,6 +12,7 @@
  * Status, most severe first:
  *   missing         no report file
  *   unreadable      report file is not valid JSON or has an unknown shape
+ *   foreign         report belongs to a different repository root
  *   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
@@ -21,27 +22,34 @@
  *   partial         clean, but higher-tier gates were skipped
  *   clean           every gate ran, nothing changed since
  */
-import { readFileSync, existsSync, statSync } from 'node:fs';
+import { readFileSync, existsSync, statSync, realpathSync } 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 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 });
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024, timeout: 20_000 });
+}
+
+// Resolve the caller's working tree independently of cached report metadata.
+function repositoryRoot(cwd) {
+  try { return realpathSync(git(cwd, ['rev-parse', '--show-toplevel']).trim()); }
+  catch { return realpathSync(cwd); }
 }
 
 /** Returns { head, changed } or null when git cannot be read. */
-function freshness(report) {
+function freshness(report, repoRoot) {
   try {
-    const head = git(report.repoRoot, ['rev-parse', 'HEAD']).trim();
+    const head = git(repoRoot, ['rev-parse', '--verify', 'HEAD']).trim();
     const startedMs = Date.parse(report.startedAt);
     const changed = [];
-    for (const rel of git(report.repoRoot, ['ls-files', '-z']).split('\0')) {
+    for (const rel of git(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);
+        if (statSync(path.join(repoRoot, rel)).mtimeMs > startedMs) changed.push(rel);
       } catch { /* deleted since the run */ }
     }
     return { head, changed };
@@ -50,10 +58,13 @@ function freshness(report) {
   }
 }
 
-export function buildReportView(reportFile, { now = Date.now(), inspectGit = true } = {}) {
-  const base = { reportFile, status: 'missing', reasons: [] };
+export function buildReportView(reportFile, { now = Date.now(), inspectGit = true, cwd = process.cwd() } = {}) {
+  const base = { reportFile, status: 'missing', clean: false, reasons: [] };
   if (!existsSync(reportFile)) {
-    return { ...base, reasons: ['No report file. Run code-quality-check, then reload.'] };
+    const configured = existsSync(path.join(stateDir(cwd), 'config.json'));
+    return { ...base, reasons: [configured
+      ? 'No report file. Run code-quality-check, then reload.'
+      : 'No code-quality configuration. Run total-recall code-quality detect --apply, then run code-quality-check.'] };
   }
   let report;
   try {
@@ -67,6 +78,19 @@ export function buildReportView(reportFile, { now = Date.now(), inspectGit = tru
     return { ...base, status: 'unreadable', reasons: ['Report does not have the code-quality schema (checks, ranChecks, startedAt).'] };
   }
 
+  if (typeof report.repoRoot !== 'string' || !path.isAbsolute(report.repoRoot)) {
+    return { ...base, status: 'unreadable', reasons: ['Report has no absolute repository root. Run code-quality-check in this repository.'] };
+  }
+  let repoRoot;
+  try {
+    repoRoot = repositoryRoot(cwd);
+    if (realpathSync(report.repoRoot) !== repoRoot) {
+      return { ...base, status: 'foreign', reasons: ['Report belongs to another repository. Run code-quality-check in this repository.'] };
+    }
+  } catch {
+    return { ...base, status: 'unreadable', reasons: ['Cannot verify report repository root. Run code-quality-check in this repository.'] };
+  }
+
   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 : [];
@@ -87,8 +111,9 @@ export function buildReportView(reportFile, { now = Date.now(), inspectGit = tru
     (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 fresh = inspectGit ? freshness(report, repoRoot) : null;
+  const revisionKnown = typeof report.gitHead === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(report.gitHead);
+  const headMoved = Boolean(fresh && revisionKnown && fresh.head !== report.gitHead);
 
   const reasons = [];
   let status = 'clean';
@@ -102,7 +127,8 @@ export function buildReportView(reportFile, { now = Date.now(), inspectGit = tru
   }
   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');
+  if (!revisionKnown) set('unknown-freshness', 'Report has no verified revision. Run code-quality-check in this repository.');
+  if (fresh === null) set('unknown-freshness', 'git freshness could not be verified; 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)}`
@@ -116,7 +142,7 @@ export function buildReportView(reportFile, { now = Date.now(), inspectGit = tru
     reasons,
     clean: status === 'clean',
     toolchain: report.toolchain,
-    repoRoot: report.repoRoot,
+    repoRoot,
     tier: report.tier,
     gitHead: report.gitHead ?? null,
     currentHead: fresh?.head ?? null,
@@ -172,7 +198,7 @@ export async function printCachedReport(args, reportFile) {
 }
 
 export function defaultReportFile() {
-  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'reports', 'latest.json');
+  return path.join(stateDir(), 'reports', 'latest.json');
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

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

@@ -17,12 +17,11 @@
  *   report.mjs --review-diagnostics [--json]  cached gate and finding details
  */
 
-import { readFileSync, existsSync, statSync } from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { stateDir } from './state.mjs';
-import { printCachedReport, wantsStructuredReport } from './report-data.mjs';
+import { buildReportView, printCachedReport, wantsStructuredReport } from './report-data.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -39,39 +38,15 @@ if (wantsStructuredReport(process.argv.slice(2))) {
   process.exit(await printCachedReport(process.argv.slice(2), REPORT_JSON));
 }
 
-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 view = buildReportView(REPORT_JSON);
+if (['missing', 'unreadable', 'foreign'].includes(view.status)) {
+  console.error(`Code Quality report: ${view.status}\n${view.reasons.join('\n')}`);
+  process.exit(1);
 }
+process.exitCode = view.clean ? 0 : 1;
 
 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 changed = view.changedSinceRun;
 const ageMin = Math.round((Date.now() - Date.parse(report.finishedAt)) / 60000);
 
 // ─── Header ───────────────────────────────────────────────────────────────────
@@ -114,11 +89,11 @@ if (opaque.length) {
   }
 }
 
-if (changed === null) {
-  console.log(`    Could not read git — cannot tell whether this report matches your tree.`);
-} else if (changed.length === 0) {
+console.log(`    Report status: ${view.status}`);
+for (const reason of view.reasons) console.log(`    ${reason}`);
+if (changed !== null && changed.length === 0 && view.currentHead === view.gitHead) {
   console.log(`    FRESH — no tracked source file has changed since this run started.`);
-} else {
+} else if (changed?.length) {
   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`);
@@ -146,15 +121,15 @@ const staleMark = (file) => (changed?.includes(file) ? ' ' : '');
 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); }
+  if (!arg) { console.log(raw.slice(0, 20000)); process.exit(view.clean ? 0 : 1); }
   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);
+  process.exit(section && view.clean ? 0 : 1);
 }
 
 if (findings.length === 0) {
   console.log(' No findings.');
-  process.exit(0);
+  process.exit(view.clean ? 0 : 1);
 }
 
 switch (mode) {

package/scaffold/.agent/skills/total-recall/plugins/code-quality/package-lock.json

@@ -1,18 +1,18 @@
 {
   "name": "tr-plugin-code-quality",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-code-quality",
-      "version": "0.2.6",
+      "version": "0.3.0",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.43.3"
+        "total-recall-brain": "3.45.0"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5543,9 +5543,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.43.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.43.3.tgz",
-      "integrity": "sha512-yjfPN/BQxEEa+iodyFXQov/6fRt1pZg/7RcmgsbpALwBt6Ki3JJjT3tzArBC7NxHQmXgGYyKnCYId6xe/W2rPg==",
+      "version": "3.45.0",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.45.0.tgz",
+      "integrity": "sha512-HDYfROazZbsLHQsFPnlBcSpe1HL1QEi7JG8x/eNRUI06RxVQsZWl8LwBo2lTWjWRDrKmCy7BUmSXQDuWF3lrEw==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -5553,7 +5553,7 @@
       ],
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
-        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.4",
+        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.5",
         "bcrypt": "^6.0.0",
         "better-sqlite3": "^12.11.1",
         "cookie-parser": "^1.4.7",

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

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-code-quality",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "type": "module",
   "description": "Total Recall code-quality plugin: shared gate runner core and per-repo gate configuration.",
   "license": "MIT",
@@ -18,6 +18,7 @@
     "plugin.json",
     "README.md",
     "LICENSE",
+    "DESIGN.md",
     "core/",
     "commands/",
     "ui/"

package/scaffold/.agent/skills/total-recall/plugins/code-quality/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "code-quality",
   "name": "Code Quality Gates",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Fail-closed deterministic code-quality gates, lint rules, and test compliance reporting.",
   "author": "Total Recall contributors",
   "license": "MIT",
@@ -22,6 +22,15 @@
         "description": "Read the latest gate report or --review-diagnostics, with --json for machine output. Never starts a check",
         "effect": "read"
       },
+      {
+        "name": "run",
+        "description": "Run the selected repository's configured fast or full gates once and persist the report",
+        "effect": "write",
+        "timeoutMs": 600000,
+        "args": [
+          { "name": "tier", "flag": "--tier", "type": "choice", "options": ["fast", "full"], "label": "Gate tier" }
+        ]
+      },
       {
         "name": "snapshot",
         "description": "Copy the exact source under test (git file lists of this repo and linked plugin repos, secrets refused) to the test node, with a SHA-256 manifest",
@@ -63,7 +72,37 @@
     }
   ],
   "ui": {
+    "home": "code-quality-home",
+    "design_tokens": "DESIGN.md",
     "elements": [
+      {
+        "id": "code-quality-home",
+        "kind": "panel",
+        "tag": "code-quality-home",
+        "module": "ui/home.mjs",
+        "description": "Home: verdict, freshness, coverage, findings and the declared operations for this repository. Data comes from `code-quality report --json`; absent data never renders as passing.",
+        "props": {
+          "view": {
+            "type": "object",
+            "description": "JSON printed by `total-recall code-quality report --json`. Absent view renders as no data, never as passing."
+          }
+        },
+        "optional_tokens": [
+          "font-body",
+          "font-mono",
+          "color-primary",
+          "color-primary-strong",
+          "color-on-primary",
+          "color-background",
+          "color-surface",
+          "color-border",
+          "color-text",
+          "color-muted",
+          "color-success",
+          "color-warning",
+          "color-danger"
+        ]
+      },
       {
         "id": "code-quality-report",
         "kind": "panel",
@@ -76,10 +115,6 @@
             "description": "JSON printed by `total-recall code-quality report json`. Absent view renders as no data, never as passing."
           }
         },
-        "events": [
-          "run-check",
-          "reload"
-        ],
         "optional_tokens": [
           "font-body",
           "color-text",
@@ -91,41 +126,6 @@
           "radius-md",
           "space-4"
         ]
-      },
-      {
-        "id": "card",
-        "kind": "card",
-        "tag": "tr-code-quality-card",
-        "module": "ui/card.js",
-        "description": "Gatekeeper Card Face"
-      }
-    ]
-  },
-  "card_face": {
-    "skin": "winamp-classic",
-    "theme": "vibrant",
-    "headline": "Deterministic Code Gates & Lint",
-    "primary_color": "#06b6d4",
-    "secondary_color": "#164e63",
-    "accent_color": "#22d3ee",
-    "touch_layout": "comfortable",
-    "interactive": true,
-    "quick_actions": [
-      {
-        "subcommand": "report",
-        "label": "REPORT"
-      },
-      {
-        "subcommand": "gate",
-        "label": "GATE"
-      },
-      {
-        "subcommand": "config",
-        "label": "CONFIG"
-      },
-      {
-        "subcommand": "detect",
-        "label": "DETECT"
       }
     ]
   },

package/scaffold/.agent/skills/total-recall/plugins/code-quality/ui/chunks/config.md

@@ -0,0 +1,15 @@
+---
+type: ui-chunk:chunk
+plugin: code-quality
+id: config
+title: Gate configuration
+description: Read, validate or change the repository's gate configuration.
+timestamp: '2026-11-08T08:04:00Z'
+intents: [show quality gate config, change a gate setting, validate gate configuration]
+surfaces: [page]
+operations: [config]
+---
+<section data-design-component="workflow">
+  <h2>Inspect the gate configuration</h2>
+  <p>Use <code>config get</code> to inspect the current settings and <code>config validate</code> to check changes before running gates.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/code-quality/ui/chunks/detect.md

@@ -0,0 +1,15 @@
+---
+type: ui-chunk:chunk
+plugin: code-quality
+id: detect
+title: Detect candidate gates
+description: Propose checks based on existing repository scripts and optionally apply the proposal.
+timestamp: '2026-11-08T08:04:00Z'
+intents: [suggest quality gates, detect package checks, review detected gates]
+surfaces: [page]
+operations: [detect]
+---
+<section data-design-component="workflow">
+  <h2>Review detected checks</h2>
+  <p>Run detection to see which checks the repository already exposes. Use <code>--apply</code> after reviewing the proposed configuration.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/code-quality/ui/chunks/gate.md

@@ -0,0 +1,15 @@
+---
+type: ui-chunk:chunk
+plugin: code-quality
+id: gate
+title: Repository gates
+description: List configured gates and locate the right add or remove operation.
+timestamp: '2026-11-08T08:04:00Z'
+intents: [list repository gates, add a quality gate, remove a quality gate]
+surfaces: [page]
+operations: [gate]
+---
+<section data-design-component="workflow">
+  <h2>Review the configured gates</h2>
+  <p>Run <code>gate list</code> to see the repository's checks. Review the current IDs and tiers before adding or removing one.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/code-quality/ui/chunks/init.md

@@ -0,0 +1,15 @@
+---
+type: ui-chunk:chunk
+plugin: code-quality
+id: init
+title: Set up repository gates
+description: Initialize the repository's code quality configuration with available defaults.
+timestamp: '2026-11-08T08:04:00Z'
+intents: [initialize quality gates, create gate configuration, set up repo checks]
+surfaces: [page]
+operations: [init]
+---
+<section data-design-component="workflow">
+  <h2>Set up the repository</h2>
+  <p>Initialize the gate configuration, then inspect the selected checks before running the first gate suite.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/code-quality/ui/chunks/report.md

@@ -0,0 +1,17 @@
+---
+type: ui-chunk:chunk
+plugin: code-quality
+id: report
+title: Latest gate report
+description: Read the cached report and compare its coverage and findings with the current repository revision.
+timestamp: '2026-11-08T08:04:00Z'
+intents: [read the latest gate report, find failing gates, check report freshness, review skipped checks]
+surfaces: [page]
+operations: [report]
+data: ['report:/status', 'report:/reasons', 'report:/tier', 'report:/gitHead', 'report:/currentHead', 'report:/finishedAt', 'report:/ageMs', 'report:/durationMs', 'report:/changedSinceRun', 'report:/sourceFileCount', 'report:/ranChecks', 'report:/skippedChecks', 'report:/gates', 'report:/totalFindings', 'report:/blockingFindings', 'report:/findings', 'report:/findingsTruncated']
+panel: code-quality-home
+---
+<section data-design-component="report">
+  <h2>Read the latest gate evidence</h2>
+  <p>Start with freshness, then check skipped gates and blocking findings. Reload the stored report if a check has just finished.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/code-quality/ui/chunks/run.md

@@ -0,0 +1,17 @@
+---
+type: ui-chunk:chunk
+plugin: code-quality
+id: run
+title: Run repository gates
+description: Start the selected repository's fast or full quality gate run and review the fresh report.
+timestamp: '2026-11-08T23:25:00Z'
+intents: [run fast quality gates, run the full repository checks, rerun gates after fixing findings]
+surfaces: [page]
+operations: [run, report]
+data: ['report:/status', 'report:/finishedAt', 'report:/ranChecks', 'report:/blockingFindings']
+panel: code-quality-report
+---
+<section data-design-component="report">
+  <h2>Run repository gates</h2>
+  <p>Choose the fast or full tier. The owner locks the selected repository for one run, then the panel reads the completed report with its timestamp and gate coverage.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/code-quality/ui/chunks/snapshot.md

@@ -0,0 +1,15 @@
+---
+type: ui-chunk:chunk
+plugin: code-quality
+id: snapshot
+title: Snapshot the source under test
+description: Inspect the files that a snapshot would send to the test node before copying them.
+timestamp: '2026-11-08T08:04:00Z'
+intents: [snapshot source under test, inspect test node snapshot, preview snapshot file list]
+surfaces: [page]
+operations: [snapshot]
+---
+<section data-design-component="workflow">
+  <h2>Preview the snapshot</h2>
+  <p>Choose the test node and use <code>--dry-run</code> to inspect the repository and linked plugin files before copying them.</p>
+</section>