docgov-cli 0.2.0

package/core/templates.js

@@ -0,0 +1,159 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as yaml from './yaml.js';
+import { TYPES, typeDef } from './taxonomy.js';
+import { read, exists, titleCase, slug } from './util.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const TEMPLATE_DIR = path.join(HERE, '..', 'templates');
+
+/**
+ * Templates (PRD §12).
+ *
+ * 52 document classes do not need 52 hand-written files. A class's required
+ * sections already describe its shape, so templates are synthesized from the
+ * taxonomy and only the classes whose value is in their *prose scaffolding*
+ * (PRD, TRD, ADR, threat model, runbook, README) ship a hand-authored file.
+ */
+
+/** Per-section prompts used when synthesizing. Keyed by lowercased section title. */
+const SECTION_HINTS = {
+  context: 'What situation makes this necessary? Link the upstream document.',
+  problem: 'State the problem in terms the reader can verify, not in terms of the solution.',
+  goals: 'Outcomes, each one observable.',
+  'non-goals': 'What this explicitly does not do, so nobody has to guess.',
+  scope: 'What is inside and outside this document\'s authority.',
+  purpose: 'One paragraph: why this exists.',
+  boundaries: 'What this owns, and what it explicitly delegates.',
+  invariants: 'Rules that must hold at all times. Give each an ID like `INV-<DOMAIN>-001`.',
+  interfaces: 'Inputs and outputs. Point at the machine contract rather than restating it.',
+  'failure modes': 'What goes wrong, how it is detected, what happens next.',
+  dependencies: 'What this relies on, and what breaks if each one is unavailable.',
+  'acceptance criteria': 'Verifiable conditions. If a reviewer cannot check it, rewrite it.',
+  'open questions': 'Unresolved decisions, each with an owner.',
+  assets: 'What is worth protecting, and why.',
+  actors: 'Who interacts with this, including the ones you would rather not have.',
+  'trust boundaries': 'Where trust changes. Name what crosses each boundary.',
+  threats: 'Each threat, its affected asset, and its likelihood.',
+  controls: 'What stops each threat. Point at the implementation.',
+  'residual risks': 'What remains after the controls, and who accepted it.',
+  assumptions: 'What must be true for this document to remain correct.',
+  trigger: 'The exact signal that starts this procedure.',
+  preconditions: 'What must be true before you begin.',
+  diagnostics: 'Commands and queries that tell you what is actually happening.',
+  procedure: 'Numbered steps. Each step has one action and one expected result.',
+  validation: 'How you know it worked.',
+  rollback: 'How to undo this, and the point past which you cannot.',
+  escalation: 'Who to wake, and when.',
+  install: 'The shortest path from nothing to installed.',
+  usage: 'The smallest useful example, runnable as written.',
+  steps: 'Numbered, each with its expected result.',
+  security: 'Trust boundaries, secrets, authorization. Link the threat model.',
+  performance: 'Targets, measured not guessed.',
+  observability: 'Signals, dashboards, alerts.',
+  migration: 'How existing data and clients move across.',
+  rollout: 'Order, gates, and the blast radius at each stage.',
+  testing: 'What is covered, at which level, and what is deliberately not.',
+  status: 'proposed | accepted | superseded',
+  decision: 'The decision, in one sentence, in the active voice.',
+  alternatives: 'What else was considered and why it lost.',
+  consequences: 'What this makes easier, and what it makes harder.',
+};
+
+/** @returns {string|null} hand-authored template body, if one exists */
+export function override(type) {
+  const f = path.join(TEMPLATE_DIR, `${type}.md`);
+  return exists(f) ? read(f) : null;
+}
+
+/**
+ * @param {{type:string, title?:string, id?:string, cfg:object, domain?:string|null,
+ *          relationships?:object, owner?:string|null, visibility?:string|null}} args
+ */
+export function create({ type, title, id, cfg, domain = null, relationships = null, owner = null, visibility = null }) {
+  const def = typeDef(type);
+  if (!TYPES[type]) throw new Error(`unknown document type: ${type}`);
+  const docId = id || slug(title || def.label);
+  const meta = {
+    id: docId,
+    type,
+    authority: def.authority,
+    audience: audienceFor(def),
+    visibility: visibility || def.visibility || 'internal',
+    status: 'draft',
+  };
+  if (domain) meta.domain = domain;
+  if (owner || cfg.profile?.require_owner) meta.owner = owner || 'unassigned';
+  if (relationships && Object.keys(relationships).length) meta.relationships = relationships;
+  if (def.generated) meta.generation = { mode: 'generated' };
+  else meta.generation = { mode: 'human-maintained' };
+  if (def.authority === 'canonical' || def.authority === 'constitution') meta.review = { cadence: '90d' };
+
+  const front = `---\n${yaml.stringify({ docgov: meta })}---\n`;
+  const body = override(type) ?? synthesize(type, title || def.label);
+  return front + body;
+}
+
+export function synthesize(type, title) {
+  const def = typeDef(type);
+  const L = [`# ${title}`, ''];
+  L.push(`> ${def.label}. ${guidanceFor(def)}`);
+  L.push('');
+  const sections = def.sections || [];
+  if (sections.length === 0) {
+    L.push('<!-- No required sections for this document class. Keep it focused on one concept. -->');
+    L.push('');
+    return L.join('\n');
+  }
+  for (const s of sections) {
+    L.push(`## ${s}`);
+    L.push('');
+    const hint = SECTION_HINTS[s.toLowerCase()];
+    L.push(`<!-- ${hint || `${s}.`} -->`);
+    L.push('');
+  }
+  return L.join('\n');
+}
+
+function guidanceFor(def) {
+  const limit = def.hard ? `Keep it under ${def.soft} lines; ${def.hard} triggers review.` : '';
+  const auth = {
+    constitution: 'Changes here should be rare and deliberate — everything else defers to this.',
+    canonical: 'This is the authoritative description. Lower-authority documents may not contradict it.',
+    requirements: 'This explains what is being built and why, not how the code happens to work today.',
+    decision: 'Record the decision and the alternatives. Do not rewrite history; supersede instead.',
+    generated: 'Generated — do not edit by hand. Change the source and regenerate.',
+    audience: 'Written for its reader, not for the architecture. Link depth rather than embedding it.',
+    historical: 'Historical record. Correct only factual errors.',
+    'machine-contract': 'The contract is authoritative; prose describing it is not.',
+  }[def.authority] || '';
+  return [auth, limit].filter(Boolean).join(' ');
+}
+
+function audienceFor(def) {
+  return {
+    readme: ['everyone'], developer: ['engineering'], architecture: ['engineering', 'architecture'],
+    security: ['engineering', 'security'], user: ['users'], operations: ['operations'], agent: ['agents'],
+  }[def.lens] || ['engineering'];
+}
+
+/** Frontmatter block for an existing document that has none (used by `organize`). */
+export function frontmatterFor({ type, id, title, cfg, domain = null, visibility = null, owner = null }) {
+  const def = typeDef(type);
+  const meta = {
+    id, type, authority: def.authority, audience: audienceFor(def),
+    visibility: visibility || def.visibility || 'internal', status: 'active',
+  };
+  if (domain) meta.domain = domain;
+  if (cfg.profile?.require_owner) meta.owner = owner || 'unassigned';
+  meta.generation = { mode: def.generated ? 'generated' : 'human-maintained' };
+  return meta;
+}
+
+export function listTypes() {
+  return Object.entries(TYPES).map(([id, t]) => ({
+    type: id, label: t.label, authority: t.authority, lens: t.lens,
+    soft: t.soft || '', hard: t.hard || '', sections: (t.sections || []).length,
+    handwritten: exists(path.join(TEMPLATE_DIR, `${id}.md`)) ? 'yes' : '',
+  }));
+}

