docs: sync to v0.4.0 and record what the release did and did not verify

.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

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 <path>`
+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

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 <id>` 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

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,28 @@ 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.
+Rerunning `docs/RELEASING.md` step 7's check with this release's version
+substituted — the response containing both `dev.adrkit/mcp` and `0.4.0` — exits 0.
+Step 7 itself stays written against `0.3.0`: it sits inside the completed v0.3.0
+cutover runbook, which is retained as a worked template whose versions the next
+cutover substitutes rather than a live command to run verbatim.
 
 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 +217,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 +229,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 +260,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 +542,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 +631,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.
 

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,37 @@ 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. They are most of what "Subsequent releases" step 1 means by "update any
+  inter-package expectations."
+- **`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

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) —

site/src/components/Hero.astro

@@ -14,7 +14,7 @@ const { title = data.title, tagline, actions = [] } = data.hero || {};
 				</svg>
 				CLI works today
 			</span>
-			<span>v0.3.0 on npm · decision memory in git</span>
+			<span>v0.4.0 on npm · decision memory in git</span>
 		</div>
 
 		<h1 id="_top" data-page-title set:html={title} />

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:
 <Aside type="note" title="Pinning the queue Action">
 	`queue@v0` resolves because the `v0` tag points at a commit containing
 	`packages/ci/queue/action.yml` — first true of the v0.2.1 release, and the tag
-	has moved forward with each release since (currently the v0.3.0 commit). `@v0`
+	has moved forward with each release since (currently the v0.4.0 commit, `c3dff3a`). `@v0`
 	is a moving tag; pin the full commit SHA instead if you need a byte-immutable
 	reference. Phase 6 is landed and maintainer reference-verified; external
 	validation ([ADR-0014](/adr/) rung 3) remains open.

site/src/content/docs/index.mdx

@@ -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.3.0</span>
+			<span class="adr-status adr-status--current">Published · v0.4.0</span>
 			<p>
 				<code>@adrkit/core</code>, <code>@adrkit/cli</code>,
 				<code>@adrkit/evaluator</code>, and <code>@adrkit/mcp</code> are on npm,

site/src/content/docs/quickstart.mdx

@@ -10,7 +10,7 @@ decisions govern a file, renders the decision graph, migrates an existing MADR
 corpus in place, emits the ARB operations queue, and runs the deterministic
 evaluator.
 
-<Aside type="tip" title="Published on npm (v0.3.0)">
+<Aside type="tip" title="Published on npm (v0.4.0)">
 	`@adrkit/cli` is live. Consumers install it with your Node package manager and
 	run the `adr` binary — no clone required. Published artifacts are Node-targeted
 	([ADR-0010](/adr/0010-bun-toolchain/)); Bun is used for developing adrkit