@phuc1403/musketeer 0.8.0 → 0.10.0

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

@@ -1,85 +1,85 @@
-#!/usr/bin/env node
-// PreToolUse guard: block an `adr new` title the tool cannot render safely.
-//
-// 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.
-//
-// 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");
-
-let raw = "";
-process.stdin.on("data", (chunk) => (raw += chunk));
-process.stdin.on("end", () => {
-  let input;
-  try {
-    input = JSON.parse(raw || "{}");
-  } catch {
-    process.exit(0); // unparseable payload — fail open, don't block legit work
-  }
-
-  const command = (input && input.tool_input && input.tool_input.command) || "";
-  if (!invokesAdr(command, "new")) process.exit(0);
-
-  // The skill always places `--` immediately before a quoted title. Extract
-  // that argument; anything else about the command's shape is not this hook's
-  // concern.
-  const afterDashDash = command.match(/--\s+(["'])((?:(?!\1).)*)\1/);
-  const title = afterDashDash ? afterDashDash[2] : null;
-
-  let reason = null;
-  if (!afterDashDash) {
-    reason =
-      "no `--` before the title (or no quoted title found after it). Without `--`, " +
-      "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 `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) {
-    process.stdout.write(
-      JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "PreToolUse",
-          permissionDecision: "deny",
-          permissionDecisionReason: `Refusing this \`adr new\` call: ${reason} Rename the title and retry.`,
-        },
-      })
-    );
-  }
-  process.exit(0);
-});
+#!/usr/bin/env node
+// PreToolUse guard: block an `adr new` title the tool cannot render safely.
+//
+// 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.
+//
+// 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");
+
+let raw = "";
+process.stdin.on("data", (chunk) => (raw += chunk));
+process.stdin.on("end", () => {
+  let input;
+  try {
+    input = JSON.parse(raw || "{}");
+  } catch {
+    process.exit(0); // unparseable payload — fail open, don't block legit work
+  }
+
+  const command = (input && input.tool_input && input.tool_input.command) || "";
+  if (!invokesAdr(command, "new")) process.exit(0);
+
+  // The skill always places `--` immediately before a quoted title. Extract
+  // that argument; anything else about the command's shape is not this hook's
+  // concern.
+  const afterDashDash = command.match(/--\s+(["'])((?:(?!\1).)*)\1/);
+  const title = afterDashDash ? afterDashDash[2] : null;
+
+  let reason = null;
+  if (!afterDashDash) {
+    reason =
+      "no `--` before the title (or no quoted title found after it). Without `--`, " +
+      "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 `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) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: `Refusing this \`adr new\` call: ${reason} Rename the title and retry.`,
+        },
+      })
+    );
+  }
+  process.exit(0);
+});

package/template/.claude/hooks/git-skill-reminder.cjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// PreToolUse hook (core company): make the ck:git skill load on git work.
+//
+// Skill auto-activation is a model judgement, not enforcement — the agent
+// routinely runs `git commit` / `git push` straight through Bash without ever
+// opening the skill, so its conventional-commit format, split rules and secret
+// scan are silently skipped. A description alone cannot fix that; only a hook
+// runs every time.
+//
+// Fires on state-changing git/gh operations only. Read-only commands (status,
+// log, diff, show) are skipped so the reminder does not burn context on every
+// incidental `git status`.
+//
+// Matches mid-command too (`cd repo && git push`), since the operation is
+// often not the first word.
+//
+// Always exits 0: this advises, it never blocks.
+
+const fs = require("fs");
+
+const SKILL = ".claude/skills/git/SKILL.md";
+
+// Mutating git verbs, plus the gh surfaces the skill covers.
+const GIT_OPS =
+  /(^|[\s;&|(])(git\s+(commit|push|merge|rebase|tag|revert|reset|cherry-pick|switch|checkout|branch|remote|stash)|gh\s+(pr|release|repo))\b/;
+
+function isGitOperation(command) {
+  if (!command || typeof command !== "string") return false;
+  return GIT_OPS.test(command);
+}
+
+try {
+  const payload = JSON.parse(fs.readFileSync(0, "utf-8"));
+  const command = payload?.tool_input?.command || "";
+
+  if (!isGitOperation(command)) process.exit(0);
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext:
+          `This is a git operation. Read ${SKILL} (the ck:git skill) and follow it — its ` +
+          "conventional-commit format, commit-splitting rules, secret scan and branch " +
+          "protections are project policy, not suggestions. Do that before running the " +
+          "command; if you have already read it this session, carry on.",
+      },
+    })
+  );
+  process.exit(0);
+} catch {
+  process.exit(0); // fail open — never block a command over a reminder
+}

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

@@ -1,173 +1,173 @@
-#!/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.
-// 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.
-// 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 { invokesAdr } = require('./lib/adr/command-scan.cjs');
-
-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');
-  process.exit(0);
-}
-
-function deny(reason) {
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'deny',
-        permissionDecisionReason: reason,
-      },
-    })
-  );
-  process.exit(0);
-}
-
-function readAdrDir() {
-  try {
-    return fs.readFileSync(ADR_DIR_FILE, 'utf8').trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-function isInitialized() {
-  return readAdrDir() !== null;
-}
-
-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() {
-  // `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' });
-}
-
-// `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();
-  if (!declared) return;
-  fs.writeFileSync(ADR_DIR_FILE, `${declared.split(path.sep).join('/')}\n`);
-}
-
-// 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() {
-  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
-  const command = payload?.tool_input?.command || '';
-  const isInit = invokesAdr(command, 'init');
-  const isNew = invokesAdr(command, 'new');
-  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(ensureTemplate()); // adr new, already set up: nothing else 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`);
-    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.'
-    );
-  }
-  normalizeAdrDirFile();
-  const note = ensureTemplate();
-  return allow(
-    `Fresh project: ran \`adr init ${ADR_DIR}\` (creates the baseline ADR).` +
-      (note ? `\n${note}` : '')
-  );
-}
-
-try {
-  main();
-} catch {
-  allow(); // fail open
-}
+#!/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.
+// 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.
+// 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 { invokesAdr } = require('./lib/adr/command-scan.cjs');
+
+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');
+  process.exit(0);
+}
+
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    })
+  );
+  process.exit(0);
+}
+
+function readAdrDir() {
+  try {
+    return fs.readFileSync(ADR_DIR_FILE, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function isInitialized() {
+  return readAdrDir() !== null;
+}
+
+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() {
+  // `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' });
+}
+
+// `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();
+  if (!declared) return;
+  fs.writeFileSync(ADR_DIR_FILE, `${declared.split(path.sep).join('/')}\n`);
+}
+
+// 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() {
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const command = payload?.tool_input?.command || '';
+  const isInit = invokesAdr(command, 'init');
+  const isNew = invokesAdr(command, 'new');
+  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(ensureTemplate()); // adr new, already set up: nothing else 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`);
+    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.'
+    );
+  }
+  normalizeAdrDirFile();
+  const note = ensureTemplate();
+  return allow(
+    `Fresh project: ran \`adr init ${ADR_DIR}\` (creates the baseline ADR).` +
+      (note ? `\n${note}` : '')
+  );
+}
+
+try {
+  main();
+} catch {
+  allow(); // fail open
+}