@kungfu-tech/buildchain 4.1.3 → 4.1.4

package/docs/install.md

@@ -1,3 +1,22 @@
+---
+status: active
+period: ongoing
+theme: buildchain-installation
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-20
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-20
+  visible_context: Current CLI source and public v4.1.3 release asset names and SHA-256 digests.
+  invisible_context_boundary: No new publication, installed artifact verification or live provider settlement is claimed.
+---
+
 # Install and Verify Buildchain
 
 Buildchain can be consumed as a standalone binary, an npm package, or a
@@ -6,9 +25,9 @@ adopting a new version.
 
 ## Standalone Binary
 
-Buildchain v4.0.0 does not publish standalone platform archives. This section
-documents the verified legacy binary release contract; v4 consumers should use
-the npm package or repository workflow surface below.
+The [v4.1.3 release](https://github.com/kungfu-systems/buildchain/releases/tag/v4.1.3)
+includes these standalone platform archives. The examples below pin that exact
+release and verify its archive bytes against the published SHA-256 digests.
 
 Use the archive that matches the platform:
 
@@ -21,31 +40,29 @@ Use the archive that matches the platform:
 Linux example:
 
 ```bash
-tag=v2.2.1
+tag=v4.1.3
 base="https://github.com/kungfu-systems/buildchain/releases/download/${tag}"
-curl -LO "${base}/buildchain-x86_64-unknown-linux-gnu.tar.gz"
-curl -LO "${base}/buildchain.release.json"
-curl -LO "${base}/artifact-evidence.json"
-npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
-tar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz
-./buildchain version
+curl -fLO "${base}/buildchain-x86_64-unknown-linux-gnu.tar.gz"
+echo 'd4240384f880f598df2a3ecd9220b3cd7ac4b7042ecb34f82c319cb76dfc8c1e  buildchain-x86_64-unknown-linux-gnu.tar.gz' | sha256sum --check &&
+  tar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz &&
+  ./buildchain version
 ```
 
 Windows example:
 
 ```powershell
-$tag = "v2.2.1"
+$tag = "v4.1.3"
 $base = "https://github.com/kungfu-systems/buildchain/releases/download/$tag"
 Invoke-WebRequest "$base/buildchain-x86_64-pc-windows-msvc.zip" -OutFile buildchain.zip
-Invoke-WebRequest "$base/buildchain.release.json" -OutFile buildchain.release.json
-Invoke-WebRequest "$base/artifact-evidence.json" -OutFile artifact-evidence.json
-npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
+$digest = (Get-FileHash buildchain.zip -Algorithm SHA256).Hash.ToLowerInvariant()
+if ($digest -ne "3ec4e2d9666d254e8a55fdbe99297d0884204cbd871dc399d8f6f791e824183f") { throw "Archive digest mismatch" }
 Expand-Archive buildchain.zip -DestinationPath .
 .\buildchain.exe version
 ```
 
-The GitHub Release page does not publish loose top-level `buildchain` or
-`buildchain.exe` files. The executable is inside each platform archive.
+The executable is inside each platform archive. The macOS archive's SHA-256
+for v4.1.3 is `79221431aa832053952bffb36e68d63676ec922fc317d6f7e315d32a2fd20993`;
+use `shasum -a 256` to check it. Select a release and its matching digests together.
 
 ## npm Package
 
@@ -64,7 +81,7 @@ Stable consumers should pin the exact Buildchain version they have validated,
 for example:
 
 ```bash
-pnpm add -D @kungfu-tech/buildchain@4.0.0
+pnpm add -D @kungfu-tech/buildchain@4.1.3
 ```
 
 If a repository dogfoods a just-published Buildchain version and pnpm's release
@@ -74,34 +91,53 @@ all packages:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@kungfu-tech/buildchain@4.0.0'
+  - '@kungfu-tech/buildchain@4.1.3'
 ```
 
 Remove that entry after the package is old enough for the repository's normal
 policy. Do not use a broad exclude such as `@kungfu-tech/*` for this case.
-Buildchain-managed Paper scaffold and migration commands maintain this exact
-version entry in `pnpm-workspace.yaml` so an immediately published, verified
-runtime can refresh the lockfile without weakening the policy for other
-packages.
+For repositories that already have `pnpm-workspace.yaml`, Paper migration
+maintains the exclusion for the selected exact Buildchain version.
 
 ## Repository Integration
 
 ```bash
 npx @kungfu-tech/buildchain init --type package --package-manager pnpm
 npx @kungfu-tech/buildchain validate --require-version-state
-npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v4/v4.0
+npx @kungfu-tech/buildchain doctor --json
 ```
 
-Use `.buildchain/buildchain.toml` to declare lifecycle commands. The commands may use Node
-package managers or non-Node tools such as pip, Conan, CMake, Make, or project
-scripts.
+Use `.buildchain/buildchain.toml` to declare schema-2 products and their install,
+build and verification commands. The generated `buildchain.yml` and
+`buildchain-recover.yml` delegate normal operation and exact-attempt recovery
+to the shared public pair. A protected channel PR expresses release intent;
+the runtime owns publication. See the [getting-started guide](getting-started.md).
+
+## Release Evidence
 
-## Verify a Release Passport
+Current pipeline releases retain `buildchain.release.json` using
+`kungfu.buildchain.release-passport/v4`, alongside plan, qualification,
+invocation, capsule and attestation JSON files. Their checks and provider
+readback belong to the shared pipeline. v4.1.3 publishes this inventory on its
+release page.
+
+Use a CLI built from the current source for the v4 reader; the published 4.1.3
+CLI still has the legacy-only reader. Keep all six evidence files together,
+unchanged, and install GitHub CLI with `gh attestation verify` support:
 
 ```bash
-buildchain verify release-passport buildchain.release.json
+gh release download v4.1.3 --repo kungfu-systems/buildchain --pattern 'buildchain.*.json'
+buildchain verify release-passport buildchain.release.json --json
 buildchain explain release --passport buildchain.release.json --for agent --json
 ```
 
-The verifier fails closed when the passport or its sibling evidence files are
-missing required fields or mismatching artifact digests.
+The current reader verifies the central publisher's attestation, exact source,
+qualification, invocation, capsules and reconstructed passport. Its report uses
+`verificationScope: signed-release-metadata`; this does not check downloaded
+archive bytes or reobserve the provider's current publication state. Check the
+archive's digest separately before extracting or running it.
+
+Missing or changed companion evidence, an unexpected publisher, or a failed
+signature check produces a failed verification report. The reader also retains
+support for the legacy `kungfu-buildchain-release-passport` envelope and its
+original sibling evidence files.

package/docs/lifecycle-protocol.md

@@ -1,5 +1,5 @@
 ---
-status: active
+status: historical
 period: ongoing
 theme: buildchain-lifecycle-protocol
 doc_type: technical-reference
@@ -8,15 +8,23 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-09-20
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-31
+  generated_at: 2026-09-20
   invisible_context: not asserted
 ---
 
-# Lifecycle Protocol
+# Legacy lifecycle protocol
+
+This page retains the schema-1 lifecycle engine reference and older migration
+examples. It is not the schema-2 consumer configuration contract. Current
+consumers declare products, install/build/verify commands, artifacts, targets,
+version files and channels in `.buildchain/buildchain.toml`; see
+[Getting started](getting-started.md) and the [CLI guide](cli.md).
+Publication, proof reuse and recovery are runtime-owned, not lifecycle hooks to
+copy into a new consumer.
 
 Buildchain uses `.buildchain/buildchain.toml` as the v3 repository configuration format.
 The file is optional for simple JavaScript repositories, but it is the preferred
@@ -202,59 +210,13 @@ git diff --check
 """
 ```
 
-`lifecycle.check` is the repository-owned source-acceptance gate. It should
-validate the checked-out source revision without entering the build, artifact,
-or release lifecycle. Consumers can run it on GitHub-hosted Linux through
-`.github/workflows/public-build-check.yml@v3` with `mode: source`; the reusable workflow runs
-only `lifecycle.install` and `lifecycle.check`. The default `mode: verify`
-continues to run `lifecycle.install` and `lifecycle.verify` for existing callers.
-Both executed stages receive `BUILDCHAIN_CHECK_MODE=source` or
-`BUILDCHAIN_CHECK_MODE=verify`, so a repository whose normal install path can
-compile native tooling can select a provisioning-only install path for source
-acceptance without weakening promotion installs.
-The reusable job name remains `check`, and `upload-artifacts: false` disables
-evidence upload without changing the job conclusion used by branch protection.
-
-Repositories with an expensive `lifecycle.check` may opt into exact source
-qualification proof reuse for merge groups. Set `source-proof-reuse: true` and
-provide non-empty JSON arrays for the policy, closure, dependency, and required
-context inputs. A successful pull-request run seals its exact source head, base,
-patch, runtime, plan, path-set roots, required contexts, controller receipt, and
-workflow run into a content-addressed artifact. The corresponding merge-group
-run downloads only an unexpired artifact from a successful run of the same
-caller workflow and pull request, recomputes every predicate, and records a
-merge-group-bound reuse decision. Reuse additionally requires the synthetic
-merge-group commit to have exactly the qualified base and proved PR head as its
-two parents; grouped or otherwise changed composition falls back. Exact
-verification skips package setup and the duplicate lifecycle commands while
-retaining the stable `check / check` context and an explicit non-executed
-lifecycle evidence manifest.
-
-The opt-in pull-request producer checks out `pull_request.head.sha`, not the
-ephemeral pull-request merge ref. This keeps the controller receipt, proof
-artifact name, and sealed source identity on the same exact PR head that the
-merge-group verifier binds as its second parent. Other check modes and callers
-retain their existing checkout behavior.
-
-The optimization is fail closed. A missing artifact, API or download error,
-base advance, source change, runtime change, contract change, configured path
-change, file blob change, required-context change, malformed proof, or
-non-qualifying producer receipt runs the full `lifecycle.install` plus
-`lifecycle.check` path. Existing callers remain unchanged because proof reuse is
-disabled by default.
+The historical `lifecycle.check` source-acceptance stage is retained by the
+internal `.build-check.yml` implementation. Its exact source-proof reuse contract
+is an implementation detail. Current consumers do not supply JSON path sets,
+required check contexts or a separate source-check reusable workflow.
 
-```yaml
-jobs:
-  source-acceptance:
-    uses: kungfu-systems/buildchain/.github/workflows/public-build-check.yml@<exact-sha>
-    with:
-      mode: source
-      source-proof-reuse: true
-      source-proof-policy-paths-json: '[".github/workflows/source.yml"]'
-      source-proof-closure-paths-json: '[".buildchain/buildchain.toml","scripts/source-check.mjs"]'
-      source-proof-dependency-paths-json: '["pnpm-lock.yaml"]'
-      source-proof-required-contexts-json: '["Candidate source acceptance / check"]'
-```
+The remaining examples describe the historical engine's environment and lifecycle
+model; these fields must not be merged into a schema-2 product declaration.
 
 Shared environment variables can be declared once:
 

package/docs/migration-inventory.md

@@ -8,21 +8,20 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-09-20
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-31
+  generated_at: 2026-09-20
   invisible_context: not asserted
 ---
 
 # Buildchain v2 Migration Inventory
 
-This historical inventory records the Buildchain v2 consolidation boundary.
-Buildchain v3 is now the active monorepo source of truth for Kungfu repository
-workflows, reusable build workflows, and Buildchain-native actions. The v2
-names below preserve the migration decisions that v3 inherited; they are not a
-current runtime baseline.
+This inventory records the dated Buildchain v2 consolidation boundary and its
+v3 successor. The original dispositions below remain historical. Current
+consumers follow the [minimal schema-2 contract](getting-started.md), using only
+the shared normal/recovery pair; historical wrappers are not compatibility APIs.
 Standalone `workflows` and `action-*` repositories are historical rollback
 anchors, not active Buildchain migration targets.
 
@@ -32,44 +31,17 @@ anchors, not active Buildchain migration targets.
 | --- | --- | --- |
 | `workflows` | `dev/v2/v2.0` | root `.github/workflows` sources migrated; reusable workflows linted by actionlint |
 
-## Reusable Workflow Boundaries
+## Historical reusable workflow boundaries
 
-The active Buildchain-native reusable surface is:
+The v2/v3 consolidation retired standalone PR orchestration and direct publish
+integrations in favor of the then-current reusable build/promotion engines.
+Those engines are now internal components. Their original migration history is
+retained in Git; a new consumer must not copy hidden build workflows, a custom
+`lifecycle.publish` hook or the former public promotion wrapper.
 
-| Workflow | Disposition |
-| --- | --- |
-| `.github/workflows/.build.yml` | active reusable build contract: runner presets, trusted event gate, publish source lock, lifecycle commands, deterministic artifacts, aggregate summary, and release manifest outputs |
-
-Hidden reusable workflow files from the old `workflows` repository are retained
-only when they still have an active compatibility or migration boundary. Retired
-PR orchestration paths are not kept in `.github/workflows`; they remain listed
-in the inventory as excluded legacy surfaces. In particular,
-`.batch-pull-request.yml` is removed with the retired batch PR action family,
-and the legacy `.release-new-version.yml` path is not the modern publish
-surface. New publish integrations should use `.build.yml`, `buildchain.toml`,
-`lifecycle.publish`, and publish transaction evidence.
-
-Release templates that previously performed direct publishing or deployment are
-now fail-closed when retained for compatibility discovery. They do not call
-legacy publish actions, `npm publish`, or deploy providers directly. Callers must
-migrate to `public-release-promote.yml@v3` or a project-owned
-`lifecycle.publish` command behind a publish-gate source lock, so floating
-`@v3` consumers cannot bypass source-lock drift protection.
-
-The public promotion workflow is now a generated dual-channel router. Existing
-callers remain source-compatible, while callers that want alpha workflow-shell
-fixes before stable promotion should add `buildchain-channel: auto` plus
-`buildchain-alpha-contract-lock-path` and
-`buildchain-stable-contract-lock-path`. Keep one common promotion declaration;
-do not duplicate alpha and stable jobs or call
-`.release-promote.yml` directly.
-
-Buildchain also keeps the workflow-file layout transition declarative in
-`.buildchain/promotion-shell-routing.json`. Stable `v2.14.13` contains the hidden
-advanced workflow, so the stable lane is pinned to that implementation's
-immutable release SHA and forwards the full internal identity surface. This is
-provider-owned compatibility state; consumers still keep the same single public
-promotion job.
+Current public workflow identities are `public-ops-pipeline.yml` and
+`public-ops-recover.yml`. Their source of truth is the workflow taxonomy and
+generated catalog. Product differences belong in TOML and product source.
 
 ## Migrated Actions
 
@@ -130,7 +102,7 @@ older standalone action repository.
 | `actions/build/lifecycle/run` | lifecycle command execution and deterministic artifact manifest generation |
 | `actions/build/lifecycle/validate` | `buildchain.toml` version-state and lifecycle preflight without executing lifecycle commands |
 
-## Current v3 Refs
+## Historical v3 Refs
 
 - Actions: `kungfu-systems/buildchain/actions/<name>@v3`
 - Reusable workflows: `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v3`

package/docs/next-development-transition.md

@@ -99,19 +99,19 @@ invalid.
 
 ## Public self-dogfood and adoption
 
-`.github/workflows/self-build-public-consumer-dogfood.yml` remains the exact thin
-consumer of the public `public-build-stage-capsule-canary.yml@v4-alpha` contract. Its
-declared `lifecycle.verify` runs `pnpm run check`, so the same public path
-executes pure recovery tests that inject a transient durable-state write
-failure, restore the adapter operation on a fresh runner, supersede stale work
-when protected Dev moves, preserve `pr-pending` during protected-PR delay, and
-prove both legal version models. No caller-local qualification job, action,
-or private self-dogfood route is added.
-
-The existing dual-channel self-consumer separately retains exact hosted
-`build.yml@v4-alpha` and `build.yml@v4` runtime evidence. Consumers adopt
-the proved contract through the floating v4 coordinates; exact resolved SHAs
-remain audit evidence and never become durable selectors.
+`.github/workflows/buildchain.yml` calls the published
+`public-ops-pipeline.yml@v4` entry. Products declare their verification commands
+in schema-2 TOML, including the full repository check on each required platform.
+Next-development preparation, independent review, protected merge and settlement
+remain runtime responsibilities.
+
+`.github/workflows/buildchain-recover.yml` calls
+`public-ops-recover.yml@v4` with one exact attempt and an optional temporary
+repaired runtime. It preserves completed publication evidence while continuing
+unfinished follow-ups. Both callers use the same generated bytes as external
+consumers. Tool-maintained locks and retained receipts bind exact runtime SHAs.
+Earlier Stage Capsule and channel-build proofs retain their historical source
+identities; they do not define additional current consumer entrypoints.
 
 ## Local adapter