ADR Kit v0.36.0

ADR Kit v0.36.0

ADR Kit v0.36.0 delivers one certified native governance experience for Claude
Code CLI, OpenAI Codex CLI, and GitHub Copilot CLI.

Highlights

• One canonical set of 14 ADR workflows generates optimized native skills and
  prompts for all three supported clients.
• Client-native manifests, fail-open hooks, and key-free MCP declarations
  preserve each CLI's real discovery and lifecycle contracts.
• The idempotent installer detects installed clients, presents its plan,
  prepares a verified local payload, supports stable updates and rollback, and
  preserves unrelated user configuration.
• Fast and deep doctor modes diagnose generated drift, settings, client
  registration, MCP, hooks, latency, and optional local-model judgment.
• Windows-native hook and generator performance are release gates. The
  deterministic generator's warm no-op path performs zero content rewrites.
• Native evidence for all three clients is bound to the exact candidate commit
  and prepared payload. Release automation consumes separately retained
  evidence to avoid a self-referential candidate hash.

Scope and compatibility

The current first-class scope is exactly Claude Code CLI, Codex CLI, and GitHub
Copilot CLI. Windows is the certified native baseline. macOS and Linux are
best-effort, and wider coding-agent support remains deferred to TASK-43.

ADR Kit retains its zero-runtime-dependency policy and supports Python 3.10 and
newer. Paid or cloud model judgment remains explicit opt-in.

Verification

• Full repository suite: 746 passed, 6 expected skips.
• Strict ADR lint and generated ADR indexes: pass.
• Generated client adapter drift: clean.
• Windows generator benchmark: clean p95 735.485 ms; warm no-op p95 60.974 ms;
  zero warm writes.
• The stable release is published only after the all-three native Windows
  certification workflow passes for the exact candidate.

ADR Kit v0.35.0

ADR Kit v0.35.0 supersedes v0.34.2 as the recommended release.

Highlights:

• Quiet, structured hook output for Claude Code, OpenAI Codex, and GitHub Copilot CLI.
• English agent-skill metadata across distributed client packages.
• Updated agent-first installation and integration documentation for the three supported clients.
• Cursor product references removed from active documentation and packaging.
• Version stamps synchronized across Claude, Codex, Copilot, templates, and managed hooks.

Verification:

• All required GitHub checks passed on PR #20, including 647 pytest cases (1 skipped), Python 3.10/3.12 on Windows, macOS, and Linux, packaging validation, ADR enforcement, and generated-index freshness.

Upgrade from v0.34.2 using the normal ADR Kit update flow; auto-update consumers can now resolve v0.35.0.

ADR Kit v0.34.2

ADR Kit v0.34.2 makes the Claude Code, OpenAI Codex, and GitHub Copilot CLI integrations quiet by default.

• Claude hooks suppress raw output while preserving model-only ADR context.
• Routine progress labels are removed.
• All three distributions carry verified English skill metadata.
• README and install guides now lead with the three first-class integrations.
• Obsolete client-specific references and runtime branches are removed.

Upgrade with your client's normal plugin update command, or rerun the agent installer from the v0.34.2 checkout:

python scripts/install-agent-envs.py --project-root /path/to/project

Existing copied project artifacts can be refreshed with the ADR Kit upgrade skill.

v0.34.1 - Copilot MCP path hotfix

ADR Kit v0.34.1 fixes GitHub Copilot CLI MCP startup when ADR Kit is installed as a plugin but Copilot is opened in another repository.

Fixed

• Copilot now resolves the bundled server through ${PLUGIN_ROOT}/bin/adr-mcp instead of looking for <active-project>/bin/adr-mcp.
• cwd remains . so ADR context, status, quality, and enforcement operate on the active project.
• Installer validation launches the manifest from an unrelated workspace, verifies the served root, and completes a real initialize/tools-list handshake.
• README troubleshooting now gives agents the native marketplace update, plugin update, inspection, and MCP reload sequence.

Upgrade

copilot plugin marketplace update rvdbreemen-adr-kit-copilot
copilot plugin update adr-kit
copilot mcp get adr-kit

The MCP args should contain ${PLUGIN_ROOT}/bin/adr-mcp. Start a new Copilot session or run /mcp reload after updating.

Validation

