@bongos/core 1.19.257 → 1.19.258

package/scripts/gds/fitness-ratchets.js

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+// scripts/gds/fitness-ratchets.js — quality budgets that only tighten (task
+// 1003129, goal 1000076; docs/audits/ai-dev-redteam-baseline.md §4).
+//
+// The audit's modularity finding was measurement without thresholds: sizes,
+// dead code, and doc entropy were all TRACKED and nothing failed when they
+// grew. This module gives each metric a committed BASELINE
+// (config/fitness-baselines.json) with RATCHET semantics:
+//   value > baseline  → violation (fitness hardFail — the number got worse)
+//   value < baseline  → warning nudge to lower the baseline (an ordinary PR)
+// GitClear's measured trend (AI-assisted code duplicates instead of reusing)
+// is the reason the gate exists; the baseline records today's debt without
+// bricking today's tree.
+//
+// Metrics (all hermetic — git + fs only, no network):
+//   oversized_file_count / excess_lines_total — tracked first-party .js files
+//     over OVERSIZE_LINES lines, and their total excess (growth anywhere over
+//     the threshold trips the sum even when the count is flat)
+//   duplicate_window_count — normalized WINDOW-line blocks appearing in 2+
+//     distinct files (the in-house jscpd: cross-file copy/paste)
+//   require_cycle_count — strongly-connected components (size >1) in the
+//     relative-require graph (the in-house madge)
+//   console_call_count — console.* call sites in SERVER paths (src/ + modules/
+//     minus their browser public/ trees); task 1003130 converts the core path
+//     to structured logging and shrinks this baseline
+//   doc_stale_links / doc_broken_anchors / doc_duplicate_prose — the
+//     docs-entropy scanner's three counts, reused as a library
+//
+// The knip dead-code ratchet needs node_modules + ~seconds, so it is NOT part
+// of the in-suite check: CI runs `node scripts/gds/fitness-ratchets.js --knip`
+// as its own step (fail-open when knip cannot run, fail-closed on regression).
+//
+// Refresh floors: node scripts/gds/fitness-ratchets.js --update-baselines
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync, execSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const BASELINE_PATH = path.join(ROOT, 'config', 'fitness-baselines.json');
+
+const OVERSIZE_LINES = 1500;
+const WINDOW = 30; // normalized lines per duplication window
+
+// Vendored / generated / third-party JS the budgets must not count.
+const EXCLUDE_RE = /(^|\/)(node_modules|public-docs)\/|\.min\.js$|redoc\.standalone\.js$|(^|\/)vendor\//;
+
+function trackedJsFiles() {
+  const out = execFileSync('git', ['ls-files', '*.js'], { cwd: ROOT, encoding: 'utf8' });
+  return out.split('\n').map((s) => s.trim()).filter(Boolean).filter((f) => !EXCLUDE_RE.test(f));
+}
+
+function readRepoFile(rel) {
+  return fs.readFileSync(path.join(ROOT, rel), 'utf8');
+}
+
+// ---------- size ----------
+
+function sizeMetrics(files, read = readRepoFile) {
+  let count = 0;
+  let excess = 0;
+  for (const f of files) {
+    const lines = read(f).split('\n').length;
+    if (lines > OVERSIZE_LINES) {
+      count++;
+      excess += lines - OVERSIZE_LINES;
+    }
+  }
+  return { oversized_file_count: count, excess_lines_total: excess };
+}
+
+// ---------- duplication (in-house jscpd) ----------
+
+function normalizeLines(text) {
+  return text
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && !l.startsWith('//') && !l.startsWith('*') && !l.startsWith('/*'));
+}
+
+// contentsByFile: Map(rel → text). Counts window-hashes seen in ≥2 DISTINCT files.
+function duplicateWindowCount(contentsByFile, window = WINDOW) {
+  const filesByHash = new Map();
+  for (const [file, text] of contentsByFile) {
+    const lines = normalizeLines(text);
+    for (let i = 0; i + window <= lines.length; i++) {
+      const h = crypto.createHash('sha1').update(lines.slice(i, i + window).join('\n')).digest('base64');
+      let set = filesByHash.get(h);
+      if (!set) filesByHash.set(h, (set = new Set()));
+      set.add(file);
+    }
+  }
+  let dupes = 0;
+  for (const set of filesByHash.values()) if (set.size >= 2) dupes++;
+  return dupes;
+}
+
+// ---------- require cycles (in-house madge) ----------
+
+const REQUIRE_RE = /require\(\s*(['"])(\.{1,2}\/[^'"]+)\1\s*\)/g;
+
+function resolveRelative(fromRel, spec, exists) {
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromRel), spec));
+  for (const cand of [base, `${base}.js`, `${base}/index.js`]) {
+    if (exists(cand)) return cand;
+  }
+  return null;
+}
+
+// edges: Map(rel → [rel...]). Returns the number of SCCs with size > 1 (Tarjan).
+function countCycles(edges) {
+  let index = 0;
+  const idx = new Map();
+  const low = new Map();
+  const onStack = new Set();
+  const stack = [];
+  let cycles = 0;
+
+  function strongconnect(v) {
+    idx.set(v, index); low.set(v, index); index++;
+    stack.push(v); onStack.add(v);
+    for (const w of edges.get(v) || []) {
+      if (!edges.has(w)) continue;
+      if (!idx.has(w)) { strongconnect(w); low.set(v, Math.min(low.get(v), low.get(w))); }
+      else if (onStack.has(w)) low.set(v, Math.min(low.get(v), idx.get(w)));
+    }
+    if (low.get(v) === idx.get(v)) {
+      let size = 0; let w;
+      do { w = stack.pop(); onStack.delete(w); size++; } while (w !== v);
+      if (size > 1) cycles++;
+    }
+  }
+  for (const v of edges.keys()) if (!idx.has(v)) strongconnect(v);
+  return cycles;
+}
+
+function requireGraph(contentsByFile) {
+  const known = new Set(contentsByFile.keys());
+  const exists = (rel) => known.has(rel);
+  const edges = new Map();
+  for (const [file, text] of contentsByFile) {
+    const deps = [];
+    for (const m of text.matchAll(REQUIRE_RE)) {
+      const target = resolveRelative(file, m[2], exists);
+      if (target && target !== file) deps.push(target);
+    }
+    edges.set(file, deps);
+  }
+  return edges;
+}
+
+// ---------- console.* in server paths ----------
+
+const CONSOLE_RE = /console\.(log|error|warn|info|debug)\s*\(/g;
+
+function isServerPath(rel) {
+  if (!(rel.startsWith('src/') || rel.startsWith('modules/') || rel === 'server.js')) return false;
+  if (rel.includes('/public/')) return false; // browser surfaces are a different concern
+  if (rel.includes('/test')) return false;
+  return true;
+}
+
+function consoleCallCount(contentsByFile) {
+  let n = 0;
+  for (const [file, text] of contentsByFile) {
+    if (!isServerPath(file)) continue;
+    n += (text.match(CONSOLE_RE) || []).length;
+  }
+  return n;
+}
+
+// ---------- doc entropy (reuse the scanner as a library) ----------
+
+function docMetrics() {
+  const de = require('./docs-entropy.js');
+  const relFiles = de.collectMarkdownFiles();
+  const linkFindings = de.scanStaleLinks(relFiles);
+  return {
+    doc_stale_links: linkFindings.filter((f) => f.issue === 'missing_file').length,
+    doc_broken_anchors: linkFindings.filter((f) => f.issue === 'missing_anchor').length,
+    doc_duplicate_prose: de.scanDuplicateProse(relFiles).length,
+  };
+}
+
+// ---------- knip (CI-only, fail-open on infra) ----------
+
+function knipIssueCount() {
+  let raw;
+  try {
+    raw = execSync('npx --no-install knip --reporter json --no-exit-code', {
+      cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    if (e && e.stdout) raw = e.stdout.toString(); else return null; // knip unavailable → skip
+  }
+  try {
+    const j = JSON.parse(raw);
+    // knip's json reporter: { files: [...], issues: [{ file, owners, exports:[], types:[], ... }] }
+    const files = Array.isArray(j.files) ? j.files.length : 0;
+    let items = 0;
+    for (const issue of j.issues || []) {
+      for (const key of ['dependencies', 'devDependencies', 'optionalPeerDependencies', 'unlisted', 'binaries', 'unresolved', 'exports', 'types', 'nsExports', 'nsTypes', 'duplicates']) {
+        const v = issue[key];
+        items += Array.isArray(v) ? v.length : 0;
+      }
+    }
+    return files + items;
+  } catch {
+    return null;
+  }
+}
+
+// ---------- baseline + ratchet ----------
+
+function readBaselines() {
+  try {
+    return JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf8')).metrics || {};
+  } catch {
+    return {};
+  }
+}
+
+// Pure ratchet verdict — exported for the hermetic test.
+function compareToBaselines(metrics, baselines) {
+  const violations = [];
+  const warnings = [];
+  for (const [name, value] of Object.entries(metrics)) {
+    if (value === null || value === undefined) continue; // metric skipped (e.g. knip off-CI)
+    const floor = baselines[name];
+    if (floor === undefined) {
+      warnings.push(`no baseline for "${name}" (value ${value}) — run --update-baselines`);
+    } else if (value > floor) {
+      violations.push(`${name} regressed: ${value} > baseline ${floor} — fix the regression; never raise the baseline to pass`);
+    } else if (value < floor) {
+      warnings.push(`ratchet-down available: ${name} improved to ${value} (baseline ${floor}) — lower the baseline in config/fitness-baselines.json`);
+    }
+  }
+  return { violations, warnings };
+}
+
+function computeMetrics({ withDocs = true } = {}) {
+  const files = trackedJsFiles();
+  const contents = new Map(files.map((f) => [f, readRepoFile(f)]));
+  return {
+    ...sizeMetrics(files, (f) => contents.get(f)),
+    duplicate_window_count: duplicateWindowCount(contents),
+    require_cycle_count: countCycles(requireGraph(contents)),
+    console_call_count: consoleCallCount(contents),
+    ...(withDocs ? docMetrics() : {}),
+  };
+}
+
+// The fitness.js check (in-suite, hermetic — everything except knip).
+function checkQualityRatchets() {
+  const metrics = computeMetrics();
+  const { violations, warnings } = compareToBaselines(metrics, readBaselines());
+  return {
+    name: 'quality ratchets — size, duplication, cycles, console, doc entropy only tighten (task 1003129)',
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `budgets: ${Object.entries(metrics).map(([k, v]) => `${k}=${v}`).join(' · ')} vs config/fitness-baselines.json (knip runs as its own CI step)`,
+  };
+}
+
+function main() {
+  const update = process.argv.includes('--update-baselines');
+  const knipOnly = process.argv.includes('--knip');
+
+  if (update) {
+    const metrics = computeMetrics();
+    const knip = knipIssueCount();
+    if (knip !== null) metrics.knip_issue_count = knip;
+    const existing = readBaselines();
+    if (knip === null && existing.knip_issue_count !== undefined) metrics.knip_issue_count = existing.knip_issue_count;
+    fs.writeFileSync(
+      BASELINE_PATH,
+      JSON.stringify({ _comment: 'fitness-ratchets baselines (task 1003129): quality debt recorded at gate-adoption. Shrink-only — lower a value when the metric improves; raising one to pass CI is out of policy.', metrics }, null, 2) + '\n',
+    );
+    console.log(`fitness-ratchets: baselines written — ${Object.entries(metrics).map(([k, v]) => `${k}=${v}`).join(' · ')}`);
+    return;
+  }
+
+  if (knipOnly) {
+    const value = knipIssueCount();
+    if (value === null) {
+      console.warn('fitness-ratchets: WARN — knip not runnable here (no node_modules / npx failure); failing OPEN.');
+      process.exit(0);
+    }
+    const { violations, warnings } = compareToBaselines({ knip_issue_count: value }, readBaselines());
+    for (const w of warnings) console.warn(`fitness-ratchets: ${w}`);
+    if (violations.length) {
+      for (const v of violations) console.error(`fitness-ratchets: FAIL — ${v}`);
+      process.exit(1);
+    }
+    console.log(`fitness-ratchets: PASS — knip_issue_count=${value}.`);
+    return;
+  }
+
+  const r = checkQualityRatchets();
+  for (const w of r.warnings) console.warn(`! ${w}`);
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkQualityRatchets,
+  computeMetrics,
+  compareToBaselines,
+  duplicateWindowCount,
+  normalizeLines,
+  countCycles,
+  requireGraph,
+  resolveRelative,
+  sizeMetrics,
+  consoleCallCount,
+  isServerPath,
+  knipIssueCount,
+  OVERSIZE_LINES,
+  WINDOW,
+  BASELINE_PATH,
+};

package/scripts/gds/fitness.js

@@ -1881,6 +1881,8 @@ const CHECKS = [
   checkVocabularyWall, // Check 19 — ADR 0174 / goal 1000068 R07: "role" is a craft, never a rank
   checkGoalMembershipVocabulary, // Check 19b — ADR 0177 / task 1003013: the FOURTH "role" (goal membership)
   checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999: every body-reading write route validates (ADR 0118)
+  require('./fitness-ratchets.js').checkQualityRatchets, // Check 20 — task 1003129: quality budgets only tighten (mechanics + knip CI step live in fitness-ratchets.js)
+  require('./control-manifest.js').checkControlsExist, // Check 21 — task 1003131: goal-1000076 controls assert their own existence (the ADR 0022 assurance-of-assurance)
 ];
 
 function runAll() {
@@ -1909,10 +1911,8 @@ function main() {
 if (require.main === module) main();
 
 module.exports = {
-  checkVocabularyWall,
-  VOCAB_ALLOW,
-  checkGoalMembershipVocabulary,
-  GOAL_VOCAB_SURFACE,
+  checkVocabularyWall, VOCAB_ALLOW,
+  checkGoalMembershipVocabulary, GOAL_VOCAB_SURFACE,
   runAll,
   resolvesToHostGame,
   checkCoreHostBoundary,

package/scripts/gds/gen-session-index.js

@@ -128,7 +128,14 @@ function renderSnippet(entries, count = SNIPPET_COUNT) {
   const recent = entries.slice(0, count);
   const L = [];
   L.push(BEGIN);
-  L.push(`**Recent sessions** (newest ${recent.length} — full history in [\`docs/session-log-index.md\`](docs/session-log-index.md)):`);
+  // NOT A MARKDOWN LINK, deliberately. docs/session-log-index.md is GITIGNORED
+  // (ADR 0110 — deploy-regenerated, never committed), so a repo-relative link to
+  // it dangles in every fresh checkout. This snippet is written into the TRACKED
+  // CLAUDE.md, so linking it here minted a stale link in CI on every run: that is
+  // what pushed doc_stale_links past the fitness ratchet baseline and turned the
+  // required `unit` check red on main, blocking all PR merges and (via publish.yml's
+  // workflow_run trigger) all releases. Name the file in a code span; never re-link it.
+  L.push(`**Recent sessions** (newest ${recent.length} — full history in \`docs/session-log-index.md\`):`);
   L.push('');
   for (const e of recent) L.push(line(e, 'docs/session-logs/'));
   L.push(END);

package/scripts/gds/redteam-patrol.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+// scripts/gds/redteam-patrol.js — the weekly deterministic red-team patrol
+// (task 1003128, goal 1000076; ADR 0180 §3, docs/audits/ai-dev-redteam-baseline.md).
+//
+// The patrol is the third enforcement layer (prevent → gate → PATROL): checks
+// too slow, too networked, or too history-wide for the merge gate, run weekly
+// by the .claude/scheduled-tasks/redteam-weekly routine. It is ADVISORY by
+// doctrine (ADR 0162 — verdicts never self-execute): findings are FILED as
+// security reports for Archon adjudication, never turned into gates here.
+//
+// Checks (all deterministic — no model reads anything):
+//   1. history-secrets — full-git-history gitleaks scan (.gitleaks.toml config;
+//      the CI gate only scans the current tree, so a key deleted years ago but
+//      still live is THIS check's catch). Needs the gitleaks binary
+//      (GITLEAKS_BIN or on PATH) — absent means a loud degraded note.
+//   2. dependency-review — npm audit delta vs config/audit-baseline.json
+//      (reuses audit-gate.js), release-age cooldown (<7 days — ADR 0180 §3),
+//      young direct deps (<90 days — the slopsquat shape), stale overrides.
+//   3. action-pins — every workflow `uses:` must be pinned to a 40-hex SHA
+//      (the tj-actions lesson).
+//
+// Filing: DRY-RUN by default (prints what it would file). --file POSTs one
+// report PER CLASS (max severity within the class, details in repro_steps_md)
+// to /api/gds/security/reports. --canary proves the end-to-end pipe: plants a
+// constructed token, asserts the scanner catches it, files a low "[canary]"
+// report, and dispute-closes it so the queue stays clean.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync, execFileSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const COOLDOWN_DAYS = 7;   // ADR 0180 §3 — patrol-enforced until npm ≥ 11.10 in CI
+const YOUNG_PKG_DAYS = 90; // a very new package is the slopsquat/typosquat shape
+const MAX_ITEMS_PER_REPORT = 10;
+
+const SEV_ORDER = { low: 0, medium: 1, high: 2, critical: 3 };
+// npm audit says "moderate"; the bounty table says "medium".
+function mapSeverity(s) {
+  const v = String(s || '').toLowerCase();
+  return v === 'moderate' ? 'medium' : (SEV_ORDER[v] !== undefined ? v : 'low');
+}
+function maxSeverity(findings) {
+  return findings.reduce((m, f) => (SEV_ORDER[f.severity] > SEV_ORDER[m] ? f.severity : m), 'low');
+}
+
+// ---------- 1. full-history secret scan ----------
+
+function gitleaksBin() {
+  const explicit = process.env.GITLEAKS_BIN;
+  if (explicit && fs.existsSync(explicit)) return explicit;
+  try {
+    execFileSync(process.platform === 'win32' ? 'where' : 'which', ['gitleaks'], { stdio: 'pipe' });
+    return 'gitleaks';
+  } catch {
+    return null;
+  }
+}
+
+// Parse a gitleaks JSON report file into patrol findings.
+function parseGitleaksReport(raw) {
+  let rows;
+  try { rows = JSON.parse(raw); } catch { return []; }
+  if (!Array.isArray(rows)) return [];
+  return rows.map((r) => ({
+    severity: 'high',
+    item: `${r.RuleID || r.ruleID || 'secret'} in ${r.File || r.file || '?'}${r.Commit ? ` @ ${String(r.Commit).slice(0, 8)}` : ''}`,
+  }));
+}
+
+function historySecretScan() {
+  const bin = gitleaksBin();
+  if (!bin) {
+    return { degraded: 'gitleaks binary not found (set GITLEAKS_BIN or `brew install gitleaks`) — history scan SKIPPED', findings: [] };
+  }
+  const report = path.join(os.tmpdir(), `gitleaks-patrol-${process.pid}.json`);
+  try {
+    execFileSync(bin, ['git', '.', '--config', '.gitleaks.toml', '--redact', '--no-banner',
+      '--report-format', 'json', '--report-path', report], { cwd: ROOT, stdio: 'pipe' });
+  } catch {
+    /* non-zero exit = leaks found; the report file is still written */
+  }
+  let findings = [];
+  try { findings = parseGitleaksReport(fs.readFileSync(report, 'utf8')); } catch { /* no report = clean */ }
+  try { fs.unlinkSync(report); } catch { /* already gone */ }
+  return { degraded: null, findings };
+}
+
+// ---------- 2. dependency review ----------
+
+function npmViewJson(spec) {
+  try {
+    return JSON.parse(execSync(`npm view ${spec} --json`, { cwd: ROOT, stdio: 'pipe', timeout: 30000 }).toString());
+  } catch {
+    return null;
+  }
+}
+
+function ageDays(iso, now = Date.now()) {
+  const t = Date.parse(iso);
+  return Number.isFinite(t) ? (now - t) / 86400000 : null;
+}
+
+function lockedVersion(lock, name) {
+  const entry = lock.packages && lock.packages[`node_modules/${name}`];
+  return entry && entry.version;
+}
+
+function dependencyReview() {
+  const findings = [];
+  const notes = [];
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+  const lock = JSON.parse(fs.readFileSync(path.join(ROOT, 'package-lock.json'), 'utf8'));
+
+  // 2a — audit delta vs the committed baseline (same lens as the CI gate, but
+  // the patrol also reports RESOLVED entries so the baseline gets shrunk).
+  const auditGate = require('./audit-gate.js');
+  try {
+    let raw;
+    try { raw = execSync('npm audit --omit=dev --json', { cwd: ROOT, maxBuffer: 32 * 1024 * 1024, stdio: 'pipe' }).toString(); }
+    catch (e) { raw = e && e.stdout ? e.stdout.toString() : null; }
+    const current = auditGate.extractFindings(JSON.parse(raw));
+    const baseline = JSON.parse(fs.readFileSync(auditGate.BASELINE_PATH, 'utf8')).findings || [];
+    const verdict = auditGate.compare(current, baseline);
+    for (const f of [...verdict.newGating, ...verdict.newAdvisory]) {
+      findings.push({ severity: mapSeverity(f.severity), item: `new advisory: [${f.severity}] ${f.name} (${f.id}) ${f.title}` });
+    }
+    for (const f of verdict.resolved) notes.push(`baseline shrinkable: ${f.name} (${f.id}) no longer reproduces`);
+  } catch (e) {
+    notes.push(`audit delta SKIPPED (infra): ${e.message}`);
+  }
+
+  // 2b — release-age cooldown + young packages, direct deps only (9 today).
+  for (const name of Object.keys(pkg.dependencies || {})) {
+    const version = lockedVersion(lock, name);
+    if (!version) continue;
+    const meta = npmViewJson(`${name} time`);
+    const time = meta && (meta.time || meta);
+    if (!time) { notes.push(`npm view failed for ${name} — cooldown check skipped`); continue; }
+    const vAge = ageDays(time[version]);
+    if (vAge !== null && vAge < COOLDOWN_DAYS) {
+      findings.push({ severity: 'medium', item: `cooldown breach: ${name}@${version} published ${vAge.toFixed(1)}d ago (<${COOLDOWN_DAYS}d — ADR 0180 §3)` });
+    }
+    const cAge = ageDays(time.created);
+    if (cAge !== null && cAge < YOUNG_PKG_DAYS) {
+      findings.push({ severity: 'medium', item: `young package: ${name} created ${cAge.toFixed(0)}d ago (<${YOUNG_PKG_DAYS}d — verify it is the intended package)` });
+    }
+  }
+
+  // 2c — override staleness (the undici lesson: a pin nobody watches rots).
+  for (const [name, range] of Object.entries(pkg.overrides || {})) {
+    if (typeof range !== 'string') continue;
+    const latest = npmViewJson(`${name} dist-tags.latest`);
+    if (!latest) continue;
+    const pinnedMajor = parseInt(String(range).replace(/^[^0-9]*/, ''), 10);
+    const latestMajor = parseInt(String(latest), 10);
+    if (Number.isFinite(pinnedMajor) && Number.isFinite(latestMajor) && latestMajor > pinnedMajor) {
+      findings.push({ severity: 'medium', item: `stale override: ${name} pinned "${range}" while latest is ${latest} — re-justify or lift the pin` });
+    }
+  }
+  return { findings, notes };
+}
+
+// ---------- 3. workflow action pins ----------
+
+const USES_RE = /^\s*(?:-\s+)?uses:\s*(\S+)/;
+const SHA_PINNED_RE = /@[0-9a-f]{40}(\s|$)/;
+
+function unpinnedUses(yamlText) {
+  const out = [];
+  for (const line of yamlText.split('\n')) {
+    const m = USES_RE.exec(line);
+    if (!m) continue;
+    const ref = m[1];
+    if (ref.startsWith('./') || ref.startsWith('docker://')) continue; // local/composite + digest-pinnable images
+    if (!SHA_PINNED_RE.test(ref)) out.push(ref);
+  }
+  return out;
+}
+
+function actionPinCheck() {
+  const dir = path.join(ROOT, '.github', 'workflows');
+  const findings = [];
+  if (!fs.existsSync(dir)) return { findings };
+  for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yml') || n.endsWith('.yaml'))) {
+    for (const ref of unpinnedUses(fs.readFileSync(path.join(dir, f), 'utf8'))) {
+      findings.push({ severity: 'medium', item: `unpinned action in ${f}: "${ref}" — pin to a 40-hex commit SHA (tj-actions lesson)` });
+    }
+  }
+  return { findings };
+}
+
+// ---------- report assembly + filing ----------
+
+function buildClassReport(className, findings, notes = []) {
+  const shown = findings.slice(0, MAX_ITEMS_PER_REPORT);
+  const body = [
+    ...shown.map((f) => `- [${f.severity}] ${f.item}`),
+    ...(findings.length > shown.length ? [`…and ${findings.length - shown.length} more`] : []),
+    ...(notes.length ? ['', 'Notes:', ...notes.map((n) => `- ${n}`)] : []),
+  ].join('\n');
+  return {
+    target: `redteam-patrol/${className}`,
+    severity: maxSeverity(findings),
+    title: `[patrol] ${className}: ${findings.length} finding(s)`,
+    description: `Weekly deterministic red-team patrol (task 1003128; advisory per ADR 0162 — adjudicate, then fix via ordinary tasks).`,
+    repro_steps_md: body,
+  };
+}
+
+async function fileReport(report) {
+  const { apiCall } = require('./cli-lib.js');
+  const r = await apiCall('POST', '/api/gds/security/reports', report);
+  const row = (r.data && r.data.report) || {};
+  return row.id || null;
+}
+
+async function disputeReport(id, note) {
+  const { apiCall } = require('./cli-lib.js');
+  return apiCall('POST', `/api/gds/security/reports/${id}/dispute`, { note });
+}
+
+// ---------- canary ----------
+
+async function runCanary(file) {
+  const bin = gitleaksBin();
+  if (!bin) { console.error('canary FAIL: gitleaks binary unavailable'); process.exit(1); }
+  const token = 'ghp_' + 'Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0Uv1Wx2Y'; // constructed, never a literal shape
+  const canaryPath = path.join(ROOT, 'src', `patrol-canary-${process.pid}.js`);
+  fs.writeFileSync(canaryPath, `const t = "${token}";\n`);
+  let caught = false;
+  try {
+    const report = path.join(os.tmpdir(), `gitleaks-canary-${process.pid}.json`);
+    try {
+      execFileSync(bin, ['dir', '.', '--config', '.gitleaks.toml', '--redact', '--no-banner',
+        '--report-format', 'json', '--report-path', report], { cwd: ROOT, stdio: 'pipe' });
+    } catch { /* leaks found → non-zero, expected */ }
+    try {
+      caught = parseGitleaksReport(fs.readFileSync(report, 'utf8')).some((f) => f.item.includes('patrol-canary'));
+      fs.unlinkSync(report);
+    } catch { caught = false; }
+  } finally {
+    fs.unlinkSync(canaryPath);
+  }
+  if (!caught) { console.error('canary FAIL: planted token was not detected'); process.exit(1); }
+  console.log('canary: planted token detected by the scanner ✓');
+  if (file) {
+    const id = await fileReport({
+      target: 'redteam-patrol/canary',
+      severity: 'low',
+      title: '[canary] patrol self-test — planted token detected end-to-end',
+      description: 'Seeded finding proving the patrol can detect and FILE (task 1003128 done-when). Dispute-closed by the patrol itself; no action needed.',
+      repro_steps_md: '- plant constructed ghp_ token in src/ → gitleaks dir catches it → report filed → dispute-closed.',
+    });
+    if (!id) { console.error('canary FAIL: report did not file'); process.exit(1); }
+    console.log(`canary: filed security report ${id} ✓`);
+    await disputeReport(id, 'canary self-test (task 1003128) — auto-closed by the patrol');
+    console.log('canary: dispute-closed ✓ — end-to-end pipe proven');
+  }
+}
+
+// ---------- main ----------
+
+async function main() {
+  if (process.argv.includes('--canary')) {
+    await runCanary(process.argv.includes('--file'));
+    return;
+  }
+  const doFile = process.argv.includes('--file');
+
+  const classes = [];
+  const secrets = historySecretScan();
+  if (secrets.findings.length) classes.push(buildClassReport('history-secrets', secrets.findings));
+  if (secrets.degraded) console.warn(`patrol: DEGRADED — ${secrets.degraded}`);
+
+  const deps = dependencyReview();
+  if (deps.findings.length) classes.push(buildClassReport('dependency-review', deps.findings, deps.notes));
+  else if (deps.notes.length) console.log(`patrol: dependency notes:\n${deps.notes.map((n) => `  - ${n}`).join('\n')}`);
+
+  const pins = actionPinCheck();
+  if (pins.findings.length) classes.push(buildClassReport('action-pins', pins.findings));
+
+  if (!classes.length) {
+    console.log('patrol: clean sweep — nothing to file.');
+    return;
+  }
+  for (const report of classes) {
+    if (doFile) {
+      const id = await fileReport(report);
+      console.log(`patrol: filed [${report.severity}] ${report.title} → report ${id}`);
+    } else {
+      console.log(`patrol (dry-run): would file [${report.severity}] ${report.title}\n${report.repro_steps_md}\n`);
+    }
+  }
+  if (!doFile) console.log('patrol: dry run — pass --file to POST these as security reports.');
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error(`patrol: ERROR ${e.message}`); process.exit(1); });
+}
+
+module.exports = {
+  parseGitleaksReport, unpinnedUses, ageDays, mapSeverity, maxSeverity,
+  buildClassReport, lockedVersion, COOLDOWN_DAYS, YOUNG_PKG_DAYS,
+};