@phuc1403/musketeer 0.6.0 → 0.7.0

package/INSTALLATION.md

@@ -14,16 +14,21 @@ an elevation prompt is refused — it falls back to printing the exact manual co
 | git | core, code-review | `winget install Git.Git` | `brew install git` | `apt/dnf/pacman install git` |
 | Python 3.8+ | core (skill-creator) | `winget install Python.Python.3.12` | `brew install python@3.12` | `apt install python3 python3-pip` |
 | Java 8+ | architecture (context-map) | `winget install Microsoft.OpenJDK` | `brew install --cask temurin` | `apt install openjdk-17-jdk` |
-| adr-tools | architecture (adr-writer) | download the [release zip](https://github.com/npryce/adr-tools/releases), copy `src/*` into `C:\Program Files\Git\usr\bin` (Git Bash) | `brew install adr-tools` | `apt install adr-tools` · Arch: AUR `adr-tools` · Fedora/RHEL: clone + add `src/` to `PATH` |
+| adr-tools | architecture (adr-writer) | `npm i -g @meza/adr-tools@2` | `npm i -g @meza/adr-tools@2` | `npm i -g @meza/adr-tools@2` |
 | gh | code-review (PR mode) | `winget install GitHub.cli` | `brew install gh` | `apt install gh` |
 
-> `adr-tools` is a set of bash scripts. On Windows it runs inside Git Bash (already required by
-> core), which is where muster now probes for it, so a working install is reported as present.
+> `adr-tools` is [`@meza/adr-tools`](https://www.npmjs.com/package/@meza/adr-tools) — the maintained
+> Node port of `npryce/adr-tools`. Same `adr` binary, same `.adr-dir`, same `NNNN-slug.md` files, so
+> existing ADRs carry over untouched. One npm command on every platform: no Git Bash, no admin
+> rights, no release zip.
 >
-> On Windows, keep the project on a path with no spaces. `adr-tools` resolves its ADR directory
-> with an unquoted path test, so a space makes it fall back to a `doc/adr` default and write the
-> record where nothing indexes it. Musketeer refuses the call rather than let that happen, but the
-> underlying tool is still wrong.
+> It is the one prereq that needs **Node >= 22.13.0** (musketeer itself still only needs 18). It is
+> installed as a prereq rather than bundled: it is GPL-3.0 and musketeer is MIT, so musketeer
+> invokes it as a subprocess instead of depending on it.
+>
+> Upgrading from `npryce/adr-tools`? Remove the old scripts first. They install as loose files in
+> `~/bin` or Git's `usr/bin`, and if either is earlier on your `PATH` the old `adr` keeps winning —
+> most visibly inside Git Bash.
 
 ### Running muster without a terminal
 

package/manifest.json

@@ -64,7 +64,7 @@
         "hooks/warn-missing-characteristics.cjs",
         "hooks/block-unsafe-adr-title.cjs",
         "hooks/init-adr-dir.cjs",
-        "hooks/inject-adr-env.cjs"
+        "hooks/inject-adr-flags.cjs"
       ],
       "settings": [
         {
@@ -90,9 +90,9 @@
         {
           "event": "PreToolUse",
           "matcher": "Bash",
-          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/inject-adr-env.cjs\"",
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/inject-adr-flags.cjs\"",
           "order": 3,
-          "statusMessage": "Filling in adr new env vars"
+          "statusMessage": "Adding -q to adr new"
         },
         {
           "event": "PreToolUse",
@@ -267,15 +267,13 @@
       "needs": ["java"]
     },
     "adr-tools": {
-      "detect": "adr config",
-      "detectShell": "bash",
+      "detect": "adr --version",
+      "minVersion": "2",
       "kind": "package",
-      "needs": ["git"],
       "install": {
-        "mac": "brew install adr-tools",
-        "linux": {
-          "apt": "sudo apt-get install -y adr-tools"
-        }
+        "win": "npm install -g @meza/adr-tools@2",
+        "mac": "npm install -g @meza/adr-tools@2",
+        "linux": "npm install -g @meza/adr-tools@2"
       }
     },
     "gh": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phuc1403/musketeer",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Distributable custom Claude Code harness — one declarative command scaffolds a curated company of musketeers (skills/agents/hooks) into any project's .claude/.",
   "type": "commonjs",
   "bin": {
@@ -19,7 +19,9 @@
     "template",
     "README.md",
     "INSTALLATION.md",
-    "LICENSE"
+    "LICENSE",
+    "!template/**/bin",
+    "!template/**/obj"
   ],
   "keywords": [
     "claude",

package/src/dotnet-scaffold-copier.js

@@ -10,6 +10,12 @@ function containedPath(root, candidate) {
   return resolved;
 }
 
+// Build output directories. These are regenerated by `dotnet build` and must
+// never reach a generated project: they embed absolute paths from whichever
+// machine built the template, and their binaries would be mangled by the
+// UTF-8 read + token substitution below.
+const EXCLUDED_DIRS = new Set(["bin", "obj"]);
+
 function substitute(text, token, replacement) {
   return text.split(token).join(replacement);
 }
@@ -31,6 +37,7 @@ function copyTemplateWithTokenSubstitution(srcDir, stagingDir, token, replacemen
 function walk(currentSrc, currentDest, stagingRoot, token, replacement) {
   const entries = fs.readdirSync(currentSrc, { withFileTypes: true });
   for (const entry of entries) {
+    if (entry.isDirectory() && EXCLUDED_DIRS.has(entry.name)) continue;
     const substitutedName = substitute(entry.name, token, replacement);
     const srcPath = path.join(currentSrc, entry.name);
     const destPath = containedPath(stagingRoot, path.join(currentDest, substitutedName));

package/src/provisioner/detect.js

@@ -14,12 +14,7 @@ const SECRET_ENV = { 'anthropic-api-key': 'ANTHROPIC_API_KEY' };
  * @returns {{code:number, stdout:string, stderr:string}}
  */
 function defaultRun(cmd) {
-  // An array is an argv, spawned without a shell. Windows quoting cannot be
-  // trusted to survive a nested `bash -lc "..."` inside cmd.exe, so probes that
-  // need a shell of their own pass their arguments already separated.
-  const r = Array.isArray(cmd)
-    ? spawnSync(cmd[0], cmd.slice(1), { encoding: 'utf8', windowsHide: true })
-    : spawnSync(cmd, { shell: true, encoding: 'utf8', windowsHide: true });
+  const r = spawnSync(cmd, { shell: true, encoding: 'utf8', windowsHide: true });
   return {
     code: typeof r.status === 'number' ? r.status : 1,
     stdout: r.stdout || '',
@@ -27,19 +22,6 @@ function defaultRun(cmd) {
   };
 }
 
-/**
- * Probe for a prereq whose manifest entry sets `detectShell: "bash"`.
- * adr-tools ships as bash scripts living in Git's own `usr/bin`, which Windows
- * cannot see or execute: `adr config` fails there while working fine in Git
- * Bash. Probing through the same shell the ADR hooks use stops muster reporting
- * a tool that is installed as missing.
- * @param {string} detect
- * @returns {string[]} argv
- */
-function bashProbe(detect) {
-  return [process.env.CLAUDE_CODE_GIT_BASH_PATH || 'bash', '-lc', detect];
-}
-
 /** Extract a numeric version tuple from arbitrary command output. */
 function parseVersion(text) {
   const m = String(text).match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
@@ -90,9 +72,7 @@ function detectPrereq(name, prereq, ctx) {
     default: {
       // package
       if (!prereq.detect) return { name, present: false, version: null, reason: 'no detect command' };
-      let r = run(prereq.detectShell === 'bash' ? bashProbe(prereq.detect) : prereq.detect);
-      // A shell-script tool invisible to Windows still answers through Git Bash.
-      if (r.code !== 0 && prereq.detectShell === 'bash') r = run(prereq.detect);
+      let r = run(prereq.detect);
       if (r.code !== 0 && name === 'python') r = run('python3 --version'); // unix fallback
       const out = r.stdout + r.stderr;
       const ver = parseVersion(out);
@@ -110,4 +90,4 @@ function detectPrereq(name, prereq, ctx) {
   }
 }
 
-module.exports = { detectPrereq, parseVersion, versionGte, defaultRun, bashProbe, SECRET_ENV };
+module.exports = { detectPrereq, parseVersion, versionGte, defaultRun, SECRET_ENV };

package/template/.claude/hooks/block-unsafe-adr-title.cjs

@@ -1,22 +1,39 @@
 #!/usr/bin/env node
-// PreToolUse guard: block an `adr new` title that adr-tools' own script cannot
-// handle safely.
+// PreToolUse guard: block an `adr new` title the tool cannot render safely.
 //
-// adr-new builds the ADR file with `sed -e "s|TITLE|$title|"`, substituting the
-// title in unescaped and using `|` as the delimiter. Two failure modes follow,
-// verified directly against /usr/bin/adr-new:
-//   - `|` in the title breaks sed's own syntax: it exits 1, but only after
-//     creating a zero-byte ADR file that already burned that number.
-//   - `&` in a sed replacement means "the whole match" — it does NOT error.
-//     "Use Kafka & Queues" silently becomes the title "Use Kafka TITLE Queues",
-//     written straight into the file and the generated index.
-// A title starting with `-` is a third case: adr-new parses its own flags with
-// getopts, so without a `--` separator the title is read as an unknown option
-// and the ADR is silently never created (clean failure, still worth catching
-// early with a clearer reason than adr-tools' own "no title given").
+// The tool builds the ADR by running plain JS string replacements over the
+// template, in a fixed order: DATE, TITLE, NUMBER, STATUS. `String.replace`
+// with a string pattern rewrites the FIRST occurrence, and by the time STATUS
+// is substituted the title is already sitting in the document — on line 1,
+// ahead of the real `STATUS` placeholder in the `## Status` section.
 //
-// Blocking, not warning: `|` wastes an ADR number and `&` corrupts data with no
-// error at all, so there is nothing later in the pipeline that will catch it.
+// So an uppercase STATUS inside the title captures the substitution meant for
+// the status line. Verified against @meza/adr-tools 2.0.4:
+//   adr new -q -- "Use STATUS codes for errors"
+// writes `# 1: Use Accepted codes for errors` and leaves the real status as the
+// literal word STATUS — exit 0, no warning, wrong data in the index.
+//
+// Only STATUS is blocked, and only in uppercase:
+//   - the replacement is case-sensitive, so "Use status codes" is fine;
+//   - DATE is substituted before the title is inserted, so it cannot be caught;
+//   - NUMBER and TITLE are substituted at points that precede the title text in
+//     the template shipped with this skill, so the real placeholder always wins.
+//     That last one holds because of where the tokens sit in
+//     `references/adr-template.md` — revisit this guard if that file is ever
+//     reordered so `## Status` precedes the heading.
+//
+// A title starting with `-` is the second case: the tool parses its own flags
+// with commander, so without a `--` separator the title is read as an unknown
+// option. That one fails cleanly (exit 1, no file created), but it is still
+// worth catching early with a clearer reason than "unknown option".
+//
+// Blocking, not warning: the STATUS case corrupts data with no error at all, so
+// there is nothing later in the pipeline that will catch it.
+//
+// The `|` and `&` characters used to be blocked here too. Those were hazards of
+// the old bash implementation, which substituted the title into
+// `sed -e "s|TITLE|$title|"`. Substitution is JS now, and both characters were
+// re-verified as harmless, so blocking them would only refuse valid titles.
 
 const { invokesAdr } = require("./lib/adr/command-scan.cjs");
 
@@ -43,18 +60,14 @@ process.stdin.on("end", () => {
   if (!afterDashDash) {
     reason =
       "no `--` before the title (or no quoted title found after it). Without `--`, " +
-      "adr-new's getopts can read a title starting with `-` as a flag and silently " +
-      "create nothing. Always: adr new [-s STEM]... -- \"Title\".";
-  } else if (title.includes("|")) {
-    reason =
-      "the title contains `|`. adr-new substitutes it into `sed -e \"s|TITLE|$title|\"`, " +
-      "using `|` as sed's own delimiter — this breaks sed's syntax and exits non-zero, " +
-      "but only after creating a zero-byte ADR file that already consumed that number.";
-  } else if (title.includes("&")) {
+      "a title starting with `-` is parsed as an unknown option and no ADR is " +
+      'created. Always: adr new -q [-s STEM]... -- "Title".';
+  } else if (title.includes("STATUS")) {
     reason =
-      "the title contains `&`. In a sed replacement `&` means \"the whole match\", so " +
-      "adr-new writes it as literal text into the title (e.g. \"Use Kafka & Queues\" " +
-      "becomes \"Use Kafka TITLE Queues\") and exits 0 — nothing else will catch this.";
+      "the title contains `STATUS` in uppercase. The tool substitutes STATUS into the " +
+      'template after the title is already in the document, so "Use STATUS codes" ' +
+      'becomes "Use Accepted codes" and the real Status section is left as the literal ' +
+      "word STATUS — it exits 0, so nothing else will catch this. Lowercase `status` is fine.";
   }
 
   if (reason) {

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

@@ -7,9 +7,13 @@
 //     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`.
+//     is a plain `.adr-dir` file with no tool call.
 // Already initialized: nothing to do, both paths are a no-op.
 //
+// Also makes sure this skill's ADR template is the one `adr new` picks up, by
+// placing it at `<adr-dir>/templates/template.md` — the third step of the tool's
+// own template resolution, and the reason no env var has to be injected.
+//
 // 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.
@@ -24,6 +28,14 @@ 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$/;
+const SKILL_TEMPLATE = path.join(
+  root,
+  '.claude',
+  'skills',
+  'adr-writer',
+  'references',
+  'adr-template.md'
+);
 
 function allow(message) {
   if (message) process.stdout.write(message + '\n');
@@ -52,11 +64,7 @@ function readAdrDir() {
 }
 
 function isInitialized() {
-  try {
-    return fs.readFileSync(ADR_DIR_FILE, 'utf8').trim() !== '';
-  } catch {
-    return false;
-  }
+  return readAdrDir() !== null;
 }
 
 function hasNumberedAdrs() {
@@ -68,39 +76,42 @@ function hasNumberedAdrs() {
 }
 
 function runAdrInit() {
-  const shell = process.env.CLAUDE_CODE_GIT_BASH_PATH || 'bash';
-  return spawnSync(shell, ['-c', `adr init ${ADR_DIR}`], { cwd: root, encoding: 'utf8' });
+  // `adr` is an npm bin — a real executable on every platform, so it is called
+  // directly rather than through a shell script interpreter. `shell: true` is
+  // here only because npm installs it as `adr.cmd` on Windows, which
+  // CreateProcess cannot launch on its own; every argument is a constant, so
+  // there is nothing for a shell to interpolate.
+  return spawnSync('adr', ['init', ADR_DIR], { cwd: root, shell: true, encoding: 'utf8' });
 }
 
-// Where adr-tools itself thinks the ADRs go. `_adr_dir` is the resolver every
-// adr subcommand uses, so asking it directly is the only honest answer.
-function resolvedAdrDir() {
-  const shell = process.env.CLAUDE_CODE_GIT_BASH_PATH || 'bash';
-  const res = spawnSync(shell, ['-c', '_adr_dir'], { cwd: root, encoding: 'utf8' });
-  if (res.error || res.status !== 0) return null;
-  const out = (res.stdout || '').trim();
-  return out || null;
-}
-
-// adr-tools resolves the directory with an unquoted `[` test, so a path holding
-// a space splits into too many arguments, the search loop is skipped, and the
-// script falls through to its `doc/adr` default. It prints the wrong answer on
-// stdout and exits 0, so the ADR lands in a directory nothing else looks at and
-// nothing reports a problem. Refuse the call instead of losing the record.
-function denyOnDirMismatch() {
+// `adr init` writes `.adr-dir` with `path.relative`, so on Windows it lands as
+// `docs\adr` with no trailing newline. That file is committed and read on every
+// other machine, where a backslash is an ordinary filename character and not a
+// separator. Rewrite it in the portable form the rest of this toolchain emits.
+function normalizeAdrDirFile() {
   const declared = readAdrDir();
-  const resolved = resolvedAdrDir();
-  if (!declared || !resolved || declared === resolved) return;
+  if (!declared) return;
+  fs.writeFileSync(ADR_DIR_FILE, `${declared.split(path.sep).join('/')}\n`);
+}
 
-  deny(
-    `adr-tools resolves the ADR directory to "${resolved}", but .adr-dir says "${declared}". ` +
-      `The new ADR would be written to "${resolved}", where the index hook never looks. ` +
-      (/\s/.test(root)
-        ? `This project's path contains a space (${root}), which is the known cause: ` +
-          "adr-tools' `_adr_dir` leaves its path test unquoted. "
-        : '') +
-      'Fix the quoting in adr-tools\' `_adr_dir`, or move the project to a path with no spaces.'
-  );
+// The tool resolves its template as: explicit argument, then $ADR_TEMPLATE, then
+// `<adr-dir>/templates/template.md`, then its own bundled default. Copying this
+// skill's template into the third slot means a bare `adr new` produces a
+// musketeer ADR with no environment set up for it.
+//
+// Only ever writes when the file is absent, so a project that has customised its
+// own template keeps it.
+function ensureTemplate() {
+  try {
+    const dir = readAdrDir() || ADR_DIR;
+    const target = path.join(root, dir, 'templates', 'template.md');
+    if (fs.existsSync(target) || !fs.existsSync(SKILL_TEMPLATE)) return null;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(SKILL_TEMPLATE, target);
+    return `Installed the adr-writer template at ${dir}/templates/template.md.`;
+  } catch {
+    return null; // never block an ADR over the template copy
+  }
 }
 
 function main() {
@@ -117,8 +128,7 @@ function main() {
           'baseline ADR and burn the next number. Run `adr new` directly.'
       );
     }
-    denyOnDirMismatch(); // exits when adr-tools would write somewhere else
-    return allow(); // adr new, already set up: nothing to do
+    return allow(ensureTemplate()); // adr new, already set up: nothing else to do
   }
 
   if (hasNumberedAdrs()) {
@@ -132,18 +142,28 @@ function main() {
       );
     }
     fs.writeFileSync(ADR_DIR_FILE, `${ADR_DIR}\n`);
-    denyOnDirMismatch();
-    return allow(`Migration detected: wrote .adr-dir (${ADR_DIR}) by hand, no baseline ADR added.`);
+    const note = ensureTemplate();
+    return allow(
+      `Migration detected: wrote .adr-dir (${ADR_DIR}) by hand, no baseline ADR added.` +
+        (note ? `\n${note}` : '')
+    );
   }
 
   // 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(
+      `Could not run \`adr init ${ADR_DIR}\` (${res.error?.message || res.stderr}); ` +
+        'letting the original command run and fail with its own error.'
+    );
   }
-  denyOnDirMismatch();
-  return allow(`Fresh project: ran \`adr init ${ADR_DIR}\` (creates the baseline ADR).`);
+  normalizeAdrDirFile();
+  const note = ensureTemplate();
+  return allow(
+    `Fresh project: ran \`adr init ${ADR_DIR}\` (creates the baseline ADR).` +
+      (note ? `\n${note}` : '')
+  );
 }
 
 try {

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

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// PreToolUse guard: add the one flag every `adr new` call needs, so the agent
+// can write a bare `adr new -- "Title"` and still get a safe command.
+//
+//   -q / --quiet — without it, an `-s` pattern matching more than one file
+//     opens an interactive prompt on stdin and hangs the session. With it,
+//     the ambiguous case throws instead, so the wrong ADR is never superseded
+//     by a silent guess.
+//
+// Nothing else is injected. The template no longer needs an env var: `adr`
+// resolves `<adr-dir>/templates/template.md` on its own, and init-adr-dir.cjs
+// puts musketeer's template there. There is no editor to suppress either —
+// `adr` only opens one on an explicit `--open`.
+//
+// Uses PreToolUse's `updatedInput` (not just allow/deny) to rewrite the
+// command before it runs. A `-q` the agent already wrote is left alone, and
+// the call is a silent no-op.
+//
+// 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 {
+  invocationRe,
+  isInsideQuotes,
+  isInsideHeredoc,
+  invokesAdr,
+} = require('./lib/adr/command-scan.cjs');
+
+const QUIET = /(?:^|\s)(?:-q|--quiet)(?=\s|$)/;
+
+// Everything between `adr new` and either the `--` option terminator or the end
+// of this command segment, whichever comes first.
+//
+// The title lives after `--` and may legitimately contain the text "-q"
+// ("Use -q for quiet builds"). Scanning it would make the hook believe the flag
+// was already supplied and skip an invocation that genuinely needs it, so the
+// title is never part of the region searched.
+function flagsRegion(command, from) {
+  const rest = command.slice(from);
+  let end = rest.length;
+
+  const terminator = rest.search(/\s--(\s|$)/);
+  if (terminator !== -1) end = terminator;
+
+  for (let i = 0; i < end; i++) {
+    if (';&|\n'.includes(rest[i]) && !isInsideQuotes(command, from + i)) {
+      end = i;
+      break;
+    }
+  }
+  return rest.slice(0, end);
+}
+
+function main() {
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const command = payload?.tool_input?.command || '';
+  if (!invokesAdr(command, 'new')) return;
+
+  let changed = false;
+  const updated = command.replace(invocationRe('new'), (whole, boundary, ws, envPrefix, adrNew, offset) => {
+    // Both guards, for the same reason the deny hooks use them: a heredoc body
+    // is documentation being written, and injecting a flag into it would
+    // rewrite the file's contents rather than the command.
+    // `offset` is the boundary character; step past it to the word `adr`.
+    const at = offset + boundary.length + ws.length + envPrefix.length;
+    if (isInsideQuotes(command, at) || isInsideHeredoc(command, at)) return whole;
+    if (QUIET.test(flagsRegion(command, at + adrNew.length))) return whole;
+    changed = true;
+    return `${boundary}${ws}${envPrefix}${adrNew} -q`;
+  });
+  if (!changed) return;
+
+  process.stdout.write(
+    JSON.stringify({
+      systemMessage: 'Added -q to `adr new` — without it an ambiguous -s prompts on stdin and hangs.',
+      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/adr/command-scan.cjs

@@ -22,9 +22,17 @@
 // false one blocks an unrelated command for a reason nobody can guess.
 
 // boundary/start, whitespace, any existing KEY=value prefix, then `adr <sub>`.
+//
+// The subcommand must not run straight into a word character or a hyphen. `\b`
+// alone is not enough: it sits happily between the `w` of `new` and the `-` of
+// `adr new-thing`, so that string would count as an `adr new` invocation. A hook
+// that only reads the command could shrug that off, but inject-adr-flags writes
+// the flag directly after the subcommand and would turn it into `adr new -q-thing`.
+// A trailing `;` or `|` still has to count, so this is a negated class rather
+// than a required space.
 function invocationRe(sub) {
   return new RegExp(
-    `(^|[;&|\\n(){}])([ \\t]*)((?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\\S*)[ \\t]+)*)(adr[ \\t]+${sub}\\b)`,
+    `(^|[;&|\\n(){}])([ \\t]*)((?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\\S*)[ \\t]+)*)(adr[ \\t]+${sub})(?![\\w-])`,
     'g'
   );
 }

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

@@ -6,6 +6,11 @@
 // 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 deletes the tool's own `decisions.md`. Every `adr new` regenerates that
+// file unconditionally (not just on `adr generate toc`), which would leave two
+// competing indexes side by side in the same directory. README.md is the richer
+// one — it carries a status column — so it is the one kept.
+//
 // Also runnable directly:  node sync-adr-toc.cjs --write
 //
 // Fails open at exit 0 on any problem — a hook must never block a session.
@@ -16,7 +21,7 @@ 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`).
+// The tool 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';
@@ -25,8 +30,8 @@ function adrDir() {
   }
 }
 
-// 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.)
+// Was this Bash call an adr command? (`adr new -q …` counts; a hyphenated name
+// such as `adr-new` does not, hence the required whitespace.)
 function isAdrCommand() {
   try {
     const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
@@ -36,8 +41,9 @@ function isAdrCommand() {
   }
 }
 
-// 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
+// First line, minus the leading "# " and the tool's own number prefix — the
+// template renders "# 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) {
@@ -45,8 +51,8 @@ function title(body, fallback) {
   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`.
+// First non-empty line of the `## Status` section. The tool maintains this:
+// "Accepted", or "Superseded 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));
@@ -78,10 +84,39 @@ function render(dir, files) {
   ].join('\n');
 }
 
+// The tool writes its own table of contents to `<adr-dir>/decisions.md` on every
+// `adr new`. README.md supersedes it, so drop it rather than commit two indexes
+// that have to agree with each other.
+//
+// Only ever deletes a file that is recognisably that generated index: the exact
+// heading it writes, followed by nothing but link lines. `decisions.md` is an
+// ordinary name for a hand-written decision log, and deleting one of those on
+// the next `adr new` would destroy work no backup covers.
+const GENERATED_TOC = /^# Table of Contents\r?\n\r?\n(?:- \[[^\]]*\]\([^)]*\)\r?\n?)*$/;
+
+function removeRedundantToc(dir) {
+  const stale = path.join(root, dir, 'decisions.md');
+  try {
+    if (!fs.existsSync(stale)) return;
+    if (!GENERATED_TOC.test(fs.readFileSync(stale, 'utf8'))) {
+      process.stdout.write(
+        `Left ${dir}/decisions.md alone — it is not the generated index. ` +
+          'README.md is the one this hook maintains.\n'
+      );
+      return;
+    }
+    fs.unlinkSync(stale);
+    process.stdout.write(`Removed ${dir}/decisions.md (README.md is the index).\n`);
+  } catch {
+    /* not worth failing the hook over */
+  }
+}
+
 function main() {
   if (!process.argv.includes('--write') && !isAdrCommand()) return;
 
   const dir = adrDir();
+  removeRedundantToc(dir);
   const files = fs
     .readdirSync(path.join(root, dir))
     .filter((f) => ADR_FILE.test(f))