package/core/util.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const EXIT = { OK: 0, VIOLATION: 1, REVIEW: 2, CONFIG: 3 };
+
+export class DocGovError extends Error {
+  constructor(msg, code = EXIT.CONFIG) { super(msg); this.name = 'DocGovError'; this.code = code; }
+}
+
+export function read(p) { return fs.readFileSync(p, 'utf8'); }
+export function exists(p) { try { fs.accessSync(p); return true; } catch { return false; } }
+
+export function write(p, content) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content, 'utf8');
+  return p;
+}
+
+export function sha(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.docgov', 'dist', 'build', 'out', 'target', 'vendor',
+  '.next', '.nuxt', '.venv', 'venv', '__pycache__', '.pytest_cache', 'coverage',
+  '.turbo', '.cache', '.idea', '.vscode', 'site-packages',
+]);
+
+/**
+ * Depth-limited recursive walk returning repo-relative POSIX paths.
+ * @param {string} root
+ * @param {{match?:(rel:string)=>boolean, maxDepth?:number, includeDirs?:boolean}} [opts]
+ */
+export function walk(root, opts = {}) {
+  const { match = () => true, maxDepth = 12, includeDirs = false } = opts;
+  const out = [];
+  const rec = (dir, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.name !== '.github' && e.name !== '.claude') continue;
+      if (SKIP_DIRS.has(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      const rel = toPosix(path.relative(root, abs));
+      if (e.isDirectory()) {
+        if (includeDirs && match(rel)) out.push(rel);
+        rec(abs, depth + 1);
+      } else if (e.isFile() && match(rel)) out.push(rel);
+    }
+  };
+  rec(root, 0);
+  return out.sort();
+}
+
+export function toPosix(p) { return p.split(path.sep).join('/'); }
+
+/** Minimal glob: supports **, *, ?, and {a,b} alternation. Anchored. */
+export function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        // "**/" matches zero or more path segments
+        if (glob[i + 2] === '/') { re += '(?:[^/]*\\/)*'; i += 2; }
+        else { re += '.*'; i += 1; }
+      } else re += '[^/]*';
+    } else if (c === '?') re += '[^/]';
+    else if (c === '{') {
+      const close = glob.indexOf('}', i);
+      if (close < 0) { re += '\\{'; continue; }
+      re += `(?:${glob.slice(i + 1, close).split(',').map(escapeRe).join('|')})`;
+      i = close;
+    } else re += escapeRe(c);
+  }
+  return new RegExp(`^${re}$`);
+}
+
+function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+export function matchGlob(p, glob) { return globToRegExp(glob).test(p); }
+export function matchAny(p, globs) { return (globs || []).some((g) => matchGlob(p, g)); }
+
+/** Deep merge; arrays replace, objects merge, undefined ignored. */
+export function merge(base, over) {
+  if (over === undefined || over === null) return base;
+  if (Array.isArray(base) || Array.isArray(over)) return over;
+  if (typeof base !== 'object' || typeof over !== 'object' || base === null) return over;
+  const out = { ...base };
+  for (const k of Object.keys(over)) out[k] = merge(base[k], over[k]);
+  return out;
+}
+
+export function slug(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60);
+}
+
+export function titleCase(s) {
+  return String(s).replace(/[-_/]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+}
+
+export function pct(n, d) { return d === 0 ? 100 : Math.round((n / d) * 100); }
+
+export function table(rows, headers) {
+  if (rows.length === 0) return '(none)';
+  const cols = headers || Object.keys(rows[0]);
+  const width = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? '').length)));
+  const line = (cells) => cells.map((v, i) => String(v ?? '').padEnd(width[i])).join('  ').trimEnd();
+  return [line(cols), line(width.map((w) => '-'.repeat(w))), ...rows.map((r) => line(cols.map((c) => r[c])))].join('\n');
+}
+
+export function plural(n, one, many = `${one}s`) { return `${n} ${n === 1 ? one : many}`; }
+
+export function findRepoRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (exists(path.join(dir, '.docgov', 'config.yaml')) || exists(path.join(dir, '.git'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) return path.resolve(start);
+    dir = up;
+  }
+}

