claude-memory-lint 0.1.0

package/lib/detectors/provenance.js

@@ -0,0 +1,668 @@
+'use strict';
+// PER-LINE PROVENANCE in the memory archive.
+//
+// The failure mode this detector exists to catch: someone's instruction, a
+// number produced by an actual command, and the model's own guess end up
+// indistinguishable in the same paragraph, and the guess gets cited later as
+// if it had been measured. The convention is one marker per claim, three
+// values (configurable, default English words):
+//
+//   (stated)    -- a person said so, this session or an earlier one
+//   (measured)  -- came out of a command that was actually run
+//   (inferred)  -- the model's hypothesis; not verified
+//
+// -- THE BOUNDARY (what needs a marker) LIVES IN ONE PLACE ------------------
+//
+// `classifyLine` is that place. Reading "every line of content carries a
+// marker" literally would make the file unreadable and fail the gate on
+// plain explanatory prose — which isn't the problem this exists to solve.
+// A marker is required only on a line that ASSERTS A VERIFIABLE FACT: a
+// number or count, a date, a URL, or an id/hash. Headings, blank lines,
+// pointers (an item that only links to another file/note/ticket), rule
+// separators and blockquotes are exempt by design.
+//
+// A NUMBERED LIST MARKER is also exempt: `1. **Note:** ...` is an enumerator,
+// not an assertion. The exemption strips only the marker itself — a number
+// asserted after it still needs a marker.
+//
+// -- MENTION IS NOT USE ------------------------------------------------------
+//
+// Backticks and fenced blocks are quotation: they're excluded from judgment
+// both ways. A whole line inside a code span doesn't need a marker, and a
+// marker quoted inside backticks doesn't count as a real marker. Masking is
+// shared with lib/mask-code.js, not reimplemented here.
+//
+// -- CUT BY LINE, NOT BY FILE -------------------------------------------------
+//
+// Judging by FILE (any file touched after the convention's start date enters
+// judgment whole) drags an entire old file into the gate the moment someone
+// appends three lines to it — the archive is append-only by nature. The cut
+// here is by LINE: a CONTENT BASELINE (a JSON file of per-file line hashes)
+// records which lines have already been seen. A line whose hash isn't in
+// that set is "new" and gets judged; a line already in the baseline is out
+// of scope (declared as a backlog, not silently forgiven).
+//
+// The baseline's per-file index also gets consulted AS ONE POOL across the
+// whole archive, not per file: renaming a note or merging duplicates
+// shouldn't turn byte-identical lines into "new" lines just because they
+// moved.
+//
+// A file that declares a `provenance:` field in its frontmatter is judged
+// whole — it opted into the convention explicitly, so the baseline doesn't
+// exempt it.
+//
+// -- THE UNIT OF JUDGMENT IS THE SENTENCE, NOT THE PHYSICAL LINE -------------
+//
+// Markdown prose wraps wherever the paragraph happens to fit, and the marker
+// conventionally comes at the END of the sentence — so a three-line sentence
+// with the marker on line three would otherwise fail lines one and two for a
+// claim that IS marked. The marker is searched for across the whole sentence
+// (a run of non-blank lines, sliced into sentences by terminal punctuation
+// and by the marker itself, since the marker also closes the sentence it
+// covers). Each sentence keeps the LINE-level pieces that composed it, so an
+// accusation still points at the physical line to fix, even though the
+// verdict is per sentence.
+//
+// -- REWRITING THE BASELINE DOES NOT FORGIVE ANYTHING ------------------------
+//
+// Two guards, both mandatory:
+//   1. `--record-baseline` is INCREMENTAL. It only ADDS the hash of a line
+//      the detector would NOT flag — prose, headings, pointers, or an
+//      already-marked claim. A line asserting an unmarked fact never enters
+//      the baseline, no matter how many times it's rewritten.
+//   2. The from-scratch write is a separate, explicit mode (`--genesis`):
+//      the only one that writes the WHOLE baseline unfiltered. It exists
+//      because the very first write needs one.
+//
+// A third guard belongs in CI, not here: reject a PR where the baseline file
+// changed but wasn't committed on purpose, so a rewrite is visible in the
+// diff instead of hidden inside a green run. `auditBaselineGit` is what that
+// check calls.
+//
+// Exit: 0 ok | 1 failed | 2 not checked (archive or baseline missing)
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { readCollection } = require('../collector');
+const { locateArchive } = require('../locate-archive');
+const { maskCode } = require('../mask-code');
+
+const DEFAULT_MARKERS = ['stated', 'measured', 'inferred'];
+
+function markerRegex(markers) {
+  return new RegExp('\\((' + markers.map(escapeRegex).join('|') + ')\\)', 'i');
+}
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// --- fact-verifiable triggers ------------------------------------------
+const RE_DATE = /\b(\d{1,2}\/\d{1,2}\/\d{2,4}|\d{4}-\d{2}-\d{2})\b/;
+const RE_URL = /\bhttps?:\/\/\S+/i;
+// Hash: 7..40 hex chars WITH at least one letter and one digit. Without both
+// assertions, an 8-digit date and a plain word would each false-match one of
+// the two classes this is meant to catch.
+const RE_ID = /\b(?=[0-9a-f]{7,40}\b)(?=[0-9a-f]*[a-f])(?=[0-9a-f]*[0-9])[0-9a-f]{7,40}\b/i;
+const RE_NUMBER = /\d/;
+
+// --- shapes that are NOT a factual assertion -----------------------------
+const RE_HEADING = /^\s{0,3}#{1,6}\s/;
+const RE_RULE = /^\s*(?:[-*_]\s*){3,}$/;
+const RE_TABLE_SEPARATOR = /^\s*\|?[\s:|-]*\|[\s:|-]*$/;
+const RE_BULLET = /^\s*(?:[-*+]|\d+[.)])\s+/;
+// Numbered list marker: `1. `, `2) `, `(3) `. Only the enumerator itself is
+// stripped from the line before the triggers run; a number asserted after it
+// still requires a marker.
+const RE_ENUMERATOR = /^\s*\(?\d+[.)]\s/;
+
+// Text left after stripping what only POINTS: list bullet, wikilink,
+// Markdown link (text and target), ticket reference (e.g. #42) and checkbox.
+// Used only to decide whether the line is a pointer.
+function withoutPointers(line) {
+  return String(line)
+    .replace(RE_BULLET, ' ')
+    .replace(/^\s*\[[ xX]\]\s*/, ' ')
+    .replace(/\[\[[^\]]*\]\]/g, ' ')
+    .replace(/\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/#\d+/g, ' ');
+}
+
+function findMarker(maskedLine, markers) {
+  const m = markerRegex(markers).exec(String(maskedLine));
+  return m ? m[1].toLowerCase() : null;
+}
+
+// The boundary, in one place. Takes the masked line (quotation already
+// blanked) and returns the shape verdict: does it need a marker, and why.
+function classifyLine(maskedLine, rawLine) {
+  const raw = rawLine === undefined ? maskedLine : rawLine;
+  const masked = String(maskedLine);
+
+  if (!masked.trim()) {
+    const reason = String(raw).trim() ? 'quotation' : 'blank';
+    return { needsMarker: false, reason, triggers: [] };
+  }
+  if (RE_HEADING.test(masked)) return { needsMarker: false, reason: 'heading', triggers: [] };
+  if (RE_RULE.test(masked)) return { needsMarker: false, reason: 'separator', triggers: [] };
+  if (RE_TABLE_SEPARATOR.test(masked)) return { needsMarker: false, reason: 'separator', triggers: [] };
+
+  // Pointer: once what only points is stripped, no assertion is left (fewer
+  // than 3 alphanumeric characters). `- [[note]]` and `- [ADR](docs/adr.md)`
+  // are map, not territory.
+  const rest = withoutPointers(masked);
+  if ((rest.match(/[0-9a-zA-ZÀ-ÿ]/g) || []).length < 3) {
+    return { needsMarker: false, reason: 'pointer', triggers: [] };
+  }
+
+  const triggers = [];
+  // A ticket reference is a pointer, not a count; a numbered-list marker is
+  // an enumerator, not a count. Both are stripped BEFORE the trigger tests.
+  const withoutTicket = masked.replace(RE_ENUMERATOR, ' ').replace(/#\d+/g, ' ');
+  if (RE_DATE.test(withoutTicket)) triggers.push('date');
+  if (RE_URL.test(masked)) triggers.push('url');
+  if (RE_ID.test(withoutTicket)) triggers.push('id');
+  if (RE_NUMBER.test(withoutTicket)) triggers.push('number');
+
+  if (!triggers.length) return { needsMarker: false, reason: 'prose', triggers: [] };
+  return { needsMarker: true, reason: 'verifiable_fact', triggers };
+}
+
+// --- the SENTENCE: the unit of judgment ------------------------------------
+
+const RE_QUOTE_START = /^\s{0,3}>/;
+const RE_TABLE_LINE = /^\s*\|/;
+
+// Builds the "sentence ends here" regex from the configured markers: final
+// punctuation, OR the marker itself (which closes the sentence it covers).
+function sentenceEndRegex(markers) {
+  const alt = markers.map(escapeRegex).join('|');
+  return new RegExp('(?:[.!?…]+|\\((?:' + alt + ')\\))[)"\'`*_\\]]*(?=\\s|$)', 'gi');
+}
+
+// Slices lines into TEXT BLOCKS: a run of non-blank lines. A blank line
+// closes the block; a heading or separator becomes its own one-line block
+// (it doesn't run into the following prose); a list item, blockquote or
+// table row opens a new block but accepts continuation (the next indented
+// line is the same sentence).
+function textBlocks(maskedLines) {
+  const blocks = [];
+  let current = null;
+  for (let i = 0; i < maskedLines.length; i++) {
+    const l = String(maskedLines[i]);
+    if (!l.trim()) {
+      current = null;
+      continue;
+    }
+    if (RE_HEADING.test(l) || RE_RULE.test(l) || RE_TABLE_SEPARATOR.test(l)) {
+      blocks.push([i]);
+      current = null;
+      continue;
+    }
+    if (!current || RE_BULLET.test(l) || RE_QUOTE_START.test(l) || RE_TABLE_LINE.test(l)) {
+      current = [i];
+      blocks.push(current);
+      continue;
+    }
+    current.push(i);
+  }
+  return blocks;
+}
+
+// Slices ONE block into sentences. Returns, per sentence, the whole text
+// (where the marker is searched for) and the line-level PIECES that make it
+// up (where triggers are measured, and where the flagged line number comes
+// from). Pure: indices and masked lines in, structure out.
+function sentencesOfBlock(indices, maskedLines, markers) {
+  const parts = indices.map((i) => String(maskedLines[i]));
+  const text = parts.join('\n');
+
+  const starts = [];
+  let acc = 0;
+  for (const p of parts) {
+    starts.push(acc);
+    acc += p.length + 1;
+  }
+
+  const re = sentenceEndRegex(markers);
+  const bounds = [];
+  let m;
+  while ((m = re.exec(text))) {
+    bounds.push(m.index + m[0].length);
+    if (re.lastIndex <= m.index) re.lastIndex = m.index + 1;
+  }
+  if (!bounds.length || bounds[bounds.length - 1] < text.length) bounds.push(text.length);
+
+  const sentences = [];
+  let from = 0;
+  for (const to of bounds) {
+    if (to <= from) continue;
+    const raw = text.slice(from, to);
+    if (raw.trim()) {
+      const pieces = [];
+      for (let k = 0; k < indices.length; k++) {
+        const a = Math.max(from, starts[k]);
+        const b = Math.min(to, starts[k] + parts[k].length);
+        if (b > a) pieces.push({ line: indices[k], text: text.slice(a, b) });
+      }
+      sentences.push({ text: raw, pieces });
+    }
+    from = to;
+  }
+  return sentences;
+}
+
+// --- content baseline: what counts as "new line" ---------------------------
+
+// Line hash. Normalizes ONLY leading/trailing whitespace: re-indenting isn't
+// a new line, changing a word is.
+function hashLine(line) {
+  return crypto.createHash('sha1').update(String(line).trim(), 'utf8').digest('hex').slice(0, 12);
+}
+
+function baselineForFile(baseline, name) {
+  if (!baseline || !Object.prototype.hasOwnProperty.call(baseline, name)) return null;
+  const list = baseline[name];
+  return new Set(Array.isArray(list) ? list : []);
+}
+
+// What the gate actually consults: every hash in the baseline, from any
+// file. A line that moved between files carries its exemption with it; new
+// text stays judged wherever it lands. `null` only when there is no baseline
+// at all — an empty per-file entry is different: there, everything is new,
+// which is the intended state right after genesis.
+function baselineContentSet(baseline) {
+  if (!baseline || typeof baseline !== 'object') return null;
+  const all = new Set();
+  for (const list of Object.values(baseline)) {
+    if (!Array.isArray(list)) continue;
+    for (const h of list) all.add(h);
+  }
+  return all;
+}
+
+function baselineEnvelope(map, mode) {
+  return {
+    generated: new Date().toISOString(),
+    mode,
+    note:
+      'Content baseline for the per-line provenance gate. Each entry is the set of content-line ' +
+      'hashes already seen in that file; a line outside the set is new and enters the gate. ' +
+      (mode === 'genesis'
+        ? 'GENESIS (--genesis): written WITHOUT filtering, exempts everything that existed at write ' +
+          'time. The only mode that does not filter — commit this file right after writing it so the ' +
+          'exemption is visible in the diff.'
+        : 'INCREMENTAL (--record-baseline): only a line the detector would NOT flag was added. A line ' +
+          'asserting an unmarked verifiable fact never enters, and stays flagged after any rewrite.'),
+    files: map,
+  };
+}
+
+// GENESIS, from already-collected files. Pure: records in, disk object out.
+// Doesn't filter anything — that's why it's a separate, non-default mode.
+function generateBaseline(files) {
+  const map = {};
+  for (const f of files) {
+    const seen = [];
+    const set = new Set();
+    for (const l of String(f.body || '').split('\n')) {
+      if (!String(l).trim()) continue;
+      const h = hashLine(l);
+      if (set.has(h)) continue;
+      set.add(h);
+      seen.push(h);
+    }
+    map[f.name] = seen;
+  }
+  return baselineEnvelope(map, 'genesis');
+}
+
+// INCREMENTAL recording: only adds the hash of a line the detector would not
+// flag — "would not flag" comes from the SAME judgment the gate runs
+// (`judgeFile` against the current baseline), never a second parallel rule.
+// A flagged line stays out and stays dirty. Never shrinks: a hash that was
+// already there stays, and a file no longer in the archive keeps its entry.
+function generateIncrementalBaseline(files, currentBaseline) {
+  const current = currentBaseline && typeof currentBaseline === 'object' ? currentBaseline : {};
+  const map = {};
+  let added = 0;
+  let rejected = 0;
+  const rejectedByFile = {};
+
+  for (const f of files) {
+    const before = Array.isArray(current[f.name]) ? current[f.name].slice() : [];
+    const set = new Set(before);
+    const seen = before;
+    const result = judgeFile(f, { baseline: current });
+    const flagged = new Set(result.occurrences.map((o) => o.line - 1));
+    const lines = String(f.body || '').split('\n');
+    let rejectedHere = 0;
+    for (let i = 0; i < lines.length; i++) {
+      if (!String(lines[i]).trim()) continue;
+      const h = hashLine(lines[i]);
+      if (set.has(h)) continue;
+      if (flagged.has(i)) {
+        rejected++;
+        rejectedHere++;
+        continue;
+      }
+      set.add(h);
+      seen.push(h);
+      added++;
+    }
+    if (rejectedHere) rejectedByFile[f.name] = rejectedHere;
+    map[f.name] = seen;
+  }
+
+  // The baseline never shrinks: a file no longer in the archive stays as it was.
+  for (const name of Object.keys(current)) {
+    if (!Object.prototype.hasOwnProperty.call(map, name)) map[name] = current[name];
+  }
+
+  return { doc: baselineEnvelope(map, 'incremental'), added, rejected, rejectedByFile };
+}
+
+// --- the guard over the baseline file itself --------------------------------
+
+// A baseline changed and NOT committed is an invisible rewrite. This answers
+// one thing: is the baseline file clean in git?
+//
+// `run` is injectable on purpose — tests exercise all four paths (no git, not
+// a clone, clean, dirty) without depending on the machine's git state. Real
+// usage falls back to `spawnSync`. Without git, outside a clone, or on a git
+// failure, the verdict is NOT CHECKED; never "ok".
+function auditBaselineGit(opts) {
+  const o = opts || {};
+  const file = path.resolve(o.file || o.baselineFile);
+  const cwd = o.cwd || path.dirname(file);
+  const exists = typeof o.exists === 'function' ? o.exists : (p) => fs.existsSync(p);
+  const run =
+    o.run ||
+    ((args, dir) =>
+      require('child_process').spawnSync('git', args, { cwd: dir, encoding: 'utf8', timeout: 30000 }));
+
+  const base = { file };
+
+  if (!exists(file)) {
+    return { ...base, state: 'not_checked', reason: 'baseline_absent', detail: `${file} does not exist: nothing to check in git.` };
+  }
+
+  const attempt = (args) => {
+    try {
+      const r = run(args, cwd);
+      if (!r || r.error) return { error: (r && r.error && r.error.message) || 'git did not run' };
+      return r;
+    } catch (e) {
+      return { error: (e && e.message) || String(e) };
+    }
+  };
+
+  const inside = attempt(['rev-parse', '--is-inside-work-tree']);
+  if (inside.error) return { ...base, state: 'not_checked', reason: 'git_missing', detail: inside.error };
+  if (inside.status !== 0 || String(inside.stdout || '').trim() !== 'true') {
+    return { ...base, state: 'not_checked', reason: 'not_a_clone', detail: `${cwd} is not a git clone: "changed and uncommitted" doesn't apply.` };
+  }
+
+  const st = attempt(['status', '--porcelain', '--', file]);
+  if (st.error || st.status !== 0) {
+    return { ...base, state: 'not_checked', reason: 'git_failed', detail: st.error || `git status exited ${st.status}: ${String(st.stderr || '').trim()}` };
+  }
+
+  const pending = String(st.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean);
+  if (pending.length) return { ...base, state: 'dirty', pending };
+  return { ...base, state: 'ok', pending: [] };
+}
+
+// --- cut: who enters judgment -----------------------------------------------
+
+// A file that declares `provenance:` in its frontmatter opted into the
+// convention: it's judged WHOLE, the baseline doesn't exempt it.
+function declaresProvenance(file) {
+  const data = (file && file.frontmatter && file.frontmatter.data) || {};
+  return typeof data.provenance === 'string' && data.provenance.trim().length > 0;
+}
+
+// --- judgment ----------------------------------------------------------------
+
+// Judges ONE already-collected file. Pure: struct in, verdict out.
+//
+// Only the BODY is judged. `description` is a lookup hook, not a factual
+// claim: it's a pointer by definition, and marking it would just be noise in
+// what loads at boot.
+function judgeFile(file, opts) {
+  const o = opts || {};
+  const baseline = o.baseline || null;
+  const markers = o.markers || DEFAULT_MARKERS;
+  const declared = declaresProvenance(file);
+  const seen = declared ? null : baselineContentSet(baseline);
+  const via = declared
+    ? 'provenance field'
+    : seen
+      ? 'content baseline'
+      : 'no baseline (judged whole)';
+
+  const text = String(file.body || '');
+  const lines = text.split('\n');
+  // Mask the WHOLE text before slicing: a code span can cross a line break.
+  const masked = maskCode(text).split('\n');
+
+  let linesInScope = 0;
+  let linesOutOfScope = 0;
+  const fresh = new Set();
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!String(raw).trim()) continue; // blank line counts toward neither
+    if (seen && seen.has(hashLine(raw))) {
+      linesOutOfScope++;
+      continue;
+    }
+    linesInScope++;
+    fresh.add(i);
+  }
+
+  // Judged by SENTENCE: the marker is looked for across the whole sentence;
+  // the trigger and the flagged line number come from the piece. One line
+  // can belong to two sentences, and only one of them carry a marker.
+  const byLine = new Map();
+  for (const block of textBlocks(masked)) {
+    for (const sentence of sentencesOfBlock(block, masked, markers)) {
+      if (findMarker(sentence.text, markers) !== null) continue;
+      for (const piece of sentence.pieces) {
+        if (!fresh.has(piece.line)) continue; // out of scope
+        const raw = lines[piece.line];
+        const c = classifyLine(piece.text, raw);
+        if (!c.needsMarker) continue;
+        const already = byLine.get(piece.line);
+        if (already) {
+          for (const t of c.triggers) if (!already.triggers.includes(t)) already.triggers.push(t);
+          continue;
+        }
+        byLine.set(piece.line, {
+          line: piece.line + 1,
+          reason: c.reason,
+          triggers: c.triggers.slice(),
+          excerpt: String(raw).trim().slice(0, 120),
+        });
+      }
+    }
+  }
+  const occurrences = [...byLine.keys()].sort((a, b) => a - b).map((k) => byLine.get(k));
+
+  const base = { name: file.name, via, linesInScope, linesOutOfScope };
+  if (occurrences.length) return { ...base, state: 'unmarked', occurrences };
+  if (!linesInScope) return { ...base, state: 'no_new_lines', occurrences: [] };
+  return { ...base, state: 'ok', occurrences: [] };
+}
+
+function auditProvenance(files, opts) {
+  return files.map((f) => judgeFile(f, opts));
+}
+
+// Summary from the SAME list the gate reads, never a second parallel count.
+function summarizeProvenance(lines) {
+  const unmarked = lines.filter((l) => l.state === 'unmarked');
+  const noNewLines = lines.filter((l) => l.state === 'no_new_lines');
+  const withNewLines = lines.filter((l) => l.state !== 'no_new_lines');
+  return {
+    total: lines.length,
+    filesWithNewLines: withNewLines.length,
+    noNewLines: noNewLines.length,
+    linesInScope: lines.reduce((n, l) => n + (l.linesInScope || 0), 0),
+    linesOutOfScope: lines.reduce((n, l) => n + (l.linesOutOfScope || 0), 0),
+    ok: withNewLines.length - unmarked.length,
+    unmarked: unmarked.length,
+    failed: unmarked.length,
+    namesUnmarked: unmarked.map((l) => l.name),
+    occurrences: unmarked.reduce((n, l) => n + l.occurrences.length, 0),
+  };
+}
+
+module.exports = {
+  DEFAULT_MARKERS,
+  markerRegex,
+  withoutPointers,
+  findMarker,
+  classifyLine,
+  textBlocks,
+  sentencesOfBlock,
+  hashLine,
+  baselineForFile,
+  baselineContentSet,
+  generateBaseline,
+  generateIncrementalBaseline,
+  auditBaselineGit,
+  declaresProvenance,
+  judgeFile,
+  auditProvenance,
+  summarizeProvenance,
+};
+
+// --- CLI ---------------------------------------------------------------
+// Usage:
+//   node lib/detectors/provenance.js [--json]
+//   node lib/detectors/provenance.js --record-baseline
+//   node lib/detectors/provenance.js --genesis
+//   node lib/detectors/provenance.js --audit-baseline
+// Exit: 0 nothing flagged | 1 some new line unmarked | 2 NOT CHECKED (archive
+// or baseline missing).
+if (require.main === module) {
+  const { loadConfig } = require('../config');
+  const json = process.argv.includes('--json');
+  const record = process.argv.includes('--record-baseline');
+  const genesis = process.argv.includes('--genesis');
+  const auditBaseline = process.argv.includes('--audit-baseline');
+  const { config } = loadConfig();
+  const baselineFile = process.env.MEMORY_LINT_BASELINE ||
+    path.resolve(process.cwd(), config.provenance.baselineFile);
+  const markers = (config.provenance && config.provenance.markers) || DEFAULT_MARKERS;
+
+  if (auditBaseline) {
+    const g = auditBaselineGit({ file: baselineFile });
+    const code = g.state === 'ok' ? 0 : g.state === 'dirty' ? 1 : 2;
+    const msg =
+      g.state === 'ok'
+        ? `PROVENANCE: baseline ${g.file} is clean in git.`
+        : g.state === 'dirty'
+          ? `PROVENANCE: BASELINE CHANGED AND NOT COMMITTED - ${g.file}\n` +
+            g.pending.map((p) => `  ${p}`).join('\n') +
+            '\nCommit the change (or `git checkout -- <file>` if it was unintentional).'
+          : `PROVENANCE: NOT CHECKED (${g.reason}) - ${g.detail}`;
+    if (json) console.log(JSON.stringify({ baseline: g.file, state: g.state, reason: g.reason || null, pending: g.pending || null, detail: g.detail || null }, null, 2));
+    else console.log(msg);
+    if (code !== 0) console.error(msg);
+    process.exit(code);
+  }
+
+  const { dir, source } = locateArchive();
+  const notChecked = (state, msg) => {
+    if (json) console.log(JSON.stringify({ dir, source, baseline: baselineFile, state, summary: null, lines: null }, null, 2));
+    else console.log(msg);
+    console.error(msg);
+    process.exit(2);
+  };
+
+  if (!fs.existsSync(dir)) {
+    notChecked('absent', `PROVENANCE: ARCHIVE NOT CHECKED - ${dir} not found (path from ${source}).`);
+  }
+
+  const r = readCollection(dir);
+
+  if (genesis) {
+    const b = generateBaseline(r.files);
+    fs.writeFileSync(baselineFile, JSON.stringify(b, null, 2) + '\n', 'utf8');
+    const lineCount = Object.values(b.files).reduce((n, l) => n + l.length, 0);
+    const msg = `PROVENANCE: GENESIS written to ${baselineFile} - ${r.files.length} file(s), ${lineCount} line(s) exempted, unfiltered. Commit this write.`;
+    if (json) console.log(JSON.stringify({ dir, baseline: baselineFile, state: 'genesis_written', mode: 'genesis', files: r.files.length, lines: lineCount }, null, 2));
+    else console.log(msg);
+    process.exit(0);
+  }
+
+  if (record) {
+    let current = {};
+    if (fs.existsSync(baselineFile)) {
+      try {
+        current = JSON.parse(fs.readFileSync(baselineFile, 'utf8')).files || {};
+      } catch (e) {
+        notChecked('baseline_unreadable', `PROVENANCE: NOT CHECKED - baseline ${baselineFile} is unreadable. Fix the JSON or restore it from git.`);
+      }
+    }
+    const { doc, added, rejected, rejectedByFile } = generateIncrementalBaseline(r.files, current);
+    fs.writeFileSync(baselineFile, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+    const lineCount = Object.values(doc.files).reduce((n, l) => n + l.length, 0);
+    const msg =
+      `PROVENANCE: incremental baseline written to ${baselineFile} - ${r.files.length} file(s), ` +
+      `${lineCount} line(s) exempt total: +${added} added, ${rejected} REJECTED for asserting a ` +
+      `verifiable fact without a marker.` +
+      (rejected
+        ? `\nRejected lines stay in the gate - mark the source: (${markers.join(') / (')}).\n` +
+          Object.entries(rejectedByFile).map(([n, q]) => `  ${n}: ${q} line(s)`).join('\n')
+        : '') +
+      `\nCommit this rewrite.`;
+    if (json) console.log(JSON.stringify({ dir, baseline: baselineFile, state: 'baseline_written', mode: 'incremental', files: r.files.length, lines: lineCount, added, rejected, rejectedByFile }, null, 2));
+    else console.log(msg);
+    process.exit(0);
+  }
+
+  if (!fs.existsSync(baselineFile)) {
+    notChecked('baseline_absent', `PROVENANCE: NOT CHECKED - baseline ${baselineFile} not found. Run --genesis once to create it.`);
+  }
+
+  let baseline = null;
+  try {
+    baseline = JSON.parse(fs.readFileSync(baselineFile, 'utf8')).files || null;
+  } catch (e) {
+    baseline = null;
+  }
+  if (!baseline) {
+    notChecked('baseline_absent', `PROVENANCE: NOT CHECKED - baseline ${baselineFile} is unreadable or missing "files".`);
+  }
+
+  const lines = auditProvenance(r.files, { baseline, markers });
+  const summary = summarizeProvenance(lines);
+  const state = summary.failed > 0 ? 'failed' : 'ok';
+
+  if (json) {
+    console.log(JSON.stringify({ dir, source, baseline: baselineFile, state, summary, lines: lines.filter((l) => l.state === 'unmarked') }, null, 2));
+  } else {
+    console.log(`archive: ${dir}  (${source})`);
+    console.log(`baseline: ${baselineFile}`);
+    console.log(`files: ${summary.total}  with new lines: ${summary.filesWithNewLines}`);
+    console.log(`lines in scope: ${summary.linesInScope}  out of scope: ${summary.linesOutOfScope}  (occurrences: ${summary.occurrences})`);
+    if (summary.failed) {
+      console.log(`\nPROVENANCE: ${summary.failed} failed.`);
+      for (const l of lines.filter((x) => x.state === 'unmarked')) {
+        for (const o of l.occurrences) {
+          console.log(`  ${l.name}:${o.line}  [${o.triggers.join('+')}]`);
+          console.log(`     ... ${o.excerpt} ...`);
+        }
+      }
+      console.log(`\nMark the source: (${markers.join(') / (')}).`);
+    } else {
+      console.log('\nPROVENANCE: no unmarked new line.');
+    }
+    if (summary.linesOutOfScope) {
+      console.log(`\nDECLARED BACKLOG: ${summary.linesOutOfScope} line(s) predating the baseline are not judged here.`);
+    }
+  }
+  process.exit(summary.failed > 0 ? 1 : 0);
+}

package/lib/index.js

@@ -0,0 +1,13 @@
+'use strict';
+module.exports = {
+  collector: require('./collector'),
+  maskCode: require('./mask-code').maskCode,
+  locateArchive: require('./locate-archive').locateArchive,
+  config: require('./config'),
+  budget: require('./detectors/budget'),
+  frontmatter: require('./detectors/frontmatter'),
+  provenance: require('./detectors/provenance'),
+  perishable: require('./detectors/perishable'),
+  pii: require('./detectors/pii'),
+  honesty: require('./detectors/honesty'),
+};