• 641 tests passed, 4 skipped.
• Windows, macOS, and Linux CI passed on Python 3.10 and 3.12.
• ADR enforcement, generated index freshness, packaging, and plugin payload synchronization passed.

Full changelog: https://github.com/rvdbreemen/adr-kit/blob/v0.34.1/CHANGELOG.md

v0.34.0

ADR Kit v0.34.0 - selectable ADR formats, a JSON decision graph, and the closed source-audit hardening set.

Documentation

• Added an agent-first ADR discovery contract: inspect the generated JSON graph
  or call adr-context, use metadata and links to shortlist records, then open
  the authoritative Markdown ADR before applying a constraint.
• Added a prominent, client-neutral INSTALL-AGENT.md runbook so coding
  agents can detect, preview, install, initialize, and validate ADR Kit without
  reading the full README. Native Claude Code, Codex, and Copilot paths fall
  back to MCP, Agent Skills, or direct Python commands for other agents.
• Explained the MADR default in the README, human and agent installation
  guides, and the installed project guide: MADR minimizes agent inference,
  Nygard optimizes concision, and canonical preserves upgrade compatibility.

Added

• Versioned JSON ADR graph (TASK-30 / ADR-007).
  bin/adr-index docs/adr now generates ADR-INDEX.json alongside the compact
  Markdown and README views. The timestamp-free graph exposes format-neutral
  lifecycle metadata, bounded decision summaries, enforcement scope, evidence
  pointers, and sorted typed relationship edges under
  schemas/adr-index.schema.json.
• Actionable context results. bin/adr-context --format json retains its
  existing ranking fields and adds source path, lifecycle status, body format,
  decision summary, scope, declared links, and invariant metadata.
• Three-platform installer contract (TASK-29).
  scripts/install-agent-envs.py now validates its full source and Python
  3.10+ child runtime before client mutations, prepares a persistent
  platform-local marketplace with the exact interpreter embedded in Codex and
  Copilot MCP manifests, restores Unix executable modes, and completes a real
  MCP initialize/tools-list smoke test. Detection and installation failures
  are isolated per client. CI runs the installer contract on Windows, macOS,
  and Linux.
• Shipped profile catalog (TASK-28). bin/adr profiles now gives humans
  and coding agents an ordered catalog, with JSON output, MADR preference,
  format guidance, exact template paths, and installed availability. Profile
  selection and template resolution share one registry, so only madr,
  nygard, and canonical are selectable and a missing shipped template
  blocks ADR creation before a record is written.
• Legacy format discovery and migration plans (TASK-27).
  bin/adr-migrate --plan scans canonical and recognizable old filenames,
  reports supported-profile metadata/rename work, and conservatively detects
  Y-Statement, Tyree/Akerman, arc42, hybrid, and unknown shapes. Install,
  init, upgrade, and lint surface the same read-only advice; no path migrates
  content automatically. The deterministic supported-profile path also
  normalizes legacy numeric H1 headings and adds required extension sections.
• Selectable ADR body profiles (TASK-26). madr, nygard, and the
  backward-compatible canonical profile share one stdlib semantic registry.
  bin/adr new honors template.profile with MADR as the default, while
  --profile selects one record.
• Deterministic profile migration. bin/adr-migrate --to-profile supports
  dry-run, check, explicit-source disambiguation, and idempotent conversion
  without rewriting invariant metadata, history, references, or Enforcement.
• Format research and ADR-005. A cited evaluation covers Nygard, MADR,
  Y-Statements, Tyree/Akerman, arc42, and ISO-oriented records. ADR-005
  supersedes ADR-003's canonical-only storage decision.

Changed

• Index, context, and relationship tools now share one stdlib, format-aware ADR
  catalog loader. adr-index --check checks all three generated views and CI
  validates the JSON graph against its versioned schema.
• Lint, quality, index, context, judge, related, retirement, suggestion,
  audit, lifecycle, and edit-time injection consume semantic roles across all
  supported profiles. Unknown and ambiguous hybrid records fail strict lint
  with an explicit migration path.
• Generated client payload drift checks normalize CRLF and LF before
  comparison, keeping --check deterministic across Windows and Unix.
• Directly invoked hooks and engine entry points now retain executable modes in
  Git archives, and the Windows/macOS/Linux CI matrix checks both manual and
  automatically prepared installation paths.

