codehere 1.0.3 → 2.0.0-beta.0

package/src/hooks.js

@@ -0,0 +1,442 @@
+// Claude Code hook handlers. Every handler fails open: if anything goes wrong,
+// it exits 0 and the agent carries on as if Codehere were not installed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import {
+  findRoot, paths, readConfig, readState, writeState, session, readRules,
+  listDocs, git, isGitRepo, me, slug, today,
+} from './brain.js';
+import {
+  responseText, signature, errorLines, similarity, tamperFindings, failingTest, lowInfoPrompt, vagueFeature,
+} from './signals.js';
+
+function readStdin() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function emitJson(obj) {
+  process.stdout.write(JSON.stringify(obj));
+  process.exit(0);
+}
+
+function toAgent(message) {
+  // exit 2: stderr is shown to the agent (PostToolUse) / blocks stopping (Stop)
+  process.stderr.write(message);
+  process.exit(2);
+}
+
+const quiet = () => process.exit(0);
+
+export async function runHook(event) {
+  const input = readStdin();
+  const root = findRoot(input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd());
+  if (!root) quiet();
+  try {
+    if (event === 'session-start') return sessionStart(root, input);
+    if (event === 'prompt') return promptSubmit(root, input);
+    if (event === 'post-tool') return postTool(root, input);
+    if (event === 'stop') return stop(root, input);
+  } catch (err) {
+    if (process.env.CODEHERE_DEBUG) console.error(err);
+  }
+  quiet();
+}
+
+// ---------- SessionStart: load only human-confirmed context ----------
+
+function sessionStart(root, input) {
+  const state = readState(root);
+  const s = session(state, input.session_id);
+  s.transcript = input.transcript_path || s.transcript;
+  if (isGitRepo(root) && !s.baseline) {
+    // Remember what was already changed before this session, so we only
+    // ever react to what the agent changes now.
+    s.startHead = git(root, 'rev-parse HEAD') || null;
+    s.baseline = dirtySnapshot(root);
+  }
+
+  const out = [];
+  const rules = readRules(root);
+  if (rules.length) {
+    out.push('Team rules from Codehere (written by your teammates, follow them):');
+    rules.slice(0, 20).forEach((r) => out.push(`- ${r}`));
+  }
+
+  if (state.pendingBrief && fs.existsSync(state.pendingBrief)) {
+    out.push('', 'Restart brief from the previous session. Treat it as the full, current spec:');
+    out.push(fs.readFileSync(state.pendingBrief, 'utf8').slice(0, 4000));
+    state.pendingBrief = null;
+  }
+
+  const mine = me(root);
+  const open = listDocs(paths(root).help).filter((d) => d.meta.status === 'open' && d.meta.author !== mine);
+  if (open.length) {
+    out.push(
+      '',
+      `Note for the user: ${open.length} teammate help request(s) are open (${open
+        .slice(0, 3)
+        .map((d) => d.meta.author)
+        .join(', ')}). Mention this once, briefly: they can run \`codehere inbox\`.`
+    );
+  }
+
+  writeState(root, state);
+  if (out.length) process.stdout.write(out.join('\n') + '\n');
+  quiet();
+}
+
+// ---------- what changed in THIS session ----------
+
+const IGNORE = (f) => f.startsWith('.codehere/') || f.startsWith('.claude/');
+
+export function dirtySnapshot(root) {
+  const files = git(root, 'status --porcelain --untracked-files=all')
+    .split('\n')
+    .filter(Boolean)
+    // "XY path"; the first line may have lost its leading space to trim()
+    .map((l) => l.replace(/^[ MADRCU?!T]{1,2}\s+/, '').replace(/^"|"$/g, '').split(' -> ').pop())
+    .filter((f) => f && !IGNORE(f));
+  const snap = {};
+  for (const f of files) {
+    snap[f] = fs.existsSync(path.join(root, f)) ? git(root, `hash-object -- "${f}"`) || 'x' : 'deleted';
+  }
+  return snap;
+}
+
+function changedThisSession(root, s) {
+  const now = dirtySnapshot(root);
+  const before = s.baseline || null;
+  const changed = new Set();
+  if (!before) {
+    Object.keys(now).forEach((f) => changed.add(f));
+  } else {
+    for (const f of new Set([...Object.keys(now), ...Object.keys(before)])) {
+      if (now[f] !== before[f]) changed.add(f);
+    }
+  }
+  if (s.startHead) {
+    git(root, `diff ${s.startHead} HEAD --name-only`)
+      .split('\n')
+      .filter((f) => f && !IGNORE(f))
+      .forEach((f) => changed.add(f));
+  }
+  return [...changed];
+}
+
+// ---------- PostToolUse (Bash): loop breaker + just-in-time team lessons ----------
+
+// Commands that only read files. Their output may contain the word "error"
+// (source code, logs) without anything having failed. A chain such as
+// `cd x && cat a; ls b` is read-only only if every part is. Quoted text is
+// emptied first so `grep "error|fail"` stays one part, and a part that runs
+// another command ($(...), backticks, <(...)) is never read-only.
+const READ_ONLY = /^\s*(cd|pwd|echo|cat|head|tail|less|more|grep|rg|ag|sed\s+-n|awk|ls|find|tree|wc|git\s+(diff|show|log|blame|grep|status))\b/;
+export function readOnly(command) {
+  const runsSomething = /\$\(|`|<\(/;
+  if (runsSomething.test(command)) return false;
+  const bare = command.replace(/(["'])(?:\\.|(?!\1)[^\\])*\1/g, "''");
+  return bare.split(/&&|\|\||\|&|[;|\n]/).every((part) => !part.trim() || READ_ONLY.test(part));
+}
+
+function matchLesson(root, sig, shown) {
+  let best = null;
+  for (const doc of listDocs(paths(root).lessons)) {
+    if (shown.includes(doc.id)) continue;
+    const score = Math.max(
+      similarity(sig, doc.meta.signature || ''),
+      similarity(sig, doc.meta.title || '') * 0.8
+    );
+    if (score >= 0.45 && (!best || score > best.score)) best = { doc, score };
+  }
+  return best?.doc || null;
+}
+
+function lessonText(doc) {
+  const fix = (doc.body.match(/## Fix\n([\s\S]*?)(\n## |$)/) || [null, doc.body])[1].trim();
+  return `Team lesson "${doc.meta.title}" (from ${doc.meta.author || 'a teammate'}, ${doc.meta.date || ''}):\n${fix.slice(0, 700)}`;
+}
+
+function postTool(root, input) {
+  if (input.tool_name && input.tool_name !== 'Bash') quiet();
+  const command = (input.tool_input && input.tool_input.command) || '';
+  if (readOnly(command)) quiet();
+  const text = responseText(input.tool_response) + '\n' + (input.error || '');
+  const sig = signature(text);
+  if (!sig) {
+    // the command that failed last now runs clean: that failure is over
+    const state = readState(root);
+    const s = state.sessions[input.session_id || 'default'];
+    if (s && s.lastFailure && s.lastFailure.command === command) {
+      s.lastFailure = null;
+      writeState(root, state);
+    }
+    quiet();
+  }
+
+  const cfg = readConfig(root);
+  const state = readState(root);
+  const s = session(state, input.session_id);
+  s.errors[sig] = (s.errors[sig] || 0) + 1;
+  s.rawErrors[sig] = errorLines(text, 8);
+  s.lastFailure = { sig, command, test: failingTest(text), lines: errorLines(text, 3), prompt: s.prompts || 0 };
+  const count = s.errors[sig];
+
+  const lesson = matchLesson(root, sig, s.shownLessons);
+  if (lesson) s.shownLessons.push(lesson.id);
+  writeState(root, state);
+
+  const threshold = cfg.loopThreshold;
+  if (count === threshold || count === threshold + 2) {
+    s.loopsStopped = (s.loopsStopped || 0) + 1;
+    writeState(root, state);
+    const msg = [
+      `Codehere: the same error has come back ${count} times this session:`,
+      `  ${sig}`,
+      'Stop patching. Do this instead:',
+      '1. Write one sentence with your root-cause hypothesis.',
+      '2. Check it with one small command before editing any file.',
+      '3. If the hypothesis is wrong, consider `git stash` and returning to the last working state.',
+    ];
+    if (lesson) msg.push('', lessonText(lesson));
+    if (count > threshold) {
+      msg.push(
+        '',
+        'You are still stuck. Stop now. Tell the user in one short line that they can run',
+        '`codehere help "<what you are stuck on>"` to send a ready-made help card to a teammate,',
+        'or `codehere brief` to restart in a fresh session. Then wait for the user.'
+      );
+    }
+    toAgent(msg.join('\n') + '\n');
+  }
+
+  if (lesson) {
+    emitJson({
+      hookSpecificOutput: {
+        hookEventName: input.hook_event_name || 'PostToolUse',
+        additionalContext: `Codehere: a teammate solved a similar error before. It may apply here. ${lessonText(lesson)}\nCheck whether it fits before trying something new.`,
+      },
+    });
+  }
+  quiet();
+}
+
+// ---------- UserPromptSubmit: restore what a short prompt leaves out ----------
+// One message at most, only about this session, under 300 tokens. Silent on normal turns.
+
+function promptSubmit(root, input) {
+  if (!input.session_id) quiet(); // without it, sessions cannot be told apart
+  const prompt = String(input.prompt || '');
+  const cfg = readConfig(root);
+  const state = readState(root);
+  const s = session(state, input.session_id);
+  s.transcript = input.transcript_path || s.transcript;
+  s.prompts = (s.prompts || 0) + 1;
+
+  // Only a failure from the agent's last turn counts: an older one may be fixed or forgotten.
+  const f = s.lastFailure && (s.lastFailure.prompt || 0) === s.prompts - 1 ? s.lastFailure : null;
+  const repeats = f ? s.errors[f.sig] || 1 : 0;
+  const low = !!f && lowInfoPrompt(prompt);
+  if (f && !s.episode) s.episode = { kind: low ? 'still-broken' : 'with-detail', start: s.prompts };
+
+  let msg = null;
+  if (low) {
+    const changed = isGitRepo(root) ? quickChanged(root, s) : [];
+    msg = [
+      "Codehere context from this session's tool output (the user did not type this):",
+      "The user's short message most likely means the last failure is still there.",
+      `- Error (seen ${repeats}x): ${((f.lines && f.lines[0]) || f.sig).slice(0, 200)}`,
+      ...(f.test ? [`- Failing test: ${f.test}`] : []),
+      `- Command: ${f.command.slice(0, 120)}`,
+      ...(changed.length ? [`- Files changed this session: ${changed.join(', ')}`] : []),
+      'Find the root cause before editing again. If a fix already failed, try a different hypothesis.',
+    ].join('\n');
+  } else if (f && !s.briefSuggested && repeats >= cfg.loopThreshold && transcriptTokens(s) >= cfg.longSessionTokens) {
+    s.briefSuggested = true;
+    msg = [
+      `Codehere: this session is long (about ${Math.round(transcriptTokens(s) / 1000)}k tokens) and the same error came back ${repeats} times.`,
+      'Fresh sessions with one clear spec fix bugs better than long ones.',
+      'In one line, suggest the user run `codehere brief` and start a new session (it loads the brief). Then continue with their request.',
+    ].join('\n');
+  } else if (!f && !s.askedHowToCheck && vagueFeature(prompt)) {
+    s.askedHowToCheck = true;
+    msg = [
+      'Codehere: this feature request has no way to check it yet.',
+      'Before writing code, ask the user only this one question: "How will you know it works?"',
+      'You may offer 2 to 4 checkable examples they can accept. Then wait for the answer.',
+      'Turn the answer into failing tests first, then build in small steps and run the tests after each one.',
+    ].join('\n');
+  }
+
+  writeState(root, state);
+  if (msg) {
+    emitJson({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: msg.slice(0, 1100) } });
+  }
+  quiet();
+}
+
+// Fast list for a prompt (no hashing): tracked files changed since the session started.
+function quickChanged(root, s) {
+  return git(root, `diff --name-only ${s.startHead || 'HEAD'}`)
+    .split('\n')
+    .filter((x) => x && !IGNORE(x))
+    .slice(0, 5);
+}
+
+// How big the agent's context is now. Claude Code records each reply's token usage in the
+// transcript; the file itself is no guide, as it also stores full request bodies.
+// 0 means unknown (no usage recorded).
+export function transcriptTokens(s) {
+  try {
+    const size = fs.statSync(s.transcript).size;
+    const fd = fs.openSync(s.transcript, 'r');
+    const len = Math.min(size, 1024 * 1024);
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, size - len);
+    fs.closeSync(fd);
+    const lines = buf.toString('utf8').split('\n').reverse();
+    for (const line of lines) {
+      if (!line.includes('"usage"')) continue;
+      try {
+        const u = JSON.parse(line).message?.usage;
+        const n = u ? (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0) : 0;
+        if (n > 0) return n;
+      } catch {}
+    }
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+
+// The session reached a verified green: close the open fix attempt, if any.
+function recordGreen(state, s) {
+  if (s.firstGreenAt == null) s.firstGreenAt = s.prompts || 0;
+  if (s.episode) {
+    state.episodes = state.episodes || [];
+    state.episodes.push({ kind: s.episode.kind, turns: Math.max(1, (s.prompts || 0) - s.episode.start + 1) });
+    state.episodes = state.episodes.slice(-200);
+    s.episode = null;
+  }
+  // A green test run ends a test failure, not an unrelated one such as a failed build.
+  const f = s.lastFailure;
+  if (f && (f.test || /\b(test|tests|pytest|jest|vitest|mocha|spec)\b/.test(f.command || ''))) s.lastFailure = null;
+}
+
+// ---------- Stop: verify "done" outside the agent ----------
+
+function runTests(root, cfg) {
+  const r = spawnSync(cfg.testCommand, {
+    cwd: root,
+    shell: true,
+    encoding: 'utf8',
+    timeout: cfg.testTimeoutSeconds * 1000,
+    env: { ...process.env, CI: '1', FORCE_COLOR: '0' },
+  });
+  const output = `${r.stdout || ''}\n${r.stderr || ''}`.trim();
+  const timedOut = r.error && r.error.code === 'ETIMEDOUT';
+  return { ok: r.status === 0 && !timedOut, output, timedOut };
+}
+
+function block(reason) {
+  emitJson({ decision: 'block', reason });
+}
+
+function stop(root, input) {
+  const cfg = readConfig(root);
+  const state = readState(root);
+  const s = session(state, input.session_id);
+  const mayBlock = (s.stopBlocks || 0) < 3; // never trap the agent: after 3 blocks, only observe
+
+  if (!isGitRepo(root)) quiet();
+  const base = s.startHead || 'HEAD';
+  const changed = changedThisSession(root, s);
+  if (!changed.length) quiet(); // the agent changed nothing this session: stay silent
+
+  // 1. tampering with tests or checks (only in files changed this session)
+  const files = changed.map((f) => `"${f}"`).join(' ');
+  const nameStatus = git(root, `diff ${base} --name-status -- ${files}`);
+  const findings = tamperFindings(nameStatus, git(root, `diff ${base} -U0 -- ${files}`));
+  const key = findings.join('|');
+  if (findings.length && s.tamperReported !== key && mayBlock) {
+    s.tamperReported = key;
+    s.stopBlocks++;
+    writeState(root, state);
+    block(
+      [
+        'Codehere found changes that weaken tests or checks:',
+        ...findings.map((f) => `- ${f}`),
+        'Restore them and fix the code instead.',
+        'If the change is truly intended, tell the user in one line why, then finish.',
+      ].join('\n')
+    );
+  }
+
+  // 2. run the tests ourselves
+  let verified = null;
+  if (cfg.verifyOnStop && cfg.testCommand) {
+    const t = runTests(root, cfg);
+    if (!t.ok && !mayBlock) {
+      writeState(root, state);
+      quiet();
+    }
+    if (!t.ok) {
+      s.stopBlocks++;
+      writeState(root, state);
+      const tail = t.output.split('\n').slice(-25).join('\n');
+      block(
+        [
+          `Codehere ran \`${cfg.testCommand}\` and it ${t.timedOut ? 'timed out' : 'failed'}. The task is not done yet.`,
+          'Last lines of output:',
+          tail,
+          'Fix the cause, then finish. Do not change or skip tests to make them pass.',
+        ].join('\n')
+      );
+    }
+    verified = cfg.testCommand;
+    if (!findings.length) {
+      state.lastGreen = { commit: git(root, 'rev-parse HEAD'), at: new Date().toISOString() };
+      recordGreen(state, s);
+    }
+  }
+
+  // 3. turn a solved repeated error into a team lesson (asked once per session)
+  const solved = Object.entries(s.errors).filter(([, n]) => n >= 2);
+  if (solved.length && !s.lessonAsked && mayBlock) {
+    s.lessonAsked = true;
+    s.stopBlocks++;
+    writeState(root, state);
+    const [sig] = solved.sort((a, b) => b[1] - a[1])[0];
+    const file = path.join('.codehere', 'lessons', `${today()}-${slug(sig, 30)}.md`);
+    block(
+      [
+        `Before you finish: you hit and solved a repeated error ("${sig}").`,
+        `Save it for the team. Create ${file} with exactly this format:`,
+        '---',
+        'title: <short name of the problem>',
+        `signature: ${sig}`,
+        `author: ${me(root)}`,
+        `date: ${today()}`,
+        '---',
+        '## Fix',
+        '- Cause: <one line>',
+        '- Fix: <one line>',
+        '- Avoid next time: <one line>',
+        'Then finish your reply as normal. Do not mention this step unless asked.',
+      ].join('\n')
+    );
+  }
+
+  writeState(root, state);
+  // Green only for intact evidence (DESIGN.md §1): a pass with a weakened test is not verified.
+  if (verified && findings.length) {
+    emitJson({ systemMessage: `Codehere ran \`${verified}\`. It passed, but a file changed this session has a weakened check: ${findings.join('; ')}.` });
+  }
+  if (verified) emitJson({ systemMessage: `Codehere verified: \`${verified}\` passed.` });
+  quiet();
+}

