chore(release): prepare v0.19.0

.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.18.0'
+      placeholder: '0.19.0'
     validations:
       required: true
   - type: dropdown

AGENTS.md

@@ -2,12 +2,14 @@
 
 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.18.0 is public. `@adrkit/core`,
+Status: early — phases 0–6 landed and v0.19.0 is public. `@adrkit/core`,
 `@adrkit/evaluator`, `@adrkit/cli` (`lint`, `new`, `graph`, `explain`,
 `check`, `queue`, `accept`, `approve`, `object`, `resolve`, `migrate --from madr`,
 `evaluate`) are published on npm, as is
 the independently versioned `@adrkit/spec-kit` Spec Kit extension (0.1.5); the
-repository-backed CI Action is available at `mbeacom/adrkit/packages/ci@v0`.
+repository-backed CI Action is available at `mbeacom/adrkit/packages/ci@v0`,
+and the build-only decision-portal Action at
+`mbeacom/adrkit/packages/ci/portal@v0.19.0` (pin an immutable tag, never `@v0`).
 The governing-decisions Action also has a root `action.yml` alias for GitHub
 Marketplace beginning with v0.13.0. Root
 Marketplace guidance uses immutable release tags; never advertise

CHANGELOG.md

@@ -9,8 +9,86 @@ Until `1.0.0`, minor releases may include breaking changes
 
 ## [Unreleased]
 
