@kungfu-tech/buildchain 4.0.10-alpha.0 → 4.1.0-alpha.1

package/AGENTS.md

@@ -1,3 +1,22 @@
+---
+status: active
+period: ongoing
+theme: buildchain-layered-architecture
+doc_type: implementation-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-11
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-11
+  visible_context: Buildchain 4.1 source, architecture registries and local validation.
+  invisible_context_boundary: No unpublished release or external consumer qualification is claimed.
+---
+
 # AGENTS.md
 
 This file orients coding agents and people working with Buildchain. It is a
@@ -26,19 +45,23 @@ consumers call the public workflow with no inputs:
 uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4
 ```
 
-Use `@v4-alpha` for the alpha runtime. The called workflow ref and SHA determine
-runtime identity and the matching contract lock. A nested project may supply
-only `config-path`; all project settings belong in TOML and infrastructure
-settings belong to a governed Buildchain environment profile. `.build.yml`
-remains the core install/build/verify backbone. Historical build inputs and
-runtime overrides are removed.
+The public workflow is the API entry. It selects the execution runtime from a
+trusted non-persistent runtime input (`runtime-ref`), the selected consumer
+contract lock, or the entry commit default. `@v4-alpha` selects the alpha entry
+and its default lock path. Entry and runtime commits may differ. See
+[`Runtime entry`](docs/runtime-entry.md) for selection and recovery.
+
+Project settings belong in TOML; `config-path` locates a nested project. All
+execution jobs prepare the selected runtime through
+`actions/runtime/environment/prepare`. Subsequent business actions use that
+runtime without Buildchain SHA comparisons or secondary runtime admission.
 
 For new repositories, prefer the CLI:
 
 ```sh
 npx @kungfu-tech/buildchain init --type package
 npx @kungfu-tech/buildchain validate --require-version-state
-npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v4/v4.1
 ```
 
 For governed Paper repositories, scaffold or migrate the repository once, then
@@ -58,12 +81,16 @@ See [`docs/cli.md`](docs/cli.md), [`docs/lifecycle-protocol.md`](docs/lifecycle-
 and [`docs/reusable-build-surface.md`](docs/reusable-build-surface.md) for the
 consumer contract.
 
-Ordinary builds do not accept runtime overrides. Specialized release/recovery
-contracts retain their bounded, non-persistent validation mechanisms; see
-[`docs/runtime-train-validation.md`](docs/runtime-train-validation.md).
+All public entries share the same runtime contract. A runtime bug is recovered
+through a new execution with a repaired train and original source evidence.
+An entry bug requires an upgraded published entry and a complete new run.
 
 ## Building this repo
 
+Read [Code organization](docs/code-organization.md) before changing implementation
+layout. Keep workflows, action adapters, JavaScript modules and Rust domains in
+their declared responsibility layers. No historical compatibility entry is retained.
+
 Buildchain is a pnpm workspace running on Node 24:
 
 ```sh
