@vpxa/aikit 0.1.214 → 0.1.215

package/scaffold/dist/definitions/skills/adr-skill.mjs

@@ -137,39 +137,33 @@ decision-makers: '{list everyone who owns the decision}'
 
 ## Directory
 
-If the repo already has an ADR directory, keep it.
+If repo already has ADR dir, keep it.
 
-If the repo has no ADR directory, choose based on project size:
+If not:
 
-- **\`docs/decisions/\`** — MADR default, recommended for projects with existing \`docs/\` structure.
-- **\`adr/\`** — simpler alternative for smaller repos.
+- **\`docs/decisions/\`** — MADR default when repo already uses \`docs/\`.
+- **\`adr/\`** — simpler small-repo default.
 
-Detection order (used by scripts): \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`docs/adrs/\`, \`decisions/\`.
+Detection order: \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`docs/adrs/\`, \`decisions/\`.
 
 ## Filename Conventions
 
 Pattern: \`YYYY-MM-DD-title-with-dashes.md\`
 
-- \`YYYY-MM-DD\` is the ADR creation date (matches the \`date\` frontmatter field).
-- Title uses lowercase, dashes, present-tense imperative verb phrase.
-- Examples: \`2025-06-15-choose-database.md\`, \`2025-07-01-adopt-adrs.md\`
-- Multiple ADRs on the same date are fine — the slug suffix disambiguates them.
-
-If a repo already uses slug-only filenames (no date prefix), follow that convention.
+- Date matches \`date\` frontmatter.
+- Slug: lowercase, dash-separated, imperative verb phrase.
+- Same-day ADRs are fine; slug disambiguates.
+- If repo already uses slug-only filenames, keep that convention.
 
 ## Minimal Sections
 
-At minimum, every ADR must clearly include:
+Every ADR needs:
 
-1. **Context**: why the decision exists now, what constraints/drivers apply.
+1. **Context**: why now; which constraints/drivers apply.
 2. **Decision**: what is chosen.
-3. **Consequences**: what becomes easier/harder, risks, costs, follow-ups.
-
-For agent-first ADRs, also ensure:
+3. **Consequences**: what gets easier/harder, plus risks, costs, follow-ups.
 
-- Constraints are explicit and measurable
-- Non-goals are stated
-- Follow-up tasks are identified
+For agent-first ADRs also state explicit constraints, non-goals, and follow-up tasks.
 
 ## Status Values
 
@@ -187,11 +181,11 @@ Common statuses:
 
 | Status                        | Meaning                                                       |
 | ----------------------------- | ------------------------------------------------------------- |
-| \`proposed\`                    | Under discussion, not yet decided                             |
-| \`accepted\`                    | Decision is active and should be followed                     |
-| \`rejected\`                    | Considered but explicitly not adopted                         |
-| \`deprecated\`                  | Was accepted but no longer applies — explain replacement path |
-| \`superseded by [title](link)\` | Replaced by a newer ADR — always link both ways               |
+| \`proposed\`                    | Under discussion |
+| \`accepted\`                    | Active decision |
+| \`rejected\`                    | Considered, not adopted |
+| \`deprecated\`                  | No longer applies |
+| \`superseded by [title](link)\` | Replaced by newer ADR |
 
 ## YAML Front Matter Fields
 
@@ -200,96 +194,31 @@ Common statuses:
 | \`status\`          | Yes      | Current lifecycle state                                  |
 | \`date\`            | Yes      | Date of last status change (YYYY-MM-DD)                  |
 | \`decision-makers\` | Yes      | People who own the decision                              |
-| \`consulted\`       | No       | Subject-matter experts consulted (two-way communication) |
-| \`informed\`        | No       | Stakeholders kept up-to-date (one-way communication)     |
+| \`consulted\`       | No       | Experts consulted |
+| \`informed\`        | No       | Stakeholders updated |
 
-The \`consulted\` and \`informed\` fields follow the RACI model and are useful for audit trails in larger teams.
+\`consulted\` and \`informed\` follow RACI.
 
 ## Mutability
 
-- Prefer appending new information with a date stamp over rewriting existing content.
-- If a decision is replaced, create a new ADR and explicitly supersede the old one.
-- Status changes and after-action notes are fine to edit in-place.
+- Append dated notes instead of rewriting prior reasoning.
+- If decision changes, create new ADR and supersede old one.
+- Status changes and after-action notes can be edited in place.
 
 ## Categories (Large Projects)
 
-For repos accumulating many ADRs, use subdirectories:
-
-\`\`\`
-contributing/decisions/   # or docs/decisions/
-  backend/
-    2025-06-15-use-postgres.md
-  frontend/
-    2025-06-20-use-react.md
-  infrastructure/
-    2025-07-01-use-terraform.md
-\`\`\`
-
-Date prefixes are local to each category. Choose a categorization scheme early (by architectural layer, by domain, by team) and document it in the index.
-
-Alternative: use tags or a flat structure with a searchable index. Subdirectories are simpler and work with all tools.
+For many ADRs, subdirectories are fine. Date prefixes stay local to category; pick one scheme early and document it in index.
 `},{file:`references/examples.md`,content:`# ADR Examples
 
-These are filled-out examples showing the same decision at two levels of detail. Use these as reference when drafting ADRs — never leave placeholder text in a real ADR.
+Filled examples of same decision at two detail levels. Reference only; never ship placeholder text.
 
 ## Short Version (Simple Template)
 
-\`\`\`markdown
----
-status: accepted
-date: 2025-06-15
-decision-makers: Sarah Chen, Joel
----
-
-# Use SQLite for local development database
-
-## Context and Problem Statement
-
-Our integration tests require a database but currently hit a shared PostgreSQL instance, causing flaky tests from concurrent writes and slow CI (3+ minute setup per run). We need a fast, isolated database for local dev and CI that doesn't require infrastructure provisioning.
-
-## Decision
-
-Use SQLite (via sql.js) for local development and CI test runs. Production remains on PostgreSQL. We'll use a thin data-access layer that abstracts the database engine, tested against both SQLite and PostgreSQL in CI.
-
-Non-goals: we are NOT migrating production to SQLite or building a full ORM abstraction.
-
-## Consequences
-
-- Good, because CI setup drops from 3+ minutes to ~2 seconds (no DB provisioning)
-- Good, because tests are fully isolated — no shared state between runs
-- Good, because developers can run the full test suite offline
-- Bad, because we must maintain compatibility between SQLite and PostgreSQL SQL dialects
-- Bad, because some PostgreSQL-specific features (JSONB operators, array columns) can't be tested locally
-
-## Implementation Plan
-
-- **Affected paths**: \`src/db/client.ts\` (new abstraction layer), \`src/db/sqlite-client.ts\` (new), \`src/db/pg-client.ts\` (refactored from current inline usage), \`tests/setup.ts\`, \`package.json\`
-- **Dependencies**: add \`sql.js@1.x\` and \`@types/sql.js@1.x\` as devDependencies; no production dependency changes
-- **Patterns to follow**: existing repository pattern in \`src/db/repositories/\` — all queries go through repository methods, never raw SQL in business logic
-- **Patterns to avoid**: do not import \`sql.js\` or \`pg\` directly outside \`src/db/\`; do not use PostgreSQL-specific SQL (JSONB operators, \`ANY()\`, array literals) in shared queries
-
-### Verification
-
-- [ ] \`npm test\` passes with \`DB_ENGINE=sqlite\` (default for test env)
-- [ ] \`npm test\` passes with \`DB_ENGINE=postgres\` against a real PostgreSQL instance
-- [ ] No imports of \`sql.js\` or \`pg\` outside \`src/db/\`
-- [ ] CI pipeline total time under 90 seconds (was 5+ minutes)
-- [ ] \`src/db/client.ts\` exports a unified interface used by all repositories
-
-## Alternatives Considered
-
-- Docker PostgreSQL per CI run: Reliable parity, but adds 90s+ startup and requires Docker-in-Docker on CI.
-- In-memory PostgreSQL (pg-mem): Good API compatibility, but incomplete support for our schema (triggers, CTEs) and unmaintained.
-
-## More Information
-
-- Follow-up: create weekly CI job running full suite against real PostgreSQL (#348)
-- Revisit trigger: if dialect-drift bugs exceed 2 per quarter, reconsider Docker PostgreSQL approach
-\`\`\`
+Use \`assets/templates/adr-simple.md\` for short-form drafting. The filled example below covers the same decision space in more detail.
 
 ## Long Version (MADR Template)
 
-The same decision with full options analysis:
+Same decision with full options analysis:
 
 \`\`\`markdown
 ---
@@ -423,81 +352,73 @@ Spin up a fresh PostgreSQL container for each CI job.
 \`\`\`
 `},{file:`references/review-checklist.md`,content:`# ADR Review Checklist
 
-Use this checklist in Phase 3 to validate an ADR before finalizing. The goal: **could a coding agent read this ADR and start implementing the decision immediately, without asking any clarifying questions?**
+Use in Phase 3. Goal: **could a coding agent read this ADR and implement without follow-up questions?**
 
 ## Agent-Readiness Checks
 
 ### Context & Problem
 
-- [ ] A reader with no prior context can understand why this decision exists
-- [ ] The trigger is clear (what changed, broke, or is about to break)
-- [ ] No tribal knowledge is assumed — acronyms are defined, systems are named explicitly
-- [ ] Links to relevant issues, PRs, or prior ADRs are included
+- [ ] Reader with no context can understand why decision exists
+- [ ] Trigger is clear
+- [ ] No tribal knowledge assumed; acronyms and systems are explicit
+- [ ] Relevant issues, PRs, or ADRs are linked
 
 ### Decision
 
-- [ ] The decision is specific enough to act on (not "use a better approach" but "use X for Y")
-- [ ] Scope is bounded — what's in AND what's out (non-goals)
-- [ ] Constraints are explicit and measurable where possible (e.g., "< 200ms p95" not "fast enough")
+- [ ] Decision is specific enough to act on
+- [ ] Scope is bounded; non-goals are stated
+- [ ] Constraints are explicit and measurable where possible
 
 ### Consequences
 
-- [ ] Each consequence is concrete and actionable, not aspirational
-- [ ] Follow-up tasks are identified (migrations, config changes, documentation, new tests)
-- [ ] Risks are stated with mitigation strategies or acceptance rationale
-- [ ] No consequence is a disguised restatement of the decision
+- [ ] Consequences are concrete and actionable
+- [ ] Follow-up tasks are identified
+- [ ] Risks include mitigation or acceptance rationale
 
 ### Implementation Plan
 
-- [ ] Affected files/directories are named explicitly (not "the database code" but "src/db/client.ts")
-- [ ] Dependencies to add/remove are specified with version constraints
-- [ ] Patterns to follow reference existing code (not abstract descriptions)
-- [ ] Patterns to avoid are stated (what NOT to do)
-- [ ] Configuration changes are listed (env vars, config files, feature flags)
-- [ ] If replacing something, migration steps are described
+- [ ] Affected files/directories are explicit
+- [ ] Dependency changes include version constraints
+- [ ] Patterns to follow reference existing code
+- [ ] Patterns to avoid are explicit
+- [ ] Config and migration steps are listed when needed
 
 ### Verification
 
-- [ ] Criteria are checkboxes, not prose
-- [ ] Each criterion is testable — an agent could write a test or run a command to check it
-- [ ] Criteria cover both "it works" (functional) and "it's done right" (structural/architectural)
-- [ ] No criterion is vague ("it performs well" → "p95 latency < 200ms under 100 concurrent requests")
+- [ ] Criteria are checkboxes
+- [ ] Each criterion is testable
+- [ ] Criteria cover functional and structural outcomes
 
 ### Options (MADR template)
 
-- [ ] At least two options were genuinely considered (not just "do the thing" vs "do nothing")
-- [ ] Each option has real pros AND cons (not a straw-man comparison)
-- [ ] The justification for the chosen option references specific drivers or tradeoffs
-- [ ] Rejected options explain WHY they were rejected, not just what they are
+- [ ] At least two genuine options were considered
+- [ ] Each option has real pros and cons
+- [ ] Chosen option cites specific drivers or tradeoffs
 
 ### Meta
 
-- [ ] Status is set correctly (usually \`proposed\` for new ADRs)
+- [ ] Status is correct
 - [ ] Date is set
 - [ ] Decision-makers are listed
-- [ ] Title is a verb phrase describing the decision (not the problem)
+- [ ] Title is a decision verb phrase
 - [ ] Filename follows repo conventions
 
 ## Quick Scoring
 
-Count the checked items. This isn't a gate — it's a conversation tool.
+Count checked items.
 
 - **All checked**: Ship it.
-- **1–3 unchecked**: Discuss the gaps with the human. Most can be fixed in a minute.
-- **4+ unchecked**: The ADR needs more work. Go back to Phase 1 for the fuzzy areas.
+- **1–3 unchecked**: Discuss gaps.
+- **4+ unchecked**: Return to Phase 1.
 
 ## Common Failure Modes
 
-| Symptom                                    | Root Cause                             | Fix                                                         |
-| ------------------------------------------ | -------------------------------------- | ----------------------------------------------------------- |
-| "Improve performance" as a consequence     | Vague intent                           | Ask: "improve which metric, by how much, measured how?"     |
-| Only one option listed                     | Decision already made, ADR is post-hoc | Ask: "what did you reject and why?" — capture the reasoning |
-| Context reads like a solution pitch        | Skipped problem framing                | Rewrite context as the problem, move solution to Decision   |
-| Consequences are all positive              | Cherry-picking                         | Ask: "what gets harder? what's the maintenance cost?"       |
-| "We decided to use X" with no why          | Missing justification                  | Ask: "why X over Y?" — the 'over Y' forces comparison       |
-| Implementation Plan says "update the code" | Too abstract                           | Ask: "which files, which functions, what pattern?"          |
-| Verification says "it works"               | Not testable                           | Ask: "what command would you run to prove it works?"        |
-| No affected paths listed                   | Implementation Plan is hand-wavy       | Agent should scan the codebase and propose specific paths   |
+| Symptom | Root Cause | Fix |
+| --- | --- | --- |
+| "Improve performance" as a consequence | Vague intent | Ask: "which metric, by how much, measured how?" |
+| Only one option listed | Decision already made | Ask: "what did you reject and why?" |
+| Implementation Plan says "update the code" | Too abstract | Ask: "which files, which functions, what pattern?" |
+| Verification says "it works" | Not testable | Ask: "what command proves it works?" |
 `},{file:`references/template-variants.md`,content:`# Template Variants
 
 This skill ships two templates in \`assets/templates/\`.
@@ -506,11 +427,11 @@ This skill ships two templates in \`assets/templates/\`.
 
 File: \`assets/templates/adr-simple.md\`
 
-Use this when:
+Use when:
 
-- The decision is straightforward (one clear winner, minimal tradeoffs)
-- You mainly need "why, what, consequences, how to implement"
-- Alternatives are few and can be dismissed in a sentence each
+- Decision is straightforward
+- You need "why, what, consequences, impl"
+- Alternatives are few and brief
 - Speed matters more than exhaustive comparison
 
 Sections: Context and Problem Statement → Decision → Consequences → Implementation Plan → Verification → Alternatives Considered (optional) → More Information (optional).
@@ -519,25 +440,24 @@ Sections: Context and Problem Statement → Decision → Consequences → Implem
 
 File: \`assets/templates/adr-madr.md\`
 
-Use this when:
+Use when:
 
-- You have multiple real options and want to document structured tradeoffs
-- You need to capture decision drivers explicitly (what criteria mattered)
-- The decision is likely to be revisited and the comparison needs to survive
-- Stakeholders need to see the reasoning process, not just the outcome
+- Multiple real options need structured tradeoffs
+- Decision drivers must be explicit
+- Decision may be revisited later
+- Stakeholders need reasoning, not only outcome
 
 Sections: Context and Problem Statement → Decision Drivers (optional) → Considered Options → Decision Outcome → Consequences → Implementation Plan → Verification → Pros and Cons of the Options (optional) → More Information (optional).
 
-This template aligns with [MADR 4.0](https://adr.github.io/madr/) and extends it with agent-first sections.
+Aligns with [MADR 4.0](https://adr.github.io/madr/) plus agent-first sections.
 
 ## Both Templates Share
 
-- **YAML front matter** for metadata (status, date, decision-makers, consulted, informed)
-- **Implementation Plan** — affected paths, dependencies, patterns to follow/avoid, configuration, migration steps. This is what makes the ADR an executable spec for agents.
-- **Verification as checkboxes** — testable criteria an agent can validate after implementation
-- **Agent-first framing**: placeholder text prompts you to be specific, measurable, and self-contained
-- **"More Information" section** for cross-links, follow-ups, and revisit triggers
-- **"Neutral, because..."** as a third argument category alongside Good and Bad
+- **YAML front matter** for status, date, decision-makers, consulted, informed
+- **Implementation Plan** — affected paths, deps, patterns to follow/avoid, config, migration steps
+- **Verification as checkboxes** — testable criteria after impl
+- **Agent-first framing** — placeholders push specificity and measurable constraints
+- **"More Information"** for cross-links, follow-ups, revisit triggers
 
 ## Choosing Between Them
 
@@ -549,829 +469,393 @@ This template aligns with [MADR 4.0](https://adr.github.io/madr/) and extends it
 | Expected lifetime        | Months          | Years        |
 | Needs stakeholder review | No              | Yes          |
 
-When in doubt, start with Simple. You can always expand to MADR if the discussion reveals more complexity.
+When in doubt, start with Simple. Expand to MADR if needed.
 `},{file:`scripts/bootstrap_adr.js`,content:`#!/usr/bin/env node
-/**
- * Bootstrap ADRs in a repo:
- * - create ADR directory
- * - create adr/README.md (index) using a template
- * - create first ADR: "Adopt architecture decision records"
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-function die(msg) {
-  process.stderr.write(\`\${msg}\\n\`);
-  process.exit(1);
+const fs=require('node:fs');
+const path=require('node:path');
+
+function die(msg){process.stderr.write(\`\${msg}\\n\`);process.exit(1);}
+function toPosix(value){return value.split(path.sep).join('/');}
+function slugify(text){
+  const value=String(text||'').trim().toLowerCase();
+  return value.replace(/['"\`]/g,'').replace(/[^a-z0-9]+/g,'-').replace(/-{2,}/g,'-').replace(/^-+|-+$/g,'')||'decision';
 }
-
-function parseArgs(argv) {
-  const out = {
-    repoRoot: '.',
-    dir: 'adr',
-    forceIndex: false,
-    indexFile: null,
-    firstTitle: 'Adopt architecture decision records',
-    firstStatus: 'accepted',
-    deciders: '',
-    technicalStory: '',
-    strategy: 'date',
-    json: false,
-  };
-
-  for (let i = 2; i < argv.length; i++) {
-    const a = argv[i];
-    const next = () => {
-      if (i + 1 >= argv.length) die(\`Missing value for \${a}\`);
-      return argv[++i];
-    };
-
-    if (a === '--repo-root') out.repoRoot = next();
-    else if (a === '--dir') out.dir = next();
-    else if (a === '--force-index') out.forceIndex = true;
-    else if (a === '--index-file') out.indexFile = next();
-    else if (a === '--first-title') out.firstTitle = next();
-    else if (a === '--first-status') out.firstStatus = next();
-    else if (a === '--deciders') out.deciders = next();
-    else if (a === '--technical-story') out.technicalStory = next();
-    else if (a === '--strategy') out.strategy = next();
-    else if (a === '--json') out.json = true;
-    else if (a === '--help' || a === '-h') {
-      process.stdout.write(
-        [
-          'Usage: node bootstrap_adr.js [options]',
-          '',
-          'Options:',
-          '  --repo-root <path>     Repo root (default: .)',
-          '  --dir <path>           ADR directory (default: adr)',
-          '  --index-file <path>    Override index file path (relative to repo root unless absolute)',
-          '  --force-index          Overwrite index file if it exists',
-          '  --first-title <text>   Title for initial ADR',
-          '  --first-status <text>  Status for initial ADR (default: accepted)',
-          '  --strategy date|slug|auto  Filename strategy for initial ADR (default: date)',
-          '  --json                 Output machine-readable JSON (default: off)',
-          '',
-        ].join('\\n'),
-      );
+function parseArgs(argv){
+  const out={repoRoot:'.',dir:'adr',forceIndex:false,indexFile:null,firstTitle:'Adopt architecture decision records',firstStatus:'accepted',deciders:'',technicalStory:'',strategy:'date',json:false};
+  for(let index=2;index<argv.length;index++){
+    const arg=argv[index];
+    const next=()=>{if(index+1>=argv.length) die(\`Missing value for \${arg}\`);return argv[++index];};
+    if(arg==='--repo-root') out.repoRoot=next();
+    else if(arg==='--dir') out.dir=next();
+    else if(arg==='--force-index') out.forceIndex=true;
+    else if(arg==='--index-file') out.indexFile=next();
+    else if(arg==='--first-title') out.firstTitle=next();
+    else if(arg==='--first-status') out.firstStatus=next();
+    else if(arg==='--deciders') out.deciders=next();
+    else if(arg==='--technical-story') out.technicalStory=next();
+    else if(arg==='--strategy') out.strategy=next();
+    else if(arg==='--json') out.json=true;
+    else if(arg==='--help'||arg==='-h'){
+      process.stdout.write([
+        'Usage: node bootstrap_adr.js [options]',
+        '',
+        'Options:',
+        '  --repo-root <path>     Repo root (default: .)',
+        '  --dir <path>           ADR dir (default: adr)',
+        '  --index-file <path>    Index path override',
+        '  --force-index          Overwrite existing index',
+        '  --first-title <text>   Initial ADR title',
+        '  --first-status <text>  Initial ADR status (default: accepted)',
+        '  --strategy date|slug|auto  Filename strategy (default: date)',
+        '  --json                 Emit JSON',
+        '',
+      ].join('\\n'));
       process.exit(0);
-    } else {
-      die(\`Unknown arg: \${a}\`);
-    }
+    }else die(\`Unknown arg: \${arg}\`);
   }
-
-  if (!['auto', 'date', 'slug'].includes(out.strategy)) die(\`Invalid --strategy: \${out.strategy}\`);
+  if(!['auto','date','slug'].includes(out.strategy)) die(\`Invalid --strategy: \${out.strategy}\`);
   return out;
 }
-
-function loadReadmeTemplate() {
-  const skillRoot = path.resolve(__dirname, '..');
-  const templatePath = path.join(skillRoot, 'assets', 'templates', 'adr-readme.md');
-  if (!fs.existsSync(templatePath)) die(\`README template not found: \${templatePath}\`);
-  return fs.readFileSync(templatePath, 'utf8');
-}
-
-function writeIndex(indexFile, adrDirName, { force }) {
-  if (fs.existsSync(indexFile) && !force) return;
-  const content = loadReadmeTemplate().replaceAll('{ADR_DIR}', adrDirName);
-  fs.mkdirSync(path.dirname(indexFile), { recursive: true });
-  fs.writeFileSync(indexFile, \`\${content.trimEnd()}\\n\`, 'utf8');
+function loadReadmeTemplate(){
+  const templatePath=path.join(path.resolve(__dirname,'..'),'assets','templates','adr-readme.md');
+  if(!fs.existsSync(templatePath)) die(\`README template not found: \${templatePath}\`);
+  return fs.readFileSync(templatePath,'utf8');
 }
-
-function slugify(text) {
-  const t = String(text || '')
-    .trim()
-    .toLowerCase();
-  const noQuotes = t.replace(/['"\`]/g, '');
-  const dashed = noQuotes.replace(/[^a-z0-9]+/g, '-').replace(/-{2,}/g, '-');
-  const trimmed = dashed.replace(/^-+/, '').replace(/-+$/, '');
-  return trimmed || 'decision';
+function writeIndex(indexFile,adrDirName,{force}){
+  if(fs.existsSync(indexFile)&&!force) return;
+  const content=loadReadmeTemplate().replaceAll('{ADR_DIR}',adrDirName);
+  fs.mkdirSync(path.dirname(indexFile),{recursive:true});
+  fs.writeFileSync(indexFile,\`\${content.trimEnd()}\\n\`,'utf8');
 }
-
-function toPosix(p) {
-  return p.split(path.sep).join('/');
-}
-
-function generateFirstAdr({ title, status, date, deciders, adrDir }) {
-  const deciderLine = deciders
-    ? String(deciders)
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .join(', ')
-    : '';
-
+function generateFirstAdr({title,status,date,deciders,adrDir}){
+  const decisionMakers=deciders?String(deciders).split(',').map((name)=>name.trim()).filter(Boolean).join(', '):'';
   return \`---
 status: \${status}
 date: \${date}
-decision-makers: \${deciderLine}
+decision-makers: \${decisionMakers}
 ---
 
 # \${title}
 
 ## Context and Problem Statement
 
-Architecture decisions in this project are made implicitly — through code, conversations, and tribal knowledge. When a new contributor (human or AI agent) joins the codebase, there is no record of *why* things are built the way they are. This makes it hard to:
-
-- Understand whether a pattern is intentional or accidental
-- Know if a past decision still applies or has been superseded
-- Avoid relitigating decisions that were already carefully considered
-
-We need a lightweight, version-controlled way to capture decisions where the code lives.
+Architecture decisions are mostly implicit: code, chat, tribal knowledge. New contributors cannot quickly recover why patterns exist or whether old decisions still apply. We need version-controlled decision records near code.
 
 ## Decision
 
-Adopt Architecture Decision Records (ADRs) using the MADR 4.0 format, stored in \\\`\${adrDir}/\\\`.
+Adopt Architecture Decision Records (ADRs) using MADR 4.0, stored in \\\`\${adrDir}/\\\`.
 
 Conventions:
 - One ADR per file, named \\\`YYYY-MM-DD-title-with-dashes.md\\\`
-- New ADRs start as \\\`proposed\\\`, move to \\\`accepted\\\` or \\\`rejected\\\`
-- Superseded ADRs link to their replacement
-- ADRs are written to be self-contained — a coding agent should be able to read one and implement the decision without further context
+- New ADRs start as \\\`proposed\\\`, then move to \\\`accepted\\\` or \\\`rejected\\\`
+- Superseded ADRs link to replacements
+- ADRs are self-contained enough for coding agents to implement from them
 
 ## Consequences
 
-* Good, because decisions are discoverable and version-controlled alongside the code
-* Good, because new contributors (human or agent) can understand the "why" behind architecture choices
-* Good, because the team builds a shared decision log that prevents relitigating settled questions
-* Bad, because writing ADRs takes time — though a good ADR saves more time than it costs
-* Neutral, because ADRs require periodic review to mark outdated decisions as deprecated or superseded
+* Good, because decisions stay discoverable and version-controlled with code
+* Good, because contributors can recover why architecture choices were made
+* Bad, because writing ADRs costs time
+* Neutral, because ADRs need periodic review for deprecation or supersession
 
 ## Alternatives Considered
 
-* No formal records: Continue making decisions in conversations and code comments. Rejected because context is lost and decisions get relitigated.
-* Wiki or Notion pages: Capture decisions outside the repo. Rejected because they drift out of sync with the code and are not version-controlled.
-* Lightweight RFCs: More heavyweight process with formal review cycles. Rejected as overkill for most decisions — ADRs can scale up to RFC-level detail when needed.
+* No formal records: Rejected because context is lost and decisions get relitigated.
+* Wiki or Notion pages: Rejected because they drift from code and lack repo history.
+* Lightweight RFCs: Rejected as too heavy for most decisions; ADRs can still scale up when needed.
 \`;
 }
-
-function updateIndexFile(indexFile, { relLink, title, status, date }) {
-  if (!fs.existsSync(indexFile)) return;
-  const content = fs.readFileSync(indexFile, 'utf8');
-  if (content.includes(relLink)) return;
-
-  const entryLine = \`- [\${title}](\${relLink}) (\${status}, \${date})\`;
-
-  // Append after "## ADRs" heading if found, otherwise append at end
-  const normalized = content.replace(/\\r\\n/g, '\\n');
-  const lines = normalized.split('\\n');
-  const headingIdx = lines.findIndex((l) => /^##\\s+ADRs\\s*$/i.test(l));
-
-  if (headingIdx !== -1) {
-    // Insert after the heading (and any blank line after it)
-    let insertAt = headingIdx + 1;
-    while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
-    lines.splice(insertAt, 0, entryLine);
-  } else {
-    lines.push(entryLine);
-  }
-
-  fs.writeFileSync(indexFile, lines.join('\\n'), 'utf8');
+function updateIndexFile(indexFile,{relLink,title,status,date}){
+  if(!fs.existsSync(indexFile)) return;
+  const content=fs.readFileSync(indexFile,'utf8');
+  if(content.includes(relLink)) return;
+  const entryLine=\`- [\${title}](\${relLink}) (\${status}, \${date})\`;
+  const lines=content.replace(/\\r\\n/g,'\\n').split('\\n');
+  const headingIndex=lines.findIndex((line)=>/^##\\s+ADRs\\s*$/i.test(line));
+  if(headingIndex!==-1){
+    let insertAt=headingIndex+1;
+    while(insertAt<lines.length&&lines[insertAt].trim()==='') insertAt++;
+    lines.splice(insertAt,0,entryLine);
+  }else lines.push(entryLine);
+  fs.writeFileSync(indexFile,lines.join('\\n'),'utf8');
 }
-
-function main() {
-  const args = parseArgs(process.argv);
-
-  const repoRoot = path.resolve(process.cwd(), args.repoRoot);
-  if (!fs.existsSync(repoRoot)) die(\`Repo root does not exist: \${repoRoot}\`);
-
-  const adrDir = path.resolve(repoRoot, args.dir);
-  fs.mkdirSync(adrDir, { recursive: true });
-
-  const indexFile = args.indexFile
-    ? path.isAbsolute(args.indexFile)
-      ? args.indexFile
-      : path.resolve(repoRoot, args.indexFile)
-    : path.join(adrDir, 'README.md');
-
-  const indexExistedBefore = fs.existsSync(indexFile);
-  writeIndex(indexFile, args.dir, { force: args.forceIndex });
-  const indexWritten = fs.existsSync(indexFile) && (!indexExistedBefore || args.forceIndex);
-
-  // Create the first ADR as a filled-out decision (not a blank template).
-  const relIndex = path.isAbsolute(indexFile) ? path.relative(repoRoot, indexFile) : indexFile;
-  const today = new Date().toISOString().slice(0, 10);
-
-  const firstAdrContent = generateFirstAdr({
-    title: args.firstTitle,
-    status: args.firstStatus,
-    date: today,
-    deciders: args.deciders,
-    adrDir: args.dir,
-  });
-
-  // Determine filename using same logic as new_adr.js
-  const strategy = args.strategy === 'auto' ? 'date' : args.strategy;
-  let firstAdrFilename;
-  if (strategy === 'date') {
-    firstAdrFilename = \`\${today}-\${slugify(args.firstTitle)}.md\`;
-  } else {
-    firstAdrFilename = \`\${slugify(args.firstTitle)}.md\`;
-  }
-  const firstAdrPath = path.join(adrDir, firstAdrFilename);
-  fs.writeFileSync(firstAdrPath, \`\${firstAdrContent.trimEnd()}\\n\`, 'utf8');
-
-  // Update index
-  const relLink = toPosix(path.relative(path.dirname(indexFile), firstAdrPath));
-  updateIndexFile(indexFile, {
-    relLink,
-    title: args.firstTitle,
-    status: args.firstStatus,
-    date: today,
-  });
-
-  if (args.json) {
-    const payload = {
-      repoRoot,
-      adrDir,
-      adrDirRelPath: toPosix(path.relative(repoRoot, adrDir)),
-      indexPath: indexFile,
-      indexRelPath: toPosix(relIndex),
-      indexExistedBefore,
-      indexWritten,
-      firstAdr: {
-        createdAdrPath: firstAdrPath,
-        createdAdrRelPath: toPosix(path.relative(repoRoot, firstAdrPath)),
-        title: args.firstTitle,
-        status: args.firstStatus,
-        strategy,
-        date: today,
-      },
-      date: today,
-    };
-    process.stdout.write(\`\${JSON.stringify(payload)}\\n\`);
+function main(){
+  const args=parseArgs(process.argv);
+  const repoRoot=path.resolve(process.cwd(),args.repoRoot);
+  if(!fs.existsSync(repoRoot)) die(\`Repo root does not exist: \${repoRoot}\`);
+  const adrDir=path.resolve(repoRoot,args.dir);
+  fs.mkdirSync(adrDir,{recursive:true});
+  const indexFile=args.indexFile?(path.isAbsolute(args.indexFile)?args.indexFile:path.resolve(repoRoot,args.indexFile)):path.join(adrDir,'README.md');
+  const indexExistedBefore=fs.existsSync(indexFile);
+  writeIndex(indexFile,args.dir,{force:args.forceIndex});
+  const indexWritten=fs.existsSync(indexFile)&&(!indexExistedBefore||args.forceIndex);
+  const relIndex=path.isAbsolute(indexFile)?path.relative(repoRoot,indexFile):indexFile;
+  const date=new Date().toISOString().slice(0,10);
+  const strategy=args.strategy==='auto'?'date':args.strategy;
+  const fileName=strategy==='date'?\`\${date}-\${slugify(args.firstTitle)}.md\`:\`\${slugify(args.firstTitle)}.md\`;
+  const firstAdrPath=path.join(adrDir,fileName);
+  fs.writeFileSync(firstAdrPath,\`\${generateFirstAdr({title:args.firstTitle,status:args.firstStatus,date,deciders:args.deciders,adrDir:args.dir}).trimEnd()}\\n\`,'utf8');
+  updateIndexFile(indexFile,{relLink:toPosix(path.relative(path.dirname(indexFile),firstAdrPath)),title:args.firstTitle,status:args.firstStatus,date});
+  if(args.json){
+    process.stdout.write(\`\${JSON.stringify({repoRoot,adrDir,adrDirRelPath:toPosix(path.relative(repoRoot,adrDir)),indexPath:indexFile,indexRelPath:toPosix(relIndex),indexExistedBefore,indexWritten,firstAdr:{createdAdrPath:firstAdrPath,createdAdrRelPath:toPosix(path.relative(repoRoot,firstAdrPath)),title:args.firstTitle,status:args.firstStatus,strategy,date},date})}\\n\`);
     return;
   }
-
   process.stdout.write(\`\${firstAdrPath}\\n\`);
-  process.stdout.write(\`Bootstrapped ADRs at \${adrDir} (\${today})\\n\`);
+  process.stdout.write(\`Bootstrapped ADRs at \${adrDir} (\${date})\\n\`);
   process.stdout.write(\`Index: \${indexFile}\\n\`);
 }
 
 main();
 `},{file:`scripts/new_adr.js`,content:`#!/usr/bin/env node
-/**
- * Create a new ADR markdown file using repo conventions and a template.
- *
- * Design goals:
- * - Safe defaults (auto-detect adr directory + numbering)
- * - No external deps
- * - Works even if the repo has no ADRs yet
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-function die(msg) {
-  process.stderr.write(\`\${msg}\\n\`);
-  process.exit(1);
-}
-
-function slugify(text) {
-  const t = String(text || '')
-    .trim()
-    .toLowerCase();
-  const noQuotes = t.replace(/['"\`]/g, '');
-  const dashed = noQuotes.replace(/[^a-z0-9]+/g, '-').replace(/-{2,}/g, '-');
-  const trimmed = dashed.replace(/^-+/, '').replace(/-+$/, '');
-  return trimmed || 'decision';
-}
-
-function toPosix(p) {
-  return p.split(path.sep).join('/');
+const fs=require('node:fs');
+const path=require('node:path');
+
+function die(msg){process.stderr.write(\`\${msg}\\n\`);process.exit(1);}
+function toPosix(value){return value.split(path.sep).join('/');}
+function slugify(text){
+  const value=String(text||'').trim().toLowerCase();
+  return value.replace(/['"\`]/g,'').replace(/[^a-z0-9]+/g,'-').replace(/-{2,}/g,'-').replace(/^-+|-+$/g,'')||'decision';
 }
-
-function parseArgs(argv) {
-  const out = {
-    repoRoot: '.',
-    dir: null,
-    noCreateDir: false,
-    title: null,
-    status: 'proposed',
-    template: 'simple', // simple | madr
-    strategy: 'auto', // auto | date | slug
-    deciders: '',
-    consulted: '',
-    informed: '',
-    technicalStory: '',
-    chosenOption: '',
-    updateIndex: false,
-    indexFile: null,
-    json: false,
-  };
-
-  for (let i = 2; i < argv.length; i++) {
-    const a = argv[i];
-    const next = () => {
-      if (i + 1 >= argv.length) die(\`Missing value for \${a}\`);
-      return argv[++i];
-    };
-
-    if (a === '--repo-root') out.repoRoot = next();
-    else if (a === '--dir') out.dir = next();
-    else if (a === '--no-create-dir') out.noCreateDir = true;
-    else if (a === '--title') out.title = next();
-    else if (a === '--status') out.status = next();
-    else if (a === '--template') out.template = next();
-    else if (a === '--strategy') out.strategy = next();
-    else if (a === '--deciders') out.deciders = next();
-    else if (a === '--consulted') out.consulted = next();
-    else if (a === '--informed') out.informed = next();
-    else if (a === '--technical-story') out.technicalStory = next();
-    else if (a === '--chosen-option') out.chosenOption = next();
-    else if (a === '--update-index') out.updateIndex = true;
-    else if (a === '--index-file') out.indexFile = next();
-    else if (a === '--json') out.json = true;
-    else if (a === '--help' || a === '-h') {
-      process.stdout.write(
-        [
-          'Usage: node new_adr.js --title "Choose database" [options]',
-          '',
-          'Options:',
-          '  --repo-root <path>     Repo root (default: .)',
-          '  --dir <path>           ADR directory (default: auto-detect, else adr/)',
-          '  --no-create-dir        Do not create ADR directory if missing',
-          '  --status <value>       ADR status (default: proposed)',
-          '  --template simple|madr Template (default: simple)',
-          '  --strategy auto|date|slug  Filename strategy (default: auto)',
-          '  --deciders "a,b"      Deciders list',
-          '  --consulted "a,b"     Consulted experts (RACI)',
-          '  --informed "a,b"      Informed stakeholders (RACI)',
-          '  --technical-story <x>  Issue/ticket/PR link or short ref',
-          '  --chosen-option <x>    MADR template: chosen option label',
-          '  --update-index         Update adr/README.md (or existing index)',
-          '  --index-file <path>    Override index file (relative to repo root unless absolute)',
-          '  --json                 Output machine-readable JSON (default: off)',
-          '',
-        ].join('\\n'),
-      );
+function parseArgs(argv){
+  const out={repoRoot:'.',dir:null,noCreateDir:false,title:null,status:'proposed',template:'simple',strategy:'auto',deciders:'',consulted:'',informed:'',technicalStory:'',chosenOption:'',updateIndex:false,indexFile:null,json:false};
+  for(let index=2;index<argv.length;index++){
+    const arg=argv[index];
+    const next=()=>{if(index+1>=argv.length) die(\`Missing value for \${arg}\`);return argv[++index];};
+    if(arg==='--repo-root') out.repoRoot=next();
+    else if(arg==='--dir') out.dir=next();
+    else if(arg==='--no-create-dir') out.noCreateDir=true;
+    else if(arg==='--title') out.title=next();
+    else if(arg==='--status') out.status=next();
+    else if(arg==='--template') out.template=next();
+    else if(arg==='--strategy') out.strategy=next();
+    else if(arg==='--deciders') out.deciders=next();
+    else if(arg==='--consulted') out.consulted=next();
+    else if(arg==='--informed') out.informed=next();
+    else if(arg==='--technical-story') out.technicalStory=next();
+    else if(arg==='--chosen-option') out.chosenOption=next();
+    else if(arg==='--update-index') out.updateIndex=true;
+    else if(arg==='--index-file') out.indexFile=next();
+    else if(arg==='--json') out.json=true;
+    else if(arg==='--help'||arg==='-h'){
+      process.stdout.write([
+        'Usage: node new_adr.js --title "Choose database" [options]',
+        '',
+        'Options:',
+        '  --repo-root <path>     Repo root (default: .)',
+        '  --dir <path>           ADR dir (default: auto-detect, else adr/)',
+        '  --no-create-dir        Do not create ADR dir',
+        '  --status <value>       ADR status (default: proposed)',
+        '  --template simple|madr Template (default: simple)',
+        '  --strategy auto|date|slug  Filename strategy (default: auto)',
+        '  --deciders "a,b"      Deciders list',
+        '  --consulted "a,b"     Consulted list (RACI)',
+        '  --informed "a,b"      Informed list (RACI)',
+        '  --technical-story <x>  Issue/ticket/PR ref',
+        '  --chosen-option <x>    MADR chosen option label',
+        '  --update-index         Update adr/README.md (or existing index)',
+        '  --index-file <path>    Index file override',
+        '  --json                 Emit JSON',
+        '',
+      ].join('\\n'));
       process.exit(0);
-    } else {
-      die(\`Unknown arg: \${a}\`);
-    }
+    }else die(\`Unknown arg: \${arg}\`);
   }
-
-  if (!out.title) die('Missing required --title');
-
-  if (!['simple', 'madr'].includes(out.template)) die(\`Invalid --template: \${out.template}\`);
-  if (!['auto', 'date', 'slug'].includes(out.strategy)) die(\`Invalid --strategy: \${out.strategy}\`);
-
+  if(!out.title) die('Missing required --title');
+  if(!['simple','madr'].includes(out.template)) die(\`Invalid --template: \${out.template}\`);
+  if(!['auto','date','slug'].includes(out.strategy)) die(\`Invalid --strategy: \${out.strategy}\`);
   return out;
 }
-
-function detectAdrDir(repoRoot) {
-  const candidates = [
-    path.join(repoRoot, 'contributing', 'decisions'),
-    path.join(repoRoot, 'docs', 'decisions'),
-    path.join(repoRoot, 'adr'),
-    path.join(repoRoot, 'docs', 'adr'),
-    path.join(repoRoot, 'docs', 'adrs'),
-    path.join(repoRoot, 'decisions'),
-  ];
-  for (const p of candidates) {
-    try {
-      if (fs.statSync(p).isDirectory()) return p;
-    } catch {
-      // ignore
-    }
+function detectAdrDir(repoRoot){
+  for(const candidate of [path.join(repoRoot,'contributing','decisions'),path.join(repoRoot,'docs','decisions'),path.join(repoRoot,'adr'),path.join(repoRoot,'docs','adr'),path.join(repoRoot,'docs','adrs'),path.join(repoRoot,'decisions')]){
+    try{if(fs.statSync(candidate).isDirectory()) return candidate;}catch{}
   }
   return null;
 }
-
-function listMdFiles(dir) {
-  let entries = [];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
-    .map((e) => e.name);
+function listMdFiles(dir){
+  try{return fs.readdirSync(dir,{withFileTypes:true}).filter((entry)=>entry.isFile()&&entry.name.toLowerCase().endsWith('.md')).map((entry)=>entry.name);}catch{return [];}
 }
-
-function detectStrategy(adrDir) {
-  const md = listMdFiles(adrDir);
-  for (const name of md) {
-    if (/^\\d{4}-\\d{2}-\\d{2}-/.test(name)) return 'date';
-  }
-  if (md.length > 0) return 'slug';
-  return 'date';
+function detectStrategy(adrDir){
+  const files=listMdFiles(adrDir);
+  if(files.some((name)=>/^\\d{4}-\\d{2}-\\d{2}-/.test(name))) return 'date';
+  return files.length?'slug':'date';
 }
-
-function todayISO() {
-  return new Date().toISOString().slice(0, 10);
+function todayISO(){return new Date().toISOString().slice(0,10);}
+function loadTemplate(name){
+  const templatePath=path.join(path.resolve(__dirname,'..'),'assets','templates',\`adr-\${name}.md\`);
+  if(!fs.existsSync(templatePath)) die(\`Template not found: \${templatePath}\`);
+  return fs.readFileSync(templatePath,'utf8');
 }
-
-function loadTemplate(templateName) {
-  const skillRoot = path.resolve(__dirname, '..');
-  const templatePath = path.join(skillRoot, 'assets', 'templates', \`adr-\${templateName}.md\`);
-  if (!fs.existsSync(templatePath)) die(\`Template not found: \${templatePath}\`);
-  return fs.readFileSync(templatePath, 'utf8');
+function renderTemplate(raw,vars){
+  let out=raw;
+  out=out.replace(/^(status:\\s*)["']?\\{[^}]*\\}["']?\\s*$/m,\`$1\${vars.status}\`);
+  out=out.replace(/^(date:\\s*)\\{[^}]*\\}\\s*$/m,\`$1\${vars.date}\`);
+  out=out.replace(/^(decision-makers:\\s*)["']?\\{[^}]*\\}["']?\\s*$/m,\`$1\${vars.deciders||''}\`);
+  out=vars.consulted?out.replace(/^(consulted:\\s*)["']?\\{[^}]*\\}["']?\\s*$/m,\`$1\${vars.consulted}\`):out.replace(/^consulted:\\s*["']?\\{[^}]*\\}["']?\\s*\\n/m,'');
+  out=vars.informed?out.replace(/^(informed:\\s*)["']?\\{[^}]*\\}["']?\\s*$/m,\`$1\${vars.informed}\`):out.replace(/^informed:\\s*["']?\\{[^}]*\\}["']?\\s*\\n/m,'');
+  return out
+    .replace(/^(#\\s+)\\{short title[^}]*\\}\\s*$/m,\`$1\${vars.title}\`)
+    .replaceAll('{TITLE}',vars.title)
+    .replaceAll('{STATUS}',vars.status)
+    .replaceAll('{DATE}',vars.date)
+    .replaceAll('{DECIDERS}',vars.deciders)
+    .replaceAll('{TECHNICAL_STORY}',vars.technicalStory)
+    .replaceAll('{CHOSEN_OPTION}',vars.chosenOption);
 }
-
-function renderTemplate(raw, vars) {
-  // Handle YAML front matter placeholders (quoted and unquoted)
-  let out = raw;
-
-  // YAML front matter fields — replace the whole placeholder pattern
-  // e.g. status: "{proposed | accepted | ...}" → status: proposed
-  out = out.replace(/^(status:\\s*)["']?\\{[^}]*\\}["']?\\s*$/m, \`$1\${vars.status}\`);
-  out = out.replace(/^(date:\\s*)\\{[^}]*\\}\\s*$/m, \`$1\${vars.date}\`);
-  out = out.replace(/^(decision-makers:\\s*)["']?\\{[^}]*\\}["']?\\s*$/m, \`$1\${vars.deciders || ''}\`);
-
-  // consulted / informed: replace if a value was provided, otherwise remove the
-  // entire line so we don't leak placeholder text like "{list everyone...}"
-  if (vars.consulted) {
-    out = out.replace(/^(consulted:\\s*)["']?\\{[^}]*\\}["']?\\s*$/m, \`$1\${vars.consulted}\`);
-  } else {
-    out = out.replace(/^consulted:\\s*["']?\\{[^}]*\\}["']?\\s*\\n/m, '');
-  }
-  if (vars.informed) {
-    out = out.replace(/^(informed:\\s*)["']?\\{[^}]*\\}["']?\\s*$/m, \`$1\${vars.informed}\`);
-  } else {
-    out = out.replace(/^informed:\\s*["']?\\{[^}]*\\}["']?\\s*\\n/m, '');
-  }
-
-  // Replace MADR-style heading placeholder
-  out = out.replace(/^(#\\s+)\\{short title[^}]*\\}\\s*$/m, \`$1\${vars.title}\`);
-
-  // Inline placeholders (title in heading, etc.)
-  out = out
-    .replaceAll('{TITLE}', vars.title)
-    .replaceAll('{STATUS}', vars.status)
-    .replaceAll('{DATE}', vars.date)
-    .replaceAll('{DECIDERS}', vars.deciders)
-    .replaceAll('{TECHNICAL_STORY}', vars.technicalStory)
-    .replaceAll('{CHOSEN_OPTION}', vars.chosenOption);
-
-  return out;
+function chooseIndexFile(adrDir){
+  for(const name of ['README.md','index.md']){const candidate=path.join(adrDir,name);if(fs.existsSync(candidate)) return candidate;}
+  return path.join(adrDir,'README.md');
 }
-
-function chooseIndexFile(adrDir) {
-  for (const name of ['README.md', 'index.md']) {
-    const p = path.join(adrDir, name);
-    if (fs.existsSync(p)) return p;
-  }
-  return path.join(adrDir, 'README.md');
+function insertIndexEntryUnderHeading(lines,headingRegex,entryLine){
+  const headingIndex=lines.findIndex((line)=>headingRegex.test(line));
+  if(headingIndex===-1) return {lines,inserted:false};
+  let sectionEnd=lines.length;
+  for(let index=headingIndex+1;index<lines.length;index++){if(/^##\\s+/.test(lines[index])){sectionEnd=index;break;}}
+  let insertAt=sectionEnd;
+  for(let index=sectionEnd-1;index>headingIndex;index--){if(/^[-*]\\s+/.test(lines[index])){insertAt=index+1;break;}}
+  const out=[...lines];
+  if(insertAt===headingIndex+1&&out[insertAt]!=='') out.splice(insertAt,0,'');
+  out.splice(insertAt,0,entryLine);
+  return {lines:out,inserted:true};
 }
-
-function insertIndexEntryUnderHeading(lines, headingRegex, entryLine) {
-  // Returns { lines, inserted }
-  const headingIndex = lines.findIndex((l) => headingRegex.test(l));
-  if (headingIndex === -1) return { lines, inserted: false };
-
-  let sectionEnd = lines.length;
-  for (let i = headingIndex + 1; i < lines.length; i++) {
-    if (/^##\\s+/.test(lines[i])) {
-      sectionEnd = i;
-      break;
-    }
-  }
-
-  // Prefer inserting at end of list in this section if there is a list.
-  let lastListItem = -1;
-  for (let i = sectionEnd - 1; i > headingIndex; i--) {
-    if (/^[-*]\\s+/.test(lines[i])) {
-      lastListItem = i;
-      break;
-    }
-  }
-
-  const insertAt = lastListItem !== -1 ? lastListItem + 1 : sectionEnd;
-
-  const out = [...lines];
-
-  // Ensure there's a blank line after the heading if we're inserting immediately after it.
-  if (insertAt === headingIndex + 1 && out[insertAt] !== '') {
-    out.splice(insertAt, 0, '');
-  }
-
-  out.splice(insertAt, 0, entryLine);
-  return { lines: out, inserted: true };
-}
-
-function updateIndex(indexFile, { relLink, title, status, date }) {
-  let content = '';
-  if (fs.existsSync(indexFile)) content = fs.readFileSync(indexFile, 'utf8');
-  else content = '# ADR Log\\n\\n';
-
-  if (content.includes(relLink)) return false;
-
-  const normalized = content.replace(/\\r\\n/g, '\\n');
-  const hadTrailingNewline = normalized.endsWith('\\n');
-  let lines = normalized.split('\\n');
-  // Normalize away the trailing empty split element so insertion math is sane.
-  if (hadTrailingNewline && lines.length > 0 && lines[lines.length - 1] === '') {
-    lines = lines.slice(0, -1);
-  }
-  const entryLine = \`- [\${title}](\${relLink}) (\${status}, \${date})\`;
-
-  // Prefer inserting under "## ADRs" if it exists, otherwise append at EOF.
-  const r = insertIndexEntryUnderHeading(lines, /^##\\s+ADRs\\s*$/i, entryLine);
-  const nextLines = r.inserted ? r.lines : [...lines, entryLine];
-
-  let next = nextLines.join('\\n');
-  if (hadTrailingNewline) next += '\\n';
-
-  fs.mkdirSync(path.dirname(indexFile), { recursive: true });
-  fs.writeFileSync(indexFile, next, 'utf8');
+function updateIndex(indexFile,{relLink,title,status,date}){
+  const source=fs.existsSync(indexFile)?fs.readFileSync(indexFile,'utf8'):'# ADR Log\\n\\n';
+  if(source.includes(relLink)) return false;
+  const normalized=source.replace(/\\r\\n/g,'\\n');
+  const hadTrailingNewline=normalized.endsWith('\\n');
+  const lines=normalized.split('\\n');
+  if(hadTrailingNewline&&lines[lines.length-1]==='') lines.pop();
+  const entryLine=\`- [\${title}](\${relLink}) (\${status}, \${date})\`;
+  const result=insertIndexEntryUnderHeading(lines,/^##\\s+ADRs\\s*$/i,entryLine);
+  let next=(result.inserted?result.lines:[...lines,entryLine]).join('\\n');
+  if(hadTrailingNewline) next+='\\n';
+  fs.mkdirSync(path.dirname(indexFile),{recursive:true});
+  fs.writeFileSync(indexFile,next,'utf8');
   return true;
 }
-
-function main() {
-  const args = parseArgs(process.argv);
-
-  const repoRoot = path.resolve(process.cwd(), args.repoRoot);
-  if (!fs.existsSync(repoRoot)) die(\`Repo root does not exist: \${repoRoot}\`);
-
-  let adrDir;
-  if (args.dir) adrDir = path.resolve(repoRoot, args.dir);
-  else adrDir = detectAdrDir(repoRoot) || path.join(repoRoot, 'adr');
-
-  if (!fs.existsSync(adrDir)) {
-    if (args.noCreateDir) die(\`ADR directory does not exist: \${adrDir}\`);
-    fs.mkdirSync(adrDir, { recursive: true });
+function main(){
+  const args=parseArgs(process.argv);
+  const repoRoot=path.resolve(process.cwd(),args.repoRoot);
+  if(!fs.existsSync(repoRoot)) die(\`Repo root does not exist: \${repoRoot}\`);
+  const adrDir=args.dir?path.resolve(repoRoot,args.dir):detectAdrDir(repoRoot)||path.join(repoRoot,'adr');
+  if(!fs.existsSync(adrDir)){if(args.noCreateDir) die(\`ADR directory does not exist: \${adrDir}\`);fs.mkdirSync(adrDir,{recursive:true});}
+  const strategy=args.strategy==='auto'?detectStrategy(adrDir):args.strategy;
+  const title=String(args.title).trim();
+  const slug=slugify(title);
+  const date=todayISO();
+  let out=path.join(adrDir,strategy==='date'?\`\${date}-\${slug}.md\`:\`\${slug}.md\`);
+  if(fs.existsSync(out)){
+    if(strategy==='date') die(\`ADR already exists: \${out}\`);
+    let suffix=2;
+    while(true){const candidate=path.join(adrDir,\`\${slug}-\${suffix}.md\`);if(!fs.existsSync(candidate)){out=candidate;break;}suffix++;}
   }
-
-  let strategy = args.strategy;
-  if (strategy === 'auto') strategy = detectStrategy(adrDir);
-
-  const title = String(args.title).trim();
-  const slug = slugify(title);
-
-  const today = todayISO();
-
-  let filename;
-  if (strategy === 'date') {
-    filename = \`\${today}-\${slug}.md\`;
-  } else {
-    filename = \`\${slug}.md\`;
-  }
-
-  let out = path.join(adrDir, filename);
-  if (fs.existsSync(out)) {
-    if (strategy === 'date') die(\`ADR already exists: \${out}\`);
-    let i = 2;
-    while (true) {
-      const candidate = path.join(adrDir, \`\${slug}-\${i}.md\`);
-      if (!fs.existsSync(candidate)) {
-        out = candidate;
-        break;
-      }
-      i++;
-    }
-  }
-
-  const deciders = String(args.deciders || '')
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean)
-    .join(', ');
-
-  const consulted = String(args.consulted || '')
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean)
-    .join(', ');
-  const informed = String(args.informed || '')
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean)
-    .join(', ');
-
-  const raw = loadTemplate(args.template);
-  const rendered = renderTemplate(raw, {
-    title,
-    status: String(args.status).trim(),
-    date: today,
-    deciders,
-    consulted,
-    informed,
-    technicalStory: String(args.technicalStory || '').trim(),
-    chosenOption: String(args.chosenOption || '').trim(),
-  });
-
-  fs.writeFileSync(out, \`\${rendered.trimEnd()}\\n\`, 'utf8');
-
-  let updatedIndexPath = null;
-  let indexChanged = false;
-
-  if (args.updateIndex) {
-    let indexFile;
-    if (args.indexFile) {
-      indexFile = path.isAbsolute(args.indexFile)
-        ? args.indexFile
-        : path.resolve(repoRoot, args.indexFile);
-    } else {
-      indexFile = chooseIndexFile(adrDir);
-    }
-
-    const relLink = toPosix(path.relative(path.dirname(indexFile), out));
-    indexChanged = updateIndex(indexFile, {
-      relLink,
-      title,
-      status: String(args.status).trim(),
-      date: today,
-    });
-    updatedIndexPath = indexFile;
-  }
-
-  if (args.json) {
-    const payload = {
-      repoRoot,
-      adrDir,
-      createdAdrPath: out,
-      createdAdrRelPath: toPosix(path.relative(repoRoot, out)),
-      title,
-      status: String(args.status).trim(),
-      template: args.template,
-      strategy,
-      date: today,
-      indexUpdated: Boolean(updatedIndexPath),
-      indexChanged,
-      indexPath: updatedIndexPath,
-      indexRelPath: updatedIndexPath ? toPosix(path.relative(repoRoot, updatedIndexPath)) : null,
-    };
-    process.stdout.write(\`\${JSON.stringify(payload)}\\n\`);
-  } else {
-    process.stdout.write(\`\${out}\\n\`);
+  const deciders=String(args.deciders||'').split(',').map((value)=>value.trim()).filter(Boolean).join(', ');
+  const consulted=String(args.consulted||'').split(',').map((value)=>value.trim()).filter(Boolean).join(', ');
+  const informed=String(args.informed||'').split(',').map((value)=>value.trim()).filter(Boolean).join(', ');
+  const rendered=renderTemplate(loadTemplate(args.template),{title,status:String(args.status).trim(),date,deciders,consulted,informed,technicalStory:String(args.technicalStory||'').trim(),chosenOption:String(args.chosenOption||'').trim()});
+  fs.writeFileSync(out,\`\${rendered.trimEnd()}\\n\`,'utf8');
+  let updatedIndexPath=null;
+  let indexChanged=false;
+  if(args.updateIndex){
+    const indexFile=args.indexFile?(path.isAbsolute(args.indexFile)?args.indexFile:path.resolve(repoRoot,args.indexFile)):chooseIndexFile(adrDir);
+    indexChanged=updateIndex(indexFile,{relLink:toPosix(path.relative(path.dirname(indexFile),out)),title,status:String(args.status).trim(),date});
+    updatedIndexPath=indexFile;
   }
+  if(args.json) process.stdout.write(\`\${JSON.stringify({repoRoot,adrDir,createdAdrPath:out,createdAdrRelPath:toPosix(path.relative(repoRoot,out)),title,status:String(args.status).trim(),template:args.template,strategy,date,indexUpdated:Boolean(updatedIndexPath),indexChanged,indexPath:updatedIndexPath,indexRelPath:updatedIndexPath?toPosix(path.relative(repoRoot,updatedIndexPath)):null})}\\n\`);
+  else process.stdout.write(\`\${out}\\n\`);
 }
 
 main();
 `},{file:`scripts/set_adr_status.js`,content:`#!/usr/bin/env node
-/**
- * Update an ADR's status in-place.
- *
- * Supported patterns:
- * - Bullet status: "- Status: proposed" or "* Status: proposed"
- * - Nygard-style section: "## Status" followed by a single-line status value
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-function die(msg) {
-  process.stderr.write(\`\${msg}\\n\`);
-  process.exit(1);
-}
-
-function toPosix(p) {
-  return p.split(path.sep).join('/');
-}
-
-function parseArgs(argv) {
-  if (argv.includes('--help') || argv.includes('-h')) {
-    process.stdout.write(
-      [
-        'Usage: node set_adr_status.js <path> --status <value> [--json]',
-        '',
-        'Example:',
-        '  node set_adr_status.js adr/2025-06-15-foo.md --status accepted',
-        '',
-      ].join('\\n'),
-    );
+const fs=require('node:fs');
+const path=require('node:path');
+
+function die(msg){process.stderr.write(\`\${msg}\\n\`);process.exit(1);}
+function toPosix(value){return value.split(path.sep).join('/');}
+function parseArgs(argv){
+  if(argv.includes('--help')||argv.includes('-h')){
+    process.stdout.write([
+      'Usage: node set_adr_status.js <path> --status <value> [--json]',
+      '',
+      'Example:',
+      '  node set_adr_status.js adr/2025-06-15-foo.md --status accepted',
+      '',
+    ].join('\\n'));
     process.exit(0);
   }
-
-  if (argv.length < 3) die('Missing <path>');
-  const file = argv[2];
-
-  let status = null;
-  let json = false;
-  for (let i = 3; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--status') {
-      if (i + 1 >= argv.length) die('Missing value for --status');
-      status = argv[++i];
-    } else if (a === '--json') {
-      json = true;
-    } else {
-      die(\`Unknown arg: \${a}\`);
-    }
+  if(argv.length<3) die('Missing <path>');
+  let status=null;
+  let json=false;
+  for(let index=3;index<argv.length;index++){
+    const arg=argv[index];
+    if(arg==='--status'){
+      if(index+1>=argv.length) die('Missing value for --status');
+      status=argv[++index];
+    }else if(arg==='--json') json=true;
+    else die(\`Unknown arg: \${arg}\`);
   }
-  if (!status) die('Missing required --status');
-  return { file, status: String(status).trim(), json };
+  if(!status) die('Missing required --status');
+  return {file:argv[2],status:String(status).trim(),json};
 }
-
-function setYamlFrontMatterStatus(lines, newStatus) {
-  // YAML front matter: starts with '---', ends with next '---'
-  if (lines.length < 2 || lines[0].trim() !== '---') return { lines, changed: false };
-
-  let changed = false;
-  const out = [];
-  let inFrontMatter = true;
-  let passedOpening = false;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-
-    if (i === 0 && line.trim() === '---') {
-      passedOpening = true;
-      out.push(line);
-      continue;
-    }
-
-    if (passedOpening && inFrontMatter && line.trim() === '---') {
-      inFrontMatter = false;
-      out.push(line);
-      continue;
-    }
-
-    if (passedOpening && inFrontMatter && /^status\\s*:/.test(line)) {
-      out.push(\`status: \${newStatus}\`);
-      changed = true;
-      continue;
-    }
-
+function setYaml(lines,status){
+  if(lines.length<2||lines[0].trim()!=='---') return {lines,changed:false};
+  const out=[];
+  let inFrontMatter=true;
+  let passedOpening=false;
+  let changed=false;
+  for(let index=0;index<lines.length;index++){
+    const line=lines[index];
+    if(index===0&&line.trim()==='---'){passedOpening=true;out.push(line);continue;}
+    if(passedOpening&&inFrontMatter&&line.trim()==='---'){inFrontMatter=false;out.push(line);continue;}
+    if(passedOpening&&inFrontMatter&&/^status\\s*:/.test(line)){out.push(\`status: \${status}\`);changed=true;continue;}
     out.push(line);
   }
-
-  return { lines: out, changed };
+  return {lines:out,changed};
 }
-
-function setBulletStatus(lines, newStatus) {
-  let changed = false;
-  const out = lines.map((line) => {
-    const m = line.match(/^([*-])\\s*Status:\\s*(.*)$/);
-    if (!m) return line;
-    changed = true;
-    return \`\${m[1]} Status: \${newStatus}\`;
-  });
-  return { lines: out, changed };
+function setBullet(lines,status){
+  let changed=false;
+  return {
+    changed,
+    lines:lines.map((line)=>{
+      const match=line.match(/^([*-])\\s*Status:\\s*(.*)$/);
+      if(!match) return line;
+      changed=true;
+      return \`\${match[1]} Status: \${status}\`;
+    }),
+  };
 }
-
-function setSectionStatus(lines, newStatus) {
-  let changed = false;
-  const out = [];
-
-  for (let i = 0; i < lines.length; i++) {
-    out.push(lines[i]);
-
-    if (!/^##\\s+Status\\s*$/.test(lines[i])) continue;
-
-    // Replace next non-empty, non-heading line. If not found, insert.
-    let j = i + 1;
-    while (j < lines.length && lines[j].trim() === '') {
-      out.push(lines[j]);
-      j++;
-    }
-
-    if (j < lines.length && !/^##\\s+/.test(lines[j])) {
-      out.push(newStatus);
-      changed = true;
-      i = j; // skip original status line
-      continue;
-    }
-
-    out.push(newStatus);
-    changed = true;
-    i = j - 1;
+function setSection(lines,status){
+  const out=[];
+  let changed=false;
+  for(let index=0;index<lines.length;index++){
+    out.push(lines[index]);
+    if(!/^##\\s+Status\\s*$/.test(lines[index])) continue;
+    let next=index+1;
+    while(next<lines.length&&lines[next].trim()===''){out.push(lines[next]);next++;}
+    if(next<lines.length&&!/^##\\s+/.test(lines[next])){out.push(status);changed=true;index=next;continue;}
+    out.push(status);changed=true;index=next-1;
   }
-
-  return { lines: out, changed };
+  return {lines:out,changed};
 }
-
-function main() {
-  const args = parseArgs(process.argv);
-  const filePath = path.resolve(process.cwd(), args.file);
-  if (!fs.existsSync(filePath)) die(\`File not found: \${filePath}\`);
-
-  const content = fs.readFileSync(filePath, 'utf8');
-  const hadTrailingNewline = content.endsWith('\\n');
-  const lines = content.replace(/\\r\\n/g, '\\n').split('\\n');
-
-  let r = setYamlFrontMatterStatus(lines, args.status);
-  if (!r.changed) r = setBulletStatus(lines, args.status);
-  if (!r.changed) r = setSectionStatus(lines, args.status);
-  if (!r.changed) {
-    die(
-      "Could not find a status to update. Expected YAML front matter 'status:', '- Status:'/'* Status:', or a '## Status' section.",
-    );
-  }
-
-  const newContent = r.lines.join('\\n') + (hadTrailingNewline ? '\\n' : '');
-  fs.writeFileSync(filePath, newContent, 'utf8');
-
-  if (args.json) {
-    process.stdout.write(
-      \`\${JSON.stringify({
-        filePath,
-        fileRelPath: toPosix(path.relative(process.cwd(), filePath)),
-        status: args.status,
-        changed: true,
-      })}\\n\`,
-    );
-  } else {
-    process.stdout.write(\`\${filePath}\\n\`);
-  }
+function main(){
+  const args=parseArgs(process.argv);
+  const filePath=path.resolve(process.cwd(),args.file);
+  if(!fs.existsSync(filePath)) die(\`File not found: \${filePath}\`);
+  const content=fs.readFileSync(filePath,'utf8');
+  const hadTrailingNewline=content.endsWith('\\n');
+  const lines=content.replace(/\\r\\n/g,'\\n').split('\\n');
+  let result=setYaml(lines,args.status);
+  if(!result.changed) result=setBullet(lines,args.status);
+  if(!result.changed) result=setSection(lines,args.status);
+  if(!result.changed) die("Could not find a status to update. Expected YAML front matter 'status:', '- Status:'/'* Status:', or a '## Status' section.");
+  fs.writeFileSync(filePath,result.lines.join('\\n')+(hadTrailingNewline?'\\n':''),'utf8');
+  if(args.json) process.stdout.write(\`\${JSON.stringify({filePath,fileRelPath:toPosix(path.relative(process.cwd(),filePath)),status:args.status,changed:true})}\\n\`);
+  else process.stdout.write(\`\${filePath}\\n\`);
 }
 
 main();
 `},{file:`SKILL.md`,content:`---
 name: adr-skill
-description: Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. Trigger on: architecture decisions, technology choices, significant design tradeoffs, decisions that affect >3 files or >1 team, irreversible choices. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.
+description: Create and maintain Architecture Decision Records (ADRs) for agentic coding workflows. Use for proposing, drafting, updating, accepting/rejecting, deprecating, superseding, bootstrapping ADRs, consulting ADRs before impl, and enforcing ADR conventions. Trigger on architecture decisions, tech choices, major tradeoffs, decisions affecting >3 files or >1 team, and hard-to-reverse choices. Uses Socratic questioning plus an agent-readiness checklist.
 metadata:
   category: cross-cutting
   domain: general
@@ -1386,159 +870,118 @@ metadata:
 
 ## Quick Reference
 
-**Purpose:** Create Architecture Decision Records optimized for agentic coding — decisions that agents can implement without follow-up questions.
+**Purpose:** Create ADRs agents can implement from without follow-up.
 
-**Write an ADR when:** Decision changes how system is built, is hard to reverse, affects other people/agents, or has real alternatives.
+**Write an ADR when:** decision changes system shape, is hard to reverse, affects other people/agents, or has real alternatives.
 
 **Four-Phase Workflow:**
-1. **Discover** — Socratic questioning to surface intent, constraints, and alternatives
-2. **Draft** — Fill template (Simple or MADR) with concrete, measurable constraints
-3. **Validate** — Agent-readiness checklist (score ≥ 80%)
-4. **Record** — Save to \`docs/decisions/\` or \`adr/\`, update index
+1. **Discover** — surface intent, constraints, alternatives
+2. **Draft** — fill Simple or MADR template with concrete constraints
+3. **Validate** — review for agent-readiness (target ≥ 80%)
+4. **Record** — save to \`docs/decisions/\` or \`adr/\`, update index
 
 **Two templates:**
 - **Simple** (≤3 options, single-team) — Context → Decision → Consequences → Implementation Plan → Alternatives
-- **MADR** (complex, multi-team) — Full template with Decision Drivers, Pros/Cons matrix, detailed Implementation Plan
+- **MADR** (complex, multi-team) — adds drivers, options matrix, deeper plan
 
-**Commands:** Create → run 4-phase workflow and save to \`docs/decisions/NNNN-slug.md\`. Consult → \`search({ query: "ADR <topic>" })\` before implementing. Update → edit content and YAML status. Deprecate → set \`status: deprecated\` and add a superseded-by link. Bootstrap → create \`docs/decisions/\` plus \`index.md\` if missing.
+**Commands:** Consult existing ADRs before impl. Create/update with scripts below.
 
-**Agent-readiness gate:** Every ADR scores ≥ 80% on: Specificity, Testability, Completeness, Independence, Actionability.
+**Agent-readiness gate:** target ≥ 80%.
 
 ## Mindset
 
-ADRs serve two audiences separated by time: the CURRENT team making the decision, and the FUTURE team wondering "why the hell did they do it this way?"
-
-The future audience is more important. They have zero context about your constraints, discussions, and tradeoffs. Write for them.
-
-An ADR is NOT meeting minutes. It captures:
-- The FORCES that drove the decision (constraints, requirements, team skills)
-- The ALTERNATIVES genuinely considered (with honest evaluation)
-- The IRREVERSIBILITY assessment (one-way door vs two-way door)
-- The CONSEQUENCES acknowledged upfront (technical debt accepted, capability traded)
+Write for future readers with zero context. ADR = decision record, not meeting notes.
 
 ## Philosophy
 
-ADRs created with this skill are **executable specifications for coding agents**. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.
-
-- Constraints must be explicit and measurable, not vibes
-- Decisions must be specific enough to act on ("use PostgreSQL 16 with pgvector" not "use a database")
-- Consequences must map to concrete follow-up tasks
-- Non-goals must be stated to prevent scope creep
-- The ADR must be self-contained — no tribal knowledge assumptions
-- **The ADR must include an implementation plan** — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly
+ADR must let an agent implement without follow-up: explicit constraints, concrete decision, follow-up tasks, non-goals, self-contained context, and an implementation plan.
 
 ## ADR Quality Criteria
 
 An ADR is agent-ready when it passes:
-- [ ] **Context is self-contained** — a reader unfamiliar with the project can understand the problem
-- [ ] **Options include at least 2 genuine alternatives** (no strawmen)
-- [ ] **Decision rationale cites concrete evidence** — performance numbers, blast radius, team constraints
-- [ ] **Consequences are bidirectional** — both benefits AND costs/risks
-- [ ] **Status is explicit** — proposed/accepted/deprecated/superseded with date
-- [ ] **Superseded ADRs link to their replacement** — no orphans
+- [ ] **Context is self-contained**
+- [ ] **Options include at least 2 genuine alternatives**
+- [ ] **Decision rationale cites concrete evidence**
+- [ ] **Consequences are bidirectional**
+- [ ] **Status is explicit**
+- [ ] **Superseded ADRs link to their replacement**
 
 ## When to Write an ADR
 
 Write an ADR when a decision:
 
-- **Changes how the system is built or operated** (new dependency, architecture pattern, infrastructure choice, API design)
+- **Changes how system is built or operated** (new dep, pattern, infra choice, API design)
 - **Is hard to reverse** once code is written against it
-- **Affects other people or agents** who will work in this codebase later
+- **Affects other people or agents** who will work in codebase later
 - **Has real alternatives** that were considered and rejected
 
 ## NEVER
 
-- **NEVER write an ADR after implementation** unless documenting a discovery — ADRs capture the decision moment, not post-hoc rationalization. If the code already exists, you're writing documentation, not a decision record.
-- **NEVER include only one option** — a "decision" with one choice isn't a decision. If there's genuinely only one approach, you don't need an ADR.
-- **NEVER use vague consequences** like "improves maintainability" — cite specific metrics, affected files, or observable outcomes.
-- **NEVER let ADRs accumulate without review** — stale "proposed" ADRs that languish >2 weeks should be accepted or withdrawn.
-- **NEVER modify an accepted ADR** — if the decision changes, SUPERSEDE with a new ADR that links back. History matters.
-- **NEVER write an ADR for trivial decisions** — library version bumps, formatting changes, and routine maintenance don't warrant the ceremony. Reserve ADRs for decisions that are hard to reverse or have team-wide impact.
-- **NEVER skip the "rejected alternatives" section** — documenting WHY you didn't pick option B is often more valuable than explaining why you picked A.
+- **NEVER write ADR after impl** unless documenting discovery
+- **NEVER include only one option**
+- **NEVER use vague consequences**
+- **NEVER let ADRs linger in stale proposed state**
+- **NEVER modify an accepted ADR**; supersede instead
+- **NEVER write ADR for trivial decisions**
+- **NEVER skip rejected alternatives**
 
-When in doubt: if a future agent working in this codebase would benefit from knowing _why_ this choice was made, write the ADR.
 
-### Proactive ADR Triggers (For Agents)
 
-If you are an agent coding in a repo and you encounter any of these situations, **stop and propose an ADR** before continuing:
+### Proactive ADR Triggers (For Agents)
 
-- You are about to introduce a new dependency that doesn't already exist in the project
-- You are about to create a new architectural pattern (new way of handling errors, new data access layer, new API convention) that other code will need to follow
-- You are about to make a choice between two or more real alternatives and the tradeoffs are non-obvious
-- You are about to change something that contradicts an existing accepted ADR
-- You realize you're writing a long code comment explaining "why" — that reasoning belongs in an ADR
+Stop and propose an ADR when you hit a new dependency, a new shared pattern, a non-obvious tradeoff, a conflict with an accepted ADR, or a long code comment explaining "why".
 
-**How to propose**: Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.
+**How to propose**: state decision, why it matters, ask whether to capture as ADR. If yes, run workflow. If no, note reasoning in code comment and move on.
 
 ## Creating an ADR: Four-Phase Workflow
 
-Every ADR goes through four phases. Do not skip phases.
+Every ADR goes through four phases. Do not skip them.
 
 ### Phase 0: Scan the Codebase
 
-Before asking questions, gather enough repo context to avoid contradictory ADRs:
+Before questions, gather enough repo context to avoid contradictory ADRs:
 
-1. **Find existing ADRs.** Check \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`decisions/\`. Note directory, naming, status style, related decisions, and anything this ADR might supersede.
-2. **Check the tech stack.** Read \`package.json\`, \`go.mod\`, \`requirements.txt\`, \`Cargo.toml\`, or equivalent for relevant dependencies and versions.
-3. **Find related code patterns.** Identify the files, directories, and implementation patterns this decision will affect.
-4. **Look for ADR references in code.** Comments and docs often reveal which decisions already govern an area.
+1. **Find existing ADRs.** Check \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`decisions/\`. Note dir, naming, status style, related ADRs, possible supersession.
+2. **Check tech stack.** Read \`package.json\`, \`go.mod\`, \`requirements.txt\`, \`Cargo.toml\`, or equivalent for relevant deps and versions.
+3. **Find related code patterns.** Identify files, dirs, and impl patterns affected.
+4. **Look for ADR references in code.** Comments and docs often reveal governing decisions.
 
 ### Phase 1: Capture Intent (Socratic)
 
-Interview the human to understand the decision space. Ask questions **one at a time**, building on previous answers.
-
-**Core questions** (ask in roughly this order, skip what's already clear from context or Phase 0):
+Ask questions **one at a time**.
 
-1. **What are you deciding?** Push for a short verb phrase title ("Choose X", "Adopt Y", "Replace Z with W").
-2. **Why now?** What changed, broke, or will break if you do nothing?
-3. **What constraints exist?** Tech stack, timeline, budget, team skills, compliance, and existing decisions.
-4. **What does success look like?** Turn "it works" into measurable outcomes.
-5. **What options were considered?** At least two real alternatives, each with a core tradeoff.
-6. **What's the current lean?** Capture the instinct and the reason.
-7. **Who decides?** List decision-makers, consulted experts, and informed stakeholders.
-8. **What would an agent need to implement this?** Affected files, patterns to follow/avoid, config changes, and verification.
+**Core questions** (skip what Phase 0 or context already answered): title, why now, constraints, success criteria, real options, current lean, who decides, and what an agent needs to implement.
 
-**Adaptive follow-ups**: probe where the decision is fuzzy. Useful prompts: "What's the worst-case outcome if this is wrong?", "What would make you revisit this in 6 months?", and "I found [existing ADR/pattern] — does this interact with it?"
+**Adaptive follow-ups**: probe fuzzy areas. Useful prompts: "What's worst case if this is wrong?", "What would make you revisit this in 6 months?", "I found [existing ADR/pattern] — does this interact with it?"
 
 **When to stop**: stop only when every ADR section, especially Implementation Plan and Verification, can be filled without guessing.
 
-**Intent Summary Gate**: Before moving to Phase 2, summarize the title, trigger, constraints, options, current lean, non-goals, related ADRs/code, affected files, and verification plan, then ask: **Does this capture your intent? Anything to add or correct?**
+**Intent Summary Gate**: Before Phase 2, summarize title, trigger, constraints, options, lean, non-goals, related ADRs/code, affected files, and verification plan. Ask: **Does this capture your intent? Anything to add or correct?**
 
-Do NOT proceed to Phase 2 until the human confirms the summary.
+Do NOT proceed to Phase 2 until human confirms summary.
 
 ### Phase 2: Draft the ADR
 
 1. **Choose the ADR directory.**
-
-   - If one exists (found in Phase 0), use it.
-   - If none exists, create \`contributing/decisions/\` (if \`contributing/\` exists), \`docs/decisions/\` (MADR default), or \`adr/\` (simpler repos).
-
+   - If one exists, use it.
+   - If none exists, create \`contributing/decisions/\` (if \`contributing/\` exists), \`docs/decisions/\`, or \`adr/\`.
 2. **Choose a filename strategy.**
-
    - If existing ADRs use date prefixes (\`YYYY-MM-DD-...\`), continue that.
    - Otherwise use slug-only filenames (\`choose-database.md\`).
-
 3. **Choose a template.**
-
-   - Use \`assets/templates/adr-simple.md\` for straightforward decisions (one clear winner, minimal tradeoffs).
-   - Use \`assets/templates/adr-madr.md\` when you need to document multiple options with structured pros/cons/drivers.
-  - See \`references/template-variants.md\` if unsure.
-
-4. **Fill every section from the confirmed intent summary.** Do not leave placeholder text. Every section should contain real content or be removed (optional sections only).
-
-5. **Write the Implementation Plan.** This is the most important section for agent-first ADRs. It tells the next agent exactly what to do. See the template for structure.
-
-6. **Write Verification criteria as checkboxes.** These must be specific enough that an agent can programmatically or manually check each one.
-
-7. **Generate the file.**
-   - Preferred: run \`scripts/new_adr.js\` (handles directory, naming, and optional index updates).
-   - If you can't run scripts, copy a template from \`assets/templates/\` and fill it manually.
+   - Use \`assets/templates/adr-simple.md\` for straightforward decisions.
+   - Use \`assets/templates/adr-madr.md\` for multiple options with structured tradeoffs.
+   - See \`references/template-variants.md\` if unsure.
+4. **Fill every section from confirmed intent summary.** Remove placeholders.
+5. **Write the Implementation Plan.** It tells next agent exactly what to do.
+6. **Write Verification criteria as checkboxes.** They must be specific enough for manual or programmatic checking.
+7. **Generate the file.** Preferred: run \`scripts/new_adr.js\`. Otherwise copy a template and fill it manually.
 
 ### Phase 3: Review Against Checklist
 
-After drafting, review the ADR against the inline quality criteria above, then use \`references/review-checklist.md\` for the full pass.
+Review against inline quality criteria, then use \`references/review-checklist.md\` for full pass.
 
-**Present the review as a summary**, not a raw checklist dump. Format:
+**Present the review as summary**, not raw checklist dump. Format:
 
 > **ADR Review**
 >
@@ -1551,102 +994,85 @@ After drafting, review the ADR against the inline quality criteria above, then u
 >
 > **Recommendation**: {Ship it / Fix the gaps first / Needs more Phase 1 work}
 
-Only surface failures and notable strengths. If there are gaps, propose specific fixes. Do not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.
+Surface failures and notable strengths only. If gaps exist, propose fixes. Do not finalize until ADR passes or human accepts gaps.
 
 ## Consulting ADRs (Read Workflow)
 
-Agents should read existing ADRs **before implementing changes** in a codebase that has them. This is not part of the create-an-ADR workflow — it's a standalone operation any agent should do.
-
-Consult ADRs:
+Read existing ADRs **before implementing changes** in repos that have them.
 
-1. **Before architecture work.** Especially auth, data layer, API design, infra, or any change that could contradict an existing decision.
-2. **Find the ADR directory and index.** Check \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`decisions/\`, then read \`README.md\` or \`index.md\` if present.
-3. **Focus on accepted ADRs first.** Those are the active rules unless superseded.
-4. **Read the full ADR, not just the title.** Context, decision, consequences, non-goals, and Implementation Plan all matter.
-5. **Follow the Implementation Plan.** If an ADR says new queries go through \`src/db/\`, do that.
-6. **Escalate conflicts.** If code and ADR disagree, or a new change would contradict an accepted ADR, flag it or draft a superseding ADR.
-7. **Reference the ADR in your work.** Link it in code comments or PR notes when the decision directly governs the change.
+1. **Before architecture work.**
+2. **Find ADR dir and index.** Start with accepted ADRs.
+3. **Read full ADR, not just title.**
+4. **Follow the Implementation Plan.**
+5. **Escalate conflicts or contradictions.**
+6. **Reference governing ADR in your work.**
 
 ## Code ↔ ADR Linking
 
-ADRs should be bidirectionally linked to the code they govern.
-
-- **ADR → Code**: the Implementation Plan should name affected paths, patterns, config changes, and verification commands.
-- **Code → ADR**: add one lightweight comment at the entry point that links back to the governing ADR.
-- **Why**: this makes the reasoning discoverable in both directions and makes superseded decisions easier to unwind.
+- **ADR → Code**: Implementation Plan names affected paths, patterns, config changes, verification commands.
+- **Code → ADR**: add one lightweight comment at entry point linking back to governing ADR.
 
 ## Other Operations
 
 ### Update an Existing ADR
 
-1. Identify the intent:
-
-   - **Accept / reject**: change status, add any final context.
-   - **Deprecate**: status → \`deprecated\`, explain replacement path.
-   - **Supersede**: create a new ADR, link both ways (old → new, new → old).
-   - **Add learnings**: append to \`## More Information\` with a date stamp. Do not rewrite history.
-
-2. Use \`scripts/set_adr_status.js\` for status changes (supports YAML front matter, bullet status, and section status).
+1. Identify intent: accept/reject, deprecate, supersede, or add learnings.
+2. Use \`scripts/set_adr_status.js\` for status changes.
 
 ### Post-Acceptance Lifecycle
 
 After an ADR is accepted:
 
-1. **Create implementation tasks.** Each item in the Implementation Plan and each follow-up in Consequences should become a trackable task (issue, ticket, or TODO).
-2. **Reference the ADR in PRs.** Link to the ADR in PR descriptions, e.g. "Implements \`contributing/decisions/2025-06-15-use-sqlite-for-test-database.md\`."
-3. **Add code references.** Add ADR path comments at key implementation points.
-4. **Check verification criteria.** Once implementation is complete, walk through the Verification checkboxes. Update the ADR with results in \`## More Information\`.
-5. **Revisit when triggers fire.** If the ADR specified revisit conditions, monitor them.
+1. **Create implementation tasks.**
+2. **Reference ADR in PRs.**
+3. **Add code references.**
+4. **Check verification criteria.** Update ADR with results in \`## More Information\`.
+5. **Revisit when triggers fire.**
 
 ### Index
 
-If the repo has an ADR index/log file (often \`README.md\` or \`index.md\` in the ADR dir), keep it updated.
+If repo has ADR index/log file, keep it updated.
 
-Preferred: let \`scripts/new_adr.js --update-index\` do it. Otherwise:
-
-- Add a bullet entry for the new ADR.
-- Keep ordering consistent (numeric if numbered; date or alpha if slugs).
+- Let \`scripts/new_adr.js --update-index\` handle it when possible.
+- Otherwise add new ADR entry and keep ordering consistent.
 
 ### Bootstrap
 
-When introducing ADRs to a repo that has none:
+When introducing ADRs to repo that has none:
 
 \`\`\`bash
 node scripts/bootstrap_adr.js
 \`\`\`
 
-This creates the directory, an index file, and a filled-out first ADR ("Adopt architecture decision records") with real content explaining why the team is using ADRs. Use \`--json\` for machine-readable output. Use \`--dir\` to override the directory name.
+Creates dir, index, and first ADR.
 
 ## Resources
 
 ### scripts/
 
-- \`scripts/new_adr.js\` — create a new ADR file from a template, using repo conventions.
-- \`scripts/set_adr_status.js\` — update ADR status in-place. Use \`--json\` for machine output.
-- \`scripts/bootstrap_adr.js\` — create ADR dir, \`README.md\`, and an initial "Adopt ADRs" decision.
+- \`scripts/new_adr.js\`
+- \`scripts/set_adr_status.js\`
+- \`scripts/bootstrap_adr.js\`
 
 ### references/
 
-- \`references/review-checklist.md\` — full Phase 3 checklist.
-- \`references/adr-conventions.md\` — directory, filename, status, and lifecycle conventions.
-- \`references/template-variants.md\` — when to use simple vs MADR.
-- \`references/examples.md\` — filled-out examples.
+- \`references/review-checklist.md\`
+- \`references/adr-conventions.md\`
+- \`references/template-variants.md\`
+- \`references/examples.md\`
 
 ### assets/
 
-- \`assets/templates/adr-simple.md\` — lean template for straightforward decisions.
-- \`assets/templates/adr-madr.md\` — MADR 4.0 template for structured tradeoffs.
-- \`assets/templates/adr-readme.md\` — default ADR index scaffold.
+- \`assets/templates/adr-simple.md\`
+- \`assets/templates/adr-madr.md\`
+- \`assets/templates/adr-readme.md\`
 
 ### Script Usage
 
 \`\`\`bash
 node scripts/new_adr.js --title "Choose database" --status proposed
-
-node scripts/new_adr.js --title "Choose database" --status proposed --update-index
-node scripts/new_adr.js --title "Choose database" --template madr --status proposed
 node scripts/bootstrap_adr.js --dir docs/decisions
 \`\`\`
 
-Scripts auto-detect ADR directory and filename strategy. Use \`--dir\`, \`--strategy\`, and \`--json\` when you need overrides or machine-readable output.
+Use \`--dir\`, \`--strategy\`, and \`--json\` as needed.
 `}];export{e as default};