@isonimus/stele 0.1.2 → 0.3.0

package/scripts/lint-docs.mjs

@@ -10,14 +10,44 @@
 //
 // Exit 1 if any error-severity rule fails. Warnings never fail the build.
 
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { readFileSync, readdirSync, existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, basename, dirname, relative } from 'node:path';
 
 const STATUSES = ['accepted', 'proposed', 'superseded', 'amended'];
 const TYPES = ['architecture', 'slice', 'batch'];
 const REQUIRED = ['id', 'title', 'type', 'status', 'date'];
 const DOC_DIRS = ['adr', 'slices'];
 
+// Prose that is read as instruction rather than as a record (ADR-0020). `CLAUDE.md` is
+// loaded at the start of every session and the command files are the assistant's own
+// procedures, so a citation rotting in either misroutes work silently — the corpus itself
+// stays green because rules 8 and 9 never open these files. Directories are scanned one
+// level deep; anything else here is a plain file path.
+const PROSE_FILES = ['CLAUDE.md', 'README.md'];
+const PROSE_DIRS = ['docs', '.claude/commands'];
+
+/**
+ * Every path this linter reads, relative to the repo root — the hook's archive list
+ * (ADR-0018) in machine-readable form.
+ *
+ * The hook materialises the staged tree and copies only what the checks read, so a rule
+ * reading outside this set runs against a file that was never extracted. That happened:
+ * rules 14 and 15 shipped reading four paths the hook did not copy, and were dead there
+ * for a release while passing in CI. `test/read-set.test.mjs` holds the two lists equal.
+ */
+export const READ_SCOPE = [
+  ...DOC_DIRS, 'LEDGER.md', ...PROSE_FILES, ...PROSE_DIRS, 'scripts', 'package.json',
+];
+
+/** Whether a root-relative path lies inside the checked scope. Outside it, the hook and a
+ *  working-tree run would disagree, and a check that depends on where it runs is worse
+ *  than no check. */
+function inReadScope(rootRelative) {
+  if (rootRelative.startsWith('..')) return false;
+  return READ_SCOPE.some((entry) => rootRelative === entry || rootRelative.startsWith(`${entry}/`));
+}
+
 // The date the required-slice-section rules (R12/R13) shipped (ADR-0004, ADR-0011). A
 // slice dated before this predates the rules and only warns; one dated on or after must
 // comply. Without the split, a repo adopting this linter would go red on its whole legacy
@@ -34,16 +64,89 @@ const normId = (v) => String(v).trim().padStart(4, '0');
 
 const isId = (v) => /^\d{1,4}$/.test(String(v).trim());
 
+/**
+ * ISO 8601 `YYYY-MM-DD`, and a day that exists — `2026-02-31` parses but round-trips wrong.
+ *
+ * `date` is not decoration: R12/R13 pick their severity by string-comparing it against
+ * SLICE_SECTIONS_SINCE, so anything sorting above `2026-07-22` grades as current and
+ * anything below grades as legacy. Unvalidated, `date: sometime last tuesday` graded as
+ * *current* purely because 's' > '2', and a copy-pasted earlier date graded as legacy —
+ * shipping a slice with no Definition of Done on a green build. ADR-0002 already specifies
+ * ISO 8601; this is that specification made executable.
+ */
+function isCalendarDate(v) {
+  const text = String(v).trim();
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(text)) return false;
+  // `2026-02-30` parses and normalises to March, so the round-trip catches it. `2026-00-01`
+  // does not parse at all, and `toISOString()` on an invalid Date throws — checked first,
+  // because a linter that dies with a stack trace on a malformed date reports nothing about
+  // the other documents and breaks `--update`'s report (ADR-0021).
+  const parsed = new Date(`${text}T00:00:00Z`);
+  if (Number.isNaN(parsed.getTime())) return false;
+  return parsed.toISOString().startsWith(text);
+}
+
 // Citations, bare or qualified (ADR-0009). A leading `<repo>:` says the decision lives in
 // another repo's corpus, which this linter cannot open and so must skip. The colon has to
 // be adjacent, leaving an ordinary sentence ending in a colon ("see also: ADR-0004")
 // resolving locally as before.
 const CITATION = /(?:([A-Za-z][\w.-]*):)?ADR[-\s](\d{1,4})/g;
 
