@kungfu-tech/buildchain 3.0.3-alpha.0 → 3.0.3-alpha.2

package/docs/publication-authority.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-07-15
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -212,7 +212,7 @@ providers select an explicit adapter:
 ```bash
 buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
-  --branch dev/v2/v2.12 \
+  --branch dev/v3/v3.0 \
   --source-sha <exact-merged-branch-sha> \
   --workflow .github/workflows/release-candidate-promote.yml \
   --workflow-ref <exact-buildchain-sha> \
@@ -223,7 +223,7 @@ buildchain audit publication-control-plane \
 # Optional stronger external evidence; generate the JSON outside the workflow.
 buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
-  --branch dev/v2/v2.12 \
+  --branch dev/v3/v3.0 \
   --workflow .github/workflows/release-candidate-promote.yml \
   --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \
   --job promote \
@@ -232,7 +232,7 @@ buildchain audit publication-control-plane \
 
 buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
-  --branch release/v2/v2.12 \
+  --branch release/v3/v3.0 \
   --workflow .github/workflows/.binary-release-assets.yml \
   --job publish \
   --environment buildchain-release-assets \

package/docs/publish-transaction.md

@@ -1,3 +1,21 @@
+---
+status: active
+period: ongoing
+theme: buildchain-publish-transaction
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Publish Transaction
 
 Buildchain release promotion is not just tag movement. A release can also publish
@@ -7,7 +25,7 @@ than Git refs because most registries are append-only: a failed rerun must know
 which artifacts already exist, which are still missing, and whether any existing
 artifact conflicts with the release material.
 
-Buildchain v2 models that work as a release transaction.
+Buildchain v3 models that work as a release transaction.
 
 ## Why This Exists
 
@@ -47,6 +65,7 @@ The branch contains:
 ```text
 state.json
 evidence.json   # present after publish evidence exists
