From f62aa370d0d4b0406f30141e1a25d813341510dd Mon Sep 17 00:00:00 2001 From: James Ross Date: Sun, 24 May 2026 13:08:18 -0700 Subject: [PATCH] Docs: Plan v18 release runway --- docs/BEARING.md | 190 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 155 insertions(+), 35 deletions(-) diff --git a/docs/BEARING.md b/docs/BEARING.md index f4634047..03fa7455 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -39,18 +39,19 @@ of handwritten adapter folklore. Current branch state at this boundary: -- Branch: `v18-continuum-slices-46-55` +- Planning branch: `v18-bearing-30-slice-plan` - Base branch: `main` -- Current `origin/main`: `b274bbc9` -- Latest merged PR: #103, v18 migration dry-run CLI and genesis equivalence - evidence +- Current `origin/main`: `91130391` +- Latest merged PR: #104, v18 migration command, scratch history, + finalization safety, command reports, and public-release blockers - Latest released package line: `17.0.1` - Latest completed implementation cycle: `0213-v18-replan-after-command-cli` -- Current work: PR E now contains slices 46 through 65. The branch is ready - for PR review after final local verification and push. -- Cleanup checkpoint: `main` has been fast-forwarded to `origin/main` after - PR #103 merged; this branch starts from that merge commit. +- Current work: realistic v18 release planning for the next thirty slices, + beginning with production-runtime scratch replay and ending with a v18 + public-release go/no-go. +- Cleanup checkpoint: local `main` has been fast-forwarded to `origin/main` + after PR #104 merged; this planning branch starts from that merge commit. The current v18 graph-model posture is: @@ -157,9 +158,10 @@ The current v18 graph-model posture is: Continuum contract tie-back, and operator release notes. That is useful progress, not a finish line. The repo still needs property -projection beyond replay/serialization boundaries, graph-model migration -tooling over real graph history, and genesis replay equivalence over scratch -migrated history before v18 can make stronger compatibility claims. +projection beyond replay/serialization boundaries, production-runtime replay +over migrated scratch history, wet-run migration proof from restored v17 +fixtures, generated Continuum contract evidence, and release documentation +before v18 can make public compatibility claims. ## What Just Shipped @@ -384,26 +386,119 @@ and wet-run fixture harnessing. ## Where We Are Heading -The remaining planned slices are the runway from "typed graph-model surfaces -and fixture-level migration proof exist" to "scratch migrated history can be -proven equivalent before finalization." - -Suggested implementation batches: - -- PR D, slices 41 through 45: merged in PR #103. -- PR E, slices 46 through 55: v17 golden graph-history fixtures, real source - inventory collection, migration operation lowering, scratch migration - writing, scratch equivalence gating, finalization safety, finalization - implementation, end-to-end command wiring, post-migration runtime - conformance, and content/property closeout audit. -- PR E extension, slices 56 through 65: legacy and scratch reading - construction, command reading providers, scratch operation readback - conformance, provider-backed finalization and divergence coverage, command - reporting, a non-finalizing command CLI wrapper, release blockers, and this - replan. -- Next goalpost, slices 66 through 70: production-runtime scratch replay, - wet-run fixture harnessing, live finalization CLI design, and generated - Continuum contract tie-back. +The remaining runway is no longer a five-slice tail. The next realistic plan +is thirty slices. Some slices may collapse when evidence is in hand, but the +release plan should assume the proof work is hard until it is proven easy. + +The first ten slices convert operation-derived confidence into +production-runtime confidence. The next five make finalization safe enough to +expose through the CLI. The next five tie the release claim to generated +Continuum/WARP Optic artifacts. The next five reduce the remaining +content/property compatibility debt that still blocks clean graph-model +language. The final five are release-candidate hardening and go/no-go work. + +### Next Thirty-Slice Checklist + +- [ ] 66. Design production-runtime scratch replay conformance. +- [ ] 67. Add runtime scratch replay request and result nouns. +- [ ] 68. Implement the production-runtime scratch replay provider. +- [ ] 69. Add restored-v17 public-read legacy reading construction. +- [ ] 70. Add scratch public-read reading construction. +- [ ] 71. Add the v17 fixture wet-run migration harness. +- [ ] 72. Capture deterministic wet-run operator reports. +- [ ] 73. Add wet-run failure fixtures for divergence and malformed history. +- [ ] 74. Add pre-finalization drift checks to the wet-run harness. +- [ ] 75. Replan with production-runtime replay evidence in hand. +- [ ] 76. Design live finalization CLI confirmation and reporting. +- [ ] 77. Add finalization request JSON and confirmation adapters. +- [ ] 78. Add finalization report sections and archive evidence output. +- [ ] 79. Enable guarded CLI finalization behind explicit confirmation. +- [ ] 80. Add live-ref drift and existing-archive finalization tests. +- [ ] 81. Inventory current Wesley/Continuum generated graph contracts. +- [ ] 82. Add generated Continuum contract fixture ingestion. +- [ ] 83. Add graph-model conformance checks against generated contracts. +- [ ] 84. Add a `warp-ttd` contract smoke over generated-family facts. +- [ ] 85. Replan with generated contract evidence in hand. +- [ ] 86. Design content attachment storage cutover from `_content*`. +- [ ] 87. Implement typed content attachment write storage behind a gate. +- [ ] 88. Add typed content attachment readback from the new storage path. +- [ ] 89. Add legacy `_content*` to attachment migration mapping. +- [ ] 90. Prove content equivalence across legacy and attachment storage. +- [ ] 91. Design the raw property-boundary retirement plan. +- [ ] 92. Replace replay and serialization raw property reads where safe. +- [ ] 93. Route reducer/op-strategy property writes through intent paths. +- [ ] 94. Tighten the closeout audit to forbid one more raw-boundary class. +- [ ] 95. Cut v18 release-candidate docs, changelog, and go/no-go evidence. + +### User Stories + +- As a migration operator, I can restore a v17 graph fixture, write migrated + scratch history, open that scratch history through the normal production + runtime, and receive deterministic proof before any live ref can move. +- As a release reviewer, I can inspect one wet-run report that includes source + basis, scratch basis, archive target, equivalence result, runtime replay + result, drift checks, and finalization eligibility. +- As a cautious operator, I can only finalize from the CLI by supplying an + explicit confirmation artifact that names the live ref, expected live head, + scratch ref, scratch head, archive ref, and proof identifiers. +- As a Continuum integrator, I can see generated Wesley/Continuum contract + artifacts admitted as evidence, not as handwritten compatibility claims. +- As a `warp-ttd` consumer, I can run at least one generated-family smoke that + consumes git-warp facts without relying on private adapter folklore. +- As a maintainer, I can keep legacy property/content compatibility boundaries + visible, shrinking, and guarded by executable audits while v18 moves toward + public release. +- As a release manager, I can decide whether to ship v18 from a single + go/no-go packet containing CI, wet-run, contract, docs, and risk evidence. + +### Acceptance Criteria + +- Production-runtime conformance opens migrated scratch history through the + same graph-runtime path normal users rely on, not only operation-history + readback. +- Wet-run migration restores the v17 golden fixture into an isolated Git + repository, writes scratch history, builds legacy and scratch readings, + runs equivalence, runs production-runtime conformance, and leaves live + `refs/warp/*` refs untouched unless finalization is explicitly requested. +- CLI finalization is refused unless the confirmation artifact exactly matches + the observed live head, scratch head, archive ref, equivalence proof, and + runtime conformance evidence. +- Archive-preserving finalization remains compare-and-swap only: stale live + refs, existing archive refs, failed equivalence, failed runtime replay, or + missing confirmation produce structured failure reports. +- Continuum/WARP Optic release claims cite generated contract artifacts from + Wesley/Continuum inputs and name any gaps as release notes, not hidden + assumptions. +- Content and property compatibility debt moves monotonically downward: every + newly retired raw boundary tightens the audit and every surviving boundary + has an explicit reason. +- The v18 release candidate is not cut until local gates, CI, wet-run harness, + generated-contract checks, operator docs, and release notes are green. + +### Test Plans + +- Unit-test every new domain noun and adapter parser with malformed-envelope, + wrong-ref, stale-head, missing-proof, duplicate-archive, and failed-replay + cases. +- Add integration tests on temporary Git repositories for fixture restore, + source inventory, scratch writing, production-runtime replay, wet-run report + capture, and non-finalizing safety. +- Add CLI tests that prove finalization flags are rejected without explicit + confirmation and accepted only when the confirmation artifact matches the + observed runtime evidence. +- Add failure fixtures for divergent scratch history, missing patch-boundary + evidence, malformed v17 history, stale live refs, and pre-existing archive + refs. +- Add generated-contract fixture tests that compare git-warp graph-model facts + with Wesley/Continuum generated contract shapes and run the first + `warp-ttd` smoke when the local fixture is available. +- Keep the closeout audit executable and ratcheting: each retired raw + content/property boundary must reduce the allowlist or make the remaining + exception narrower. +- Before a v18 release candidate, run `npm run test:local`, + `npm run test:coverage`, `npm run lint`, `npm run typecheck`, + `npm run lint:md`, `npm run lint:sludge`, `npm run lint:semgrep`, the + wet-run harness, and the generated-contract smoke. ## Invariants @@ -536,7 +631,32 @@ and concrete checks live in `docs/invariants/`. - [x] 65. Replan after the command CLI: [0213](design/0213-v18-replan-after-command-cli/v18-replan-after-command-cli.md). - [ ] 66. Design production-runtime scratch replay conformance. -- [ ] 67. Implement production-runtime scratch replay provider. -- [ ] 68. Add a v17 fixture wet-run migration harness. -- [ ] 69. Design live finalization CLI confirmation and reporting. -- [ ] 70. Tie v18 release claims to generated Continuum contract evidence. +- [ ] 67. Add runtime scratch replay request and result nouns. +- [ ] 68. Implement the production-runtime scratch replay provider. +- [ ] 69. Add restored-v17 public-read legacy reading construction. +- [ ] 70. Add scratch public-read reading construction. +- [ ] 71. Add the v17 fixture wet-run migration harness. +- [ ] 72. Capture deterministic wet-run operator reports. +- [ ] 73. Add wet-run failure fixtures for divergence and malformed history. +- [ ] 74. Add pre-finalization drift checks to the wet-run harness. +- [ ] 75. Replan with production-runtime replay evidence in hand. +- [ ] 76. Design live finalization CLI confirmation and reporting. +- [ ] 77. Add finalization request JSON and confirmation adapters. +- [ ] 78. Add finalization report sections and archive evidence output. +- [ ] 79. Enable guarded CLI finalization behind explicit confirmation. +- [ ] 80. Add live-ref drift and existing-archive finalization tests. +- [ ] 81. Inventory current Wesley/Continuum generated graph contracts. +- [ ] 82. Add generated Continuum contract fixture ingestion. +- [ ] 83. Add graph-model conformance checks against generated contracts. +- [ ] 84. Add a `warp-ttd` contract smoke over generated-family facts. +- [ ] 85. Replan with generated contract evidence in hand. +- [ ] 86. Design content attachment storage cutover from `_content*`. +- [ ] 87. Implement typed content attachment write storage behind a gate. +- [ ] 88. Add typed content attachment readback from the new storage path. +- [ ] 89. Add legacy `_content*` to attachment migration mapping. +- [ ] 90. Prove content equivalence across legacy and attachment storage. +- [ ] 91. Design the raw property-boundary retirement plan. +- [ ] 92. Replace replay and serialization raw property reads where safe. +- [ ] 93. Route reducer/op-strategy property writes through intent paths. +- [ ] 94. Tighten the closeout audit to forbid one more raw-boundary class. +- [ ] 95. Cut v18 release-candidate docs, changelog, and go/no-go evidence.