-/** Ids cited in `text` that this repo is expected to own — cross-repo refs skipped. */
-function* localCitations(text) {
-  for (const [, repo, id] of text.matchAll(CITATION)) {
-    if (repo === undefined) yield normId(id);
+/**
+ * `text` with link destinations and URLs removed, so only prose is scanned for citations.
+ *
+ * A URL path can contain an `ADR-1234`-shaped run that cites nothing —
+ * `https://example.com/docs/ADR-9999`, or a ticket link. Rules 8 and 14 are error severity,
+ * so one coincidence blocks a correct commit, and the advice their message gives is
+ * unusable: the `<repo>:` qualifier cannot be written inside a URL. Link *text* is kept,
+ * because `[ADR-0020](adr/0020-….md)` is a citation and rule 15 checks the target
+ * separately.
+ */
+const citableText = (text) =>
+  text.replace(/\]\([^)]*\)/g, ']()').replace(/\S*:\/\/\S*/g, '');
+
+/**
+ * Ids cited in `text` that this repo is expected to own — cross-repo refs skipped.
+ *
+ * A qualifier naming *this* repo resolves locally (ADR-0020). Text that is vendored into
+ * other repos must qualify its citations, or a bare `ADR-0005` copied into gamatar reads
+ * as gamatar's ADR-0005; but qualifying it would also put it permanently beyond checking,
+ * since ADR-0009 skips every qualified reference. Recognising our own name is what keeps
+ * `stele:ADR-0005` verified in the one corpus that can verify it.
+ */
+function* localCitations(text, selfRepo = null) {
+  for (const [, repo, id] of citableText(text).matchAll(CITATION)) {
+    if (repo === undefined || (selfRepo !== null && repo === selfRepo)) yield normId(id);
+  }
+}
+
+/** This repo's own name for citation purposes: the unscoped half of package.json `name`.
+ *  Null when there is no readable name — rule 11 owns malformed package.json, and without
+ *  a name there is simply no self-qualifier to recognise. */
+function repoName(root) {
+  const path = join(root, 'package.json');
+  if (!existsSync(path)) return null;
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+  const name = typeof pkg.name === 'string' ? pkg.name : '';
+  const unscoped = name.startsWith('@') ? name.slice(name.indexOf('/') + 1) : name;
+  return unscoped === '' ? null : unscoped;
+}
+
+// Inline markdown links, with the optional title form `[x](path "title")`.
+const LINK = /\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g;
+
+/** Link targets in `line` that name a file in this repo. External URLs, mail links,
+ *  in-page anchors and absolute paths are all outside what a file check can decide. */
+function* relativeLinks(line) {
+  for (const [, target] of line.matchAll(LINK)) {
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|\/|#)/i.test(target)) continue;
+    const path = target.split('#')[0].split('?')[0];
+    if (path !== '') yield path;
   }
 }
 
@@ -127,16 +230,53 @@ export function loadDocs(root) {
   return docs;
 }
 
+/** The prose files present under `root`, as { path, text }. Missing ones are simply
+ *  absent — not every repo has docs/ or slash commands. */
+function loadProse(root) {
+  const paths = PROSE_FILES.map((f) => join(root, f));
+  for (const dir of PROSE_DIRS) {
+    const full = join(root, dir);
+    if (!existsSync(full)) continue;
+    paths.push(...readdirSync(full).sort().filter((f) => f.endsWith('.md')).map((f) => join(full, f)));
+  }
+  return paths.filter(existsSync).map((path) => ({ path, text: readFileSync(path, 'utf8') }));
+}
+
 // --- section helpers --------------------------------------------------------
 // Slice rules (R12/R13) assert the presence and shape of `## Sections` in the body prose.
 // This is the only place the linter reads body text structurally; ADR-0002 keeps
 // frontmatter the machine-readable surface, and a markdown heading is not frontmatter.
 
