4.x ADRs

Architectural Decision Records for the 4.x line. New ADRs land here.

Era history

The 4.x line began with the 4.0.0 release-candidate cycle (4.0.0rc1, 2026-09-13). The cycle's intent is declared in docs/changelog/4.0.0.md and executed against the 4.0.0 milestone roadmap.

This folder opened on 2026-09-30. ADRs written earlier in the 4.0.0 cycle (dated 2026-09-13 to 2026-09-29) stay in docs/adr/3.x/: ADRs are immutable and moving them would break every link to them. Read the two folders together for the full 4.0.0 decision record.

Naming

  • YYYY-MM-DD-N-descriptive-title-with-dashes.md where N is 1, 2, 3, … per ADR landed on a given date.

After adding an ADR file, run (from the repository root, so scripts resolves as a package) python -m scripts.docs.freshen_adr_inventory docs/adr/4.x/<your-adr>.md to update the page-inventory lockfile and add the row to the index table below.

Status Conventions

  • Accepted means the decision remains current policy.
  • Superseded means a newer ADR replaced the decision; keep the file for history, but do not implement from it.
  • Deprecated means the direction is in active retirement and should not receive new work.

Template

Use the shared template at docs/architecture/adr-template.md.

Index

Date Title
2026-09-30 allowlist ratchets are priced debt
2026-10-01 dead-symbol allowlist identity is (module, name)
2026-10-01 a mission status read API replaces the CLI-bundled dashboard (extract and replace)
2026-10-01 the decision ledger is a PRIMARY-partition kind (reverses the #3928 COORD intent)
2026-10-03 replace charter reads and writes through a staged Java service strangler
2026-10-04 a Mission waives the contracts/ deliverable with a meta.json declaration
2026-10-04 a started work package keeps its recorded execution lane on re-finalize
2026-10-04 a completed upgrade run reports one outcome
2026-10-04 upgrade writes project-global state once, in the repository root checkout
2026-10-04 the approval stamp bounds what consolidate treats as approved work
2026-10-05 a bare-slug coordination Mission has one exact directory alias set, and one directory on the target
2026-10-05 owned-checkout and start-up performance tests assert runner-relative ratios
2026-10-05 org packs ship their own built-in override sanction
2026-10-06 the Team Kitty surfaces are hidden unless hosted drain is on
2026-10-06 charter offering, active charter and activation presets
2026-10-07 upgrade never runs the mission-state repair
2026-10-06 evidence gates check origin freshness before they trust local evidence
2026-10-07 governed planning application seam and status integration
2026-10-07 a work package leaves review or approval only through a verdict or a noted force
2026-10-08 advancing a mission run is serialised by a per-run-dir lock and a caller-step compare-and-swap
2026-10-10 a scoped workspace handle layers onto the coordination/primary partition (it does not replace it)
2026-10-11 the archive-freeze gate verifies reducer OUTCOME reproduction, not byte-identity
2026-10-11 a Charter Pack declares its level in pack.yaml
2026-10-11 acceptance testing and BDD support: Gherkin scenarios, a per-PR tag check and a black-box Cucumber-JVM nightly
2026-10-12 the test baseline is captured at for_review, at the lane fork point, not at the claim
2026-10-12 the charter becomes an external contract package in its own repository
2026-10-13 acceptance scenarios link to product promises by identifier only; core checks the scenario contract per pull request and hands on versioned evidence
2026-10-13 the event ledger is the publication seam, on by default, with a versioned row contract and local-log retention
2026-10-14 an event-native core with one canonical event writer behind a domain port
2026-10-15 QA and core share ownership of the acceptance scenarios, and engineering tests move into them only through a checked ledger
2026-10-16 extract the charter offering layer first as the GA gate leg; the activation rework rides the post-GA stable line
2026-10-17 the applied-migration ledger is an explicit, two-partition record that is the execution authority for what has run
2026-10-19 one activation ledger persists deactivation, and nothing silently reinstalls it
2026-10-20 command skills use spec-conformant spec-kitty- names, and Antigravity gets its commands as skills
2026-10-22 the Java write service is the canonical event writer, one resident service per repository
Edit this page