Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ body:
attributes:
label: adrkit version
description: Output of `adr --version` (or the package version you installed).
placeholder: '0.15.0'
placeholder: '0.16.0'
validations:
required: true
- type: dropdown
Expand Down
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

Decision memory for human- and agent-authored plans — machine-readable ADRs
that are enforceable in CI and legible to agents, without leaving git.
Status: early — phases 0–6 landed and v0.15.0 is public. `@adrkit/core`,
Status: early — phases 0–6 landed and v0.16.0 is public. `@adrkit/core`,
`@adrkit/evaluator`, `@adrkit/cli` (`lint`, `new`, `graph`, `explain`,
`check`, `queue`, `migrate --from madr`, `evaluate`) are published on npm, as is
`check`, `queue`, `accept`, `migrate --from madr`, `evaluate`) are published on npm, as is
the independently versioned `@adrkit/spec-kit` Spec Kit extension (0.1.4); the
repository-backed CI Action is available at `mbeacom/adrkit/packages/ci@v0`.
The governing-decisions Action also has a root `action.yml` alias for GitHub
Expand Down
33 changes: 32 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,19 @@ Until `1.0.0`, minor releases may include breaking changes

## [Unreleased]

## [0.16.0] - 2026-10-01

### Security

- **The Action bundles carry `undici` 6.29.0**, up from 6.27.0, closing
[GHSA-rfgv-xxqx-mfg5](https://github.com/advisories/GHSA-rfgv-xxqx-mfg5)
(high): a denial of service through an unrequested WebSocket subprotocol.
`undici` reaches both Actions through `@actions/github` and
`@actions/http-client`. Consumers of `packages/ci@v0` and
`packages/ci/queue@v0` pick it up when `v0` moves to this release; anyone
pinned to `v0.15.0` or earlier should move to `v0.16.0`
([#251](https://github.com/mbeacom/adrkit/pull/251)).

### Added

- **`adr accept <id> --by <identity>`** ratifies a `proposed` record. It sets
Expand All @@ -25,6 +38,23 @@ Until `1.0.0`, minor releases may include breaking changes
blocked. Piped, redirected, and captured output is still the Markdown report,
byte for byte. `--format terminal` and `--format markdown` choose
explicitly.
- **`acceptAdrSource` in `@adrkit/core`**, the pure transition behind
`adr accept`: given a record's source text, a ratifier, and a timestamp, it
returns the new text or a typed refusal. This adds a runtime export.

### Changed

- **`adr queue --format` defaults to `auto` instead of `markdown`.** Only stdout
attached to a terminal sees a difference. Pipes, redirects, CI, the
managed-issue Action, and agents still receive the Markdown report byte for
byte, and `--format markdown` restores it in a terminal.
- **The toolchain moved from Bun 1.3.14 to 1.4.2**
([#249](https://github.com/mbeacom/adrkit/pull/249)). The published packages
are still Node-targeted and are now built with 1.4.2. The Action bundles are
about 25% smaller because 1.4.2 drops the parts of `zod` nothing calls:
every error-message locale except English, and unused helpers. Apart from
that and the `undici` update under Security, the bundles contain the same
modules as in 0.15.0.

## [0.15.0] - 2026-09-28

Expand Down Expand Up @@ -1696,7 +1726,8 @@ against live Spec Kit, rather than reasoning about it:
- Node-targeted published distribution of all packages, smoke-tested under Node
22 and 24.

[Unreleased]: https://github.com/mbeacom/adrkit/compare/v0.15.0...HEAD
[Unreleased]: https://github.com/mbeacom/adrkit/compare/v0.16.0...HEAD
[0.16.0]: https://github.com/mbeacom/adrkit/compare/v0.15.0...v0.16.0
[0.15.0]: https://github.com/mbeacom/adrkit/compare/v0.14.0...v0.15.0
[0.14.0]: https://github.com/mbeacom/adrkit/compare/v0.13.0...v0.14.0
[0.13.0]: https://github.com/mbeacom/adrkit/compare/v0.12.0...v0.13.0
Expand Down
33 changes: 27 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,8 @@ docker run --rm --read-only --network none -i \

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`, or
`migrate` without `--dry-run`), omit `--read-only` and the mount's `:ro`
configuration. For CLI commands that intentionally write (`new`, `accept`,
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`).
Expand Down Expand Up @@ -152,6 +152,22 @@ Corpus fingerprint: `96e7f3185c5bb89bd1c87e10a28dcbef66703f381d3f14ea486ceaf2990
| 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/).
Expand Down Expand Up @@ -336,7 +352,12 @@ answer where the next decision is actually being made.
approves, persists, or writes**.
- **`adr queue`** — emit the ARB operations queue: a read-only, deterministic
projection of the corpus's `review` metadata (tiers, SLA state, approvals,
objections) as Markdown or `QueueReport` v1 JSON; also a managed-issue Action.
objections) as Markdown or `QueueReport` v1 JSON, or as a list sized to the
window in a terminal; also a managed-issue Action.
- **`adr accept <id> --by <identity>`** — ratify a `proposed` record from the
queue. It changes only `status`, `provenance.ratifiedBy`, and
`review.decidedAt`, refuses a record with an unresolved objection, an unmet
quorum, or a result that would not validate, and never infers who ratified.
- **CI comment** — the `@adrkit/ci` GitHub Action surfaces the governing decisions
on the PRs that touch or explicitly declare them; pattern matches render as `via`
and PR-authored marker claims as `declared by`. The comment also distinguishes
Expand All @@ -351,7 +372,7 @@ answer where the next decision is actually being made.
It never approves anything. It routes, and humans decide.

The root Marketplace entry point has shipped with every release since
`v0.13.0`. Pin its immutable root reference — currently `v0.15.0` — for the
`v0.13.0`. Pin its immutable root reference — currently `v0.16.0` — for the
complete governing-decisions workflow (see
[Use in CI](https://adrkit.dev/ci/)):

Expand All @@ -370,7 +391,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: mbeacom/adrkit@v0.15.0
- uses: mbeacom/adrkit@v0.16.0
```

Existing consumers of the nested form can stay on
Expand Down Expand Up @@ -406,7 +427,7 @@ table is the short version:
|---|---|---|
| Available now | `@adrkit/core`, `@adrkit/cli`, `@adrkit/evaluator`, `@adrkit/mcp` | Published on npm for Node 22+ |
| Available now | `@adrkit/spec-kit` | Published separately for current Spec Kit releases |
| Available now | `adr queue` and the governing-decisions GitHub Action | Queue reporting and PR comments are part of the shipped workflow |
| Available now | `adr queue`, `adr accept`, and the governing-decisions GitHub Action | Queue reporting, ratification from the queue, and PR comments are part of the shipped workflow |
| Available now | `adrkit` agent plugin | Install from this repository or marketplace; shells out to `adr` |
| In development | Later evaluator passes | Passes 1–3 and calibration remain design targets; Pass 0 is the implemented evaluator surface |
| In development | Catalog packages | `@adrkit/catalog-envelope` and `@adrkit/catalog-backstage` exist in the workspace at `0.0.0` and are not released |
Expand Down
8 changes: 4 additions & 4 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions docs/RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ Actions, one Marketplace entry point, and one lockstep OCI image:
| `@adrkit/cli` (`adr`, `adrkit`) | npm |
| `@adrkit/mcp` (`adrkit-mcp`) | npm |
| `action.yml` | GitHub Actions Marketplace and Git tag (governing-decisions alias; available beginning with `v0.13.0`) |
| `packages/ci/action.yml` | Git tag (existing governing-decisions subpath, latest immutable release `v0.15.0`, moving `v0`) |
| `packages/ci/queue/action.yml` | Git tag (nested queue Action, latest immutable release `v0.15.0`, moving `v0`) |
| `packages/ci/action.yml` | Git tag (existing governing-decisions subpath, latest immutable release `v0.16.0`, moving `v0`) |
| `packages/ci/queue/action.yml` | Git tag (nested queue Action, latest immutable release `v0.16.0`, moving `v0`) |
| `ghcr.io/mbeacom/adrkit` | GitHub Container Registry (`vX.Y.Z`, moving `vX`, `latest`; begins with the first release containing ADR-0032) |

`@adrkit/ci` stays private because GitHub executes the committed Action bundle
Expand All @@ -23,7 +23,7 @@ Action intentionally remains nested. `scripts/marketplace-action-contract.test.t
keeps the two governing-decisions metadata contracts identical except for their
different bundle paths.

The coordinated lockstep surface is published; the current release is `v0.15.0`. `@adrkit/core`,
The coordinated lockstep surface is published; the current release is `v0.16.0`. `@adrkit/core`,
`@adrkit/evaluator`, and `@adrkit/cli` use GitHub Actions Trusted Publishing.
`@adrkit/mcp` was created with the isolated one-time bootstrap path below; its
Trusted Publisher and token-restriction cleanup must be completed before the
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "adrkit",
"version": "0.15.0",
"version": "0.16.0",
"description": "Decision memory for human and agent-authored plans \u2014 machine-readable, CI-enforceable architecture decision records.",
"type": "module",
"private": true,
Expand Down
22 changes: 22 additions & 0 deletions packages/cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,35 @@ The binary includes:
- `explain`
- `check`
- `queue`
- `accept`
- `migrate --from madr`
- `completion`
- `evaluate`

Run `adr --help` for the command list, `adr help <command>` for one command's
flags, and `adr --version` to print the installed version.

## Review queue and acceptance

`adr queue` lists every `proposed` record with its SLA state, deadline,
approvals, and objections. In a terminal it prints a list sized to the window,
and each item ends with the next step: the command to accept it, or the reason
it cannot be accepted yet. Piped, redirected, or captured output is the
deterministic Markdown report, unchanged; `--format json` emits `QueueReport`
v1, and `--format terminal|markdown` choose explicitly.

```bash
adr queue
adr accept 0044 --by @octocat
```

`adr accept` sets `status: accepted`, `provenance.ratifiedBy`, and
`review.decidedAt` (now, UTC, with seconds), and changes no other line. It
commits nothing. It refuses, and leaves the file untouched, when the record is
not `proposed`, has an unresolved objection, has fewer approvals than its
`review.quorum`, or would not be a valid accepted record. `--by` is required and
is never inferred. Exit codes: `0` accepted, `1` refused, `2` usage error.

## Decision graph

`adr graph` chooses its default at the stdout boundary: an interactive terminal
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@adrkit/cli",
"version": "0.15.0",
"version": "0.16.0",
"description": "Git-native architecture decision record tooling from adrkit.",
"type": "module",
"license": "Apache-2.0",
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ import { getPresentation, setPresentation, styleUsageBlock, type ColorMode, type
* (mirroring `@adrkit/mcp`'s `SERVER_INFO`) so the bundled `dist/index.js` never has
* to locate `package.json` at runtime. `version.test.ts` asserts the two agree.
*/
export const CLI_VERSION = '0.15.0';
export const CLI_VERSION = '0.16.0';

function topLevelUsage(style?: StreamStyle): string {
return renderTopLevelUsage(CLI_VERSION, style);
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/test/color.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ describe('CLI color presentation', () => {
expect(result.exitCode).toBe(0);
expect(result.stderr).toBe('');
expect(result.stdout).toContain('\u001b[');
expect(result.stdout).toContain('adrkit 0.15.0');
expect(result.stdout).toContain('adrkit 0.16.0');
});

test('forced color keeps lint stdout and stderr separated', async () => {
Expand Down
2 changes: 1 addition & 1 deletion packages/core/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@adrkit/core",
"version": "0.15.0",
"version": "0.16.0",
"description": "Pure ADR parsing, validation, migration, and affects resolution for adrkit.",
"type": "module",
"license": "Apache-2.0",
Expand Down
2 changes: 1 addition & 1 deletion packages/evaluator/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@adrkit/evaluator",
"version": "0.15.0",
"version": "0.16.0",
"description": "Deterministic, model-free ADR proposal evaluation and routing for adrkit.",
"type": "module",
"license": "Apache-2.0",
Expand Down
2 changes: 1 addition & 1 deletion packages/mcp/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@adrkit/mcp",
"mcpName": "dev.adrkit/mcp",
"version": "0.15.0",
"version": "0.16.0",
"description": "Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.",
"type": "module",
"license": "Apache-2.0",
Expand Down
4 changes: 2 additions & 2 deletions packages/mcp/server.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"name": "dev.adrkit/mcp",
"title": "adrkit decision memory",
"description": "Deterministic, offline, read-only ADR decision memory for coding agents. No model or network calls.",
"version": "0.15.0",
"version": "0.16.0",
"websiteUrl": "https://adrkit.dev",
"repository": {
"url": "https://github.com/mbeacom/adrkit",
Expand All @@ -15,7 +15,7 @@
"registryType": "npm",
"registryBaseUrl": "https://registry.npmjs.org",
"identifier": "@adrkit/mcp",
"version": "0.15.0",
"version": "0.16.0",
"runtimeHint": "npx",
"transport": {
"type": "stdio"
Expand Down
2 changes: 1 addition & 1 deletion packages/mcp/src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import { registerGetDecisionContext } from './tools/get-decision-context.ts';
import { registerListSuperseded } from './tools/list-superseded.ts';
import type { ToolConfig } from './tools/shared.ts';

export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.15.0' } as const;
export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.16.0' } as const;

/**
* The MCP protocol revision this server serves through `serveStdio`'s modern era.
Expand Down
2 changes: 1 addition & 1 deletion site/src/components/Hero.astro
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ const { title = data.title, tagline, actions = [] } = data.hero || {};
</svg>
CLI works today
</span>
<span>v0.15.0 on npm · decision memory in git</span>
<span>v0.16.0 on npm · decision memory in git</span>
</div>

<h1 id="_top" data-page-title set:html={title} />
Expand Down
4 changes: 2 additions & 2 deletions site/src/content/docs/badges.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,8 @@ jobs:
# current release.
- run: |
mkdir -p .adrkit
npx @adrkit/cli@0.15.0 queue --format json > .adrkit/queue.json.tmp
npx @adrkit/cli@0.15.0 lint --json > .adrkit/lint.json.tmp
npx @adrkit/cli@0.16.0 queue --format json > .adrkit/queue.json.tmp
npx @adrkit/cli@0.16.0 lint --json > .adrkit/lint.json.tmp

# A truncated or malformed write renders as `no result` on the badge, which
# reads as a bug in your tooling. Fail here instead of committing it.
Expand Down
10 changes: 5 additions & 5 deletions site/src/content/docs/ci.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: mbeacom/adrkit@v0.15.0
- uses: mbeacom/adrkit@v0.16.0
# with:
# dir: docs/adr # ADR corpus directory (default: docs/adr)
# token: ${{ github.token }}
Expand All @@ -67,7 +67,7 @@ the comment reaches GitHub's size limit. Keep the default checkout rooted at
`GITHUB_WORKSPACE`; if a workflow checks out elsewhere, marker health will
identify files the Action could not inspect.

The Marketplace form is pinned to the immutable `v0.15.0` release. For
The Marketplace form is pinned to the immutable `v0.16.0` release. For
the nested compatibility form, `v0` is a moving major tag; pin an immutable
release tag or commit SHA when maximum reproducibility matters.

Expand All @@ -78,14 +78,14 @@ release tag or commit SHA when maximum reproducibility matters.
</Aside>

<Aside type="caution" title="Pinning a release tag by SHA">
The `v*` release tags are **annotated**, so `refs/tags/v0.15.0` resolves to a tag
The `v*` release tags are **annotated**, so `refs/tags/v0.16.0` resolves to a tag
object rather than a commit, and `uses:` rejects that SHA. Pin the commit the tag
points *at*:

```sh
git rev-parse v0.15.0^{commit}
git rev-parse v0.16.0^{commit}
# or, over the API — this endpoint peels the tag for you:
gh api repos/mbeacom/adrkit/commits/v0.15.0 --jq .sha
gh api repos/mbeacom/adrkit/commits/v0.16.0 --jq .sha
```

Note that `GET /git/ref/tags/{tag}` does **not** peel: its `object.sha` is the tag
Expand Down
2 changes: 1 addition & 1 deletion site/src/content/docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ hero:
<div class="adr-home">
<section class="adr-status-band" aria-label="Project status">
<div class="adr-status-band__item">
<span class="adr-status adr-status--current">Published · v0.15.0</span>
<span class="adr-status adr-status--current">Published · v0.16.0</span>
<p><code>@adrkit/core</code>, <code>@adrkit/cli</code>, <code>@adrkit/evaluator</code>, and <code>@adrkit/mcp</code> are on npm, plus the independently versioned <code>@adrkit/spec-kit</code> extension; the CI Action ships at <code>mbeacom/adrkit/packages/ci@v0</code>.</p>
</div>
<div class="adr-status-band__item">
Expand Down
Loading
Loading