@phuc1403/musketeer 0.8.0 → 0.10.0

package/template/.claude/hooks/validate-characteristics-hook.cjs

@@ -1,66 +1,66 @@
-#!/usr/bin/env node
-// PostToolUse validation hook for the two architecture-characteristic documents.
-//
-// .claude/settings.json calls this after every Write/Edit/MultiEdit. If the
-// edited file is the ranking or the worksheet, both are checked together — the
-// worksheet is a derivation of the ranking, so neither can be judged alone.
-//
-// Hook exit-code contract:
-//   exit 0 -> ok (stdout shown in transcript)
-//   exit 2 -> blocking error (stderr fed back to Claude to fix)
-// An unrelated edit, a missing file, or an unparseable payload all exit 0.
-//
-// Only structure is checked. The ranking ORDER is the architect's call and is
-// never second-guessed here.
-
-const fs = require('fs');
-const path = require('path');
-
-const RANKING = 'docs/architecture-characteristics-ranking.md';
-const WORKSHEET = 'docs/architecture-characteristics.md';
-
-function read(root, rel) {
-  try {
-    return fs.readFileSync(path.join(root, rel), 'utf8');
-  } catch {
-    return null;
-  }
-}
-
-try {
-  const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
-  const edited = payload?.tool_input?.file_path;
-
-  if (!edited) process.exit(0);
-
-  // Windows resolves paths case-insensitively, so the same document can arrive
-  // spelled several ways. Comparing case-sensitively there would let an edit
-  // slip past the gate unchecked, which is worse than checking one file twice.
-  const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
-  const rel = path.relative(root, path.resolve(root, edited)).split(path.sep).join('/');
-  if (fold(rel) !== fold(RANKING) && fold(rel) !== fold(WORKSHEET)) process.exit(0);
-
-  const { check } = require('./lib/characteristics/checker.cjs');
-  const ranking = read(root, RANKING);
-
-  // Editing the ranking alone, before any worksheet exists, is the normal path
-  // through Phase A: `read` returns null and the worksheet rules stay quiet.
-  const worksheet = read(root, WORKSHEET);
-
-  const errors = check({ ranking, worksheet });
-
-  if (errors.length) {
-    process.stderr.write(
-      `Architecture characteristics: ${errors.length} structural problem(s) in ${rel}\n\n` +
-        errors.map((e) => `  - ${e}`).join('\n') +
-        '\n\nFix the file. These are mechanical rules, not judgement calls: the ranking must ' +
-        'cover the catalog exactly once each, every Reason must name the row directly below it, ' +
-        'and the worksheet must derive from the top 7.\n'
-    );
-    process.exit(2);
-  }
-} catch {
-  /* fail open — a structure checker must never be the thing that breaks a session */
-}
-process.exit(0);
+#!/usr/bin/env node
+// PostToolUse validation hook for the two architecture-characteristic documents.
+//
+// .claude/settings.json calls this after every Write/Edit/MultiEdit. If the
+// edited file is the ranking or the worksheet, both are checked together — the
+// worksheet is a derivation of the ranking, so neither can be judged alone.
+//
+// Hook exit-code contract:
+//   exit 0 -> ok (stdout shown in transcript)
+//   exit 2 -> blocking error (stderr fed back to Claude to fix)
+// An unrelated edit, a missing file, or an unparseable payload all exit 0.
+//
+// Only structure is checked. The ranking ORDER is the architect's call and is
+// never second-guessed here.
+
+const fs = require('fs');
+const path = require('path');
+
+const RANKING = 'docs/architecture-characteristics-ranking.md';
+const WORKSHEET = 'docs/architecture-characteristics.md';
+
+function read(root, rel) {
+  try {
+    return fs.readFileSync(path.join(root, rel), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+try {
+  const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const edited = payload?.tool_input?.file_path;
+
+  if (!edited) process.exit(0);
+
+  // Windows resolves paths case-insensitively, so the same document can arrive
+  // spelled several ways. Comparing case-sensitively there would let an edit
+  // slip past the gate unchecked, which is worse than checking one file twice.
+  const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+  const rel = path.relative(root, path.resolve(root, edited)).split(path.sep).join('/');
+  if (fold(rel) !== fold(RANKING) && fold(rel) !== fold(WORKSHEET)) process.exit(0);
+
+  const { check } = require('./lib/characteristics/checker.cjs');
+  const ranking = read(root, RANKING);
+
+  // Editing the ranking alone, before any worksheet exists, is the normal path
+  // through Phase A: `read` returns null and the worksheet rules stay quiet.
+  const worksheet = read(root, WORKSHEET);
+
+  const errors = check({ ranking, worksheet });
+
+  if (errors.length) {
+    process.stderr.write(
+      `Architecture characteristics: ${errors.length} structural problem(s) in ${rel}\n\n` +
+        errors.map((e) => `  - ${e}`).join('\n') +
+        '\n\nFix the file. These are mechanical rules, not judgement calls: the ranking must ' +
+        'cover the catalog exactly once each, every Reason must name the row directly below it, ' +
+        'and the worksheet must derive from the top 7.\n'
+    );
+    process.exit(2);
+  }
+} catch {
+  /* fail open — a structure checker must never be the thing that breaks a session */
+}
+process.exit(0);

package/template/.claude/hooks/validate-cml-hook.js

@@ -1,145 +1,145 @@
-#!/usr/bin/env node
-// PostToolUse validation hook for Context Mapper `.cml` files (cross-platform).
-//
-// .claude/settings.json calls this as `node validate-cml-hook.js` after every
-// Write/Edit. It
-// reads the PostToolUse payload from stdin, and if the edited file is a .cml,
-// validates it with the Context Mapper CLI and speaks the hook exit-code
-// contract:
-//   exit 0 -> ok (stdout shown in transcript)
-//   exit 2 -> blocking error (stderr fed back to Claude to fix)
-// A non-.cml edit / missing file / unparseable payload all exit 0.
-//
-// Bootstrap installs Context Mapper CLI 6.12+ into ~/.context-mapper-cli/ (Java
-// 8+ required) on first run. The run path is unified (java -classpath <lib>/*
-// MainClass); only archive extraction branches by platform. Override the
-// install location with CONTEXT_MAPPER_HOME.
-
-const os = require('os');
-const path = require('path');
-const fs = require('fs');
-const { spawnSync } = require('child_process');
-
-const VERSION = '6.12.0';
-const MAIN_CLASS = 'org.contextmapper.cli.ContextMapperCLI';
-const isWin = process.platform === 'win32';
-const installDir = process.env.CONTEXT_MAPPER_HOME || path.join(os.homedir(), '.context-mapper-cli');
-const distDir = path.join(installDir, `context-mapper-cli-${VERSION}`);
-const libDir = path.join(distDir, 'lib');
-
-function fail(code, msg) {
-  process.stderr.write(msg + '\n');
-  process.exit(code);
-}
-
-function isInstalled() {
-  try {
-    return fs.readdirSync(libDir).some((f) => f.endsWith('.jar'));
-  } catch {
-    return false;
-  }
-}
-
-function hasJava() {
-  const r = spawnSync('java', ['-version'], { stdio: 'ignore' });
-  return !r.error && r.status === 0;
-}
-
-async function bootstrap() {
-  if (!hasJava()) fail(2, 'Java 8+ is required (e.g. Temurin LTS). Install Java, then retry.');
-
-  process.stderr.write(`Bootstrapping Context Mapper CLI ${VERSION} into ${installDir} ...\n`);
-  fs.mkdirSync(installDir, { recursive: true });
-
-  // Extraction must be platform-specific: Windows `tar` (Git's GNU tar) cannot
-  // read .zip and mangles `C:\` paths as remote host:path, so we use the .zip +
-  // Expand-Archive there, and the .tar + `tar` on macOS/Linux. The run path
-  // (java -classpath) stays unified.
-  const ext = isWin ? 'zip' : 'tar';
-  const archive = path.join(installDir, `cli-${VERSION}.${ext}`);
-  const url = `https://repo1.maven.org/maven2/org/contextmapper/context-mapper-cli/${VERSION}/context-mapper-cli-${VERSION}.${ext}`;
-
-  let res;
-  try {
-    res = await fetch(url);
-  } catch (e) {
-    fail(3, `Download failed: ${e.message}\nURL: ${url}`);
-  }
-  if (!res.ok) fail(3, `Download failed: HTTP ${res.status}\nURL: ${url}`);
-  fs.writeFileSync(archive, Buffer.from(await res.arrayBuffer()));
-
-  const ex = isWin
-    ? spawnSync('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command',
-        `Expand-Archive -LiteralPath '${archive}' -DestinationPath '${installDir}' -Force`], { stdio: 'inherit' })
-    : spawnSync('tar', ['-xf', archive, '-C', installDir], { stdio: 'inherit' });
-  if (ex.error || ex.status !== 0) {
-    fail(4, `Extraction failed. Inspect ${installDir} manually.`);
-  }
-  fs.rmSync(archive, { force: true });
-
-  if (!isInstalled()) fail(4, `Bootstrap failed: no jars under ${libDir} after extract. Inspect ${installDir} manually.`);
-}
-
-// Run the CLI's main class and capture its output. The JVM expands the `lib/*`
-// wildcard itself, so we pass it as one literal classpath entry (no shell -> no
-// shell glob expansion).
-function runJava(args, cwd) {
-  const classpath = path.join(libDir, '*');
-  const res = spawnSync('java', ['-classpath', classpath, MAIN_CLASS, ...args], {
-    cwd,
-    stdio: 'pipe',
-    encoding: 'utf8',
-  });
-  if (res.error) {
-    if (res.error.code === 'ENOENT') fail(2, 'Java 8+ is required (e.g. Temurin LTS). Install Java, then retry.');
-    fail(1, `Failed to launch java: ${res.error.message}`);
-  }
-  return res;
-}
-
-// --- Hook mode: validate the .cml named in a PostToolUse stdin payload -------
-function runHook() {
-  let raw = '';
-  try {
-    raw = fs.readFileSync(0, 'utf8'); // fd 0 = stdin
-  } catch {
-    process.exit(0);
-  }
-  if (!raw.trim()) process.exit(0);
-
-  let payload;
-  try {
-    payload = JSON.parse(raw);
-  } catch {
-    process.exit(0); // nothing actionable
-  }
-
-  const filePath = payload?.tool_input?.file_path;
-  if (!filePath || !/\.cml$/i.test(filePath) || !fs.existsSync(filePath)) {
-    process.exit(0);
-  }
-
-  const name = path.basename(filePath);
-  // cwd = the file's directory so the bare filename resolves (relative-path gotcha).
-  const res = runJava(['validate', '-i', name], path.dirname(filePath));
-  const output = `${res.stdout || ''}${res.stderr || ''}`.trim();
-
-  // Two failure modes: parse failures throw a Java exception and exit non-zero;
-  // semantic-validation failures print uppercase "ERROR ..." lines (possibly
-  // while still exiting 0). Match ERROR case-sensitively so the success line
-  // ("...without errors.") is not a false positive; WARNING lines (intentional
-  // ACL, or JVM sun.misc.Unsafe deprecation noise) are allowed.
-  const hasErrorLine = output.split(/\r?\n/).some((l) => /ERROR/.test(l));
-
-  if (res.status !== 0 || hasErrorLine) {
-    process.stderr.write(`CML validation FAILED for ${name}\n${output}\n`);
-    process.exit(2);
-  }
-  process.stdout.write(`CML validation passed for ${name}\n${output}\n`);
-  process.exit(0);
-}
-
-(async () => {
-  if (!isInstalled()) await bootstrap();
-  runHook();
-})();
+#!/usr/bin/env node
+// PostToolUse validation hook for Context Mapper `.cml` files (cross-platform).
+//
+// .claude/settings.json calls this as `node validate-cml-hook.js` after every
+// Write/Edit. It
+// reads the PostToolUse payload from stdin, and if the edited file is a .cml,
+// validates it with the Context Mapper CLI and speaks the hook exit-code
+// contract:
+//   exit 0 -> ok (stdout shown in transcript)
+//   exit 2 -> blocking error (stderr fed back to Claude to fix)
+// A non-.cml edit / missing file / unparseable payload all exit 0.
+//
+// Bootstrap installs Context Mapper CLI 6.12+ into ~/.context-mapper-cli/ (Java
+// 8+ required) on first run. The run path is unified (java -classpath <lib>/*
+// MainClass); only archive extraction branches by platform. Override the
+// install location with CONTEXT_MAPPER_HOME.
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const VERSION = '6.12.0';
+const MAIN_CLASS = 'org.contextmapper.cli.ContextMapperCLI';
+const isWin = process.platform === 'win32';
+const installDir = process.env.CONTEXT_MAPPER_HOME || path.join(os.homedir(), '.context-mapper-cli');
+const distDir = path.join(installDir, `context-mapper-cli-${VERSION}`);
+const libDir = path.join(distDir, 'lib');
+
+function fail(code, msg) {
+  process.stderr.write(msg + '\n');
+  process.exit(code);
+}
+
+function isInstalled() {
+  try {
+    return fs.readdirSync(libDir).some((f) => f.endsWith('.jar'));
+  } catch {
+    return false;
+  }
+}
+
+function hasJava() {
+  const r = spawnSync('java', ['-version'], { stdio: 'ignore' });
+  return !r.error && r.status === 0;
+}
+
+async function bootstrap() {
+  if (!hasJava()) fail(2, 'Java 8+ is required (e.g. Temurin LTS). Install Java, then retry.');
+
+  process.stderr.write(`Bootstrapping Context Mapper CLI ${VERSION} into ${installDir} ...\n`);
+  fs.mkdirSync(installDir, { recursive: true });
+
+  // Extraction must be platform-specific: Windows `tar` (Git's GNU tar) cannot
+  // read .zip and mangles `C:\` paths as remote host:path, so we use the .zip +
+  // Expand-Archive there, and the .tar + `tar` on macOS/Linux. The run path
+  // (java -classpath) stays unified.
+  const ext = isWin ? 'zip' : 'tar';
+  const archive = path.join(installDir, `cli-${VERSION}.${ext}`);
+  const url = `https://repo1.maven.org/maven2/org/contextmapper/context-mapper-cli/${VERSION}/context-mapper-cli-${VERSION}.${ext}`;
+
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (e) {
+    fail(3, `Download failed: ${e.message}\nURL: ${url}`);
+  }
+  if (!res.ok) fail(3, `Download failed: HTTP ${res.status}\nURL: ${url}`);
+  fs.writeFileSync(archive, Buffer.from(await res.arrayBuffer()));
+
+  const ex = isWin
+    ? spawnSync('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command',
+        `Expand-Archive -LiteralPath '${archive}' -DestinationPath '${installDir}' -Force`], { stdio: 'inherit' })
+    : spawnSync('tar', ['-xf', archive, '-C', installDir], { stdio: 'inherit' });
+  if (ex.error || ex.status !== 0) {
+    fail(4, `Extraction failed. Inspect ${installDir} manually.`);
+  }
+  fs.rmSync(archive, { force: true });
+
+  if (!isInstalled()) fail(4, `Bootstrap failed: no jars under ${libDir} after extract. Inspect ${installDir} manually.`);
+}
+
+// Run the CLI's main class and capture its output. The JVM expands the `lib/*`
+// wildcard itself, so we pass it as one literal classpath entry (no shell -> no
+// shell glob expansion).
+function runJava(args, cwd) {
+  const classpath = path.join(libDir, '*');
+  const res = spawnSync('java', ['-classpath', classpath, MAIN_CLASS, ...args], {
+    cwd,
+    stdio: 'pipe',
+    encoding: 'utf8',
+  });
+  if (res.error) {
+    if (res.error.code === 'ENOENT') fail(2, 'Java 8+ is required (e.g. Temurin LTS). Install Java, then retry.');
+    fail(1, `Failed to launch java: ${res.error.message}`);
+  }
+  return res;
+}
+
+// --- Hook mode: validate the .cml named in a PostToolUse stdin payload -------
+function runHook() {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf8'); // fd 0 = stdin
+  } catch {
+    process.exit(0);
+  }
+  if (!raw.trim()) process.exit(0);
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0); // nothing actionable
+  }
+
+  const filePath = payload?.tool_input?.file_path;
+  if (!filePath || !/\.cml$/i.test(filePath) || !fs.existsSync(filePath)) {
+    process.exit(0);
+  }
+
+  const name = path.basename(filePath);
+  // cwd = the file's directory so the bare filename resolves (relative-path gotcha).
+  const res = runJava(['validate', '-i', name], path.dirname(filePath));
+  const output = `${res.stdout || ''}${res.stderr || ''}`.trim();
+
+  // Two failure modes: parse failures throw a Java exception and exit non-zero;
+  // semantic-validation failures print uppercase "ERROR ..." lines (possibly
+  // while still exiting 0). Match ERROR case-sensitively so the success line
+  // ("...without errors.") is not a false positive; WARNING lines (intentional
+  // ACL, or JVM sun.misc.Unsafe deprecation noise) are allowed.
+  const hasErrorLine = output.split(/\r?\n/).some((l) => /ERROR/.test(l));
+
+  if (res.status !== 0 || hasErrorLine) {
+    process.stderr.write(`CML validation FAILED for ${name}\n${output}\n`);
+    process.exit(2);
+  }
+  process.stdout.write(`CML validation passed for ${name}\n${output}\n`);
+  process.exit(0);
+}
+
+(async () => {
+  if (!isInstalled()) await bootstrap();
+  runHook();
+})();

