@kungfu-tech/buildchain 2.0.16-alpha.0 → 2.0.17-alpha.0

package/docs/release-flow.md

@@ -0,0 +1,259 @@
+# Release Flow Diagrams
+
+This document describes the Buildchain v2 branch, tag, and version-state flow.
+See [Release governance](release-governance.md) for the design rationale.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  Maintainer["Maintainer opens channel PR"]
+  Verify["Release - Verify"]
+  Review["Protected branch review"]
+  Merge["Merge PR into alpha or release"]
+  Promotion["Buildchain Ref Promotion"]
+  Action["promote-buildchain-ref action"]
+  VersionState["Version-state commit"]
+  ExactTag["Exact tag"]
+  FloatingRefs["Floating tags and channel branches"]
+  Consumers["Consumers pin stable or exact refs"]
+
+  Maintainer --> Verify
+  Verify --> Review
+  Review --> Merge
+  Merge --> Promotion
+  Promotion --> Action
+  Action --> VersionState
+  Action --> ExactTag
+  Action --> FloatingRefs
+  ExactTag --> Consumers
+  FloatingRefs --> Consumers
+```
+
+Buildchain treats the PR merge as release intent and the promotion action as the
+only component allowed to turn that intent into release refs.
+
+## Ref State
+
+| 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 |
+| 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 minor tag | `v2.0` | moves | latest production patch on a minor line |
+| Floating major tag | `v2` | moves | selected stable major entrypoint |
+
+## Ref Protection Contract
+
+Repository rulesets must distinguish immutable evidence refs from mutable
+channel refs.
+
+Protect exact release and alpha tags as immutable evidence:
+
+```text
+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`, and
+`v2.0-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`, and `v2.0-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.
+
+## Alpha Promotion
+
+```mermaid
+sequenceDiagram
+  participant Dev as dev/vX/vX.Y
+  participant PR as PR dev -> alpha
+  participant Verify as Release - Verify
+  participant Alpha as alpha/vX/vX.Y
+  participant Promote as Buildchain Ref Promotion
+  participant Tags as Tags
+
+  Dev->>PR: open channel PR
+  PR->>Verify: run verification checks
+  Verify-->>PR: check succeeds
+  PR->>Alpha: reviewed merge
+  Alpha->>Promote: Verify workflow_run completed
+  Promote->>Promote: validate same-repo merged PR
+  Promote->>Promote: compute next vX.Y.Z-alpha.N
+  Promote->>Promote: write and verify version state
+  Promote->>Tags: create or reuse vX.Y.Z-alpha.N
+  Promote->>Tags: move vX.Y-alpha
+  Promote->>Alpha: move alpha/vX/vX.Y
+  Promote->>Dev: move dev/vX/vX.Y
+```
+
+Result:
+
+```text
+vX.Y.Z-alpha.N
+vX.Y-alpha
+alpha/vX/vX.Y
+dev/vX/vX.Y
+```
+
+all point at the generated alpha version-state commit.
+
+## Release Promotion
+
+```mermaid
+sequenceDiagram
+  participant Alpha as alpha/vX/vX.Y
+  participant PR as PR alpha -> release
+  participant Verify as Release - Verify
+  participant Release as release/vX/vX.Y
+  participant Promote as Buildchain Ref Promotion
+  participant Tags as Tags
+  participant Dev as dev/vX/vX.Y
+
+  Alpha->>PR: open channel PR
+  PR->>Verify: run verification checks
+  Verify-->>PR: check succeeds
+  PR->>Release: reviewed merge
+  Release->>Promote: Verify workflow_run completed
+  Promote->>Promote: validate same-repo merged PR
+  Promote->>Promote: find same-patch alpha tag
+  Promote->>Promote: compare release tree with tested alpha tree
+  Promote->>Promote: write and verify final version state
+  Promote->>Tags: create or reuse vX.Y.Z
+  Promote->>Tags: move vX.Y
+  Promote->>Tags: move vX when eligible
+  Promote->>Release: move release/vX/vX.Y
+  Promote->>Promote: prepare vX.Y.(Z+1)-alpha.0
+  Promote->>Tags: create or reuse vX.Y.(Z+1)-alpha.0
+  Promote->>Tags: move vX.Y-alpha
+  Promote->>Alpha: move alpha/vX/vX.Y
+  Promote->>Dev: move dev/vX/vX.Y
+```
+
+Result:
+
+```text
+vX.Y.Z
+vX.Y
+vX
+release/vX/vX.Y
+```
+
+point at the production version-state commit, while:
+
+```text
+vX.Y.(Z+1)-alpha.0
+vX.Y-alpha
+alpha/vX/vX.Y
+dev/vX/vX.Y
+```
+
+point at the next alpha version-state commit.
+
+## State Machine
+
+```mermaid
+stateDiagram-v2
+  [*] --> Development: work lands on dev/vX/vX.Y
+  Development --> AlphaCandidate: PR dev -> alpha
+  AlphaCandidate --> AlphaPublished: Verify + review + merge + promotion
+  AlphaPublished --> ReleaseCandidate: PR alpha -> release
+  ReleaseCandidate --> ProductionPublished: Verify + review + merge + promotion
+  ProductionPublished --> NextAlphaPrepared: prepare vX.Y.(Z+1)-alpha.0
+  NextAlphaPrepared --> Development: dev and alpha refs move to next alpha
+```
+
+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`.
+
+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
+```
+
+It should also prepare:
+
+```text
+v2.0.3-alpha.0          exact next alpha tag
+v2.0-alpha              floating alpha tag
+alpha/v2/v2.0           alpha channel branch
+dev/v2/v2.0             development channel branch
+```
+
+This is expected behavior. A production release closes one patch and opens the
+next test patch on the same minor line.
+
+## Major Gate Promotion
+
+```mermaid
+sequenceDiagram
+  participant Release as release/vX/vX.Y
+  participant PR as PR release -> publish-gate/major
+  participant Verify as Release - Verify
+  participant Gate as publish-gate/major
+  participant Promote as Buildchain Ref Promotion
+  participant Tags as Tags
+  participant Next as dev/alpha/release v(X+1).0
+
+  Release->>PR: open administrator PR
+  PR->>Verify: run verification checks
+  Verify-->>PR: check succeeds
+  PR->>Gate: reviewed merge
+  Gate->>Promote: Verify workflow_run completed
+  Promote->>Promote: validate same-repo release -> publish-gate/major PR
+  Promote->>Promote: write v(X+1).0.0 version state
+  Promote->>Tags: create v(X+1).0.0
+  Promote->>Tags: move v(X+1).0 and v(X+1)
+  Promote->>Gate: move publish-gate/major to v(X+1).0.0
+  Promote->>Next: move release/v(X+1)/v(X+1).0 to v(X+1).0.0
+  Promote->>Promote: prepare v(X+1).0.1-alpha.0
+  Promote->>Next: move alpha/dev v(X+1).0 to next alpha
+```
+
+`publish-gate/major` is intentionally not an active source branch. It is the PR
+target for the administrator's "publish the next major" decision. The older
+`major-gate` name is a compatibility alias only.
+
+## Failure Boundaries
+
+Promotion should stop before moving refs when:
+
+- the run is a non-dry-run manual dispatch;
+- the expected same-repository PR cannot be found;
+- the PR was not merged;
+- the branch pair is not a valid channel path;
+- the required status check did not pass;
+- a release tree does not match the same-patch alpha tag tree;
+- version-state verification fails;
+- a required exact tag already exists at a commit unrelated to the active
+  transaction or finalized channel head.
+
+These failures are intentional. They protect consumers from refs that look
+released but do not have a complete evidence chain.
+
+During transaction finalization recovery, the current channel head may be a
+generated version-state merge commit. Buildchain validates that the durable
+transaction version, exact tag, evidence, and release material match, and that
+the current target ref contains or corresponds to the recorded
+`release_material_sha`. It must then tolerate exact tags, dev refs, or alpha
+refs that have already moved and continue filling any missing floating tags
+before writing the transaction state as `complete`.

