@phuc1403/musketeer 0.3.0 → 0.5.0

package/template/.claude/hooks/init-adr-dir.cjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// PreToolUse guard: set up `.adr-dir` before the first `adr new` in a project,
+// so the agent never has to pick between `adr init` and a hand-written file.
+//
+// Two setup paths, and picking the wrong one is destructive:
+//   - fresh (no `.adr-dir`, no numbered ADRs yet): `adr init docs/adr` is safe —
+//     it creates docs/adr/, writes `.adr-dir`, and adds a baseline ADR.
+//   - migration (numbered ADRs already exist, but no `.adr-dir`): `adr init`
+//     would ALSO add that baseline ADR, burning the next real number. The fix
+//     is a plain `.adr-dir` file with no tool call: `printf 'docs/adr\n' > .adr-dir`.
+// Already initialized: nothing to do, both paths are a no-op.
+//
+// Runs the setup itself (as a side effect) before allowing `adr new` through,
+// and denies a *direct* `adr init` call whenever running it would be wrong —
+// already initialized, or migration state — since either would burn a number.
+// Anything it does is echoed to stdout so it stays visible in the transcript.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const ADR_DIR = 'docs/adr';
+const ADR_DIR_FILE = path.join(root, '.adr-dir');
+const ADR_FILE = /^\d+-.*\.md$/;
+
+function allow(message) {
+  if (message) process.stdout.write(message + '\n');
+  process.exit(0);
+}
+
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    })
+  );
+  process.exit(0);
+}
+
+function isInitialized() {
+  try {
+    return fs.readFileSync(ADR_DIR_FILE, 'utf8').trim() !== '';
+  } catch {
+    return false;
+  }
+}
+
+function hasNumberedAdrs() {
+  try {
+    return fs.readdirSync(path.join(root, ADR_DIR)).some((f) => ADR_FILE.test(f));
+  } catch {
+    return false; // directory doesn't exist yet -> nothing to migrate
+  }
+}
+
+function runAdrInit() {
+  const shell = process.env.CLAUDE_CODE_GIT_BASH_PATH || 'bash';
+  return spawnSync(shell, ['-c', `adr init ${ADR_DIR}`], { cwd: root, encoding: 'utf8' });
+}
+
+function main() {
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const command = payload?.tool_input?.command || '';
+  const isInit = /\badr\s+init\b/.test(command);
+  const isNew = /\badr\s+new\b/.test(command);
+  if (!isInit && !isNew) return allow();
+
+  if (isInitialized()) {
+    if (isInit) {
+      return deny(
+        '.adr-dir already exists — do not run `adr init` again, it would add a duplicate ' +
+          'baseline ADR and burn the next number. Run `adr new` directly.'
+      );
+    }
+    return allow(); // adr new, already set up: nothing to do
+  }
+
+  if (hasNumberedAdrs()) {
+    // Migration: numbered ADRs exist but `.adr-dir` does not. `adr init` would
+    // still add a baseline ADR here, so it is never the right command.
+    if (isInit) {
+      return deny(
+        'Numbered ADRs already exist without `.adr-dir` — this is a migration, not a fresh ' +
+          'project. `adr init` would add a duplicate baseline ADR and burn the next number. ' +
+          'Run `adr new` directly; `.adr-dir` is set up automatically.'
+      );
+    }
+    fs.writeFileSync(ADR_DIR_FILE, `${ADR_DIR}\n`);
+    return allow(`Migration detected: wrote .adr-dir (${ADR_DIR}) by hand, no baseline ADR added.`);
+  }
+
+  // Fresh project.
+  if (isInit) return allow(); // the agent's own `adr init` call is correct here — let it run
+  const res = runAdrInit();
+  if (res.error || res.status !== 0) {
+    return allow(`Could not run \`adr init ${ADR_DIR}\` (${res.error?.message || res.stderr}); letting the original command run and fail with its own error.`);
+  }
+  return allow(`Fresh project: ran \`adr init ${ADR_DIR}\` (creates the baseline ADR).`);
+}
+
+try {
+  main();
+} catch {
+  allow(); // fail open
+}

