@isonimus/stele 0.2.0 → 0.4.1

package/scripts/init-method.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Installs the method kit into a git repo (ADR-0006). Dry-run by default.
 //
-//   node scripts/init-method.mjs <repo-root> [--apply] [--check] [--update]
+//   node scripts/init-method.mjs <repo-root> [--apply] [--check] [--update [--force]]
 //
 // The load-bearing rule lives in installHook(): the pre-commit hook is linked ONLY
 // against a corpus the linter calls clean. An unwired scripts/*-verify.mjs is an R11
@@ -12,7 +12,8 @@
 // documents it would report "0 document(s) — ok" (the reason rule 10 exists), certifying
 // an install that checks nothing.
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, lstatSync, readlinkSync, symlinkSync, unlinkSync, readdirSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, lstatSync, statSync, accessSync, constants as fsConstants, readlinkSync, symlinkSync, unlinkSync, readdirSync, realpathSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -34,17 +35,49 @@ const VENDORED = [
 
 const COMMANDS_DIR = '.claude/commands';
 
+/** Prose vendored alongside the commands and under the same rules: adaptable, kept on
+ *  update unless untouched. The quality bar is the standard a slice's Definition of Done
+ *  is measured against, so it has to reach the repo the Definition of Done lives in
+ *  (ADR-0024). A Python repo cutting the rule about `any` is use, not drift. */
+export const ADAPTABLE_DOCS = ['docs/quality-bar.md'];
+
 /**
- * The slash commands, vendored too (ADR-0007) — same target path as toolkit path.
+ * Everything vendored under the adaptable rules (ADR-0023) — same target path as toolkit
+ * path, which is what lets one classification serve both `--update` and `--check`.
  *
- * Read from disk rather than listed, so a new command reaches installed repos without
- * anyone remembering to extend an array here.
+ * Commands are read from disk rather than listed, so a new command reaches installed repos
+ * without anyone remembering to extend an array here.
  */
-const commandFiles = (toolkit) =>
-  readdirSync(join(toolkit, COMMANDS_DIR))
+const adaptableFiles = (toolkit) => [
+  ...readdirSync(join(toolkit, COMMANDS_DIR))
     .filter((name) => name.endsWith('.md'))
     .sort()
-    .map((name) => `${COMMANDS_DIR}/${name}`);
+    .map((name) => `${COMMANDS_DIR}/${name}`),
+  ...ADAPTABLE_DOCS,
+];
+
+/**
+ * What the toolkit last handed this repo: vendored adaptable path → SHA-256 of the content
+ * written there (ADR-0023).
+ *
+ * The JSON key is still `commands`, though the set now includes `docs/quality-bar.md`
+ * (ADR-0024). Renaming it would mean bumping PROVENANCE_VERSION, and an unrecognised
+ * version is deliberately read as *no record at all* — so a cosmetic rename would
+ * reclassify every command in every installed repo as `unknown` on the next run. The
+ * inaccuracy is cheaper than that, and this comment is the fix.
+ *
+ * Without it an update sees two states where three are needed — a stale copy of an older
+ * release and a deliberate local adaptation are the same observation, "differs from the
+ * toolkit", and the only safe reading of that is the destructive one. Committed, not
+ * ignored: a fresh clone missing it classifies every command as unreconciled.
+ */
+const PROVENANCE = '.claude/.stele-vendored.json';
+
+/** Bumped only when the record's shape changes; an unrecognised version is treated as no
+ *  record at all, which keeps every command rather than overwriting it. */
+const PROVENANCE_VERSION = 1;
+
+const digest = (text) => createHash('sha256').update(text).digest('hex');
 
 /** Scaffolded once and never overwritten: target path ← template path. */
 const SCAFFOLD = [
@@ -109,6 +142,76 @@ function isSymlink(path) {
   }
 }
 
+/**
+ * Managed paths in the target that exist but are not a file this tool can read and write.
+ *
+ * `existsSync` answers the wrong question twice, and every managed path lives in a repo we
+ * do not control. It is **true** for a directory, so the read crashes with an `EISDIR` that
+ * names `readFileSync` rather than the offending path; it is **false** for a symlink that
+ * does not resolve, so the path reads as *absent* — `--check` calls it missing and `--apply`
+ * writes straight through the link. Refusing by name is the fix, for the reason the hook
+ * install refuses rather than warns (ADR-0006): a stack trace tells the operator nothing
+ * about which file is wrong.
+ *
+ * `.git/hooks/pre-commit` is deliberately a symlink and is judged by installHook(), not here.
+ */
+function unusablePaths({ target, toolkit }) {
+  const managed = [
+    ...SCAFFOLD.map(([dest]) => dest),
+    ...VENDORED.map(([dest]) => dest),
+    ...adaptableFiles(toolkit),
+    join('adr', 'INDEX.md'),
+    PROVENANCE,
+    FRAMEWORK_CONFIG,
+  ];
+
+  return managed.flatMap((dest) => {
+    const path = join(target, dest);
+    let link;
+    try {
+      link = lstatSync(path, { throwIfNoEntry: false });
+    } catch (error) {
+      // throwIfNoEntry suppresses ENOENT and nothing else. ENOTDIR here means an ancestor
+      // exists as a file, so nothing at this path can be read, written or created — and
+      // pointing at the leaf would send the operator to the wrong file.
+      return [{ path, kind: error.code === 'ENOTDIR'
+        ? 'unreachable — a parent of it exists as a file rather than a directory'
+        : `cannot be inspected (${error.code})` }];
+    }
+    if (link === undefined) return []; // absent: the ordinary case
+    if (link.isFile()) return whenUnreadable(path);
+    if (!link.isSymbolicLink()) {
+      return [{ path, kind: link.isDirectory() ? 'a directory' : 'not a regular file' }];
+    }
+    // A symlink to a real file reads and writes fine, so it stays supported. statSync
+    // throws ELOOP on a cycle, which throwIfNoEntry does not suppress — the code it
+    // carries goes into the report rather than being discarded.
+    try {
+      if (statSync(path).isFile()) return whenUnreadable(path);
+      return [{ path, kind: `a symlink to ${readlinkSync(path)}, which is not a file` }];
+    } catch (error) {
+      return [{ path, kind: `a symlink to ${readlinkSync(path)} that cannot be resolved (${error.code})` }];
+    }
+  });
+}
+
+/**
+ * A file whose type is fine but whose permissions are not: `lstat` succeeds on a `chmod 000`
+ * file, and the read that follows throws a bare EACCES.
+ *
+ * Only readability is checked. Every managed path that exists is read unconditionally, while
+ * writes are conditional — so refusing on write permission too would reject a read-only
+ * vendored file that already matches the toolkit and needs no write at all.
+ */
+function whenUnreadable(path) {
+  try {
+    accessSync(path, fsConstants.R_OK);
+    return [];
+  } catch (error) {
+    return [{ path, kind: `unreadable (${error.code})` }];
+  }
+}
+
 /** The linter's error findings for a repo.
  *  Always the repo ROOT: pointed at a subdirectory holding no documents the linter
  *  reports "0 document(s) — ok", certifying an install that checks nothing (rule 10). */
@@ -133,38 +236,123 @@ function vendor({ target, toolkit, apply, report }) {
     }
     mkdirSync(dirname(to), { recursive: true });
     copyFileSync(from, to);
-    report('wrote', to, `${verb}d from toolkit`);
+    report('wrote', to, `${verb === 'copy' ? 'copied' : 'updated'} from toolkit`);
   }
 }
 
 /**
- * Slash commands, which are prose and therefore adaptable (ADR-0007).
+ * The recorded digests, or `{}` when there is no usable record.
+ *
+ * A record we cannot read is reported and then treated as absent. That is the safe
+ * direction and not a silenced error: every command classifies as `unknown`, so nothing is
+ * overwritten and the operator sees why (ADR-0023).
+ */
+export function readProvenance(target, report) {
+  const path = join(target, PROVENANCE);
+  if (!existsSync(path)) return {};
+
+  let parsed;
+  try {
+    parsed = JSON.parse(read(path));
+  } catch (error) {
+    report('problem', path, `unreadable (${error.message}) — treating every command as unreconciled, so none will be overwritten. Delete it to start a fresh record.`);
+    return {};
+  }
+
+  const commands = parsed?.commands;
+  if (parsed?.version !== PROVENANCE_VERSION || typeof commands !== 'object' || commands === null) {
+    report('problem', path, `unrecognised shape (expected version ${PROVENANCE_VERSION}) — treating every command as unreconciled, so none will be overwritten.`);
+    return {};
+  }
+  return commands;
+}
+
+function writeProvenance(target, commands) {
+  const path = join(target, PROVENANCE);
+  const ordered = Object.fromEntries(Object.entries(commands).sort(([a], [b]) => a.localeCompare(b)));
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ version: PROVENANCE_VERSION, commands: ordered }, null, 2)}\n`);
+}
+
+/**
+ * What an installed command is, relative to the toolkit and to what we last handed over.
+ *
+ * `stale` and `adapted` are the two states the old boolean could not tell apart, and the
+ * whole of ADR-0023 is the ability to name them separately. `unknown` is a differing file
+ * with no record — an install predating the record — which is kept, because assuming
+ * permission to overwrite is exactly the incident.
+ *
+ * @returns {'absent'|'current'|'stale'|'adapted'|'unknown'}
+ */
+export function classifyVendored({ targetText, toolkitText, recordedDigest }) {
+  if (targetText === null) return 'absent';
+  if (targetText === toolkitText) return 'current';
+  if (recordedDigest === undefined) return 'unknown';
+  return digest(targetText) === recordedDigest ? 'stale' : 'adapted';
+}
+
+const KEPT_REASON = {
+  stale: 'behind the toolkit but unmodified here — `--update` takes the new version',
+  adapted: 'adapted locally — kept; `--update --force` discards the adaptation',
+  unknown: 'differs from the toolkit and predates the vendoring record, so it cannot be told from a local adaptation — kept. Reconcile it once by hand, or `--update --force` to take the toolkit version',
+};
+
+/**
+ * Slash commands and the quality bar — prose, and therefore adaptable (ADR-0023, ADR-0024).
  *
  * Copy-if-absent, unlike vendor(): a repo that has tailored `/slice` to its own workflow
- * must not have that overwritten by an install. `--update` is the explicit way to take
- * the toolkit's version back.
+ * must not have that overwritten. `--update` additionally refreshes anything the repo has
+ * not touched, and only `--force` discards an adaptation (ADR-0023).
  */
-function vendorCommands({ target, toolkit, apply, force, report }) {
-  for (const path of commandFiles(toolkit)) {
+function vendorAdaptable({ target, toolkit, apply, update, force, report }) {
+  const recorded = readProvenance(target, report);
+  const learned = { ...recorded };
+  let changed = false;
+
+  for (const path of adaptableFiles(toolkit)) {
     const to = join(target, path);
-    const from = join(toolkit, path);
-    if (matches(to, from)) {
+    const toolkitText = read(join(toolkit, path));
+    const state = classifyVendored({
+      targetText: existsSync(to) ? read(to) : null,
+      toolkitText,
+      recordedDigest: recorded[path],
+    });
+
+    // An up-to-date command is how an install predating the record acquires one: its bytes
+    // ARE the toolkit's, so the digest is known without having written anything.
+    if (state === 'current') {
       report('ok', to, 'current');
+      if (recorded[path] !== digest(toolkitText)) {
+        learned[path] = digest(toolkitText);
+        changed = true;
+      }
       continue;
     }
-    if (existsSync(to) && !force) {
-      report('keep', to, 'differs from the toolkit — left as it is; `--update` takes the toolkit version');
+
+    const takeover = state === 'absent' || (update && (state === 'stale' || force));
+    if (!takeover) {
+      report('keep', to, KEPT_REASON[state]);
       continue;
     }
-    const verb = existsSync(to) ? 'overwrite' : 'copy';
+
+    const verb = state === 'absent' ? 'copy' : 'overwrite';
     if (!apply) {
       report('would', to, `${verb} from toolkit`);
       continue;
     }
     mkdirSync(dirname(to), { recursive: true });
-    copyFileSync(from, to);
+    writeFileSync(to, toolkitText);
+    learned[path] = digest(toolkitText);
+    changed = true;
     report('wrote', to, `${verb === 'copy' ? 'copied' : 'overwritten'} from toolkit`);
   }
+
+  // Never on a dry run: the record describes what is on disk, and writing it while writing
+  // nothing else would claim we handed over files we did not.
+  if (apply && changed) {
+    writeProvenance(target, learned);
+    report('wrote', join(target, PROVENANCE), 'recorded what was vendored, so a later --update can tell a stale command from an adapted one');
+  }
 }
 
 function scaffold({ target, toolkit, apply, report }) {
@@ -302,12 +490,22 @@ function check({ target, toolkit, report }) {
     else report('ok', to, 'current');
   }
 
-  // Commands are prose a repo may legitimately adapt, so their drift is informational
-  // (ADR-0007) — reported so it is visible, never counted against a clean check.
-  for (const path of commandFiles(toolkit)) {
+  // An *adaptation* is prose a repo may legitimately own, so it stays informational. A
+  // command merely behind and unmodified is a repo missing a fix, which is a problem — the
+  // record is what lets --check tell those two apart at all (ADR-0023, superseding ADR-0007,
+  // under which no command difference could be counted and so a shipped defect in one was
+  // invisible in every installed repo).
+  const recorded = readProvenance(target, report);
+  for (const path of adaptableFiles(toolkit)) {
     const to = join(target, path);
-    if (!existsSync(to)) report('missing', to, 'not installed — run /init-method --apply');
-    else if (!matches(to, join(toolkit, path))) report('local', to, 'differs from the toolkit — kept; `--update` takes the toolkit version');
+    const state = classifyVendored({
+      targetText: existsSync(to) ? read(to) : null,
+      toolkitText: read(join(toolkit, path)),
+      recordedDigest: recorded[path],
+    });
+    if (state === 'absent') report('missing', to, 'not installed — run /init-method --apply');
+    else if (state === 'stale') report('problem', to, 'behind the toolkit and unmodified here — run /init-method --update');
+    else if (state !== 'current') report('local', to, KEPT_REASON[state]);
     else report('ok', to, 'current');
   }
 
@@ -340,9 +538,10 @@ function check({ target, toolkit, report }) {
  * @param {string} [options.toolkit] this kit's root (overridable for tests)
  * @param {'install'|'check'|'update'} [options.mode]
  * @param {boolean} [options.apply]  false = dry run, the default
+ * @param {boolean} [options.force]  update only: discard local command adaptations too
  * @returns {{actions: Array<{status: string, path: string, message: string}>, problems: number}}
  */
-export function initMethod({ target, toolkit = TOOLKIT, mode = 'install', apply = false }) {
+export function initMethod({ target, toolkit = TOOLKIT, mode = 'install', apply = false, force = false }) {
   const actions = [];
   const report = (status, path, message) => actions.push({ status, path, message });
 
@@ -351,16 +550,27 @@ export function initMethod({ target, toolkit = TOOLKIT, mode = 'install', apply
     return { actions, problems: 1 };
   }
 
+  // Before anything reads or writes, and in every mode: a partial install is worse than no
+  // install, and --check cannot judge a state it would crash on. Every offending path is
+  // named, not just the first, so one re-run is enough to clear them.
+  const unusable = unusablePaths({ target, toolkit });
+  if (unusable.length > 0) {
+    for (const { path, kind } of unusable) {
+      report('problem', path, `${kind} — this tool reads and writes it as a file. Move or remove it, then re-run.`);
+    }
+    return { actions, problems: unusable.length };
+  }
+
   if (mode === 'check') {
     check({ target, toolkit, report });
   } else if (mode === 'update') {
     vendor({ target, toolkit, apply, report });
-    vendorCommands({ target, toolkit, apply, force: true, report });
+    vendorAdaptable({ target, toolkit, apply, update: true, force, report });
     if (apply) lintAfterUpdate({ target, report });
   } else {
     scaffold({ target, toolkit, apply, report });
     vendor({ target, toolkit, apply, report });
-    vendorCommands({ target, toolkit, apply, force: false, report });
+    vendorAdaptable({ target, toolkit, apply, update: false, force: false, report });
     buildIndex({ target, apply, report });
     installHook({ target, apply, report });
   }
@@ -374,8 +584,14 @@ function main(argv) {
   const target = positional[0] ?? process.cwd();
   const mode = flags.has('--check') ? 'check' : flags.has('--update') ? 'update' : 'install';
   const apply = flags.has('--apply');
+  const force = flags.has('--force');
+
+  if (force && mode !== 'update') {
+    console.error('--force only means anything with --update: it discards local command adaptations.');
+    return 1;
+  }
 
-  const { actions, problems } = initMethod({ target, mode, apply });
+  const { actions, problems } = initMethod({ target, mode, apply, force });
 
   console.log(`\n${target} — /init-method ${mode}${apply || mode === 'check' ? '' : ' (dry run)'}`);
   for (const a of actions) {

package/scripts/lint-docs.mjs

@@ -77,7 +77,13 @@ const isId = (v) => /^\d{1,4}$/.test(String(v).trim());
 function isCalendarDate(v) {
   const text = String(v).trim();
   if (!/^\d{4}-\d{2}-\d{2}$/.test(text)) return false;
-  return new Date(`${text}T00:00:00Z`).toISOString().startsWith(text);
+  // `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
@@ -86,6 +92,19 @@ function isCalendarDate(v) {
 // resolving locally as before.
 const CITATION = /(?:([A-Za-z][\w.-]*):)?ADR[-\s](\d{1,4})/g;
 
+/**
+ * `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.
  *
@@ -96,7 +115,7 @@ const CITATION = /(?:([A-Za-z][\w.-]*):)?ADR[-\s](\d{1,4})/g;
  * `stele:ADR-0005` verified in the one corpus that can verify it.
  */
 function* localCitations(text, selfRepo = null) {
-  for (const [, repo, id] of text.matchAll(CITATION)) {
+  for (const [, repo, id] of citableText(text).matchAll(CITATION)) {
     if (repo === undefined || (selfRepo !== null && repo === selfRepo)) yield normId(id);
   }
 }

package/templates/CLAUDE.md

@@ -4,10 +4,14 @@
 
 Stack: {{STACK}}
 
-General working practices — quality bar, commit hygiene, delegation, correction, language
-— live in `~/.claude/CLAUDE.md` and apply here without being restated. This file carries
-only what is specific to **this** repo. Restating a global rule here would create a second
-copy with no sync path, which is the failure stele:ADR-0005 exists to prevent.
+General working practices — quality bar, testing standard, commit hygiene, delegation,
+correction, language — live in [`docs/quality-bar.md`](docs/quality-bar.md) and apply here
+without being restated. It ships with the method and is vendored into this repo, so it is
+yours to adapt; an update keeps what you changed (stele:ADR-0024).
+
+This file carries only what is specific to **this** repo. Restating a rule from the bar here
+would create a second copy with no sync path, which is the failure stele:ADR-0005 exists to
+prevent.
 
 ## 1. Document taxonomy — four kinds