package/docs/release-governance.md

@@ -0,0 +1,313 @@
+# Release Governance
+
+Buildchain v2 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
+release intent. Automation must then create the version-state commit, exact tag,
+floating tag, and next alpha state that make that intent true in Git.
+
+## Design Problem
+
+Kungfu release automation has to keep four facts aligned:
+
+1. The source tree that was reviewed.
+2. The package version recorded in manifests such as `package.json` or
+   `lerna.json`.
+3. The exact immutable release or prerelease tag.
+4. The floating channel refs that consumers actually use.
+
+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
+  says the previous release;
+- a maintainer can move `v2` without producing an exact `v2.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
+  missing.
+
+The older ABV workflow addressed this by letting GitHub PRs drive release
+state. Buildchain keeps that choice because it makes release intent reviewable,
+observable, and recoverable from Git history.
+
+## What ABV Contributed
+
+The old ABV model was not just "bump a version number." It encoded a governance
+loop:
+
+- release branches are named as channels: `dev`, `alpha`, `release`, and the
+  administrative `publish-gate/major`;
+- a PR from one channel to the next is the release request;
+- verify jobs check that the branch pair is valid before merge;
+- a maintainer review is required before the branch moves;
+- after merge, automation writes the version change and moves tags;
+- exact tags and floating refs are aligned with the resulting commit;
+- the next development channel is prepared automatically.
+
+ABV also kept the version-state mutation in the repository. For JavaScript
+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
+line.
+
+## Buildchain Implementation
+
+Buildchain implements the same governance loop with:
+
+- `.github/workflows/release-verify.yml` for PR verification;
+- `.github/workflows/buildchain-ref-promotion.yml` for post-verify ref
+  promotion;
+- `actions/promote-buildchain-ref` for branch, tag, version-state, and
+  governance checks;
+- package-manager adapters that can update version state for pnpm, npm, and
+  yarn style repositories;
+- `buildchain.toml` lifecycle configuration for repositories whose version
+  state or verification commands are not Node package-manager defaults.
+
+The implementation is intentionally stricter than a local release script:
+
+- manual workflow dispatch can only do dry-run promotion;
+- non-dry-run promotion must be driven by a completed `Verify` workflow;
+- target branch protection details must be readable, and branch protection must
+  apply to administrators as well as regular contributors;
+- alpha promotion must come from a merged same-repository PR from
+  `dev/vX/vX.Y` to `alpha/vX/vX.Y`;
+- release promotion must come from a merged same-repository PR from
+  `alpha/vX/vX.Y` to `release/vX/vX.Y`;
+- major promotion must come from a merged same-repository PR from
+  `release/vX/vX.Y` to `publish-gate/major`;
+- release promotion requires an existing same-patch alpha tag and checks the
+  release source tree against that tested alpha tree;
+- generated version-state commits are verified before refs move.
+
+## 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
+patch releases:
+
+```text
+v2.0.0
+v2.0.1
+v2.0.2
+...
+v2.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.
+
+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`, and `v2.0-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
+patterns such as `refs/tags/v*.*.*` for immutable release evidence, while
+leaving floating channel tags under Buildchain automation control.
+
+## Alpha Semantics
+
+An alpha merge is:
+
+```text
+dev/vX/vX.Y -> alpha/vX/vX.Y
+```
+
+Buildchain then:
+
+1. Computes the next prerelease for the minor line.
+2. Writes version state such as `vX.Y.Z-alpha.N`.
+3. Verifies the generated version-state tree.
+4. Creates or reuses the exact alpha tag.
+5. Moves `alpha/vX/vX.Y` to the generated alpha commit.
+6. Moves `dev/vX/vX.Y` to the same generated alpha commit when this is a
+   fast-forward update.
+7. Moves `vX.Y-alpha` to the same generated alpha commit.
+
+This keeps the test channel self-describing. If a consumer checks out
+`v2.0-alpha`, the manifests and exact alpha tag agree.
+
+If `dev/vX/vX.Y` has already advanced while the generated alpha version-state PR
+was under review, Buildchain records `skipped-non-fast-forward` for the dev sync
+and still completes the exact and floating alpha tags for the reviewed alpha
+commit. Later dev changes must go through their own dev-to-alpha promotion
+instead of rewinding dev.
+
+If alpha finalization is resumed after the version-state PR is merged,
+Buildchain accepts the current alpha head as a merge commit that contains the
+recorded release material. An already-created exact alpha tag may point at the
+transaction release/material SHA or at the finalized alpha head; missing
+floating alpha tags are retried before the transaction becomes `complete`.
+
+## Release Semantics
+
+A release merge is:
+
+```text
+alpha/vX/vX.Y -> release/vX/vX.Y
+```
+
+Buildchain then:
+
+1. Finds the same-patch alpha tag that was tested.
+2. Checks that the release source tree matches that alpha tag tree, excluding
+   only generated version-state differences.
+3. Writes final release version state such as `vX.Y.Z`.
+4. Verifies the generated release tree.
+5. Creates or reuses the exact release tag `vX.Y.Z`.
+6. Moves `release/vX/vX.Y` to the exact release commit.
+7. Moves `vX.Y` to the exact release commit.
+8. Moves `vX` when this minor line should be the stable major entrypoint.
+9. Prepares the next alpha version-state commit, such as
+   `vX.Y.(Z+1)-alpha.0`.
+10. Moves `alpha/vX/vX.Y`, `dev/vX/vX.Y`, and `vX.Y-alpha` to that next alpha
+    commit.
+
+The production channel and the test channel therefore intentionally diverge
+after release: production stays on the release commit, while alpha/dev continue
+at the next prerelease commit.
+
+If release finalization is resumed after the version-state PR is merged,
+Buildchain applies the same recovery rule: the current release head may be a
+merge commit that contains the recorded release material, existing exact tags
+and alpha/dev refs are accepted when they match the transaction, and missing
+floating `vX.Y` or `vX` tags are retried idempotently before completion.
+
+## Major Gate Semantics
+
+A major gate merge is:
+
+```text
+release/vX/vX.Y -> publish-gate/major
+```
+
+`publish-gate/major` is the explicit replacement for the older ABV `main`
+channel. The name is intentionally operational: it is a gate for a rare
+administrator decision, not the active trunk. Keeping this decision in the same
+PR UI as alpha and release promotion keeps the human workflow simple while
+avoiding the misleading meaning of `main`. The older `major-gate` branch name is
+a compatibility alias only.
+
+Buildchain then:
+
+1. Verifies the source is a merged same-repository PR from a protected release
+   line into `publish-gate/major`.
+2. Writes the next major production version state, such as `v(X+1).0.0`.
+3. Creates or reuses the exact release tag `v(X+1).0.0`.
+4. Moves `publish-gate/major` and `release/v(X+1)/v(X+1).0` to that release commit.
+5. Moves `v(X+1).0` and `v(X+1)` to that release commit.
+6. Prepares the next alpha version-state commit, such as
+   `v(X+1).0.1-alpha.0`.
+7. Moves `alpha/v(X+1)/v(X+1).0`, `dev/v(X+1)/v(X+1).0`, and
+   `v(X+1).0-alpha` to that next alpha commit.
+
+Checking out `publish-gate/major` should therefore look like a frozen release
+state, not like a branch where day-to-day source work continues. Day-to-day
+source work continues on `dev/vX/vX.Y`.
+
+## Package-Manager Adapters
+
+Old ABV assumed JavaScript repositories with root version state and often
+Lerna. Buildchain keeps the version-state contract but does not assume every
+repository is yarn/Lerna.
+
+The promotion action discovers and updates:
+
+- root `package.json`;
+- `lerna.json`;
+- package manifests from `package.json` workspaces;
+- package manifests from `lerna.json` packages;
+- package manifests from `pnpm-workspace.yaml`.
+
+It then runs the repository's detected package manager semantics where needed:
+
+- pnpm repositories use pnpm-oriented workspace discovery;
+- npm repositories use npm/package-lock semantics where present;
+- yarn repositories use yarn-style metadata where present.
+
+For Buildchain itself, version state is required. For a consumer repository that
+has no package manifest, the same action can degrade to ref-only behavior only
+when that is explicitly allowed by the caller.
+
+## Lifecycle Configuration
+
+`buildchain.toml` is the v2 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`.
+
+The promotion action currently consumes `version.files` and `lifecycle.verify`.
+The verify stage runs after generated version-state changes are applied locally
+and before any release refs move. If `verification-command` is passed directly
+to the action, that explicit command overrides `lifecycle.verify`.
+
+Protected release-line branches keep their normal review gate. When generated
+version state would move a protected alpha or release branch, Buildchain creates
+a version-state PR instead of bypassing branch protection. After that PR is
+reviewed, checked, and merged, the next promotion run verifies that only
+declared version-state files changed from the legally merged source parent, then
+moves the exact and floating tags.
+
+## What This Guarantees
+
+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 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`;
+- version manifests match the tag visible from the same commit;
+- production releases are derived from the alpha tree that was tested;
+- manual non-dry-run promotion cannot bypass PR review and verification;
+- admin users cannot make a channel promotion valid by temporarily bypassing
+  branch protection.
+
+This is the practical meaning of "governance closed loop" in Buildchain: the
+decision, code, version state, and Git refs close over the same evidence chain.
+
+## What This Does Not Do
+
+Buildchain release promotion does not embed registry clients or product-specific
+publish logic. When publish transactions are enabled, `promote-buildchain-ref`
+can run the consumer's `lifecycle.publish` command and own the transaction,
+evidence validation, durable recovery state, and ref finalization order. The
+consumer repository still owns registry truth: npm, PyPI, OCI, S3, Conan, CMake
+packaging, download pages, dist-tags, and similar side effects must be
+implemented by project lifecycle commands that emit Buildchain publish evidence.
+
+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
+```
+
+## Operational Reading Order
+
+When debugging or extending release behavior, read in this order:
+
+1. `docs/release-flow.md`
+2. `.github/workflows/release-verify.yml`
+3. `.github/workflows/buildchain-ref-promotion.yml`
+4. `actions/promote-buildchain-ref/README.md`
+5. `actions/promote-buildchain-ref/src/`
+6. `docs/migration-inventory.md`
+
+That path gives the policy first, the workflow trigger second, and the action
+implementation last.

package/fixtures/libnode-shaped/README.md

@@ -0,0 +1,23 @@
+# Libnode-shaped Fixture
+
+This fixture models the Buildchain contract needed by `kungfu-systems/libnode`
+without running the real native build.
+
+It is intentionally small, but it keeps the important shape:
+
+- `package.json` is the package version-state file;
+- `libnode.release.json` is the explicit upstream anchor manifest;
+- `buildchain.toml` declares `install`, `build`, and `verify` lifecycle stages;
+- `version.strategy = "anchored"` and `version.next = "manual"` tell
+  Buildchain to validate the current anchor instead of deriving the next Node
+  anchor automatically;
+- lifecycle commands are Node-based and cross-platform;
+- build output lands under `dist/`, which the reusable build workflow uploads
+  with a deterministic artifact name and manifest;
+- the fixture can be resolved through a publish-gate source lock, which binds
+  the requested consumer version to `package.json` and `libnode.release.json`
+  before any publish side effect is allowed;
+- `[publish]` declares the normal token-free path:
+  `mode = "publish-final-version"` with `auth = "trusted-publishing"`, `latest`
+  as the release dist-tag, and platform packages published before the main
+  package.

package/fixtures/publish-transaction-shaped/README.md

@@ -0,0 +1,26 @@
+# publish-transaction-shaped
+
+Fixture for the Buildchain publish transaction contract.
+
+It represents a release unit with three required artifact families:
+
+- npm package metadata;
+- OCI image digest;
+- binary archive digest.
+
+The fixture does not publish to external services. `lifecycle.publish` writes
+generic Buildchain evidence to `BUILDCHAIN_PUBLISH_EVIDENCE`, which is enough for
+tests and for consumers to understand the expected shape.
+
+```bash
+BUILDCHAIN_VERSION=1.0.0 \
+BUILDCHAIN_CHANNEL=release \
+BUILDCHAIN_SOURCE_SHA=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
+BUILDCHAIN_RELEASE_SHA=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb \
+BUILDCHAIN_RELEASE_MATERIAL_SHA=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb \
+BUILDCHAIN_PUBLISH_TOOLING_SHA=cccccccccccccccccccccccccccccccccccccccc \
+BUILDCHAIN_TARGET_REF=release/v1/v1.0 \
+BUILDCHAIN_EVIDENCE_DIR=.buildchain/release-evidence/v1.0.0 \
+BUILDCHAIN_PUBLISH_EVIDENCE=.buildchain/release-evidence/v1.0.0/evidence.json \
+node scripts/publish.mjs
+```

package/fixtures/web-surface-shaped/README.md

@@ -0,0 +1,9 @@
+# Web Surface Shaped Fixture
+
+This fixture models a static site repository that wants Buildchain deployment
+semantics without opting into package release lines.
+
+It proves that `project.type = "web-surface"` can declare preview, staging, and
+production channels, generate deterministic deployment manifests, and create
+dry-run deploy and cleanup plans without touching AWS.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.0.16-alpha.0",
+  "version": "2.0.17-alpha.0",
   "private": false,
   "description": "Kungfu Buildchain reusable workflows, release governance, and CLI tooling.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -16,15 +16,26 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "AGENTS.md",
     "bin/",
+    "CONTRIBUTING.md",
+    "LICENSE-POLICY.md",
     "scripts/*.mjs",
     "packages/core/",
     "README.md",
+    "SECURITY.md",
+    "docs/MAP.md",
     "docs/cli.md",
     "docs/lifecycle-protocol.md",
+    "docs/migration-inventory.md",
+    "docs/ownership.md",
     "docs/publish-transaction.md",
+    "docs/release-flow.md",
+    "docs/release-governance.md",
     "docs/reusable-build-surface.md",
-    "docs/web-surface-deployments.md"
+    "docs/web-surface-deployments.md",
+    "actions/*/README.md",
+    "fixtures/*/README.md"
   ],
   "engines": {
     "node": ">=22.14.0"