docgov-cli 0.2.0

package/bin/docgov.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0docgov" %*

package/core/check.js

@@ -0,0 +1,298 @@
+import path from 'node:path';
+import { blocks, limitFor, locationFor } from './config.js';
+import { TYPES, AUTHORITY, VISIBILITY, STATUS, typeDef } from './taxonomy.js';
+import { matchAny, matchGlob, EXIT } from './util.js';
+import { classify, destinationFor } from './classify.js';
+import { brokenLinks, brokenAnchors } from './links.js';
+import { assess, readmeOverreach, missingIndexes } from './size.js';
+import { danglingReferences } from './registry.js';
+import { similarPairs } from './similarity.js';
+import { parse as fmParse } from './frontmatter.js';
+
+/**
+ * The deterministic check engine (PRD §21).
+ *
+ * Every check here is decidable by software. Nothing in this file asks a model a
+ * question, which is exactly why it is allowed to fail CI. Subjective findings
+ * live in the agent layer and are advisory by construction.
+ */
+
+/** check id -> {severity, deterministic, blurb} */
+export const CHECKS = {
+  'invalid-yaml':        { severity: 'critical', blurb: 'frontmatter is not parseable' },
+  'missing-frontmatter': { severity: 'high',     blurb: 'no docgov frontmatter block' },
+  'missing-id':          { severity: 'high',     blurb: 'docgov.id is absent' },
+  'invalid-id':          { severity: 'high',     blurb: 'docgov.id does not match the pattern for its type' },
+  'duplicate-id':        { severity: 'critical', blurb: 'two documents claim the same docgov.id' },
+  'unknown-type':        { severity: 'high',     blurb: 'docgov.type is not a known document class' },
+  'unknown-reference':   { severity: 'high',     blurb: 'a relationship points at an id that does not exist' },
+  'invalid-relationship':{ severity: 'medium',   blurb: 'relationship name is not in the taxonomy' },
+  'broken-link':         { severity: 'high',     blurb: 'internal link target does not exist' },
+  'broken-anchor':       { severity: 'low',      blurb: 'in-page anchor has no matching heading' },
+  'wrong-location':      { severity: 'medium',   blurb: 'document is not in the canonical location for its type' },
+  'visibility-path':     { severity: 'critical', blurb: 'document visibility is forbidden in this path' },
+  'missing-visibility':  { severity: 'medium',   blurb: 'visibility is not declared' },
+  'invalid-visibility':  { severity: 'high',     blurb: 'visibility is not a known value' },
+  'invalid-status':      { severity: 'medium',   blurb: 'status is not a known value' },
+  'missing-sections':    { severity: 'medium',   blurb: 'required template sections are absent' },
+  'soft-limit':          { severity: 'low',      blurb: 'document exceeds its soft line limit' },
+  'hard-limit':          { severity: 'medium',   blurb: 'document exceeds its hard line limit' },
+  'generated-edit':      { severity: 'critical', blurb: 'a generated document was edited by hand' },
+  'frozen-edit':         { severity: 'high',     blurb: 'an archived document was edited' },
+  'missing-owner':       { severity: 'medium',   blurb: 'owner is required in this project mode' },
+  'authority-violation': { severity: 'critical', blurb: 'a lower-authority document claims authority over a higher one' },
+  'orphan':              { severity: 'low',      blurb: 'no inbound or outbound relationships' },
+  'unclassified':        { severity: 'medium',   blurb: 'document type could not be determined' },
+  'readme-overreach':    { severity: 'low',      blurb: 'a README section has grown into its own document' },
+  'missing-index':       { severity: 'low',      blurb: 'directory has several documents and no index' },
+  'duplicate-candidate': { severity: 'low',      blurb: 'two documents are textually very similar' },
+  'new-root-document':   { severity: 'medium',   blurb: 'a new top-level Markdown file was added outside the taxonomy' },
+  'expired-suppression': { severity: 'medium',   blurb: 'a suppression has expired and is no longer in effect' },
+};
+
+for (const r of Object.values(CHECKS)) r.deterministic = true;
+
+/**
+ * @param {{root:string, cfg:object, docs:any[], registry:object, graph:any,
+ *          inv:object, only?:string[]}} ctx
+ * @returns {{findings:object[], stats:object}}
+ */
+export function run({ root, cfg, docs, registry, graph, inv, only = null }) {
+  const findings = [];
+  const allFiles = new Set(inv.all);
+  const scope = only ? docs.filter((d) => only.includes(d.path)) : docs;
+  const add = (check, doc, message, extra = {}) => {
+    const meta = CHECKS[check] || { severity: 'medium', blurb: check };
+    findings.push({
+      check, severity: extra.severity || meta.severity, path: doc?.path ?? extra.path ?? '(repository)',
+      id: doc?.id ?? extra.id ?? null, message, deterministic: true,
+      blocking: blocks(cfg, check), fix: extra.fix || null, ...extra,
+    });
+  };
+
+  // ---- per-document checks
+  for (const d of scope) {
+    if (d.error) { add('invalid-yaml', d, d.error); continue; }
+
+    const inArchive = matchAny(d.path, ['docs/99-archive/**', 'docs/archive/**']);
+    const generated = d.isGenerated || matchAny(d.path, cfg.generated_paths || []);
+
+    if ((!d.hasFrontmatter || !d.frontmatter.docgov) && !d.externallyRegistered) {
+      add('missing-frontmatter', d, 'no `docgov:` frontmatter block',
+        { fix: `docgov tag --apply --path ${d.path}`
+          + ` — or, for a file GitHub renders, register it under documentation.registrations` });
+    } else {
+      if (!d.meta.id) add('missing-id', d, 'docgov.id is required');
+      if (d.meta.type && !TYPES[d.meta.type]) add('unknown-type', d, `unknown type "${d.meta.type}"`);
+      if (d.meta.visibility && !VISIBILITY.includes(d.meta.visibility))
+        add('invalid-visibility', d, `visibility "${d.meta.visibility}" is not one of ${VISIBILITY.join(', ')}`);
+      if (!d.meta.visibility) add('missing-visibility', d, `visibility not declared (defaulting to ${d.visibility})`);
+      if (d.meta.status && !STATUS.includes(d.meta.status))
+        add('invalid-status', d, `status "${d.meta.status}" is not one of ${STATUS.join(', ')}`);
+      const idPattern = typeDef(d.type).idPattern;
+      if (idPattern && d.meta.id && !new RegExp(idPattern).test(d.meta.id))
+        add('invalid-id', d, `id "${d.meta.id}" must match ${idPattern}`);
+      for (const rel of Object.keys(d.relationships)) {
+        if (!['depends_on', 'defines', 'implements', 'derived_from', 'supersedes', 'references',
+          'validated_by', 'generated_from', 'exposes', 'documents'].includes(rel))
+          add('invalid-relationship', d, `"${rel}" is not a relationship in the taxonomy`);
+      }
+      if (cfg.profile?.require_owner && !d.owner && !inArchive)
+        add('missing-owner', d, `project mode "${cfg.project.mode}" requires docgov.owner`);
+    }
+
+    if (d.type === 'unknown') {
+      const c = classify(d);
+      add('unclassified', d, c.type === 'unknown'
+        ? 'no classification signal matched'
+        : `type not declared; best guess is ${c.type} (${c.confidence}% confidence)`,
+        { suggestion: c.type === 'unknown' ? null : c.type, candidates: c.candidates });
+    }
+
+    // Location
+    const allowedAtRoot = !d.path.includes('/') && (cfg.governance.allowed_root_docs || []).includes(d.path);
+    if (d.type !== 'unknown' && !inArchive && !typeDef(d.type).anywhere && !allowedAtRoot) {
+      const want = locationFor(cfg, d.type);
+      const ok = want.endsWith('/') ? d.path.startsWith(want) : d.path === want;
+      if (!ok) add('wrong-location', d, `a ${typeDef(d.type).label} belongs in ${want}`,
+        { fix: `docgov tag --apply`, destination: destinationFor(cfg, d.type, d.path) });
+    }
+
+    // Visibility paths (PRD §10)
+    for (const vp of cfg.visibility_paths || []) {
+      if (!matchGlob(d.path, vp.glob)) continue;
+      if (!vp.require.includes(d.visibility))
+        add('visibility-path', d, `${vp.glob} may only hold ${vp.require.join(' or ')} documents; this one is ${d.visibility}`);
+    }
+
+    // Required sections
+    if (!generated && !inArchive) {
+      const missing = d.missingSections();
+      if (missing.length) add('missing-sections', d, `missing: ${missing.join(', ')}`,
+        { missing, required: typeDef(d.type).sections });
+    }
+
+    // Size
+    const size = assess(cfg, d);
+    if (size.level === 'hard') add('hard-limit', d, `${d.lines} lines exceeds the hard limit of ${size.hard}`, { size });
+    else if (size.level === 'soft') add('soft-limit', d, `${d.lines} lines exceeds the soft limit of ${size.soft}`, { size });
+
+    for (const r of readmeOverreach(cfg, d)) {
+      add('readme-overreach', d, `section "${r.section}" is ${r.lines} lines`,
+        { fix: r.moveTo ? `docgov create ${r.moveTo}` : null, detail: r });
+    }
+
+    if (inArchive && !only) { /* archived documents are frozen; edits are caught at write time */ }
+  }
+
+  // ---- repository-wide checks
+  const seenIds = new Map();
+  for (const d of docs) {
+    if (!d.meta.id) continue;
+    if (seenIds.has(d.meta.id)) {
+      add('duplicate-id', d, `id "${d.meta.id}" is also used by ${seenIds.get(d.meta.id)}`,
+        { other: seenIds.get(d.meta.id) });
+    } else seenIds.set(d.meta.id, d.path);
+  }
+
+  for (const r of danglingReferences(registry)) {
+    add('unknown-reference', null, `${r.relationship}: "${r.target}" is not a registered document`,
+      { path: r.path, id: r.id, fix: `docgov registry --rebuild` });
+  }
+
+  for (const b of brokenLinks(docs, root, allFiles)) {
+    add('broken-link', null, `link to "${b.target}" resolves to ${b.resolved}, which does not exist`, { path: b.path });
+  }
+  for (const a of brokenAnchors(docs)) {
+    add('broken-anchor', null, `anchor ${a.anchor} has no matching heading`, { path: a.path });
+  }
+
+  for (const v of graph.authorityViolations()) {
+    add('authority-violation', null,
+      `${v.fromAuthority} document ${v.rel} a ${v.toAuthority} document`, { path: v.from, other: v.to });
+  }
+
+  for (const o of graph.orphans()) {
+    if (matchAny(o.path, ['docs/99-archive/**', 'docs/archive/**', 'docs/10-internal/**', 'docs/internal/**'])) continue;
+    add('orphan', null, 'no relationships declared and nothing links to it', { path: o.path, id: o.id });
+  }
+
+  for (const m of missingIndexes(docs)) {
+    add('missing-index', null, `${m.documents} documents and no index`,
+      { path: m.dir, fix: `docgov create ${m.type} "Overview" --path ${m.suggest}` });
+  }
+
+  for (const p of similarPairs(docs, { threshold: 0.55, limit: 15 })) {
+    add('duplicate-candidate', null, `${Math.round(p.score * 100)}% textual overlap with ${p.b}${p.reasons.length ? ` (${p.reasons.join(', ')})` : ''}`,
+      { path: p.a, other: p.b, score: p.score });
+  }
+
+  // New top-level Markdown beyond the allowed singletons
+  const allowedRoot = new Set(Object.values(TYPES).filter((t) => t.singleton).map((t) => t.compact || t.full)
+    .concat(cfg.governance.allowed_root_docs || []));
+  const rootDocs = docs.filter((d) => !d.path.includes('/') && !allowedRoot.has(d.path));
+  if (rootDocs.length > (cfg.governance.max_new_root_docs ?? 0)) {
+    for (const d of rootDocs) {
+      add('new-root-document', d, 'top-level Markdown outside the taxonomy',
+        { fix: `docgov tag --apply --path ${d.path}` });
+    }
+  }
+
+  const stats = summarize(findings);
+  return { findings: sortFindings(findings), stats };
+}
+
+export function sortFindings(findings) {
+  const S = ['critical', 'high', 'medium', 'low'];
+  return findings.slice().sort((a, b) =>
+    Number(b.blocking) - Number(a.blocking) ||
+    S.indexOf(a.severity) - S.indexOf(b.severity) ||
+    String(a.path).localeCompare(String(b.path)) ||
+    a.check.localeCompare(b.check));
+}
+
+export function summarize(findings) {
+  const s = { total: findings.length, blocking: 0, critical: 0, high: 0, medium: 0, low: 0, byCheck: {} };
+  for (const f of findings) {
+    s[f.severity] = (s[f.severity] || 0) + 1;
+    if (f.blocking) s.blocking++;
+    s.byCheck[f.check] = (s.byCheck[f.check] || 0) + 1;
+  }
+  return s;
+}
+
+/**
+ * Exit code contract (PRD §39), with the resolution FEASIBILITY §3.6 demands:
+ * only deterministic violations produce 1. Drift and advisory findings produce 2,
+ * which CI may choose to treat as soft.
+ */
+export function exitCode({ findings, driftFindings = [], cfg }) {
+  if (findings.some((f) => f.blocking)) return EXIT.VIOLATION;
+  const sev = (cfg.drift?.fail_on || ['critical', 'high']);
+  if (driftFindings.some((f) => sev.includes(f.severity))) return EXIT.REVIEW;
+  return EXIT.OK;
+}
+
+/** Pre-write decision for the PreToolUse hook: ring 1 (FEASIBILITY §3.1). */
+export function preWrite({ cfg, relPath, registry, isNew, content }) {
+  const reasons = [];
+  const deny = (check, msg, fix) => reasons.push({ check, message: msg, fix, blocking: blocks(cfg, check) });
+
+  if (matchAny(relPath, cfg.generated_paths || []) && !cfg.generated.allow_manual_edit) {
+    deny('generated-edit', `${relPath} sits in a generated tree; edit the source and regenerate instead`,
+      'change the generator input, then run the generator');
+  }
+  if (matchAny(relPath, ['docs/99-archive/**', 'docs/archive/**'])) {
+    deny('frozen-edit', `${relPath} is archived, and the archive is a historical record`,
+      'create a new document rather than editing the archive');
+  }
+
+  const entry = Object.entries(registry.documents || {}).find(([, e]) => e.path === relPath);
+  if (entry && entry[1].generated && !cfg.generated.allow_manual_edit) {
+    deny('generated-edit', `${relPath} is registered with generation.mode: generated`,
+      'regenerate it rather than editing it');
+  }
+
+  if (content != null && /\.mdx?$/.test(relPath)) {
+    let meta = null;
+    try {
+      meta = fmParse(content).data.docgov || null;
+    } catch (e) {
+      deny('invalid-yaml', `frontmatter in ${relPath} would not parse: ${e.message}`,
+        'fix the YAML, or omit the frontmatter block entirely');
+    }
+    if (meta?.id) {
+      const clash = Object.entries(registry.documents || {})
+        .find(([id, e]) => id === meta.id && e.path !== relPath);
+      if (clash) deny('duplicate-id', `docgov.id "${meta.id}" already belongs to ${clash[1].path}`,
+        `update ${clash[1].path} instead, or choose a different id`);
+    }
+    if (meta?.type && !TYPES[meta.type]) {
+      deny('unknown-type', `docgov.type "${meta.type}" is not a known document class`,
+        'run `docgov types` to list the document classes');
+    }
+    if (meta?.visibility && !VISIBILITY.includes(meta.visibility)) {
+      deny('invalid-visibility', `visibility "${meta.visibility}" is not one of ${VISIBILITY.join(', ')}`, null);
+    }
+    if (meta?.type) {
+      for (const vp of cfg.visibility_paths || []) {
+        if (!matchGlob(relPath, vp.glob)) continue;
+        const vis = meta.visibility || typeDef(meta.type).visibility || 'internal';
+        if (!vp.require.includes(vis)) {
+          deny('visibility-path', `${vp.glob} may only hold ${vp.require.join(' or ')} documents; this one is ${vis}`,
+            'move the document, or change its visibility');
+        }
+      }
+    }
+  }
+
+  if (isNew) {
+    const topLevel = !relPath.includes('/') && /\.mdx?$/.test(relPath);
+    const allowed = new Set(cfg.governance.allowed_root_docs || []);
+    if (topLevel && !allowed.has(relPath)) {
+      deny('new-root-document', `${relPath} would be a new top-level Markdown file`,
+        'run `docgov whatis --path ' + relPath + '` to find where it belongs in the documentation tree');
+    }
+  }
+  return reasons;
+}

