contextdevkit 1.8.0

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Squad helper — the deterministic half of `/squad` (the command adds judgment).
+ *
+ * Scaffolds the **tier-2 rich briefing** for an agent into its squad folder, so
+ * the two-tier pattern (lean agent in `.claude/agents/` + deep briefing in
+ * `contextkit/squads/<squad>/`) is real, not just convention.
+ *
+ *   node .../squad.mjs list             # agents + which have a tier-2 briefing
+ *   node .../squad.mjs brief <agent>    # scaffold contextkit/squads/<squad>/<agent>.md
+ *
+ * Squad detection: `qa-*` → qa-team; otherwise the `(... squad)` / `(...-team)`
+ * tag in the agent's `description`; falls back to `devteam`.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { squadOf } from './squad-meta.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const AGENTS = resolve(ROOT, '.claude/agents');
+const SQUADS = pathsFor(ROOT).squads;
+const squadFor = (agent) => squadOf(AGENTS, agent);
+
+function listAgents() {
+  try {
+    return readdirSync(AGENTS).filter((f) => f.endsWith('.md') && f !== '_TEMPLATE.md').map((f) => f.slice(0, -3));
+  } catch {
+    return [];
+  }
+}
+
+function brief() {
+  const agent = process.argv[3];
+  if (!agent) {
+    console.error('Usage: squad.mjs brief <agent>');
+    process.exit(1);
+  }
+  if (!existsSync(resolve(AGENTS, `${agent}.md`))) {
+    console.error(`No agent at .claude/agents/${agent}.md (Level < 4?).`);
+    process.exit(1);
+  }
+  const squad = squadFor(agent);
+  mkdirSync(resolve(SQUADS, squad), { recursive: true });
+  const dest = resolve(SQUADS, squad, `${agent}.md`);
+  if (existsSync(dest)) {
+    console.log(`ℹ️  Briefing already exists: contextkit/squads/${squad}/${agent}.md`);
+    return;
+  }
+  let tpl = '# {{AGENT}} — rich briefing ({{SQUAD}} squad)\n';
+  try {
+    tpl = readFileSync(resolve(SQUADS, '_BRIEFING.md.tpl'), 'utf-8');
+  } catch {
+    /* fall back to the one-line stub */
+  }
+  writeFileSync(dest, tpl.replaceAll('{{AGENT}}', agent).replaceAll('{{SQUAD}}', squad), 'utf-8');
+  console.log(`✅ Scaffolded contextkit/squads/${squad}/${agent}.md — now fill it with real anti-patterns / recipes / edge cases.`);
+}
+
+function list() {
+  const agents = listAgents();
+  if (agents.length === 0) {
+    console.log('No agents found (Level < 4?). Run /context-level 4 to install the squads.');
+    return;
+  }
+  console.log(`👥 ${agents.length} agents (📄 = has a tier-2 briefing):`);
+  for (const a of agents) {
+    const squad = squadFor(a);
+    const has = existsSync(resolve(SQUADS, squad, `${a}.md`));
+    console.log(`   ${has ? '📄' : '  '} ${a} — ${squad}`);
+  }
+}
+
+const cmd = process.argv[2];
+if (cmd === 'brief') brief();
+else if (cmd === 'list') list();
+else {
+  console.error('Usage: squad.mjs <list | brief <agent>>');
+  process.exit(1);
+}

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

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Platform telemetry — how healthy is the ContextDevKit practice on this project?
+ *
+ * Reports: registered sessions, sessions per ISO week, avg files/session,
+ * drift rate (Stop hook had to nudge), ADR count, agents installed, level.
+ * Reads archived ledgers in `.claude/.sessions/.archive/` + live ledgers, and
+ * the memory tree. Zero-dependency.
+ *
+ * Usage:  node contextkit/tools/scripts/stats.mjs [--json]
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getLevel } from '../../runtime/config/load.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+import { readJsonSafe } from '../../runtime/hooks/safe-io.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+
+const readJson = (p) => readJsonSafe(p);
+
+function listJson(dir) {
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => readJson(resolve(dir, f))).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function count(dir, re) {
+  try {
+    return readdirSync(dir).filter((f) => re.test(f)).length;
+  } catch {
+    return 0;
+  }
+}
+
+function isoWeek(ms) {
+  const d = new Date(ms);
+  const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  t.setUTCDate(t.getUTCDate() - ((t.getUTCDay() + 6) % 7) + 3);
+  const firstThu = new Date(Date.UTC(t.getUTCFullYear(), 0, 4));
+  const week = 1 + Math.floor(Math.round((t - firstThu) / 86_400_000) / 7);
+  return `${t.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}
+
+function collectForge() {
+  const root = resolve(ROOT, 'agent-packages');
+  let entries = [];
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return null; }
+  const pkgs = entries.filter((entry) => entry.isDirectory() && /^[a-z][a-z0-9-]*@\d+\.\d+\.\d+/.test(entry.name));
+  if (!pkgs.length) return null;
+  let evaluated = 0;
+  let monthlyTarget = 0;
+  let monthlyHardCap = 0;
+  const byPrimary = {};
+  for (const entry of pkgs) {
+    const manifestPath = resolve(root, entry.name, 'manifest.yaml');
+    let manifest = '';
+    try { manifest = readFileSync(manifestPath, 'utf-8'); } catch { continue; }
+    const evalLine = manifest.match(/eval_passed_at:\s*['"]?([^'\n]+)['"]?/);
+    if (evalLine && evalLine[1].trim() !== 'null') evaluated += 1;
+    const target = Number((manifest.match(/monthly_budget_usd:\s*([\d.]+)/) || [])[1] || 0);
+    monthlyTarget += target;
+    monthlyHardCap += Math.round(target * 1.5);
+    const providerMatch = manifest.match(/primary:\s*\n\s*provider:\s*(\w[\w-]*)/);
+    const provider = providerMatch ? providerMatch[1] : 'unknown';
+    byPrimary[provider] = (byPrimary[provider] || 0) + 1;
+  }
+  return { packages: pkgs.length, evaluated, unevaluated: pkgs.length - evaluated, monthlyTarget, monthlyHardCap, byPrimary };
+}
+
+function collect() {
+  const ledgers = [
+    ...listJson(resolve(ROOT, '.claude/.sessions')),
+    ...listJson(resolve(ROOT, '.claude/.sessions/.archive')),
+  ];
+  const registeredSessions = count(P.sessions, /^\d{4}-\d{2}-\d{2}-\d{2,}-.+\.md$/);
+  const adrs = count(P.decisions, /^\d{4}-.+\.md$/);
+  const agents = count(resolve(ROOT, '.claude/agents'), /\.md$/);
+  const commands = count(resolve(ROOT, '.claude/commands'), /\.md$/);
+  const forge = collectForge();
+
+  const perWeek = {};
+  let totalFiles = 0;
+  let nudged = 0;
+  for (const l of ledgers) {
+    if (typeof l.startedAt === 'number') perWeek[isoWeek(l.startedAt)] = (perWeek[isoWeek(l.startedAt)] || 0) + 1;
+    totalFiles += new Set((l.modifications || []).map((m) => m.path)).size;
+    if (typeof l.stopWarnedAt === 'number') nudged += 1;
+  }
+  const n = ledgers.length || 1;
+  return {
+    level: getLevel(ROOT),
+    registeredSessions,
+    ledgersSeen: ledgers.length,
+    avgFilesPerSession: +(totalFiles / n).toFixed(1),
+    driftRatePct: +((nudged / n) * 100).toFixed(1),
+    adrs,
+    agents,
+    commands,
+    perWeek,
+    forge,
+  };
+}
+
+function main() {
+  const s = collect();
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(s, null, 2) + '\n');
+    return;
+  }
+  console.log('📊 ContextDevKit stats\n');
+  console.log(`Level:                 L${s.level}`);
+  console.log(`Registered sessions:   ${s.registeredSessions}`);
+  console.log(`ADRs:                  ${s.adrs}`);
+  console.log(`Agents / commands:     ${s.agents} / ${s.commands}`);
+  console.log(`Ledgers analyzed:      ${s.ledgersSeen}`);
+  console.log(`Avg files / session:   ${s.avgFilesPerSession}`);
+  console.log(`Drift rate (nudged):   ${s.driftRatePct}%`);
+  const weeks = Object.entries(s.perWeek).sort();
+  if (weeks.length) {
+    console.log('\nSessions per ISO week:');
+    for (const [w, c] of weeks) console.log(`  ${w}  ${'█'.repeat(c)} (${c})`);
+  }
+  if (s.forge) {
+    console.log('\n🔥 Forge Stats (agent-packages/)');
+    console.log(`  Packages:           ${s.forge.packages}`);
+    console.log(`  Eval-stamped:       ${s.forge.evaluated} / ${s.forge.packages}` + (s.forge.unevaluated ? `  ⚠️  ${s.forge.unevaluated} unevaluated` : ''));
+    console.log(`  Monthly target:     $${s.forge.monthlyTarget.toFixed(2)}`);
+    console.log(`  Monthly hard cap:   $${s.forge.monthlyHardCap.toFixed(2)}`);
+    const providers = Object.entries(s.forge.byPrimary).sort((a, b) => b[1] - a[1]);
+    if (providers.length) console.log('  By primary provider: ' + providers.map(([p, c]) => `${p}=${c}`).join(', '));
+  }
+}
+
+main();

package/templates/contextkit/tools/scripts/sync-check.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * GitHub sync awareness — facts for `/dev-start` (preflight) and `/git pr` (prepr).
+ *
+ * The boot banner already shows branch/commit divergence and recent branches;
+ * `pre-push` blocks textual conflicts. This script adds the missing **PR** layer
+ * at the two moments that matter, WITHOUT touching the SessionStart hot path:
+ *
+ *   - preflight (before coding): ahead/behind, recent in-flight branches, and
+ *     OPEN PRs with CI/review status — flagging PRs *awaiting status* that may
+ *     overlap the objective.
+ *   - prepr (before opening a PR): re-check divergence vs the default branch and
+ *     detect a DUPLICATE open PR for the current branch.
+ *
+ * `gh` is optional. Absent/unauthed ⇒ the git-only half runs and the PR half is
+ * reported as **skipped, never a pass** (Rule 8). No remote / offline ⇒ silent,
+ * exit 0. Read-only: it never creates, edits, or merges a PR. Zero deps. [ADR-0026]
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/sync-check.mjs preflight [--json]
+ *   node contextkit/tools/scripts/sync-check.mjs prepr     [--json]
+ */
+import { execFileSync } from 'node:child_process';
+
+const ROOT = process.cwd();
+
+/**
+ * Hard ceiling (ms) for any git/`gh` subprocess. A hung `git fetch` or `gh pr
+ * list` against an unreachable remote must not freeze the dev flow. On timeout
+ * `execFileSync` throws → `run()` returns `{ ok:false }` (the failed-command
+ * path) and the report degrades gracefully. Env-overridable for fast tests.
+ */
+const CMD_TIMEOUT_MS = Number.parseInt(process.env.CONTEXT_GIT_TIMEOUT_MS || '', 10) || 10000;
+
+/** PR fields pulled from `gh` — enough to derive checks + review status. */
+const PR_FIELDS = 'number,title,headRefName,state,statusCheckRollup,reviewDecision,updatedAt,url,isDraft';
+
+function run(cmd, args) {
+  try {
+    return { ok: true, out: execFileSync(cmd, args, { cwd: ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: CMD_TIMEOUT_MS }).trim() };
+  } catch (err) {
+    return { ok: false, out: '', code: err?.status };
+  }
+}
+
+function int(value) {
+  return Number.parseInt(value ?? '0', 10) || 0;
+}
+
+/** Strip a UTF-8 BOM and parse; returns null on any malformation (Rule 4). */
+function parseJson(text) {
+  try {
+    return JSON.parse(text.replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+function currentBranch() {
+  return run('git', ['symbolic-ref', '--short', 'HEAD']).out || null;
+}
+
+function hasRemote() {
+  return Boolean(run('git', ['remote', 'get-url', 'origin']).out);
+}
+
+/** The default branch (origin/HEAD target), falling back to "main". */
+function mainBranch() {
+  const ref = run('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+  return ref.ok && ref.out ? ref.out.replace(/^origin\//, '') : 'main';
+}
+
+/**
+ * ahead/behind after a best-effort fetch. Prefers the branch's own upstream
+ * (`@{u}`); a branch with no upstream (fresh feature branch) falls back to
+ * `origin/<main>` so "am I behind the trunk?" still answers. null when unknowable.
+ */
+function divergence(main) {
+  run('git', ['fetch', 'origin', '--quiet']);
+  const upstream = run('git', ['rev-list', '--left-right', '--count', 'HEAD...@{u}']);
+  if (upstream.ok) {
+    const [a, b] = upstream.out.split(/\s+/);
+    return { ahead: int(a), behind: int(b), against: '@{u}' };
+  }
+  const trunk = run('git', ['rev-list', '--left-right', '--count', `HEAD...origin/${main}`]);
+  if (!trunk.ok) return null;
+  const [a, b] = trunk.out.split(/\s+/);
+  return { ahead: int(a), behind: int(b), against: `origin/${main}` };
+}
+
+/** The 20 most-recent OTHER remote branches (in-flight work), newest first. */
+function recentBranches(branch, limit = 20) {
+  const r = run('git', ['for-each-ref', '--sort=-committerdate', `--count=${limit}`, '--format=%(refname:short)|%(committerdate:relative)|%(authorname)', 'refs/remotes']);
+  if (!r.ok) return [];
+  return r.out.split('\n').map((line) => line.trim()).filter(Boolean)
+    .map((line) => line.split('|'))
+    .filter(([ref]) => ref && ref.includes('/') && !/\/(main|master|HEAD)$/.test(ref) && ref !== `origin/${branch}`)
+    .map(([ref, age, author]) => ({ ref, age, author }));
+}
+
+/** `gh` is usable only when installed AND authenticated. */
+function ghReady() {
+  return run('gh', ['--version']).ok && run('gh', ['auth', 'status']).ok;
+}
+
+/** Collapse a PR's check-rollup into one of: passing | failing | pending | none. */
+function rollupChecks(rollup) {
+  if (!Array.isArray(rollup) || rollup.length === 0) return 'none';
+  let pending = false;
+  let failing = false;
+  for (const check of rollup) {
+    const { status, conclusion, state } = check ?? {};
+    if (state === 'PENDING' || (status && status !== 'COMPLETED')) pending = true;
+    if (['FAILURE', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(conclusion)) failing = true;
+    if (state === 'FAILURE' || state === 'ERROR') failing = true;
+  }
+  if (failing) return 'failing';
+  if (pending) return 'pending';
+  return 'passing';
+}
+
+function reviewLabel(decision) {
+  if (decision === 'APPROVED') return 'approved';
+  if (decision === 'CHANGES_REQUESTED') return 'changes-requested';
+  if (decision === 'REVIEW_REQUIRED') return 'review-required';
+  return 'none';
+}
+
+/** Project a raw `gh` PR into the kit's summary shape + the "awaiting" verdict. */
+function summarizePr(pr) {
+  const checks = rollupChecks(pr.statusCheckRollup);
+  const review = reviewLabel(pr.reviewDecision);
+  const awaiting = checks === 'pending' || checks === 'failing' || review === 'review-required' || review === 'changes-requested';
+  return { number: pr.number, title: pr.title, head: pr.headRefName, draft: Boolean(pr.isDraft), url: pr.url, updated: pr.updatedAt, checks, review, awaiting };
+}
+
+/** Open PRs (optionally filtered), or null when `gh` couldn't answer (a SKIP). */
+function listOpenPRs(extraArgs = []) {
+  const r = run('gh', ['pr', 'list', '--state', 'open', '--limit', '30', '--json', PR_FIELDS, ...extraArgs]);
+  if (!r.ok) return null;
+  const parsed = parseJson(r.out);
+  return Array.isArray(parsed) ? parsed.map(summarizePr) : null;
+}
+
+function preflight() {
+  const branch = currentBranch();
+  const remote = hasRemote();
+  const main = mainBranch();
+  const ghOk = remote && ghReady();
+  return {
+    mode: 'preflight',
+    branch,
+    remote,
+    divergence: remote ? divergence(main) : null,
+    recentBranches: remote ? recentBranches(branch) : [],
+    ghReady: ghOk,
+    prs: ghOk ? listOpenPRs() : null,
+  };
+}
+
+function prepr() {
+  const branch = currentBranch();
+  const remote = hasRemote();
+  const main = mainBranch();
+  const ghOk = remote && ghReady();
+  const branchPrs = ghOk && branch ? listOpenPRs(['--head', branch]) : null;
+  return {
+    mode: 'prepr',
+    branch,
+    main,
+    remote,
+    divergence: remote ? divergence(main) : null,
+    ghReady: ghOk,
+    existingPr: Array.isArray(branchPrs) && branchPrs.length ? branchPrs[0] : (ghOk ? null : undefined),
+  };
+}
+
+function printPreflight(s) {
+  console.log('🔄 Sync preflight\n');
+  console.log(`branch:      ${s.branch ?? '—'}`);
+  if (!s.remote) { console.log('remote:      NONE → nothing to sync against yet.'); return; }
+  if (s.divergence) console.log(`sync:        ahead ${s.divergence.ahead} / behind ${s.divergence.behind} (vs ${s.divergence.against})`);
+  if (s.recentBranches.length) {
+    console.log('\nRecent remote branches (in flight):');
+    for (const b of s.recentBranches.slice(0, 8)) console.log(`  - ${b.ref} — ${b.age} by ${b.author}`);
+  }
+  if (!s.ghReady) { console.log('\nPR checks skipped (gh not installed/authed) — git-only view above.'); return; }
+  if (s.prs == null) { console.log('\nPR checks skipped (gh query failed) — git-only view above.'); return; }
+  if (s.prs.length === 0) { console.log('\nOpen PRs: none.'); return; }
+  console.log(`\nOpen PRs (${s.prs.length}):`);
+  for (const pr of s.prs) {
+    console.log(`  #${pr.number} ${pr.awaiting ? '⏳ awaiting' : '✓ ready'} — ${pr.title}`);
+    console.log(`     head ${pr.head} · checks ${pr.checks} · review ${pr.review}${pr.draft ? ' · draft' : ''}`);
+  }
+  const awaiting = s.prs.filter((pr) => pr.awaiting).length;
+  if (awaiting) console.log(`\n→ ${awaiting} PR(s) awaiting status/review — check overlap with your objective before coding.`);
+}
+
+function printPrepr(s) {
+  console.log('🔄 Pre-PR check\n');
+  console.log(`branch:      ${s.branch ?? '—'}`);
+  if (!s.remote) { console.log('remote:      NONE → set one up with /git before opening a PR.'); return; }
+  if (s.divergence) {
+    console.log(`sync:        ahead ${s.divergence.ahead} / behind ${s.divergence.behind} (vs ${s.divergence.against})`);
+    if (s.divergence.behind > 0) console.log(`  ⚠️  behind by ${s.divergence.behind} — rebase first: git pull --rebase origin ${s.main}`);
+  }
+  if (!s.ghReady) { console.log('\nPR dedupe skipped (gh not installed/authed) — verify manually before opening.'); return; }
+  if (!s.existingPr) { console.log('\nNo open PR for this branch — safe to create one.'); return; }
+  const pr = s.existingPr;
+  console.log(`\n⚠️  An open PR already exists for ${pr.head}:`);
+  console.log(`  #${pr.number} — ${pr.title}`);
+  console.log(`  ${pr.url}`);
+  console.log(`  checks ${pr.checks} · review ${pr.review}${pr.draft ? ' · draft' : ''}`);
+  console.log('  → Push to update it instead of creating a duplicate.');
+}
+
+const mode = process.argv[2];
+const asJson = process.argv.includes('--json');
+
+if (mode !== 'preflight' && mode !== 'prepr') {
+  console.error('Usage: sync-check.mjs <preflight|prepr> [--json]');
+  process.exit(2);
+}
+
+try {
+  const summary = mode === 'preflight' ? preflight() : prepr();
+  if (asJson) console.log(JSON.stringify(summary, null, 2));
+  else if (mode === 'preflight') printPreflight(summary);
+  else printPrepr(summary);
+  process.exit(0);
+} catch (err) {
+  // Never break the dev flow — degrade to a one-line note (Rule 2).
+  process.stderr.write(`[sync-check] ${err?.message ?? err}\n`);
+  process.exit(0);
+}

