From ae949937a85b7431d3979b6e294edf78b8ed7c8f Mon Sep 17 00:00:00 2001 From: Mark Beacom Date: Sat, 8 Aug 2026 19:31:14 -0400 Subject: [PATCH 1/2] docs: sync to v0.4.0 and record what the release did and did not verify MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The v0.3.0 pattern: the docs sync follows the release rather than riding the version bump, because a status block claiming "v0.4.0 on npm" before the tag is pushed is briefly false. v0.4.0 published 2026-08-08 at 22:25Z and the MCP registry entry re-published at 23:16Z, so both claims are now true. Version strings move in the README status block, CLAUDE.md, the site hero, homepage status band, quickstart, the CI guide's pin advice, and the bug-report template's placeholder. The CI guide's "currently the v0.3.0 commit" note names `c3dff3a`, where `v0` actually points now. The status blocks say the rung, not just the number. Markers landed at ADR-0014 rung 1 — unit, contract and purity coverage plus maintainer verification, and no reference-repository run. Every other surface the README and CLAUDE.md describe is at rungs 1-2. Bumping the version without that clause would silently promote the newest and least-verified feature to the evidence level of the oldest. CLAUDE.md gains a section for markers, covering the two properties that are load-bearing and easy to break: that they reach `adr explain` and nothing else, and that the scanner's dedicated-line rule and observed-byte truncation are what stop a marker from naming a record the file never declared. DISTRIBUTION.md records the 0.4.0 registry publication with the fields the response actually returned, and its A5 snippet is replaced with the live `packages/mcp/server.json` verbatim rather than hand-patched. Those two had already drifted: the doc still described `ADRKIT_MCP_CWD` as "Repository root to read (default: process.cwd())" while the shipped manifest says it must contain a readable `.git` entry. Bumping two version strings would have left that wrong for another release. RELEASING.md keeps the v0.3.0 carry-forwards and adds three from this cutover, each of which cost time: `bun.lock` records a `version` per workspace package that no install command refreshes, `CLI_VERSION` and `SERVER_INFO` are hardcoded and move with the manifests, and the publish dry-run now fails on the adapter (#104). The reference-verification index is annotated, not edited. Its rows record runs that happened against `@adrkit/cli@0.3.0`, and rewriting them to 0.4.0 would manufacture evidence for a run nobody performed. The reference workflow pins `ADRKIT_CLI_VERSION: "0.3.0"` deliberately, so the gate is green rather than stale-and-red, but green against a superseded CLI is not evidence about the current release. A dated note says so and scopes the verdict. Verified: 1840 tests pass, lint clean, `adr lint` reports 21 records with 0 errors and 0 warnings, and the documentation site builds (31 pages). Signed-off-by: Mark Beacom --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- CLAUDE.md | 32 +++++++++- README.md | 14 ++++- docs/DISTRIBUTION.md | 59 +++++++++++-------- docs/RELEASING.md | 29 ++++++++- ...ference-verification-spec-kit-extension.md | 10 ++++ site/src/components/Hero.astro | 2 +- site/src/content/docs/ci.mdx | 4 +- site/src/content/docs/index.mdx | 2 +- site/src/content/docs/quickstart.mdx | 2 +- 10 files changed, 122 insertions(+), 34 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 0afba7c3..b5c35ff9 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -31,7 +31,7 @@ body: attributes: label: adrkit version description: Output of `adr --version` (or the package version you installed). - placeholder: '0.3.0' + placeholder: '0.4.0' validations: required: true - type: dropdown diff --git a/CLAUDE.md b/CLAUDE.md index e892de0a..63f0256c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ 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.3.0 is public. `@adrkit/core`, +Status: early — phases 0–6 landed and v0.4.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 the independently versioned `@adrkit/spec-kit` Spec Kit extension (0.1.2); the @@ -17,6 +17,36 @@ driven through the official MCP Inspector. The Inspector defaults to the 2025 era; select the modern one with `"protocolEra": "modern"` (or `"auto"`) in the server's entry in the Inspector's `mcp.json` — there is no CLI flag for it. +## Inbound `@adr` markers (v0.4.0) + +A file can declare the decision it lives under by putting `@adr 0012` on a +dedicated comment line inside its first 8192 bytes, and `adr explain ` +resolves that inbound edge alongside the outbound `affects` patterns +([ADR-0021](./docs/adr/0021-resolve-inbound-source-annotations-without-changing-the-schema.md), +[#97](https://github.com/mbeacom/adrkit/pull/97)). No schema change: `AdrFrontmatter`, +`AffectsType`, and `schema/adr.schema.json` are untouched. + +Two properties are load-bearing and easy to break: + +- **Markers reach `adr explain` and nothing else.** `adr check`, `checkChanges`, + the CI Action, and `packages/adapters/spec-kit/scripts/context.sh` do not scan + them. `declaredBy` lives on an explain-only `ExplainedDecision`, *not* on the + shared `GoverningDecision` that `checkChanges` returns, so `check --json` is + marker-free and `packages/ci/dist` gains nothing. Wiring markers into `check` + or the Action changes CI semantics and moves the filesystem boundary, so it is + a separate decision. +- **A marker must not be able to lie.** The scanner requires the comment + introducer to begin the physical line with `@adr` as the comment's first + content, so prose discussing a decision, a string literal containing one, and + a trailing `} // @adr 0012` are all rejected. Truncation uses the byte count + `read.ts` observed rather than re-deriving it from decoded text, because + `TextDecoder` drops a BOM and expands invalid bytes, and a re-derived window + can sever a reference mid-token and report a record the file never named. + +Unlike the surfaces below, this is at **rung 1** of ADR-0014 only — unit, +contract, and purity coverage plus maintainer verification. No reference-repository +run. + Phase 6 ARB queue is implemented under `specs/007-arb-queue/` (see [`plan.md`](./plan.md)): the pure `buildQueueReport` kernel and canonical JSON/Markdown formatters live in diff --git a/README.md b/README.md index a4b5a81f..b5066d41 100644 --- a/README.md +++ b/README.md @@ -222,12 +222,24 @@ different artifact from a heading convention. That is the whole thesis. Early, under active development, and deliberately honest about what is proven. -- **Published — v0.3.0 on npm.** The schema, `@adrkit/core`, `@adrkit/cli`, +- **Published — v0.4.0 on npm.** The schema, `@adrkit/core`, `@adrkit/cli`, the deterministic Pass 0 `@adrkit/evaluator`, and the read-only `@adrkit/mcp` server are all implemented and released. The MCP server speaks both protocol eras and passed real-session dogfood against the published artifact on each, driven through the official MCP Inspector ([ADR-0018](docs/adr/0018-adopt-mcp-sdk-v2-and-serve-protocol-revision-2026-07-28-dual-era.md)). +- **New in v0.4.0, and at rung 1 only.** A file can declare the decision it + lives under with an `@adr ` marker on a dedicated comment line, and + `adr explain` resolves that inbound edge alongside the `affects` patterns that + already matched the path + ([ADR-0021](docs/adr/0021-resolve-inbound-source-annotations-without-changing-the-schema.md)). + The feature reaches `adr explain` and nothing else: `adr check`, the Action, + and the Spec Kit context script do not scan markers, so no CI semantics move. + Evidence is unit, contract, and purity coverage plus maintainer verification — + **rung 1** of the ADR-0014 ladder, not the rungs 1–2 the surfaces below carry. + Contributed by [@aballiet](https://github.com/aballiet) in + [#97](https://github.com/mbeacom/adrkit/pull/97), the first community feature + this project has shipped. - **Landed, maintainer reference-verified — not yet externally validated.** The Phase 6 ARB queue (`adr queue` plus the managed-issue Action) is verified on rungs 1–2 of the diff --git a/docs/DISTRIBUTION.md b/docs/DISTRIBUTION.md index 63523a1b..b12097bf 100644 --- a/docs/DISTRIBUTION.md +++ b/docs/DISTRIBUTION.md @@ -5,8 +5,8 @@ the `@adrkit/*` CLI presence in the MCP and ADR-tooling ecosystems. It contains ready-to-paste content and exact procedures. > **Submission status.** The official MCP registry entry (§A) **has been published** -> — `dev.adrkit/mcp` at `0.3.0`, status `active` (first published 2026-07-28 at -> `0.2.1`; re-published 2026-07-31 for the v0.3.0 release). Every other +> — `dev.adrkit/mcp` at `0.4.0`, status `active` (first published 2026-07-28 at +> `0.2.1`; re-published 2026-07-31 for v0.3.0 and 2026-08-08 for v0.4.0). Every other > venue below remains prepared but **not submitted**. Every outbound action — > publishing to a registry, opening a PR, filling a form, creating a git tag, or > posting anywhere — is performed by a human, never by tooling or an agent. @@ -32,13 +32,13 @@ GitHub repo, so a small number of prerequisites unblock several venues at once. ### P1 — npm packages are published ✅ **Satisfied.** `@adrkit/mcp`, `@adrkit/cli`, `@adrkit/core`, and `@adrkit/evaluator` -are published at `0.3.0` — the exact version `server.json` names. The MCP registry +are published at `0.4.0` — the exact version `server.json` names. The MCP registry hosts *metadata only*; the npm package must already exist at the version named in -`server.json`. Verified with `npm view @adrkit/mcp@0.3.0 version` → `0.3.0`. +`server.json`. Verified with `npm view @adrkit/mcp@0.4.0 version` → `0.4.0`. ### P2 — `mcpName` in the **published** `@adrkit/mcp` ✅ -**Satisfied.** `npm view @adrkit/mcp@0.3.0 mcpName` returns `dev.adrkit/mcp`, +**Satisfied.** `npm view @adrkit/mcp@0.4.0 mcpName` returns `dev.adrkit/mcp`, matching `server.json` `name` exactly. The requirement, and why the ordering mattered: the official registry verifies npm @@ -104,7 +104,7 @@ confusion in every listing: ## A. Official MCP registry (`registry.modelcontextprotocol.io`) — **PUBLISHED** **Status: published.** First published 2026-07-28 via the DNS namespace path; -re-published 2026-07-31 for v0.3.0. `dev.adrkit/mcp` is listed at `0.3.0` with +re-published 2026-07-31 for v0.3.0 and 2026-08-08 for v0.4.0. `dev.adrkit/mcp` is listed at `0.4.0` with status `active` and `isLatest: true`; see §A4 for the verified response. The subsections below are retained as the procedure to repeat on each release. @@ -182,24 +182,25 @@ mcp-publisher publish curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=dev.adrkit/mcp" ``` -**Verified 2026-07-31** (the v0.3.0 re-publication; the entry first went live -2026-07-28 at `0.2.1`). The registry returns the `0.3.0` record as latest: +**Verified 2026-08-08** (the v0.4.0 re-publication; the entry first went live +2026-07-28 at `0.2.1`, and was re-published 2026-07-31 for v0.3.0). The registry +returns the `0.4.0` record as latest: | Field | Value | |---|---| | `name` | `dev.adrkit/mcp` | -| `version` | `0.3.0` | -| `packages[0].identifier` / `version` | `@adrkit/mcp` / `0.3.0` | +| `version` | `0.4.0` | +| `packages[0].identifier` / `version` | `@adrkit/mcp` / `0.4.0` | | `transport.type` | `stdio` | | `_meta…/official.status` | `active` | | `_meta…/official.isLatest` | `true` | -| `_meta…/official.publishedAt` | `2026-07-31T10:54:25.076965Z` | +| `_meta…/official.publishedAt` | `2026-08-08T23:16:38.484551Z` | -The registry retains the superseded `0.2.1` record alongside it; `isLatest` is the -field that distinguishes them. +The registry retains the superseded `0.2.1` and `0.3.0` records alongside it; +`isLatest` is the field that distinguishes them. `docs/RELEASING.md` step 7's exact assertion — the response containing both -`dev.adrkit/mcp` and `0.3.0` — exits 0. +`dev.adrkit/mcp` and `0.4.0` — exits 0. A subsequent release must re-run `mcp-publisher publish` with `server.json`'s two version fields bumped; the registry pins a specific npm version and does not track @@ -213,7 +214,7 @@ version fields bumped; the registry pins a specific npm version and does not tra "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.3.0", + "version": "0.4.0", "websiteUrl": "https://adrkit.dev", "repository": { "url": "https://github.com/mbeacom/adrkit", @@ -225,12 +226,24 @@ version fields bumped; the registry pins a specific npm version and does not tra "registryType": "npm", "registryBaseUrl": "https://registry.npmjs.org", "identifier": "@adrkit/mcp", - "version": "0.3.0", + "version": "0.4.0", "runtimeHint": "npx", - "transport": { "type": "stdio" }, + "transport": { + "type": "stdio" + }, "environmentVariables": [ - { "name": "ADRKIT_MCP_CWD", "description": "Repository root to read (default: process.cwd()).", "isRequired": false, "isSecret": false }, - { "name": "ADRKIT_MCP_DIR", "description": "ADR directory under the repo root (default: docs/adr).", "isRequired": false, "isSecret": false } + { + "name": "ADRKIT_MCP_CWD", + "description": "Repository root; must contain a readable .git entry. Defaults to the process working directory.", + "isRequired": false, + "isSecret": false + }, + { + "name": "ADRKIT_MCP_DIR", + "description": "ADR directory, resolved against the root and required to stay contained within it. Defaults to docs/adr.", + "isRequired": false, + "isSecret": false + } ] } ] @@ -244,7 +257,7 @@ version fields bumped; the registry pins a specific npm version and does not tra **Listing criteria met?** Yes — schema-valid, npm package exists at the manifest version, stdio transport, public repo. Both original blockers (the human namespace proof and an npm publication carrying `mcpName`) were cleared for v0.2.1 and remain -satisfied at v0.3.0. +satisfied at v0.4.0. --- @@ -526,8 +539,8 @@ ARB-queue Action from its moving major tag like any other: uses: mbeacom/adrkit/packages/ci/queue@v0 ``` -`v0` moves with every release, so it now peels to the v0.3.0 release commit -(`3adefc7`) rather than to `31bed03`. That is the point of a moving major tag; the +`v0` moves with every release, so it now peels to the v0.4.0 release commit +(`c3dff3a`) rather than to `31bed03`. That is the point of a moving major tag; the commit named below is the historical one that first made `@v0` resolve. The rest of this section is the historical record of why a full-commit pin was @@ -615,7 +628,7 @@ itself, not a pin. No distribution-blocking source edits are currently delegated to another workstream. `packages/mcp/package.json` declares `"mcpName": "dev.adrkit/mcp"` -(matching `server.json` `name`), v0.3.0 has been cut, and the registry entry is +(matching `server.json` `name`), v0.4.0 has been cut, and the registry entry is **published** at that version (§A4). Nothing in this repository blocks any remaining venue; what is left is per-venue human submission, tracked in the readiness table above. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 556386eb..fa69a6fe 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -9,12 +9,12 @@ Action: | `@adrkit/evaluator` | npm | | `@adrkit/cli` (`adr`) | npm | | `@adrkit/mcp` (`adrkit-mcp`) | npm | -| `packages/ci/action.yml` | Git tag (latest immutable release `v0.3.0`, moving `v0`) | +| `packages/ci/action.yml` | Git tag (latest immutable release `v0.4.0`, moving `v0`) | `@adrkit/ci` stays private because GitHub executes the committed Action bundle directly from the referenced repository ref. -The coordinated `v0.2.0` release is complete. `@adrkit/core`, +The coordinated lockstep surface is published; the current release is `v0.4.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 @@ -258,13 +258,36 @@ Two notes worth carrying forward from the v0.3.0 cutover: - `bun run release:pack` triggers a **non-frozen** `bun install`, which can pull transitive drift into the committed `packages/ci/dist` bundles. Check - `git status` after step 2; it was clean for v0.3.0. + `git status` after step 2; it was clean for v0.3.0 and for v0.4.0. - The published-consumer advisory audit reported **0 vulnerabilities** at v0.3.0, and `KNOWN_CONSUMER_ADVISORY_ACCEPTANCES` is now empty ([ADR-0018](adr/0018-adopt-mcp-sdk-v2-and-serve-protocol-revision-2026-07-28-dual-era.md) removed the last entry). Any advisory appearing in a future run is therefore an unrecorded exposure and a release blocker until reconciled. +Three more from the v0.4.0 cutover, all of which cost time: + +- **`bun.lock` records a `version` for each workspace package, and nothing + refreshes it.** Neither `bun install` nor `bun install --force` updates those + fields after a manifest bump. `release-pack` catches it — `@adrkit/evaluator + must resolve @adrkit/core to 0.4.0, got 0.3.0` — because it validates a packed + dependency against the dependency's own version. Deleting and regenerating the + lockfile fixes it *and* pulls unrelated transitive drift into the release + commit (at v0.4.0: `jose`, `undici`, `@octokit/*`, `@types/node`). Edit the + workspace `version` lines directly, then confirm with + `bun install --frozen-lockfile`. +- **Two hardcoded version constants move with the manifests**: `CLI_VERSION` in + `packages/cli/src/index.ts` and `SERVER_INFO` in `packages/mcp/src/server.ts`. + Each has a test asserting it matches its `package.json`, so `bun test` finds + them; step 1's "update any inter-package expectations" is mostly these. +- **`bun run release:publish -- --dry-run` fails on the adapter** now that an + independently versioned package rides along in a lockstep pack. The registry + idempotency check that skips an already-published artifact is gated behind + `!dryRun`, so the dry run tries to republish `@adrkit/spec-kit` at its current + version. The four lockstep packages dry-run cleanly first, and the real run + skips the adapter because the packed tarball's integrity matches the registry. + Tracked in [#104](https://github.com/mbeacom/adrkit/issues/104). + 1. Start from the final release commit on `main`. ```sh diff --git a/docs/reference-verification-spec-kit-extension.md b/docs/reference-verification-spec-kit-extension.md index 43dc330e..a482f7b8 100644 --- a/docs/reference-verification-spec-kit-extension.md +++ b/docs/reference-verification-spec-kit-extension.md @@ -20,6 +20,16 @@ vocabulary: **implemented → reference-verified → landed**. It is **not** **Reviewer verdict**: PASS. All four rung-2 criteria — reproducible, self-verifying, fail-closed, reviewed — are met by the artifacts below. +> **Currency, as of 2026-08-08.** Everything recorded below describes runs that +> actually happened, and none of it is edited when a new adrkit version ships. +> The reference workflow pins `ADRKIT_CLI_VERSION: "0.3.0"`, so as of the v0.4.0 +> release this gate exercises the extension against a **superseded** CLI. It is +> green rather than stale-and-red — the pin is deliberate and `PIN-3` still +> matches — but the rung-2 evidence for `@adrkit/spec-kit` is not evidence about +> the current release. Bumping the pin and recording a fresh run is tracked +> separately; until that lands, read the verdict below as scoped to +> `@adrkit/cli@0.3.0`. + ## Reference repository (maintainer-owned, isolated) [`mbeacom/adrkit-t018-dogfood`](https://github.com/mbeacom/adrkit-t018-dogfood) — diff --git a/site/src/components/Hero.astro b/site/src/components/Hero.astro index 906dee44..04ac2dc9 100644 --- a/site/src/components/Hero.astro +++ b/site/src/components/Hero.astro @@ -14,7 +14,7 @@ const { title = data.title, tagline, actions = [] } = data.hero || {}; CLI works today - v0.3.0 on npm · decision memory in git + v0.4.0 on npm · decision memory in git

diff --git a/site/src/content/docs/ci.mdx b/site/src/content/docs/ci.mdx index 32d46187..86e7f090 100644 --- a/site/src/content/docs/ci.mdx +++ b/site/src/content/docs/ci.mdx @@ -39,7 +39,7 @@ jobs: # token: ${{ github.token }} ``` -`v0` is a moving major tag. Pin the immutable `v0.3.0` tag or a commit SHA for +`v0` is a moving major tag. Pin the immutable `v0.4.0` tag or a commit SHA for maximum reproducibility. ## Publish the ARB operations queue @@ -76,7 +76,7 @@ jobs: