create-pmos 0.46.0 → 0.48.0

package/workspace/lib/jev-categorize.js

@@ -0,0 +1,399 @@
+'use strict';
+/* jev-categorize.js — ask Jev what kind of document a file is, only when the local rules cannot tell (D82).
+ *
+ * This is the BRIDGE between the document categorizer (lib/doc-category.js, local and pure) and the one TypeSafe module
+ * (lib/typesafe.js). `doc-category.js` never reaches that module; this file is the categorizer's only way to it.
+ *
+ * WHAT MAY LEAVE THE MACHINE. For a Markdown file the local rules leave `undetermined`: its title, its headings and the
+ * opening of its body, at most SNIPPET_MAX characters, and one Choice question over the categories. Never the path, never
+ * the frontmatter, never the whole file. Only when ALL THREE gates hold: a saved key, D79 consent for the repository, and
+ * the "categorize with Jev" switch. A file under an excluded path, or a snippet the secret scan matches, is withheld.
+ *
+ * HOW IT STAYS CHEAP. The first run shows its request count and sends only after the PM confirms that number. Afterwards
+ * a pass sends only snippets with no cached answer (a new file, or a changed one); a pass of more than AUTO_LIMIT waits for
+ * the same confirmation. An answer is cached by the hash of the snippet, the question and the model, so an unchanged
+ * snippet, or a revert, is never asked twice.
+ *
+ * WHAT A RESULT IS. Advisory (D40), basis `jev`, shown in words. The ticket options are summed into one `ticket` first;
+ * a top category under 0.6, or within 0.1 of the next, is `undetermined` with the two leading options named (C6).
+ *
+ * WHAT IT NEVER DOES. It writes nothing into the repository. Its state (confirmation, pause, cache) lives in the per-user
+ * cache directory the caller passes. Two rejected keys or three failed asks in a row pause the repository until resumed.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const DC = require('./doc-category');
+const scanner = require('./secret-scan');
+const settings = require('./typesafe-settings');
+const typesafe = require('./typesafe');
+
+const SNIPPET_MAX = 3000;
+const HEADINGS_MAX = 1000;
+const AUTO_LIMIT = 25;
+const MAX_CACHE = 5000;
+const MAX_LISTED = 20;
+const REJECTED_LIMIT = 2;
+const UNREACHABLE_LIMIT = 3;
+const UNSURE_BELOW = 0.6;
+const UNSURE_GAP = 0.1;
+const UNREADABLE_LIMIT = 3;
+const sha = (s) => crypto.createHash('sha1').update(s).digest('hex');
+
+/* The Choice options. A ticket is three options, so one question decides the category and the ticket kind. */
+const OPTIONS = {
+  prd: 'A product requirements document: the problem, the requirements and how success is judged.',
+  'meeting-notes': 'Notes from a meeting: who attended, what was discussed, decisions and action items.',
+  report: 'A report: a status update, findings, results, metrics or a post-mortem about work already done.',
+  'ticket-design': 'A ticket for design work: a UI, UX or visual change, with acceptance criteria.',
+  'ticket-engineering': 'A ticket for engineering work: a bug, a defect or a technical task, with steps or acceptance criteria.',
+  'ticket-other': 'A ticket for any other kind of work item.',
+  knowledge: 'Explanatory knowledge: a concept, a guide, a how-to or reference material.',
+  'spec-artifact': 'A control record of the delivery process: a rubric, an initiative record, a user story or a decision record.',
+  other: 'None of the kinds above.',
+};
+const INSTRUCTIONS = 'Which kind of document is this? Judge from its title, its headings and its opening, given below.';
+// The question's own text is in the cache key, so editing an option or the instructions asks again; no version tag to forget.
+const QUESTION_HASH = sha(JSON.stringify([INSTRUCTIONS, OPTIONS]));
+
+const wordsFor = (p) => (p >= 0.85 ? 'very likely' : 'likely');
+
+/** Which of the three gates is shut. `open` only when none is. */
+function gates({ key, consent, categorize }) {
+  const missing = [];
+  if (!key) missing.push('key');
+  if (!consent) missing.push('consent');
+  if (!categorize) missing.push('categorize');
+  return { open: missing.length === 0, missing };
+}
+const GATE_WORDS = {
+  key: 'No TypeSafe key is saved.',
+  consent: 'Validation is not switched on for this repository.',
+  categorize: 'Categorizing with Jev is off for this repository.',
+};
+const gateSentence = (missing) => missing.map((m) => GATE_WORDS[m]).join(' ');
+
+/* ── the snippet ───────────────────────────────────────────────────────────────────────────────── */
+const FRONTMATTER = /^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+const clip = (s, n) => (s.length > n ? s.slice(0, n) : s);
+
+/** The text that may be sent for one document: title, headings, opening. Never longer than SNIPPET_MAX. Pure. */
+function snippetFor({ fm = {}, text = '' }) {
+  const body = String(text || '').replace(/^\uFEFF/, '').replace(FRONTMATTER, '');
+  const heads = [];
+  for (const m of body.matchAll(/^#{1,6}\s+(.+?)\s*#*\s*$/gm)) heads.push(clip(m[1].replace(/\s+/g, ' '), 120));
+  const title = clip(String((fm && fm.title) || heads[0] || '').replace(/\s+/g, ' ').trim(), 200) || '(none)';
+  let hs = '';
+  for (const h of heads) { const line = '- ' + h + '\n'; if (hs.length + line.length > HEADINGS_MAX) break; hs += line; }
+  const head = `TITLE: ${title}\nHEADINGS:\n${hs || '(none)\n'}\nOPENING:\n`;
+  const opening = body.replace(/^#{1,6}\s+.*$/gm, '').replace(/\s+/g, ' ').trim();
+  return clip(head + opening, SNIPPET_MAX);
+}
+
+const keyFor = (snip) => sha([sha(snip), QUESTION_HASH, typesafe.DEFAULT_MODEL].join('\0'));
+const requestFor = (snip) => ({ state: snip, questions: { category: { type: 'choice', instructions: INSTRUCTIONS, criteria: OPTIONS } } });
+
+/** The documents the local rules leave undetermined. Only these may ever be sent. Pure. */
+function candidates(docs, named = new Map()) {
+  const out = [];
+  for (const d of docs || []) {
+    const rel = String(d.rel || '').replace(/\\/g, '/');
+    if (!/\.md$/i.test(rel)) continue;
+    const r = DC.categorize({ rel, fm: d.fm || {}, text: d.text || '', named, correction: d.correction || null });   // a PM correction decides too
+    if (r.decided || r.category !== DC.UNDETERMINED) continue;
+    out.push({ rel, fm: d.fm || {}, text: d.text || '' });
+  }
+  return out;
+}
+
+/* ── reading an answer ─────────────────────────────────────────────────────────────────────────── */
+/** The answer's probability per option, or null. Read defensively: the shape is documented only by a third party (D82). */
+function readAnswer(ans) {
+  if (!ans || typeof ans !== 'object') return null;
+  const probs = {};
+  const put = (k, v) => { const n = Number(v); if (Object.prototype.hasOwnProperty.call(OPTIONS, k) && Number.isFinite(n) && n >= 0 && n <= 1) probs[k] = n; };
+  const raw = ans.probabilities || ans.distribution;
+  if (Array.isArray(raw)) { for (const x of raw) if (x && typeof x === 'object') put(x.option || x.label || x.choice, x.probability != null ? x.probability : x.p); }
+  else if (raw && typeof raw === 'object') { for (const [k, v] of Object.entries(raw)) put(k, v); }
+  if (!Object.keys(probs).length && typeof ans.choice === 'string') put(ans.choice, ans.confidence);
+  if (!Object.keys(probs).length) return null;
+  const sum = Object.values(probs).reduce((a, b) => a + b, 0);
+  if (sum > 1.05) return null;                                         // not a distribution
+  return probs;
+}
+
+/** C6 on Jev's answer: fold the ticket options, then decide or stay undetermined with the two leading options. Pure. */
+function decide(probs) {
+  const cat = {};
+  let ticketKind = null, ticketBest = -1;
+  for (const [k, v] of Object.entries(probs || {})) {
+    if (k.startsWith('ticket-')) {
+      cat.ticket = (cat.ticket || 0) + v;
+      if (v > ticketBest) { ticketBest = v; ticketKind = k.slice('ticket-'.length); }
+    } else cat[k] = (cat[k] || 0) + v;
+  }
+  const ranked = Object.entries(cat).sort((a, b) => b[1] - a[1]);
+  if (!ranked.length) return null;
+  const [top, second] = [ranked[0], ranked[1] || [null, 0]];
+  const leading = [top, second].filter((x) => x[0]).map(([category, p]) => ({ category, p: Math.round(p * 1000) / 1000 }));
+  if (top[1] < UNSURE_BELOW || top[1] - second[1] < UNSURE_GAP) {
+    return { decided: false, category: DC.UNDETERMINED, ticket_kind: null, p: null, leading };
+  }
+  return { decided: true, category: top[0], ticket_kind: top[0] === 'ticket' ? ticketKind : null, p: Math.round(top[1] * 1000) / 1000, leading };
+}
+
+/** One sentence for the page: what Jev said, in words, never the number. */
+function sentenceFor(d) {
+  if (!d) return null;
+  if (!d.decided) return d.leading.length > 1 ? `Jev was unsure: ${d.leading.map((x) => x.category).join(' or ')} (advisory).` : `Jev was unsure: ${d.leading[0].category}, and it reported no other option (advisory).`;
+  return `Jev rates it ${wordsFor(d.p)} that this is ${d.category === 'ticket' ? 'a ' + d.ticket_kind + ' ticket' : d.category} (advisory).`;
+}
+
+/* ── per-user state ────────────────────────────────────────────────────────────────────────────── */
+const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
+function writeJson(f, v) {
+  try { fs.mkdirSync(path.dirname(f), { recursive: true }); const tmp = f + '.' + process.pid + '.tmp'; fs.writeFileSync(tmp, JSON.stringify(v)); fs.renameSync(tmp, f); return true; }
+  catch { return false; }
+}
+const stateFile = (cacheDir) => path.join(cacheDir, 'jev-categorize.json');
+const cacheFile = (cacheDir) => path.join(cacheDir, 'jev-categorize-cache.json');
+/* One pass at a time per repository, across processes: the workspace's passes and the bench's measured pass write the same
+ * cache and state files, so a second pass would lose the first one's answers or its pause. A lock older than LOCK_STALE_MS is
+ * left over from a crash and is taken over. */
+const LOCK_STALE_MS = 10 * 60 * 1000;
+const lockFile = (cacheDir) => path.join(cacheDir, 'jev-categorize.lock');
+function takeLock(cacheDir) {
+  const f = lockFile(cacheDir);
+  try { fs.mkdirSync(cacheDir, { recursive: true }); } catch { /* the write below reports it */ }
+  for (let i = 0; i < 2; i++) {
+    try { fs.writeFileSync(f, JSON.stringify({ pid: process.pid, at: Date.now() }), { flag: 'wx' }); return true; }
+    catch (e) {
+      if (!e || e.code !== 'EEXIST') return true;                         // no lock possible here; the state writes fail the same way
+      const held = readJson(f, null);
+      if (held && typeof held.at === 'number' && Date.now() - held.at < LOCK_STALE_MS) return false;
+      try { fs.unlinkSync(f); } catch { /* another process took it over first */ }
+    }
+  }
+  return false;
+}
+function dropLock(cacheDir) { try { fs.unlinkSync(lockFile(cacheDir)); } catch { /* already gone */ } }
+const BUSY = 'Another pass is categorizing this repository now, so nothing was sent. Try again when it ends.';
+async function locked(cacheDir, busy, fn) {
+  if (!takeLock(cacheDir)) return busy;
+  try { return await fn(); } finally { dropLock(cacheDir); }
+}
+
+const emptyState = () => ({ confirmed: false, confirmed_at: null, paused: null, rejected: 0, unreachable: 0, unreadable: 0, last: null });
+function readState(cacheDir) {
+  const s = readJson(stateFile(cacheDir), null);
+  return s && typeof s === 'object' ? { ...emptyState(), ...s } : emptyState();
+}
+const writeState = (cacheDir, s) => writeJson(stateFile(cacheDir), s);
+function readCache(cacheDir) { const c = readJson(cacheFile(cacheDir), {}); return c && typeof c === 'object' && !Array.isArray(c) ? c : {}; }
+function writeCache(cacheDir, c) {
+  const keys = Object.keys(c);
+  if (keys.length > MAX_CACHE) for (const k of keys.sort((a, b) => String(c[a].at).localeCompare(String(c[b].at))).slice(0, keys.length - MAX_CACHE)) delete c[k];
+  return writeJson(cacheFile(cacheDir), c);
+}
+
+/** What the page may know about the bridge for one repository. */
+function status(cacheDir) {
+  const s = readState(cacheDir);
+  return { confirmed: s.confirmed, confirmed_at: s.confirmed_at, paused: s.paused, last: s.last };
+}
+/** The PM's press: lift a pause and forget the failure counts. */
+function resume(cacheDir) {
+  const s = readState(cacheDir);
+  s.paused = null; s.rejected = 0; s.unreachable = 0; s.unreadable = 0;
+  return writeState(cacheDir, s);
+}
+
+/** Jev's cached answer for one locally undetermined document, or null. Reads only; sends nothing. */
+function lookup(cache, doc) {
+  const hit = cache && cache[keyFor(snippetFor(doc))];
+  if (!hit || !hit.probs) return null;                                  // an unreadable answer is cached as a marker, never shown
+  const d = decide(hit.probs);
+  return d ? { ...d, model: hit.model || null, sentence: sentenceFor(d) } : null;
+}
+
+/** Triage the candidates: excluded, withheld by the secret scan, answered from the cache, or to ask. Pure; sends nothing. */
+function triage(cands, { exclude = [], cache }) {
+  const out = { ask: [], cached: 0, withheld: [], excluded: 0 };
+  for (const d of cands) {
+    if (settings.isExcluded(exclude, d.rel)) { out.excluded++; continue; }
+    const snip = snippetFor(d);
+    const rules = scanner.scan(snip);
+    if (rules.length) { out.withheld.push({ doc: d.rel, rules }); continue; }
+    const ck = keyFor(snip);
+    if (cache[ck]) out.cached++; else out.ask.push({ rel: d.rel, snip, ck });
+  }
+  return out;
+}
+
+/* ── asking ────────────────────────────────────────────────────────────────────────────────────── */
+async function askAll({ items, key, ask, askOpts, state, cache, now }) {
+  let failed = 0, unreadable = 0, sent = 0, decided = 0, unsure = 0, lastError = null;
+  const asked = new Set();
+  for (const it of items) {
+    if (state.paused) break;
+    if (asked.has(it.ck)) continue;                                      // two files with one snippet: one request
+    asked.add(it.ck);
+    const req = requestFor(it.snip);
+    const res = await ask({ key, state: req.state, questions: req.questions, ...askOpts });
+    if (!res.ok) {
+      failed++; lastError = res.reason;
+      if (res.status === 401) { state.rejected++; state.unreachable = 0; } else { state.unreachable++; state.rejected = 0; }
+      if (state.rejected >= REJECTED_LIMIT) state.paused = { reason: 'The service rejected the key twice, so categorizing with Jev is paused.', at: new Date(now).toISOString() };
+      else if (state.unreachable >= UNREACHABLE_LIMIT) state.paused = { reason: 'The service could not be reached three times in a row, so categorizing with Jev is paused.', at: new Date(now).toISOString() };
+      continue;                                                          // not cached: asked again next time
+    }
+    state.rejected = 0; state.unreachable = 0; sent++;
+    const probs = readAnswer(res.answers && res.answers.category);
+    if (!probs) {
+      // Cached as a marker, so no later pass sends the same snippet again; three in a row pause the repository, because
+      // that is what a changed answer format looks like.
+      unreadable++; state.unreadable = (state.unreadable || 0) + 1;
+      cache[it.ck] = { probs: null, unreadable: true, model: res.model || null, at: new Date(now).toISOString() };
+      if (state.unreadable >= UNREADABLE_LIMIT) state.paused = { reason: 'Jev\'s answers could not be read three times in a row, so categorizing with Jev is paused.', at: new Date(now).toISOString() };
+      continue;
+    }
+    state.unreadable = 0;
+    cache[it.ck] = { probs, model: res.model || null, at: new Date(now).toISOString() };
+    if (decide(probs).decided) decided++; else unsure++;
+  }
+  return { failed, unreadable, sent, decided, unsure, lastError };
+}
+
+const summarize = (extra) => ({ at: new Date().toISOString(), sent: 0, cached: 0, withheld: [], excluded: 0, failed: 0, decided: 0, unsure: 0, ...extra });
+const gatesFor = (key, flags) => gates({ key: typesafe.validKey(key), consent: !!(flags && flags.consent), categorize: !!(flags && flags.categorize) });
+
+/** Which snippets a plan sends, as one hash, so a confirmation covers those files and not merely that count. */
+const fingerprintOf = (ask) => sha(Array.from(new Set(ask.map((x) => x.ck))).sort().join('\n'));
+
+/** What a confirmed run would send now. Sends nothing. */
+function plan({ docs, named, cacheDir, exclude = [] }) {
+  const cands = candidates(docs, named);
+  const t = triage(cands, { exclude, cache: readCache(cacheDir) });
+  const unique = new Set(t.ask.map((x) => x.ck)).size;
+  return { candidates: cands.length, requests: unique, fingerprint: fingerprintOf(t.ask), characters: t.ask.reduce((n, x) => n + x.snip.length, 0), cached: t.cached,
+    withheld: t.withheld.slice(0, MAX_LISTED), withheld_count: t.withheld.length, excluded: t.excluded, host: typesafe.HOST, confirmed: readState(cacheDir).confirmed };
+}
+
+/**
+ * The PM's confirmed run. Refuses unless `expectRequests` is what the plan counts now, so the PM never confirms one plan
+ * and runs another. The first such run is what lets later passes send on their own.
+ */
+async function runConfirmed(opts) {
+  const g = gatesFor(opts.key, opts.flags);
+  if (!g.open) return { ok: false, error: gateSentence(g.missing), missing: g.missing };
+  return locked(opts.cacheDir, { ok: false, busy: true, error: BUSY }, () => confirmedPass(opts));
+}
+async function confirmedPass({ docs, named, cacheDir, key, exclude = [], expectRequests, expectFingerprint = null, ask = typesafe.ask, askOpts = {}, now = Date.now() }) {
+  const state = readState(cacheDir);
+  if (state.paused) return { ok: false, error: state.paused.reason + ' Resume it first.' };
+  const cache = readCache(cacheDir);
+  const t = triage(candidates(docs, named), { exclude, cache });
+  const unique = new Set(t.ask.map((x) => x.ck)).size;
+  if (!Number.isInteger(expectRequests) || expectRequests !== unique) {
+    return { ok: false, conflict: true, error: `the plan changed — it now has ${unique} request(s), not ${expectRequests}. Review it again.` };
+  }
+  if (expectFingerprint !== null && expectFingerprint !== fingerprintOf(t.ask)) {
+    return { ok: false, conflict: true, error: 'the plan changed — the same number of files, but not the same files. Review it again.' };
+  }
+  const r = await askAll({ items: t.ask, key, ask, askOpts, state, cache, now });
+  state.confirmed = true; state.confirmed_at = state.confirmed_at || new Date(now).toISOString();
+  state.last = summarize({ confirmed: true, sent: r.sent, cached: t.cached, withheld: t.withheld.slice(0, MAX_LISTED), withheld_count: t.withheld.length, excluded: t.excluded, failed: r.failed, unreadable: r.unreadable, decided: r.decided, unsure: r.unsure, error: r.lastError, paused: state.paused });
+  writeCache(cacheDir, cache); writeState(cacheDir, state);
+  return { ok: true, sent: r.sent, cached: t.cached, withheld: t.withheld.length, excluded: t.excluded, failed: r.failed, unreadable: r.unreadable, decided: r.decided, unsure: r.unsure, paused: state.paused };
+}
+
+/**
+ * The automatic pass, after a confirmed first run: only snippets with no cached answer, and at most AUTO_LIMIT of them.
+ * Does nothing unless all three gates hold.
+ */
+async function runAuto(opts) {
+  const g = gatesFor(opts.key, opts.flags);
+  if (!g.open) return { ok: true, skipped: 'gates', missing: g.missing, sent: 0 };
+  return locked(opts.cacheDir, { ok: true, skipped: 'busy', sent: 0 }, () => autoPass(opts));
+}
+async function autoPass({ docs, named, cacheDir, key, exclude = [], ask = typesafe.ask, askOpts = {}, now = Date.now() }) {
+  const state = readState(cacheDir);
+  if (state.paused) return { ok: true, skipped: 'paused', paused: state.paused, sent: 0 };
+  if (!state.confirmed) return { ok: true, skipped: 'not-confirmed', sent: 0 };
+  const cache = readCache(cacheDir);
+  const t = triage(candidates(docs, named), { exclude, cache });
+  const unique = new Set(t.ask.map((x) => x.ck)).size;
+  if (!unique) return { ok: true, skipped: 'nothing-new', sent: 0 };
+  if (unique > AUTO_LIMIT) {
+    state.last = summarize({ waiting: unique, cached: t.cached, withheld_count: t.withheld.length, excluded: t.excluded });
+    writeState(cacheDir, state);
+    return { ok: true, skipped: 'needs-confirmation', requests: unique, sent: 0 };
+  }
+  const r = await askAll({ items: t.ask, key, ask, askOpts, state, cache, now });
+  state.last = summarize({ sent: r.sent, cached: t.cached, withheld: t.withheld.slice(0, MAX_LISTED), withheld_count: t.withheld.length, excluded: t.excluded, failed: r.failed, unreadable: r.unreadable, decided: r.decided, unsure: r.unsure, error: r.lastError, paused: state.paused });
+  writeCache(cacheDir, cache); writeState(cacheDir, state);
+  return { ok: true, sent: r.sent, cached: t.cached, failed: r.failed, decided: r.decided, unsure: r.unsure, paused: state.paused };
+}
+
+/* ── the measured pass (Run 3): the labelled set through Jev, started by the PM's own press ──────────────────────────── */
+/* It measures Jev, so it sends labelled files the local rules already decide, not only the undetermined ones (D82 point 11).
+ * A file the PM corrected is never sent. The gates, the exclusions, the secret scan and the confirmed count and files still
+ * hold. It reports agreement in the open, including when it is poor. */
+function measureItems(rows, exclude) {
+  const items = []; const withheld = []; let excluded = 0; let corrected = 0;
+  for (const r of rows || []) {
+    const rel = String(r.rel || '').replace(/\\/g, '/');
+    if (r.corrected) { corrected++; continue; }
+    if (settings.isExcluded(exclude, rel)) { excluded++; continue; }
+    const snip = snippetFor(r);
+    const rules = scanner.scan(snip);
+    if (rules.length) { withheld.push({ doc: rel, rules }); continue; }
+    items.push({ rel, snip, ck: keyFor(snip), expected: r.expected });
+  }
+  return { items, withheld, excluded, corrected };
+}
+/** What the measured pass would send. Sends nothing. */
+function measurePlan({ rows, exclude = [] }) {
+  const m = measureItems(rows, exclude);
+  const unique = new Set(m.items.map((x) => x.ck)).size;
+  return { labelled: (rows || []).length, requests: unique, fingerprint: fingerprintOf(m.items), characters: m.items.reduce((n, x) => n + x.snip.length, 0),
+    withheld_count: m.withheld.length, excluded: m.excluded, corrected: m.corrected, host: typesafe.HOST };
+}
+/** The measured pass. Refuses unless the gates hold and the PM confirmed this plan's count (and, when given, its files). */
+async function measure(opts) {
+  const g = gatesFor(opts.key, opts.flags);
+  if (!g.open) return { ok: false, error: gateSentence(g.missing), missing: g.missing };
+  return locked(opts.cacheDir, { ok: false, busy: true, error: BUSY }, () => measuredPass(opts));
+}
+async function measuredPass({ rows, cacheDir, key, exclude = [], expectRequests, expectFingerprint = null, ask = typesafe.ask, askOpts = {}, now = Date.now() }) {
+  const state = readState(cacheDir);
+  if (state.paused) return { ok: false, error: state.paused.reason + ' Resume it first.' };
+  const m = measureItems(rows, exclude);
+  const unique = new Set(m.items.map((x) => x.ck)).size;
+  if (!Number.isInteger(expectRequests) || expectRequests !== unique || (expectFingerprint !== null && expectFingerprint !== fingerprintOf(m.items))) {
+    return { ok: false, conflict: true, error: `the plan changed — it now has ${unique} request(s), not ${expectRequests}. Review it again.` };
+  }
+  const cache = readCache(cacheDir);
+  const toAsk = m.items.filter((x) => !cache[x.ck]);                       // a cached answer is the same answer; not asked twice
+  const r = await askAll({ items: toAsk, key, ask, askOpts, state, cache, now });
+  writeCache(cacheDir, cache); writeState(cacheDir, state);
+  const per = {}; const disagreements = []; let right = 0, answered = 0, unsure = 0, unreadable = 0, missing = 0;
+  for (const it of m.items) {
+    const hit = cache[it.ck];
+    if (!hit) { missing++; continue; }
+    if (!hit.probs) { unreadable++; continue; }
+    const d = decide(hit.probs);
+    const row = per[it.expected] || (per[it.expected] = { labelled: 0, right: 0, unsure: 0 });
+    row.labelled++; answered++;
+    if (!d.decided) { unsure++; row.unsure++; disagreements.push({ doc: it.rel, expected: it.expected, got: 'undetermined', leading: d.leading.map((x) => x.category) }); continue; }
+    if (d.category === it.expected) { right++; row.right++; } else disagreements.push({ doc: it.rel, expected: it.expected, got: d.category, words: wordsFor(d.p) });
+  }
+  return { ok: true, sent: r.sent, failed: r.failed, paused: state.paused, labelled: (rows || []).length, answered, right, unsure, unreadable, not_answered: missing,
+    agreement: answered ? right / answered : null, by_category: per, disagreements, withheld_count: m.withheld.length, excluded: m.excluded, corrected: m.corrected };
+}
+
+module.exports = {
+  plan, runConfirmed, runAuto, measurePlan, measure, status, resume, lookup, readCache, gates, gateSentence, candidates, snippetFor, requestFor,
+  readAnswer, decide, sentenceFor, wordsFor, keyFor, triage,
+  OPTIONS, SNIPPET_MAX, AUTO_LIMIT, REJECTED_LIMIT, UNREACHABLE_LIMIT, UNREADABLE_LIMIT, UNSURE_BELOW, UNSURE_GAP,
+};

package/workspace/lib/jev-claims.js

@@ -36,11 +36,14 @@ const REJECTED_LIMIT = 2;
 const UNREACHABLE_LIMIT = 3;
 const sha = (s) => crypto.createHash('sha1').update(s).digest('hex');
 
+const STATUS_KINDS = new Set(['stub', 'contradicts']);
 const QUESTION_LABEL = {
   coverage: ['REQUIREMENT', 'RUBRIC DIMENSIONS'],
   delivers: ['STORY SECTION', 'REQUIREMENTS IT CITES'],
   supports: ['SENTENCE THAT CITES A DECISION', 'THE DECISION'],
   sections: ['FIRST SECTION', 'SECOND SECTION'],
+  stub: ['DOCUMENT', 'THE INITIATIVE IT BELONGS TO'],
+  contradicts: ['NOTE', 'REQUIREMENTS OF THE INITIATIVE IT NAMES'],
 };
 
 /** Words, never the number. */
@@ -71,7 +74,7 @@ function writeJson(f, v) {
 }
 const stateFile = (cacheDir) => path.join(cacheDir, 'jev.json');
 const cacheFile = (cacheDir) => path.join(cacheDir, 'jev-cache.json');
-const emptyState = () => ({ baselined: false, baselined_at: null, pairs: {}, pending: 0, paused: null, rejected: 0, unreachable: 0, last: null });
+const emptyState = () => ({ status_baselined: false, status_ids: [], baselined: false, baselined_at: null, pairs: {}, pending: 0, paused: null, rejected: 0, unreachable: 0, last: null });
 function readState(cacheDir) {
   const s = readJson(stateFile(cacheDir), null);
   if (!s || typeof s !== 'object') return emptyState();
@@ -88,7 +91,7 @@ function writeCache(cacheDir, c) {
 /** What the page may know about the bridge for one repository. */
 function status(cacheDir) {
   const s = readState(cacheDir);
-  return { baselined: s.baselined, baselined_at: s.baselined_at, paused: s.paused, last: s.last, tracked: Object.keys(s.pairs).length };
+  return { baselined: s.baselined, baselined_at: s.baselined_at, paused: s.paused, last: s.last, tracked: Object.keys(s.pairs).length, status_baselined: !!s.status_baselined };
 }
 /** The PM's press: lift a pause and forget the failure counts. */
 function resume(cacheDir) {
@@ -98,7 +101,9 @@ function resume(cacheDir) {
 }
 
 /* ── one pair: what would happen to it ─────────────────────────────────────────────────────────── */
-const hashes = (p) => { const hA = sha(p.a), hB = sha(p.b); return { hA, hB, h: sha(hA + '\0' + hB), ck: sha([hA, hB, p.kind, typesafe.DEFAULT_MODEL].join('\0')) }; };
+// The cache key names the model REQUESTED. The caller passes a named version from the model policy
+// (prompt-model-routing R11), so a change of version misses the cache and a revert to a version hits it again.
+const hashes = (p, model = typesafe.DEFAULT_MODEL) => { const hA = sha(p.a), hB = sha(p.b); return { hA, hB, h: sha(hA + '\0' + hB), ck: sha([hA, hB, p.kind, model].join('\0')) }; };
 const requestFor = (p) => {
   const [la, lb] = QUESTION_LABEL[p.kind];
   return { state: `${la}:\n${p.a}\n\n${lb}:\n${p.b}`, questions: { [p.kind]: { type: 'noul', instructions: p.question } } };
@@ -109,15 +114,17 @@ function sentenceFor(p, p1) {
     case 'coverage': return `Jev rates it ${w} that ${p.a_label} in ${p.doc} is graded by no dimension of ${p.partner}.`;
     case 'delivers': return `Jev rates it ${w} that the story section "${p.subject}" in ${p.doc} does not deliver what ${(p.ids || []).join(', ')} in ${p.partner} asks for.`;
     case 'supports': return `Jev rates it ${w} that ${p.partner} does not support what ${p.doc} says it decides in the sentence that cites it.`;
+    case 'stub': return `Jev rates it ${w} that ${p.doc} is a stub, an outline or an unfinished draft.`;
+    case 'contradicts': return `Jev rates it ${w} that ${p.doc} says something that contradicts a requirement in ${p.partner}.`;
     default: return `Jev rates it ${w} that the ${p.a_label} sections of ${p.doc} contradict each other.`;
   }
 }
 
 /** Triage every pair: excluded, withheld by the secret scan, answered from the cache, or to ask. Pure; sends nothing. */
-function triage(pairs, { exclude, cache, state, onlyChanged }) {
+function triage(pairs, { exclude, cache, state, onlyChanged, model }) {
   const out = { ask: [], cached: [], withheld: [], excluded: 0, unchanged: 0 };
   for (const p of pairs) {
-    const hs = hashes(p);
+    const hs = hashes(p, model);
     if (onlyChanged && state.pairs[p.id] === hs.h) { out.unchanged++; continue; }
     if (settings.isExcluded(exclude, p.doc) || (p.partner && /\.\w+$/.test(p.partner) && settings.isExcluded(exclude, p.partner))) { out.excluded++; continue; }
     const rules = Array.from(new Set(scanner.scan(p.a).concat(scanner.scan(p.b))));
@@ -143,7 +150,7 @@ function recordResults({ ledgerFile, pairs, evaluated, now }) {
     if (verdict.p >= 0.5) {
       const sentence = sentenceFor(p, verdict.p); const likelihood = wordsFor(verdict.p);
       if (prev && prev.status === 'suspected' && prev.likelihood === likelihood && prev.text === p.a.slice(0, 220) && prev.sentence === sentence) continue;
-      append({ type: 'claim', claim_id: id, doc: p.doc, doc_type: 'PRD', kind: 'jev_' + p.kind, subject: p.subject, text: p.a.slice(0, 220), status: 'suspected',
+      append({ type: 'claim', claim_id: id, doc: p.doc, doc_type: p.doc_type || 'PRD', kind: 'jev_' + p.kind, initiative: p.initiative || undefined, subject: p.subject, text: p.a.slice(0, 220), status: 'suspected',
         probability: Math.round(verdict.p * 1000) / 1000, likelihood, truth: null, source: p.partner || null, sentence, model: verdict.model || null, verified_at: at, at });
     } else if (prev && prev.status === 'suspected') {
       append({ ...prev, status: 'withdrawn', sentence: null, verified_at: at, at });
@@ -196,17 +203,34 @@ async function run({ root, cacheDir, ledgerFile, key, flags, exclude = [], chang
   if (!g.open) return { ok: true, skipped: 'gates', missing: g.missing, sent: 0 };
   const state = readState(cacheDir);
   if (state.paused) return { ok: true, skipped: 'paused', paused: state.paused, sent: 0 };
-  if (state.baselined && changed === 0 && !state.pending) return { ok: true, skipped: 'nothing-changed', sent: 0 };
-  const { pairs } = claims.pairsFor({ root, cacheDir });
+  const statusOn = !!(flags && flags.status_read);
+  // A flip of the status switch is work even when no file changed: its baseline is recorded (or forgotten) now.
+  if (state.baselined && changed === 0 && !state.pending && statusOn === !!state.status_baselined) return { ok: true, skipped: 'nothing-changed', sent: 0 };
+  const { pairs } = claims.pairsFor({ root, cacheDir, statusKinds: statusOn });
   if (!state.baselined) {
     for (const p of pairs) state.pairs[p.id] = hashes(p).h;
     state.baselined = true; state.baselined_at = new Date(now).toISOString();
+    if (statusOn) { state.status_baselined = true; state.status_ids = pairs.filter((p) => STATUS_KINDS.has(p.kind)).map((p) => p.id); }
     state.last = summarize({ baseline: pairs.length });
     writeState(cacheDir, state);
     return { ok: true, baseline: pairs.length, sent: 0 };
   }
+  // D83: the status kinds have their own baseline. Switching "read documents for status" on records the documents that
+  // exist and sends nothing for them, exactly as D80's first pass does; switching it off forgets that baseline, so a
+  // later switch-on starts again from what exists then, never from what changed while it was off.
+  if (!statusOn && state.status_baselined) {
+    for (const id of state.status_ids || []) delete state.pairs[id];
+    state.status_baselined = false; state.status_ids = [];
+  }
+  if (statusOn && !state.status_baselined) {
+    const ids = [];
+    for (const p of pairs) if (STATUS_KINDS.has(p.kind)) { state.pairs[p.id] = hashes(p).h; ids.push(p.id); }
+    state.status_baselined = true; state.status_ids = ids;
+  }
+  // every status pair seen while the switch is on is remembered, so switching off forgets the ones added later too
+  if (statusOn) state.status_ids = Array.from(new Set((state.status_ids || []).concat(pairs.filter((p) => STATUS_KINDS.has(p.kind)).map((p) => p.id))));
   const cache = readCache(cacheDir);
-  const t = triage(pairs, { exclude, cache, state, onlyChanged: true });
+  const t = triage(pairs, { exclude, cache, state, onlyChanged: true, model: askOpts.model || typesafe.DEFAULT_MODEL });
   const evaluated = t.cached.map((c) => [c.p, c.verdict]);
   for (const c of t.cached) state.pairs[c.p.id] = c.hs.h;
   const r = await askAll({ items: t.ask, key, ask, askOpts, state, cache, now });
@@ -228,9 +252,9 @@ async function run({ root, cacheDir, ledgerFile, key, flags, exclude = [], chang
 }
 
 /* ── the backlog: every pair not already answered, after the PM has seen the count ─────────────── */
-function backlogPlan({ root, cacheDir, exclude = [] }) {
-  const { pairs } = claims.pairsFor({ root, cacheDir });
-  const t = triage(pairs, { exclude, cache: readCache(cacheDir), state: readState(cacheDir), onlyChanged: false });
+function backlogPlan({ root, cacheDir, exclude = [], model = typesafe.DEFAULT_MODEL, flags = null }) {
+  const { pairs } = claims.pairsFor({ root, cacheDir, statusKinds: !!(flags && flags.status_read) });
+  const t = triage(pairs, { exclude, cache: readCache(cacheDir), state: readState(cacheDir), onlyChanged: false, model });
   const reqs = t.ask.map((x) => requestFor(x.p));
   return { pairs: pairs.length, requests: reqs.length, characters: reqs.reduce((n, r) => n + r.state.length, 0), cached: t.cached.length, withheld: t.withheld.slice(0, MAX_LISTED), withheld_count: t.withheld.length, excluded: t.excluded, host: typesafe.HOST };
 }
@@ -241,9 +265,9 @@ async function runBacklog({ root, cacheDir, ledgerFile, key, flags, exclude = []
   if (!g.open) return { ok: false, error: gateSentence(g.missing) };
   const state = readState(cacheDir);
   if (state.paused) return { ok: false, error: state.paused.reason + ' Resume it first.' };
-  const { pairs } = claims.pairsFor({ root, cacheDir });
+  const { pairs } = claims.pairsFor({ root, cacheDir, statusKinds: !!(flags && flags.status_read) });
   const cache = readCache(cacheDir);
-  const t = triage(pairs, { exclude, cache, state, onlyChanged: false });
+  const t = triage(pairs, { exclude, cache, state, onlyChanged: false, model: askOpts.model || typesafe.DEFAULT_MODEL });
   if (!Number.isInteger(expectRequests) || expectRequests !== t.ask.length) {
     return { ok: false, conflict: true, error: `the plan changed — it now has ${t.ask.length} request(s), not ${expectRequests}. Review it again.` };
   }
@@ -263,4 +287,24 @@ async function runBacklog({ root, cacheDir, ledgerFile, key, flags, exclude = []
   return { ok: true, sent: r.sent, cached: t.cached.length, withheld: t.withheld.length, excluded: t.excluded, failed: r.failed, suspected, written, paused: state.paused };
 }
 
-module.exports = { run, runBacklog, backlogPlan, status, resume, gates, gateSentence, wordsFor, triage, requestFor, sentenceFor, REJECTED_LIMIT, UNREACHABLE_LIMIT };
+/**
+ * status-from-artifacts Run 2 (D83): the suggestions for ONE initiative, read from the claims ledger — suspected
+ * `jev_stub` and `jev_contradicts` claims on the documents tied to it. Read-only. A suggestion is advisory: the caller
+ * shows it beside the ladder and never lets it change a step, a stage or a count.
+ */
+function suggestionsFor({ ledgerFile, initiativeId }) {
+  const out = [];
+  let folded;
+  try { folded = claims.foldLedger(ledgerFile); } catch { return { ok: false, reason: 'the claims ledger could not be read', items: [] }; }
+  for (const [, e] of folded) {
+    if (!e || e.status !== 'suspected') continue;
+    if (e.kind !== 'jev_stub' && e.kind !== 'jev_contradicts') continue;
+    const iid = e.initiative || String(e.subject || '').split(':')[1];
+    if (iid !== initiativeId) continue;
+    out.push({ kind: e.kind.slice(4), doc: e.doc, partner: e.source || null, likelihood: e.likelihood || null, sentence: e.sentence || null, model: e.model || null, at: e.verified_at || e.at || null });
+  }
+  out.sort((a, b) => String(a.doc).localeCompare(String(b.doc)));
+  return { ok: true, items: out.slice(0, MAX_LISTED) };
+}
+
+module.exports = { suggestionsFor, run, runBacklog, backlogPlan, status, resume, gates, gateSentence, wordsFor, triage, requestFor, sentenceFor, REJECTED_LIMIT, UNREACHABLE_LIMIT };