diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e490394..013f466f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -46,6 +46,50 @@ Until `1.0.0`, minor releases may include breaking changes at the queue Action for deadline pressure, since a badge cannot detect its own staleness and an issue can notify. +### Changed + +- **Ratified the five foundational ADRs that the corpus had already been building + on**: [ADR-0003](docs/adr/0003-ship-as-spec-kit-extension.md) (Spec Kit extension + plus standalone CLI), [ADR-0006](docs/adr/0006-license-apache-2-and-single-monorepo.md) + (Apache-2.0, DCO, monorepo), [ADR-0007](docs/adr/0007-adapter-isolation-and-public-surface-build.md) + (adapter isolation and the public-surface build), + [ADR-0008](docs/adr/0008-import-and-migration-semantics.md) (MADR migration and + one-way import), and [ADR-0009](docs/adr/0009-affects-resolution-and-catalog-binding.md) + (`affects` resolution and catalog binding) move from `proposed` to `accepted`. + + **This closed a governance inversion, not a formality.** Nine accepted records + already relied on ADR-0007 and six on ADR-0009, and two of them narrowed clauses + of records that had never been ratified — ADR-0013 amends both, ADR-0012 refines + ADR-0009. Accepted decisions were resting on a `proposed` foundation. Each of the + five was verified against the tree before ratification rather than on the strength + of its own checkboxes: ADR-0007's two assertions run as the `clean-clone-builds` + CI job and `scripts/check-deps.ts`, four of ADR-0009's five deliverables exist + (`core/src/affects/`, the purity test, `test/conformance/`, and `adr explain`), + and ADR-0006 is irreversible in fact because the repository is already public. + + Ratification is recorded on each record as `review.decidedAt` and + `review.approvals`, the first use of either field in this corpus, so the audit + trail says when the decision was taken and by whom rather than leaving `status` + to carry it alone. Stale action-item checkboxes were corrected to match verified + reality; items that are genuinely open were left unchecked, including ADR-0006's + DCO bot, which is documented in CONTRIBUTING.md but which no ruleset check + enforces, ADR-0008's re-import pull request, which is unbuilt because non-MADR + re-import is unbuilt, and ADR-0009's catalog port item — the port type exists but + no adapter implementation ships, since `catalog-backstage` is placement and + dependency boundary only. Ratification rests on the resolution semantics, which + are implemented and conformance-tested; the catalog adapter remains governed by + ADR-0013 and ADR-0020. `MANIFEST.md` is brought back in step with the corpus, + and the follow-ups ADR-0012 and ADR-0013 left open for this decision are closed + by it. + + **ARB queue depth drops from 6 to 1**, which the queue-depth badge reads from + `$.totalItems`. [ADR-0005](docs/adr/0005-deterministic-first-evaluator-with-declarative-escalation.md) + deliberately stays `proposed`: only Pass 0 of its four passes exists, and the + record carries a `SOC2 CC8.1` control plus a standing commitment to publish + escalation precision and recall each release. Ratifying it would assert a + compliance obligation the project cannot yet compute. Its `reviewBy` of + 2027-01-18 leaves room to ship Passes 1–3 first. + ## [0.6.0] - 2026-08-11 ### Added diff --git a/MANIFEST.md b/MANIFEST.md index 23e2966c..87e57d22 100644 --- a/MANIFEST.md +++ b/MANIFEST.md @@ -43,13 +43,13 @@ adrkit/ ├── 0000-template.md draft (template) ├── 0001 git-native markdown records accepted ├── 0002 MADR-superset typed frontmatter accepted - ├── 0003 Spec Kit extension + standalone CLI proposed + ├── 0003 Spec Kit extension + standalone CLI accepted ├── 0004 git truth, DB as derived index accepted ├── 0005 deterministic-first evaluator proposed - ├── 0006 Apache-2.0, DCO, monorepo proposed - ├── 0007 adapter isolation, public-surface build proposed - ├── 0008 MADR migration + one-way import proposed - ├── 0009 affects resolution + catalog binding proposed + ├── 0006 Apache-2.0, DCO, monorepo accepted + ├── 0007 adapter isolation, public-surface build accepted + ├── 0008 MADR migration + one-way import accepted + ├── 0009 affects resolution + catalog binding accepted ├── 0010 Bun toolchain, Node-targeted output accepted ├── 0011 host schema at its $id (adrkit.dev) accepted ├── 0012 explicit catalog owned-paths binding accepted @@ -59,7 +59,13 @@ adrkit/ ├── 0016 observed-failing as the coverage bar accepted ├── 0017 explicit, release-scoped dependency audit accepted ├── 0018 MCP SDK v2, dual-era protocol revisions accepted - └── 0019 ship the Spec Kit extension (spike no-go) accepted + ├── 0019 ship the Spec Kit extension (spike no-go) accepted + ├── 0020 rescope SC-010, authorize catalog adapter accepted + ├── 0021 inbound markers without a schema change superseded + ├── 0022 scan markers in check and CI, no authority accepted + ├── 0023 read a marker only where the format hides it accepted + ├── 0024 report the measured scan extent accepted + └── 0025 badges as recipes over existing output accepted ``` ## Known-open, deliberately @@ -70,13 +76,18 @@ adrkit/ Not `mbeacom.github.io` — ADR-0006 publishes under a personal namespace that may later transfer to an org, and a namespace-encoded `$id` breaks every pinned reference on transfer. -- Six records remain `proposed` (0003, 0005–0009). They are queued for review by - `adr queue`; being proposed does not stop the code they describe from having - shipped, and the queue reports that state rather than hiding it. +- One record remains `proposed` (0005). It is queued for review by `adr queue`; + being proposed does not stop the code it describes from having shipped, and the + queue reports that state rather than hiding it. Records 0003 and 0006–0009 were + ratified on 2026-08-12, closing a gap in which accepted records rested on a + proposed foundation. - ADR-0014 rung-3 external/community validation is open for both the Phase 6 ARB queue and the Spec Kit extension. Tracked honestly as absent, never as met. -- Catalog binding (`packages/adapters/catalog-*`) is not built. The viability - spike `specs/009-catalog-binding-viability/` recorded `blocked`. +- Catalog binding is not built. `packages/adapters/catalog-backstage` exists as + placement and dependency boundary only and generates nothing; no snapshot + envelope exists. The viability spike `specs/009-catalog-binding-viability/` + recorded `blocked`, and ADR-0020 authorizes the work without asserting it has + landed. ADR-0009's catalog-port action item is open for the same reason. - Three open questions at the foot of `plan.md`. Do not let an implementer resolve them silently. @@ -89,8 +100,9 @@ independent of the GitHub namespace and unaffected either way. ## Verification -20 files under `docs/adr/` — the template plus 19 records, ids 0001–0019, no -gaps. All at schema 0.1.0: 13 accepted, 6 proposed, and the template at `draft`. +26 files under `docs/adr/` — the template plus 25 records, ids 0001–0025, no +gaps. All at schema 0.1.0: 23 accepted, 1 proposed, 1 superseded, and the +template at `draft`. No dangling `relatesTo`. No one-way door on the auto tier. No accepted record without a decider or an import provenance. JSON Schema and Zod agree on property casing. No `@adr/` references remain — the scope is `@adrkit/*` throughout. diff --git a/docs/adr/0003-ship-as-spec-kit-extension.md b/docs/adr/0003-ship-as-spec-kit-extension.md index cc04250a..ac085d7e 100644 --- a/docs/adr/0003-ship-as-spec-kit-extension.md +++ b/docs/adr/0003-ship-as-spec-kit-extension.md @@ -2,7 +2,7 @@ schemaVersion: 0.1.0 id: "0003" title: Ship as a Spec Kit extension plus a standalone CLI, not a competing harness -status: proposed +status: accepted date: 2026-07-18 deciders: ["@mbeacom"] tags: [strategy, integration, distribution] @@ -23,6 +23,8 @@ review: tierReason: Determines distribution strategy and primary adoption channel. queuedAt: 2026-07-28T00:00:00Z slaDays: 30 + approvals: ["@mbeacom"] + decidedAt: 2026-08-12T12:00:00Z externalRefs: - type: doc url: https://github.github.com/spec-kit/ diff --git a/docs/adr/0006-license-apache-2-and-single-monorepo.md b/docs/adr/0006-license-apache-2-and-single-monorepo.md index 8fe1aad5..0c7a8afb 100644 --- a/docs/adr/0006-license-apache-2-and-single-monorepo.md +++ b/docs/adr/0006-license-apache-2-and-single-monorepo.md @@ -2,7 +2,7 @@ schemaVersion: 0.1.0 id: "0006" title: License Apache-2.0 with a DCO and develop in a single monorepo -status: proposed +status: accepted date: 2026-07-18 deciders: ["@mbeacom"] tags: [licensing, governance, repo] @@ -23,6 +23,8 @@ review: tierReason: Licensing is effectively irreversible once external contributions land. queuedAt: 2026-07-28T00:00:00Z slaDays: 30 + approvals: ["@mbeacom"] + decidedAt: 2026-08-12T12:00:00Z --- # ADR-0006: License Apache-2.0 with a DCO and develop in a single monorepo @@ -144,10 +146,11 @@ sense if standardization is genuinely the goal — which ADR-0002 asserts it is. ## Action items -1. [ ] LICENSE, NOTICE, per-package `license` fields +1. [x] LICENSE, NOTICE, per-package `license` fields 2. [ ] DCO bot enabled on the repository -3. [ ] `schema/LICENSE` (CC0) with the carve-out stated plainly in the README -4. [ ] SECURITY.md and CODE_OF_CONDUCT.md before the repository goes public +3. [x] `schema/LICENSE` (CC0) with the carve-out stated plainly in the README +4. [x] SECURITY.md and CODE_OF_CONDUCT.md before the repository goes public 5. [ ] Resolve external participation obligations before first public push -6. [ ] Register a namespace-independent domain for the schema `$id`, or accept +6. [x] Register a namespace-independent domain for the schema `$id`, or accept that the schema hostname is fixed for the life of the major version + — resolved by `https://adrkit.dev/schema/adr/v0.1.0/adr.schema.json`. diff --git a/docs/adr/0007-adapter-isolation-and-public-surface-build.md b/docs/adr/0007-adapter-isolation-and-public-surface-build.md index d7afddd6..f33967f3 100644 --- a/docs/adr/0007-adapter-isolation-and-public-surface-build.md +++ b/docs/adr/0007-adapter-isolation-and-public-surface-build.md @@ -2,7 +2,7 @@ schemaVersion: 0.1.0 id: "0007" title: Isolate integrations as optional adapters and build only against public surfaces -status: proposed +status: accepted date: 2026-07-18 deciders: ["@mbeacom"] tags: [architecture, packaging, governance, ip-hygiene] @@ -27,6 +27,8 @@ review: boundary for the repository. Expensive to reverse once adapters exist. queuedAt: 2026-07-28T00:00:00Z slaDays: 30 + approvals: ["@mbeacom"] + decidedAt: 2026-08-12T12:00:00Z assertions: - id: core-has-no-adapter-deps description: >- @@ -158,9 +160,9 @@ mostly selecting for adapters that were viable anyway. ## Action items -1. [ ] `packages/adapters/` with a documented plugin contract -2. [ ] `core-has-no-adapter-deps` as a dependency-graph check in CI -3. [ ] `clean-clone-builds` job running with no credentials in the environment -4. [ ] Adapter release matrix pinning tested upstream versions -5. [ ] CONTRIBUTING.md states the public-surface rule as a contribution +1. [x] `packages/adapters/` with a documented plugin contract +2. [x] `core-has-no-adapter-deps` as a dependency-graph check in CI +3. [x] `clean-clone-builds` job running with no credentials in the environment +4. [x] Adapter release matrix pinning tested upstream versions +5. [x] CONTRIBUTING.md states the public-surface rule as a contribution requirement, not a preference diff --git a/docs/adr/0008-import-and-migration-semantics.md b/docs/adr/0008-import-and-migration-semantics.md index 99312c2c..4e0bc4ee 100644 --- a/docs/adr/0008-import-and-migration-semantics.md +++ b/docs/adr/0008-import-and-migration-semantics.md @@ -2,7 +2,7 @@ schemaVersion: 0.1.0 id: "0008" title: Migrate MADR corpora in place and treat all other imports as one-way with a re-import diff -status: proposed +status: accepted date: 2026-07-18 deciders: ["@mbeacom"] tags: [import, migration, interop, adoption] @@ -25,6 +25,8 @@ review: earned. Low technical risk, high governance risk. queuedAt: 2026-07-28T00:00:00Z slaDays: 30 + approvals: ["@mbeacom"] + decidedAt: 2026-08-12T12:00:00Z --- # ADR-0008: Migrate MADR corpora in place and treat all other imports as one-way with a re-import diff @@ -157,9 +159,9 @@ decision-log adapter, not here. ## Action items -1. [ ] `import-incomplete` lint rule (schema support already lands in ADR-0002) -2. [ ] `adr migrate --from madr`, idempotent, in place, body untouched -3. [ ] Fingerprint + four-bucket classifier in `packages/core/src/import/` +1. [x] `import-incomplete` lint rule (schema support already lands in ADR-0002) +2. [x] `adr migrate --from madr`, idempotent, in place, body untouched +3. [x] Fingerprint + four-bucket classifier in `packages/core/src/import/` 4. [ ] Re-import emits a PR with a divergence report; never a direct write -5. [ ] Round-trip explicitly documented as unsupported, with this record as the +5. [x] Round-trip explicitly documented as unsupported, with this record as the reason diff --git a/docs/adr/0009-affects-resolution-and-catalog-binding.md b/docs/adr/0009-affects-resolution-and-catalog-binding.md index e4dcdb41..ab417eb4 100644 --- a/docs/adr/0009-affects-resolution-and-catalog-binding.md +++ b/docs/adr/0009-affects-resolution-and-catalog-binding.md @@ -2,7 +2,7 @@ schemaVersion: 0.1.0 id: "0009" title: Pin affects resolution semantics and bind entity refs to pluggable catalogs -status: proposed +status: accepted date: 2026-07-18 deciders: ["@mbeacom"] tags: [schema, core, matching, catalog] @@ -25,6 +25,8 @@ review: changes which decisions govern which code. queuedAt: 2026-07-28T00:00:00Z slaDays: 30 + approvals: ["@mbeacom"] + decidedAt: 2026-08-12T12:00:00Z assertions: - id: resolution-is-pure description: >- @@ -175,10 +177,15 @@ actionable rather than to suppress it. ## Action items -1. [ ] Resolver in `packages/core/src/affects/`, pure, exhaustively unit-tested -2. [ ] `resolution-is-pure` assertion wired into CI -3. [ ] Conformance fixture suite — matcher set + file list + expected match, as +1. [x] Resolver in `packages/core/src/affects/`, pure, exhaustively unit-tested +2. [x] `resolution-is-pure` assertion wired into CI +3. [x] Conformance fixture suite — matcher set + file list + expected match, as published test data other implementations can run 4. [ ] Catalog port interface, with both adapters stubbed against public docs -5. [ ] `adr explain ` — print every governing decision and the matcher + — the port type exists (`packages/core/src/affects/catalog.ts`), but no + adapter implementation ships. `packages/adapters/catalog-backstage` is + placement and dependency boundary only and generates nothing; the + cloud-catalog adapter is deferred per the Decision above. Tracked by + ADR-0013 and ADR-0020. +5. [x] `adr explain ` — print every governing decision and the matcher that fired, because an unexplainable match is as bad as a wrong one diff --git a/docs/adr/0012-bind-catalog-entities-to-owned-paths-with-an-explicit-annotation.md b/docs/adr/0012-bind-catalog-entities-to-owned-paths-with-an-explicit-annotation.md index e73a1a40..026f2d9c 100644 --- a/docs/adr/0012-bind-catalog-entities-to-owned-paths-with-an-explicit-annotation.md +++ b/docs/adr/0012-bind-catalog-entities-to-owned-paths-with-an-explicit-annotation.md @@ -357,5 +357,9 @@ remains required for each; it is deliberately out of scope here. 3. [ ] Implement `adrkit.io/owned-paths` parsing, the restricted-dialect glob validator, and atomic fail-closed semantics in the offline snapshot generator (gated; not authorized here). -4. [ ] Open the separate status-ratification or amendment decision for ADR-0007 +4. [x] Open the separate status-ratification or amendment decision for ADR-0007 and ADR-0009 once their blockers above clear. + — both ratified 2026-08-12. Ratification rests on ADR-0007's two green + required checks and ADR-0009's implemented, conformance-tested resolution + semantics; items 2 and 3 above remain open and continue to gate the + persisted envelope and the generator, which no ratified clause asserts. diff --git a/docs/adr/0013-reconcile-adapter-isolation-and-catalog-binding-with-the-offline-snapshot-genera.md b/docs/adr/0013-reconcile-adapter-isolation-and-catalog-binding-with-the-offline-snapshot-genera.md index c73f8ea0..83354837 100644 --- a/docs/adr/0013-reconcile-adapter-isolation-and-catalog-binding-with-the-offline-snapshot-genera.md +++ b/docs/adr/0013-reconcile-adapter-isolation-and-catalog-binding-with-the-offline-snapshot-genera.md @@ -199,8 +199,10 @@ rewriting one-way-door records in a reconciliation PR. ## Action items -1. [ ] Fold these amendments into ADR-0007 and ADR-0009 when each is taken to an +1. [x] Fold these amendments into ADR-0007 and ADR-0009 when each is taken to an explicit accept/supersede decision. + — both were accepted 2026-08-12 carrying the amendment inline, so each + record states the narrowed rule at the point a reader meets it. 2. [ ] Ensure `specs/009-catalog-binding-viability/` scoping records the offline-generator/no-dynamic-loader boundary and the versioned envelope. 3. [ ] Keep `core-has-no-adapter-deps` and `clean-clone-builds` green as the