@isonimus/stele 0.1.2 → 0.3.0

package/scripts/check-mutants.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+// Mutation check over the linter's pure predicates (ADR-0004's probe idea, made standing).
+//
+//   node scripts/check-mutants.mjs [--quiet]
+//
+// Each mutant is a small, deliberate behaviour change. The suite is run against it: a
+// mutant that dies proves a test was watching, one that SURVIVES proves the behaviour is
+// unpinned and a refactor could reverse it in silence. Exit 1 if any non-exempt mutant
+// survives.
+//
+// Scope is deliberately narrow: the total, IO-free predicates in lint-docs.mjs and
+// check-immutable.mjs. Every subtle-logic defect this repo has had lived in that class.
+// init-method.mjs is excluded — its behaviour is pinned by real-filesystem fixtures, where
+// a mutant mostly proves the filesystem still works — and the hook is shell, not JS.
+//
+// What this does NOT buy, stated so a green run is not read as more than it is: none of the
+// three defects this repo has actually suffered would have been caught. Two were missing
+// inputs and one was a wrong specification; mutation testing perturbs code and asks whether
+// tests notice, so it is blind to a case nobody wrote and to a rule that was wrong from the
+// start. It measures regression durability, not correctness (LEDGER).
+
+import { cpSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const LINTER = 'scripts/lint-docs.mjs';
+const IMMUTABLE = 'scripts/check-immutable.mjs';
+
+/** ADR-0022 excluded init-method.mjs wholesale, reasoning that a mutant there mostly proves
+ *  the filesystem still works. `classifyCommand` (ADR-0023) is the first total, IO-free
+ *  predicate in that file, so it falls inside the scope ADR-0022 actually described rather
+ *  than the file it named. Recorded as a refinement, never a silent exception. */
+const INIT = 'scripts/init-method.mjs';
+
+/**
+ * The curated mutant list. Each entry names one behaviour and the smallest edit that
+ * reverses it.
+ *
+ * Hand-picked rather than generated: a generator emits hundreds of mutants over these files
+ * and most are equivalent or trivial, so the triage cost — not the runtime — is what makes
+ * a framework a bad trade here. Curating is the work; the runner is twenty lines.
+ *
+ * `equivalent` marks a mutant that cannot be killed because the mutated code means the same
+ * thing. It is kept rather than deleted, so nobody re-adds it as a "gap", and it must carry
+ * the reason it is exempt.
+ */
+export const MUTANTS = [
+  {
+    label: 'normId: pad ids to 3 digits instead of 4',
+    file: LINTER,
+    find: "String(v).trim().padStart(4, '0')",
+    replace: "String(v).trim().padStart(3, '0')",
+  },
+  {
+    label: 'isCalendarDate: drop the round-trip check',
+    file: LINTER,
+    find: 'return parsed.toISOString().startsWith(text);',
+    replace: 'return true;',
+  },
+  {
+    label: 'citableText: stop stripping URLs before matching citations',
+    file: LINTER,
+    find: "text.replace(/\\]\\([^)]*\\)/g, ']()').replace(/\\S*:\\/\\/\\S*/g, '')",
+    replace: "text.replace(/\\]\\([^)]*\\)/g, ']()')",
+  },
+  {
+    label: 'inReadScope: drop the exact-match branch, keeping only the prefix',
+    file: LINTER,
+    find: 'rootRelative === entry || rootRelative.startsWith(`${entry}/`)',
+    replace: 'rootRelative.startsWith(`${entry}/`)',
+  },
+  {
+    label: 'withoutFences: stop blanking lines inside a code fence',
+    file: LINTER,
+    find: "return open === null ? line : '';",
+    replace: 'return line;',
+  },
+  {
+    label: 'sectionText: read to end of body instead of stopping at the next heading',
+    file: LINTER,
+    find: "(end === -1 ? rest : rest.slice(0, end)).join('\\n')",
+    replace: "rest.join('\\n')",
+  },
+  {
+    label: 'hasGherkinTriad: require any step kind rather than all three',
+    file: LINTER,
+    find: "steps.has('given') && steps.has('when') && steps.has('then')",
+    replace: "steps.has('given') || steps.has('when') || steps.has('then')",
+  },
+  {
+    label: 'R6: ignore a superseded_by list of exactly one target',
+    file: LINTER,
+    find: 'if (!isSuperseded && supersededBy.length > 0) {',
+    replace: 'if (!isSuperseded && supersededBy.length > 1) {',
+  },
+  {
+    label: 'classifyCommand: treat an unrecorded command as stale rather than unknown',
+    file: INIT,
+    find: "if (recordedDigest === undefined) return 'unknown';",
+    replace: "if (recordedDigest === undefined) return 'stale';",
+  },
+  {
+    label: 'classifyCommand: swap the stale/adapted verdict',
+    file: INIT,
+    find: "return digest(targetText) === recordedDigest ? 'stale' : 'adapted';",
+    replace: "return digest(targetText) === recordedDigest ? 'adapted' : 'stale';",
+  },
+  {
+    label: 'firstLostLine: weaken the exhausted-scan guard',
+    file: IMMUTABLE,
+    find: 'if (cursor === now.length) return i;',
+    replace: 'if (cursor > now.length) return i;',
+  },
+  {
+    label: 'firstLostLine: compare body lines loosely',
+    file: IMMUTABLE,
+    find: 'while (cursor < now.length && now[cursor] !== was[i]) cursor++;',
+    replace: 'while (cursor < now.length && now[cursor] != was[i]) cursor++;',
+    equivalent: 'both operands are strings, so != and !== are the same comparison',
+  },
+];
+
+/**
+ * A disposable copy of the working tree. The check never edits the operator's files: a run
+ * interrupted midway would otherwise leave mutated source behind, and "my linter is subtly
+ * wrong and I do not know why" is an expensive afternoon.
+ *
+ * `.git` is copied with everything else, because the copy has to behave identically or the
+ * baseline below fails for reasons that have nothing to do with any mutant. `migrate-adrs`
+ * reads commit dates and falls back silently when git cannot answer, so a hollow `.git`
+ * changed its plan and failed five tests. At 3.2MB the copy is not worth being clever about.
+ */
+function scratchCopy() {
+  const dir = mkdtempSync(join(tmpdir(), 'stele-mutants-'));
+  cpSync(ROOT, dir, { recursive: true, filter: (src) => !src.endsWith('/node_modules') });
+  return dir;
+}
+
+/**
+ * `test/mutants.test.mjs` guards this script's own list by asserting every anchor matches
+ * exactly once. Applying a mutant is precisely what stops an anchor matching, so under a
+ * mutated tree that test fails — and every mutant would be scored as killed by the guard
+ * rather than by any regression test, including the equivalent one that cannot be killed
+ * at all. It runs in the ordinary suite, where it belongs, and is excluded here.
+ */
+const SELF_REFERENTIAL = 'mutants.test.mjs';
+
+/** The suite's files, expanded here rather than by a shell: `node --test test/` reads that
+ *  argument as a module path and dies, which is not a test failure but looks exactly like
+ *  one from the outside. */
+function testFiles(cwd) {
+  const dir = join(cwd, 'test');
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith('.test.mjs') && f !== SELF_REFERENTIAL)
+    .sort();
+  if (files.length === 0) throw new Error(`no test files under ${dir} — nothing to run mutants against`);
+  return files.map((f) => join('test', f));
+}
+
+/** True when the suite passes — i.e. the mutant went unnoticed. */
+function suitePasses(cwd, files) {
+  try {
+    execFileSync(process.execPath, ['--test', ...files], { cwd, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function checkMutants({ quiet = false } = {}) {
+  const dir = scratchCopy();
+  const survivors = [];
+  try {
+    const files = testFiles(dir);
+
+    // The load-bearing guard. Every verdict here is "the suite failed, so something was
+    // watching" — which is worthless if the suite fails for its own reasons, and reports a
+    // perfect score while testing nothing. The first draft of this script did exactly that:
+    // it ran `node --test test/`, which is not a directory glob, so all ten mutants "died"
+    // in 621ms against a suite that never started.
+    if (!suitePasses(dir, files)) {
+      throw new Error(
+        'the unmutated suite does not pass — every mutant would report as killed for the\n' +
+        'wrong reason. Fix the suite first, then re-run this check.',
+      );
+    }
+
+    for (const mutant of MUTANTS) {
+      const path = join(dir, mutant.file);
+      const pristine = readFileSync(path, 'utf8');
+
+      // A rotted anchor is a failure, never a skip. The alternative is a probe that quietly
+      // stops testing what it claims to — the exact false green this repo exists to remove.
+      const hits = pristine.split(mutant.find).length - 1;
+      if (hits !== 1) {
+        throw new Error(
+          `mutant anchor matched ${hits} times in ${mutant.file}, expected exactly 1:\n` +
+          `  ${mutant.label}\n` +
+          `  The code moved. Re-aim the mutant at the behaviour it was written for, or ` +
+          `delete it if that behaviour is gone.`,
+        );
+      }
+
+      writeFileSync(path, pristine.replace(mutant.find, mutant.replace));
+      const survived = suitePasses(dir, files);
+      writeFileSync(path, pristine);
+
+      // An equivalent mutant that dies is the canary, not a bonus. It cannot be detected by
+      // any honest test, so a kill means the suite failed for a reason unrelated to the
+      // mutation and every other verdict in this run is worthless. Both times this harness
+      // scored wrongly — the crashing test command, then the self-referential guard — this
+      // is the line that showed it.
+      if (mutant.equivalent && !survived) {
+        throw new Error(
+          `an equivalent mutant was killed, which cannot happen honestly:\n` +
+          `  ${mutant.label}\n` +
+          `  exempt because: ${mutant.equivalent}\n` +
+          `  The suite is failing for a reason unrelated to the mutation, so every other\n` +
+          `  verdict in this run is meaningless. Run the suite by hand and find out why.`,
+        );
+      }
+
+      if (survived && !mutant.equivalent) survivors.push(mutant);
+      if (!quiet) {
+        const verdict = mutant.equivalent ? 'exempt   (equivalent)' : (survived ? 'SURVIVED' : 'killed');
+        console.log(`  ${verdict.padEnd(24)} ${mutant.label}`);
+      }
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  return survivors;
+}
+
+function main(argv) {
+  const quiet = argv.includes('--quiet');
+  if (!quiet) console.log(`\n${ROOT} — ${MUTANTS.length} mutant(s)`);
+
+  const survivors = checkMutants({ quiet });
+  const exempt = MUTANTS.filter((m) => m.equivalent).length;
+
+  if (survivors.length === 0) {
+    console.log(`\nall ${MUTANTS.length - exempt} non-exempt mutant(s) killed, ${exempt} exempt`);
+    return 0;
+  }
+
+  console.log(`\n${survivors.length} mutant(s) survived — the behaviour below is unpinned:`);
+  for (const m of survivors) console.log(`  ${m.file}: ${m.label}`);
+  console.log(
+    '\nEach needs a regression test, or — if the mutated code genuinely means the same thing\n' +
+    '— an `equivalent` note on the mutant saying why it cannot be killed.',
+  );
+  return 1;
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}

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
@@ -13,6 +13,7 @@
 // an install that checks nothing.
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, lstatSync, 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';
 
@@ -28,13 +29,14 @@ const TOOLKIT = dirname(dirname(fileURLToPath(import.meta.url)));
 const VENDORED = [
   ['scripts/lint-docs.mjs', 'scripts/lint-docs.mjs'],
   ['scripts/build-index.mjs', 'scripts/build-index.mjs'],
+  ['scripts/check-immutable.mjs', 'scripts/check-immutable.mjs'],
   ['.claude/hooks/pre-commit', '.claude/hooks/pre-commit'],
 ];
 
 const COMMANDS_DIR = '.claude/commands';
 
 /**
- * The slash commands, vendored too (ADR-0007) — same target path as toolkit path.
+ * The slash commands, vendored too (ADR-0023) — same target path as toolkit path.
  *
  * Read from disk rather than listed, so a new command reaches installed repos without
  * anyone remembering to extend an array here.
@@ -45,6 +47,23 @@ const commandFiles = (toolkit) =>
     .sort()
     .map((name) => `${COMMANDS_DIR}/${name}`);
 
+/**
+ * What the toolkit last handed this repo: command path → SHA-256 of the content written
+ * there (ADR-0023).
+ *
+ * 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 = [
   ['CLAUDE.md', 'templates/CLAUDE.md'],
@@ -61,7 +80,16 @@ const FRAMEWORK_CONFIG = '.pre-commit-config.yaml';
 /** Identifies our block on re-runs, so composing is idempotent. */
 const FRAMEWORK_HOOK_ID = 'stele-docs';
 
-/** Appended verbatim. Mirrors .claude/hooks/pre-commit — the same two commands. */
+/**
+ * Appended verbatim. Mirrors .claude/hooks/pre-commit — the same two checks.
+ *
+ * These deliberately run against the working tree (`.`), where the hook materialises the
+ * staged tree first (ADR-0018). It is not an oversight and must not be "fixed" into a
+ * copy of that machinery: the framework stashes unstaged changes before dispatching, so
+ * by the time these entries run the working tree already *is* the index. Reproducing the
+ * archive dance here would duplicate what the framework provides — which is the whole
+ * reason ADR-0008 chose to compose with it rather than fight it for the file.
+ */
 const FRAMEWORK_BLOCK = `
   # Doc invariants (stele:ADR-0003, composed by /init-method per stele:ADR-0008).
   # Zero-dependency and language: system, so there is nothing to install but node.
@@ -79,6 +107,12 @@ const FRAMEWORK_BLOCK = `
         language: system
         pass_filenames: false
         always_run: true
+      - id: stele-immutable
+        name: immutable documents only grow
+        entry: node scripts/check-immutable.mjs
+        language: system
+        pass_filenames: false
+        always_run: true
 `;
 
 const read = (path) => readFileSync(path, 'utf8');
@@ -122,33 +156,118 @@ function vendor({ target, toolkit, apply, report }) {
 }
 
 /**
- * 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 classifyCommand({ 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, which are prose and therefore adaptable (ADR-0023).
  *
  * 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 }) {
+function vendorCommands({ target, toolkit, apply, update, force, report }) {
+  const recorded = readProvenance(target, report);
+  const learned = { ...recorded };
+  let changed = false;
+
   for (const path of commandFiles(toolkit)) {
     const to = join(target, path);
-    const from = join(toolkit, path);
-    if (matches(to, from)) {
+    const toolkitText = read(join(toolkit, path));
+    const state = classifyCommand({
+      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 }) {
@@ -256,6 +375,28 @@ function frameworkInstalled({ target, report }) {
   else report('problem', hook, 'the pre-commit framework is configured but never installed — no hook runs at all, including its own. Run `pre-commit install`.');
 }
 
+/**
+ * Reports a corpus the freshly vendored linter calls red.
+ *
+ * `--apply` refuses to *install* a hook on a red corpus, because a hook that blocks every
+ * commit is the tool bricking the repo it protects. `--update` reaches the same state by
+ * the other door and had no equivalent guard: a release that adds an error-severity rule
+ * lands a stricter linter behind a hook that is already live, and the next commit fails
+ * with no hint that an update caused it.
+ *
+ * It reports rather than refuses. By the time the copy is written the old linter is gone,
+ * so there is nothing to decline into — and rolling back would leave the repo on machinery
+ * the operator explicitly asked to replace. Loud and accurate beats a silent half-update.
+ */
+function lintAfterUpdate({ target, report }) {
+  const errors = lintErrors(target);
+  if (errors.length === 0) {
+    return report('ok', target, 'corpus still clean under the updated linter');
+  }
+  for (const f of errors) report('problem', f.path, f.message);
+  report('problem', target, `${errors.length} lint error(s) under the updated linter — the hook is live, so every commit is blocked until these are fixed. \`git commit --no-verify\` is the escape hatch while you do.`);
+}
+
 function check({ target, toolkit, report }) {
   for (const [dest, src] of VENDORED) {
     const to = join(target, dest);
@@ -264,12 +405,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.
+  // 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 commandFiles(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 = classifyCommand({
+      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');
   }
 
@@ -302,9 +453,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 });
 
@@ -317,11 +469,12 @@ export function initMethod({ target, toolkit = TOOLKIT, mode = 'install', apply
     check({ target, toolkit, report });
   } else if (mode === 'update') {
     vendor({ target, toolkit, apply, report });
-    vendorCommands({ target, toolkit, apply, force: true, report });
+    vendorCommands({ 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 });
+    vendorCommands({ target, toolkit, apply, update: false, force: false, report });
     buildIndex({ target, apply, report });
     installHook({ target, apply, report });
   }
@@ -335,8 +488,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) {