package/template/.claude/skills/adr-writer/SKILL.md

@@ -1,48 +1,48 @@
----
-name: adr-writer
-description: Write and manage Architecture Decision Records (ADRs) following structured methodology with proper numbering, status tracking, governance, and conversational writing style.
----
-
-# ADR Writer
-
-Write Architecture Decision Records — the log of "architecturally significant" decisions affecting structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
-
-**Scope:** Create, update, and supersede ADRs. Does NOT implement the decisions themselves.
-
-## Workflow
-
-1. **Read the context.** `docs/architecture-characteristics.md` — every Decision is justified against these, with trade-offs framed as which are favored vs. sacrificed. If it is missing, read `.claude/skills/architecture-characteristic-writer/SKILL.md` and use its questions to gather the driving characteristics from the user before going on. Then read `docs/adr/README.md` for the decisions already recorded — one ADR's Consequences are often the next one's Context.
-
-2. **Research before suggesting** — REQUIRED whenever a technology, vendor, product, version, or price is in play. Invoke `/research`; never propose options from memory, it goes stale. Confirm each option still exists and is supported today. Report in one pass, source and verdict per option.
-
-3. **Challenge the proposal — be harsh.** REQUIRED whenever the user proposes a specific option. Do not rubber-stamp it:
-   - **State why** — the concrete reasons, not familiarity or preference.
-   - **Score it against each driving and implicit characteristic** — does it *serve*, *ignore*, or *actively harm* it?
-   - **Give a verdict** — suitable / suitable-with-trade-offs / unsuitable. If it conflicts with a driving characteristic, say so plainly and recommend the better fit, even when that is not what was asked for.
-   - Continue only once it survives, or the user overrides knowing the trade-off — record that override as a Consequence.
-
-4. **Create the file.** From the repo root:
-   ```bash
-   adr new -q -- "Use X for Z"
-   ```
-   - `-q` is required on every call. Without it an ambiguous `-s` prompts on stdin and hangs the session; with it, that case errors instead.
-   - `adr new` prints nothing. Run `adr list` (last line is the new file) or read `docs/adr/README.md` — never guess the number or slug.
-   - Never use uppercase `STATUS` in a title. It is substituted after the title is inserted, so "Use STATUS codes" silently becomes "Use Accepted codes" and leaves the real Status unset. Lowercase is fine.
-   - Superseding — always the full padded stem, never a bare number. `-s` matches by substring: with `-q` an *ambiguous* match errors, but a single *wrong* match still succeeds silently. Writes the cross-link into both ADRs' `## Status`:
-     ```bash
-     adr new -q -s 0002-use-mysql-for-persistence -- "…"
-     ```
-
-5. **Write the ADR.** Replace every `{…}` placeholder — nothing else. `adr new` has already written the number, title, `Accepted` status, and any supersede/link lines; leave all of them alone. Section Guidance below covers what each section needs. An Accepted ADR is immutable — to change it, write a new ADR that supersedes it.
-
-## Writing Style
-
-- **Calibrate against `references/adr-example.md`** — re-read it before drafting; it is the target for terseness. Cut any section markedly longer than its equivalent.
-- **Match `references/adr-template.md` exactly.** Use only the sections it defines. No invented sections or fields; research citations go inline in the Decision.
-
-## Section Guidance
-
-- **Title** — reveal the *decision*, not the topic: "Use X for Z". Bad: "Gmail Polling for Ingestion". Good: "Use Cloud Scheduler Polling for Gmail Ingestion".
-- **Context** — value-neutral, tensions explicit. No alternatives here, and no notes about what is *not* being decided.
-- **Decision** — record the WHY, not the HOW — omit libraries, drivers, and wiring.
-- **Consequences** — both `### Positive` and `### Negative` required. Consider team, infrastructure, cost, and one-way doors.
+---
+name: adr-writer
+description: Write and manage Architecture Decision Records (ADRs) following structured methodology with proper numbering, status tracking, governance, and conversational writing style.
+---
+
+# ADR Writer
+
+Write Architecture Decision Records — the log of "architecturally significant" decisions affecting structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
+
+**Scope:** Create, update, and supersede ADRs. Does NOT implement the decisions themselves.
+
+## Workflow
+
+1. **Read the context.** `docs/architecture-characteristics.md` — every Decision is justified against these, with trade-offs framed as which are favored vs. sacrificed. If it is missing, read `.claude/skills/architecture-characteristic-writer/SKILL.md` and use its questions to gather the driving characteristics from the user before going on. Then read `docs/adr/README.md` for the decisions already recorded — one ADR's Consequences are often the next one's Context.
+
+2. **Research before suggesting** — REQUIRED whenever a technology, vendor, product, version, or price is in play. Invoke `/research`; never propose options from memory, it goes stale. Confirm each option still exists and is supported today. Report in one pass, source and verdict per option.
+
+3. **Challenge the proposal — be harsh.** REQUIRED whenever the user proposes a specific option. Do not rubber-stamp it:
+   - **State why** — the concrete reasons, not familiarity or preference.
+   - **Score it against each driving and implicit characteristic** — does it *serve*, *ignore*, or *actively harm* it?
+   - **Give a verdict** — suitable / suitable-with-trade-offs / unsuitable. If it conflicts with a driving characteristic, say so plainly and recommend the better fit, even when that is not what was asked for.
+   - Continue only once it survives, or the user overrides knowing the trade-off — record that override as a Consequence.
+
+4. **Create the file.** From the repo root:
+   ```bash
+   adr new -q -- "Use X for Z"
+   ```
+   - `-q` is required on every call. Without it an ambiguous `-s` prompts on stdin and hangs the session; with it, that case errors instead.
+   - `adr new` prints nothing. Run `adr list` (last line is the new file) or read `docs/adr/README.md` — never guess the number or slug.
+   - Never use uppercase `STATUS` in a title. It is substituted after the title is inserted, so "Use STATUS codes" silently becomes "Use Accepted codes" and leaves the real Status unset. Lowercase is fine.
+   - Superseding — always the full padded stem, never a bare number. `-s` matches by substring: with `-q` an *ambiguous* match errors, but a single *wrong* match still succeeds silently. Writes the cross-link into both ADRs' `## Status`:
+     ```bash
+     adr new -q -s 0002-use-mysql-for-persistence -- "…"
+     ```
+
+5. **Write the ADR.** Replace every `{…}` placeholder — nothing else. `adr new` has already written the number, title, `Accepted` status, and any supersede/link lines; leave all of them alone. Section Guidance below covers what each section needs. An Accepted ADR is immutable — to change it, write a new ADR that supersedes it.
+
+## Writing Style
+
+- **Calibrate against `references/adr-example.md`** — re-read it before drafting; it is the target for terseness. Cut any section markedly longer than its equivalent.
+- **Match `references/adr-template.md` exactly.** Use only the sections it defines. No invented sections or fields; research citations go inline in the Decision.
+
+## Section Guidance
+
+- **Title** — reveal the *decision*, not the topic: "Use X for Z". Bad: "Gmail Polling for Ingestion". Good: "Use Cloud Scheduler Polling for Gmail Ingestion".
+- **Context** — value-neutral, tensions explicit. No alternatives here, and no notes about what is *not* being decided.
+- **Decision** — record the WHY, not the HOW — omit libraries, drivers, and wiring.
+- **Consequences** — both `### Positive` and `### Negative` required. Consider team, infrastructure, cost, and one-way doors.

