# Decisions Compendium Compact rendered index of every ADR's chosen option, confirmation criteria, and relationship graph. **Authoritative substance lives in the per-ADR body** (`-..md`); this compendium is a derived view for routine `wr-architect:agent` compliance review. **Two sections:** - **In-force decisions** (`proposed` + `accepted`) — the current rules to follow. - **Historical decisions** (`superseded` + `rejected` + `deprecated`) — direction for what NOT to do. Useful when reviewing a proposed change that re-treads a path already tried, or that conflicts with a superseded decision's still-valid intent. The status badge on each entry says which kind it is. For deep-dive — creating, evolving, ratifying, or contesting a decision — open the per-ADR file directly. `/wr-architect:create-adr`, `/wr-architect:capture-adr`, and `/wr-architect:review-decisions` all keep the full body in scope. Decision Drivers, Considered Options bodies, Pros and Cons, Consequences narrative, and Reassessment Criteria are intentionally NOT in this routine view — they live in the per-ADR body. **Total ADRs:** 24 (20 in-force, 4 historical) --- ## In-force decisions _20 ADRs. These are the current rules. The architect agent reads this section first for routine compliance review._ ### ADR-0001 — 0001. Use ES Modules for All Code **Status:** accepted | **Oversight:** confirmed **Chosen:** Chosen option: **ES Modules throughout the entire codebase**, because users install and run the CLI rather than importing it as a library, modern tooling (vitest, ESLint, bundlers) works best with ES modules, and all supported Node.js LTS v... ### ADR-0002 — 0002. Support JSON and XML Output Formats **Status:** accepted | **Oversight:** confirmed **Chosen:** Chosen option: **JSON and XML output formats alongside the existing table format**, because the CLI must serve both modern automation (JSON) and environments where XML is still the consumed format, while preserving the existing human-readab... ### ADR-0003 — 0003. Standardize CLI Exit Codes **Status:** accepted | **Oversight:** confirmed **Chosen:** Chosen option: **three-code scheme**, because it gives automation a single deterministic contract that survives the introduction of new modes and aligns with the principle that exit code `2` is reserved for tool errors (mirroring `getopt` a... ### ADR-0004 — 0004. Add Check Mode for CI/CD Enforcement **Status:** accepted | **Oversight:** confirmed **Chosen:** Chosen option: **`--check` flag**, because opt-in enforcement preserves the default informational behaviour, makes the intent explicit at the call site, and composes cleanly with the exit-code contract in ADR-0003. ### ADR-0005 — 0005. Semantic Release Version Management **Status:** accepted | **Oversight:** confirmed **Chosen:** Chosen option: **Version bumps and `package.json` updates are managed exclusively by semantic-release in the CI/CD pipeline and are NOT committed back to the repository**, because git tags are the authoritative version record, clean history... ### ADR-0006 — 0006. Use JSDoc with TypeScript for Type Checking **Status:** accepted | **Oversight:** confirmed **Chosen:** Chosen option: **JSDoc annotations with TypeScript as a type checker (not a compiler)**, because TypeScript is already installed, JSDoc coverage already exists, and the project's scale and stability do not warrant a build step. ### ADR-0007 — 0007. ESLint Plugin Selection Strategy **Status:** accepted | **Oversight:** confirmed **Chosen:** Chosen option: **Do NOT add `eslint-plugin-unicorn` or additional linting plugins at this time**, because current quality measures are sufficient for the project's scale and there is no evidence of problems these plugins would solve. ### ADR-0008 — 0008. Use better-npm-audit for Security Audit Exception Management **Status:** accepted | **Oversight:** confirmed **Chosen:** Chosen option: **Use `better-npm-audit` for security audit exception management in CI/CD pipelines**, because it provides a declarative, version-controlled exception list with an audit trail, while still catching new vulnerabilities. ### ADR-0011 — 0011. ADR Format and Lifecycle Convention **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen option: **MADR 4.0 with `.proposed.md`/`.accepted.md`/`.superseded.md` filename suffixes**, because it aligns the project with the format the `wr-architect:create-adr` skill produces, makes status visible in `ls docs/decisions/`, and... ### ADR-0012 — 0012. Authentication Mechanism for Autonomous GitHub Workflows **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen option: **OIDC token-exchange via Anthropic** (Option 3), because it eliminates the manual credential-provisioning step entirely, produces short-lived tokens (no rotation cycle), and reuses the existing Claude Code GitHub App install... ### ADR-0014 — 0014. `--update` writes the latest-safe version, not the semver-range-satisfying version **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen option: **Write `latest` (4th tuple element, post-filter / post-smart-search) into `package.json`**, because it (a) is the only interpretation consistent with the spec's safety claim — the 4th element is the version the filters hav... ### ADR-0016 — 0016. Pre-commit hook auto-write and re-stage policy **Status:** proposed | **Oversight:** confirmed | **Supersedes:** 0013-pre-commit-hook-read-only-policy **Chosen:** Chosen option: **Option 1 — plain-shell write-and-restage on staged files only**, because it honours the project's zero-runtime-dep / minimal-devDep posture (carried forward from ADR-0013), the implementation is small enough to read in on... ### ADR-0017 — 0017. Single-workflow inline-loop for autonomous dependency updates **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen option: **"Single inline-loop workflow"**, because it matches the maintainer's confirmed design intent, eliminates the cross-workflow `workflow_run` indirection that was load-bearing only under the old fallback framing, and lets reco... ### ADR-0018 — 0018. Surface known-vulnerable-but-unfixable packages in dry-aged-deps output **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen option: **"On by default in all output formats, suppressible via `--no-unfixable`"**, because it directly satisfies JTBD-006's default-policy expectation and JTBD-008's PR-body inspection job. Visibility-first is the right default fo... ### ADR-0019 — Adopt the Problem-RFC-Story Framework (per @windyroad/itil ADR-060) **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen option: **"Option A"**, because the framework is already implemented in the `@windyroad/itil` plugin we already adopt; reinventing the schema or skipping the tier would either fork the framework or leave direction-confirmed work (P01... ### ADR-0020 — 0020. Test placement: co-locate paired tests beside their `src/` module **Status:** proposed | **Oversight:** confirmed | **Supersedes:** 0015-test-placement-co-location-exception-for-tdd-hook **Chosen:** Chosen: **Option 1 (universal co-location for paired tests)**. ### ADR-0021 — 0021. `--update` reconciles package-lock.json via incremental `npm install --package-lock-only` **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen option: **"Reconcile in `--update`"** (Option 1), selected by the **Confirmation:** REQ-POST-UPDATE (prompts/011.0) is amended: post-update reconciles the; A test asserts the reconcile spawns npm with --ignore-scripts and; A test asserts the no-safe-updates path does NOT spawn the reconcile. **Related:** ADR-0014, ADR-0017, ADR-0008 ### ADR-0022 — 0022. `--update`/`--check` flag and skip un-landable updates via npm-resolver bisect **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen (maintainer, 2026-07-09, via AskUserQuestion): **Confirmation:** A fixture batch with one ERESOLVE-inducing update classifies that update; A non-ERESOLVE npm error during reconcile still fails loud (ADR-0021 preserved).; No code path passes --force / --legacy-peer-deps.; The incompatible-peers surface is additive across table/JSON/XML. **Related:** ADR-0021, ADR-0018, ADR-0014, ADR-0002 ### ADR-0023 — Surface deprecated dependencies advisory-only in a dedicated section **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen: **surface the verbatim npm deprecation message in a dedicated section (table) / `deprecated` array (JSON, XML), advisory-only** — deprecation never influences filtering or `--update`. This is the strictest reading of the user's "j... **Confirmation:** A project depending on a known-deprecated package (e.g. clerk-sveltekit) shows a Deprecated dependencies secti...; --update applied to such a project produces the same package.json/lockfile result as before this change (depre...; The deprecated value is read from the same per-package registry call as time (no second npm view per package) ... ### ADR-0024 — Pin CI npm to the lockfile-generator npm version **Status:** proposed | **Oversight:** confirmed **Chosen:** Chosen option: **"Align every release-path CI npm pin to the lockfile-generator npm"**, because the lockfile is generated by the npm the dev/agent sessions actually run (npm 11.x) and the CI pin is the side that can be moved to match withou... --- ## Historical decisions _4 ADRs. These were tried and superseded, rejected, or deprecated. Read them as direction for what NOT to do, or to understand the lineage of an in-force decision. Do not enforce them as current rules._ ### ADR-0009 — 0009. Scheduled Autonomous Dependency-Update Workflow **Status:** superseded **Chosen:** Chosen option: **Pure scheduled GitHub Actions workflow opening a PR with `gh pr merge --auto --squash`**, because it produces an auditable PR validated by the existing `ci-publish.yml` build-and-test job, requires no new long-lived secrets... ### ADR-0010 — 0010. AI Agent CI Trust Boundary for Dependency-Update Recovery **Status:** superseded **Chosen:** Chosen option: **`claude-code-action` invoked only on `prepush` or `ci-publish.yml` failure, with a strict writable-paths allow-list and a single-retry policy**, because it confines AI authority to the moment of failure (rare events in stea... ### ADR-0013 — 0013. Pre-commit hook read-only policy **Status:** superseded **Chosen:** Chosen option: **Option 1 — read-only check (`format:check` abort)**, because it eliminates the silent-mutation foot-gun with a one-line change to the hook and no new dependency. The auto-fix path remains available to the developer as a d... ### ADR-0015 — 0015. Test placement: co-location exception for `src/update-packages.test.js` **Status:** superseded **Chosen:** Chosen: **Option 1 (narrow exception)** in combination with P004 (Option 4's report-upstream path). Co-located tests for `src/` modules stay where they are; future new tests for `src/` modules require a fresh ADR (or amendment of this one) ...