contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/doctor.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * ContextDevKit doctor — diagnoses an installed project's setup.
+ *
+ * Checks node version, config validity + level, that `.claude/settings.json`
+ * hook wiring matches the configured level, git-hook presence (L≥3), memory
+ * scaffolding, onboarding state, and optional zod. Prints a report and exits
+ * non-zero if any CRITICAL (✗) problem is found, with a suggested fix per item.
+ *
+ * Run:  node contextkit/tools/scripts/doctor.mjs   (or /context-doctor)
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { composeSettings } from '../../runtime/config/settings-compose.mjs';
+import { getLevel, loadConfigSync } from '../../runtime/config/load.mjs';
+import { MAX_LEVEL, MIN_LEVEL, isValidLevel } from '../../runtime/config/levels.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+import { readJsonSafe } from '../../runtime/hooks/safe-io.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+let crit = 0;
+let warn = 0;
+const pass = (m) => console.log(`  ✓ ${m}`);
+const fail = (m, fix) => {
+  console.error(`  ✗ ${m}${fix ? `\n      → ${fix}` : ''}`);
+  crit++;
+};
+const note = (m, fix) => {
+  console.log(`  ⚠ ${m}${fix ? `\n      → ${fix}` : ''}`);
+  warn++;
+};
+
+const readJson = (rel) => readJsonSafe(resolve(ROOT, rel));
+
+function checkNode() {
+  const major = Number(process.versions.node.split('.')[0]);
+  major >= 18 ? pass(`Node ${process.versions.node}`) : fail(`Node ${process.versions.node} is too old`, 'install Node >= 18');
+}
+
+function checkConfig() {
+  if (!existsSync(P.config)) {
+    fail('contextkit/config.json missing', 're-run the installer');
+    return null;
+  }
+  const raw = readJson('contextkit/config.json');
+  if (!raw) {
+    fail('contextkit/config.json is not valid JSON', 'fix the JSON or re-run the installer');
+    return null;
+  }
+  const level = getLevel(ROOT);
+  isValidLevel(level) ? pass(`config valid — level L${level}`) : note('config.level out of range', `use /context-level <${MIN_LEVEL}-${MAX_LEVEL}>`);
+  return level;
+}
+
+function checkWiring(level) {
+  const settings = readJson('.claude/settings.json');
+  if (!settings) {
+    fail('.claude/settings.json missing or invalid', 'run /context-level ' + (level ?? 2));
+    return;
+  }
+  const expected = Object.keys(composeSettings(null, level ?? 2).hooks || {}).sort();
+  const actual = Object.keys(settings.hooks || {})
+    .filter((evt) => (settings.hooks[evt] || []).some((g) => (g.hooks || []).some((h) => String(h.command || '').includes('contextkit/runtime/hooks'))))
+    .sort();
+  JSON.stringify(expected) === JSON.stringify(actual)
+    ? pass(`hook wiring matches L${level}: ${actual.join(', ') || '(none)'}`)
+    : fail(`hook wiring (${actual.join(', ') || 'none'}) does not match L${level} (${expected.join(', ')})`, `run /context-level ${level} and restart Claude Code`);
+}
+
+function checkGitHooks(level) {
+  if ((level ?? 0) < 3) return;
+  if (!existsSync(resolve(ROOT, '.git'))) {
+    note('Level ≥ 3 but no .git directory', 'git init, then re-run the installer to add git hooks');
+    return;
+  }
+  for (const h of ['pre-commit', 'commit-msg']) {
+    existsSync(resolve(ROOT, '.git/hooks', h)) ? pass(`git hook ${h} installed`) : note(`git hook ${h} missing`, 're-run the installer');
+  }
+}
+
+function checkMemory() {
+  existsSync(P.sessions) ? pass('memory/sessions present') : note('memory/sessions missing', 're-run the installer');
+  existsSync(resolve(ROOT, 'docs/CHANGELOG.md')) ? pass('docs/CHANGELOG.md present') : note('CHANGELOG missing', 're-run the installer');
+}
+
+function checkSetup() {
+  const completed = loadConfigSync(ROOT)?.setup?.completed === true;
+  completed ? pass('onboarding complete') : note('onboarding not run', 'run /setupcontextdevkit');
+}
+
+function checkRoadmap() {
+  const p = P.roadmap;
+  let defined = false;
+  try {
+    const t = readFileSync(p, 'utf-8');
+    defined = !t.includes('ROADMAP-NOT-DEFINED') && t.trim().length > 0;
+  } catch {
+    /* missing */
+  }
+  defined ? pass('product roadmap defined') : note('product roadmap not defined', 'run /roadmap to create it (with you)');
+}
+
+function checkModuleClaudeMd() {
+  const groups = ['apps', 'packages', 'modules', 'services', 'libs'];
+  const splits = ['backend', 'frontend', 'client', 'server', 'api', 'web', 'mobile', 'functions', 'worker'];
+  const manifests = ['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'tsconfig.json'];
+  const buildable = (d) => manifests.some((m) => existsSync(resolve(d, m))) || existsSync(resolve(d, 'src'));
+  const roots = new Set();
+  for (const s of splits) {
+    const abs = resolve(ROOT, s);
+    if (existsSync(abs) && buildable(abs)) roots.add(s);
+  }
+  for (const g of groups) {
+    const gAbs = resolve(ROOT, g);
+    if (!existsSync(gAbs)) continue;
+    let children = [];
+    try {
+      children = readdirSync(gAbs, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name);
+    } catch {
+      /* skip */
+    }
+    for (const c of children) if (buildable(resolve(gAbs, c))) roots.add(`${g}/${c}`);
+  }
+  if (roots.size === 0) return; // single-package — root CLAUDE.md is enough
+  const missing = [...roots].filter((r) => !existsSync(resolve(ROOT, r, 'CLAUDE.md')));
+  missing.length === 0
+    ? pass(`all ${roots.size} module(s) have a scoped CLAUDE.md`)
+    : note(`${missing.length} module(s) missing CLAUDE.md: ${missing.join(', ')}`, 'run /claude-md to scaffold + fill them');
+}
+
+function checkRemote() {
+  if (!existsSync(resolve(ROOT, '.git'))) return; // not a git repo — /git can init
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    url ? pass(`git remote: ${url}`) : note('no git remote', 'run /git setup-remote (GitHub/GitLab/other)');
+  } catch {
+    note('no git remote configured', 'run /git setup-remote to connect GitHub/GitLab/other + CLI');
+  }
+}
+
+function checkZod(level) {
+  if ((level ?? 0) < 5) return;
+  const hasZod = existsSync(resolve(ROOT, 'node_modules/zod'));
+  hasZod ? pass('zod present (strict /context-config validation enabled)') : note('zod not installed (optional)', 'add zod for strict config validation, or ignore');
+}
+
+console.log('\n🩺 ContextDevKit doctor\n');
+checkNode();
+const level = checkConfig();
+checkWiring(level);
+checkGitHooks(level);
+checkMemory();
+checkSetup();
+checkRoadmap();
+checkModuleClaudeMd();
+checkRemote();
+checkZod(level);
+console.log(
+  crit === 0
+    ? `\n✅ Healthy${warn ? ` (${warn} advisory note${warn > 1 ? 's' : ''})` : ''}.\n`
+    : `\n❌ ${crit} critical issue${crit > 1 ? 's' : ''}${warn ? ` + ${warn} note(s)` : ''}.\n`,
+);
+process.exit(crit === 0 ? 0 : 1);

