docgov-cli 0.2.0

package/core/onboard.js

@@ -0,0 +1,271 @@
+import path from 'node:path';
+import { classify, destinationFor } from './classify.js';
+import { TYPES, AUTHORITY, typeDef } from './taxonomy.js';
+import { similarPairs } from './similarity.js';
+import { coverageGaps } from './inventory.js';
+import { assess, readmeOverreach, splitCandidates } from './size.js';
+import { brokenLinks } from './links.js';
+import { primaryAuthor, isRepo, isClean, lastCommitDate } from './git.js';
+import { locationFor } from './config.js';
+import { matchAny, table, plural } from './util.js';
+
+/**
+ * Existing-project review (PRD §15, §44).
+ *
+ * The hard rule: this produces a plan and changes nothing. The plan is a file a
+ * human reads and edits; `docgov fix` executes exactly what the plan says.
+ * Separating proposal from execution is what makes the "without losing
+ * information" promise checkable rather than aspirational.
+ */
+
+export const PLAN_PATH = '.docgov/fix-plan.md';
+export const PLAN_DATA_PATH = '.docgov/fix-plan.json';
+
+/**
+ * @param {{root:string, cfg:object, docs:any[], inv:object, graph:any, registry:object}} ctx
+ */
+export function plan({ root, cfg, docs, inv, graph, registry }) {
+  const actions = [];
+  const classifications = [];
+  const gitAvailable = isRepo(root);
+
+  for (const d of docs) {
+    const c = classify(d);
+    const owner = d.owner || (gitAvailable ? (primaryAuthor(root, d.path)?.name ?? null) : null);
+    const lastChanged = gitAvailable ? lastCommitDate(root, d.path) : null;
+    classifications.push({
+      path: d.path, current: d.type, proposed: c.type, confidence: c.confidence,
+      needsReview: c.needsReview, signals: c.signals.slice(0, 3), candidates: c.candidates,
+      owner, lastChanged, lines: d.lines, registered: d.registered,
+    });
+
+    const archived = matchAny(d.path, ['docs/99-archive/**', 'docs/archive/**']);
+    const target = archived ? d.path : destinationFor(cfg, c.type, d.path);
+
+    if (c.type === 'unknown') {
+      actions.push({ kind: 'CLASSIFY', path: d.path, reason: 'no classification signal matched',
+        risk: 'low', requiresJudgement: true });
+    } else if (target !== d.path) {
+      actions.push({ kind: 'MOVE', path: d.path, to: target, type: c.type,
+        reason: `a ${typeDef(c.type).label} belongs in ${locationFor(cfg, c.type)}`,
+        risk: c.needsReview ? 'medium' : 'low', requiresJudgement: c.needsReview });
+    }
+    if (!d.registered) {
+      actions.push({ kind: 'ANNOTATE', path: d.path, to: target, type: c.type,
+        reason: 'no docgov frontmatter; add id, type, authority, visibility',
+        risk: 'low', requiresJudgement: false });
+    }
+
+    const size = assess(cfg, d);
+    if (size.recommendSplit) {
+      actions.push({ kind: 'SPLIT', path: d.path, type: c.type, risk: 'high', requiresJudgement: true,
+        reason: `${d.lines} lines across ${size.independentConcepts} independently addressable concepts`,
+        into: size.candidates.map((s) => ({ title: s.title, lines: s.lines,
+          to: path.posix.join(stripFile(target), s.suggested) })) });
+    }
+    for (const r of readmeOverreach(cfg, d)) {
+      actions.push({ kind: 'EXTRACT', path: d.path, section: r.section, lines: r.lines,
+        to: r.moveTo ? locationFor(cfg, r.moveTo) : null, type: r.moveTo,
+        reason: `README section "${r.section}" is ${r.lines} lines; a README links depth, it does not contain it`,
+        risk: 'medium', requiresJudgement: true });
+    }
+    if (d.status === 'deprecated' || d.status === 'superseded' || /^(old|deprecated|legacy)[-_/]/i.test(d.path)) {
+      if (!archived) actions.push({ kind: 'ARCHIVE', path: d.path,
+        to: `${cfg.project.layout === 'full' ? 'docs/99-archive' : 'docs/archive'}/${path.basename(d.path)}`,
+        reason: `status is ${d.status}`, risk: 'low', requiresJudgement: false });
+    }
+  }
+
+  const duplicates = similarPairs(docs, { threshold: 0.5, limit: 25 });
+  for (const p of duplicates) {
+    if (p.score < 0.72) continue;
+    actions.push({ kind: 'MERGE', path: p.a, other: p.b, score: p.score, risk: 'high', requiresJudgement: true,
+      reason: `${Math.round(p.score * 100)}% textual overlap${p.reasons.length ? ` (${p.reasons.join(', ')})` : ''}` });
+  }
+
+  const gaps = coverageGaps(inv);
+  for (const g of gaps) {
+    actions.push({ kind: 'CREATE', type: g.type, to: locationFor(cfg, g.type), risk: 'low',
+      requiresJudgement: false,
+      reason: g.because === 'baseline'
+        ? 'every repository should have this'
+        : `${g.because} detected (${g.evidence}) but no ${g.label} exists` });
+  }
+
+  const broken = brokenLinks(docs, root, new Set(inv.all));
+
+  const contradictionCandidates = duplicates
+    .filter((p) => p.score >= 0.5)
+    .map((p) => {
+      const a = docs.find((d) => d.path === p.a), b = docs.find((d) => d.path === p.b);
+      const ra = AUTHORITY[a?.authority]?.rank ?? 9, rb = AUTHORITY[b?.authority]?.rank ?? 9;
+      return { ...p, authorityA: a?.authority, authorityB: b?.authority,
+        sameAuthority: ra === rb,
+        note: ra === rb ? 'equal authority — a contradiction here has no tie-break'
+          : `${ra < rb ? p.a : p.b} wins a contradiction` };
+    });
+
+  const summary = {
+    documents: docs.length,
+    unclassified: classifications.filter((c) => c.proposed === 'unknown').length,
+    lowConfidence: classifications.filter((c) => c.needsReview && c.proposed !== 'unknown').length,
+    moves: actions.filter((a) => a.kind === 'MOVE').length,
+    annotations: actions.filter((a) => a.kind === 'ANNOTATE').length,
+    splits: actions.filter((a) => a.kind === 'SPLIT').length,
+    extracts: actions.filter((a) => a.kind === 'EXTRACT').length,
+    merges: actions.filter((a) => a.kind === 'MERGE').length,
+    archives: actions.filter((a) => a.kind === 'ARCHIVE').length,
+    creates: actions.filter((a) => a.kind === 'CREATE').length,
+    brokenLinks: broken.length,
+    duplicateCandidates: duplicates.length,
+    needJudgement: actions.filter((a) => a.requiresJudgement).length,
+    highRisk: actions.filter((a) => a.risk === 'high').length,
+  };
+
+  return {
+    version: 1, generated: new Date().toISOString(),
+    layout: cfg.project.layout, mode: cfg.project.mode,
+    git: { repo: gitAvailable, clean: gitAvailable ? isClean(root) : false },
+    summary, classifications, actions, duplicates, contradictionCandidates, gaps, brokenLinks: broken,
+    stack: inv.stack.map((s) => ({ id: s.id, evidence: s.evidence[0], count: s.count })),
+    contracts: inv.contracts,
+    agentInstructions: inv.agentInstructions,
+  };
+}
+
+function stripFile(p) { return p.replace(/\.mdx?$/, ''); }
+
+/** The human-readable plan. This is the artifact the user approves. */
+export function render(planData, cfg) {
+  const L = [];
+  const s = planData.summary;
+  L.push('# DocGov fix plan');
+  L.push('');
+  L.push(`Generated ${planData.generated.slice(0, 19).replace('T', ' ')} · layout \`${planData.layout}\` · mode \`${planData.mode}\``);
+  L.push('');
+  L.push('**Nothing has changed yet.** This plan is a proposal. Edit it freely — delete any action you');
+  L.push('disagree with — then run `docgov fix` to execute exactly what remains.');
+  L.push('');
+
+  if (!planData.git.repo) {
+    L.push('> ⚠ This is not a git repository. `docgov fix` refuses to run without git, because the');
+    L.push('> only honest way to promise "without losing information" is to make every change revertible.');
+    L.push('');
+  } else if (!planData.git.clean) {
+    L.push('> ⚠ The working tree is dirty. Commit or stash before migrating.');
+    L.push('');
+  }
+
+  L.push('## Current state');
+  L.push('');
+  L.push(`- ${plural(s.documents, 'document')}, ${plural(planData.contracts.length, 'machine contract')}`);
+  L.push(`- ${plural(s.unclassified, 'document')} could not be classified, ${s.lowConfidence} classified with low confidence`);
+  L.push(`- ${plural(s.brokenLinks, 'broken internal link')}, ${plural(s.duplicateCandidates, 'suspected duplicate pair')}`);
+  if (planData.stack.length) L.push(`- stack detected: ${planData.stack.map((x) => x.id).join(', ')}`);
+  if (planData.agentInstructions.length) L.push(`- existing agent instructions: ${planData.agentInstructions.join(', ')}`);
+  L.push('');
+
+  L.push('## Proposed state');
+  L.push('');
+  L.push('```');
+  L.push(tree(planData, cfg));
+  L.push('```');
+  L.push('');
+
+  const groups = [
+    ['MOVE', 'Moves', 'Relocated to the canonical position for their class. Links are repaired automatically.'],
+    ['ANNOTATE', 'Annotations', 'Frontmatter added so the document becomes addressable by id.'],
+    ['SPLIT', 'Splits', 'Each of these holds several independently addressable concepts. Needs your judgement.'],
+    ['EXTRACT', 'Extractions', 'README sections that have outgrown a README.'],
+    ['MERGE', 'Merges', 'Suspected duplicates. DocGov will not merge prose on its own — these are for you.'],
+    ['ARCHIVE', 'Archives', 'Superseded or deprecated documents moved to the archive namespace.'],
+    ['CREATE', 'Missing documents', 'The repository implies these should exist.'],
+    ['CLASSIFY', 'Needs classification', 'No signal matched. Tell DocGov what these are.'],
+  ];
+  for (const [kind, title, blurb] of groups) {
+    const items = planData.actions.filter((a) => a.kind === kind);
+    if (!items.length) continue;
+    L.push(`## ${title} (${items.length})`);
+    L.push('');
+    L.push(blurb);
+    L.push('');
+    for (const a of items) {
+      if (kind === 'MOVE' || kind === 'ARCHIVE') L.push(`- \`${a.path}\` → \`${a.to}\`  \n  ${a.reason}`);
+      else if (kind === 'SPLIT') {
+        L.push(`- \`${a.path}\` — ${a.reason}`);
+        for (const part of a.into) L.push(`    - \`${part.to}\` ← "${part.title}" (${part.lines} lines)`);
+        L.push('    - parent becomes an index that links the parts');
+      } else if (kind === 'EXTRACT') L.push(`- \`${a.path}\` § "${a.section}" (${a.lines} lines) → \`${a.to || '(choose a destination)'}\``);
+      else if (kind === 'MERGE') L.push(`- \`${a.path}\` + \`${a.other}\` — ${a.reason}`);
+      else if (kind === 'CREATE') L.push(`- \`${a.to}\` (${a.type}) — ${a.reason}`);
+      else L.push(`- \`${a.path}\` — ${a.reason}`);
+    }
+    L.push('');
+  }
+
+  if (planData.contradictionCandidates.length) {
+    L.push('## Suspected contradictions');
+    L.push('');
+    L.push('Textual overlap narrows the candidates; only a reviewer can confirm a real contradiction.');
+    L.push('Run `/docgov:inspect --contradictions` to have the architect agent adjudicate these pairs.');
+    L.push('');
+    for (const c of planData.contradictionCandidates.slice(0, 12)) {
+      L.push(`- \`${c.a}\` (${c.authorityA}) vs \`${c.b}\` (${c.authorityB}) — ${Math.round(c.score * 100)}% overlap. ${c.note}`);
+    }
+    L.push('');
+  }
+
+  if (planData.brokenLinks.length) {
+    L.push('## Broken internal links');
+    L.push('');
+    for (const b of planData.brokenLinks.slice(0, 25)) L.push(`- \`${b.path}\` → \`${b.target}\``);
+    if (planData.brokenLinks.length > 25) L.push(`- … and ${planData.brokenLinks.length - 25} more`);
+    L.push('');
+  }
+
+  L.push('## Risk');
+  L.push('');
+  L.push(table([
+    { Risk: 'low', Actions: planData.actions.filter((a) => a.risk === 'low').length, Meaning: 'mechanical, fully reversible' },
+    { Risk: 'medium', Actions: planData.actions.filter((a) => a.risk === 'medium').length, Meaning: 'correct destination is a judgement call' },
+    { Risk: 'high', Actions: planData.actions.filter((a) => a.risk === 'high').length, Meaning: 'content must be rewritten; never automatic' },
+  ], ['Risk', 'Actions', 'Meaning']));
+  L.push('');
+  L.push(`${s.needJudgement} of ${planData.actions.length} actions need a human or an agent to decide something.`);
+  L.push('');
+  L.push('## Execute');
+  L.push('');
+  L.push('```bash');
+  L.push('docgov fix --dry-run   # show every file operation, touch nothing');
+  L.push('docgov fix             # on a new branch, mechanical actions only');
+  L.push('docgov fix --include split,merge,extract   # also the judgement calls, one at a time');
+  L.push('```');
+  L.push('');
+  L.push('`migrate` runs MOVE, ANNOTATE and ARCHIVE automatically and repairs every internal link.');
+  L.push('SPLIT, MERGE and EXTRACT are left to `/docgov:tag`, which uses an agent to rewrite prose.');
+  return L.join('\n');
+}
+
+function tree(planData, cfg) {
+  const dirs = new Map();
+  for (const c of planData.classifications) {
+    const a = planData.actions.find((x) => x.kind === 'MOVE' && x.path === c.path);
+    const final = a ? a.to : c.path;
+    const dir = final.includes('/') ? final.slice(0, final.lastIndexOf('/')) : '.';
+    if (!dirs.has(dir)) dirs.set(dir, []);
+    dirs.get(dir).push({ file: final.split('/').pop(), from: a ? c.path : null });
+  }
+  for (const a of planData.actions.filter((x) => x.kind === 'CREATE')) {
+    const dir = a.to.replace(/\/$/, '');
+    if (!dirs.has(dir)) dirs.set(dir, []);
+    dirs.get(dir).push({ file: '(to create)', from: null, create: true });
+  }
+  const out = [];
+  for (const dir of [...dirs.keys()].sort()) {
+    out.push(`${dir}/`);
+    for (const f of dirs.get(dir).sort((x, y) => x.file.localeCompare(y.file))) {
+      out.push(`  ${f.file}${f.from ? `   ← ${f.from}` : ''}${f.create ? '   (new)' : ''}`);
+    }
+  }
+  return out.join('\n');
+}