package/core/yaml.js

@@ -0,0 +1,250 @@
+/**
+ * Strict YAML subset parser + emitter. Zero dependencies.
+ *
+ * Supported: comments, nested block maps (2-space or any consistent indent),
+ * block sequences, scalars (string / number / bool / null), single- and
+ * double-quoted strings, inline flow sequences [a, b], inline flow maps {a: b}.
+ *
+ * Deliberately UNSUPPORTED — these throw rather than guess, because a governance
+ * engine that silently misreads its own config is worse than one that refuses to
+ * start: anchors (&), aliases (*), tags (!!), block scalars (| >), tabs,
+ * multi-document streams (---  beyond frontmatter fences), complex keys (?).
+ */
+
+export class YamlError extends Error {
+  constructor(msg, line) {
+    super(line == null ? msg : `${msg} (line ${line + 1})`);
+    this.name = 'YamlError';
+    this.line = line;
+  }
+}
+
+const UNSUPPORTED = [
+  [/^\s*[?]\s/, 'complex mapping keys (?)'],
+  [/\t/, 'tab indentation'],
+];
+
+function stripComment(s) {
+  // Remove a trailing # comment that is not inside quotes.
+  let q = null;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (q) {
+      if (c === '\\' && q === '"') i++;
+      else if (c === q) q = null;
+    } else if (c === '"' || c === "'") q = c;
+    else if (c === '#' && (i === 0 || /\s/.test(s[i - 1]))) return s.slice(0, i);
+  }
+  return s;
+}
+
+function parseScalar(raw, lineNo) {
+  const s = raw.trim();
+  if (s === '') return '';
+  if (s[0] === '&' || s[0] === '*') throw new YamlError('anchors and aliases are not supported', lineNo);
+  if (s.startsWith('!!') || s.startsWith('!')) throw new YamlError('YAML tags are not supported', lineNo);
+  if (s === '|' || s === '>' || s === '|-' || s === '>-' || s === '|+' || s === '>+')
+    throw new YamlError('block scalars (| >) are not supported; use a quoted single-line string', lineNo);
+  if (s[0] === '"' && s.endsWith('"') && s.length > 1) return JSON.parse(s);
+  if (s[0] === "'" && s.endsWith("'") && s.length > 1) return s.slice(1, -1).replace(/''/g, "'");
+  if (s[0] === '[') return parseFlowSeq(s, lineNo);
+  if (s[0] === '{') return parseFlowMap(s, lineNo);
+  if (s === 'null' || s === '~') return null;
+  if (s === 'true' || s === 'yes' || s === 'on') return true;
+  if (s === 'false' || s === 'no' || s === 'off') return false;
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  if (/^-?\d*\.\d+$/.test(s)) return parseFloat(s);
+  return s;
+}
+
+function splitFlow(body, lineNo) {
+  const parts = [];
+  let depth = 0, q = null, cur = '';
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (q) {
+      cur += c;
+      if (c === '\\' && q === '"') { cur += body[++i] ?? ''; }
+      else if (c === q) q = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { q = c; cur += c; continue; }
+    if (c === '[' || c === '{') depth++;
+    if (c === ']' || c === '}') depth--;
+    if (c === ',' && depth === 0) { parts.push(cur); cur = ''; continue; }
+    cur += c;
+  }
+  if (q) throw new YamlError('unterminated quote in flow collection', lineNo);
+  if (cur.trim() !== '') parts.push(cur);
+  return parts;
+}
+
+function parseFlowSeq(s, lineNo) {
+  if (!s.endsWith(']')) throw new YamlError('unterminated flow sequence', lineNo);
+  const body = s.slice(1, -1).trim();
+  if (body === '') return [];
+  return splitFlow(body, lineNo).map((p) => parseScalar(p, lineNo));
+}
+
+function parseFlowMap(s, lineNo) {
+  if (!s.endsWith('}')) throw new YamlError('unterminated flow mapping', lineNo);
+  const body = s.slice(1, -1).trim();
+  const out = {};
+  if (body === '') return out;
+  for (const p of splitFlow(body, lineNo)) {
+    const i = splitKey(p);
+    if (i < 0) throw new YamlError('flow mapping entry missing ":"', lineNo);
+    out[parseScalar(p.slice(0, i), lineNo)] = parseScalar(p.slice(i + 1), lineNo);
+  }
+  return out;
+}
+
+/** Index of the ":" that separates key from value, ignoring quoted regions. */
+function splitKey(s) {
+  let q = null;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (q) {
+      if (c === '\\' && q === '"') i++;
+      else if (c === q) q = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { q = c; continue; }
+    if (c === ':' && (i + 1 === s.length || /[\s]/.test(s[i + 1]))) return i;
+  }
+  return -1;
+}
+
+/** @returns {{indent:number, text:string, lineNo:number}[]} */
+function tokenize(src) {
+  const out = [];
+  const lines = src.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    for (const [re, what] of UNSUPPORTED) {
+      if (re.test(raw)) throw new YamlError(`${what} is not supported`, i);
+    }
+    const text = stripComment(raw).replace(/\s+$/, '');
+    if (text.trim() === '') continue;
+    out.push({ indent: raw.length - raw.trimStart().length, text: text.trimStart(), lineNo: i });
+  }
+  return out;
+}
+
+/**
+ * @param {string} src
+ * @returns {any}
+ */
+export function parse(src) {
+  if (src == null) return {};
+  const toks = tokenize(String(src));
+  if (toks.length === 0) return {};
+  const [value, next] = parseBlock(toks, 0, toks[0].indent);
+  if (next < toks.length) throw new YamlError('unexpected content after document', toks[next].lineNo);
+  return value;
+}
+
+function parseBlock(toks, i, indent) {
+  if (i >= toks.length) return [null, i];
+  if (toks[i].text.startsWith('- ') || toks[i].text === '-') return parseSeq(toks, i, indent);
+  return parseMap(toks, i, indent);
+}
+
+function parseSeq(toks, i, indent) {
+  const out = [];
+  while (i < toks.length && toks[i].indent === indent) {
+    const t = toks[i];
+    if (!(t.text === '-' || t.text.startsWith('- '))) break;
+    const rest = t.text === '-' ? '' : t.text.slice(2).trim();
+    if (rest === '') {
+      i++;
+      if (i < toks.length && toks[i].indent > indent) {
+        const [v, n] = parseBlock(toks, i, toks[i].indent);
+        out.push(v); i = n;
+      } else out.push(null);
+      continue;
+    }
+    const k = splitKey(rest);
+    if (k >= 0) {
+      // "- key: value" opens an inline map whose continuation is indented past the dash
+      const inner = [{ indent: indent + 2, text: rest, lineNo: t.lineNo }];
+      let j = i + 1;
+      while (j < toks.length && toks[j].indent > indent) { inner.push(toks[j]); j++; }
+      const [v, n] = parseMap(inner, 0, indent + 2);
+      if (n < inner.length) throw new YamlError('unexpected content in sequence item', inner[n].lineNo);
+      out.push(v); i = j;
+      continue;
+    }
+    out.push(parseScalar(rest, t.lineNo));
+    i++;
+  }
+  return [out, i];
+}
+
+function parseMap(toks, i, indent) {
+  const out = {};
+  while (i < toks.length && toks[i].indent === indent) {
+    const t = toks[i];
+    if (t.text.startsWith('- ')) break;
+    const k = splitKey(t.text);
+    if (k < 0) throw new YamlError(`expected "key: value", got ${JSON.stringify(t.text)}`, t.lineNo);
+    const key = String(parseScalar(t.text.slice(0, k), t.lineNo));
+    const rest = t.text.slice(k + 1).trim();
+    if (rest !== '') { out[key] = parseScalar(rest, t.lineNo); i++; continue; }
+    // nested block, or explicit empty
+    if (i + 1 < toks.length && toks[i + 1].indent > indent) {
+      const [v, n] = parseBlock(toks, i + 1, toks[i + 1].indent);
+      out[key] = v; i = n;
+    } else if (i + 1 < toks.length && toks[i + 1].indent === indent && toks[i + 1].text.startsWith('- ')) {
+      const [v, n] = parseSeq(toks, i + 1, indent);
+      out[key] = v; i = n;
+    } else { out[key] = null; i++; }
+  }
+  return [out, i];
+}
+
+const PLAIN_SAFE = /^[A-Za-z0-9_][A-Za-z0-9 _\-./:+@]*$/;
+
+function emitScalar(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  const s = String(v);
+  if (s === '') return "''";
+  if (PLAIN_SAFE.test(s) && !/^(true|false|yes|no|on|off|null|~)$/i.test(s) && !/^-?\d+(\.\d+)?$/.test(s) && !s.endsWith(' '))
+    return s;
+  return JSON.stringify(s);
+}
+
+/**
+ * Deterministic emitter: object keys in insertion order, 2-space indent.
+ * @param {any} value
+ * @param {number} [indent]
+ */
+export function stringify(value, indent = 0) {
+  const pad = ' '.repeat(indent);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return `${pad}[]\n`;
+    return value.map((v) => {
+      if (v !== null && typeof v === 'object') {
+        const body = stringify(v, indent + 2);
+        return `${pad}-${body.slice(indent + 1)}`;
+      }
+      return `${pad}- ${emitScalar(v)}\n`;
+    }).join('');
+  }
+  if (value !== null && typeof value === 'object') {
+    const keys = Object.keys(value);
+    if (keys.length === 0) return `${pad}{}\n`;
+    return keys.map((k) => {
+      const v = value[k];
+      const key = PLAIN_SAFE.test(k) ? k : JSON.stringify(k);
+      if (v !== null && typeof v === 'object') {
+        if (Array.isArray(v) && v.length === 0) return `${pad}${key}: []\n`;
+        if (!Array.isArray(v) && Object.keys(v).length === 0) return `${pad}${key}: {}\n`;
+        return `${pad}${key}:\n${stringify(v, indent + 2)}`;
+      }
+      return `${pad}${key}: ${emitScalar(v)}\n`;
+    }).join('');
+  }
+  return `${pad}${emitScalar(value)}\n`;
+}

