diff --git a/docs/program/README.md b/docs/program/README.md new file mode 100644 index 0000000..4a30523 --- /dev/null +++ b/docs/program/README.md @@ -0,0 +1,13 @@ +# Program documents + +Release-completion program documents for Braid, seeded on the `factory/release-completion` +branch from the verified baseline (main `3d7b79f` = tag `v0.1.3` = npm `0.1.3`). + +- `braid-VISION.md` — the release-completion VISION with numbered priorities P1–P6. +- `braid-PROGRAM-MAP.md` — the program map: verified baseline, node assignments, and the + final `swe-final-integration-pr` node that flips the draft PR to ready. + +Both were reconstructed from `README.md`, `docs/08-verification.md`, and +`docs/09-delivery-plan.md` evidence because the round-1 originals were not handed to this arm. +Completion authority remains `docs/08-verification.md` and `docs/09-delivery-plan.md` +(`AGENTS.md:71`). diff --git a/docs/program/braid-PROGRAM-MAP.md b/docs/program/braid-PROGRAM-MAP.md new file mode 100644 index 0000000..390606c --- /dev/null +++ b/docs/program/braid-PROGRAM-MAP.md @@ -0,0 +1,31 @@ +# Braid release-completion program map + +> **Reconstruction notice.** This map was reconstructed by the N1 seeding arm from `README.md`, +> `docs/08-verification.md`, and `docs/09-delivery-plan.md` evidence, because the round-1 +> original program documents were not handed to this arm. Completion authority remains +> `docs/08-verification.md` and `docs/09-delivery-plan.md` (`AGENTS.md:71`); priorities are +> defined in `braid-VISION.md`. + +**Verified baseline:** tangle-network/braid main `3d7b79f` = tag `v0.1.3` = npm `0.1.3`; +warmup PR pipeline proven on agent-knowledge#140: PR #142 merged. + +## Nodes + +| Node | Arm | Mandate | VISION priorities | +| --- | --- | --- | --- | +| N1 | This arm (seed `factory/release-completion`) | Seed the integration branch from the pinned base `3d7b79f`, reconstruct and commit the program documents (`docs/program/`), and open the standing **draft** PR. | P4+P1 | +| N2 | Live-matrix arm | Close `LIVE-01`–`LIVE-12` with real-provider records and confirmed cleanup: strict bridge gate `pnpm test:live:bridge:release` (`LIVE-01`–`LIVE-05`), Tangle inference/sandbox/interaction/fork/confidential rows, supervisor, and `agent-eval` analysis; run the retained-sandbox canary-plus-cohort; resolve or honestly route the CLI Bridge issue 130 aggregate-run blocker (`docs/08-verification.md:360-425`, `:383-413`, `:423`, `:479-492`). | P2 | +| N3 | Measurement arm | Land the full `PERF-01`–`PERF-10` distributions (W12) and the calibrated `EVAL-01`–`EVAL-06` judge records (11-of-12 calibration, trivial baselines rejected) so VR-03/VR-07/VR-09 hold for the exact build (`docs/08-verification.md:318-350`, `:516-547`, `:600-611`, `:740`). | P3 | +| N4 | Publication arm | Execute W13 on the frozen main commit: `pnpm check`, `pnpm release:prepare`, isolated code-free Ed25519 endorsement, npm publish with provenance, registry smoke on Linux x64 and macOS arm64, publication record, tag (`docs/09-delivery-plan.md:396-428`; `docs/08-verification.md:352-358`, `:627-639`, `:694-696`). | P5 | +| N5 | Audit-close arm | Assemble the comprehensive audit on demand (not an npm prerequisite), confirm zero unresolved externally billable live resources, and walk the final definition of done (`docs/08-verification.md:615-720`; `docs/09-delivery-plan.md:489-505`). | P6 | +| Final | `swe-final-integration-pr` | Flip the N1 draft PR to ready and merge it into `main` once N2–N5 land. **The draft stays draft until this node.** | P4 | + +## Rules + +- The base is pinned at the charter sha `3d7b79f`; every arm rebases cleanly on `origin/main` + before landing (freeze only after all feature changes merge, `docs/09-delivery-plan.md:467`). +- Every arm keeps `pnpm check` green on the branch (`README.md:296-316`). +- An unavailable required live provider blocks the release and is reported unavailable — never + skipped or simulated (`docs/08-verification.md:381`). +- No requirement identifier is marked complete without exact-build evidence + (`docs/08-verification.md:789`, VR-01). diff --git a/docs/program/braid-VISION.md b/docs/program/braid-VISION.md new file mode 100644 index 0000000..2505202 --- /dev/null +++ b/docs/program/braid-VISION.md @@ -0,0 +1,124 @@ +# Braid release-completion VISION + +> **Reconstruction notice.** This document was reconstructed by the N1 seeding arm from +> `README.md`, `docs/08-verification.md`, and `docs/09-delivery-plan.md` evidence, because the +> round-1 original program documents were not handed to this arm. Where a claim below rests on +> repository evidence, the source file and line range are cited. Completion authority is not +> this document: per `AGENTS.md:71`, release completion is defined only by +> `docs/08-verification.md` and `docs/09-delivery-plan.md`. + +## Completion frame + +Braid is complete only when one immutable release build passes every required check and one +machine-readable evidence manifest links each requirement identifier to reproducible evidence +(`docs/08-verification.md:3-15`), and the work is complete only at package publication and +post-publication verification (`docs/09-delivery-plan.md:3-9`). The final definition of done is +the checklist at `docs/09-delivery-plan.md:489-505`. This VISION orders the remaining work into +numbered priorities; the program map in `braid-PROGRAM-MAP.md` assigns arms to them. + +## Priorities + +### P1 — Program baseline and scaffolding (executed by this arm) + +Seed the `factory/release-completion` integration branch from the verified baseline +(main `3d7b79f` = tag `v0.1.3` = npm `0.1.3`) and reconstruct the program documents from +repository evidence before any release-completion arm launches. + +- Evidence: the verification plan and the delivery plan are the proof authorities the README + points to (`README.md:312-314`); `AGENTS.md:71` pins those two documents as the only + definition of release completion; `docs/09-delivery-plan.md:457` requires the audit verifier + to extract required identifiers from the committed specification, so the specification-side + program documents must exist and stay grounded in that committed evidence. +- Done when: the branch exists at the pinned base, the three `docs/program/` files are + committed with the reconstruction note, and the draft PR is open. + +### P2 — Complete the required live matrix `LIVE-01`–`LIVE-12` + +Close the gap between what the current observations prove and what the required live matrix +demands. The 2026-08-09 core-path observations explicitly "do not claim the broader +interaction, tool, replay-cursor, cancellation, Tangle, or analysis rows in the required live +matrix" (`docs/08-verification.md:415-425`); the 2026-08-15 retained cohort satisfies only the +retained create, process-loss recovery, replay, cancellation, and cleanup parts of `LIVE-07` +(`docs/08-verification.md:445-477`). + +- Evidence: the full matrix `LIVE-01`–`LIVE-12` at `docs/08-verification.md:360-381`; a + required live provider that is unavailable blocks the release rather than being reported + skipped or simulated (`docs/08-verification.md:381`); the strict bridge gate is + `pnpm test:live:bridge:release` for `LIVE-01`–`LIVE-05`, which "narrower bridge smoke cannot + satisfy" (`docs/08-verification.md:744`); the retained-sandbox canary-plus-cohort command is + defined at `docs/08-verification.md:383-413`; runner conformance flow before any interactive + advertisement at `docs/08-verification.md:479-492`; the known aggregate-run blocker is + CLI Bridge issue 130 (`docs/08-verification.md:423`), an upstream defect this arm family + must resolve or route around honestly, not approximate. +- Done when: every `LIVE-*` identifier maps to a passing real-provider record with complete + provenance and confirmed cleanup (`docs/08-verification.md:310-314`, VR-04 at + `docs/08-verification.md:792`). + +### P3 — Land the measured verification planes: `PERF-01`–`PERF-10` and `EVAL-01`–`EVAL-06` + +The full performance matrix lands in W12 (`docs/08-verification.md:740`): all ten targets with +complete distributions, warm/cold separation, and both reference machines +(`docs/08-verification.md:516-547`; VR-07). Semantic evaluation requires the calibrated judge +(11-of-12 paired preference, trivial baselines rejected) before the six release cases are +admissible (`docs/08-verification.md:318-350`, `:600-611`; VR-09). + +- Evidence: report-shape requirements at `docs/08-verification.md:520-528`; target-change rule + requiring a decision record at `docs/08-verification.md:545`; requirement ownership placing + `PERF-*` in W12 and `EVAL-*` in W11 (`docs/09-delivery-plan.md:452-453`). +- Done when: VR-03, VR-07, and VR-09 pass for the exact release build + (`docs/08-verification.md:791-797`). + +### P4 — One sustained integration draft PR, flipped ready only at the final node (executed by this arm) + +The release-completion program lands on a single `factory/release-completion` integration PR +opened as a draft by this arm. The release candidate is frozen only after all feature changes +merge (`docs/09-delivery-plan.md:467`), and the program publishes only that frozen digest +(`docs/09-delivery-plan.md:468`), so the draft stays draft until the final integration node +(`swe-final-integration-pr`) flips it to ready. Every arm keeps the branch rebased clean on +`origin/main`; the base is pinned at the verified baseline `3d7b79f`. + +- Evidence: upstream PR and release order at `docs/09-delivery-plan.md:459-473`; every push + receives current CI and review reinspection before the package is treated as ready + (`docs/09-delivery-plan.md:473`); `README.md:296-316` defines the development proof + (`pnpm check`) every push must keep green. +- Done when: `swe-final-integration-pr` flips this draft to ready and it merges into `main`. + +### P5 — W13 publication: build, endorse, publish, verify from the registry + +Execute the direct acceptance path: `pnpm check` once on the exact main commit, build one +immutable package with `pnpm release:prepare`, endorse that exact package and manifest in an +isolated code-free Ed25519 job, publish `@tangle-network/braid` with npm provenance, repeat +the post-publication smoke from the registry on Linux x64 and macOS arm64, validate the four +platform records plus provenance in one publication record, endorse the fixed bundle, and only +then tag. + +- Evidence: W13 deliverables and done-when at `docs/09-delivery-plan.md:396-428`; Layer 9 + installation and release checks at `docs/08-verification.md:352-358`; publication direct + acceptance path and endorsement keys pinned in `release/endorsement-public-key.pem` at + `docs/08-verification.md:627-639` and `:694-696`; VR-10 registry-matches-candidate rule at + `docs/08-verification.md:798`; supported targets are Linux x64 and macOS arm64 + (`README.md:32`), and the package rejects Windows until encrypted state meets the required + path-race boundary there (`README.md:34`) — Windows stays out of scope for this release. +- Done when: the W13 done-when checklist passes (`docs/09-delivery-plan.md:418-428`). + +### P6 — Close the audit and cleanup ledger + +Assemble the comprehensive audit manifest on demand (it is available when a product decision +needs every requirement record in one manifest and is not an npm publication prerequisite, +`docs/08-verification.md:615-617`), confirm every live resource is cleaned up — the release +cannot complete with an unresolved externally billable test resource +(`docs/08-verification.md:718-720`) — and walk the final definition of done +(`docs/09-delivery-plan.md:489-505`) with no unresolved critical or high finding. + +- Evidence: manifest shape and verifier rules at `docs/08-verification.md:641-717`; rollback + and failure policy at `docs/09-delivery-plan.md:475-487` (a publication failure stops before + tag and preserves the approved candidate, `docs/09-delivery-plan.md:481`). +- Done when: the final definition of done holds line by line + (`docs/09-delivery-plan.md:489-505`). + +## Priority order and this arm's mandate + +Priorities are ordered by dependency, not by importance: P1 scaffolds the program, P2 and P3 +close the evidence planes, P4 is the standing integration vehicle, P5 publishes, P6 closes the +ledger. **This arm executes P4+P1** — it seeds the branch, the documents, and the standing +draft PR. Subsequent arms are assigned in `braid-PROGRAM-MAP.md`.