chore(release): v0.5.0 — ratify ADR-0022 and ADR-0023, retire ADR-0021

[mbeacom]

What and why

Cuts v0.5.0 and ratifies the three records behind it.

This is the release where inbound @adr markers stop being a single local
command and start appearing in pull-request comments. ADR-0023 rides along
deliberately: the window in which the loose marker grammar is visible in CI is
exactly the window between two releases, so shipping #106 and #109 together means
no adopter ever sees * @adr 0012 in a NOTES.md produce a governing decision
and then watch it disappear on upgrade.

Governance

Record	Before	After
ADR-0021	accepted	superseded, supersededBy: "0022"
ADR-0022	proposed	accepted, deciders: ["@mbeacom"], provenance.ratifiedBy, review.tier: arb
ADR-0023	proposed	accepted, deciders: ["@mbeacom"], provenance.ratifiedBy

ADR-0021's argument is untouched — only status and supersededBy moved, so the
record of the explain-only scope shipped in v0.4.0 still reads as written.

Nothing mechanical enforces the retirement: corpus-invariants.ts only checks
reference resolvability, and the schema only couples status: superseded with
supersededBy in both directions. Verified functionally rather than assumed —
adr check packages/core/src/markers/read.ts now reports:

Decisions governing this change:
  0022  [accepted] Scan inbound markers in check and CI without giving them exit-code authority
  0023  [accepted] Read a marker only where the format hides it: fences and markdown prose
Historical records that once covered this change (not binding):
  0021  [superseded] Resolve inbound source annotations without changing the schema (superseded by 0022)

Why ADR-0022 takes the arb tier

0022 shipped without a review block at all, which made it the only ratified
record in the corpus carrying no routing tier. Filling that in turned out to need
an actual judgment rather than a copied value, because the corpus's two signals
disagree here.

Surveying all 24 records: arb tracks scope: org (17 records), async tracks
the narrower ones (0016, 0017, 0018, 0021, 0023). 0022 is the only record in
the corpus with blastRadius: cross-team at scope: component — by scope it
looks like async, by blast radius it looks like arb.

Resolved toward arb, and the reason is now in the record: ADR-0021 reached
adr explain, a command run against a file the caller owns. 0022 points the same
reader at content a fork pull request authored, inside CI, and renders strings
derived from it into a comment signed by github-actions[bot]. That is a change
of kind — the first time @adrkit/core opens untrusted input in an automated
context — and it is precisely why 0022's blast radius is cross-team where its
predecessor's was component. Its failure modes are all quiet: an existence oracle
handed to a fork, a live link in a trusted comment, a 422 turning authored
content into a failed check. Two of those three were closed by review rather than
by design, which argues for the higher tier rather than against it.

Held to the corpus's actual convention on shape: tier + tierReason only,
matching 0016/0017/0018/0021/0023. queuedAt/slaDays appear only on the six
records from the original 2026-07-28 queueing batch, and approvals,
decidedAt, quorum, and objections are used nowhere in the corpus — so none
were invented here.

If you read the scope axis as decisive instead, this is a one-word change to
async; the tierReason explains the call either way.

Why minor, not patch

Two things exceed the patch rule in docs/RELEASING.md:

• Three additive runtime exports on @adrkit/core — readSourceMarkersBatch,
  MARKER_SCAN_FILE_CAP, MARKER_SCAN_CONCURRENCY — all pinned by
  packages/core/test/surface.test.ts. Nothing removed or renamed.