+## [0.19.0] - 2026-10-10
+
+This release ships the decision portal: a third, build-only nested Action,
+`mbeacom/adrkit/packages/ci/portal@v0.19.0`, that builds a static, read-only
+view of your decisions for GitHub Pages
+([ADR-0054](docs/adr/0054-publish-a-static-decision-portal-for-github-pages-built-outside-the-cli-from-the.md)).
+Pin it by immutable tag; it has no root alias and is never advertised at `@v0`.
+On npm, `@adrkit/core`, `@adrkit/evaluator`, and `@adrkit/cli` move to 0.19.0
+for lockstep with no source change, and `@adrkit/mcp` picks up
+`@modelcontextprotocol/server` 2.3.1. No existing CLI, MCP, or Action behavior
+changes. It also carries the agent plugin's work since 0.18.0 (`adrkit` 0.9.0
+through 0.11.0), which already shipped on merge to `main` and is listed here for
+the record; the plugin and `@adrkit/spec-kit` are versioned independently and do
+not move with this release (`spec-kit-v0.1.5` has its own section below).
+Dependency bumps that touch only this repository's workflows (#288, #278) or the
+documentation site (#286) are not listed.
+
 ### Added
 
+- **A nested, build-only decision-portal Action, `packages/ci/portal`.** It
+  runs the portal generator over the corpus and writes the bundle into `out`
+  (default `_site`), and nothing else: it holds no token, makes no GitHub API
+  call, and needs only `contents: read`. Your workflow uploads the directory
+  with `actions/upload-pages-artifact` and deploys it with
+  `actions/deploy-pages` in a separate job; the full SHA-pinned workflow is in
+  [Use in CI](https://adrkit.dev/ci/#publish-a-decision-portal-to-github-pages).
+  - **A private repository fails closed.** The bundle carries every record body
+    and the governed file paths, so the Action builds only when the event
+    payload says the repository is public, or when `publish-private` is exactly
+    `'true'`. Private, internal, and a payload that does not say are each
+    refused with a fixed message before the generator runs, so nothing is
+    written. `publish-private` is read untrimmed: the default trimming turned
+    `' true '` into the exact opt-in (found in security review).
+  - **Exit codes follow the generator.** `0` succeeds; `1` succeeds with a
+    warning and the complete bundle, with the corpus errors shown on every
+    page; `2` fails with the generator's own fixed message and writes nothing.
+    A thrown error fails with a fixed message, never its text. The
+    `exit-code` output is set whenever the generator ran.
+  - **The image still builds.** The Containerfile's build stage now copies
+    `packages/portal/package.json`, which Bun's frozen install needs once
+    `@adrkit/ci` depends on `@adrkit/portal`, and a contract test checks that
+    every copied manifest's workspace dependencies are copied too.
+  - **Recovery keeps older releases recoverable.** `action-tag-recovery.yml`
+    and `docs/RELEASING.md` require `dist/portal-action.js` only when
+    `packages/ci/portal/action.yml` exists at the target, so `v0` can still be
+    moved back to a pre-portal release such as v0.18.0.
+
+  Rung 1 of ADR-0014: unit, contract, and mutation tests, and a Node 22 run of
+  the committed bundle against a git fixture. The `dist/index.js` and
+  `dist/queue-action.js` bundles are unchanged.
+- **The portal generator and page, `@adrkit/portal` (private).** It ships to
+  users only inside the Action above and is not published to npm. It is built
+  on `@adrkit/sdk` alone.
+  - `portal-data.json` v1 comes from a pure builder (no clock, file, or
+    environment; identical inputs give identical bytes).
+  - The page has five read-only views on hash routes: the records, one record,
+    the graph, the review queue, and governance by path. Governance by path is
+    shown as available (possibly capped), unavailable when the corpus has
+    errors, or absent without a git work tree; the page never says
+    "ungoverned".
+  - The page carries a `default-src 'none'` CSP and builds its DOM with
+    `textContent` only. Record bodies go through an in-house Markdown renderer
+    that renders raw HTML, and any link that is not http(s), a fragment, or
+    another record, as text, with table and link-bracket work bounded.
+  - The queue shows raw review facts and no readiness verdict, and the
+    portal's strings name no review or ratifying command.
+  - The graph layout, pan and zoom, and theme are byte-identical copies of the
+    agent plugin's modules, kept in step by `bun run emit:portal-vendor` and a
+    no-diff step in `clean-clone-builds`.
+  - The corpus directory is confined with `realpath`, and the bundle is staged
+    and swapped into place, so a failed write leaves nothing half-written.
+- **`@adrkit/sdk` is implemented, and still unpublished.** `openDecisions` and
+  `DecisionSet` now work, as a read-only mapping layer over `@adrkit/core`'s
+  kernels with the SDK's own frozen types: `records` and `issues`, `queue`
+  (with the queue's review counts and no readiness field), `graph` (supersession
+  by default; `relatesTo` and `conflictsWith` on request), `governing` (the
+  chain `adr explain` runs), and each record's raw Markdown `body`. There is no
+  npm package: it stays at `0.0.0` with no exports map and no release wiring,
+  and the portal is its only consumer. Publication waits on the gates in
+  [ADR-0053](docs/adr/0053-implement-adrkit-sdk-over-core-s-kernels-and-accept-an-in-repo-consumer-as-its-r.md).
 - **The agent plugin adds a read-only `decision-board` canvas for the GitHub
   Copilot app (`adrkit` 0.9.0).** Where `decision-review` is scoped to one
   change, the board maps the whole corpus: how the records relate, from
@@ -81,6 +159,15 @@ Until `1.0.0`, minor releases may include breaking changes
 
 ### Changed
 
+- **`@adrkit/mcp` now runs on `@modelcontextprotocol/server` 2.3.1**, from
+  2.2.0, with the dev-only `@modelcontextprotocol/client` moved with it so that
+  one `@modelcontextprotocol/core@2.3.1` resolves in the tree. Both stay
+  exact-pinned. 2.3.0's breaking change, that a server object serves one
+  connection at a time, does not reach `adrkit-mcp`: it already builds a fresh
+  server per connection through `serveStdio(() => …)`, the form upstream lists
+  as unaffected. 2.3.0's other additions are opt-in and unused here. The
+  server's source is unchanged, and its tests, which drive both protocol eras
+  over real stdio, pass on the new version.
 - **The agent plugin's two Copilot app canvases get a visual pass (`adrkit`
   0.11.0).** Function, routes, actions, the payload, and the
   Content-Security-Policy are unchanged.
@@ -105,6 +192,13 @@ Until `1.0.0`, minor releases may include breaking changes
 
 ### Fixed
 
+- **Release notes start at the previous tag of the same kind.** The Release
+  workflow's generated GitHub release notes diffed against the latest release
+  of any kind, so `spec-kit-v0.1.5`'s notes listed every pull request since
+  v0.18.0, and this release's would have started at `spec-kit-v0.1.5`.
+  `scripts/release-notes-start-tag.ts` now passes `--notes-start-tag` with the
+  previous `v*` tag for a lockstep release and the previous `<adapter>-v*` tag
+  for an adapter (#303).
 - **Docs: the Spec Kit install command, the command names, and the checkout pin
   in workflow snippets.** Found while building a demo repository on Spec Kit
   1.0.5.
@@ -143,6 +237,29 @@ Until `1.0.0`, minor releases may include breaking changes
   `adr queue` exits 2 because the corpus directory is not there, the panel says
   that instead of "exited 2". This follows a Windows report (git
   2.55.0.vfs.0.10) whose cause is not reproduced here.
+- **The decision board's end-to-end test no longer races the queue (agent
+  plugin test only).** It read the first queue row while the queue, which
+  arrives in a second update, could still be `null`, and failed
+  `clean-clone-builds` intermittently. It now keeps polling.
+
+### Documentation
+
+- **Decisions for the SDK, the portal, and the hosted surfaces.**
+  [ADR-0053](docs/adr/0053-implement-adrkit-sdk-over-core-s-kernels-and-accept-an-in-repo-consumer-as-its-r.md)
+  (implement the SDK over core),
+  [ADR-0054](docs/adr/0054-publish-a-static-decision-portal-for-github-pages-built-outside-the-cli-from-the.md)
+  (the Pages portal), and
+  [ADR-0055](docs/adr/0055-serve-a-read-only-rest-api-over-the-sdk-in-the-oci-image-and-reach-mcp-clients-t.md)
+  (a read-only REST API in the image) are accepted, as are
+  [ADR-0057](docs/adr/0057-preview-the-decision-portal-locally-through-a-preview-selector-in-the-published.md)
+  (a local portal preview),
+  [ADR-0058](docs/adr/0058-project-the-decision-corpus-into-a-github-project-as-a-one-way-derived-view.md)
+  (a one-way GitHub Project view), and
+  [ADR-0059](docs/adr/0059-aggregate-decision-corpora-across-an-organization-s-repositories-as-a-pinned-rea.md)
+  (organization-level federation).
+  [ADR-0056](docs/adr/0056-ship-the-azure-deployment-surface-as-terraform-in-a-separate-repository-behind-a.md)
+  (Terraform for Azure in `mbeacom/adrkit-azure`) is proposed. Only ADR-0053
+  and ADR-0054 are implemented in this release; the others are rung 0.
 
 ## [spec-kit-0.1.5] - 2026-10-09
 
@@ -2169,7 +2286,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.18.0...HEAD
+[Unreleased]: https://github.com/mbeacom/adrkit/compare/v0.19.0...HEAD
+[0.19.0]: https://github.com/mbeacom/adrkit/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/mbeacom/adrkit/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/mbeacom/adrkit/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/mbeacom/adrkit/compare/v0.15.0...v0.16.0

README.md

@@ -91,7 +91,7 @@ See the [Quickstart guide](https://adrkit.dev/quickstart/) and the full
 | 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 |
-| Browse decisions on GitHub Pages | [Decision portal](https://adrkit.dev/ci/#publish-a-decision-portal-to-github-pages) | Nested build-only Action, beginning with the first lockstep release containing ADR-0054 |
+| Browse decisions on GitHub Pages | [Decision portal](https://adrkit.dev/ci/#publish-a-decision-portal-to-github-pages) | Nested build-only Action, beginning with `v0.19.0` |
 | 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 |
@@ -414,7 +414,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.18.0` — for the
+`v0.13.0`. Pin its immutable root reference — currently `v0.19.0` — for the
 complete governing-decisions workflow (see
 [Use in CI](https://adrkit.dev/ci/)):
 
@@ -433,15 +433,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: mbeacom/adrkit@v0.18.0
+      - uses: mbeacom/adrkit@v0.19.0
 ```
 
 Existing consumers of the nested form can stay on
 `mbeacom/adrkit/packages/ci@v0`. The queue Action remains available at
 `mbeacom/adrkit/packages/ci/queue@v0`.
 
 A third, build-only Action, `mbeacom/adrkit/packages/ci/portal@vX.Y.Z` (pin an
-immutable release tag; beginning with the first lockstep release containing ADR-0054), builds a
+immutable release tag; beginning with `v0.19.0`), builds a
 static, read-only decision portal for GitHub Pages
 ([ADR-0054](docs/adr/0054-publish-a-static-decision-portal-for-github-pages-built-outside-the-cli-from-the.md)).
 It holds no token and needs only `contents: read`; your workflow deploys the
@@ -480,8 +480,10 @@ 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`, `adr approve`, `adr object`, `adr resolve`, `adr accept`, and the governing-decisions GitHub Action | Queue reporting, recorded review state, ratification from the queue, and PR comments are part of the shipped workflow |
+| Available now | Decision portal Action (`packages/ci/portal`) | Builds a static, read-only portal for GitHub Pages, beginning with `v0.19.0`; the private `@adrkit/portal` generator ships only inside it |
 | 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 | `@adrkit/sdk` | Implemented over `@adrkit/core` and used by the portal, but unpublished at `0.0.0`; there is no npm package |
 | In development | Catalog packages | `@adrkit/catalog-envelope` and `@adrkit/catalog-backstage` exist in the workspace at `0.0.0` and are not released |
 | Planned | Additional downstream integrations | Future integrations will build on the current typed corpus and read-only retrieval model |
 

docs/RELEASING.md

@@ -10,9 +10,9 @@ 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.18.0`, moving `v0`) |
-| `packages/ci/queue/action.yml` | Git tag (nested queue Action, latest immutable release `v0.18.0`, moving `v0`) |
-| `packages/ci/portal/action.yml` | Git tag (nested, build-only decision-portal Action, ADR-0054; beginning with the first lockstep release containing ADR-0054, moving `v0`; document only immutable `vX.Y.Z` pins) |
+| `packages/ci/action.yml` | Git tag (existing governing-decisions subpath, latest immutable release `v0.19.0`, moving `v0`) |
+| `packages/ci/queue/action.yml` | Git tag (nested queue Action, latest immutable release `v0.19.0`, moving `v0`) |
+| `packages/ci/portal/action.yml` | Git tag (nested, build-only decision-portal Action, ADR-0054; beginning with `v0.19.0`, moving `v0`; document only immutable `vX.Y.Z` pins) |
 | `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
@@ -25,7 +25,7 @@ and portal Actions intentionally remain nested. Never advertise a root alias or
 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.18.0`. `@adrkit/core`,
+The coordinated lockstep surface is published; the current release is `v0.19.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

package.json

@@ -1,6 +1,6 @@
 {
   "name": "adrkit",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Decision memory for human and agent-authored plans \u2014 machine-readable, CI-enforceable architecture decision records.",
   "type": "module",
   "private": true,

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrkit/cli",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Git-native architecture decision record tooling from adrkit.",
   "type": "module",
   "license": "Apache-2.0",

packages/cli/src/index.ts

@@ -70,7 +70,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.18.0';
+export const CLI_VERSION = '0.19.0';
 
 function topLevelUsage(style?: StreamStyle): string {
   return renderTopLevelUsage(CLI_VERSION, style);

packages/cli/test/color.test.ts

@@ -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.18.0');
+    expect(result.stdout).toContain('adrkit 0.19.0');
   });
 
   test('forced color keeps lint stdout and stderr separated', async () => {

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrkit/core",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Pure ADR parsing, validation, migration, and affects resolution for adrkit.",
   "type": "module",
   "license": "Apache-2.0",

packages/evaluator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrkit/evaluator",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Deterministic, model-free ADR proposal evaluation and routing for adrkit.",
   "type": "module",
   "license": "Apache-2.0",

packages/mcp/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adrkit/mcp",
   "mcpName": "dev.adrkit/mcp",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.",
   "type": "module",
   "license": "Apache-2.0",