package/template/.claude/hooks/inject-adr-env.cjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// PreToolUse guard: inject the env vars every `adr new` call needs, so the
+// agent can write a bare `adr new -- "Title"` and get a correct command.
+//
+//   VISUAL=true EDITOR=true  — without them an ambient EDITOR opens an
+//     interactive editor and hangs the session (adr-new always shells out to
+//     $VISUAL/$EDITOR to "edit" the new file).
+//   ADR_TEMPLATE=...adr-template.md — points adr-new at this skill's template
+//     instead of adr-tools' own bundled default.
+//
+// Uses PreToolUse's `updatedInput` (not just allow/deny) to rewrite the
+// command before it runs. Only fills in vars that are missing — an assignment
+// the agent already wrote (any value, even a deliberately different template)
+// is left alone. Silent no-op if all three are already present.
+//
+// Safety: a title that happens to contain the literal text "adr new" could
+// make the matching regex fire inside a quoted string. Guarded by counting
+// quote characters before each match — an odd count means "inside an open
+// string", and that occurrence is left untouched rather than risk corrupting
+// the title.
+
+const fs = require('fs');
+
+const DEFAULTS = [
+  ['ADR_TEMPLATE', '.claude/skills/adr-writer/references/adr-template.md'],
+  ['VISUAL', 'true'],
+  ['EDITOR', 'true'],
+];
+
+// boundary/start, leading whitespace, any existing KEY=value prefix, `adr new`.
+const ADR_NEW_RE = /(^|[;&|\n])([ \t]*)((?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S*)[ \t]+)*)(adr[ \t]+new\b)/g;
+
+function existingVars(prefix) {
+  const names = new Set();
+  const re = /([A-Za-z_][A-Za-z0-9_]*)=/g;
+  let m;
+  while ((m = re.exec(prefix))) names.add(m[1]);
+  return names;
+}
+
+function isInsideQuotes(command, index) {
+  const before = command.slice(0, index);
+  const dq = (before.match(/"/g) || []).length;
+  const sq = (before.match(/'/g) || []).length;
+  return dq % 2 === 1 || sq % 2 === 1;
+}
+
+function main() {
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const command = payload?.tool_input?.command || '';
+  if (!/\badr\s+new\b/.test(command)) return;
+
+  let changed = false;
+  const updated = command.replace(ADR_NEW_RE, (whole, boundary, ws, existingPrefix, adrNew, offset) => {
+    if (isInsideQuotes(command, offset)) return whole;
+    const present = existingVars(existingPrefix);
+    const missing = DEFAULTS.filter(([name]) => !present.has(name));
+    if (missing.length === 0) return whole;
+    changed = true;
+    const injected = missing.map(([name, value]) => `${name}=${value}`).join(' ');
+    return `${boundary}${ws}${injected} ${existingPrefix}${adrNew}`;
+  });
+  if (!changed) return;
+
+  process.stdout.write(
+    JSON.stringify({
+      systemMessage: 'Added missing VISUAL/EDITOR/ADR_TEMPLATE env vars before `adr new`.',
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: { command: updated },
+      },
+    })
+  );
+}
+
+try {
+  main();
+} catch {
+  /* fail open: leave the command untouched */
+}
+process.exit(0);

package/template/.claude/hooks/lib/characteristics/checker.cjs

@@ -0,0 +1,357 @@
+'use strict';
+
+// Structural checker for the two architecture-characteristic documents.
+//
+// Checks only what is mechanically decidable. The ranking ORDER is a judgement
+// call and is never questioned here; what is checked is that the table is
+// complete, that every comparative reason names the row it actually sits above,
+// and that the worksheet is a faithful derivation of the ranking's top 7.
+//
+// The catalog markdown is the single source of truth for which characteristics
+// exist, which of them are implicit, and how the composites decompose. Nothing
+// here restates it — edit the markdown and this checker follows.
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CATALOG_PATH = path.join(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'skills',
+  'architecture-characteristic-writer',
+  'references',
+  'characteristics-catalog.md'
+);
+
+const DRIVING_LIMIT = 7;
+
+// The ranking table is found by its header row rather than by the heading above
+// it. A heading is prose the author may reword or duplicate; this signature is
+// the table itself. Both the checker and scripts/ranking-table.cjs locate the
+// table this way, so neither can end up working on a different table.
+const RANKING_HEADER = /^\|\s*order\s*\|\s*characteristic\s*\|\s*reason\s*\|/i;
+
+// "feasibility (cost/time)" and "**feasibility**" both normalise to "feasibility"
+// so the checker never argues with formatting.
+function normalise(cell) {
+  return String(cell)
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/\*\*/g, '')
+    .replace(/\([^)]*\)/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+const isPlaceholder = (row) => row.some((c) => /\{[a-z0-9_]+\}/i.test(c)) || row.some((c) => c === '...');
+
+const splitCells = (line) =>
+  line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+
+const isSeparator = (cells) => cells.every((c) => /^:?-+:?$/.test(c) || c === '');
+
+// Returns the data rows of the first pipe table under a heading matching `re`,
+// or of the whole document when `re` is null. Header and separator are dropped.
+function parseTable(markdown, re) {
+  const lines = markdown.split(/\r?\n/);
+  let start = 0;
+
+  if (re) {
+    const i = lines.findIndex((l) => /^#{1,6}\s/.test(l) && re.test(l));
+    if (i === -1) return null;
+    start = i + 1;
+    const next = lines.slice(start).findIndex((l) => /^#{1,6}\s/.test(l));
+    if (next !== -1) lines.length = start + next;
+  }
+
+  const rows = [];
+  let seenHeader = false;
+
+  for (const line of lines.slice(start)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) {
+      if (seenHeader && rows.length) break;
+      continue;
+    }
+    const cells = splitCells(trimmed);
+    if (!seenHeader) {
+      seenHeader = true;
+      continue;
+    }
+    if (isSeparator(cells)) continue;
+    rows.push(cells);
+  }
+
+  return seenHeader ? rows : null;
+}
+
+// Line bounds of the table whose header matches `headerRe`, covering the header
+// through the last consecutive pipe line. Returns null when there is no match.
+function locateTable(lines, headerRe) {
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!lines[i].trim().startsWith('|') || !headerRe.test(lines[i].trim())) continue;
+    let end = i + 1;
+    while (end < lines.length && lines[end].trim().startsWith('|')) end += 1;
+    return { start: i, end };
+  }
+  return null;
+}
+
+// Data rows of the table located by `headerRe`, header and separator dropped.
+function tableRows(markdown, headerRe) {
+  const lines = markdown.split(/\r?\n/);
+  const at = locateTable(lines, headerRe);
+  if (!at) return null;
+  return lines
+    .slice(at.start + 1, at.end)
+    .map(splitCells)
+    .filter((c) => !isSeparator(c));
+}
+
+// Reads the catalog markdown and derives every set the checker needs from it.
+// Throws when the file is absent or a section is unreadable; the caller decides
+// whether that is fatal.
+function loadCatalog(catalogPath = DEFAULT_CATALOG_PATH) {
+  const markdown = fs.readFileSync(catalogPath, 'utf8');
+
+  const names = (re) => {
+    const rows = parseTable(markdown, re);
+    if (!rows) throw new Error(`no table found under a heading matching ${re}`);
+    return rows.filter((r) => r.length && !isPlaceholder(r)).map((r) => normalise(r[0]));
+  };
+
+  const common = names(/common/i);
+  const implicit = names(/implicit/i);
+
+  const compositeRows = parseTable(markdown, /composite/i);
+  if (!compositeRows) throw new Error('no Composite Architecture Characteristics table found');
+
+  const composites = {};
+  for (const row of compositeRows.filter((r) => r.length >= 2 && !isPlaceholder(r))) {
+    composites[normalise(row[0])] = row[1].split('+').map(normalise).filter(Boolean);
+  }
+
+  if (!common.length || !implicit.length) throw new Error('the Common or Implicit section is empty');
+
+  return { catalog: [...common, ...implicit], implicit, composites };
+}
+
+function checkRanking(markdown, { catalog }) {
+  const errors = [];
+  const found = tableRows(markdown, RANKING_HEADER);
+  if (!found) {
+    return {
+      errors: ['ranking: no table with a "| Order | Characteristic | Reason |" header row'],
+      order: [],
+    };
+  }
+  const raw = found.filter((r) => r.length >= 3);
+  const unfilled = raw.filter(isPlaceholder);
+  const rows = raw.filter((r) => !isPlaceholder(r));
+
+  // A scaffold is a blank form, not a broken document: every reason is still a
+  // placeholder, bar the last row whose reason is only the em dash.
+  const hasContent = (r) => !isPlaceholder(r) && !/^[—-]$/.test(String(r[2]).trim());
+  if (raw.length && !raw.some(hasContent)) return { errors: [], order: [] };
+  if (!rows.length) return { errors: ['ranking: no table rows found'], order: [] };
+
+  // Half-filled, so adjacency cannot be judged: a filled row's neighbour may be
+  // one of the rows still holding a placeholder. Ask for the rest first.
+  if (unfilled.length) {
+    return {
+      errors: [`ranking: ${unfilled.length} row(s) still hold the {why} placeholder, fill them in`],
+      order: [],
+    };
+  }
+
+  const order = rows.map((r) => normalise(r[1]));
+
+  // Rule 1 — the Order column counts 1..N with no gaps and no repeats.
+  rows.forEach((r, i) => {
+    const n = Number(String(r[0]).trim());
+    if (n !== i + 1) errors.push(`ranking row ${i + 1}: Order column reads "${r[0]}", expected ${i + 1}`);
+  });
+
+  // Rule 2 — the ranked set is exactly the catalog. Nothing missing, nothing
+  // invented, nothing ranked twice.
+  const seen = new Set();
+  order.forEach((name, i) => {
+    if (!catalog.includes(name)) errors.push(`ranking row ${i + 1}: "${name}" is not in the catalog`);
+    if (seen.has(name)) errors.push(`ranking row ${i + 1}: "${name}" is ranked more than once`);
+    seen.add(name);
+  });
+  for (const name of catalog) {
+    if (!seen.has(name)) errors.push(`ranking: "${name}" is missing`);
+  }
+
+  // Rules 3 and 4 — every reason names the row it actually sits above. This is
+  // what goes stale after a reorder, so it is checked by string, not by eye.
+  rows.forEach((r, i) => {
+    const reason = String(r[2]).trim();
+    const last = i === rows.length - 1;
+
+    if (last) {
+      if (!/^[—-]$/.test(reason)) {
+        errors.push(`ranking row ${i + 1}: last row has nothing below it, its Reason must be "—"`);
+      }
+      return;
+    }
+
+    const below = order[i + 1];
+    const m = reason.match(/^above\s+([^:]+):\s*(.*)$/i);
+
+    if (!m) {
+      errors.push(`ranking row ${i + 1} (${order[i]}): Reason must start with "Above ${below}:"`);
+      return;
+    }
+    if (normalise(m[1]) !== below) {
+      errors.push(
+        `ranking row ${i + 1} (${order[i]}): Reason compares against "${m[1].trim()}" but the row below is "${below}"`
+      );
+    }
+    if (m[2].trim().length < 15) {
+      errors.push(`ranking row ${i + 1} (${order[i]}): Reason has a prefix but no justification after it`);
+    }
+  });
+
+  return { errors, order };
+}
+
+function checkWorksheet(markdown, order, { implicit, composites }) {
+  const errors = [];
+  const driving = (parseTable(markdown, /driving/i) || []).filter((r) => r.length >= 2 && !isPlaceholder(r));
+  const implicitRows = (parseTable(markdown, /implicit/i) || []).filter(
+    (r) => r.length >= 1 && !isPlaceholder(r)
+  );
+
+  if (!driving.length) return ['worksheet: no Driving Characteristics rows found'];
+
+  const names = driving.map((r) => normalise(r[1] !== undefined && r.length >= 3 ? r[1] : r[0]));
+
+  // Rule 5 — no backfill. Composing shrinks the section; it never refills.
+  if (names.length > DRIVING_LIMIT) {
+    errors.push(`worksheet: ${names.length} driving characteristics, maximum is ${DRIVING_LIMIT}`);
+  }
+
+  // Listed twice, so the count is a lie and the top 7 cannot all be present.
+  // Said plainly here, or it surfaces later as a confusing pile of "missing".
+  const twice = new Set();
+  names.forEach((name, i) => {
+    if (names.indexOf(name) !== i) twice.add(name);
+  });
+  for (const name of twice) errors.push(`worksheet: "${name}" is listed more than once`);
+
+  // Without a readable ranking the remaining rules have nothing to derive from.
+  if (!order.length) return errors;
+
+  const top = order.slice(0, DRIVING_LIMIT);
+  const absorbed = new Set();
+
+  for (const name of names) {
+    const parts = composites[name];
+
+    if (parts) {
+      // Rule 7 — a composite stands only when the whole of it ranked top 7.
+      const missing = parts.filter((p) => !top.includes(p));
+      if (missing.length) {
+        errors.push(
+          `worksheet: "${name}" needs all of [${parts.join(', ')}] in the top 7, missing [${missing.join(', ')}]`
+        );
+      }
+      parts.forEach((p) => absorbed.add(p));
+
+      // Rule 8 — a composite and its own parts must never be listed side by side.
+      const both = parts.filter((p) => names.includes(p));
+      if (both.length) {
+        errors.push(`worksheet: "${name}" is listed alongside its own component [${both.join(', ')}]`);
+      }
+      continue;
+    }
+
+    // Rule 6 — everything driving traces back to the top 7.
+    if (!top.includes(name)) {
+      const rank = order.indexOf(name);
+      errors.push(
+        rank === -1
+          ? `worksheet: "${name}" is not in the ranking at all`
+          : `worksheet: "${name}" is ranked ${rank + 1}, outside the top 7`
+      );
+    }
+  }
+
+  const present = new Set([...names, ...absorbed]);
+
+  // Rule 6b — the top 7 is taken whole. Every one of them is either listed or
+  // swallowed by a composite; none may be quietly dropped.
+  for (const name of top) {
+    if (!present.has(name)) {
+      errors.push(`worksheet: "${name}" is ranked ${order.indexOf(name) + 1} but is missing from the worksheet`);
+    }
+  }
+
+  // Rule 9 — the implicit set is a pure derivation: the catalog's implicit
+  // characteristics, less any that reached the top 7, counting those a
+  // composite swallowed.
+  const expected = implicit.filter((c) => !present.has(c));
+  const actual = implicitRows.map((r) => normalise(r[0])).filter((c) => implicit.includes(c));
+
+  for (const c of expected) {
+    if (!actual.includes(c)) errors.push(`worksheet: implicit characteristic "${c}" is missing`);
+  }
+  for (const c of actual) {
+    if (!expected.includes(c)) {
+      errors.push(`worksheet: "${c}" is in the top 7, so it must not be listed as implicit`);
+    }
+  }
+
+  return errors;
+}
+
+// ranking and worksheet are file contents; either may be null when absent.
+// The catalog sets default to the shipped markdown; pass `catalog` to inject.
+function check({ ranking = null, worksheet = null, catalog = null, catalogPath } = {}) {
+  let sets = catalog;
+
+  if (!sets) {
+    try {
+      sets = loadCatalog(catalogPath);
+    } catch (err) {
+      return [`cannot read the characteristics catalog, so nothing can be checked: ${err.message}`];
+    }
+  }
+
+  let errors = [];
+  let order = [];
+
+  if (ranking !== null) {
+    const res = checkRanking(ranking, sets);
+    errors = errors.concat(res.errors);
+    order = res.order;
+  }
+
+  if (worksheet !== null) {
+    if (ranking === null) {
+      errors.push('worksheet: no ranking file to derive from, write the ranking first');
+    } else {
+      errors = errors.concat(checkWorksheet(worksheet, order, sets));
+    }
+  }
+
+  return errors;
+}
+
+module.exports = {
+  check,
+  checkRanking,
+  checkWorksheet,
+  parseTable,
+  locateTable,
+  splitCells,
+  isSeparator,
+  normalise,
+  loadCatalog,
+  RANKING_HEADER,
+  DEFAULT_CATALOG_PATH,
+};

package/template/.claude/hooks/sync-adr-toc.cjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// PostToolUse hook: after any `adr` command, rebuild docs/adr/README.md from the
+// ADR files themselves — one row per ADR with its title and current status.
+//
+// The index is fully derived, so it can never drift: every run re-reads the
+// source. That is why there is no need to be clever about which adr subcommand
+// ran, or to protect the file from being rewritten.
+//
+// Also runnable directly:  node sync-adr-toc.cjs --write
+//
+// Fails open at exit 0 on any problem — a hook must never block a session.
+
+const fs = require('fs');
+const path = require('path');
+
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const ADR_FILE = /^\d+-.*\.md$/;
+
+// adr-tools reads its directory from a committed `.adr-dir` (default `doc/adr`).
+function adrDir() {
+  try {
+    return fs.readFileSync(path.join(root, '.adr-dir'), 'utf8').trim() || 'doc/adr';
+  } catch {
+    return 'doc/adr';
+  }
+}
+
+// Was this Bash call an adr command? (`VISUAL=true EDITOR=true adr new …` counts;
+// the internal `adr-new` script name does not, hence the required whitespace.)
+function isAdrCommand() {
+  try {
+    const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+    return /\badr\s/.test(payload?.tool_input?.command || '');
+  } catch {
+    return false;
+  }
+}
+
+// First line, minus the leading "# " and adr-tools' own number prefix — it writes
+// "# 12: Use X over Y" for 0012-….md. Dropping the unpadded 12 keeps the padded
+// stem in the ADR column the only number in the file, so nothing here can be
+// mistaken for the stem `adr new -s` expects.
+function title(body, fallback) {
+  const first = body.split(/\r?\n/)[0] || '';
+  return first.replace(/^#\s*(\d+\s*[:.]\s*)?/, '').trim() || fallback;
+}
+
+// First non-empty line of the `## Status` section. adr-tools maintains this:
+// "Accepted", or "Superceded by [4: …](0004-….md)" after `adr new -s`.
+function status(body) {
+  const lines = body.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^##\s+Status\s*$/i.test(l));
+  if (start === -1) return 'Unknown';
+  for (const line of lines.slice(start + 1)) {
+    if (/^##\s/.test(line)) break;
+    if (line.trim()) return line.trim();
+  }
+  return 'Unknown';
+}
+
+function render(dir, files) {
+  const rows = files.map((name) => {
+    const body = fs.readFileSync(path.join(root, dir, name), 'utf8');
+    const stem = name.replace(/\.md$/, ''); // padded — what `adr new -s` needs
+    const cell = (s) => s.replace(/\|/g, '\\|'); // never break the table
+    return `| [${stem}](./${name}) | ${cell(title(body, stem))} | ${cell(status(body))} |`;
+  });
+
+  return [
+    '# Architecture Decision Records',
+    '',
+    'Generated from the ADR files by the `sync-adr-toc` hook — do not hand-edit.',
+    '',
+    '| ADR | Title | Status |',
+    '|-----|-------|--------|',
+    ...rows,
+    '',
+  ].join('\n');
+}
+
+function main() {
+  if (!process.argv.includes('--write') && !isAdrCommand()) return;
+
+  const dir = adrDir();
+  const files = fs
+    .readdirSync(path.join(root, dir))
+    .filter((f) => ADR_FILE.test(f))
+    .sort();
+  if (files.length === 0) return;
+
+  const target = path.join(root, dir, 'README.md');
+  const next = render(dir, files);
+
+  let current = null;
+  try {
+    current = fs.readFileSync(target, 'utf8');
+  } catch {
+    /* no index yet */
+  }
+  if (current === next) return; // already in sync
+
+  fs.writeFileSync(target, next);
+  process.stdout.write(`Regenerated ${dir}/README.md (${files.length} ADRs).\n`);
+}
+
+try {
+  main();
+} catch {
+  /* fail open */
+}
+process.exit(0);