package/core/paths.js

@@ -0,0 +1,53 @@
+/**
+ * Path predicates, in one place because drift and impact were each carrying their own
+ * copy and they drifted apart — which is how `bin/docgov` became invisible to the drift
+ * engine that governs it.
+ *
+ * The important distinction here:
+ *
+ *   `isMappable` gates a **graph lookup**. The question is "does some document claim this
+ *   path?", and the graph is the authority on that, not a file-extension list. Filtering by
+ *   extension first silently discarded every extensionless executable, shell script,
+ *   Dockerfile, Makefile and config file a document had explicitly mapped.
+ *
+ *   `CODE_RE` gates a **heuristic** — "did behaviour probably change?" — where a list of
+ *   known source extensions is exactly the right tool and a false negative costs nothing.
+ */
+
+export const MD_RE = /\.mdx?$/i;
+
+export const CONTRACT_RE =
+  /\.(proto|graphql|gql)$|openapi.*\.(ya?ml|json)$|schema\.prisma$|(^|\/)schemas?\/.*\.json$/;
+
+export const TEST_RE = /(^|\/)(test|tests|spec|__tests__)\/|\.(test|spec)\./;
+
+/** Known source extensions, plus scripts and infrastructure-as-code. Heuristic use only. */
+export const CODE_RE = new RegExp(
+  '\\.(' + [
+    'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'py', 'go', 'rs', 'rb', 'java', 'kt', 'kts',
+    'swift', 'cs', 'php', 'ex', 'exs', 'erl', 'scala', 'clj', 'dart', 'lua', 'pl', 'r',
+    'c', 'cc', 'cpp', 'h', 'hpp', 'm', 'mm', 'sql', 'vue', 'svelte', 'astro',
+    'sh', 'bash', 'zsh', 'fish', 'ps1', 'bat', 'cmd', 'tf', 'hcl',
+  ].join('|') + ')$',
+);
+
+/** Files that are conventionally executable or build logic despite having no extension. */
+const EXTENSIONLESS_CODE =
+  /(^|\/)(bin|sbin|scripts?|hooks|cmd)\/[^/.]+$|(^|\/)(Dockerfile|Makefile|Rakefile|Gemfile|Brewfile|Procfile|Justfile|CMakeLists\.txt)$/i;
+
+/** Does this path look like code for the purposes of the behaviour heuristic? */
+export function isCode(p) {
+  return CODE_RE.test(p) || EXTENSIONLESS_CODE.test(p);
+}
+
+/**
+ * Can this path be mapped to a document by the graph?
+ *
+ * Deliberately broad. If a document declares `documents: ["assets/schema.png"]` then that
+ * image is something the document claims, and a change to it is something a reviewer should
+ * see. Only markdown (which is the documentation, not the thing documented) and DocGov's own
+ * state are excluded.
+ */
+export function isMappable(p) {
+  return !MD_RE.test(p) && !p.startsWith('.docgov/');
+}

