adrkit

# adrkit

**Decision memory for human- and agent-authored plans** — architecture decision
records that are machine-readable, enforceable in CI, and legible to agents,
without leaving git.

[![npm version](https://img.shields.io/npm/v/@adrkit/cli?logo=npm&label=%40adrkit%2Fcli)](https://www.npmjs.com/package/@adrkit/cli)
[![CI](https://github.com/mbeacom/adrkit/actions/workflows/ci.yml/badge.svg)](https://github.com/mbeacom/adrkit/actions/workflows/ci.yml)
[![ADRs](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fadrkit.dev%2Flint.json&query=%24.checked&label=ADRs&color=cb492d)](./docs/adr)
[![ARB queue](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fadrkit.dev%2Fqueue.json&query=%24.totalItems&label=ARB%20queue&suffix=%20pending&color=cb492d)](./docs/adr)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)

Most ADR tooling is a markdown template and a static site generator. That
*records* a decision; it doesn't make the decision *do* anything. adrkit treats a
record as **typed data with a markdown body** and adds one field — `affects` —
so a tool can answer *"which decisions govern this pull request?"* and put the
answer where the next decision is being made.

## Decision governance, not generated documentation

Generated knowledge systems answer *"how does the system work now?"* adrkit
answers *"what did people decide, what alternatives were rejected, and which
decisions govern this change?"*
[ADR-0037](docs/adr/0037-treat-generated-knowledge-systems-as-downstream-read-models-not-decision-authorities.md)
sets that boundary: generated knowledge systems are downstream read models of
adrkit's human-reviewed decision corpus, never decision authorities.

Tools such as [OpenWiki](https://github.com/langchain-ai/openwiki) can consume
ADRs as evidence and turn them into browsable current-state documentation. That
is complementary to adrkit: the generated wiki is a downstream read model, while
the reviewed records in git retain authority over decision lifecycle and typed
relationships. Machine verification of generated content is not human
ratification of a decision.

See the provisional
[generated-knowledge guide](https://adrkit.dev/generated-knowledge/) for the
OpenWiki setup being evaluated and the ownership boundary ADR-0037 sets between
the two tools.

## Quickstart

The CLI is published as [`@adrkit/cli`](https://www.npmjs.com/package/@adrkit/cli)
and exposes the `adr` binary. Published artifacts target **Node 22+**:

```sh
npx @adrkit/cli lint                 # validate the corpus in docs/adr
npx @adrkit/cli explain src/payments/api.ts   # which decisions govern this file?
```

Or add it to a project (Bun-first repos can use `bun add -D @adrkit/cli` / `bunx`):

```sh
npm i -D @adrkit/cli
```

The pure library surfaces install independently:
`npm i @adrkit/core @adrkit/evaluator`.

See the [Quickstart guide](https://adrkit.dev/quickstart/) and the full
[command reference](https://adrkit.dev/commands/).

## Choose a starting point

| If you want to... | Start here | Notes |
|---|---|---|
| Validate or inspect an ADR corpus | [`@adrkit/cli`](packages/cli/README.md) | `npx @adrkit/cli ...` on Node 22+ |
| Build your own tooling | [`@adrkit/core`](packages/core/README.md) | Pure parser, validator, matcher, and queue APIs |
| Run the deterministic proposal checks | [`@adrkit/evaluator`](packages/evaluator/README.md) | Pass 0 is the shipped evaluator surface today |
| Feed prior decisions to coding agents | [`@adrkit/mcp`](packages/mcp/README.md) | Local, read-only stdio MCP server |
| Run adrkit from an OCI image | [Container usage](#container-usage) | Lockstep multi-architecture image, beginning with the first release containing ADR-0032 |
| Comment governing decisions on pull requests | [Use in CI](https://adrkit.dev/ci/) | GitHub Action from this repository |
| Evaluate decision governance with a generated wiki | [Generated knowledge guide](https://adrkit.dev/generated-knowledge/) | Provisional OpenWiki recipe; no runtime coupling |
| Add decision memory to Spec Kit | [`@adrkit/spec-kit`](packages/adapters/spec-kit/README.md) | Published separately for Spec Kit `>=0.13.0,<1.2.0` |
| Add decision memory to Copilot, Claude Code, or opencode | [`adrkit` agent plugin](packages/adapters/agent-plugin/README.md) | Install from this repository or marketplace |

## Container usage

Beginning with the first lockstep release containing
[ADR-0032](docs/adr/0032-publish-one-lockstep-oci-image-after-the-coordinated-release-succeeds.md),
releases are published as a multi-architecture OCI image at
`ghcr.io/mbeacom/adrkit`. Pin an immutable `vX.Y.Z` tag in automation; `vX`
and `latest` move only after that lockstep release has completed:

```sh
docker run --rm --read-only --network none \
  -v "$PWD:/workspace:ro" \
  ghcr.io/mbeacom/adrkit:vX.Y.Z lint

docker run --rm --read-only --network none -i \
  -v "$PWD:/workspace:ro" \
  ghcr.io/mbeacom/adrkit:vX.Y.Z mcp
```

The MCP command keeps stdin open because MCP uses stdio. Its repository mount is
read-only, matching the server contract; use an absolute host path in MCP client
configuration. For CLI commands that intentionally write (`new`, `accept`,
`approve`, `object`, `resolve`, or `migrate` without `--dry-run`), omit
`--read-only` and the mount's `:ro` suffix. The image runs as the non-root
`node` user; on a host with a different UID/GID, add
`--user "$(id -u):$(id -g)"`. On SELinux hosts, add the appropriate
bind-mount label (for example, `:Z`).

The default image treats an unrecognized selector as an `adr` subcommand.
Explicit selectors are `cli`/`adr`/`adrkit`, `mcp`/`adrkit-mcp`,
`ci`/`adrkit-ci`, and `queue-action`/`adrkit-queue-action`. The default
`--help` describes these selectors; `cli --help` opens the CLI command
reference. The container also reserves `-h`, `container-help`, and
`--container-help`; CLI help subcommands such as `help lint` otherwise pass
through unchanged.

Build the same source locally with Docker or Podman. Purpose-specific `cli`,
`mcp`, `ci`, and `queue-action` targets are isolated for local policy and SBOM
inspection; the registry publishes only the all-in-one `adrkit` target:

```sh
docker build -f Containerfile -t adrkit:local .
docker build -f Containerfile --target mcp -t adrkit-mcp:local .
docker run --rm --read-only --network none -i \
  -v "$PWD:/workspace:ro" \
  adrkit-mcp:local
```

The two CI entry points preserve the existing GitHub Actions runtime contract:
they expect `GITHUB_WORKSPACE`, the event payload and repository environment,
`INPUT_*` values, and a token. For hosted GitHub Actions, the repository-backed
Actions remain the simpler interface:
`mbeacom/adrkit/packages/ci@v0` and
`mbeacom/adrkit/packages/ci/queue@v0`. Container publication and recovery are
documented in [`docs/RELEASING.md`](docs/RELEASING.md#oci-container-image).

The governing-decisions Action also has a repository-root entry point for its
GitHub Marketplace listing. That root form is available beginning with
`v0.13.0`; the existing `packages/ci` form remains supported.
GitHub lists only root Action metadata, so the queue Action stays at its nested
path.

## What it looks like

`adr queue` emits the review backlog as a deterministic, read-only projection of
the corpus — byte-for-byte identical for identical inputs:

```text
# ARB Queue — 2026-07-25

Corpus fingerprint: `96e7f3185c5bb89bd1c87e10a28dcbef66703f381d3f14ea486ceaf29903cb00`
7 item(s) | 0 corpus finding(s) | 0 item(s) with findings

## Queue Items

| # | ID | Title | Tier | SLA State | Deadline | Approvals | Objections |
|---|----|-------|------|-----------|----------|-----------|------------|
| 1 | `0005` | Gate proposals with a deterministic-first evaluator … | arb | within-sla | 2027-01-18 | 0/- | 0 |
| 2 | `0015` | Validate descriptors against Backstage field formats … | arb | within-sla | 2027-01-25 | 0/- | 0 |
```

That is what a pipe, a CI job, or an agent receives. In a terminal the same
report prints as a list sized to the window, and each item ends with its next
step — the command to accept it, or the reason it cannot be accepted yet:

```text
1. 0044  within-sla · due 2027-03-31 (in 182 days)
   Ratify a proposed record with adr accept and present the queue for terminals
   async · asynchronous human review
   approvals 0 · objections 0 · route @mbeacom
   docs/adr/0044-ratify-a-proposed-record-with-adr-accept-and-present-the-queue-for-terminals.md
   next: adr accept 0044 --by <identity>
```

`adr accept 0044 --by @you` then sets `status`, `provenance.ratifiedBy`, and
`review.decidedAt`, and changes no other line, for review in a pull request.

In CI, the `@adrkit/ci` Action comments the governing decisions on the PRs that
touch them — read-only, comment-only, no database, no approval. See
[Use in CI](https://adrkit.dev/ci/).

## For agents: the MCP server

The most differentiated hook: `@adrkit/mcp` is a local, **read-only**
[Model Context Protocol](https://modelcontextprotocol.io) server that lets an
agent retrieve prior decisions — **including the rejected and superseded ones** —
before proposing something already tried. No writes, no HTTP/auth, no model,
embedding, or network access, and no persistent index. It exposes exactly four
tools:

| Tool | Purpose |
|------|---------|
| `search_decisions` | Filtered search across the corpus |
| `get_decision` | Fetch one record by id |
| `get_decision_context(files[])` | Decisions governing a set of files |
| `list_superseded` | The graveyard — what was already rejected |

Run it against a repository's corpus:

```sh
npx @adrkit/mcp             # or the adrkit-mcp bin
adrkit-mcp --cwd /path/to/repo --dir docs/adr
```

`--cwd` (env `ADRKIT_MCP_CWD`) must be a Git worktree root; `--dir` (env
`ADRKIT_MCP_DIR`, default `docs/adr`) is resolved within it. stdout carries only
JSON-RPC frames; diagnostics go to stderr; the graveyard is included by default.
See the [MCP setup guide](h