Fixed

• Closed every actionable finding from the 2026-07-18 multi-perspective source
  audit: bounded regex execution, schema-validated runtime configuration,
  fail-closed diff limits, exact staged/worktree snapshots, decoded Git paths,
  complete generated-validator semantics or explicit rejection, legal and
  rollback-safe lifecycle changes, explicit context authority, transactional
  release bumps, and cross-process guardian/watcher state updates.
• Release preflight now validates and computes all ten versioned targets before
  the first write, rolls every target back on failure, and prints the complete
  staging set.
• Public install, security, roadmap, supersession, validator, audit, and
  changelog-link documentation now matches the shipped behavior.
• The clarity gate no longer reports acronyms it cannot help with. It ignores
  a documented allowlist of universal technical vocabulary (ADR, JSON,
  YAML, HTTP, and similar), accepts the expansion (ACRONYM) word order in
  addition to ACRONYM (expansion), and skips YAML frontmatter, where an inline
  expansion cannot be written. Previously any ADR whose title contained a common
  acronym could never satisfy bin/adr accept, because acceptance runs the gate
  set that includes clarity. Its finding summary also counted only the first
  five hits; it now counts every distinct acronym.
• The packaged Windows hook wrapper is now smoke-tested through its absolute
  path, matching how plugin.json launches it. The previous bare-name
  invocation failed on shells that set NoDefaultCurrentDirectoryInExePath.

---

Full changelog: https://github.com/rvdbreemen/adr-kit/blob/v0.34.0/CHANGELOG.md

Install: see INSTALL.md, or INSTALL-AGENT.md for coding agents.

v0.33.0 - Native Codex and Multi-CLI Installation

ADR Kit v0.33.0: Native Codex and multi-CLI installation

ADR Kit now ships first-class, separate plugins for OpenAI Codex and the
standalone GitHub Copilot CLI while preserving the existing Claude Code plugin.

Highlights

• Codex gets a validated .codex-plugin distribution with 14 namespaced
  skills and the four-tool, key-free ADR MCP server.
• The standalone Copilot CLI gets its own marketplace and self-contained
  plugin with 14 skills and the same MCP server.
• scripts/install-agent-envs.py detects real claude, codex, and copilot
  executables from version output, installs every detected client through its
  native plugin API, and validates the result.
• MCP tools now accept project_root and adr_dir, so a server launched from
  a plugin cache always operates on the active workspace.
• Project pre-commit hooks resolve the newest engine across Claude Code,
  Codex, and Copilot CLI plugin caches.
• Generated Codex and Copilot payloads are checked byte-for-byte against the
  canonical engines, schemas, templates, and instructions.

Install

From a cloned checkout:

python scripts/install-agent-envs.py --detect-only
python scripts/install-agent-envs.py

Manual client commands are documented in README.md and INSTALL.md.

Compatibility

• Claude Code keeps its existing .claude-plugin manifest, 14 skills,
  adr-generator agent, and SessionStart, PreToolUse, and PostToolUse hooks.
• Codex uses the separate codex/ distribution and namespaced skills such as
  $adr-kit:context.
• Copilot support targets the standalone @github/copilot CLI, not
  gh copilot or VS Code agent mode.

Validation

• Official Codex plugin validator: PASS.
• Claude Code plugin validation and component inventory: PASS.
• Clean-home installer smoke tests for Claude Code, Codex, and Copilot CLI:
  PASS.
• Codex and Copilot MCP/skill discovery: PASS.
• Full automated suite: 524 passed, 3 skipped.
• Strict ADR lint, generated index, and ADR doctor: PASS with 0 findings.
• Markdown lint, JSON syntax, payload drift, and release-version checks: PASS.

v0.32.0 - Local ADR Governance

v0.32.0 - Local ADR Governance

This release consolidates the local governance workstreams after v0.31.0 and moves every update-sensitive artifact to version 0.32.0: plugin manifest, marketplace manifest, guide stamp, wrapper stamps, changelog, tags, and GitHub Release notes.

Highlights