package/hooks/hooks.json

@@ -0,0 +1,65 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "args": ["node", "${CLAUDE_PLUGIN_ROOT}/bin/docgov", "hook", "session-start"],
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "args": ["node", "${CLAUDE_PLUGIN_ROOT}/bin/docgov", "hook", "pre-tool"],
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "prompt",
+            "if": "Write(**/*.md)",
+            "timeout": 20,
+            "continueOnBlock": true,
+            "prompt": "You are a documentation lens reviewer for a single file write. The tool input contains `file_path` and `content`.\n\nJudge ONLY these two things, which are decidable from the content and path alone. Everything structural is already enforced deterministically elsewhere — do not repeat it.\n\n1. AUDIENCE LENS MISMATCH. Does the content match the audience its location implies?\n   - a README, getting-started, tutorial or anything under a `user/`, `public/` or `08-user/` path must be task-oriented for its reader: no internal implementation dumps, no architecture essays, no unexplained internal jargon.\n   - anything under an `architecture/`, `03-architecture/` or `domains/` path must describe boundaries, responsibilities, data flows and trade-offs — not installation steps or tutorials.\n   - a runbook must be executable under pressure: numbered steps with expected results, not prose.\n\n2. VISIBILITY LEAK. If the path is public-facing (`README`, `SECURITY.md`, `CONTRIBUTING.md`, or anything under `public/`, `external/`, `11-external/`, `08-user/`), does the content contain internal hostnames, private IPs, credential-shaped strings, internal ticket ids, employee emails, or descriptions of unmitigated vulnerabilities?\n\nRespond with JSON only.\nIf both are fine: {\"ok\": true}\nIf not: {\"ok\": false, \"reason\": \"<which of the two problems, the specific lines or phrases at fault, and what to do instead>\"}\n\nBe conservative. A document that is merely terse, incomplete or unpolished is fine — say ok. Only flag a genuine audience mismatch or a genuine leak.\n\n$ARGUMENTS"
+          }
+        ]
+      }
+    ],
+
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "args": ["node", "${CLAUDE_PLUGIN_ROOT}/bin/docgov", "hook", "post-write"],
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "args": ["node", "${CLAUDE_PLUGIN_ROOT}/bin/docgov", "hook", "stop"],
+            "timeout": 20
+          }
+        ]
+      }
+    ]
+  }
+}

