@jamie-tam/forge 6.0.0

package/skills/support-wiki-lint/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: support-wiki-lint
+description: "Use to validate a wiki page against its schema — required frontmatter, required H2 sections, line caps, citation hash drift. Runs synchronously on every aiwiki/** write via PostToolUse hook, and on dream output before user review. Catches schema violations and stale citations the moment they happen."
+---
+
+# Support: Wiki Lint
+
+## Overview
+
+The wiki is curated to answer recurring questions. That only works if every page conforms to its declared schema (so AI can find what it needs predictably) and every code citation still points at the code that exists today (so claims don't go silently stale). This skill enforces both — fast, deterministic, blocking.
+
+**Core principle:** validation is mechanical. No judgment, no "this looks roughly right." Either the page matches its schema and citations resolve, or it doesn't.
+
+**Announce at start:** "I'm using the support-wiki-lint skill to validate the wiki page."
+
+## When to Use
+
+- Synchronously on every `aiwiki/**` write (PostToolUse hook fires the script)
+- On dream output in `aiwiki/proposed/{dream_id}/` before the dream is marked complete
+- On-demand when validating a wiki page manually (e.g. after a refactor that may have moved cited code)
+
+**Do NOT skip when:**
+- The page "looks fine" — schema drift accumulates silently; that's why we lint
+- The change is "just a typo" — a typo in frontmatter (`schema_id: decsion`) breaks downstream tooling
+- The dream just produced the file — dreamer's output goes through lint like every other write
+
+## Scope
+
+Catches four classes of wiki defect:
+
+| Defect | Example | Severity |
+|---|---|---|
+| Missing or malformed frontmatter | No `schema_id`; `schema_version` is a string instead of integer | error (block) |
+| Missing required H2 section | ADR with no `## Decision` | error (block) |
+| Section order violation when schema declares `section_order: strict` | `## Decision` before `## Context` | error (block) |
+| Line cap exceeded | ADR > 400 lines | error (block) |
+| Stale citation hash | `file:line@a3f2bc1` but recomputed hash is now `b1c2d3e` | error (block) |
+| Missing citation hash on a `file:line` reference | `src/auth.ts:42` instead of `src/auth.ts:42@a3f2bc1` | warning (auto-backfill) |
+| Cited file does not exist | `src/old.ts:42@a3f2bc1` after `src/old.ts` was deleted | error (block) |
+| Soft-target line count exceeded | Gotcha at 110 lines (soft target 50-100) | warning (don't block) |
+
+Out of scope (intentionally — these are someone else's job):
+- Semantic content quality ("is this ADR's rationale sound?") → reviewer subagents
+- Cross-page consistency ("does this ADR contradict another?") → dream consolidation
+- Markdown rendering correctness → markdown linter (different tool)
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Target file path, repo root, schema directory (`aiwiki/schemas/`) |
+| **Produces** | JSON to stdout: `{ok: bool, errors: [...], warnings: [...], updates: [...] }`. Exit 0 on pass, exit 1 on lint failure, exit 2 on internal error. |
+| **Side effect** | Auto-backfills missing `@<sha7>` citation hashes in-place (via `updates[]`). Auto-backfill is the ONLY in-place modification; everything else is reported, not fixed. |
+| **Feeds into** | PostToolUse hook (block on exit ≠ 0); dream-completion gate; manual `/wiki lint` invocation |
+
+## Process
+
+### Step 0: locate inputs
+
+| Input | How to find |
+|---|---|
+| Repo root | `git rev-parse --show-toplevel`, or `${CLAUDE_PROJECT_DIR}` if set |
+| Schema directory | `<repo-root>/aiwiki/schemas/`. If missing, the wiki isn't initialized — surface the gap and stop |
+| Target file path | Provided by caller (hook passes the file being written; manual invocation passes user-specified path) |
+| Script path | `<repo-root>/.claude/skills/support-wiki-lint/scripts/lint.mjs`. If missing, the skill isn't installed in this project — surface the gap |
+
+### Step 1: invoke the lint script
+
+```bash
+node "<repo-root>/.claude/skills/support-wiki-lint/scripts/lint.mjs" \
+  --file "<target-file-path>" \
+  --schemas "<repo-root>/aiwiki/schemas/" \
+  --root "<repo-root>"
+```
+
+Output: JSON to stdout. Exit codes: 0 = pass, 1 = lint failure, 2 = internal error.
+
+Output shape:
+```json
+{
+  "ok": false,
+  "file": "aiwiki/decisions/0042-token-storage.md",
+  "schema_id": "decision",
+  "errors": [
+    {"kind": "missing_section", "section": "## Review", "message": "Required section '## Review' not found"},
+    {"kind": "stale_citation", "citation": "src/auth.ts:42@a3f2bc1", "message": "Hash mismatch: recomputed b1c2d3e", "expected": "a3f2bc1", "actual": "b1c2d3e"}
+  ],
+  "warnings": [
+    {"kind": "soft_cap_exceeded", "lines": 247, "soft_target": [100, 200], "message": "Page is 247 lines; soft target is 100-200"}
+  ],
+  "updates": [
+    {"kind": "citation_hash_backfilled", "before": "src/auth.ts:88", "after": "src/auth.ts:88@e5f6789"}
+  ]
+}
+```
+
+### Step 2: interpret and report
+
+If `ok: true`: one line — `wiki-lint: <file> ok` (with note if `updates[]` non-empty).
+
+If `ok: false`: structured report grouped by error kind. Example:
+
+```markdown
+## wiki-lint: FAILED — aiwiki/decisions/0042-token-storage.md
+
+### Schema violations (2)
+1. Missing required section `## Review` (decision schema requires it for status: accepted)
+2. Section order: `## Decision` appears before `## Context` (schema declares strict order)
+
+### Stale citations (1)
+1. `src/auth.ts:42@a3f2bc1` — hash recomputed as `b1c2d3e`. Either:
+   - Update the citation to the new line / hash
+   - Remove the claim that depended on it
+   - Annotate the citation line with `// ack-stale: <reason>` if the staleness is acceptable for now
+```
+
+The user fixes; re-run.
+
+### Step 3: handle auto-backfills
+
+When the script reports `updates[]`, the citation hashes have already been written in-place. Surface them as informational:
+
+```
+wiki-lint: 2 citation hash(es) auto-backfilled.
+- src/auth.ts:88 → src/auth.ts:88@e5f6789
+- src/cache.ts:14 → src/cache.ts:14@b1c2d3e
+```
+
+Do not require user action for backfills — they're a courtesy, not a finding.
+
+## Schema validation rules
+
+The script reads `aiwiki/schemas/{schema_id}.md` and applies its declared rules:
+
+- `required_frontmatter` — every key must be present in target's frontmatter. Type-check (`type: integer`, `type: enum`, `type: date`) where declared. Optional fields (`optional: true`) may be absent or null.
+- `required_sections` — every section name must appear as a `## <name>` line in target.
+- `section_order: strict` — required sections must appear in the same order as declared.
+- `section_order: flexible` — required sections must all appear, but in any order.
+- `hard_cap_lines` — total file line count must not exceed.
+- `soft_target_lines: [min, max]` — total line count outside this range = warning, not error.
+- `citation_rule: required` — every code claim must have a `file:line@<sha7>` or `symbol` citation.
+- `citation_rule: required-in-<section>` — only the named section requires citations.
+- `citation_rule: required-where-claims-about-code` — heuristic mode (script only flags missing citations on lines that mention a function/class/file name without a citation).
+
+Schemas live at `aiwiki/schemas/{schema_id}.md`. If the target's `schema_id` doesn't resolve to a schema file, that's a `missing_schema` error.
+
+## Citation rules
+
+Two citation forms:
+
+- `file:line@<sha7>` — e.g. `src/auth.ts:42@a3f2bc1`. The `@<sha7>` is the first 7 chars of `sha256(content)`, where `content` is the cited line ±2 lines (5 lines total) joined with `\n` (LF). Padded with empty lines if the cited line is within 2 of file start/end.
+- `symbol` — e.g. `src/auth.ts#login`. Matches the symbol name; no hash. Less precise but tolerant of line drift.
+
+**Auto-backfill**: a `file:line` reference without `@<sha7>` is backfilled in-place on first lint. Same for hashless symbol citations (no hash to add — verified existence only).
+
+**Staleness**: a `@<sha7>` that doesn't match the recomputed hash fails lint. Resolve by:
+1. Updating the citation to point at the new location
+2. Removing the claim that depended on it
+3. Annotating with `// ack-stale: <reason>` on the citation line — the script accepts this as a deliberate mark and warns instead of failing
+
+## Common errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `missing_schema` | Target's `schema_id` doesn't have a corresponding `aiwiki/schemas/{id}.md` | Either typo'd `schema_id`, or the schema wasn't initialized — check `aiwiki/schemas/` |
+| `frontmatter_invalid` | YAML parse failed, or required field missing | Compare target's frontmatter against the schema's `required_frontmatter` block |
+| `missing_section` | Required H2 not present | Add the section (see schema's "Required sections" body for purpose); if you genuinely don't have content for it, the page may not match this schema type |
+| `section_order_violation` | Schema declares `section_order: strict`, target's sections are reordered | Reorder to match the schema |
+| `hard_cap_exceeded` | File too long | Split into multiple files (architecture/), or trim to fit (gotcha/convention) |
+| `stale_citation` | Cited code moved or content changed | Update citation, remove claim, or annotate `// ack-stale: <reason>` |
+| `missing_file_in_citation` | Cited file path no longer exists | Update or remove the claim |
+
+## Red Flags
+
+**Never:**
+- Suppress lint findings to make a page pass — fix the page or fix the schema
+- Annotate every stale citation as `ack-stale` to silence the gate (high `ack-stale` density signals architectural drift, not lint problems)
+- Modify the page outside the auto-backfill (citation hashes) — every other change is the user's
+
+**Always:**
+- Run lint after every wiki write (the hook does this; manual edits via the agent should still trigger validation)
+- Report all findings — never filter for brevity
+- Re-run after fixing — drift in one section can mask drift in another
+
+## Integration
+
+| Caller | When |
+|---|---|
+| `PostToolUse` hook on `aiwiki/**` | Synchronous validation on every wiki write |
+| `support-dream` skill | After dream produces `aiwiki/proposed/{dream_id}/`, before marking the dream complete |
+| Manual `/wiki lint <file>` | User-invoked validation |
+
+| Pairs with | For |
+|---|---|
+| `support-dream` | Dream output passes through this lint before user review |
+| Wiki schemas in `aiwiki/schemas/` | The validation rules live there; this skill enforces them |

package/skills/support-wiki-lint/scripts/lint.mjs

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+// Wiki lint (v6.0).
+// Validates a wiki page against its declared schema: required frontmatter,
+// required H2 sections, section order, line caps, and citation hash freshness.
+// Auto-backfills missing @<sha7> citation hashes in-place. Outputs JSON to
+// stdout. Exit 0 on pass, 1 on lint failure, 2 on internal error.
+//
+// Hermetic: depends only on node: built-in modules. Uses an inline minimal
+// YAML parser (handles the subset our schemas + frontmatter use; not a
+// general-purpose YAML library).
+//
+// Usage:
+//   node lint.mjs --file <path> --schemas <dir> --root <dir>
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { parseArgs } from 'node:util';
+
+// ---- Constants -------------------------------------------------------------
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+const CITATION_HASHED_RE = /([\w./@~-]+\.\w+):(\d+)@([0-9a-f]{7})\b/g;
+const CITATION_BARE_RE = /([\w./@~-]+\.\w+):(\d+)(?!@?[0-9a-f]{7})\b/g;
+const ACK_STALE_RE = /\/\/\s*ack-stale\s*:|#\s*ack-stale\s*:/;
+const SECTION_RE = /^##\s+(.+?)\s*$/gm;
+
+// ---- Minimal YAML parser ---------------------------------------------------
+// Handles only what our schema + frontmatter files use:
+//   - Top-level mapping
+//   - Scalars: string (bare or quoted), integer, float, boolean, null (~ or null)
+//   - Block sequences: `key:\n  - item\n  - item`
+//   - Block mappings: `key:\n  subkey: subvalue`
+//   - Inline mappings: `key: { sub: val, sub: val }`
+//   - Inline sequences: `key: [val, val]`
+//   - Comments: `#` to end of line (line-leading or after value)
+// Does NOT handle: anchors, aliases, multi-doc, complex keys, folded scalars.
+
+export function parseYaml(text) {
+  const rawLines = text.split('\n');
+  const lines = rawLines.map((line) => {
+    // Strip line comments — but only when # is preceded by whitespace
+    // or starts the line; not inside quoted strings or URLs (rare in our schemas).
+    const m = line.match(/^([^#]*?)(?:\s+#.*)?$/);
+    return m ? m[1].replace(/\s+$/, '') : line;
+  }).filter((line, i) => {
+    const orig = rawLines[i];
+    const t = orig.trim();
+    return t !== '' && !t.startsWith('#');
+  });
+  return parseBlock(lines, 0).value;
+}
+
+function indentOf(line) {
+  const m = line.match(/^( *)/);
+  return m ? m[1].length : 0;
+}
+
+function parseBlock(lines, startIdx, baseIndent = 0) {
+  if (startIdx >= lines.length) return { value: {}, next: startIdx };
+  const firstLine = lines[startIdx];
+  const firstIndent = indentOf(firstLine);
+
+  // Decide if block is sequence or mapping based on first line
+  if (firstLine.trim().startsWith('- ')) {
+    return parseBlockSequence(lines, startIdx, firstIndent);
+  }
+  return parseBlockMapping(lines, startIdx, firstIndent);
+}
+
+function parseBlockMapping(lines, startIdx, indent) {
+  const result = {};
+  let i = startIdx;
+  while (i < lines.length) {
+    const line = lines[i];
+    const lineIndent = indentOf(line);
+    if (lineIndent < indent) break;
+    if (lineIndent > indent) {
+      // Skip — should have been consumed by recursive call
+      i++;
+      continue;
+    }
+    const trimmed = line.trim();
+    const m = trimmed.match(/^([\w\-]+)\s*:\s*(.*)$/);
+    if (!m) {
+      i++;
+      continue;
+    }
+    const key = m[1];
+    const rest = m[2];
+
+    if (rest === '' || rest === '~' || rest === 'null') {
+      // Block-style: peek next line for child indent
+      const nextIdx = i + 1;
+      if (nextIdx >= lines.length || indentOf(lines[nextIdx]) <= indent) {
+        result[key] = null;
+        i = nextIdx;
+        continue;
+      }
+      const childIndent = indentOf(lines[nextIdx]);
+      const child = parseBlock(lines, nextIdx, childIndent);
+      result[key] = child.value;
+      i = child.next;
+    } else {
+      result[key] = parseInlineValue(rest);
+      i++;
+    }
+  }
+  return { value: result, next: i };
+}
+
+function parseBlockSequence(lines, startIdx, indent) {
+  const items = [];
+  let i = startIdx;
+  while (i < lines.length) {
+    const line = lines[i];
+    const lineIndent = indentOf(line);
+    if (lineIndent !== indent) break;
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('- ')) break;
+    items.push(parseInlineValue(trimmed.slice(2).trim()));
+    i++;
+  }
+  return { value: items, next: i };
+}
+
+function parseInlineValue(s) {
+  s = s.trim();
+  if (s === '' || s === '~' || s === 'null') return null;
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (s.startsWith('{') && s.endsWith('}')) return parseInlineMapping(s);
+  if (s.startsWith('[') && s.endsWith(']')) return parseInlineArray(s);
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  if (/^-?\d+\.\d+$/.test(s)) return parseFloat(s);
+  // ISO date — keep as string (consumers compare by string)
+  return s;
+}
+
+function parseInlineMapping(s) {
+  const inner = s.slice(1, -1).trim();
+  if (!inner) return {};
+  const result = {};
+  for (const part of splitTopLevel(inner, ',')) {
+    const m = part.trim().match(/^([\w\-]+)\s*:\s*(.*)$/);
+    if (m) {
+      result[m[1]] = parseInlineValue(m[2]);
+    }
+  }
+  return result;
+}
+
+function parseInlineArray(s) {
+  const inner = s.slice(1, -1).trim();
+  if (!inner) return [];
+  return splitTopLevel(inner, ',').map((p) => parseInlineValue(p.trim()));
+}
+
+function splitTopLevel(s, sep) {
+  const out = [];
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (!inSingle && !inDouble) {
+      if (c === '{' || c === '[') depth++;
+      else if (c === '}' || c === ']') depth--;
+      else if (c === '"') inDouble = true;
+      else if (c === "'") inSingle = true;
+      else if (c === sep && depth === 0) {
+        out.push(s.slice(start, i));
+        start = i + 1;
+      }
+    } else if (inDouble && c === '"') inDouble = false;
+    else if (inSingle && c === "'") inSingle = false;
+  }
+  out.push(s.slice(start));
+  return out;
+}
+
+// ---- Public API ------------------------------------------------------------
+
+export function lint({ file, schemasDir, root }) {
+  const errors = [];
+  const warnings = [];
+  const updates = [];
+
+  const absFile = path.resolve(root, file);
+  if (!fs.existsSync(absFile)) {
+    return { ok: false, file, errors: [{ kind: 'file_not_found', message: `File not found: ${file}` }], warnings, updates };
+  }
+  const original = fs.readFileSync(absFile, 'utf8');
+
+  const fmMatch = FRONTMATTER_RE.exec(original);
+  if (!fmMatch) {
+    return { ok: false, file, errors: [{ kind: 'frontmatter_invalid', message: 'No YAML frontmatter block found (expected `---\\n...\\n---\\n` at file start)' }], warnings, updates };
+  }
+  const [, fmText, body] = fmMatch;
+
+  let fm;
+  try {
+    fm = parseYaml(fmText);
+  } catch (err) {
+    return { ok: false, file, errors: [{ kind: 'frontmatter_invalid', message: `YAML parse error: ${err.message}` }], warnings, updates };
+  }
+  if (!fm || typeof fm !== 'object' || Array.isArray(fm)) {
+    return { ok: false, file, errors: [{ kind: 'frontmatter_invalid', message: 'Frontmatter must be a YAML mapping' }], warnings, updates };
+  }
+
+  const schemaId = fm.schema_id;
+  if (!schemaId || typeof schemaId !== 'string') {
+    return { ok: false, file, errors: [{ kind: 'frontmatter_invalid', message: '`schema_id` field missing or not a string' }], warnings, updates };
+  }
+  const schemaPath = path.join(schemasDir, `${schemaId}.md`);
+  if (!fs.existsSync(schemaPath)) {
+    return { ok: false, file, schema_id: schemaId, errors: [{ kind: 'missing_schema', message: `Schema file not found: ${path.relative(root, schemaPath)}` }], warnings, updates };
+  }
+  const schemaContent = fs.readFileSync(schemaPath, 'utf8');
+  const schemaFmMatch = FRONTMATTER_RE.exec(schemaContent);
+  if (!schemaFmMatch) {
+    return { ok: false, file, schema_id: schemaId, errors: [{ kind: 'schema_invalid', message: `Schema ${schemaId}.md has no frontmatter` }], warnings, updates };
+  }
+  let schema;
+  try {
+    schema = parseYaml(schemaFmMatch[1]);
+  } catch (err) {
+    return { ok: false, file, schema_id: schemaId, errors: [{ kind: 'schema_invalid', message: `Schema YAML parse error: ${err.message}` }], warnings, updates };
+  }
+
+  const requiredFm = schema.required_frontmatter || {};
+  for (const [key, spec] of Object.entries(requiredFm)) {
+    const optional = spec && typeof spec === 'object' && spec.optional === true;
+    const value = fm[key];
+    if (value === undefined || value === null) {
+      if (!optional) {
+        errors.push({ kind: 'frontmatter_invalid', field: key, message: `Required frontmatter field '${key}' missing` });
+      }
+      continue;
+    }
+    if (spec && typeof spec === 'object') {
+      if (spec.equals !== undefined && value !== spec.equals) {
+        errors.push({ kind: 'frontmatter_invalid', field: key, message: `Field '${key}' must equal '${spec.equals}', got '${value}'` });
+      }
+      if (spec.type === 'integer' && !Number.isInteger(value)) {
+        errors.push({ kind: 'frontmatter_invalid', field: key, message: `Field '${key}' must be integer, got ${typeof value}` });
+      }
+      if (spec.type === 'enum' && Array.isArray(spec.values) && !spec.values.includes(value)) {
+        errors.push({ kind: 'frontmatter_invalid', field: key, message: `Field '${key}' must be one of [${spec.values.join(', ')}], got '${value}'` });
+      }
+    }
+  }
+
+  const requiredSections = Array.isArray(schema.required_sections) ? schema.required_sections : [];
+  const foundSections = [];
+  let m;
+  SECTION_RE.lastIndex = 0;
+  while ((m = SECTION_RE.exec(body)) !== null) {
+    foundSections.push(`## ${m[1]}`);
+  }
+  const sectionOrder = schema.section_order || 'strict';
+  if (sectionOrder === 'strict') {
+    let cursor = 0;
+    for (const required of requiredSections) {
+      const idx = foundSections.indexOf(required, cursor);
+      if (idx === -1) {
+        if (foundSections.includes(required)) {
+          errors.push({ kind: 'section_order_violation', section: required, message: `Section '${required}' appears out of declared order` });
+        } else {
+          errors.push({ kind: 'missing_section', section: required, message: `Required section '${required}' not found` });
+        }
+      } else {
+        cursor = idx + 1;
+      }
+    }
+  } else {
+    for (const required of requiredSections) {
+      if (!foundSections.includes(required)) {
+        errors.push({ kind: 'missing_section', section: required, message: `Required section '${required}' not found` });
+      }
+    }
+  }
+
+  const totalLines = original.split('\n').length;
+  if (typeof schema.hard_cap_lines === 'number' && totalLines > schema.hard_cap_lines) {
+    errors.push({
+      kind: 'hard_cap_exceeded',
+      lines: totalLines,
+      cap: schema.hard_cap_lines,
+      message: `File is ${totalLines} lines; hard cap is ${schema.hard_cap_lines}`,
+    });
+  }
+  const soft = schema.soft_target_lines;
+  if (Array.isArray(soft) && soft.length === 2 && (totalLines < soft[0] || totalLines > soft[1])) {
+    warnings.push({
+      kind: 'soft_cap_exceeded',
+      lines: totalLines,
+      soft_target: soft,
+      message: `File is ${totalLines} lines; soft target is ${soft[0]}-${soft[1]}`,
+    });
+  }
+
+  const fileLines = original.split('\n');
+  const lineByteOffsets = computeLineOffsets(original);
+
+  const hashedCitations = collectMatches(original, CITATION_HASHED_RE);
+  for (const citation of hashedCitations) {
+    const [, citedFile, citedLineStr, citedHash] = citation.match;
+    const citedLineNum = parseInt(citedLineStr, 10);
+    const onAckStaleLine = isOnAckStaleAnnotatedLine(citation.matchOffset, lineByteOffsets, fileLines);
+
+    const citedAbs = path.resolve(root, citedFile);
+    if (!fs.existsSync(citedAbs)) {
+      errors.push({
+        kind: 'missing_file_in_citation',
+        citation: citation.text,
+        message: `Cited file not found: ${citedFile}`,
+      });
+      continue;
+    }
+    const citedContent = fs.readFileSync(citedAbs, 'utf8');
+    const recomputed = computeContextHash(citedContent, citedLineNum);
+    if (recomputed === null) {
+      errors.push({
+        kind: 'stale_citation',
+        citation: citation.text,
+        message: `Cited line ${citedLineNum} is past end of ${citedFile}`,
+      });
+      continue;
+    }
+    if (recomputed !== citedHash) {
+      const finding = {
+        kind: 'stale_citation',
+        citation: citation.text,
+        expected: citedHash,
+        actual: recomputed,
+        message: `Hash mismatch: declared ${citedHash}, recomputed ${recomputed}`,
+      };
+      if (onAckStaleLine) {
+        warnings.push({ ...finding, kind: 'stale_citation_acked' });
+      } else {
+        errors.push(finding);
+      }
+    }
+  }
+
+  const hashedRanges = hashedCitations.map((c) => [c.matchOffset, c.matchOffset + c.text.length]);
+  let modifiedBody = body;
+  let modifiedFm = fmText;
+  const bareCitations = collectMatches(original, CITATION_BARE_RE).filter((c) => !overlaps(c.matchOffset, c.matchOffset + c.text.length, hashedRanges));
+  for (const citation of bareCitations) {
+    const [, citedFile, citedLineStr] = citation.match;
+    const citedLineNum = parseInt(citedLineStr, 10);
+    const citedAbs = path.resolve(root, citedFile);
+    if (!fs.existsSync(citedAbs)) {
+      errors.push({
+        kind: 'missing_file_in_citation',
+        citation: citation.text,
+        message: `Cited file not found: ${citedFile}`,
+      });
+      continue;
+    }
+    const citedContent = fs.readFileSync(citedAbs, 'utf8');
+    const computed = computeContextHash(citedContent, citedLineNum);
+    if (computed === null) {
+      errors.push({
+        kind: 'missing_file_in_citation',
+        citation: citation.text,
+        message: `Cited line ${citedLineNum} past end of ${citedFile}`,
+      });
+      continue;
+    }
+    const replacement = `${citation.text}@${computed}`;
+    updates.push({
+      kind: 'citation_hash_backfilled',
+      before: citation.text,
+      after: replacement,
+    });
+    modifiedBody = modifiedBody.split(citation.text).join(replacement);
+    modifiedFm = modifiedFm.split(citation.text).join(replacement);
+  }
+
+  if (updates.length > 0) {
+    const newContent = `---\n${modifiedFm}\n---\n${modifiedBody}`;
+    fs.writeFileSync(absFile, newContent, 'utf8');
+  }
+
+  return {
+    ok: errors.length === 0,
+    file,
+    schema_id: schemaId,
+    errors,
+    warnings,
+    updates,
+  };
+}
+
+// ---- Helpers ---------------------------------------------------------------
+
+function computeContextHash(content, line) {
+  const lines = content.split('\n');
+  if (line < 1 || line > lines.length) return null;
+  const window = [];
+  for (let i = line - 2; i <= line + 2; i++) {
+    if (i < 1 || i > lines.length) {
+      window.push('');
+    } else {
+      window.push(lines[i - 1]);
+    }
+  }
+  const text = window.join('\n');
+  const hash = crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+  return hash.substring(0, 7);
+}
+
+function collectMatches(text, regex) {
+  const out = [];
+  regex.lastIndex = 0;
+  let m;
+  while ((m = regex.exec(text)) !== null) {
+    out.push({ match: m, text: m[0], matchOffset: m.index });
+  }
+  return out;
+}
+
+function overlaps(start, end, ranges) {
+  for (const [rs, re] of ranges) {
+    if (start < re && end > rs) return true;
+  }
+  return false;
+}
+
+function computeLineOffsets(text) {
+  const offsets = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '\n') offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+function isOnAckStaleAnnotatedLine(byteOffset, lineOffsets, fileLines) {
+  let lineIdx = 0;
+  for (let i = 0; i < lineOffsets.length; i++) {
+    if (lineOffsets[i] > byteOffset) break;
+    lineIdx = i;
+  }
+  const lineText = fileLines[lineIdx] ?? '';
+  return ACK_STALE_RE.test(lineText);
+}
+
+// ---- CLI -------------------------------------------------------------------
+
+function parseCliArgs() {
+  const { values } = parseArgs({
+    options: {
+      file: { type: 'string' },
+      schemas: { type: 'string' },
+      root: { type: 'string' },
+    },
+    strict: false,
+  });
+  if (!values.file || !values.schemas || !values.root) {
+    process.stderr.write('Usage: lint.mjs --file <path> --schemas <dir> --root <dir>\n');
+    process.exit(2);
+  }
+  return values;
+}
+
+function main() {
+  const { file, schemas, root } = parseCliArgs();
+  let result;
+  try {
+    result = lint({ file, schemasDir: schemas, root });
+  } catch (err) {
+    process.stdout.write(JSON.stringify({ ok: false, errors: [{ kind: 'internal_error', message: String(err?.message ?? err) }] }, null, 2) + '\n');
+    process.exit(2);
+  }
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  process.exit(result.ok ? 0 : 1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1].endsWith('lint.mjs')) {
+  main();
+}