package/src/signals.js

@@ -0,0 +1,186 @@
+// Deterministic signals. No AI in the decision path.
+
+const ERROR_LINE =
+  /(error|exception|traceback|failed|failure|fatal|cannot|can't|not found|undefined is not|is not defined|is not a function|segmentation fault|ERR!|panic:|denied|refused|unexpected token|syntaxerror|typeerror|referenceerror|modulenotfound|no such file)/i;
+
+const NOISE = /^(\s*at\s|\s*\^+\s*$|\s*$)/;
+// A passing test whose name mentions an error ("✔ returns an error for bad input"),
+// or a summary that says zero failed ("ℹ fail 0"), is not a failure.
+const PASSING = /^\s*(✔|✓|√|ok \d+\b|PASS\b)|^\s*(ℹ\s*)?(fail|failed|failures|errors)\s*[:=]?\s*0\s*$/i;
+
+export function stripAnsi(s) {
+  return String(s).replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+}
+
+// Pull text out of whatever shape the tool response has.
+export function responseText(resp) {
+  if (resp == null) return '';
+  if (typeof resp === 'string') return resp;
+  const parts = [];
+  for (const key of ['stderr', 'stdout', 'output', 'error', 'content', 'result']) {
+    const v = resp[key];
+    if (typeof v === 'string') parts.push(v);
+    else if (Array.isArray(v)) parts.push(v.map((x) => (typeof x === 'string' ? x : x?.text || '')).join('\n'));
+  }
+  return parts.length ? parts.join('\n') : JSON.stringify(resp);
+}
+
+export function errorLines(text, max = 12) {
+  const lines = stripAnsi(text).split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length && hits.length < max; i++) {
+    if (ERROR_LINE.test(lines[i]) && !NOISE.test(lines[i]) && !PASSING.test(lines[i])) hits.push(lines[i].trim());
+  }
+  return hits;
+}
+
+// A stable fingerprint for "the same error again".
+export function normalize(line) {
+  return stripAnsi(line)
+    .replace(/(['"`]).*?\1/g, "'…'")
+    .replace(/(?:[A-Za-z]:)?(?:[\w.-]*[\\/])+([\w.-]+)/g, '$1')
+    .replace(/0x[0-9a-f]+/gi, 'N')
+    .replace(/-?\d+(\.\d+)?/g, 'N')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 160);
+}
+
+export function signature(text) {
+  const lines = errorLines(text, 3);
+  if (!lines.length) return null;
+  return normalize(lines[0]);
+}
+
+// The name of the failing test, from node --test / TAP, jest, pytest or go test output.
+export function failingTest(text) {
+  const t = stripAnsi(text);
+  const m =
+    t.match(/^\s*(?:✖|×|✗|not ok \d+ -)\s+(?!failing tests)(.+?)(?:\s+\(?\d[\d.]*\s?m?s\)?)?\s*$/m) ||
+    t.match(/^\s*●\s+(.+?)\s*$/m) ||
+    t.match(/^FAILED\s+(\S+)/m) ||
+    t.match(/^--- FAIL:\s+(\S+)/m);
+  return m ? m[1].trim().slice(0, 120) : null;
+}
+
+// ---------- prompts (UserPromptSubmit) ----------
+
+const words = (p) => String(p || '').trim().split(/\s+/).filter(Boolean);
+// A file path, inline code, a pasted error line or a number: the prompt carries its own
+// information. The bare word "error" does not count ("still error", "masih error").
+const SPECIFIC = /`|[\w-]+\/[\w./-]+|\.\w{1,5}\b|\w*(error|exception)\s*[:[(]|\b(traceback|line \d+|expected|got)\b|\d{3,}/i;
+// English and Indonesian words that ask for a repair. Thanks and "works now" never count.
+const REPAIR =
+  /\b(still|again|broken|fix|fail|fails|failing|failed|wrong|same|bug|error|errors|wtf|ugh|stuck|nope|masih|lagi|rusak|gagal|eror|salah|belum|tolong|perbaiki|benerin|betulin)\b|\b(not|doesn'?t|didn'?t|isn'?t|won'?t|can'?t|gak|nggak|ngga|ga|tidak|blm)\s+(work|working|run|running|pass|passing|load|loading|jalan|bisa|berhasil)\b/i;
+const POSITIVE = /\b(thanks|thank you|thx|works now|working now|great|nice|good|perfect|awesome|mantap|makasih|terima kasih|sip|berhasil|sudah bisa|udah bisa)\b/i;
+
+// "still broken", "fix it", "masih error": short, no specifics, asks for a repair.
+export function lowInfoPrompt(p) {
+  const w = words(p);
+  if (!w.length || w.length > 8 || SPECIFIC.test(p) || POSITIVE.test(p)) return false;
+  return REPAIR.test(p);
+}
+
+const BUILD_START =
+  /^\s*(please\s+|tolong\s+|can you\s+|could you\s+)?(build|create|make|add|implement|develop|design|set up|setup|buat|buatkan|bikin|bikinin|tambah|tambahkan|bangun)\b/i;
+const BIG = /\b(app|application|feature|system|platform|website|site|dashboard|service|bot|game|aplikasi|fitur|sistem|situs|web)\b/i;
+const SMALL = /\b(make sure|pastikan|instead|still|again|fix|bug|error|rename|change|ubah|ganti|refactor|button|color|colour|font|style)\b/i;
+const CHECKABLE =
+  /\b(tests?|spec|expect|assert|should (return|show|be|print)|when i|given|acceptance|example|input|output|returns?|tes|uji|contoh|harus|kalau|jika)\b/i;
+
+// "build me a todo app with login": a new feature with nothing that says how to check it.
+// Questions and small edits ("make the button blue") do not count.
+export function vagueFeature(p) {
+  return (
+    words(p).length >= 6 &&
+    BUILD_START.test(p) &&
+    BIG.test(p) &&
+    !SMALL.test(p) &&
+    !CHECKABLE.test(p) &&
+    !SPECIFIC.test(p) &&
+    !/\?\s*$/.test(p)
+  );
+}
+
+function tokens(s) {
+  return new Set(
+    String(s)
+      .toLowerCase()
+      .split(/[^a-z0-9_]+/)
+      .filter((w) => w.length > 2 && w !== 'n')
+  );
+}
+
+export function similarity(a, b) {
+  const A = tokens(a);
+  const B = tokens(b);
+  if (!A.size || !B.size) return 0;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter++;
+  return inter / (A.size + B.size - inter);
+}
+
+// ---------- test tampering ----------
+
+const TEST_FILE = /(^|\/)(test|tests|__tests__|spec)\/|\.(test|spec)\.[a-z]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/i;
+
+const TAMPER_ADDED = [
+  { re: /\b(it|test|describe)\.skip\s*\(/, why: 'a test was skipped (.skip)' },
+  { re: /\b(xit|xdescribe|xtest)\s*\(/, why: 'a test was disabled (xit/xdescribe)' },
+  { re: /@pytest\.mark\.skip|unittest\.skip/, why: 'a Python test was skipped' },
+  { re: /@ts-nocheck/, why: 'type checking was turned off (@ts-nocheck)' },
+  { re: /--no-verify/, why: 'git hooks were bypassed (--no-verify)' },
+  { re: /expect\([^)]*\)\.(toBe|toEqual)\(\s*(true|1)\s*\)\s*;?\s*\/\/\s*(todo|temp|hack)/i, why: 'an assertion was replaced with a placeholder' },
+];
+
+export function tamperFindings(nameStatus, diff) {
+  const found = [];
+  for (const line of nameStatus.split('\n')) {
+    const [status, file] = line.split(/\s+/);
+    if (status === 'D' && file && TEST_FILE.test(file)) found.push(`test file deleted: ${file}`);
+  }
+  let current = '';
+  let removedAsserts = 0;
+  let addedAsserts = 0;
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('+++ ')) {
+      current = line.replace(/^\+\+\+ (b\/)?/, '');
+      continue;
+    }
+    if (line.startsWith('--- ')) continue;
+    if (line.startsWith('+')) {
+      for (const t of TAMPER_ADDED) if (t.re.test(line)) found.push(`${t.why} in ${current}`);
+      if (TEST_FILE.test(current) && /\b(expect|assert)\w*\s*\(/.test(line)) addedAsserts++;
+    } else if (line.startsWith('-')) {
+      if (TEST_FILE.test(current) && /\b(expect|assert)\w*\s*\(/.test(line)) removedAsserts++;
+    }
+  }
+  if (removedAsserts - addedAsserts >= 2) {
+    found.push(`${removedAsserts - addedAsserts} assertions removed from test files`);
+  }
+  return [...new Set(found)];
+}
+
+// ---------- redaction for anything that leaves the machine ----------
+
+const SECRETS = [
+  /sk-[A-Za-z0-9_-]{16,}/g,
+  /sk-ant-[A-Za-z0-9_-]{16,}/g,
+  /gh[pousr]_[A-Za-z0-9]{20,}/g,
+  /AKIA[0-9A-Z]{16}/g,
+  /xox[abprs]-[A-Za-z0-9-]{10,}/g,
+  /AIza[0-9A-Za-z_-]{30,}/g,
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /\b[\w.+-]+@[\w-]+\.[\w.-]+\b/g,
+];
+
+export function redact(text) {
+  let out = String(text);
+  for (const re of SECRETS) out = out.replace(re, '[redacted]');
+  out = out.replace(
+    /\b([A-Z0-9_]*(SECRET|TOKEN|PASSWORD|PASSWD|API_KEY|APIKEY|PRIVATE_KEY|ACCESS_KEY)[A-Z0-9_]*)\s*[:=]\s*\S+/gi,
+    '$1=[redacted]'
+  );
+  return out;
+}