package/core/classify.js

@@ -0,0 +1,233 @@
+import path from 'node:path';
+import { TYPES } from './taxonomy.js';
+import { matchGlob } from './util.js';
+
+/**
+ * Deterministic, explainable classification.
+ *
+ * Every candidate carries the signals that produced it, so `docgov whatis`
+ * can always answer "why". The LLM layer is only asked to adjudicate when the
+ * top two candidates are close (see `needsReview`) — it never sees the easy cases.
+ */
+
+/** filename / path signals: [regex, type, weight] */
+const NAME_SIGNALS = [
+  [/^readme\.mdx?$/i, 'user.readme', 100],
+  [/^(readme|index)\.mdx?$/i, 'docs.index', 55],
+  [/^contributing/i, 'governance.contributing', 100],
+  [/^security\.mdx?$/i, 'security.public-model', 70],
+  [/^support/i, 'governance.support', 90],
+  [/^changelog/i, 'release.changelog', 100],
+  [/^claude\.mdx?$|^agents\.mdx?$|^\.cursorrules$/i, 'agent.instructions', 100],
+  [/^code_of_conduct/i, 'governance.code-of-conduct', 95],
+  [/^license/i, 'governance.policy', 30],
+  [/^product\.mdx?$/i, 'constitution.product', 90],
+  [/^principles?\.mdx?$/i, 'constitution.principles', 90],
+  [/^invariants?\.mdx?$/i, 'constitution.invariants', 95],
+  [/^glossary\.mdx?$/i, 'constitution.glossary', 95],
+  [/^domains?\.mdx?$/i, 'constitution.domains', 80],
+  [/(^|[-_/])adr[-_]?\d*|^\d{3,4}-.*\.mdx?$/i, 'architecture.adr', 75],
+  [/(^|[-_])prd(\b|[-_.])|product[-_]requirements/i, 'product.prd', 85],
+  [/(^|[-_])trd(\b|[-_.])|technical[-_]requirements|tech[-_]design|design[-_]doc/i, 'architecture.trd', 80],
+  [/feasibilit|spike|evaluation|assessment|trade[-_]?off|prior[-_]art|research[-_]note/i, 'architecture.assessment', 85],
+  [/threat[-_]?model/i, 'security.threat-model', 95],
+  [/runbook|playbook|oncall|on[-_]call/i, 'operations.runbook', 90],
+  [/disaster|dr[-_]plan|business[-_]continuity/i, 'operations.disaster-recovery', 85],
+  [/deploy(ment)?/i, 'operations.deployment', 70],
+  [/infra(structure)?|terraform|kubernetes|k8s/i, 'operations.infrastructure', 65],
+  [/observability|monitoring|telemetry|metrics|logging|alerting/i, 'operations.observability', 70],
+  [/getting[-_]?started|quick[-_]?start/i, 'user.getting-started', 90],
+  [/tutorial|walkthrough/i, 'user.tutorial', 80],
+  [/troubleshoot|common[-_]issues|known[-_]issues/i, 'user.troubleshooting', 85],
+  [/^faq|\bfaq\b/i, 'user.faq', 85],
+  [/user[-_]guide|admin(istrator)?[-_]guide/i, 'user.guide', 75],
+  [/architecture|system[-_]design/i, 'architecture.overview', 65],
+  [/migration|upgrad(e|ing)/i, 'release.migration', 75],
+  [/deprecat/i, 'release.deprecation', 80],
+  [/release[-_]notes?/i, 'release.notes', 85],
+  [/roadmap/i, 'product.roadmap', 90],
+  [/persona/i, 'product.persona', 90],
+  [/\bux\b|user[-_]experience/i, 'design.ux', 75],
+  [/accessibilit|a11y|wcag/i, 'design.accessibility', 85],
+  [/\bflows?\b|user[-_]journey/i, 'design.flow', 60],
+  [/authoriz|authz|rbac|permissions?/i, 'security.authorization', 75],
+  [/data[-_]classif/i, 'security.data-classification', 90],
+  [/auth(entication)?|identity|oauth|sso/i, 'security.architecture', 55],
+  [/test(ing)?[-_]?(strategy|plan|guide)/i, 'engineering.testing', 80],
+  [/conventions?|style[-_]guide|standards?/i, 'engineering.conventions', 70],
+  [/dependenc/i, 'engineering.dependencies', 75],
+  [/development|dev[-_]setup|contributing[-_]setup|local[-_]dev/i, 'engineering.development', 70],
+  [/config(uration)?[-_]?(reference|ref)?/i, 'operations.configuration', 60],
+  [/\breference\b|api[-_]reference|cli[-_]reference/i, 'user.reference', 70],
+  [/lifecycle|versioning|support[-_]policy/i, 'governance.lifecycle', 70],
+  [/policy|polic(y|ies)/i, 'governance.policy', 55],
+  [/\bnotes?\b|scratch|wip|todo|ideas?/i, 'note.internal', 50],
+  [/vision/i, 'product.vision', 80],
+  [/feature/i, 'product.feature', 55],
+  [/component/i, 'architecture.component', 60],
+  [/data[-_]model|schema[-_]design|erd/i, 'architecture.data', 75],
+  [/integration/i, 'architecture.integration', 70],
+  [/domain/i, 'architecture.domain', 55],
+];
+
+const PATH_SIGNALS = [
+  ['docs/00-canonical/**', null, 40, 'constitution'],
+  ['docs/01-product/**', 'product.prd', 30, null],
+  ['docs/01-product/features/**', 'product.feature', 45, null],
+  ['docs/01-product/personas/**', 'product.persona', 60, null],
+  ['docs/01-product/roadmap/**', 'product.roadmap', 60, null],
+  ['docs/02-design/ux/**', 'design.ux', 50, null],
+  ['docs/02-design/flows/**', 'design.flow', 60, null],
+  ['docs/02-design/accessibility/**', 'design.accessibility', 60, null],
+  ['docs/03-architecture/overview/**', 'architecture.overview', 55, null],
+  ['docs/03-architecture/domains/**', 'architecture.domain', 70, null],
+  ['docs/03-architecture/components/**', 'architecture.component', 45, null],
+  ['docs/03-architecture/data/**', 'architecture.data', 60, null],
+  ['docs/03-architecture/integrations/**', 'architecture.integration', 60, null],
+  ['docs/03-architecture/adr/**', 'architecture.adr', 80, null],
+  ['docs/adr/**', 'architecture.adr', 80, null],
+  ['docs/decisions/**', 'architecture.adr', 70, null],
+  ['docs/04-security/threat-models/**', 'security.threat-model', 70, null],
+  ['docs/04-security/authorization/**', 'security.authorization', 70, null],
+  ['docs/04-security/data-classification/**', 'security.data-classification', 70, null],
+  ['docs/04-security/**', 'security.architecture', 35, null],
+  ['docs/05-engineering/testing/**', 'engineering.testing', 60, null],
+  ['docs/05-engineering/conventions/**', 'engineering.conventions', 60, null],
+  ['docs/05-engineering/dependencies/**', 'engineering.dependencies', 60, null],
+  ['docs/05-engineering/**', 'engineering.development', 30, null],
+  ['docs/06-operations/runbooks/**', 'operations.runbook', 75, null],
+  ['docs/06-operations/deployment/**', 'operations.deployment', 60, null],
+  ['docs/06-operations/infrastructure/**', 'operations.infrastructure', 60, null],
+  ['docs/06-operations/configuration/**', 'operations.configuration', 60, null],
+  ['docs/06-operations/observability/**', 'operations.observability', 60, null],
+  ['docs/06-operations/disaster-recovery/**', 'operations.disaster-recovery', 70, null],
+  ['docs/07-release/releases/**', 'release.notes', 60, null],
+  ['docs/07-release/migrations/**', 'release.migration', 65, null],
+  ['docs/07-release/deprecations/**', 'release.deprecation', 65, null],
+  ['docs/08-user/getting-started/**', 'user.getting-started', 70, null],
+  ['docs/08-user/guides/**', 'user.guide', 50, null],
+  ['docs/08-user/reference/**', 'user.reference', 65, null],
+  ['docs/08-user/troubleshooting/**', 'user.troubleshooting', 70, null],
+  ['docs/08-user/faq/**', 'user.faq', 70, null],
+  ['docs/09-governance/**', 'governance.policy', 35, null],
+  ['docs/10-internal/**', 'note.internal', 45, null],
+  ['docs/internal/**', 'note.internal', 45, null],
+  ['docs/90-generated/**', 'user.reference', 60, null],
+  ['docs/99-archive/**', 'archive.document', 95, null],
+  ['docs/archive/**', 'archive.document', 90, null],
+];
+
+/** content signals: [regex over body, type, weight] */
+const CONTENT_SIGNALS = [
+  [/^\s*#+\s*(status|decision)\s*$/im, 'architecture.adr', 35],
+  [/\bsupersed(es|ed by)\b/i, 'architecture.adr', 20],
+  [/\b(trust boundar|threat actor|attack surface|STRIDE|residual risk)/i, 'security.threat-model', 45],
+  [/\b(non-?goals?)\b/i, 'product.prd', 20],
+  [/\bacceptance criteria\b/i, 'product.prd', 25],
+  [/\b(personas?|user stor(y|ies))\b/i, 'product.prd', 15],
+  [/\b(rollback|rollout)\b.*\n[\s\S]*\b(observability|migration)\b/i, 'architecture.trd', 30],
+  [/\b(RPO|RTO)\b/, 'operations.disaster-recovery', 50],
+  [/\b(escalat|pager|severity|SEV-?\d)\b/i, 'operations.runbook', 30],
+  [/^\s*#+\s*(trigger|diagnostics|procedure)\s*$/im, 'operations.runbook', 45],
+  [/\binvariant\b/i, 'constitution.invariants', 25],
+  [/^\s*\|?\s*term\s*\|/im, 'constitution.glossary', 40],
+  [/\bnpm install\b|\bpip install\b|\bgetting started\b/i, 'user.getting-started', 20],
+  [/\bSLO\b|\bSLI\b|\bprometheus\b|\bgrafana\b/i, 'operations.observability', 35],
+  [/\b(kubernetes|terraform|helm|ECS|EKS)\b/i, 'operations.infrastructure', 25],
+  [/\bWCAG\b|\bscreen reader\b|\baria-/i, 'design.accessibility', 45],
+  [/\bRBAC\b|\brole\b.*\bpermission\b/i, 'security.authorization', 30],
+  [/\bdeprecat(ed|ion)\b/i, 'release.deprecation', 25],
+  [/^\s*#+\s*v?\d+\.\d+\.\d+/m, 'release.notes', 40],
+  [/\bopenapi\b|\bswagger\b/i, 'user.reference', 15],
+  [/\bAUTO-?GENERATED\b|\bDo not edit\b/i, 'user.reference', 55],
+  [/^#+\s*\d+\.\s+verdict|^#+\s*verdict\s*$/im, 'architecture.assessment', 45],
+];
+
+const CONFIDENT = 60;
+const AMBIGUOUS_GAP = 15;
+
+/**
+ * @param {{path:string, body?:string, frontmatter?:object}} doc
+ * @returns {{type:string, confidence:number, signals:string[], candidates:{type:string,score:number}[], needsReview:boolean, declared:boolean}}
+ */
+export function classify(doc) {
+  const declared = doc.frontmatter?.docgov?.type;
+  if (declared && TYPES[declared]) {
+    return { type: declared, confidence: 100, signals: ['declared in frontmatter'],
+      candidates: [{ type: declared, score: 100 }], needsReview: false, declared: true };
+  }
+
+  const rel = doc.path;
+  const base = path.basename(rel);
+  const scores = new Map();
+  const signals = new Map();
+  const bump = (type, w, why) => {
+    if (!type || !TYPES[type]) return;
+    scores.set(type, (scores.get(type) || 0) + w);
+    if (!signals.has(type)) signals.set(type, []);
+    signals.get(type).push(why);
+  };
+
+  for (const [re, type, w] of NAME_SIGNALS) {
+    if (re.test(base)) bump(type, w, `filename matches ${re.source.slice(0, 34)}`);
+    else if (re.test(rel)) bump(type, Math.round(w * 0.6), `path matches ${re.source.slice(0, 34)}`);
+  }
+  for (const [glob, type, w, authority] of PATH_SIGNALS) {
+    if (!matchGlob(rel, glob)) continue;
+    if (type) bump(type, w, `located in ${glob}`);
+    if (authority) for (const [id, t] of Object.entries(TYPES)) if (t.authority === authority) bump(id, w, `located in ${glob}`);
+  }
+  const body = doc.body ?? '';
+  for (const [re, type, w] of CONTENT_SIGNALS) {
+    if (re.test(body)) bump(type, w, `content matches ${re.source.slice(0, 34)}`);
+  }
+
+  // Root-level singletons are a strong tie-break: only one README can exist.
+  if (!rel.includes('/')) {
+    for (const [id, t] of Object.entries(TYPES)) {
+      if (t.singleton && (t.compact || t.full) === rel) bump(id, 60, 'canonical singleton path');
+    }
+  }
+
+  // Singleton classes (README, CHANGELOG, the constitution documents) exist exactly once,
+  // at a fixed path. A nested README.md is a directory index, not *the* README, and letting
+  // it win would send every subdirectory README to the repository root.
+  for (const [type, t] of Object.entries(TYPES)) {
+    if (!t.singleton || !scores.has(type)) continue;
+    const canonical = t.compact || t.full;
+    if (rel !== canonical) {
+      scores.delete(type);
+      signals.delete(type);
+    }
+  }
+
+  const candidates = [...scores.entries()]
+    .map(([type, score]) => ({ type, score }))
+    .sort((a, b) => b.score - a.score || a.type.localeCompare(b.type));
+
+  if (candidates.length === 0) {
+    return { type: 'unknown', confidence: 0, signals: ['no signal matched'], candidates: [], needsReview: true, declared: false };
+  }
+
+  const top = candidates[0];
+  const gap = top.score - (candidates[1]?.score ?? 0);
+  const confidence = Math.min(99, top.score);
+  return {
+    type: top.type,
+    confidence,
+    signals: signals.get(top.type) || [],
+    candidates: candidates.slice(0, 5),
+    needsReview: confidence < CONFIDENT || gap < AMBIGUOUS_GAP,
+    declared: false,
+  };
+}
+
+/** Suggested destination path for a doc of `type`, given the active layout. */
+export function destinationFor(cfg, type, currentPath) {
+  const t = TYPES[type] || TYPES.unknown;
+  if (t.anywhere) return currentPath;                       // belongs to its directory
+  const loc = cfg.project.layout === 'full' ? t.full : (t.compact || t.full);
+  if (!loc.endsWith('/')) return loc;                       // singleton or fixed file
+  const base = path.basename(currentPath);
+  return loc + base;
+}