• scanSourceMarkers(source, path) now varies with path. Same signature,
  different semantics: the extension selects the introducer set, so two files with
  identical bytes scan differently. TypeScript will not catch this for an existing
  caller, which is why it is called out here and in the changelog. It is fail-safe
  — it only ever removes a declaration, plus the one addition of {/*.

Version surfaces touched

The four lockstep manifests, plus the three places a version is duplicated
outside them: CLI_VERSION, SERVER_INFO, and both fields in
packages/mcp/server.json. Also the four bun.lock workspace version lines —
edited by hand per docs/RELEASING.md, because neither bun install nor
bun install --force refreshes them, and regenerating the lockfile pulls
transitive @octokit/* drift into the release commit (confirmed: it did, and was
reverted).

Changelog

[Unreleased] promoted to [0.5.0], link refs added. Three corrections while
promoting:

• The entry claimed ADR-0021 "stands unedited" — true of its argument, false of
  its frontmatter once ratified here. Reworded rather than left to imply the
  record was untouched.
• The deleted-file marker-slot fix from feat(core,ci): wire inbound @adr markers into check #106's revisions was not recorded.
• The localeCompare → code-unit sort from feat(core,ci): wire inbound @adr markers into check #106's revisions was not recorded,
  including that it decides which paths survive the cap and which ten appear in
  the marker-scan-capped warning.

Verification

Run on this branch:

Gate	Result
bun test	1895 pass, 0 fail
bun run typecheck	clean
bun run lint	clean
bun run adr lint	23 records, 0 errors, 0 warnings
bun run build → git status packages/ci/dist	no drift
bun run schema:emit	no diff
bun run check:deps	ok
bun run check:freeze-hashes	ok (2 artifacts)
bun run audit:gate	PASSED — 0 high, 0 critical (3 moderate)
bun run release:pack -- --tag v0.5.0	5 packages prepared; git status clean afterwards
bun install --frozen-lockfile	clean after the hand-edited lock
adr queue	0022/0023 correctly absent — the queue projects proposed only

.release/npm/ contains adrkit-{core,evaluator,cli,mcp}-0.5.0.tgz plus
adrkit-spec-kit-0.1.2.tgz riding along unchanged.

Not done here — needs you

• Node 22 and Node 24 installed-tarball smoke. Requires switching Node
  versions in one shell; not something to fake.
• bun run release:publish -- --dry-run. Expected to fail on the adapter
  (The publish dry-run skips the idempotency check, so it tries to republish a released adapter #104) — the idempotency skip is gated behind !dryRun, so it tries to
  republish @adrkit/spec-kit at its current version. The four lockstep packages
  dry-run cleanly first.
• Tag v0.5.0 and move v0 (bun run release:action-tag) after npm succeeds.

Follow-ups, not blockers

Post-release docs sync (matching #105): README.md:228,234,
site/src/components/Hero.astro:17, ci.mdx:42,79, index.mdx:21,
quickstart.mdx:13, and docs/RELEASING.md:12,17. Plus the four open items from
the #106 review — marker-per-scan cap, scan health in the rendered comment,
toForwardSlash divergence, and the remaining uniqueSorted localeCompare.

One structural note worth its own issue: adr queue emits item.tier-absent
only when a review block exists but omits tier. A record with no review
block at all — which is what 0022 was — produces no finding, so it can be
ratified carrying no routing tier without anything noticing. That is the gap that
let this one through.

[Copilot]

Pull request overview

Prepares v0.5.0, ratifying inbound-marker governance decisions and retiring ADR-0021.

Changes:

• Bumps all lockstep package and runtime versions to 0.5.0.
• Accepts ADR-0022/0023 and supersedes ADR-0021.
• Promotes the unreleased changelog entries to v0.5.0.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
package.json	Bumps repository version.
bun.lock	Synchronizes workspace versions.
CHANGELOG.md	Publishes v0.5.0 release notes.
packages/core/package.json	Bumps core package version.
packages/evaluator/package.json	Bumps evaluator package version.
packages/cli/package.json	Bumps CLI package version.
packages/cli/src/index.ts	Updates the CLI runtime version.
packages/mcp/package.json	Bumps MCP package version.
packages/mcp/src/server.ts	Updates MCP server information.
packages/mcp/server.json	Updates MCP registry versions.
docs/adr/0021-resolve-inbound-source-annotations-without-changing-the-schema.md	Marks ADR-0021 superseded.
docs/adr/0022-scan-inbound-markers-in-check-and-ci-without-giving-them-exit-code-authority.md	Ratifies ADR-0022.
docs/adr/0023-read-a-marker-only-where-the-format-hides-it-fences-and-markdown-prose.md	Ratifies ADR-0023.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.