+/**
+ * Body lines with fenced code blocks blanked out, positions preserved.
+ *
+ * A `## Verification` inside a fence is a *quotation* of the rule, not compliance with it.
+ * Reproduced 2026-07-27: a slice whose only two required sections sat in a ```markdown
+ * sample — exactly what a document explaining the slice template contains — lints clean,
+ * which is a false green on the two rules that define "done".
+ */
+function withoutFences(body) {
+  const fence = /^\s*(```|~~~)/;
+  let open = null;
+  return (body ?? '').split('\n').map((line) => {
+    const marker = line.match(fence);
+    if (marker && open === null) {
+      open = marker[1];
+      return '';
+    }
+    if (marker && line.trim().startsWith(open)) {
+      open = null;
+      return '';
+    }
+    return open === null ? line : '';
+  });
+}
+
 /** The text under a `## Heading`, up to the next `#`/`##` heading or end of body.
  *  Returns null when the heading is absent — distinct from a present-but-empty section. */
 function sectionText(body, name) {
   const heading = new RegExp(`^##\\s+${name}\\s*$`, 'i');
-  const lines = (body ?? '').split('\n');
+  const lines = withoutFences(body);
   const start = lines.findIndex((l) => heading.test(l.trim()));
   if (start === -1) return null;
   const rest = lines.slice(start + 1);
@@ -201,6 +341,9 @@ const rules = {
           report('error', d.path, `R1 missing required field "${field}"`);
         }
       }
+      if (d.data.date !== undefined && !isCalendarDate(d.data.date)) {
+        report('error', d.path, `R1 date "${d.data.date}" is not a calendar date in YYYY-MM-DD form`);
+      }
     }
   },
 