• Added canonical ADR frontmatter with a stdlib parser, renderer, migration helper, and JSON Schema.
• Added bin/adr-lint --strict for schema validation, verified evidence resolution, reciprocal supersession checks, binding gate lookup, and CI-ready failure handling.
• Added bin/adr lifecycle commands: propose, accept, supersede, reject, and document.
• Added after-the-fact ADR acceptance: shipped behaviour can be documented with verified_in evidence and auto-accepted only after strict lint and quality checks pass.
• Added bin/adr-doctor, a local health check for agents and CI that combines strict lint, generated index freshness, staleness checks, evidence drift checks, missing-gate detection, and material-drift audit summaries.
• Consolidated bin/adr-index into two compatible modes: ADR-004 context index generation for docs/adr/ADR-INDEX.md, and local README index generation/checking for docs/adr/README.md.
• Updated agent-facing instructions so agents use generated indexes, strict lint, doctor checks, and Backlog.md instead of editing governance files by hand.

Upgrade Notes

• Claude Code plugin updates compare .claude-plugin/marketplace.json plugins[].version; this release bumps that field to 0.32.0 together with .claude-plugin/plugin.json.
• Copied project artifacts are stamped as 0.32.0. Existing projects may get a guardian stale-artifact nudge after the plugin update; run /adr-kit:upgrade to refresh the git wrapper, project settings entry, and .claude/adr-kit-guide.md.
• Regenerate both generated ADR indexes when adopting the new lifecycle tools:

bin/adr-index --adr-dir docs/adr -o docs/adr/ADR-INDEX.md
bin/adr-index docs/adr/

Validation

• Full Python suite: 504 passed, 7 skipped.
• Strict ADR lint: 4 ADRs pass, 0 failures.
• bin/adr-doctor --fix-index docs/adr/ --format json: clean.
• Generated context index and README index are fresh.

v0.31.0 - Layered ADR Context Injection

v0.31.0 - Layered ADR Context Injection

This release makes ADR context active before and during agent edits.

Highlights

• Added ADR-004 and the layered context injection model: session index, pre-edit injection, post-edit nudge, and commit-time enforcement.
• Added bin/adr-index --adr-dir docs/adr -o docs/adr/ADR-INDEX.md, a deterministic compact ADR map that can be imported from CLAUDE.md.
• Added the PreToolUse edit-tier hook through .claude-plugin/plugin.json, backed by bin/adr-watch --pre-edit.
• Added enforcement floor coverage buckets to bin/adr-status.
• Added CI freshness checking for docs/adr/ADR-INDEX.md.
• Extended bin/adr-lint to flag one-directional supersession drift.

Upgrade Notes

• Existing plugin installs should update through the normal Claude Code plugin flow.
• Projects using copied artifacts may see stale guide or hook stamps after the plugin updates; run /adr-kit:upgrade to refresh them.
• Regenerate the compact context index with:

bin/adr-index --adr-dir docs/adr -o docs/adr/ADR-INDEX.md

v0.30.5

Fixed

• Config schema rejected the judge.* performance-budget knobs (#10). schemas/adr-kit-config.schema.json declares judge with additionalProperties: false but omitted the TASK-712 performance-bounded-hooks fields that adr-kit's own dogfood .adr-kit.json (and downstream projects) already set: pre_commit_timeout_ms, pre_push_timeout_ms, llm_timeout_ms, warn_on_exceed. Config validation failed with 'pre_commit_timeout_ms' was unexpected before any ADR was evaluated, including against this repo's own config. The four knobs are now declared as permissive, documented properties; additive, so previously-valid configs stay valid.

Full changelog: https://github.com/rvdbreemen/adr-kit/blob/v0.30.5/CHANGELOG.md

v0.30.4

Fixed

• bin/bump-version now also stamps the guide template's version line. templates/adr-kit-guide.md opens with <!-- adr-kit-guide vX.Y.Z -->, which /adr-kit:upgrade uses to decide whether a project's copied guide is fresh; the line had been frozen at v0.18.0 because no release step updated it, so the freshness check would have reported every guide as stale forever. Found by running /adr-kit:upgrade on this repo itself. Covered by a lockstep test (template line must equal plugin.json version) and a bump fixture test.

Changed

• This repo now carries its own adr-kit footprint (dogfooding): CLAUDE.md stub and the pre-commit wrapper at .githooks/pre-commit with core.hooksPath set, so Enforcement violations are caught locally before CI. ADR-003 deliberately carries no Enforcement block (process decision, no code surface).