diff --git a/docs/BEARING.md b/docs/BEARING.md index 4af775ee..1685a7cb 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -186,19 +186,21 @@ Current direction and active tensions. Historical ship data is in ## Next Target -With Code Dojo, DX-047/#342, DL-018/#343, #335, and #354 landed, the immediate -`v7.2.0` focus is final release prep: version metadata, dated changelog, -front-door release copy, release-readiness, and final-main tag validation. +With `v7.2.0` tagged, published, and verified, the immediate target is #457: +shape the V8 Runtime Graph and Scene IR product contract before implementation +continues. ```text -DOGFOOD release-story surfaces - -> #354 criteria audit - -> release-readiness and preflight - -> v7.2.0 tag decision +VISOR v8 tracker (#457) + -> GraphQL Blocks source contract + -> bijou-block/1 artifact contract + -> ui-scene-ir/1 lowering contract + -> receipts, source maps, lower modes, and debug facts + -> DOGFOOD round-trip witness ``` -After `v7.2.0` stabilizes the current V7 surface, V8 must turn the proof chain -into product contract: +The proof chain that V7 shipped must become a product contract before Bijou +pulls in broad Geordi, Wesley, browser, or native-render work: ```text GraphQL SDL fixture @@ -211,18 +213,19 @@ GraphQL SDL fixture Recommended pull order: -1. Finish the `v7.2.0` release-prep branch and Release Dry Run before any tag - is created. -2. Merge release prep, sync local `main` to `origin/main`, and rerun - milestone-aware release-readiness from the exact tag commit. -3. Create `v7.2.0` only from synced `main` after final-main evidence is green. -4. Shape #302 into a V8 design packet with artifact semantics, receipt - invariants, source-map ownership, lower-mode contracts, and failure cases. -5. Promote only the Runtime Graph and Scene IR issues needed for that contract +1. Land the #457 design packet that defines GraphQL Blocks source model, + `bijou-block/1` artifact semantics, `ui-scene-ir/1` lowering contract, + receipt and source-map ownership, lower-mode rules, debug facts, failure + cases, and DOGFOOD witness criteria. +2. Promote only the Runtime Graph and Scene IR issues needed for that contract out of `Beyond`. -6. Keep `v9.0.0` for Product Workbench and operator surfaces after V8 stabilizes +3. Pull #458 as the first implementation proof: emit a GraphQL block artifact + bundle with replay and visual scene facts. +4. Pull #459 after #458 fixes the bundle shape: validate + `packed-bijou-cells/1` and adapt it to `Surface`. +5. Keep `v9.0.0` for Product Workbench and operator surfaces after V8 stabilizes the source/artifact/IR contract. -7. Keep closed dependency PR #326 as superseded lineage, not active release +6. Keep closed dependency PR #326 as superseded lineage, not active release work. Non-goals for the next cycle: diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 32fb77de..1bca52f4 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file. All packages (`@flyingrobots/bijou`, `@flyingrobots/bijou-node`, `@flyingrobots/bijou-tui`, `@flyingrobots/bijou-tui-app`, `create-bijou-tui-app`, `@flyingrobots/bijou-i18n`, `@flyingrobots/bijou-i18n-tools`, `@flyingrobots/bijou-i18n-tools-node`, `@flyingrobots/bijou-i18n-tools-xlsx`, `@flyingrobots/bijou-mcp`) are versioned in lock-step. +## [Unreleased] + +### Changed + +- **V8 Runtime Graph contract shaping** — `docs/BEARING.md` now treats #457 as + the immediate post-`v7.2.0` target, + [`DX-048`](design/DX-048-v8-runtime-graph-scene-ir-contract.md) records the + GraphQL Blocks, `bijou-block/1`, `ui-scene-ir/1`, receipts, source maps, + lower modes, debug facts, and DOGFOOD round-trip contract, and the `v7.2.0` + release packet now records the completed tag, publish, GitHub Release, and + npm registry verification evidence. + ## [7.2.0] - 2026-07-05 ### Added @@ -2558,6 +2570,7 @@ First public release. - **Screen control** — `enterScreen()`, `exitScreen()`, `clearAndHome()`, `renderFrame()` - **Layout helpers** — `vstack()`, `hstack()` +[Unreleased]: https://github.com/flyingrobots/bijou/compare/v7.2.0...HEAD [7.2.0]: https://github.com/flyingrobots/bijou/compare/v7.1.0...v7.2.0 [7.1.0]: https://github.com/flyingrobots/bijou/compare/v7.0.0...v7.1.0 [7.0.0]: https://github.com/flyingrobots/bijou/compare/v5.0.0...v7.0.0 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 1ba67252..6daec310 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -228,8 +228,9 @@ that a cross-repository release is the next smallest honest boundary. ## Next Pull -The immediate product pull after `v7.2.0` should shape the **v8.0.0 Runtime -Graph and Scene IR product contract**. +The immediate product pull after `v7.2.0` should land +[`DX-048`](./design/DX-048-v8-runtime-graph-scene-ir-contract.md) and shape the +**v8.0.0 Runtime Graph and Scene IR product contract**. That pull should keep the V8 tracker staged around VISOR, artifact semantics, receipts, source maps, lower modes, debug facts, DOGFOOD round-trip fixtures, @@ -245,7 +246,7 @@ remain the intended feature horizons after the stabilization release. | :--- | :--- | :--- | :--- | :--- | | `v7.1.0` | Shipped Post-V7 Minor | Landed DX-046 [#329](https://github.com/flyingrobots/bijou/issues/329), release-prep guardrails [#270](https://github.com/flyingrobots/bijou/issues/270) and [#312](https://github.com/flyingrobots/bijou/issues/312), the v7.1.0 release PR, and `Unreleased` changelog work after `v7.0.0` | The repo shipped a meaningful post-V7 batch without turning it into a new product epoch. | Met: DX-046 green, #270/#312 green, release evidence packet written, #329 kept in `v7.1.0` without moving #302 out of `Beyond`, and no broad scope creep. | | `v7.2.0` | Demo Integrity And Framework Input Stabilization | Release-gate goalpost [#354](https://github.com/flyingrobots/bijou/issues/354), framework input stories [#344](https://github.com/flyingrobots/bijou/issues/344), [#345](https://github.com/flyingrobots/bijou/issues/345), [#353](https://github.com/flyingrobots/bijou/issues/353), landed DOGFOOD repair stories [#340](https://github.com/flyingrobots/bijou/issues/340), [#341](https://github.com/flyingrobots/bijou/issues/341), [#342](https://github.com/flyingrobots/bijou/issues/342), [#343](https://github.com/flyingrobots/bijou/issues/343), landed release-story story [#335](https://github.com/flyingrobots/bijou/issues/335), and security patches [#357](https://github.com/flyingrobots/bijou/issues/357), [#370](https://github.com/flyingrobots/bijou/issues/370). | The v7.1 proof exists, but the release-video rehearsal exposed demo-breaking seams in localization, theme posture, Blocks docs, release-story surfaces, and mouse routing; GitHub/npm audit also reported narrow development-tooling and dependency advisories that are now triaged clean. | Workspace pointer fallthrough fixed, page-frame helper exports public, mouse test helpers available, DOGFOOD demo surfaces honest enough for release video, audit clean, #335 release-story surfaces implemented, and release-readiness green. | -| `v8.0.0` | Runtime Graph And Scene IR Product Contract | Staged milestone tracker [#457](https://github.com/flyingrobots/bijou/issues/457), VISOR artifact bundle [#458](https://github.com/flyingrobots/bijou/issues/458), and packed Bijou cell adapter [#459](https://github.com/flyingrobots/bijou/issues/459). Candidate source lineage remains in Beyond: [#202](https://github.com/flyingrobots/bijou/issues/202), [#209](https://github.com/flyingrobots/bijou/issues/209), [#210](https://github.com/flyingrobots/bijou/issues/210), [#211](https://github.com/flyingrobots/bijou/issues/211), [#212](https://github.com/flyingrobots/bijou/issues/212), [#213](https://github.com/flyingrobots/bijou/issues/213), [#216](https://github.com/flyingrobots/bijou/issues/216), [#219](https://github.com/flyingrobots/bijou/issues/219), [#301](https://github.com/flyingrobots/bijou/issues/301), and [#302](https://github.com/flyingrobots/bijou/issues/302). | This is the current product direction after DX-043 through DX-046 and the VISOR planning turn: portable scenes, GraphQL blocks, deterministic debug facts, packed terminal cells, replay/capture evidence, and product fixtures need to become a stable contract. | Stable artifact semantics, DOGFOOD round-trip fixtures, terminal/frame-capture proof, lower-mode and source-map receipts, and failure tests. | +| `v8.0.0` | Runtime Graph And Scene IR Product Contract | Staged milestone tracker [#457](https://github.com/flyingrobots/bijou/issues/457), design packet [`DX-048`](./design/DX-048-v8-runtime-graph-scene-ir-contract.md), VISOR artifact bundle [#458](https://github.com/flyingrobots/bijou/issues/458), and packed Bijou cell adapter [#459](https://github.com/flyingrobots/bijou/issues/459). Candidate source lineage remains in Beyond: [#202](https://github.com/flyingrobots/bijou/issues/202), [#209](https://github.com/flyingrobots/bijou/issues/209), [#210](https://github.com/flyingrobots/bijou/issues/210), [#211](https://github.com/flyingrobots/bijou/issues/211), [#212](https://github.com/flyingrobots/bijou/issues/212), [#213](https://github.com/flyingrobots/bijou/issues/213), [#216](https://github.com/flyingrobots/bijou/issues/216), [#219](https://github.com/flyingrobots/bijou/issues/219), [#301](https://github.com/flyingrobots/bijou/issues/301), and [#302](https://github.com/flyingrobots/bijou/issues/302). | This is the current product direction after DX-043 through DX-046 and the VISOR planning turn: portable scenes, GraphQL blocks, deterministic debug facts, packed terminal cells, replay/capture evidence, and product fixtures need to become a stable contract. | Stable artifact semantics, DOGFOOD round-trip fixtures, terminal/frame-capture proof, lower-mode and source-map receipts, and failure tests. | | `v9.0.0` | Product Workbench And Operator Surfaces | Beyond: [#204](https://github.com/flyingrobots/bijou/issues/204), [#205](https://github.com/flyingrobots/bijou/issues/205), [#206](https://github.com/flyingrobots/bijou/issues/206), [#207](https://github.com/flyingrobots/bijou/issues/207), [#208](https://github.com/flyingrobots/bijou/issues/208), [#214](https://github.com/flyingrobots/bijou/issues/214), [#215](https://github.com/flyingrobots/bijou/issues/215), [#217](https://github.com/flyingrobots/bijou/issues/217), [#218](https://github.com/flyingrobots/bijou/issues/218), [#248](https://github.com/flyingrobots/bijou/issues/248), [#272](https://github.com/flyingrobots/bijou/issues/272), [#311](https://github.com/flyingrobots/bijou/issues/311), [#315](https://github.com/flyingrobots/bijou/issues/315), [#318](https://github.com/flyingrobots/bijou/issues/318). Triage: [#317](https://github.com/flyingrobots/bijou/issues/317), [#316](https://github.com/flyingrobots/bijou/issues/316). | Once V8 stabilizes the artifact contract, the next value is authoring and inspecting real product surfaces: BlockLab, Theme Lab, localization operations, artifact matrices, and host controls. | Storybook-grade BlockLab workflows, Theme Inspector/Lab provenance, localization workbench proof, artifact matrices, and playback-backed terminal input where applicable. | | `v10.0.0+` | Ecosystem Integration | Wesley, Geordi, and host integration follow-on work after V8/V9 shape the contracts | Cross-repository integration should consume proven Bijou contracts rather than define them under release pressure. | A cross-repo release packet with explicit dependency ordering, proof artifacts, and rollback boundaries. | diff --git a/docs/design/DX-048-v8-runtime-graph-scene-ir-contract.md b/docs/design/DX-048-v8-runtime-graph-scene-ir-contract.md new file mode 100644 index 00000000..a355c1ec --- /dev/null +++ b/docs/design/DX-048-v8-runtime-graph-scene-ir-contract.md @@ -0,0 +1,259 @@ +--- +title: DX-048 V8 Runtime Graph And Scene IR Contract +legend: DX +lane: release +priority: high +github_issue: 457 +status: active +keywords: + - developer-experience + - runtime-graph + - scene-ir + - graphql + - blocks + - visor + - v8.0.0 +--- + +# DX-048 V8 Runtime Graph And Scene IR Contract + +Legend: [DX - Developer Experience](../legends/DX-developer-experience.md) + +## Linked Work + +- Goalpost tracker: [#457](https://github.com/flyingrobots/bijou/issues/457) +- First artifact proof: + [#458](https://github.com/flyingrobots/bijou/issues/458) +- Packed-cell proof: + [#459](https://github.com/flyingrobots/bijou/issues/459) +- Broad source lineage: + [#302](https://github.com/flyingrobots/bijou/issues/302) +- VISOR coordination surface: + [flyingrobots/visor](https://github.com/flyingrobots/visor) +- Prior Bijou proof: + [DX-046 GraphQL Authored DOGFOOD Block Fixture](./DX-046-graphql-authored-dogfood-block-fixture.md) + +## Decision Summary + +`v7.1.0` proved a constrained path from GraphQL SDL to `bijou-block/1`, +`ui-scene-ir/1`, terminal proof, grouped debug facts, and DOGFOOD product +facts. `v7.2.0` stabilized the demo and release surface enough to stop treating +that path as release bookkeeping. + +The V8 work starts by freezing the product contract before implementation +continues. DX-048 defines the source, artifact, IR, receipt, source-map, +lower-mode, debug, capture, and witness boundaries that #458 and #459 must +consume. + +VISOR is the coordination surface for the proof. Bijou remains responsible for +the source-side contracts and the terminal `Surface` proof. Geordi, Wesley, +Bunny, WARP TTD, browser renderers, and native renderers may consume or inform +the contract later, but they do not define the first Bijou release gate. + +## Sponsor Human + +A maintainer wants V8 to become a stable product contract, not a pile of +exciting demos. They should be able to ask, "what exactly crosses from GraphQL +Blocks into Bijou Blocks IR and then into render targets?" and get a versioned, +testable answer. + +## Sponsor Agent + +An agent needs to trace one product fact from a GraphQL source fixture through +artifact fields, scene nodes, terminal cells, lower modes, source maps, debug +facts, and receipts without scraping rendered text or guessing ownership. + +## Hill + +Given a checked-in DOGFOOD GraphQL fixture, Bijou can produce a deterministic +artifact bundle with `bijou-block/1`, `ui-scene-ir/1`, +`graphql-bijou-block-debug/1`, lower-mode witnesses, source maps, receipts, and +packed-cell render evidence, and reviewers can replay the full path without any +Wesley or Geordi repository changes. + +## Playback Questions + +- What is the GraphQL Blocks source model allowed to express? +- Which facts belong in the `bijou-block/1` artifact and which belong only in + the compiler receipt? +- What is the `ui-scene-ir/1` lowering contract and what facts must it preserve? +- Who owns receipt and source-map ownership when a source field fans out into + multiple scene nodes or terminal cells? +- Which lower modes are mandatory for a fixture before V8 calls it product + proof? +- What debug facts are stable enough for DOGFOOD, VISOR, and future replay + tooling to inspect? +- What invalid source cases fail before terminal rendering? + +## Scope + +This cycle defines the V8 contract and proof boundaries: + +- GraphQL Blocks source model: + - fixture identity + - component identity + - field identity + - group identity + - binding and command-intent identity + - i18n key references + - theme token references + - target render profile +- `bijou-block/1` artifact semantics: + - stable artifact version + - deterministic field and group ordering + - explicit product-fact inventory + - hashable payload shape + - no hidden global registry dependency +- `ui-scene-ir/1` lowering contract: + - stable scene version + - node identity and role ownership + - text, style, focus, and geometry facts + - lower-mode witness fields + - source-map references back to artifact and source spans +- receipt and source-map ownership: + - source hash + - artifact hash + - scene hash + - packed-cell hash + - dependency and transform list + - failure facts for rejected input +- debug fact contract: + - `graphql-bijou-block-debug/1` summary facts + - group, field, i18n, token, action, binding, lower-mode, and hash inventory + - deterministic error categories +- DOGFOOD round-trip fixture: + - source fixture checked into the repo + - artifact bundle checked or snapshotted as test evidence + - terminal `Surface` proof + - lower-mode evidence + - review path documented in DOGFOOD or release-facing docs + +## Non-Goals + +This cycle does not: + +- implement the #458 artifact bundle +- implement the #459 packed-cell adapter +- migrate every DOGFOOD block to GraphQL +- introduce a general GraphQL resolver runtime +- require Geordi, Wesley, Bunny, WARP TTD, browser, or native app changes +- ship BlockLab, Theme Lab, localization workbench, or operator surfaces +- define the final browser or native render target APIs +- move all #302 lineage issues into `v8.0.0` + +## Contract Sketch + +The minimum accepted artifact bundle should be inspectable as plain facts: + +```text +graphql-source/1 + -> bijou-block/1 + -> ui-scene-ir/1 + -> packed-bijou-cells/1 + -> terminal-surface-proof/1 +``` + +Each transition must produce a receipt: + +```text +receipt/1 { + fromVersion + toVersion + sourceHash + outputHash + dependencyHashes[] + transformFacts[] + sourceMapRefs[] + lowerModeWitnesses[] + debugFactRefs[] +} +``` + +The receipt is not a logging nicety. It is the review contract. If a future +VISOR, DOGFOOD, WARP TTD, or browser proof cannot name the receipt it consumed, +it is not part of the V8 release gate. + +## Failure Cases + +The V8 contract must reject: + +- duplicate source, field, group, node, binding, or command ids +- missing component identity +- missing product facts for a DOGFOOD witness +- broken i18n key references +- broken theme token references +- source spans that cannot map back from artifact or scene facts +- lower-mode witnesses that omit required role or text facts +- packed cells that cannot map to scene nodes +- debug summaries that omit hashes or dependency facts + +## Accessibility Posture + +The contract must preserve lower-mode witnesses. Terminal proof alone is not +enough. Every accepted DOGFOOD fixture must expose accessible text and role +facts through the artifact or scene receipt so reviewers can inspect a non-TTY +representation. + +## Localization / Directionality Posture + +The GraphQL source may reference i18n keys and source-language fallback copy, +but it must not smuggle untracked visible copy into the artifact. V8 must keep +localization keys visible in debug facts and receipts so DOGFOOD can explain +what translated and what fell back. + +## Agent Inspectability / Explainability Posture + +Agents must be able to inspect the complete source-to-render chain without +executing a full app: + +- parse the fixture +- read the artifact +- read the scene IR +- read the receipt list +- read the source map +- read debug facts +- run the terminal proof +- compare hashes + +This is the line between a demo and a product contract. + +## Linked Invariants + +- Tests Are the Spec +- Runtime Truth Wins +- Docs Are the Demo +- Work Is Issue-Backed +- Release Claims Need Proof +- Facts Before Behavior + +## Implementation Outline + +1. Land this design packet and post-release BEARING refresh. +2. Update #457 with the contract decision and the #458 / #459 pull order. +3. Add tests that keep ROADMAP, BEARING, and this design aligned. +4. In #458, introduce the artifact bundle fixture and receipt shape. +5. In #459, validate `packed-bijou-cells/1` and adapt it to `Surface`. +6. Only after #458 and #459 are stable, promote broader #302 lineage into V8 + implementation scope. + +## Tests To Write First + +- WF-130 roadmap tests must require this design packet while #457 is open. +- Artifact bundle tests in #458 should fail until `bijou-block/1`, + `ui-scene-ir/1`, receipts, source maps, and debug facts are emitted together. +- Packed-cell tests in #459 should fail until `packed-bijou-cells/1` can map + cells back to scene nodes and render a `Surface` proof. + +## Validation Plan + +```bash +npx vitest run --config vitest.config.ts tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts tests/cycles/WF-130/roadmap-goalpost-policy.part02.test.ts tests/cycles/WF-130/roadmap-goalpost-policy.part03.test.ts +npm run docs:inventory +npm run typecheck:test +npm run lint +git diff --check +``` + +## Closeout Notes + +Open. This design is the first V8 pull after `v7.2.0` shipped. diff --git a/docs/releases/7.2.0/README.md b/docs/releases/7.2.0/README.md index e524ccfa..0c6ecbd0 100644 --- a/docs/releases/7.2.0/README.md +++ b/docs/releases/7.2.0/README.md @@ -5,25 +5,28 @@ Bijou 7.2.0 is a narrow stabilization and demo-integrity release after the DOGFOOD localization and themes, Blocks documentation, release-story surfaces, dependency posture, and release bookkeeping. -This packet was started on the release-gate branch and finalized on the -release-prep branch before the public tag exists. The release-prep branch owns -the lock-step package version bump, changelog boundary, README update, package -metadata validation, release-readiness replay, and Release Dry Run before -merge. Tag creation, publish automation, npm registry verification, and GitHub -Release verification remain final-main work and must run only from the merged -`origin/main` release commit. +This packet was started on the release-gate branch, finalized on the +release-prep branch, and closed from the verified `origin/main` release commit. +The public `v7.2.0` tag was created from +`123f4a6150963932118cbf763a8a6ec03487e227` on 2026-07-05 after final-main +validation passed. Tag Guard, Release workflow, tag CI, GitHub Release +verification, and npm registry verification all passed after the tag was +pushed. ## Release Summary - Version: `7.2.0` -- Tag: `v7.2.0` (pending final-main release step) +- Tag: [`v7.2.0`](https://github.com/flyingrobots/bijou/releases/tag/v7.2.0) - Previous public tag: `v7.1.0` +- Release commit: `123f4a6150963932118cbf763a8a6ec03487e227` - Release type: stable minor - npm dist-tag after publish: `latest` - Release-prep branch: `cycle/v72-release-prep` - Release-gate lineage branch: `cycle/v72-release-gate-354` - Release date: 2026-07-05 - Publish surface: npm workspace packages only +- Release workflow: + ## Tracker And Goalpost Map @@ -56,8 +59,8 @@ disposition. in-app release-story surfaces. - Canonical proof inputs: the tests and DOGFOOD fixtures named in the per-slice sections below. -- Replay: run `npm run release:readiness` from the release-prep branch and - then run `npm run release:readiness -- --milestone v7.2.0` again from the +- Replay: run `npm run release:readiness` from the release-prep branch, then + run `npm run release:readiness -- --milestone v7.2.0` again from the exact merged final-main release commit before tagging. - Witness: local release-gate validation on 2026-07-04 passed `npm run release:preflight`, `npm run docs:inventory`, @@ -66,9 +69,12 @@ disposition. `npm run release:readiness` without `--milestone`. Release-prep validation on 2026-07-05 passed `npm run release:readiness -- --milestone v7.2.0` after the lock-step - version bump and dated changelog boundary. -- Residual risk: no accepted release risk. Final-main validation must still - replay the milestone-aware command before any version tag is created. + version bump and dated changelog boundary. Final-main validation on + 2026-07-05 passed `npm run release:preflight`, `npm run docs:inventory`, + `npm audit --omit=dev --audit-level=high`, and the milestone-aware + readiness gate from commit `123f4a61`; the Release Dry Run, Tag Guard, + Release workflow, tag CI, GitHub Release, and npm registry checks all passed. +- Residual risk: no accepted release risk. ### Framework Input Stabilization @@ -259,13 +265,19 @@ disposition. | Gate | Command or source | Expected result | Status | | :--- | :--- | :--- | :--- | -| Release metadata preflight | `npm run release:preflight` | Lock-step workspace metadata is valid. | Passed on release-prep branch after the lock-step `7.2.0` manifest and lockfile bump. | -| Docs inventory | `npm run docs:inventory` | Documentation manifest remains valid. | Passed on release-prep branch. | +| Release metadata preflight | `npm run release:preflight` | Lock-step workspace metadata is valid. | Passed on release-prep branch and final-main release commit. | +| Docs inventory | `npm run docs:inventory` | Documentation manifest remains valid. | Passed on release-prep branch and final-main release commit. | | Dev-tooling dependency audit | `npm audit --audit-level=high` | Zero high or critical vulnerabilities across production and development dependencies, including dev-tooling packages such as `esbuild`. | Passed: `found 0 vulnerabilities`. | -| Runtime dependency audit | `npm audit --omit=dev --audit-level=high` | Zero high or critical runtime vulnerabilities. | Passed: `found 0 vulnerabilities`. | +| Runtime dependency audit | `npm audit --omit=dev --audit-level=high` | Zero high or critical runtime vulnerabilities. | Passed on release-prep branch and final-main release commit: `found 0 vulnerabilities`. | | Focused roadmap proof | `npx vitest run --config vitest.config.ts tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts tests/cycles/WF-130/roadmap-goalpost-policy.part02.test.ts tests/cycles/WF-130/roadmap-goalpost-policy.part03.test.ts` | Roadmap snapshot, release posture, Beyond count, and Markdown policy are self-consistent. | Passed on release-prep branch. | -| Release gauntlet | `npm run release:readiness` | Local release-readiness gauntlet passes without live milestone checks. | Covered by the milestone-aware release-readiness pass on release-prep branch. | -| Milestone-aware readiness | `npm run release:readiness -- --milestone v7.2.0` | Blocks until the target milestone has zero open tracker items, including issues or pull requests, and no WIP labels. | Passed on release-prep branch on 2026-07-05; final-main must rerun it before tagging. | +| Release gauntlet | `npm run release:readiness` | Local release-readiness gauntlet passes without live milestone checks. | Passed on release-gate and release-prep lineage. | +| Milestone-aware readiness | `npm run release:readiness -- --milestone v7.2.0` | Blocks until the target milestone has zero open tracker items, including issues or pull requests, and no WIP labels. | Passed on release-prep branch and final-main release commit on 2026-07-05. | +| Release Dry Run | GitHub Actions run `28736681371` | Packed files, publish dry-runs, DOGFOOD smokes, and release evidence stay green from `main`. | Passed before tag creation. | +| Tag Guard | GitHub Actions run `28736930947` | The pushed tag resolves to the intended release commit and metadata is valid. | Passed after `v7.2.0` tag push. | +| Publish workflow | GitHub Actions run `28736930944` | Automated npm publishing succeeds for every workspace package. | Publish workflow passed on 2026-07-05. | +| Tag CI | GitHub Actions run `28736930919` | The tag build/test lane succeeds. | Passed after `v7.2.0` tag push. | +| GitHub Release | | Release notes are published for the public tag. | Published on 2026-07-05. | +| npm registry verification | `npm view version dist-tags --json` | Every automated package reports version `7.2.0` with `latest`. | npm registry verification passed for every automated package. | ## Human Review Matrix @@ -274,8 +286,8 @@ disposition. | `docs/CHANGELOG.md` | v7.2 framework input, mouse tracking, DOGFOOD demo integrity, Code Dojo, and security changes now live under the dated `7.2.0` boundary. | | `README.md` | Front-door What's New now describes v7.2.0 and links to the v7.2 release docs. | | `docs/ROADMAP.md` | Updated on 2026-07-05 from GitHub milestone state: v7.2 has zero open and seventeen closed milestone items, Beyond has 39 open items, and v8 is staged separately. | -| `docs/BEARING.md` | Updated so the next target is final v7.2 release prep and the next feature horizon is V8. | -| `docs/releases/7.2.0/README.md` | This packet records release-prep evidence and the remaining final-main checks. | +| `docs/BEARING.md` | Updated after release so the next target is #457 and the next feature horizon is V8. | +| `docs/releases/7.2.0/README.md` | This packet records release-prep, final-main, tag, publish, GitHub Release, and npm registry evidence. | | `docs/releases/7.2.0/whats-new.md` | Versioned v7.2 release overview is ready for DOGFOOD and public release docs. | | `docs/releases/7.2.0/migration-guide.md` | Versioned v7.2 migration guidance is ready for DOGFOOD and public release docs. | | Package READMEs | No package front-door API positioning was changed by this release-gate branch. | @@ -283,8 +295,8 @@ disposition. ## Package And Registry Verification Plan -The release-prep PR performs the package metadata mutation and must validate -the resulting branch before it merges: +The release-prep PR performed the package metadata mutation and validated the +resulting branch before it merged: ```bash npm run version 7.2.0 @@ -295,13 +307,15 @@ npm audit --audit-level=high npm run release:readiness -- --milestone v7.2.0 ``` -The **Release Dry Run** workflow must run against the release-prep branch or PR -commit before the release PR merges. That dry run is the current authoritative -packed-file and npm publish dry-run evidence for the automated publish matrix. +The **Release Dry Run** workflow ran against release-prep before merge and +again from final `main` before tag creation. The final-main run + is the +authoritative packed-file and npm publish dry-run evidence for the automated +publish matrix. -After the release-prep PR merges and local `main` exactly matches -`origin/main`, final tag preparation must replay the metadata and docs checks -from that merged commit: +After the release-prep PR merged and local `main` exactly matched +`origin/main`, final tag preparation replayed the metadata and docs checks from +the merged commit: ```bash git fetch origin main --tags --prune @@ -314,8 +328,9 @@ npm run release:preflight npm run docs:inventory ``` -After the `v7.2.0` tag is pushed and the publish workflow passes, verify every -published package resolves to version `7.2.0` with the stable `latest` dist-tag: +After the `v7.2.0` tag was pushed and the publish workflow passed, registry +verification confirmed every published package resolves to version `7.2.0` +with the stable `latest` dist-tag: ```bash npm view @flyingrobots/bijou version dist-tags --json @@ -330,13 +345,37 @@ npm view @flyingrobots/bijou-i18n-tools-xlsx version dist-tags --json npm view @flyingrobots/bijou-mcp version dist-tags --json ``` +## Release-Time Registry Snapshot + +The table below is the immutable release evidence. It records the registry +state observed during post-publish verification on 2026-07-05 after Release +workflow run `28736930944` completed at `2026-07-05T10:03:04Z` from release +commit `123f4a6150963932118cbf763a8a6ec03487e227`. The `npm view` commands +above are operational replay aids and may report a later `latest` value after a +future release; this table is the historical `v7.2.0` snapshot. + +| Package | Observed version | Observed `latest` dist-tag | +| :--- | :--- | :--- | +| `@flyingrobots/bijou` | `7.2.0` | `7.2.0` | +| `@flyingrobots/bijou-node` | `7.2.0` | `7.2.0` | +| `@flyingrobots/bijou-tui` | `7.2.0` | `7.2.0` | +| `@flyingrobots/bijou-tui-app` | `7.2.0` | `7.2.0` | +| `create-bijou-tui-app` | `7.2.0` | `7.2.0` | +| `@flyingrobots/bijou-i18n` | `7.2.0` | `7.2.0` | +| `@flyingrobots/bijou-i18n-tools` | `7.2.0` | `7.2.0` | +| `@flyingrobots/bijou-i18n-tools-node` | `7.2.0` | `7.2.0` | +| `@flyingrobots/bijou-i18n-tools-xlsx` | `7.2.0` | `7.2.0` | +| `@flyingrobots/bijou-mcp` | `7.2.0` | `7.2.0` | + Tag creation, publish automation, npm registry verification, and GitHub Release -verification remain final-main work. They must not run from the release-prep -branch before it has merged. +verification all ran from the merged release commit after the release-prep +branch landed. The public release is +. ## Deterministic Reproducibility -All branch-local claims above are replayable from the branch tip with: +All historical release-prep claims above are replayable from the release-prep +branch tip with: ```bash npm run release:preflight @@ -347,7 +386,7 @@ npx vitest run --config vitest.config.ts tests/cycles/WF-130/roadmap-goalpost-po npm run release:readiness ``` -Before the public tag is created from merged `main`, run: +The public tag was created only after the final merged `main` checks passed: ```bash npm run release:preflight @@ -357,14 +396,11 @@ npm audit --audit-level=high npm audit --omit=dev --audit-level=high ``` -The final tag must be created only after #354 is closed, the release-prep PR -has merged, the local checkout is clean, `main` exactly matches `origin/main`, -and CI / Release Dry Run evidence is green. +The final tag was created after #354 closed, the release-prep PR merged, the +local checkout was clean, `main` exactly matched `origin/main`, and CI / +Release Dry Run evidence was green. ## Residual Risk -- The release-prep branch intentionally does not create or push `v7.2.0`. -- The Release Dry Run workflow, final tag, publish workflow, npm registry - verification, and GitHub Release verification remain final-main work. - Code Dojo debt remains tracked by ratcheting baselines. This release improves enforcement and lowers debt, but does not claim zero standards debt. diff --git a/docs/releases/7.2.0/migration-guide.md b/docs/releases/7.2.0/migration-guide.md index a11edc32..4593ecb4 100644 --- a/docs/releases/7.2.0/migration-guide.md +++ b/docs/releases/7.2.0/migration-guide.md @@ -3,9 +3,8 @@ Bijou 7.2.0 is a minor release from 7.1.0. It is intended to be additive for applications using documented public APIs. -The public tag is created only after the release-prep branch merges and -final-main validation passes. These instructions are the versioned migration -guide for the 7.2.0 package set. +The public tag was created from the verified 2026-07-05 `main` release commit. +These instructions are the versioned migration guide for the 7.2.0 package set. ## Recommended Upgrade @@ -59,17 +58,18 @@ when preparing or validating a release branch. ## Release Tooling -Maintainers preparing the release should use both release-readiness modes: +Maintainers replaying or auditing the release should use both release-readiness +modes: ```bash npm run release:readiness npm run release:readiness -- --milestone v7.2.0 ``` -The plain command validates local release evidence before the milestone is -closed. The milestone-aware command is the final release gate and must pass -after the release-prep PR has merged, the target milestone has zero open -tracker items, and no tracked work carries a `work-in-progress` label. +The plain command validates local release evidence without live milestone +checks. The milestone-aware command is the release gate that passed from the +merged `main` release commit after the target milestone had zero open tracker +items and no tracked work carried a `work-in-progress` label. ## Compatibility Stance diff --git a/docs/releases/7.2.0/whats-new.md b/docs/releases/7.2.0/whats-new.md index 62b56dbd..1c5c358e 100644 --- a/docs/releases/7.2.0/whats-new.md +++ b/docs/releases/7.2.0/whats-new.md @@ -5,9 +5,9 @@ surface. It keeps the public Runtime Graph direction intentionally narrow while tightening framework input behavior, DOGFOOD readability, Blocks documentation, release evidence, and dependency review. -The public tag is created only after the release-prep branch merges and -final-main validation passes. This document is the versioned release overview -DOGFOOD and the repository front door use for 7.2.0. +The public tag was created from the verified 2026-07-05 `main` release commit. +This document is the versioned release overview DOGFOOD and the repository +front door use for 7.2.0. ## Framework Input Stabilization @@ -56,8 +56,8 @@ security audit scope, registry verification, release-readiness posture, and residual risk. Maintainers should treat the release evidence packet as the authoritative 7.2 -release-prep checklist until the final tag is created from the merged -`origin/main` release commit. +release record: it includes the public GitHub Release, final-main validation, +publish workflow, tag CI, Tag Guard, and npm registry verification evidence. ## V8 Posture diff --git a/tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts b/tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts index 5f24f731..5b0d7b22 100644 --- a/tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts +++ b/tests/cycles/WF-130/roadmap-goalpost-policy.part01.test.ts @@ -37,6 +37,7 @@ describe('WF-130 roadmap goalpost policy', () => { const bearing = normalizeWhitespace(read('docs/BEARING.md')); const releaseRunbook = normalizeWhitespace(read('docs/release.md')); const dx046Design = normalizeWhitespace(read('docs/design/DX-046-graphql-authored-dogfood-block-fixture.md')); + const dx048Design = normalizeWhitespace(read('docs/design/DX-048-v8-runtime-graph-scene-ir-contract.md')); expect(roadmap).toContain('Last synced from GitHub milestone items: 2026-07-05.'); expect(roadmap).toContain('The latest shipped public release is'); @@ -66,6 +67,7 @@ describe('WF-130 roadmap goalpost policy', () => { expect(roadmap).toContain('`Beyond`'); expect(roadmap).toContain('39 | 6'); expect(roadmap).toContain('Next Pull'); + expect(roadmap).toContain('[`DX-048`](./design/DX-048-v8-runtime-graph-scene-ir-contract.md)'); expect(roadmap).toContain('Runtime Graph and Scene IR product contract'); expect(roadmap).toContain('VISOR'); expect(roadmap).toContain('#335'); @@ -111,12 +113,13 @@ describe('WF-130 roadmap goalpost policy', () => { expect(roadmap).not.toContain('Workflow, Capture, And CI Determinism'); expect(bearing).toContain('The latest shipped public release is `v7.2.0`'); expect(bearing).toContain('The next feature horizon remains `v8.0.0`'); - expect(bearing).toContain('the immediate `v7.2.0` focus is final release prep'); + expect(bearing).toContain('the immediate target is #457: shape the V8 Runtime Graph and Scene IR product contract'); expect(bearing).toContain('`v7.2.0` completed as a narrow stabilization and demo-integrity release'); expect(bearing).toContain('`v7.2.0` milestone is complete release lineage: 0 open and 17 closed milestone items'); expect(bearing).toContain('`v8.0.0` milestone is staged as the next feature horizon: 3 open and 0 closed milestone items'); expect(bearing).toContain('The selected `v7.2.0` DOGFOOD product pull #335 has landed'); expect(bearing).toContain('Shape V8 And V9 From Beyond'); + expect(bearing).not.toContain('final-main tag validation'); expect(bearing).not.toContain('The next selected product pull after that gate is DX-047'); expect(bearing).not.toContain('The next release-facing action is release-readiness validation'); @@ -129,6 +132,15 @@ describe('WF-130 roadmap goalpost policy', () => { expect(dx046Design).toContain('Parent tracker: [#302](https://github.com/flyingrobots/bijou/issues/302)'); expect(dx046Design).toContain('NavigationListBlock'); expect(dx046Design).toContain('Tests To Write First'); + + expect(dx048Design).toContain('Goalpost tracker: [#457](https://github.com/flyingrobots/bijou/issues/457)'); + expect(dx048Design).toContain('GraphQL Blocks source model'); + expect(dx048Design).toContain('`bijou-block/1` artifact semantics'); + expect(dx048Design).toContain('`ui-scene-ir/1` lowering contract'); + expect(dx048Design).toContain('receipt and source-map ownership'); + expect(dx048Design).toContain('DOGFOOD round-trip fixture'); + expect(dx048Design).toContain('[flyingrobots/visor](https://github.com/flyingrobots/visor)'); + expect(dx048Design).not.toContain('VISOR coordination surface: https://github.com/flyingrobots/visor'); }); }); diff --git a/tests/cycles/WF-130/roadmap-goalpost-policy.part03.test.ts b/tests/cycles/WF-130/roadmap-goalpost-policy.part03.test.ts index f5e0b9a3..08a24ddb 100644 --- a/tests/cycles/WF-130/roadmap-goalpost-policy.part03.test.ts +++ b/tests/cycles/WF-130/roadmap-goalpost-policy.part03.test.ts @@ -102,13 +102,22 @@ describe('WF-130 roadmap goalpost policy', () => { expect(releasePacket).toContain('## Package And Registry Verification Plan'); expect(releasePacket).toContain('npm run version 7.2.0'); expect(releasePacket).toContain('Release Dry Run'); - expect(releasePacket).toMatch( - /Tag creation, publish automation, npm registry\s+verification, and GitHub Release\s+verification remain final-main work/, + expect(releasePacket).toContain('https://github.com/flyingrobots/bijou/releases/tag/v7.2.0'); + expect(releasePacket).toContain('Publish workflow passed on 2026-07-05'); + expect(releasePacket).toContain('npm registry verification passed for every automated package'); + expect(releasePacket).toContain('## Release-Time Registry Snapshot'); + expect(releasePacket).toContain( + 'workflow run `28736930944` completed at `2026-07-05T10:03:04Z`', ); + expect(releasePacket).toContain('The `npm view` commands'); + expect(releasePacket).toContain('may report a later `latest` value'); + expect(releasePacket).not.toContain('pending final-main release step'); + expect(releasePacket).not.toContain('verification remain final-main work'); expect(releasePacket).not.toContain('The version bump, final release dry run, tag creation'); for (const packageName of publishedPackages) { expect(releasePacket).toContain(`npm view ${packageName} version dist-tags --json`); + expect(releasePacket).toContain(`| \`${packageName}\` | \`7.2.0\` | \`7.2.0\` |`); } });