@@ -261,6 +404,14 @@ const rules = {
       const supersededBy = listOf(d, 'superseded_by');
       const supersedes = listOf(d, 'supersedes');
 
+      // R4 — a document cannot supersede itself. Self-reference satisfies every other
+      // check in this rule vacuously: the bidirectionality test finds the id in its own
+      // list, R6 sees a superseded status with a non-empty superseded_by, and R7 sees a
+      // target that is not "accepted". The whole graph agrees, about nothing.
+      if (supersedes.includes(id) || supersededBy.includes(id)) {
+        report('error', d.path, `R4 ADR ${id} supersedes itself — a decision is replaced by a later one, never by itself`);
+      }
+
       // R5 — dangling references. Legacy 0051 and 0061 claimed supersession with no
       // resolvable target at all.
       for (const key of ['supersedes', 'superseded_by']) {
@@ -315,8 +466,9 @@ const rules = {
     const ids = new Set(docs.filter((d) => d.ok && d.data.id !== undefined).map((d) => normId(d.data.id)));
 
     const text = readFileSync(path, 'utf8');
+    const self = repoName(root);
     text.split('\n').forEach((line, i) => {
-      for (const id of localCitations(line)) {
+      for (const id of localCitations(line, self)) {
         if (!ids.has(id)) {
           report('error', path, `R8 line ${i + 1} cites ADR ${id}, which does not exist. Another repo's decision is cited as \`<repo>:ADR-${id}\` (ADR-0009).`);
         }
@@ -324,6 +476,41 @@ const rules = {
     });
   },
 
+  // R14/R15 — the prose that is read as instruction (ADR-0020). Rules 8 and 9 open
+  // `LEDGER.md` and the corpus and nothing else, so `CLAUDE.md`, `README.md`, `docs/` and
+  // the slash commands were never checked at all. That is not hypothetical: gamatar's
+  // vendored `/remember` said "the exact failure ADR-0005 exists to prevent", and
+  // gamatar's ADR-0005 is a superseded decision about canvas face textures.
+  //
+  // Error, not a warning like R9: measured across boxel's prose (43 bare references) and
+  // gamatar's, every reference that is meant to be local resolves, so the severity that
+  // forced R9 to warn — legacy volume — is absent here.
+  //
+  // The two run together because they share the file set. R15 checks relative link
+  // targets, and only here: a broken link inside an immutable document cannot be fixed
+  // without the rewrite ADR-0019 forbids, so it is not something to fail a build on.
+  prose(docs, root, report) {
+    const ids = new Set(docs.filter((d) => d.ok && d.data.id !== undefined).map((d) => normId(d.data.id)));
+    const self = repoName(root);
+
+    for (const { path, text } of loadProse(root)) {
+      text.split('\n').forEach((line, i) => {
+        for (const id of localCitations(line, self)) {
+          if (!ids.has(id)) {
+            report('error', path, `R14 line ${i + 1} cites ADR ${id}, which does not exist. Another repo's decision is cited as \`<repo>:ADR-${id}\` (ADR-0009).`);
+          }
+        }
+        for (const target of relativeLinks(line)) {
+          const resolved = relative(root, join(dirname(path), target));
+          if (!inReadScope(resolved)) continue;
+          if (!existsSync(join(root, resolved))) {
+            report('error', path, `R15 line ${i + 1} links to ${target}, which does not exist`);
+          }
+        }
+      });
+    }
+  },
+
   // R11 — every verify script is wired into package.json (ADR-0004). The harness's
   // load-bearing half: an unwired `*-verify.mjs` ran once on the day it was written and
   // never again — ADR-0004 Finding 2 found eleven of twelve boxel scripts in exactly that
@@ -400,12 +587,13 @@ const rules = {
   // Since ADR-0009 a bare reference means unambiguously "in this repo" — the other-repo
   // case has its own syntax — so the remaining obstacle to erroring here is boxel's
   // legacy volume alone, not the mechanism.
-  proseRefs(docs, _root, report) {
+  proseRefs(docs, root, report) {
     const ids = new Set(docs.filter((d) => d.ok && d.data.id !== undefined).map((d) => normId(d.data.id)));
+    const self = repoName(root);
     for (const d of docs) {
       if (!d.ok || !d.body) continue;
       const unresolved = new Set();
-      for (const id of localCitations(d.body)) {
+      for (const id of localCitations(d.body, self)) {
         if (!ids.has(id)) unresolved.add(id);
       }
       for (const ref of [...unresolved].sort()) {
@@ -458,6 +646,8 @@ function main(argv) {
   return errors > 0 ? 1 : 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+// realpath, not a string compare on argv[1]: invoked through a bin symlink the naive form
+// silently does nothing, which is how `npx stele` shipped as a no-op (ADR-0015).
+if (realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
   process.exit(main(process.argv.slice(2)));
 }

package/templates/CLAUDE.md

@@ -36,13 +36,27 @@ Changing our minds means writing a **new** ADR that supersedes the old one, neve
 it. The superseding note must say *why the old reasoning was wrong* — that record is the
 most valuable thing this workflow produces, and an in-place edit destroys it.
 
+A committed document's body may **gain** lines — an appended `## Amendment — <date>: …`, or a
+correction marker placed at the claim it corrects — and may never lose or rewrite one. The
+hook enforces this (stele:ADR-0019); frontmatter is exempt, because status and supersession
+fields are how a record announces it was superseded.
+
 This is also how a justified rule-violation gets recorded. `~/.claude/CLAUDE.md` §2 says a
 justified violation is written down as a decision rather than taken as a silent exception;
 in this repo, that decision is a new or superseding ADR.
 
 ## 2. Enforcement — invariants are executable
 
-`node scripts/lint-docs.mjs` runs from a pre-commit hook and in CI.
+`node scripts/lint-docs.mjs` runs from a pre-commit hook and in CI. The hook checks the
+**commit**, not the working tree, so a fix you forgot to stage cannot green a red commit
+(stele:ADR-0018); alongside the linter it verifies that `adr/INDEX.md` matches the corpus and
+that immutable bodies have only gained lines (stele:ADR-0019).
+
+A citation is bare (`ADR-NNNN`) only when it means *this* repo, and qualified
+(`<repo>:ADR-NNNN`) otherwise (stele:ADR-0009). The linter resolves citations in `LEDGER.md`,
+in the corpus, and in the prose that is read as instruction — this file, `README.md`,
+`docs/`, `.claude/commands/` — so a citation that rots there fails the build rather than
+quietly misrouting the next session (stele:ADR-0020).
 
 A rule enforced by memory is a rule that holds until the first busy afternoon. If a
 convention matters, it gets a rule; if it genuinely can't be checked, say so out loud
@@ -76,7 +90,7 @@ are exempt: a probe answers its question once and the number lands in an ADR.
 
 Every slice carries two required sections, both rule-checked: `## Verification` names the
 proof (R12), and `## Definition of Done` states the acceptance criteria as Given/When/Then
-scenarios written before the code (R13, ADR-0011). Each scenario names its proof in
+scenarios written before the code (R13, stele:ADR-0011). Each scenario names its proof in
 `## Verification`; the linter checks the sections exist and that the Definition of Done
 holds a full triad — it cannot check that a scenario is *right*, which is what `/wrap-up`
 is for.