package/template/.claude/skills/adr-writer/references/adr-example.md

@@ -1,35 +1,35 @@
-# ADR Example
-
-Reference example of a well-written ADR.
-
-Filename: docs/adr/0012-use-of-queues-for-asynchronous-messaging-between-order-and-downstream-services.md — heading number unpadded, filename four-digit padded.
-
-```markdown
-# 12: Use of Queues for Asynchronous Messaging Between Order and Downstream Services
-
-## Status
-Accepted
-
-## Context
-The trading service must inform downstream services (namely the notification and analytics services, for now) about new items available for sale and about all transactions. This can be done through synchronous messaging (using REST) or asynchronous messaging (using queues or topics).
-
-## Decision
-We will use queues for asynchronous messaging between the trading and downstream services.
-
-Using queues makes the system more extensible, since each queue can deliver a different kind of message. Furthermore, since the trading service is acutely aware of any and all subscribers, adding a new consumer involves modifying it — which improves the security of the system.
-
-## Consequences
-
-### Positive
-- System is more extensible via separate queues per message type
-- Security improved — trading service controls subscriber access
-
-### Negative
-- Higher degree of coupling between services
-- Queuing infrastructure must be provisioned and clustered for HA
-- Adding new downstream services requires modifications to trading service
-
-## Governance
-- Code reviews on all queue consumer/producer changes
-- Infrastructure monitoring for queue health and message delivery
-
+# ADR Example
+
+Reference example of a well-written ADR.
+
+Filename: docs/adr/0012-use-of-queues-for-asynchronous-messaging-between-order-and-downstream-services.md — heading number unpadded, filename four-digit padded.
+
+```markdown
+# 12: Use of Queues for Asynchronous Messaging Between Order and Downstream Services
+
+## Status
+Accepted
+
+## Context
+The trading service must inform downstream services (namely the notification and analytics services, for now) about new items available for sale and about all transactions. This can be done through synchronous messaging (using REST) or asynchronous messaging (using queues or topics).
+
+## Decision
+We will use queues for asynchronous messaging between the trading and downstream services.
+
+Using queues makes the system more extensible, since each queue can deliver a different kind of message. Furthermore, since the trading service is acutely aware of any and all subscribers, adding a new consumer involves modifying it — which improves the security of the system.
+
+## Consequences
+
+### Positive
+- System is more extensible via separate queues per message type
+- Security improved — trading service controls subscriber access
+
+### Negative
+- Higher degree of coupling between services
+- Queuing infrastructure must be provisioned and clustered for HA
+- Adding new downstream services requires modifications to trading service
+
+## Governance
+- Code reviews on all queue consumer/producer changes
+- Infrastructure monitoring for queue health and message delivery
+