create-pmos 0.40.0 → 0.42.0

package/workspace/lib/jev-claims.js

@@ -0,0 +1,266 @@
+'use strict';
+/* jev-claims.js — ask Jev about pairs of short claim texts, only for what changed (jev-claim-checks, D80).
+ *
+ * This is the BRIDGE between the claims ledger and the one TypeSafe module (lib/typesafe.js). `claims.js` and
+ * `repo-watch.js` never reach that module; this file, `validate.js` and `server.js` are the only ones that do.
+ *
+ * WHAT MAY LEAVE THE MACHINE. A pair of short texts (lib/claims.js `pairsFor`) and one Noul question, only when ALL
+ * FOUR gates hold: a saved key, D79 consent for the repository, the watch switch, and the "check with Jev
+ * automatically" switch. A text under an excluded path, or one the secret scan matches, is withheld and listed.
+ *
+ * HOW IT STAYS CHEAP. The first check after the switch goes on records every existing pair as a BASELINE and sends
+ * nothing. Afterwards a pair is sent only when either of its texts differs from the one last recorded. A verdict is
+ * cached by the hash of both texts, the question and the model, so an unchanged pair, or a revert, is never asked
+ * twice. There is no request cap: the baseline and the cache are what bound the cost. "Check the backlog" is a
+ * separate press that shows its request count first.
+ *
+ * WHAT A RESULT IS. `suspected`: advisory, outside the problem total, shown in words. A Noul answer is P(yes) with no
+ * separate confidence, so the page shows words, never the number. Two rejected keys or three failed asks in a row
+ * pause the repository until the PM resumes it.
+ *
+ * WHAT IT NEVER DOES. It edits no repository document, decision or acceptance. Its one write into the repository is
+ * the claims ledger, through lib/sink.js. Its state (baseline, cache, pause) lives in the per-user cache directory.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const claims = require('./claims');
+const scanner = require('./secret-scan');
+const settings = require('./typesafe-settings');
+const typesafe = require('./typesafe');
+const { createSinkGuard } = require('./sink');
+
+const MAX_CACHE = 5000;
+const MAX_LISTED = 20;
+const REJECTED_LIMIT = 2;
+const UNREACHABLE_LIMIT = 3;
+const sha = (s) => crypto.createHash('sha1').update(s).digest('hex');
+
+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'],
+};
+
+/** Words, never the number. */
+const wordsFor = (p) => (p >= 0.85 ? 'very likely' : p >= 0.65 ? 'likely' : 'possible');
+
+/** Which of the four gates is shut. `open` only when none is. */
+function gates({ key, consent, watch, jev }) {
+  const missing = [];
+  if (!key) missing.push('key');
+  if (!consent) missing.push('consent');
+  if (!watch) missing.push('watch');
+  if (!jev) missing.push('jev');
+  return { open: missing.length === 0, missing };
+}
+const GATE_WORDS = {
+  key: 'No TypeSafe key is saved.',
+  consent: 'Validation is not switched on for this repository.',
+  watch: 'Keeping this repository checked as files change is off.',
+  jev: 'Checking with Jev automatically is off.',
+};
+const gateSentence = (missing) => missing.map((m) => GATE_WORDS[m]).join(' ');
+
+/* ── 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.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 });
+function readState(cacheDir) {
+  const s = readJson(stateFile(cacheDir), null);
+  if (!s || typeof s !== 'object') return emptyState();
+  return { ...emptyState(), ...s, pairs: s.pairs && typeof s.pairs === 'object' ? s.pairs : {} };
+}
+const writeState = (cacheDir, s) => writeJson(stateFile(cacheDir), s);
+function readCache(cacheDir) { const c = readJson(cacheFile(cacheDir), {}); return c && typeof c === 'object' ? 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 { baselined: s.baselined, baselined_at: s.baselined_at, paused: s.paused, last: s.last, tracked: Object.keys(s.pairs).length };
+}
+/** 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;
+  return writeState(cacheDir, s);
+}
+
+/* ── 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')) }; };
+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 } } };
+};
+function sentenceFor(p, p1) {
+  const w = wordsFor(p1);
+  switch (p.kind) {
+    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.`;
+    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 }) {
+  const out = { ask: [], cached: [], withheld: [], excluded: 0, unchanged: 0 };
+  for (const p of pairs) {
+    const hs = hashes(p);
+    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))));
+    if (rules.length) { out.withheld.push({ doc: p.doc, kind: p.kind, rules }); continue; }
+    const hit = cache[hs.ck];
+    if (hit) out.cached.push({ p, hs, verdict: hit }); else out.ask.push({ p, hs });
+  }
+  return out;
+}
+
+/* ── the ledger: suspected claims in, withdrawn claims out ─────────────────────────────────────── */
+const claimIdOf = (p) => 'j' + sha('jev|' + p.doc + '|' + p.kind + '|' + p.subject).slice(0, 11);
+
+function recordResults({ ledgerFile, pairs, evaluated, now }) {
+  const folded = claims.foldLedger(ledgerFile);
+  const guard = createSinkGuard({ sink: ledgerFile, what: 'claims' });
+  const at = new Date(now).toISOString();
+  const currentIds = new Set(pairs.map(claimIdOf));
+  let written = 0;
+  const append = (e) => { guard.appendLine(ledgerFile, e); written++; };
+  for (const [p, verdict] of evaluated) {
+    const id = claimIdOf(p); const prev = folded.get(id);
+    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',
+        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 });
+    }
+  }
+  // a suspected claim whose pair no longer exists (the requirement or section was removed) is withdrawn
+  for (const [id, e] of folded) if (claims.isJev(e) && e.status === 'suspected' && !currentIds.has(id)) append({ ...e, status: 'withdrawn', sentence: null, verified_at: at, at });
+  return written;
+}
+
+/* ── asking ────────────────────────────────────────────────────────────────────────────────────── */
+async function askAll({ items, key, ask, askOpts, state, cache, now }) {
+  const done = []; let failed = 0, unreadable = 0, sent = 0, lastError = null;
+  for (const it of items) {
+    if (state.paused) break;
+    const req = requestFor(it.p);
+    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 automatic checking 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 automatic checking is paused.', at: new Date(now).toISOString() };
+      continue;                                                              // not recorded as seen: it is asked again next time
+    }
+    state.rejected = 0; state.unreachable = 0; sent++;
+    const ans = res.answers && res.answers[it.p.kind];
+    const v = ans && (ans.type == null || ans.type === 'noul') ? Number(ans.noul) : NaN;
+    if (!Number.isFinite(v) || v < 0 || v > 1) { unreadable++; state.pairs[it.p.id] = it.hs.h; continue; }
+    const verdict = { p: v, model: res.model || null, at: new Date(now).toISOString() };
+    cache[it.hs.ck] = verdict;
+    state.pairs[it.p.id] = it.hs.h;
+    done.push([it.p, verdict]);
+  }
+  return { done, failed, unreadable, sent, lastError };
+}
+
+const summarize = (extra) => ({ at: new Date().toISOString(), baseline: 0, sent: 0, cached: 0, withheld: [], excluded: 0, failed: 0, suspected: 0, ...extra });
+
+/**
+ * The automatic pass, called after a local check. Does nothing unless all four gates hold.
+ * @param {object} a
+ * @param {string} a.root, a.cacheDir, a.ledgerFile
+ * @param {string|null} a.key     the TypeSafe key, or null
+ * @param {{consent:boolean, watch:boolean, jev:boolean}} a.flags
+ * @param {string[]} [a.exclude]
+ * @param {number} [a.changed]    files the local check saw change; 0 after the baseline means nothing to do
+ */
+async function run({ root, cacheDir, ledgerFile, key, flags, exclude = [], changed = null, ask = typesafe.ask, askOpts = {}, now = Date.now() }) {
+  const g = gates({ key: typesafe.validKey(key), consent: !!(flags && flags.consent), watch: !!(flags && flags.watch), jev: !!(flags && flags.jev) });
+  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 });
+  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();
+    state.last = summarize({ baseline: pairs.length });
+    writeState(cacheDir, state);
+    return { ok: true, baseline: pairs.length, sent: 0 };
+  }
+  const cache = readCache(cacheDir);
+  const t = triage(pairs, { exclude, cache, state, onlyChanged: true });
+  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 });
+  evaluated.push(...r.done);
+  state.pending = t.ask.length - r.done.length - r.unreadable;           // pairs not recorded as seen: asked again next pass
+  // an excluded or withheld pair is recorded as seen, so it is not re-triaged on every check
+  for (const p of pairs) {
+    const hs = hashes(p);
+    if (state.pairs[p.id] === hs.h) continue;
+    if (settings.isExcluded(exclude, p.doc) || scanner.scan(p.a).length || scanner.scan(p.b).length) state.pairs[p.id] = hs.h;
+  }
+  let written = 0;
+  try { written = recordResults({ ledgerFile, pairs, evaluated, now }); }
+  catch (e) { return { ok: false, error: 'the Jev results could not be recorded — ' + String((e && e.message) || e).slice(0, 200) }; }
+  const suspected = evaluated.filter(([, v]) => v.p >= 0.5).length;
+  state.last = summarize({ sent: r.sent, cached: t.cached.length, withheld: t.withheld.slice(0, MAX_LISTED), withheld_count: t.withheld.length, excluded: t.excluded, failed: r.failed, unreadable: r.unreadable, suspected, error: r.lastError, paused: state.paused });
+  writeCache(cacheDir, cache); writeState(cacheDir, state);
+  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 };
+}
+
+/* ── 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 });
+  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 };
+}
+
+/** Send the backlog. Refuses unless `expectRequests` is what the plan counts now, so the PM never confirms one plan and runs another. */
+async function runBacklog({ root, cacheDir, ledgerFile, key, flags, exclude = [], expectRequests, ask = typesafe.ask, askOpts = {}, now = Date.now() }) {
+  const g = gates({ key: typesafe.validKey(key), consent: !!(flags && flags.consent), watch: true, jev: !!(flags && flags.jev) });
+  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 cache = readCache(cacheDir);
+  const t = triage(pairs, { exclude, cache, state, onlyChanged: false });
+  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.` };
+  }
+  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 });
+  evaluated.push(...r.done);
+  state.pending = t.ask.length - r.done.length - r.unreadable;
+  for (const p of pairs) { const hs = hashes(p); if (state.pairs[p.id] !== hs.h && (settings.isExcluded(exclude, p.doc) || scanner.scan(p.a).length || scanner.scan(p.b).length)) state.pairs[p.id] = hs.h; }
+  state.baselined = true; state.baselined_at = state.baselined_at || new Date(now).toISOString();
+  let written = 0;
+  try { written = recordResults({ ledgerFile, pairs, evaluated, now }); }
+  catch (e) { return { ok: false, error: 'the Jev results could not be recorded — ' + String((e && e.message) || e).slice(0, 200) }; }
+  const suspected = evaluated.filter(([, v]) => v.p >= 0.5).length;
+  state.last = summarize({ backlog: true, sent: r.sent, cached: t.cached.length, withheld: t.withheld.slice(0, MAX_LISTED), withheld_count: t.withheld.length, excluded: t.excluded, failed: r.failed, unreadable: r.unreadable, suspected, error: r.lastError, paused: state.paused });
+  writeCache(cacheDir, cache); writeState(cacheDir, state);
+  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 };

package/workspace/lib/kg-cli.js

@@ -0,0 +1,146 @@
+'use strict';
+/* kg-cli.js — `pmos kg …`: query the repository's knowledge graph from the terminal (knowledge-graph K1).
+ *
+ *   pmos kg find <term>                          cards whose id, title, headings or card match, with their token cost
+ *   pmos kg card <id>                            one card
+ *   pmos kg neighbors <id> [--type T] [--depth 1|2]
+ *   pmos kg section <path>#<heading>             the lines of one section
+ *   pmos kg section <path> <from>-<to>           a line range
+ *   pmos kg why <D-id>                           the decision's ADR view, its amendment-log line, and the files citing it
+ *   pmos kg stats                                counts, not claims
+ *   --max-tokens N                               stop at a card boundary and say how many results were not shown
+ *
+ * Reads the repository's tracked .md files straight from disk — no server, no model, no network. The graph is cached in
+ * the runtime state directory (never in the repository), keyed by git HEAD plus the modification times of uncommitted
+ * .md files, so a stale graph is rebuilt and a pull request never carries a graph diff. The only write is that cache.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const Kg = require('./kg');
+const { defaultRoot } = require('./state-root');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = ['find', 'card', 'neighbors', 'section', 'why', 'stats'];
+const RULES_FILE = path.join(__dirname, 'kg-dangling-rules.json');
+const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+
+function repoRoot(cwd) { return git(cwd, ['rev-parse', '--show-toplevel']).trim(); }
+
+function loadFiles(root) {
+  const out = []; const unreadable = [];
+  for (const rel of git(root, ['ls-files', '-z', '*.md']).split('\0').filter(Boolean)) {
+    try { out.push({ path: rel, text: fs.readFileSync(path.join(root, rel), 'utf8') }); }
+    catch (e) { unreadable.push({ path: rel, error: e.code || e.message }); }
+  }
+  return { files: out, unreadable };
+}
+
+function cacheKey(root) {
+  const head = git(root, ['rev-parse', 'HEAD']).trim();
+  const dirty = git(root, ['status', '--porcelain', '-z', '--untracked-files=no']).split('\0').filter(Boolean)
+    .map((l) => l.slice(3)).filter((p) => /\.md$/.test(p)).sort()
+    .map((p) => { try { return p + ':' + fs.statSync(path.join(root, p)).mtimeMs; } catch { return p + ':gone'; } });
+  return crypto.createHash('sha1').update(head + '\n' + dirty.join('\n')).digest('hex');
+}
+
+function graphFor(root, { stateDir = defaultRoot() } = {}) {
+  const dir = path.join(stateDir, 'kg');
+  const file = path.join(dir, crypto.createHash('sha1').update(root).digest('hex').slice(0, 12) + '.json');
+  const key = cacheKey(root);
+  try { const c = JSON.parse(fs.readFileSync(file, 'utf8')); if (c.key === key) return { graph: c.graph, unreadable: c.unreadable, cached: true }; } catch { /* rebuild */ }
+  const { files, unreadable } = loadFiles(root);
+  const graph = Kg.build(files);
+  try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(file, JSON.stringify({ key, graph, unreadable })); } catch { /* the cache is an optimisation, never required */ }
+  return { graph, unreadable, cached: false };
+}
+
+function run(argv, { say, cwd = process.cwd(), stateDir } = {}) {
+  const [group, verb, ...rest] = argv;
+  const { pos, flags } = parseArgs(rest);
+  const fail = (m) => { say('✗ ' + m); return 1; };
+  if (group !== 'kg' || !verb || flags.help || verb === 'help') { say(`usage: pmos kg <${COMMANDS.join('|')}> …  [--max-tokens N]`); return verb ? 0 : 1; }
+  if (!COMMANDS.includes(verb)) return fail(`unknown command "${verb}" — use ${COMMANDS.join(', ')}`);
+  let root;
+  try { root = repoRoot(cwd); } catch { return fail('this is not a git repository, so there are no tracked files to read'); }
+  const { graph, unreadable, cached } = graphFor(root, { stateDir });
+  const budget = flags['max-tokens'] === undefined ? Infinity : Number(flags['max-tokens']);
+  if (!(budget > 0)) return fail('--max-tokens takes a positive number');
+  for (const u of unreadable || []) say(`not read — ${u.path}: ${u.error}`);
+
+  /* print blocks until the budget is spent, stopping at a block boundary; say how many were not shown */
+  const emit = (blocks) => {
+    let used = 0; let shown = 0;
+    for (const b of blocks) {
+      const cost = Kg.estTokens(b);
+      if (shown && used + cost > budget) break;
+      say(b); used += cost; shown++;
+    }
+    if (shown < blocks.length) say(`… ${blocks.length - shown} more result(s) not shown (--max-tokens ${budget}). ~${used} tokens printed.`);
+    else if (budget !== Infinity) say(`~${used} tokens printed.`);
+  };
+
+  if (verb === 'find') {
+    if (!pos[0]) return fail('find needs a term');
+    const hits = Kg.find(graph, pos.join(' '), { limit: 50 });
+    if (!hits.length) { say(`nothing matches "${pos.join(' ')}"`); return 0; }
+    emit(hits.map((h) => `${Kg.cardText(h.node)}\n    matched: ${h.where.join(', ')} · linked from ${h.indegree} file(s)`));
+    return 0;
+  }
+  if (verb === 'card') {
+    const n = Kg.nodeById(graph, pos[0]);
+    if (!n) return fail(`no file "${pos[0] || ''}" in the graph`);
+    say(Kg.cardText(n));
+    for (const h of n.headings) say(`${'  '.repeat(h.level - 1)}${h.text}  (lines ${h.start}-${h.end})`);
+    return 0;
+  }
+  if (verb === 'neighbors') {
+    const depth = flags.depth === undefined ? 1 : Number(flags.depth);
+    if (![1, 2].includes(depth)) return fail('--depth takes 1 or 2');
+    const rows = Kg.neighbors(graph, pos[0], { type: flags.type || null, depth });
+    if (!rows) return fail(`no file "${pos[0] || ''}" in the graph`);
+    if (!rows.length) { say('no neighbours' + (flags.type ? ` of type ${flags.type}` : '')); return 0; }
+    emit(rows.map((r) => `${r.direction === 'out' ? '→' : '←'} ${r.via} (${r.basis}${r.depth > 1 ? ', depth ' + r.depth : ''})  ${Kg.cardText(Kg.nodeById(graph, r.id))}`));
+    return 0;
+  }
+  if (verb === 'section') {
+    let id = pos[0] || ''; let spec = pos[1] || '';
+    const hash = id.indexOf('#');
+    if (hash > 0) { spec = id.slice(hash); id = id.slice(0, hash); }
+    const n = Kg.nodeById(graph, id);
+    if (!n) return fail(`no file "${id}" in the graph`);
+    if (!spec) return fail('section needs #heading or from-to');
+    const s = Kg.section(n, fs.readFileSync(path.join(root, id), 'utf8'), spec);
+    if (!s) return fail(`no section "${spec}" in ${id} — run: pmos kg card ${id}`);
+    say(`${id} lines ${s.from}-${s.to} (~${Kg.estTokens(s.text)} tokens of ${n.tokens_est})`);
+    say(s.text);
+    return 0;
+  }
+  if (verb === 'why') {
+    const w = Kg.why(graph, pos[0]);
+    if (!w) return fail(`no decision "${pos[0] || ''}" — the ADR views are okf/products/pmos/adr/dNN-*.md`);
+    say(Kg.cardText(w.adr));
+    say(w.amendmentLog ? `amendment log: ${w.amendmentLog.path} line ${w.amendmentLog.line}` : 'amendment log: no "Added **D…**" line found');
+    const blocks = [];
+    for (const [kind, rows] of Object.entries(w.citedBy).sort()) blocks.push(`${kind} (${rows.length}):\n` + rows.map((r) => `  ${r.id}  [${r.via.join('+')}, ${r.basis}]`).join('\n'));
+    emit(blocks.length ? blocks : ['no file cites this decision']);
+    return 0;
+  }
+  if (verb === 'stats') {
+    const rules = JSON.parse(fs.readFileSync(RULES_FILE, 'utf8'));
+    const s = Kg.stats(graph, rules);
+    say(`${s.nodes} files, ${s.edges} edges (${s.byBasis.stated} stated, ${s.byBasis.mention} mention) — graph ${cached ? 'from cache' : 'rebuilt'}`);
+    say('edges by type: ' + Object.entries(s.byType).sort().map(([k, v]) => `${k} ${v}`).join(', '));
+    say(`cards: ${s.cardsWritten} written (description), ${s.cardsDerived} derived from the first paragraph, ${s.noCard} none`);
+    say(`${s.noType} file(s) have no type · ${s.noIncoming} have no incoming link (index and log files excluded)`);
+    say(`dangling links: ${s.dangling} — ${s.danglingHistory} history by design (${path.relative(root, RULES_FILE) || RULES_FILE}), ${s.danglingNeedsDecision} need a decision`);
+    for (const d of s.needsDecision) say(`  ${d.from} → ${d.to}`);
+    say('Only relations written in the files are found. Token counts are characters ÷ 4, an estimate.');
+    return 0;
+  }
+  return 0;
+}
+
+module.exports = { run, graphFor, loadFiles, cacheKey, COMMANDS };

package/workspace/lib/kg-dangling-rules.json

@@ -0,0 +1,6 @@
+[
+  { "from": "^okf/log\\.md$", "why": "the OKF log records references to documents that were removed on purpose" },
+  { "from": "^okf/products/pmos/", "to": "(mcp-tools|data-model|references/metrics/v_)", "why": "D66 deleted the hosted-backend reference documents; the text that cites them is history" },
+  { "from": "/blind-plants/", "why": "a blind-plant specimen is planted with broken references on purpose" },
+  { "to": "^/planning/prd/x\\.md$", "why": "an example path in an explainer, not a reference" }
+]