package/core/publish.js

@@ -0,0 +1,92 @@
+import { VISIBILITY } from './taxonomy.js';
+import { matchAny } from './util.js';
+
+/**
+ * Publishing analysis (PRD §29).
+ *
+ * DocGov never copies an internal document outward. It identifies what is
+ * publishable, flags what leaks, and hands the rewrite to a human or an agent
+ * under the external lens. The boundary is deliberate, not incidental (PRD §43).
+ */
+
+/** Patterns that should never cross the internal/external boundary. */
+const LEAK_PATTERNS = [
+  { id: 'internal-host', re: /\b(?:[a-z0-9-]+\.)+(?:internal|local|corp|intranet|lan)\b/gi, what: 'internal hostname' },
+  { id: 'private-ip', re: /\b(?:10\.\d{1,3}|192\.168|172\.(?:1[6-9]|2\d|3[01]))\.\d{1,3}(?:\.\d{1,3})?\b/g, what: 'private IP address' },
+  { id: 'aws-key', re: /\bAKIA[0-9A-Z]{16}\b/g, what: 'AWS access key id' },
+  { id: 'bearer', re: /\b(?:bearer|token|api[_-]?key|secret)\s*[:=]\s*['"]?[A-Za-z0-9_\-]{16,}/gi, what: 'credential-shaped string' },
+  { id: 'private-key', re: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g, what: 'private key block' },
+  { id: 'jira', re: /\b(?:[A-Z]{2,10}-\d{1,6})\b/g, what: 'internal ticket reference', soft: true },
+  { id: 'internal-path', re: /\/(?:Users|home)\/[a-z0-9._-]+\//gi, what: 'developer machine path' },
+  { id: 'employee-email', re: /\b[a-z0-9._%+-]+@(?!example\.)(?:[a-z0-9-]+\.)+[a-z]{2,}\b/gi, what: 'email address', soft: true },
+  { id: 'internal-jargon', re: /\b(?:TODO|FIXME|HACK|XXX|WIP)\b/g, what: 'work-in-progress marker' },
+  { id: 'threat-detail', re: /\b(?:exploit|attack vector|unmitigated|known vulnerability|CVE-\d{4}-\d+)\b/gi, what: 'unmitigated-risk language', soft: true },
+];
+
+/**
+ * @param {{cfg:object, docs:any[], target?:string}} args
+ */
+export function analyze({ cfg, docs, target = 'docs/11-external' }) {
+  const publishable = [], blocked = [], rewrite = [];
+
+  for (const d of docs) {
+    const isPublic = d.visibility === 'public' || d.visibility === 'generated-public';
+    const leaks = scan(d);
+    const hard = leaks.filter((l) => !l.soft);
+
+    if (!isPublic) {
+      if (d.visibility === 'confidential') {
+        blocked.push({ path: d.path, reason: 'confidential documents are never publishable', leaks: leaks.length });
+      } else {
+        rewrite.push({
+          path: d.path, currentVisibility: d.visibility, leaks,
+          reason: 'internal document — publishing requires an external-lens rewrite, not a copy',
+          suggestedTarget: `${target}/${d.path.split('/').pop()}`,
+        });
+      }
+      continue;
+    }
+    if (hard.length) blocked.push({ path: d.path, reason: `${hard.length} sensitive pattern(s) detected`, leaks: hard });
+    else publishable.push({ path: d.path, visibility: d.visibility, softFlags: leaks.length });
+  }
+
+  return { publishable, blocked, rewrite, target,
+    gate: 'Nothing is published by this command. Review, then publish through your own pipeline.' };
+}
+
+export function scan(doc) {
+  const out = [];
+  const body = doc.body ?? String(doc);
+  for (const p of LEAK_PATTERNS) {
+    const matches = [...body.matchAll(p.re)].slice(0, 3);
+    for (const m of matches) {
+      out.push({ id: p.id, what: p.what, sample: redact(m[0]), soft: Boolean(p.soft),
+        line: body.slice(0, m.index).split('\n').length });
+    }
+  }
+  return out;
+}
+
+function redact(s) {
+  if (s.length <= 8) return s;
+  return `${s.slice(0, 4)}…${s.slice(-3)}`;
+}
+
+/** The external lens brief handed to whichever agent does the rewrite. */
+export function rewriteBrief(entry) {
+  return [
+    `Rewrite ${entry.path} for an external audience. This is a new artifact, not a copy.`,
+    '',
+    'Remove or generalize:',
+    ...entry.leaks.map((l) => `  - line ${l.line}: ${l.what} (${l.sample})`),
+    '',
+    'External lens requirements:',
+    '  - no internal jargon, team names, or ticket references',
+    '  - no unmitigated risks, internal hostnames, or infrastructure topology',
+    '  - task-oriented: what the reader wants to do, not how the system is built',
+    '  - state prerequisites explicitly',
+    '  - every example runnable as written',
+    '',
+    'A human must approve the result before it is published.',
+  ].join('\n');
+}

package/core/registry.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import * as yaml from './yaml.js';
+import { read, write, exists, DocGovError } from './util.js';
+
+export const REGISTRY_PATH = '.docgov/registry.yaml';
+
+/**
+ * The registry is the authoritative id -> path map. It is the reason
+ * "is this id a duplicate?" is answered by software and not by a model (PRD §47).
+ */
+export function load(root) {
+  const file = path.join(root, REGISTRY_PATH);
+  if (!exists(file)) return { version: 1, documents: {} };
+  let r;
+  try { r = yaml.parse(read(file)) || {}; }
+  catch (e) { throw new DocGovError(`${REGISTRY_PATH} is not valid: ${e.message}`); }
+  r.documents ||= {};
+  return r;
+}
+
+export function save(root, registry) {
+  const sorted = {};
+  for (const k of Object.keys(registry.documents).sort()) sorted[k] = registry.documents[k];
+  return write(path.join(root, REGISTRY_PATH), yaml.stringify({ version: registry.version || 1, documents: sorted }));
+}
+
+/**
+ * Rebuild from documents on disk. Reports id collisions rather than silently
+ * picking a winner.
+ * @param {import('./document.js').Document[]} docs
+ */
+export function build(docs, contracts = []) {
+  const documents = {};
+  const collisions = [];
+  for (const d of docs) {
+    const id = d.id;
+    if (documents[id]) collisions.push({ id, paths: [documents[id].path, d.path] });
+    else documents[id] = d.toRegistryEntry();
+  }
+  for (const c of contracts) {
+    const id = contractId(c.path);
+    if (documents[id]) collisions.push({ id, paths: [documents[id].path, c.path] });
+    else documents[id] = { path: c.path, type: `contract.${c.kind === 'openapi' ? 'openapi' : 'schema'}`,
+      authority: 'machine-contract', visibility: 'internal', machine: true };
+  }
+  return { registry: { version: 1, documents }, collisions };
+}
+
+export function contractId(p) {
+  return p.replace(/\.[^.]+$/, '').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').toLowerCase();
+}
+
+export function pathOf(registry, id) { return registry.documents[id]?.path || null; }
+
+export function idAt(registry, relPath) {
+  for (const [id, e] of Object.entries(registry.documents)) if (e.path === relPath) return id;
+  return null;
+}
+
+/** Ids referenced by relationships that do not exist in the registry (PRD §21). */
+export function danglingReferences(registry) {
+  const out = [];
+  for (const [id, e] of Object.entries(registry.documents)) {
+    for (const [rel, targets] of Object.entries(e.relationships || {})) {
+      for (const t of targets) {
+        if (!registry.documents[t]) out.push({ id, relationship: rel, target: t, path: e.path });
+      }
+    }
+  }
+  return out;
+}

package/core/similarity.js

@@ -0,0 +1,89 @@
+/**
+ * tf-idf cosine similarity over document bodies.
+ *
+ * This exists so duplicate and contradiction detection can narrow ~5,000 candidate
+ * pairs down to ~20 before any model is asked to look (FEASIBILITY §3.5). Local,
+ * deterministic, no embedding service — which keeps PRD §43's local-first promise.
+ */
+
+const STOP = new Set(('the and for that this with are was from have has not you your our they them their can will'
+  + ' should would could but all any its where when what which who how why into than then also more most other'
+  + ' such only own same too very just about over under via per use used using based each one two new'
+  + ' docs doc documentation document section see also note example examples').split(/\s+/));
+
+/** @param {string[]} tokens */
+function termFreq(tokens) {
+  const tf = new Map();
+  let n = 0;
+  for (const t of tokens) {
+    if (STOP.has(t) || t.length < 4) continue;
+    tf.set(t, (tf.get(t) || 0) + 1);
+    n++;
+  }
+  return { tf, n };
+}
+
+/**
+ * @param {{id:string, tokens:()=>string[]}[]} docs
+ * @returns {Map<string, Map<string, number>>} id -> term -> tf-idf weight (L2 normalized)
+ */
+export function vectorize(docs) {
+  const freqs = docs.map((d) => ({ id: d.id, ...termFreq(d.tokens()) }));
+  const df = new Map();
+  for (const f of freqs) for (const t of f.tf.keys()) df.set(t, (df.get(t) || 0) + 1);
+  const N = Math.max(1, docs.length);
+  const out = new Map();
+  for (const f of freqs) {
+    const vec = new Map();
+    let norm = 0;
+    for (const [t, c] of f.tf) {
+      const idf = Math.log(1 + N / (df.get(t) || 1));
+      const w = (c / Math.max(1, f.n)) * idf;
+      vec.set(t, w);
+      norm += w * w;
+    }
+    norm = Math.sqrt(norm) || 1;
+    for (const [t, w] of vec) vec.set(t, w / norm);
+    out.set(f.id, vec);
+  }
+  return out;
+}
+
+export function cosine(a, b) {
+  if (!a || !b) return 0;
+  const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+  let s = 0;
+  for (const [t, w] of small) { const o = large.get(t); if (o) s += w * o; }
+  return s;
+}
+
+/**
+ * Candidate near-duplicate pairs, most similar first.
+ * @param {{id:string,path:string,type:string,domain:string|null,tokens:()=>string[]}[]} docs
+ * @param {{threshold?:number, limit?:number}} [opts]
+ */
+export function similarPairs(docs, opts = {}) {
+  const { threshold = 0.45, limit = 40 } = opts;
+  const vecs = vectorize(docs);
+  const pairs = [];
+  for (let i = 0; i < docs.length; i++) {
+    for (let j = i + 1; j < docs.length; j++) {
+      const a = docs[i], b = docs[j];
+      const score = cosine(vecs.get(a.id), vecs.get(b.id));
+      if (score < threshold) continue;
+      const reasons = [];
+      if (a.type === b.type && a.type !== 'unknown') reasons.push('same document type');
+      if (a.domain && a.domain === b.domain) reasons.push('same domain');
+      pairs.push({ a: a.path, b: b.path, aId: a.id, bId: b.id, score: Math.round(score * 100) / 100, reasons });
+    }
+  }
+  return pairs.sort((x, y) => y.score - x.score).slice(0, limit);
+}
+
+/** Terms that carry a document's topic, for a human-readable "about" line. */
+export function topTerms(doc, allDocs, k = 8) {
+  const vecs = vectorize(allDocs);
+  const v = vecs.get(doc.id);
+  if (!v) return [];
+  return [...v.entries()].sort((a, b) => b[1] - a[1]).slice(0, k).map(([t]) => t);
+}

package/core/size.js

@@ -0,0 +1,87 @@
+import { limitFor } from './config.js';
+import { typeDef } from './taxonomy.js';
+
+/**
+ * Size discipline (PRD §13).
+ *
+ * Line count alone never triggers a split — it only decides whether a semantic
+ * reviewer is worth spending. The split *candidates* are computed structurally:
+ * a document whose H2 sections each carry enough substance to stand alone is a
+ * document of several documents.
+ */
+
+const SPLITTABLE_MIN_LINES = 40;
+
+export function assess(cfg, doc) {
+  const { soft, hard } = limitFor(cfg, doc.type);
+  const over = hard > 0 && doc.lines > hard;
+  const warn = soft > 0 && doc.lines > soft;
+  const candidates = splitCandidates(doc);
+  return {
+    path: doc.path, type: doc.type, lines: doc.lines, soft, hard,
+    level: over ? 'hard' : warn ? 'soft' : 'ok',
+    independentConcepts: candidates.length,
+    candidates,
+    // Structural evidence, not an opinion: several fat sections in one file.
+    recommendSplit: candidates.length >= 3 && (warn || over),
+  };
+}
+
+/** H2 sections substantial enough to become their own document. */
+export function splitCandidates(doc) {
+  return doc.sections
+    .filter((s) => s.lines >= SPLITTABLE_MIN_LINES)
+    .map((s) => ({ title: s.title, lines: s.lines, suggested: fileNameFor(s.title) }));
+}
+
+function fileNameFor(title) {
+  return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 48) + '.md';
+}
+
+/**
+ * README-specific extraction advice (PRD §28). A README section that has grown
+ * past `maxSection` lines belongs somewhere else with a summary left behind.
+ */
+export function readmeOverreach(cfg, doc, maxSection = 40) {
+  if (doc.type !== 'user.readme') return [];
+  const EXTRACT = {
+    architecture: 'architecture.overview', design: 'architecture.overview',
+    development: 'engineering.development', contributing: 'governance.contributing',
+    security: 'security.public-model', deployment: 'operations.deployment',
+    configuration: 'operations.configuration', api: 'user.reference',
+    troubleshooting: 'user.troubleshooting', faq: 'user.faq', testing: 'engineering.testing',
+    roadmap: 'product.roadmap', changelog: 'release.notes',
+  };
+  const out = [];
+  for (const s of doc.sections) {
+    if (s.lines <= maxSection) continue;
+    const key = Object.keys(EXTRACT).find((k) => s.title.toLowerCase().includes(k));
+    out.push({ section: s.title, lines: s.lines, moveTo: key ? EXTRACT[key] : null,
+      replaceWith: `${Math.min(12, Math.ceil(s.lines / 15))}-line summary plus a link` });
+  }
+  return out;
+}
+
+/** Progressive disclosure check (PRD §14): does a tree have an index document? */
+export function missingIndexes(docs) {
+  const dirs = new Map();
+  for (const d of docs) {
+    const dir = d.path.includes('/') ? d.path.slice(0, d.path.lastIndexOf('/')) : '';
+    if (!dir) continue;
+    if (!dirs.has(dir)) dirs.set(dir, []);
+    dirs.get(dir).push(d);
+  }
+  const out = [];
+  for (const [dir, group] of dirs) {
+    if (group.length < 3) continue;
+    const hasIndex = group.some((d) => /\/(README|index)\.mdx?$/i.test(d.path));
+    if (!hasIndex) out.push({ dir, documents: group.length, suggest: `${dir}/README.md`, type: 'docs.index' });
+  }
+  return out;
+}
+
+export function requiredSectionReport(doc) {
+  const def = typeDef(doc.type);
+  const missing = doc.missingSections();
+  return { path: doc.path, type: doc.type, required: (def.sections || []).length, missing };
+}