package/templates/contextkit/tools/scripts/fleet.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * Fleet mode — one control plane over many ContextDevKit repos.
+ *
+ * Aggregates each registered repo's telemetry/scanners and reports cross-repo
+ * CLAUDE.md rule drift. The registry lives OUTSIDE any repo (a true control
+ * plane): `~/.contextdevkit/fleet.json` (override with `CONTEXT_FLEET_FILE`).
+ *
+ *   fleet.mjs list                       # registered repos
+ *   fleet.mjs add <path>                 # register a repo (abs path stored)
+ *   fleet.mjs remove <path>              # unregister
+ *   fleet.mjs stats [--json]            # aggregate stats.mjs across repos
+ *   fleet.mjs audit [--json]            # aggregate deep-analysis findings
+ *   fleet.mjs propagate <rule-file>     # report repos whose CLAUDE.md lacks the rule
+ *
+ * Zero-dependency and defensive: a missing/broken repo is skipped, never throws.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { dirname, basename, resolve } from 'node:path';
+import { readJsonSafe } from '../../runtime/hooks/safe-io.mjs';
+import { resolveHome, readHomeFile, writeHomeFile } from './home.mjs';
+
+const FLEET_NAME = 'fleet.json';
+// CONTEXT_FLEET_FILE overrides the FULL path (used by integration tests). When
+// absent, fleet.json lives in `~/.contextdevkit/` via the home helper (ADR-0020).
+const FLEET_FILE_OVERRIDE = process.env.CONTEXT_FLEET_FILE || null;
+const FLEET_FILE = FLEET_FILE_OVERRIDE || resolve(resolveHome(), FLEET_NAME);
+
+function loadRegistry() {
+  if (FLEET_FILE_OVERRIDE) {
+    const reg = readJsonSafe(FLEET_FILE_OVERRIDE);
+    return reg && Array.isArray(reg.repos) ? reg : { repos: [] };
+  }
+  const reg = readHomeFile(FLEET_NAME);
+  return reg && Array.isArray(reg.repos) ? reg : { repos: [] };
+}
+
+function saveRegistry(reg) {
+  if (FLEET_FILE_OVERRIDE) {
+    const dir = dirname(FLEET_FILE_OVERRIDE);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(FLEET_FILE_OVERRIDE, JSON.stringify(reg, null, 2) + '\n', 'utf-8');
+    return;
+  }
+  writeHomeFile(FLEET_NAME, reg);
+}
+
+/** Run a repo's script with --json and parse the rows. null on any failure. */
+function runRepoJson(repo, rel, args = ['--json']) {
+  const script = resolve(repo, rel);
+  if (!existsSync(script)) return null;
+  try {
+    return JSON.parse(execFileSync(process.execPath, [script, ...args], { cwd: repo, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 60000 }));
+  } catch {
+    return null;
+  }
+}
+
+function isJson() {
+  return process.argv.includes('--json');
+}
+
+function cmdList() {
+  const { repos } = loadRegistry();
+  if (isJson()) return void process.stdout.write(JSON.stringify({ file: FLEET_FILE, repos }, null, 2) + '\n');
+  if (!repos.length) return void console.log(`🛰️  fleet: no repos registered (${FLEET_FILE}).\n   Add one:  node contextkit/tools/scripts/fleet.mjs add <path>`);
+  console.log(`🛰️  fleet: ${repos.length} repo(s) — ${FLEET_FILE}`);
+  for (const r of repos) console.log(`   ${existsSync(resolve(r, 'contextkit')) ? '✓' : '⚠'} ${r}`);
+}
+
+function cmdAdd() {
+  const input = process.argv[3];
+  if (!input) return void fail('Usage: fleet.mjs add <path>');
+  const abs = resolve(process.cwd(), input);
+  if (!existsSync(abs)) return void fail(`Path not found: ${abs}`);
+  const reg = loadRegistry();
+  if (reg.repos.includes(abs)) return void console.log(`already registered: ${abs}`);
+  reg.repos.push(abs);
+  saveRegistry(reg);
+  console.log(`🛰️  fleet: registered ${abs} (${reg.repos.length} total).`);
+}
+
+function cmdRemove() {
+  const abs = resolve(process.cwd(), process.argv[3] || '');
+  const reg = loadRegistry();
+  const next = reg.repos.filter((r) => r !== abs);
+  saveRegistry({ ...reg, repos: next });
+  console.log(next.length === reg.repos.length ? `not registered: ${abs}` : `🛰️  fleet: removed ${abs}.`);
+}
+
+function cmdStats() {
+  const { repos } = loadRegistry();
+  const rows = repos.map((repo) => {
+    const s = runRepoJson(repo, 'contextkit/tools/scripts/stats.mjs');
+    if (!s) return { path: repo, name: basename(repo), ok: false };
+    return { path: repo, name: basename(repo), ok: true, level: s.level, registeredSessions: s.registeredSessions, adrs: s.adrs, agents: s.agents, driftRatePct: s.driftRatePct, forge: s.forge || null };
+  });
+  const ok = rows.filter((r) => r.ok);
+  const forgeRows = ok.filter((r) => r.forge);
+  const totals = {
+    repos: rows.length,
+    withStats: ok.length,
+    totalSessions: ok.reduce((a, r) => a + (r.registeredSessions || 0), 0),
+    totalAdrs: ok.reduce((a, r) => a + (r.adrs || 0), 0),
+    avgDriftPct: ok.length ? +(ok.reduce((a, r) => a + (r.driftRatePct || 0), 0) / ok.length).toFixed(1) : 0,
+    forge: forgeRows.length ? {
+      repos: forgeRows.length,
+      packages: forgeRows.reduce((a, r) => a + (r.forge.packages || 0), 0),
+      evaluated: forgeRows.reduce((a, r) => a + (r.forge.evaluated || 0), 0),
+      monthlyTarget: +forgeRows.reduce((a, r) => a + (r.forge.monthlyTarget || 0), 0).toFixed(2),
+      monthlyHardCap: +forgeRows.reduce((a, r) => a + (r.forge.monthlyHardCap || 0), 0).toFixed(2),
+    } : null,
+  };
+  if (isJson()) return void process.stdout.write(JSON.stringify({ repos: rows, totals }, null, 2) + '\n');
+  console.log(`🛰️  fleet stats — ${totals.repos} repo(s), ${totals.totalSessions} sessions, ${totals.totalAdrs} ADRs, avg drift ${totals.avgDriftPct}%\n`);
+  for (const r of rows) {
+    if (!r.ok) {
+      console.log(`   ${r.name}  (no stats — not a ContextDevKit repo?)`);
+      continue;
+    }
+    const forge = r.forge ? `  🔥 ${r.forge.packages} pkg (${r.forge.evaluated}✅)` : '';
+    console.log(`   ${r.name}  L${r.level}  ${r.registeredSessions} sess  ${r.adrs} ADR  ${r.agents} agents  ${r.driftRatePct}% drift${forge}`);
+  }
+  if (totals.forge) {
+    console.log(`\n🔥 Forge fleet: ${totals.forge.packages} packages across ${totals.forge.repos} repo(s), ${totals.forge.evaluated} eval-stamped, monthly target $${totals.forge.monthlyTarget} / hard cap $${totals.forge.monthlyHardCap}`);
+  }
+}
+
+function cmdAudit() {
+  const { repos } = loadRegistry();
+  const rows = repos.map((repo) => {
+    const a = runRepoJson(repo, 'contextkit/tools/scripts/deep-analysis.mjs');
+    if (!a || typeof a.total !== 'number') return { path: repo, name: basename(repo), ok: false };
+    return { path: repo, name: basename(repo), ok: true, total: a.total, byScan: a.byScan || {} };
+  });
+  const ok = rows.filter((r) => r.ok);
+  const totals = { repos: rows.length, scanned: ok.length, totalFindings: ok.reduce((a, r) => a + r.total, 0) };
+  if (isJson()) return void process.stdout.write(JSON.stringify({ repos: rows, totals }, null, 2) + '\n');
+  console.log(`🛰️  fleet audit — ${totals.totalFindings} finding(s) across ${totals.scanned}/${totals.repos} repo(s)\n`);
+  for (const r of rows) console.log(r.ok ? `   ${r.name}  ${r.total} finding(s)` : `   ${r.name}  (no analyzer)`);
+}
+
+function cmdPropagate() {
+  const ruleFile = process.argv[3];
+  if (!ruleFile || !existsSync(ruleFile)) return void fail('Usage: fleet.mjs propagate <rule-file>  (a CLAUDE.md rule snippet)');
+  const snippet = readFileSync(ruleFile, 'utf-8').trim();
+  const key = snippet.split('\n').find((l) => l.trim().length > 12)?.trim() || snippet.slice(0, 40);
+  const { repos } = loadRegistry();
+  const rows = repos.map((repo) => {
+    const claudeMd = resolve(repo, 'CLAUDE.md');
+    const has = existsSync(claudeMd) && readFileSync(claudeMd, 'utf-8').includes(key);
+    return { path: repo, name: basename(repo), present: has };
+  });
+  const missing = rows.filter((r) => !r.present);
+  if (isJson()) return void process.stdout.write(JSON.stringify({ key, missing: missing.map((r) => r.path), checked: rows }, null, 2) + '\n');
+  console.log(`🛰️  fleet propagate (detect-only) — rule absent in ${missing.length}/${rows.length} repo(s):\n   key: "${key}"\n`);
+  for (const r of rows) console.log(`   ${r.present ? '✓ has ' : '✗ MISSING'}  ${r.name}`);
+  if (missing.length) console.log(`\n   Add the rule to each MISSING repo's CLAUDE.md (reviewed, per-repo) — fleet does not auto-edit.`);
+}
+
+function fail(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
+const cmd = process.argv[2];
+const table = { list: cmdList, add: cmdAdd, remove: cmdRemove, stats: cmdStats, audit: cmdAudit, propagate: cmdPropagate };
+if (table[cmd]) table[cmd]();
+else fail('Usage: fleet.mjs <list|add|remove|stats|audit|propagate> [...]');

package/templates/contextkit/tools/scripts/generate-context.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * On-demand full-project snapshot → `.context-snapshot.md` (gitignored).
+ *
+ * STACK-AGNOSTIC. Produces a single document useful for:
+ *   - A brutal refactor where Claude needs to see the whole tree at once.
+ *   - Pasting into another AI (ChatGPT, Gemini) that lacks the boot hook.
+ *   - Impact analysis ("what breaks if I change X?").
+ *
+ * Contents: folder tree (depth-limited), detected stack, latest session,
+ * CHANGELOG `[Unreleased]`, and a glossary excerpt. Best-effort, never throws.
+ *
+ * Usage:  node contextkit/tools/scripts/generate-context.mjs
+ */
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const OUTPUT = resolve(ROOT, '.context-snapshot.md');
+const MAX_DEPTH = 4;
+const IGNORE = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.next', '.turbo', '.expo', 'coverage', '__pycache__', 'target', 'vendor', '.claude']);
+
+async function readSafe(rel) {
+  try {
+    return await readFile(resolve(ROOT, rel), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+async function buildTree(dir, prefix = '', depth = 0) {
+  if (depth > MAX_DEPTH) return [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  entries = entries.filter((e) => !(e.isDirectory() && IGNORE.has(e.name)) && !e.name.startsWith('.tmp'));
+  entries.sort((a, b) => (a.isDirectory() === b.isDirectory() ? a.name.localeCompare(b.name) : a.isDirectory() ? -1 : 1));
+  const lines = [];
+  for (const e of entries.slice(0, 60)) {
+    lines.push(`${prefix}${e.isDirectory() ? '📁' : '📄'} ${e.name}`);
+    if (e.isDirectory()) lines.push(...(await buildTree(resolve(dir, e.name), prefix + '  ', depth + 1)));
+  }
+  return lines;
+}
+
+async function detectStack() {
+  const hints = [];
+  const pkgRaw = await readSafe('package.json');
+  if (pkgRaw) {
+    try {
+      const pkg = JSON.parse(pkgRaw);
+      const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+      hints.push(`**package.json** — ${Object.keys(deps).length} deps. Key: ${Object.keys(deps).slice(0, 15).join(', ')}`);
+    } catch {
+      /* ignore */
+    }
+  }
+  for (const [file, label] of [
+    ['pyproject.toml', 'Python (pyproject.toml)'],
+    ['go.mod', 'Go (go.mod)'],
+    ['Cargo.toml', 'Rust (Cargo.toml)'],
+    ['pom.xml', 'Java (Maven)'],
+    ['Gemfile', 'Ruby (Gemfile)'],
+  ]) {
+    if (await readSafe(file)) hints.push(`**${label}**`);
+  }
+  return hints.length ? hints.map((h) => `- ${h}`).join('\n') : '_(no recognized manifest)_';
+}
+
+async function latestSession() {
+  let files = [];
+  try {
+    files = await readdir(P.sessions);
+  } catch {
+    return null;
+  }
+  const entries = files.filter((f) => /^\d{4}-\d{2}-\d{2}-\d{2,}-.+\.md$/.test(f)).sort((a, b) => Number.parseInt(b.split('-')[3], 10) - Number.parseInt(a.split('-')[3], 10));
+  if (!entries.length) return null;
+  const content = await readSafe(`contextkit/memory/sessions/${entries[0]}`);
+  return content ? content.split('\n').slice(0, 40).join('\n') : null;
+}
+
+function unreleased(changelog) {
+  if (!changelog) return null;
+  const lines = changelog.split('\n');
+  const start = lines.findIndex((l) => /^##\s+\[Unreleased\]/i.test(l));
+  if (start === -1) return null;
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((l) => /^##\s+\[/.test(l) || l.trim() === '---');
+  return rest.slice(0, end === -1 ? 40 : end).join('\n').trim();
+}
+
+async function main() {
+  const out = [];
+  out.push(`# Context Snapshot — ${new Date().toISOString().slice(0, 10)}`);
+  out.push('');
+  out.push('> Generated by `generate-context`. Gitignored, ephemeral. Do not commit.');
+  out.push('');
+  out.push('## Detected stack');
+  out.push('');
+  out.push(await detectStack());
+  out.push('');
+  out.push('## Project tree (depth ≤ 4)');
+  out.push('');
+  out.push('```');
+  out.push(...(await buildTree(ROOT)));
+  out.push('```');
+  out.push('');
+  const session = await latestSession();
+  if (session) {
+    out.push('## Latest session');
+    out.push('');
+    out.push(session);
+    out.push('');
+  }
+  const unrel = unreleased(await readSafe('docs/CHANGELOG.md'));
+  if (unrel) {
+    out.push('## CHANGELOG [Unreleased]');
+    out.push('');
+    out.push(unrel);
+    out.push('');
+  }
+  const glossary = await readSafe('contextkit/memory/GLOSSARY.md');
+  if (glossary) {
+    out.push('## Glossary (excerpt)');
+    out.push('');
+    out.push(glossary.split('\n').slice(0, 40).join('\n'));
+    out.push('');
+  }
+  await writeFile(OUTPUT, out.join('\n'), 'utf-8');
+  console.log(`✅ .context-snapshot.md regenerated (${out.length} lines).`);
+}
+
+main().catch((err) => {
+  console.error('❌ Failed to generate context snapshot:', err);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/gh-alerts.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * GitHub security alerts → findings (the loop-closer).
+ *
+ * Pulls Dependabot + code-scanning alerts via the `gh` CLI and shapes them like
+ * deps-audit findings, so `pipeline.mjs ingest` turns GitHub's alerts into
+ * prioritized, owned backlog tasks. The `code-security` agent then triages them.
+ *
+ *   node .../gh-alerts.mjs            # console summary
+ *   node .../gh-alerts.mjs --json     # { findings: [...] }
+ *   node .../gh-alerts.mjs --write    # → contextkit/memory/gh-alerts-findings.json
+ *
+ * Defensive: needs an authenticated `gh` + a GitHub repo. If `gh` is missing,
+ * unauthenticated, offline, or the repo has no GitHub remote, it reports nothing
+ * and exits 0 — never throws, never blocks.
+ */
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const SEV = { critical: 5, high: 4, medium: 3, moderate: 3, low: 2, warning: 2, error: 4, note: 1 };
+const findings = [];
+
+/** Maps one Dependabot alert (GitHub API shape) to a deps-audit-style finding. Pure. */
+export function mapDependabotAlert(alert) {
+  const sev = alert?.security_advisory?.severity || alert?.security_vulnerability?.severity || 'low';
+  const pkg = alert?.dependency?.package?.name || 'dependency';
+  const file = alert?.dependency?.manifest_path || 'package.json';
+  return {
+    kind: 'dependabot',
+    severity: SEV[String(sev).toLowerCase()] || 2,
+    path: file,
+    message: `\`${pkg}\`: ${sev} — ${alert?.security_advisory?.summary || 'Dependabot advisory'} (${alert?.security_advisory?.ghsa_id || 'GHSA ?'}).`,
+    source: `gh:dependabot:${file}`,
+  };
+}
+
+/** Maps one code-scanning alert (GitHub API shape) to a finding. Pure. */
+export function mapCodeScanningAlert(alert) {
+  const sev = alert?.rule?.security_severity_level || alert?.rule?.severity || 'warning';
+  const file = alert?.most_recent_instance?.location?.path || 'code';
+  return {
+    kind: 'code-scanning',
+    severity: SEV[String(sev).toLowerCase()] || 2,
+    path: file,
+    message: `${alert?.rule?.id || 'rule'}: ${alert?.rule?.description || alert?.most_recent_instance?.message?.text || 'code-scanning alert'}.`,
+    source: `gh:code-scanning:${file}`,
+  };
+}
+
+function gh(args) {
+  return execFileSync('gh', args, { cwd: ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 30000 });
+}
+
+function repoNwo() {
+  try {
+    return JSON.parse(gh(['repo', 'view', '--json', 'nameWithOwner'])).nameWithOwner || null;
+  } catch {
+    return null;
+  }
+}
+
+function apiJson(path) {
+  try {
+    return JSON.parse(gh(['api', '-H', 'Accept: application/vnd.github+json', '--paginate', path]) || 'null');
+  } catch {
+    return null;
+  }
+}
+
+function dependabotAlerts(repo) {
+  const alerts = apiJson(`repos/${repo}/dependabot/alerts?state=open&per_page=100`);
+  if (!Array.isArray(alerts)) return;
+  for (const a of alerts) findings.push(mapDependabotAlert(a));
+}
+
+function codeScanningAlerts(repo) {
+  const alerts = apiJson(`repos/${repo}/code-scanning/alerts?state=open&per_page=100`);
+  if (!Array.isArray(alerts)) return;
+  for (const a of alerts) findings.push(mapCodeScanningAlert(a));
+}
+
+function main() {
+  const repo = repoNwo();
+  if (!repo) {
+    if (process.argv.includes('--json')) process.stdout.write('{"findings":[]}\n');
+    else console.log('🔐 gh-alerts: no GitHub repo / `gh` unavailable — nothing to sync.');
+    return;
+  }
+  dependabotAlerts(repo);
+  codeScanningAlerts(repo);
+  const report = { findings };
+
+  if (process.argv.includes('--write')) {
+    writeFileSync(resolve(P.memory, 'gh-alerts-findings.json'), JSON.stringify(report, null, 2), 'utf-8');
+    console.log(`🔐 gh-alerts: ${findings.length} alert(s) → contextkit/memory/gh-alerts-findings.json`);
+    console.log('   → feed the backlog:  node contextkit/tools/scripts/pipeline.mjs ingest contextkit/memory/gh-alerts-findings.json --type chore');
+    return;
+  }
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return;
+  }
+  if (findings.length === 0) {
+    console.log(`🔐 gh-alerts: no open alerts for ${repo} (or none accessible).`);
+    return;
+  }
+  console.log(`🔐 gh-alerts: ${findings.length} open alert(s) for ${repo}.`);
+  for (const f of [...findings].sort((a, b) => b.severity - a.severity)) console.log(`   ${'●'.repeat(f.severity)} ${f.kind} — ${f.message}`);
+}
+
+// Auto-run only when invoked as a script; importing (for tests) is side-effect-free.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();