+sealed-bundle/<candidate-root>/files/**  # present for build-once publication
 ```
 
 The local `.buildchain/release-state/...` and
@@ -62,6 +81,16 @@ for transient service failures such as HTTP 5xx responses, connection resets,
 timeouts, and "other side closed" socket failures. If the durable write still
 cannot be persisted after retries, the action fails closed.
 
+For a sealed publication, `state.json` also carries the typed sealed-bundle
+manifest, its candidate root, publication milestones, stable
+`publication_state`, and an exact resume command. The durable ref stores every
+declared bundle file as binary Git blobs before the publish lifecycle starts.
+A fresh runner restores those blobs into
+`.buildchain/recovered-publication/<version>/`, verifies every size and SHA-256
+against the manifest, and only then supplies the recovered paths to the publish
+lifecycle. A missing or changed tarball, PDF, source bundle, or manifest fails
+before registry publication.
+
 Durable release-state refs reserve their exact version even when the public exact
 tag was never created. If a later machine run sees a failed or repair-required
 state for `vX.Y.Z-alpha.N` and cannot resume it with the same transaction
@@ -103,6 +132,10 @@ BUILDCHAIN_RELEASE_SHA
 BUILDCHAIN_RELEASE_MATERIAL_SHA
 BUILDCHAIN_PUBLISH_TOOLING_SHA
 BUILDCHAIN_PUBLISH_EVIDENCE
+BUILDCHAIN_SEALED_BUNDLE_ROOT
+BUILDCHAIN_SEALED_NPM_TARBALL
+BUILDCHAIN_SEALED_NPM_INTEGRITY
+BUILDCHAIN_SEALED_NPM_SHA256
 BUILDCHAIN_REQUIRED_ARTIFACTS
 BUILDCHAIN_PUBLISH_MODE
 BUILDCHAIN_PUBLISH_AUTH
@@ -121,7 +154,8 @@ command = "node scripts/npm-publish-transaction.mjs"
 That script validates that `package.json` matches `BUILDCHAIN_VERSION`, runs
 `npm publish --access public --tag <BUILDCHAIN_NPM_DIST_TAG>` through npm Trusted
 Publishing, and writes npm artifact evidence before the promotion action moves
-public refs.
+public refs. When the sealed npm variables are present, the script verifies and
+publishes that exact `.tgz` file. It does not run `npm pack` again.
 
 `BUILDCHAIN_RELEASE_MATERIAL_SHA` is the source material whose artifacts must
 match. `BUILDCHAIN_PUBLISH_TOOLING_SHA` identifies the publishing code. A repair
@@ -253,7 +287,7 @@ fields and required artifact identities before final refs move.
   "channel": "release",
   "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   "release_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
-  "target_ref": "release/v2/v2.0",
+  "target_ref": "release/v3/v3.0",
   "release_material_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
   "publish_tooling_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
   "artifacts": [
@@ -323,33 +357,42 @@ however they need, as long as they emit the common evidence contract.
 The state machine is:
 
 ```text
-prepared -> publishing -> published -> finalizing -> complete
-                    |            |            |
-                    v            v            v
-              publish_failed  repair_required failed_permanently
-                    |
-                    v
-                abandoned
+prepared -> sealed -> publishing -> published -> finalizing -> complete
+                          |            |            |
+                          v            v            v
+                    publish_failed  repair_required failed_permanently
+                          |
+                          v
+                      abandoned
 ```
 
 Supported states:
 
-| State | Meaning |
-| --- | --- |
-| `prepared` | Transaction identity was created, but publish has not started. |
-| `publishing` | Publish lifecycle is running or may have been interrupted. |
-| `publish_failed` | Publish command failed before valid evidence was produced. |
-| `published` | Evidence is valid; refs have not necessarily finalized. |
-| `finalizing` | Buildchain is moving exact/floating refs or needs a later run to do it. |
-| `complete` | Required evidence is valid and refs have finalized. |
-| `repair_required` | Existing evidence or artifact state conflicts with expected release material. |
-| `abandoned` | A human or controlled process abandoned this transaction, usually because a newer version supersedes it. |
-| `failed_permanently` | Recovery should not continue without explicit override. |
+| State                | Meaning                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `prepared`           | Transaction identity was created, but publish has not started.                                           |
+| `sealed`             | Exact candidate bytes and manifest are verified and durable; registry publication has not started.       |
+| `publishing`         | Publish lifecycle is running or may have been interrupted.                                               |
+| `publish_failed`     | Publish command failed before valid evidence was produced.                                               |
+| `published`          | Evidence is valid; refs have not necessarily finalized.                                                  |
+| `finalizing`         | Buildchain is moving exact/floating refs or needs a later run to do it.                                  |
+| `complete`           | Required evidence is valid and refs have finalized.                                                      |
+| `repair_required`    | Existing evidence or artifact state conflicts with expected release material.                            |
+| `abandoned`          | A human or controlled process abandoned this transaction, usually because a newer version supersedes it. |
+| `failed_permanently` | Recovery should not continue without explicit override.                                                  |
 
 `repair_required`, `abandoned`, and `failed_permanently` fail closed unless the
 operator passes an explicit override. That override is for controlled repair
 runs, not normal retry behavior.
 
+`publication_state` is a stable operator-facing projection over the detailed
+transaction state. Its successful progression is
+`prepared -> sealed -> package-published -> alpha-complete` for Alpha or
+`release-complete` for stable release. If npm succeeds but GitHub Release work
+is interrupted, the durable record remains `package-published`; the next run
+reuses the exact npm evidence and sealed release assets instead of rebuilding
+or republishing them.
+
 ## Ref Ordering
 
 When publish transactions are enabled, promotion order is:
@@ -357,11 +400,15 @@ When publish transactions are enabled, promotion order is:
 1. verify target source and governance;
 2. create or reuse the version-state release commit;
 3. acquire or resume the release transaction;
-4. run `lifecycle.publish` or accept already-valid evidence;
-5. validate evidence and required artifacts;
-6. move exact release/prerelease tag;
-7. move floating tags and channel refs;
-8. mark the transaction `complete`.
+4. for build-once publication, verify and persist the complete sealed bundle;
+5. run `lifecycle.publish` from the exact sealed tarball or accept already-valid
+   evidence;
+6. validate evidence and required artifacts;
+7. move exact release/prerelease tag;
+8. move floating tags and channel refs;
+9. mark the transaction `complete`;
+10. create or update the GitHub Release from restored sealed assets and record
+    the `github_release` milestone.
 
 When a protected channel requires a generated version-state pull request, the
 first run can stop at `finalizing` after registry publication. If the reviewed
@@ -497,10 +544,10 @@ different SHA is a material conflict and blocks recovery.
 Local recovery commands operate on the same state/evidence files:
 
 ```bash
-node scripts/release-transaction.mjs inspect --version v2.0.11
-node scripts/release-transaction.mjs recover --version v2.0.11
-node scripts/release-transaction.mjs finalize --version v2.0.11
-node scripts/release-transaction.mjs abort --version v2.0.11 --superseded-by v2.0.12
+node scripts/release-transaction.mjs inspect --version v3.0.2
+node scripts/release-transaction.mjs recover --version v3.0.2
+node scripts/release-transaction.mjs finalize --version v3.0.2
+node scripts/release-transaction.mjs abort --version v3.0.2 --superseded-by v3.0.3
 ```
 
 The CLI is a diagnostic and local repair surface. It reports the durable
@@ -517,7 +564,7 @@ When no state file exists, creation commands also require:
 --repository kungfu-systems/buildchain \
 --source-sha <sha> \
 --release-sha <sha> \
---target-ref release/v2/v2.0 \
+--target-ref release/v3/v3.0 \
 --channel release
 ```
 

package/docs/release-candidate.md

@@ -41,6 +41,21 @@ contains:
 - normalized platform matrix and artifact summaries;
 - the hash of the aggregate `build-summary.json`.
 
+## Initiative-family release evidence
+
+A consumer may pass `release-candidate-family-evidence-json` to the reusable
+build. Buildchain normalizes that value as
+`kungfu-buildchain-initiative-family-release-evidence/v1`, binds it into the
+candidate hash, and carries it unchanged into publication authority. The
+envelope can identify one Initiative family root plus the exact Initiative and
+Assignment responsible for the release; continuation evidence can also bind
+the previous family root.
+
+This is an adapter-edge release contract, not a second Work Control authority.
+The immutable native Family State v1 projection and the additive Family State
+v2 typed envelope remain owned by Kungfu. Buildchain only proves that the
+release candidate consumed the caller-supplied family evidence exactly.
+
 Promotion workflows that should not rebuild artifacts can enable:
 
 ```yaml
@@ -52,6 +67,10 @@ Promotion workflows that should not rebuild artifacts can enable:
     promote-only-release-candidate: "true"
     release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json
     release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json
+    release-candidate-family-evidence-required: "true"
+    release-candidate-family-evidence-root: sha256:<initiative-family-root>
+    release-candidate-family-initiative-id: 2026-07-30-example-initiative
+    release-candidate-family-assignment-id: 2026-07-30-example-release
 ```
 
 With `promote-only-release-candidate: "true"`, promotion fails before
@@ -82,6 +101,11 @@ other package as `role: platform`. Consumer workflows therefore stay
 declarative and do not need their own artifact download or publish-evidence
 generation scripts.
 
+When `release-candidate-family-evidence-required` is true, the promotion
+boundary additionally requires the exact family root and may require the
+Initiative and Assignment ids. Missing, mismatched, or source-drifted family
+evidence fails before version-state, release-state, tag, or branch mutation.
+
 Because a channel merge can trigger promotion before its PR-stage matrix has
 finished uploading evidence, the resolver waits up to ten minutes for the exact
 merged PR's successful workflow run and paired artifacts. Polling remains bound

package/docs/release-flow.md

@@ -1,6 +1,24 @@
+---
+status: active
+period: ongoing
+theme: buildchain-release-flow
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Release Flow Diagrams
 
-This document describes the Buildchain v2 branch, tag, and version-state flow.
+This document describes the Buildchain v3 branch, tag, and version-state flow.
 See [Release governance](release-governance.md) for the design rationale.
 
 ## Architecture
@@ -46,16 +64,16 @@ for the versioned policy and evidence contract.
 
 | Ref kind | Example | Mutability | Purpose |
 | --- | --- | --- | --- |
-| Development branch | `dev/v2/v2.0` | moves | next source state for a minor line |
-| Alpha branch | `alpha/v2/v2.0` | moves | latest test state for a minor line |
-| Release branch | `release/v2/v2.0` | moves | latest production state for a minor line |
+| Development branch | `dev/v3/v3.0` | moves | next source state for a minor line |
+| Alpha branch | `alpha/v3/v3.0` | moves | latest test state for a minor line |
+| Release branch | `release/v3/v3.0` | moves | latest production state for a minor line |
 | Major gate branch | `publish-gate/major` | moves | reviewed administrator gate for publishing the next major |
-| Exact alpha tag | `v2.0.3-alpha.0` | immutable | audit ref for one tested prerelease |
-| Exact release tag | `v2.0.2` | immutable | audit ref for one production release |
-| Floating alpha tag | `v2.0-alpha` | moves | latest test channel for a minor line |
-| Floating major alpha tag | `v2-alpha` | moves | latest test channel on the highest published alpha minor for a major line |
-| Floating minor tag | `v2.0` | moves | latest production patch on a minor line |
-| Floating major tag | `v2` | moves | selected stable major entrypoint |
+| Exact alpha tag | `v3.0.3-alpha.0` | immutable | audit ref for one tested prerelease |
+| Exact release tag | `v3.0.2` | immutable | audit ref for one production release |
+| Floating alpha tag | `v3.0-alpha` | moves | latest test channel for a minor line |
+| Floating major alpha tag | `v3-alpha` | moves | latest test channel on the highest published alpha minor for a major line |
+| Floating minor tag | `v3.0` | moves | latest production patch on a minor line |
+| Floating major tag | `v3` | moves | selected stable major entrypoint |
 
 ## Ref Protection Contract
 
@@ -69,16 +87,16 @@ refs/tags/v*.*.*
 ```
 
 Do not apply immutable-tag rulesets to every `refs/tags/v*` ref. Buildchain
-must be able to update floating channel tags such as `v2`, `v2.0`, `v2.0-alpha`,
-and `v2-alpha` after the exact tag and publish evidence are valid. A ruleset that
+must be able to update floating channel tags such as `v3`, `v3.0`, `v3.0-alpha`,
+and `v3-alpha` after the exact tag and publish evidence are valid. A ruleset that
 matches all `v*` tags also matches floating tags, so release finalization can
 fail with GitHub protected-ref errors even though the exact release tag and
 published artifacts are already durable.
 
 The intended governance split is:
 
-- exact tags such as `v2.0.14` and `v2.0.15-alpha.0` are immutable audit refs;
-- floating tags such as `v2`, `v2.0`, `v2.0-alpha`, and `v2-alpha` are mutable channel refs
+- exact tags such as `v3.0.2` and `v3.0.3-alpha.0` are immutable audit refs;
+- floating tags such as `v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` are mutable channel refs
   owned by the Buildchain promotion token;
 - protected branches still require reviewed channel PRs before Buildchain can
   move any exact or floating release refs.
@@ -94,17 +112,17 @@ The workflow is backed by the CLI command:
 
 ```bash
 buildchain release line open \
-  --major 2 \
-  --minor 10 \
-  --source-ref release/v2/v2.9 \
+  --major 3 \
+  --minor 1 \
+  --source-ref release/v3/v3.0 \
   --json
 ```
 
 When the workflow is run with `apply=true`, Buildchain:
 
-- writes the initial version-state commit, such as `2.10.0-alpha.0`;
-- creates `dev/v2/v2.10` from that commit;
-- creates `alpha/v2/v2.10` and `release/v2/v2.10` from the selected source ref;
+- writes the initial version-state commit, such as `3.1.0-alpha.0`;
+- creates `dev/v3/v3.1` from that commit;
+- creates `alpha/v3/v3.1` and `release/v3/v3.1` from the selected source ref;
 - applies branch protection with one approving review and the configured
   required status check; dev starts strict, while alpha and release also require
   the pair-specific `verify` aggregate without a source-up-to-date ancestry loop;
@@ -112,7 +130,7 @@ When the workflow is run with `apply=true`, Buildchain:
   the exact queue parameters and bypass actors from the current default dev
   branch when the policy is `inherit` or absent;
 - switches the repository default branch to the new dev line when requested;
-- opens the first `dev/v2/v2.10 -> alpha/v2/v2.10` channel PR when requested.
+- opens the first `dev/v3/v3.1 -> alpha/v3/v3.1` channel PR when requested.
 
 This makes minor-line creation a single audited operation. The channel PR still
 goes through the normal verify/review/promotion path before an alpha is
@@ -229,26 +247,26 @@ The same minor line can loop through this state machine many times.
 
 ## Version Examples
 
-Assume `v2.0.2-alpha.1` has been tested and a maintainer merges
-`alpha/v2/v2.0 -> release/v2/v2.0`.
+Assume `v3.0.2-alpha.1` has been tested and a maintainer merges
+`alpha/v3/v3.0 -> release/v3/v3.0`.
 
 Buildchain should produce:
 
 ```text
-v2.0.2                  exact production tag
-v2.0                    floating minor tag
-v2                      floating major tag when v2.0 is the selected major line
-release/v2/v2.0         production channel branch
+v3.0.2                  exact production tag
+v3.0                    floating minor tag
+v3                      floating major tag when v3.0 is the selected major line
+release/v3/v3.0         production channel branch
 ```
 
 It should also prepare:
 
 ```text
-v2.0.3-alpha.0          exact next alpha tag
-v2.0-alpha              floating alpha tag
-v2-alpha                floating major alpha tag when v2.0 is the highest published alpha minor
-alpha/v2/v2.0           alpha channel branch
-dev/v2/v2.0             development channel branch
+v3.0.3-alpha.0          exact next alpha tag
+v3.0-alpha              floating alpha tag
+v3-alpha                floating major alpha tag when v3.0 is the highest published alpha minor
+alpha/v3/v3.0           alpha channel branch
+dev/v3/v3.0             development channel branch
 ```
 
 This is expected behavior. A production release closes one patch and opens the

package/docs/release-governance.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-27
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -18,7 +18,7 @@ ai_provenance:
 
 # Release Governance
 
-Buildchain v2 preserves the release semantics of the older ABV workflow while
+Buildchain v3 preserves the release semantics of the older ABV workflow while
 moving the implementation into one modern repository.
 
 The central idea is simple: a reviewed merge into a release channel is the
@@ -37,9 +37,9 @@ Kungfu release automation has to keep four facts aligned:
 
 If any one of these facts is updated by hand, the system can split:
 
-- a consumer can fetch `v2.0` and receive a tree whose package version still
+- a consumer can fetch `v3.0` and receive a tree whose package version still
   says the previous release;
-- a maintainer can move `v2` without producing an exact `v2.0.N` audit tag;
+- a maintainer can move `v3` without producing an exact `v3.0.N` audit tag;
 - an alpha can be promoted to production even though the release tree is not the
   same tree that was tested;
 - a protected branch merge can succeed while the follow-up version commit is
@@ -70,7 +70,7 @@ repositories that usually meant changing `lerna.json` and/or `package.json`.
 That commit is important because the tag alone is not enough evidence: the
 source tree should also declare the version that the tag advertises.
 
-Buildchain v2 treats that as a hard semantic requirement for its own release
+Buildchain v3 treats that as a hard semantic requirement for its own release
 line.
 
 ## Buildchain Implementation
@@ -133,7 +133,7 @@ older Buildchain aggregate context, inspect the exact candidate SHA first:
 GH_TOKEN="$(gh auth token)" npx @kungfu-tech/buildchain@latest \
   release-governance reconcile \
   --repository kungfu-systems/example \
-  --branch release/v2/v2.14 \
+  --branch release/v3/v3.0 \
   --candidate-sha <tested-pr-head-sha> \
   --json
 ```
@@ -181,32 +181,32 @@ workflow preflight cannot receive a second set of publication side effects.
 ## Version Lines
 
 Kungfu uses Python-like version lines where a minor line can represent a
-long-lived product train. A line such as `v2.0` can produce many production
+long-lived product train. A line such as `v3.0` can produce many production
 patch releases:
 
 ```text
-v2.0.0
-v2.0.1
-v2.0.2
+v3.0.0
+v3.0.1
+v3.0.2
 ...
-v2.0.1234
+v3.0.1234
 ```
 
 This is why Buildchain maintains both exact and floating refs:
 
-- `v2.0.2` is immutable release evidence;
-- `v2.0` is the latest production release on the `2.0` line;
-- `v2` is the selected stable major-line entrypoint;
-- `v2.0.3-alpha.0` is immutable alpha evidence;
-- `v2.0-alpha` is the latest test channel for the `2.0` line.
-- `v3-alpha` is the latest test channel on the highest published alpha minor in major `2`.
+- `v3.0.2` is immutable release evidence;
+- `v3.0` is the latest production release on the `3.0` line;
+- `v3` is the selected stable major-line entrypoint;
+- `v3.0.3-alpha.0` is immutable alpha evidence;
+- `v3.0-alpha` is the latest test channel for the `3.0` line.
+- `v3-alpha` is the latest test channel on the highest published alpha minor in major `3`.
 
 A release does not mean "minor is complete." It means "this patch on this minor
 line is now production."
 
 GitHub repository rules must preserve that distinction. Exact tags such as
-`v2.0.2` and `v2.0.3-alpha.0` should be immutable. Floating channel tags such as
-`v2`, `v2.0`, `v2.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion
+`v3.0.2` and `v3.0.3-alpha.0` should be immutable. Floating channel tags such as
+`v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion
 token after governance checks and publish evidence pass. A tag ruleset that
 protects every `refs/tags/v*` ref is too broad because it also locks the
 floating channel tags that Buildchain is required to update. Prefer exact-tag
@@ -239,7 +239,7 @@ line-specific dist-tag `vX.Y-alpha` so they cannot roll the global `alpha`
 channel backward. Exact prerelease versions remain installable directly.
 
 This keeps the test channel self-describing. If a consumer checks out
-`v2.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major
+`v3.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major
 alpha ref removes routine consumer edits when Buildchain opens a newer minor,
 while exact tags and SHAs remain the reproducible audit choice.
 
@@ -248,7 +248,7 @@ while exact tags and SHAs remain the reproducible audit choice.
 Buildchain continuously consumes its own current major alpha through
 `.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the
 released channel router at `build.yml@v3-alpha`. The auto lane must resolve
-`v3-alpha`; the explicit stable lane must resolve `v2`. Both execute the same
+`v3-alpha`; the explicit stable lane must resolve `v3`. Both execute the same
 declared install, build, and verify fixture, proving that a single consumer
 surface routes to distinct released runtimes without duplicating lifecycle
 configuration in the consumer.
@@ -285,7 +285,7 @@ reviewed alpha SHA and compatibility digest; it does not replace the stable
 consumer lock. A later alpha with only compatible additive drift continues,
 while a changed breaking digest fails until the new alpha contract is reviewed.
 
-The evidence job resolves `v3-alpha` and `v2` through the GitHub refs API,
+The evidence job resolves `v3-alpha` and `v3` through the GitHub refs API,
 compares those immutable SHAs with the reusable workflow outputs, verifies the
 `alpha` and `stable` classifications, and uploads a JSON evidence artifact.
 The canary runs after successful Buildchain ref promotion, on a daily fallback
@@ -618,7 +618,7 @@ jobs:
       checks: read
       statuses: read
     with:
-      target-branch: dev/v2/v2.6
+      target-branch: dev/v3/v3.0
       required-status-checks: check / check
       ready-label: ready
       block-labels: blocked,do-not-merge
@@ -720,7 +720,7 @@ when that is explicitly allowed by the caller.
 
 ## Lifecycle Configuration
 
-`buildchain.toml` is the v2 user configuration format. It lets a repository
+`.buildchain/buildchain.toml` is the v3 user configuration format. It lets a repository
 declare version-state files and lifecycle commands without pretending every
 project is a Node workspace. Supported version files include JSON, TOML, and
 regex-based files such as `CMakeLists.txt` or `conanfile.py`.
@@ -785,13 +785,13 @@ bypass actor.
 
 When the loop succeeds, maintainers and consumers can rely on these facts:
 
-- every production release has an exact tag such as `v2.0.2`;
-- every production minor line has a floating tag such as `v2.0`;
-- every selected stable major has a floating tag such as `v2`;
+- every production release has an exact tag such as `v3.0.2`;
+- every production minor line has a floating tag such as `v3.0`;
+- every selected stable major has a floating tag such as `v3`;
 - every next-major release is driven by a reviewed `release -> publish-gate/major` PR,
   not a hidden manual button;
-- every test channel has an exact alpha tag such as `v2.0.3-alpha.0`;
-- every alpha minor line has a floating tag such as `v2.0-alpha`;
+- every test channel has an exact alpha tag such as `v3.0.3-alpha.0`;
+- every alpha minor line has a floating tag such as `v3.0-alpha`;
 - every major with a published alpha has a cross-minor floating tag such as `v3-alpha`, owned by its highest published alpha minor;
 - version manifests match the tag visible from the same commit;
 - production releases are derived from the alpha tree that was tested;
@@ -887,8 +887,8 @@ Buildchain also does not maintain bare exact tags such as `1.0.0`. The supported
 exact release and alpha refs are v-prefixed:
 
 ```text
-v2.0.0
-v2.0.1-alpha.0
+v3.0.0
+v3.0.1-alpha.0
 ```
 
 ## Operational Reading Order

package/docs/release-passport.md

@@ -99,6 +99,10 @@ Additive passport sections:
   semantic Passport root, exact clean source revision, complete platform
   coverage, verdict, and residual risk. Buildchain owns release admission, not
   the meaning of the product invariants.
+- `releaseEvidence`: typed references to product-owned JSON evidence copied
+  beside the Passport. Buildchain does not interpret product or legal meaning;
+  it binds each document's canonical JSON digest and exact source SHA, tag, and
+  channel, then independently re-verifies the sibling document.
 - `githubArtifactAttestations`: expected GitHub keyless attestation identities
   for Linux release artifacts, including subject, caller source, original build
   evidence, exact Buildchain signer workflow digest, and least-privilege