package/lenses/agent.md

@@ -0,0 +1,38 @@
+# Agent lens
+
+**The question:** can a different agent, with no access to this conversation, act on this
+document and get it right?
+
+This is the lens that matters most in a repository most of whose authors are agents, and
+the one human reviewers never apply.
+
+## Evaluates
+
+- **Self-containment.** No reliance on context that lived in a chat.
+- **Stated prerequisites.** An agent will not infer an unstated precondition; it will
+  proceed confidently without it.
+- **No ambiguous authority.** It is clear whether this document is authoritative or
+  describes something else that is.
+- **No TBD as fact.** `TODO`, `TBD`, `???` and "coming soon" will be read as current state.
+  Either state what is true or say explicitly that it is unknown and who owns it.
+- **Verifiable claims.** Numbers, paths and versions an agent can check. An unsourced claim
+  gets propagated as authoritative.
+- **Runnable examples.** Exactly as written, with no implied edits.
+- **Declared relationships.** A document outside the graph is invisible to impact analysis,
+  so nothing will ever tell an agent it went stale.
+- **Fits a context window.** Past roughly 1,200 lines an agent will see a truncated half of
+  the document and will not know which half.
+- **Unambiguous terminology.** One term per concept. A document that uses "tenant",
+  "organization" and "account" for the same thing will produce code that uses all three.
+
+## Fails the lens
+
+- "As discussed" / "per the decision" with no link.
+- Two sections describing the same behaviour differently; an agent may read either.
+- Aspirational present tense, which an agent will implement against.
+- Examples with placeholders (`<your-key>`) and no statement that they are placeholders.
+
+## The test
+
+Strip the document of everything except its own text. Would an agent reading only that make
+a wrong assumption? Each wrong assumption is a finding.