package/templates/contextkit/tools/scripts/tech-debt-detectors.mjs

@@ -0,0 +1,76 @@
+/**
+ * Tech-debt detectors — pure functions over file content, STACK-AGNOSTIC.
+ *
+ * Each detector takes `(relPath, content, opts)` and returns findings:
+ *   { kind, severity, path, line?, snippet?, message }
+ *   severity: 1..5 (5 = blocker, 1 = nit)
+ *
+ * Regex-based (no AST) so the scan is fast and dependency-free. False
+ * positives are acceptable — the board is human-reviewed, not enforcing.
+ */
+
+const CODE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|swift|c|cpp|cs)$/;
+
+/** File length vs the constitution's line budget (configurable). */
+export function detectLineBudget(relPath, content, { yellow = 240, red = 308 } = {}) {
+  const total = content.split('\n').length;
+  if (total > red) {
+    return [{ kind: 'line-budget', severity: 5, path: relPath, line: total, message: `${total} lines — RED ZONE (> ${red}). Split by responsibility.` }];
+  }
+  if (total >= yellow) {
+    return [{ kind: 'line-budget', severity: 3, path: relPath, line: total, message: `${total} lines — yellow zone (>= ${yellow}). Plan a split or document cohesion at the top.` }];
+  }
+  return [];
+}
+
+/** Identifiers whose names join two responsibilities ("And"/"Or"/"E"). */
+export function detectSrpAnd(relPath, content) {
+  if (!CODE_RE.test(relPath)) return [];
+  const findings = [];
+  const lines = content.split('\n');
+  const jsDecl = /(?:function\s+|const\s+|let\s+|var\s+|async\s+function\s+|export\s+(?:function\s+|const\s+|async\s+function\s+))([a-z][a-zA-Z0-9_]*)/g;
+  const jsBad = /[a-z](And|Or|E)[A-Z][a-zA-Z0-9]*/;
+  const pyDecl = /def\s+([a-z][a-z0-9_]*)/g;
+  const pyBad = /_(and|or)_/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    for (const [re, bad] of [[jsDecl, jsBad], [pyDecl, pyBad]]) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(line)) !== null) {
+        if (bad.test(m[1])) {
+          findings.push({ kind: 'srp-and', severity: 2, path: relPath, line: i + 1, snippet: line.trim().slice(0, 120), message: `Identifier \`${m[1]}\` joins two responsibilities — split into separate functions.` });
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+/** Flags the four standard unresolved-debt markers the author left in code. */
+export function detectTodoMarkers(relPath, content) {
+  if (!CODE_RE.test(relPath)) return [];
+  const findings = [];
+  const re = /\b(TODO|FIXME|HACK|XXX)\b/;
+  content.split('\n').forEach((line, i) => {
+    if (re.test(line) && /\/\/|#|\/\*|\*/.test(line)) {
+      findings.push({ kind: 'todo-marker', severity: 1, path: relPath, line: i + 1, snippet: line.trim().slice(0, 120), message: 'Unresolved TODO/FIXME marker.' });
+    }
+  });
+  return findings;
+}
+
+/** React components with > 2 useState AND >= 1 useEffect → extract a hook. */
+export function detectReactStateLoop(relPath, content) {
+  if (!/\.(tsx|jsx)$/.test(relPath)) return [];
+  if (/(^|\/)hooks?\//.test(relPath) || /use[A-Z]/.test(relPath.split('/').pop() || '')) return [];
+  const states = (content.match(/\buseState\s*\(/g) || []).length;
+  const effects = (content.match(/\buseEffect\s*\(/g) || []).length;
+  if (states > 2 && effects >= 1) {
+    return [{ kind: 'react-state-loop', severity: 3, path: relPath, message: `${states} useState + ${effects} useEffect — extract logic into a custom hook.` }];
+  }
+  return [];
+}
+
+export const ALL_DETECTORS = [detectLineBudget, detectSrpAnd, detectTodoMarkers, detectReactStateLoop];
+export { CODE_RE };