@@ -99,34 +126,26 @@ consume `kungfu-systems/buildchain/.github/workflows/public-build-stage-capsule-
 through the same public reusable-workflow contract as every other consumer.
 The caller must remain a thin workflow with no steps or local orchestration,
 and `.buildchain/buildchain.toml` must declare the same real `install`, `build`,
-and `verify` lifecycle. The public workflow binds the exact called-workflow SHA,
+and `verify` lifecycle. The public workflow records the entry and selected runtime and binds
 consumer source SHA, platform, commands, manifests, summaries, dependencies,
 and output roots on Linux, macOS, and Windows.
 
-No agent may add or restore a relative/self reusable-workflow call, direct
-qualification job, local action, candidate-branch runtime override,
-Buildchain-only consumer identity/profile, environment-variable escape hatch,
-or any other private self-dogfood path. Generic Stage Capsule internals may be
-called only by the public reusable workflow and tests. `version-state`,
-`publish`, provider, signing, release, credential, AWS, and production-reuse
-effects remain excluded.
-
-Buildchain v4 workflow calls persisted in tracked source use only `@v4` or
-`@v4-alpha` and retain matching stable and alpha contract locks.
-A source-persisted exact commit SHA, exact default, repository-variable indirection, nested
-composite indirection, missing lock, or stale selected lock fails consumer
-admission. Exact resolved SHAs remain evidence and runtime data, never a durable
-selector.
-
-If public workflow recursion prevents candidate validation, publish the exact
-candidate at `train/v4/v4.0/<capability>`, keep the thin caller on `@v4-alpha`,
-and pass the train only through the trusted non-persistent runtime input. Fix
-failures in the train/public contract; never solve recursion with an internal exception.
-Never use a persisted train/SHA selector. After qualification and protected
-merge, the durable caller remains on the floating channel with refreshed dual
-contract locks. `pnpm run check` and protected Verify run
-`scripts/check-public-dogfood-contract.mjs`; changing this rule, its gate, or
-the protected caller requires independent `@kungfu-origin` review.
+Dogfood callers use the same public entry and runtime preparation as external
+consumers. No repository-specific runtime selection or recovery exception is
+allowed. Stage Capsule internals are invoked by public workflows and tests;
+provider effects remain subject to their own source, artifact and readback rules.
+
+External Buildchain v4 workflow calls persisted in tracked source use only `@v4` or
+`@v4-alpha` and retain matching stable and alpha contract locks. A
+source-persisted exact commit SHA or train is not a durable entry selector.
+Exact resolved SHAs belong in lock data and provenance. Normal self workflows
+call `@v4`; dedicated post-publication alpha entry qualification calls `@v4-alpha`.
+
+Train validation passes `train/v4/v4.1/<capability>` only through the trusted
+non-persistent runtime input. The central entry resolves it once, and every
+business job executes the selected runtime. Protected merge and requested alpha
+publication follow successful validation. Changes to dogfood policy or its
+gates require independent `@kungfu-origin` review.
 
 `pnpm run check` validates inventory data, generated public references and site
 bundle drift, lints root workflows, runs unit tests, and rebuilds every action
@@ -140,7 +159,7 @@ handoff in
 
 - Open pull requests against the relevant `dev/*` channel branch.
 - If a Buildchain change needs downstream validation before stable refs move,
-  publish a `train/v3/v3.0/<capability>` ref and include the validation request
+  publish a `train/v4/v4.1/<capability>` ref and include the validation request
   described in [`docs/runtime-train-validation.md`](docs/runtime-train-validation.md).
   After validation succeeds, do not leave the train as a pending merge item:
   merge the pull request into the active `dev/*` mainline and run the requested

package/CONTRIBUTING.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-09-07
+last_reviewed: 2026-09-11
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-07
+  generated_at: 2026-09-11
   visible_context: Repository contribution rules and implementation naming and release transition changes.
   invisible_context_boundary: No private credentials or unpublished external release state.
 ---
@@ -47,26 +47,16 @@ repository itself is a Node/pnpm workspace.
 
 ## Repository layout
 
-- `.github/workflows` - repository checks, reusable workflows, and Buildchain
-  self-promotion.
-- `.github/retrospectives` - time-bounded engineering reviews and maintenance
-  handoff records. Start with the latest record before broad consolidation work.
-- `actions` - the active GitHub Actions surface:
-  `validate-config`, `run-lifecycle`, `promote-buildchain-ref`, and
-  `report-buildchain-issue`.
-- `bin` - the published `buildchain` command-line entrypoint.
-- `docs` - release governance, lifecycle, reusable workflow, web-surface, and
-  CLI documentation.
-- `fixtures` - safe shape fixtures used by tests and reusable workflow checks.
-- `packages/core` - shared ESM library code used by CLI and scripts.
-- `scripts` - local and workflow runtime scripts.
-- `tests` - Node test runner suites and inventory contracts.
-
-Standalone historical `action-*` repositories are not mirrored here as active
-actions. See [`docs/migration-inventory.md`](docs/migration-inventory.md).
-
-The current consolidation handoff is
-[`2026-07-10-buildchain-consolidation.md`](.github/retrospectives/2026-07-10-buildchain-consolidation.md).
+The [code organization contract](docs/code-organization.md) defines the layers.
+Consumer APIs and hosted job boundaries live in `.github/workflows`; semantic
+node adapters live in `actions/<capability>/<group>/<operation>`; JavaScript business logic
+lives in `packages/core/<capability>`; authoritative Rust domains and the native
+host live in `crates`. `bin` contains the CLI entry, and `scripts` contains only
+repository tooling. Schemas, ownership declarations and tests live in
+`contracts`, `architecture` and `tests`.
+
+Do not add historical aliases or compatibility forwarders. Update every owned
+caller and generated artifact when moving a contract or implementation.
 
 ## Build and verification
 
@@ -106,15 +96,14 @@ category vocabulary is enforced by `architecture/workflow-taxonomy.json`:
 Categories are only `build`, `release`, and `ops`. Register the identity, role,
 category, purpose, owner, lifecycle status, invocation, and rationale before
 adding its derived filename. The [Workflow Catalog](docs/workflow-catalog.md)
-lists every allowed path and compatibility exception. Existing public aliases
-are generated from their canonical implementations; self workflows have one
-event entry. A matching prefix alone does not admit an unregistered workflow.
+lists every canonical API and component path; self workflows have one
+event entry. Retired paths have no generated aliases. A matching prefix alone does not admit an unregistered workflow.
 
 Run `pnpm run generate:workflows`, `pnpm run check:workflows`, then the full
 `pnpm run check`. The required Verify lifecycle runs this gate on PRs, merge
 queue candidates, and pushes. Policy, enforcement, and ownership changes require
-independent `@kungfu-origin` review. Keep published floating consumers on their
-registered legacy paths until the selected channel actually ships the new path.
+independent `@kungfu-origin` review. A development merge does not publish a floating channel. Consumers adopt the
+new API only after that channel publishes it and their contract locks are refreshed.
 
 ## Generated files
 
@@ -157,16 +146,15 @@ release/vX/vX.Y -> publish-gate/major
   `docs/*`, `ci/*`, or `refactor/*` branches and open a PR into the target dev
   line.
 - Repositories may call
-  `.github/workflows/dev-pr-auto-merge.yml` from their own scheduled or manual
+  `.github/workflows/public-ops-dev-auto-merge.yml` from their own scheduled or manual
   wrapper to merge ready, conflict-free dev PRs. The wrapper is policy-gated:
   required checks, ready/block labels, same-repository heads, approvals,
   branch prefixes, max merges, and dry-run are all declared inputs.
 - Ordinary build callers use `build.yml@v4` or `build.yml@v4-alpha` with
-  project settings in `buildchain.toml`. They have no runtime override input.
-  Validate the implementation and exact contract before merging into protected
-  Dev, publish Alpha, then qualify the public Alpha build before Stable.
-  Specialized release/recovery train admission follows its own bounded
-  contract in `docs/runtime-train-validation.md`.
+  project settings in `buildchain.toml`. Every public workflow uses the central
+  runtime entry: transient `runtime-ref`, contract lock, then entry default.
+  Validate the implementation before protected Dev, publish Alpha, and qualify
+  the published consumer entry. See `docs/runtime-entry.md`.
 - Merging into `alpha/*`, `release/*`, or `publish-gate/major` expresses a
   release intent. Buildchain promotion then creates version-state commits,
   exact tags, floating tags, npm publish evidence, and next-alpha state.
@@ -190,7 +178,7 @@ Name implementation directories, scripts, functions, and runtime work directorie
 for their responsibility. Product generation prefixes such as `v4-` are rejected
 by `pnpm run check:implementation-naming`, including nested JavaScript bindings
 and Rust declarations. `architecture/implementation-naming.json` records the
-explicit relocation and public export aliases. Published schema identities, hash
+current implementation identities and prohibited generation prefixes. Published schema identities, hash
 domains, selectors, runner labels, API compatibility keys, and exact historical
 evidence keep their established identities; they do not name new implementations.
 

package/README.md

@@ -1,5 +1,28 @@
+---
+status: active
+period: ongoing
+theme: buildchain-layered-architecture
+doc_type: implementation-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-10
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-10
+  visible_context: Buildchain 4.1 source, architecture registries and local validation.
+  invisible_context_boundary: No unpublished release or external consumer qualification is claimed.
+---
+
 # Buildchain
 
+Development: **4.1.0-alpha.0** on `dev/v4/v4.1`. This development version has
+not been published. See [Code organization](docs/code-organization.md) for the
+workflow → action → JavaScript/Rust implementation layers.
+
 <!-- buildchain-auditable-demo:start -->
 
 ## Buildchain beginner bootstrap
@@ -37,9 +60,9 @@ This exact standalone-binary scenario proves deterministic local bootstrap behav
 [![Buildchain Release Passport: passed](https://buildchain.libkungfu.dev/badges/v1/buildchain-release-passport/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0969da.svg)](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)
 [![Platform: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-6e7781.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
-[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)
-[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)
-[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)
+[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-verify.yml)
+[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/self-release-promote.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/self-release-promote.yml)
+[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-binary-distribution.yml)
 <!-- buildchain:badges:end -->
 
 Buildchain Release Passport is a mature product release record for artifacts
@@ -216,7 +239,7 @@ Consumers can report Buildchain-owned workflow failures directly to the
 Buildchain repository with a scoped issue-write token:
 
 ```yaml
-- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v4
+- uses: kungfu-systems/buildchain/actions/governance/incident/report@v4
   if: failure()
   with:
     token: ${{ steps.buildchain-issue-token.outputs.token }}
@@ -283,30 +306,33 @@ plus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These
 gates preserve product-owned qualification and support decisions; they do not
 turn a schema-valid record into certification or shipped support.
 
-Buildchain's action registry contains fourteen active entries. Six are
-direct consumer integration actions:
+Reusable workflows are the primary consumer API. The generated action registry
+indexes the capability/group/operation hierarchy and marks direct action contracts.
+The direct consumer integration actions are:
 
-- `actions/validate-config`
-- `actions/run-lifecycle`
-- `actions/promote-buildchain-ref`
-- `actions/report-buildchain-issue`
-- `actions/release-tail`
-- `actions/release-candidate-promote`
+- `actions/build/lifecycle/validate`
+- `actions/build/lifecycle/run`
+- `actions/release/promotion/ref`
+- `actions/governance/incident/report`
+- `actions/release/tail/settle`
+- `actions/release/promotion/candidate`
 
-Two additional release-authority components are also registered and versioned:
+Three additional release-authority components are also registered and versioned:
 
-- `actions/github-artifact-attestation`
-- `actions/macos-credential-island`
+- `actions/build/artifact/prepare-attestation`
+- `actions/build/artifact/seal-attestation`
+- `actions/build/credential/macos-island`
 
-Six shared build components have explicit ownership in
+Seven shared build components have explicit ownership in
 `architecture/build-orchestration.json`:
 
-- [`actions/build-lifecycle-stage`](actions/build-lifecycle-stage/action.yml)
-- [`actions/build-signing-request`](actions/build-signing-request/action.yml)
-- [`actions/build-verification-evidence`](actions/build-verification-evidence/action.yml)
-- [`actions/build-attestation-policy`](actions/build-attestation-policy/action.yml)
-- [`actions/build-agent-hub-evidence`](actions/build-agent-hub-evidence/action.yml)
-- [`actions/build-artifact-transfer`](actions/build-artifact-transfer/action.yml)
+- [`actions/build/lifecycle/plan`](actions/build/lifecycle/plan/action.yml)
+- [`actions/build/lifecycle/prepare`](actions/build/lifecycle/prepare/action.yml)
+- [`actions/build/lifecycle/stage`](actions/build/lifecycle/stage/action.yml)
+- [`actions/build/artifact/transfer`](actions/build/artifact/transfer/action.yml)
+- [`actions/build/artifact/sign`](actions/build/artifact/sign/action.yml)
+- [`actions/build/artifact/attest`](actions/build/artifact/attest/action.yml)
+- [`actions/build/artifact/finalize`](actions/build/artifact/finalize/action.yml)
 
 `dist/site/workflow-registry.json#actions` is the machine-readable inventory;
 this split keeps the older four-action consumer snapshot from being mistaken for
@@ -314,14 +340,14 @@ the complete current registry.
 
 The active reusable workflow surfaces are:
 
-- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile
+- `.github/workflows/.build-gate-profile.yml` for project-neutral Shifu Gate profile
   planning, capability-aware runner dispatch, receipt validation, and one
   stable aggregate check;
-- `.github/workflows/.auditable-demo.yml` for exact-artifact demo
+- `.github/workflows/.build-demo-adapter.yml` for exact-artifact demo
   qualification, transcript-bound renderer smoke, optional media rendering
   from the exact passing Gate bundle, and opt-in content-addressed web-delivery
   profiles with independently verified rendition roles;
-- `.github/workflows/.declarative-auditable-demo.yml` for standalone binary
+- `.github/workflows/public-build-demo.yml` for standalone binary
   consumers that provide only a versioned multi-demo argv scenario and exact
   same-run binary artifact coordinates; Buildchain owns isolated native
   capture, Gate, Release Passport, materialization, and protected README PRs;
@@ -329,10 +355,10 @@ The active reusable workflow surfaces are:
   artifact contracts;
 - `.github/workflows/build.yml` for the single-config channel router that uses
   `vN-alpha` during development/prerelease work and `vN` for stable releases;
-- `.github/workflows/release-candidate-promote.yml` for post-merge
+- `.github/workflows/public-release-promote.yml` for post-merge
   promote-only publication from a PR-stage release candidate, without a second
   heavy build;
-- `.github/workflows/.web-surface.yml` for preview, staging, production, and
+- `.github/workflows/public-release-web.yml` for preview, staging, production, and
   cleanup plans for site/app repositories;
 - `.github/workflows/self-release-promote.yml` for protected release
   promotion and version-state transactions;
@@ -343,7 +369,7 @@ Stable consumers should reference actions and workflows through floating major
 refs after reviewing the exact release passport:
 
 ```yaml
-uses: kungfu-systems/buildchain/actions/validate-config@v4
+uses: kungfu-systems/buildchain/actions/build/lifecycle/validate@v4
 ```
 
 ```yaml
@@ -351,7 +377,7 @@ uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4
 ```
 
 ```yaml
-uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4
+uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v4
 ```
 
 ## Release Model

package/actions/build/artifact/prepare-attestation/README.md

@@ -0,0 +1,26 @@
+---
+status: active
+period: ongoing
+theme: github-artifact-attestation
+doc_type: action-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-10
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-10
+  visible_context: Action metadata and attestation transaction source.
+  invisible_context_boundary: No hosted publication qualification is claimed.
+---
+
+# Prepare a GitHub artifact attestation
+
+Validate the exact subject bytes, platform manifest, release Passport and signer policy before calling the external attestation action. The action runs on Node 24 and verifies the selected Buildchain runtime commit.
+
+Supply `runtime-sha`, `subject-path`, `platform-manifest-path`, `release-passport-path` and `policy-json`. The outputs include the verified subject digest, predicate path and `preparation-json` consumed by the sealing action.
+
+Use the public reusable artifact-attestation workflow for the complete credential and provider boundary. [`action.yml`](action.yml) defines the exact input/output contract; [`seal-attestation`](../seal-attestation/README.md) verifies the provider result.

package/actions/build/artifact/seal-attestation/README.md

@@ -0,0 +1,26 @@
+---
+status: active
+period: ongoing
+theme: github-artifact-attestation
+doc_type: action-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-10
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-10
+  visible_context: Action metadata and attestation transaction source.
+  invisible_context_boundary: No hosted publication qualification is claimed.
+---
+
+# Seal a GitHub artifact attestation
+
+Verify the external provider result against the preparation record and unchanged subject bytes, then retain the attestation bundle and rooted evidence. The action runs on Node 24 and rechecks the exact selected runtime commit.
+
+Supply `runtime-sha`, `preparation-json`, `bundle-path`, `attestation-id`, `attestation-url` and an explicit read `token`. The outputs identify the retained bundle digest and evidence root. Provider failure or subject drift prevents sealing.
+
+Use the public reusable artifact-attestation workflow for the complete credential and provider boundary. [`action.yml`](action.yml) defines the exact contract; [`prepare-attestation`](../prepare-attestation/README.md) owns pre-provider validation.

package/actions/build/lifecycle/run/README.md

@@ -0,0 +1,71 @@
+# run-lifecycle
+
+Run a Buildchain lifecycle stage or an explicit command and write a deterministic
+artifact manifest.
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/build/lifecycle/run@v3
+  with:
+    stage: build
+    required: "true"
+    artifact-name: my-product-linux-x64-${{ github.sha }}
+    artifact-paths: |
+      dist
+      build/stage
+```
+
+When `command` is provided, it overrides `buildchain.toml` for that invocation.
+When `command` is empty, the action loads `buildchain.toml` and runs the named
+stage.
+
+`timeout-minutes` defaults to 120 and bounds either command source. A
+stage-specific `timeout_minutes` in `buildchain.toml` takes precedence. Timeout
+errors identify the lifecycle stage and platform so a hung self-hosted build can
+be diagnosed after the runner is released.
+
+The action writes both a full manifest and a compact summary. It also exposes
+the summary as outputs for reusable workflow callers:
+
+For a `build` stage, paths selected by `[[signing.artifacts]]` for the current
+`platform-id` are automatically included in the lifecycle manifest even when
+they sit outside `artifact-paths`. This binds every byte sent to the signing
+authority without changing which ordinary product paths the caller uploads.
+
+| Output | Meaning |
+| --- | --- |
+| `manifest-path` | Full manifest path |
+| `summary-path` | Compact summary path |
+| `artifact-name` | Resolved artifact name |
+| `artifact-file-count` | Number of manifest files |
+| `artifact-total-bytes` | Total manifest bytes |
+| `artifact-summary-json` | One-line JSON summary |
+| `expected-artifacts-ok` | `true` when expectations passed |
+
+`expected-artifacts-json` can require exact paths, file count bounds, and a
+minimum byte total:
+
+```yaml
+with:
+  expected-artifacts-json: >-
+    {"minFiles":2,"requiredPaths":["dist/app.tar.gz","dist/checksums.txt"]}
+```
+
+For long native builds, set `sample-process-tree: "true"` and pass
+`process-summary-path`. The action wraps either the explicit `command` or the
+configured lifecycle stage with `buildchain sample process-tree`, then embeds
+the produced summary in the lifecycle diagnostics artifact:
+
+```yaml
+with:
+  stage: build
+  sample-process-tree: "true"
+  process-summary-path: .buildchain/diagnostics/process-summary.json
+```
+
+Custom wrappers can still pass an existing sampler report or summary with
+`process-summary-path`; the action reads it after the lifecycle command
+finishes, so commands may generate the file during the same invocation.
+Set `process-summary-required: "false"` when the summary is an optional sidecar,
+for example when a reusable workflow may skip an optional build stage.
+The diagnostics directory also includes `diagnostics-manifest.json`, a compact
+inventory of the diagnostics sidecars with byte counts and sha256 hashes.

package/actions/build/lifecycle/validate/README.md

@@ -0,0 +1,52 @@
+---
+status: active
+period: ongoing
+theme: buildchain-config-validation-action
+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
+---
+
+# validate-config
+
+Buildchain v3 action for validating `.buildchain/buildchain.toml` without running lifecycle
+commands.
+
+Use this action during repository migration when a heavyweight project needs to
+prove that its Buildchain version state and lifecycle declaration are ready, but
+the actual build should not run yet.
+
+## Usage
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/build/lifecycle/validate@v3
+  with:
+    require-version-state: "true"
+    require-lifecycle-stages: "install,build,verify"
+```
+
+The action checks:
+
+- `buildchain.toml` exists and uses schema `1`;
+- configured version-state files exist and expose a string version;
+- anchored/manual version strategy declarations and JSON/TOML anchor manifests
+  are structurally valid when configured;
+- web-surface project, channel, deploy adapter, retention, and staging security
+  declarations are structurally valid when configured;
+- required lifecycle stages are declared and structurally valid.
+
+It does not execute `lifecycle.install`, `lifecycle.build`, `lifecycle.verify`,
+or any other lifecycle command.
+
+Outputs include `project-type`, `project-name`, `project-site`, `channels`, and
+`deploy-adapters-json`, so callers can route site workflows without reparsing
+TOML in every repository.