package/lenses/architecture.md

@@ -0,0 +1,30 @@
+# Architecture lens
+
+**The question:** can a reader tell what this system guarantees, where its boundaries are,
+and which changes are safe?
+
+## Evaluates
+
+- **Boundaries.** What is inside, what is outside, what crosses. Unambiguous.
+- **Responsibilities.** What each component owns. Two components owning one thing is a
+  finding, not a detail.
+- **Data flows.** What moves where, in what shape, triggered by what.
+- **Dependencies.** Direction included. Cycles are findings.
+- **Invariants.** What must always hold. Given ids so they can be enforced and cited.
+- **Trade-offs.** What was given up. An architecture document with no trade-offs is a sales
+  document.
+- **ADR references.** Decisions linked rather than re-argued, so nobody reverses one by
+  accident.
+
+## Fails the lens
+
+- Installation or usage instructions. Wrong document.
+- A diagram with no text. A diagram shows structure; it cannot state a guarantee.
+- "Scalable", "robust", "performant" with no number or mechanism.
+- Present tense describing aspiration. If it is not built, say so and link the PRD.
+- Restating a schema that lives in a machine contract, creating a second source of truth.
+
+## The test
+
+Could a reader use this document to decide whether a proposed change is safe? If not, it
+describes the system without governing it.