@kungfu-tech/buildchain 4.0.2-alpha.4 → 4.0.2-alpha.40

package/AGENTS.md

@@ -79,6 +79,15 @@ pnpm install --frozen-lockfile
 pnpm run check
 ```
 
+Workflow paths are governed by [`architecture/workflow-taxonomy.json`](architecture/workflow-taxonomy.json)
+and the generated [`Workflow Catalog`](docs/workflow-catalog.md). Before adding,
+renaming, or editing workflow YAML, register its role (`public`, component `.`,
+or `self`) and category (`build`, `release`, or `ops`). Use the derived filename;
+do not invent prefixes, categories, or compatibility aliases. Edit canonical
+implementations, run `pnpm run generate:workflows`, and pass
+`pnpm run check:workflows` plus the full check. Taxonomy and gate changes require
+independent `@kungfu-origin` review through CODEOWNERS.
+
 Buildchain v4 Stage Capsule checkpoint work is governed by
 `architecture/v4-platform-stage-checkpoints.json`. Agents must use that single
 platform/stage declaration for shadow emission and clean-process restore. Do
@@ -93,7 +102,7 @@ effects always require readback and never become Capsule reuse.
 Stage Capsule qualification and Wave 2 reconciliation are governed by
 `architecture/v4-stage-capsule-qualification.json`. Buildchain v4 dogfood is a
 repository invariant, not an implementation convenience: this repository must
-consume `kungfu-systems/buildchain/.github/workflows/v4-stage-capsule-canary.yml`
+consume `kungfu-systems/buildchain/.github/workflows/public-build-stage-capsule-canary.yml`
 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`,

package/CONTRIBUTING.md

@@ -73,6 +73,30 @@ pnpm run build
 npm pack --dry-run --json --registry=https://registry.npmjs.org/
 ```
 
+## Workflow organization
+
+All workflows remain directly under `.github/workflows/`. The finite role and
+category vocabulary is enforced by `architecture/workflow-taxonomy.json`:
+
+| Role | Filename | Scope |
+| --- | --- | --- |
+| Public | `public-<category>-<purpose>.yml` | Consumer entry |
+| Component | `.<category>-<purpose>.yml` | Advanced reusable component |
+| Self | `self-<category>-<purpose>.yml` | Buildchain repository automation |
+
+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.
+
+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.
+
 ## Generated files
 
 GitHub Actions consume committed bundles. When changing an action

package/README.md

@@ -324,9 +324,9 @@ The active reusable workflow surfaces are:
   heavy build;
 - `.github/workflows/.web-surface.yml` for preview, staging, production, and
   cleanup plans for site/app repositories;
-- `.github/workflows/buildchain-ref-promotion.yml` for protected release
+- `.github/workflows/self-release-promote.yml` for protected release
   promotion and version-state transactions;
-- `.github/workflows/binary-distribution.yml` for Buildchain's own release
+- `.github/workflows/self-build-binary-distribution.yml` for Buildchain's own release
   passport proof case.
 
 Stable consumers should reference actions and workflows through floating major

package/actions/promote-buildchain-ref/README.md

@@ -310,7 +310,7 @@ Buildchain itself uses this path for npm. Its `lifecycle.publish` runs
 `node scripts/npm-publish-transaction.mjs`, which publishes
 `@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm
 artifact evidence into the transaction before release refs move. The separate
-`.github/workflows/npm-publish.yml` workflow is dry-run only.
+`.github/workflows/self-release-npm-dry-run.yml` workflow is dry-run only.
 
 Publish lifecycle environment:
 

package/actions/v4-release-candidate-promote/README.md

@@ -1,3 +1,31 @@
+---
+status: active
+period: ongoing
+theme: protected-publication-source
+doc_type: reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-06
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-06
+  visible_context: Publication adapter, regression tests, and public GitHub commit metadata.
+  invisible_context_boundary: No credentials or private runtime state inspected.
+---
+
 # v4 release-candidate promote action
 
 This internal action validates a sealed v4 publication qualification receipt, aggregates the Buildchain Release Passport, and executes the fixed four-capability Release Tail Provider Plane. It has no command or shell extension input and is invoked by the v4 branch of the reusable `release-candidate-promote` workflow.
+
+The protected publication source must match the qualified candidate's exact
+Git tree. An exact commit is accepted directly; a final PR merge may also bind
+through identical ordered parents. For repositories requiring linear history,
+`squash-equivalent` requires a protected commit with one parent, a qualified
+merge candidate with two parents, and the same first parent. GitHub must report
+the exact PR as merged into the protected commit, and its head must equal the
+candidate's second parent. Candidate qualification, workflow and repository
+provenance, and artifact verification remain required before publication.

package/architecture/agent-change-map.md

@@ -54,7 +54,6 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 - sources: `packages/core/readme-badges.js`
 - sources: `packages/core/release-candidate.js`
 - sources: `packages/core/release-passport.js`
-- sources: `packages/core/release-tail-provider-plane.js`
 - sources: `packages/core/release-train.js`
 - sources: `packages/core/stable-release-gate.js`
 - sources: `packages/core/v4-runtime-ref-resume-authority.js`
@@ -84,6 +83,7 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 - sources: `scripts/run-lifecycle-core.mjs`
 - sources: `scripts/stable-candidate-patrol.mjs`
 - sources: `scripts/stable-release-gate.mjs`
+- sources: `scripts/v4-universal-workflow-engine.mjs`
 - sources: `scripts/v4-architecture.mjs`
 - sources: `scripts/v4-warrant-shadow-plan.mjs`
 - sources: `scripts/web-surface-core.mjs`
@@ -92,6 +92,9 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 - sources: `actions/promote-buildchain-ref/internal/promotion-operations.js`
 - rust: `crates/buildchain-v4-bridge/src/main.rs`
 - rust: `crates/buildchain-v4-contracts/src/main.rs`
+- rust: `crates/buildchain-v4-contracts/src/product_publication.rs`
+- rust: `crates/buildchain-v4-contracts/src/release_tail.rs`
+- rust: `crates/buildchain-v4-contracts/src/wasm.rs`
 - rust: `crates/buildchain-v4-contracts/src/provider_operation_journal.rs`
 - rust: `crates/buildchain-v4-contracts/src/provider_operation_journal/fold.rs`
 - rust: `crates/buildchain-v4-contracts/src/warrant.rs`
@@ -150,12 +153,20 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 
 ### Current top twenty maintenance hotspots
 
+- `.github/workflows/.build.yml`
+- `.github/workflows/.publication-authority.yml`
+- `.github/workflows/bootstrap.yml`
+- `scripts/check-v4-universal-workflow-bootstrap.mjs`
+- `scripts/v4-universal-workflow-engine.mjs`
+- `tests/v4-universal-workflow-bootstrap.test.mjs`
 - `tests/v3-v4-capability-inventory.test.mjs`
 - `tests/v4-floating-consumer-policy-contract.test.mjs`
 - `tests/v4-publication-qualification.test.mjs`
 - `.github/workflows/v4-adopter-delivery.yml`
 - `.github/workflows/buildchain-ref-promotion.yml`
+- `.github/workflows/dev-pr-auto-merge.yml`
 - `tests/release-candidate-recovery.test.mjs`
+- `tests/buildchain-ref-promotion-recovery-entry.test.mjs`
 - `.github/workflows/.release-candidate-promote.yml`
 - `tests/build-surface-promotion.test.mjs`
 - `.github/workflows/buildchain-ref-promotion-recovery.yml`
@@ -166,9 +177,13 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 - `.github/workflows/release-candidate-promote.yml`
 - `actions/promote-buildchain-ref/lib.js`
 - `actions/v4-release-candidate-promote/index.js`
+- `actions/v4-release-candidate-promote/product-provider.js`
+- `actions/v4-release-candidate-promote/product-provider-github-adapters.js`
+- `tests/v4-release-candidate-promote.test.mjs`
 - `scripts/check-inventory.mjs`
 - `tests/promote-buildchain-ref.test.mjs`
 - `tests/promotion-channel-router.test.mjs`
+- `tests/v4-release-topology.test.mjs`
 - `scripts/site-capability-metadata.mjs`
 - `tests/v4-floating-consumer-policy.test.mjs`
 - `tests/v4-declarative-promotion-mode.test.mjs`
@@ -183,6 +198,8 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 - `scripts/buildchain-cli-help.mjs`
 - `scripts/check-maintainability.mjs`
 - `tests/maintainability.test.mjs`
+- `scripts/generate-v4-universal-workflow-facades.mjs`
+- `scripts/check-v4-release-topology.mjs`
 
 ## cli-command-registry
 
@@ -383,6 +400,7 @@ Owner: Buildchain action maintainers
 
 ### Implementation
 
+- `actions/promote-buildchain-ref/internal/contained-published-version-state.js`
 - `actions/promote-buildchain-ref/internal/promote-alpha-channel.js`
 - `actions/promote-buildchain-ref/internal/promote-major-channel.js`
 - `actions/promote-buildchain-ref/internal/promote-release-channel.js`
@@ -394,6 +412,7 @@ Owner: Buildchain action maintainers
 
 ### Tests
 
+- `tests/promote-buildchain-ref-contained-published-version-state.test.mjs`
 - `tests/promote-buildchain-ref.test.mjs`
 - `tests/promote-buildchain-ref-recovery.test.mjs`
 - `tests/promote-buildchain-ref-governance.test.mjs`
@@ -405,7 +424,7 @@ Owner: Buildchain action maintainers
 
 ### Minimal validation
 
-- `node --test tests/promote-buildchain-ref.test.mjs tests/promote-buildchain-ref-recovery.test.mjs tests/promote-buildchain-ref-governance.test.mjs tests/promotion-responsibilities.test.mjs`
+- `node --test tests/promote-buildchain-ref-contained-published-version-state.test.mjs tests/promote-buildchain-ref.test.mjs tests/promote-buildchain-ref-recovery.test.mjs tests/promote-buildchain-ref-governance.test.mjs tests/promotion-responsibilities.test.mjs`
 
 ## promotion-github-transaction-store
 
@@ -638,6 +657,7 @@ Owner: Buildchain contract maintainers
 
 - `packages/core/buildchain-contract.js`
 - `scripts/build-contract-core.mjs`
+- `scripts/github-output.mjs`
 
 ### Contracts
 
@@ -649,6 +669,7 @@ Owner: Buildchain contract maintainers
 - `tests/buildchain-contract.test.mjs`
 - `tests/build-surface.test.mjs`
 - `tests/build-surface-promotion.test.mjs`
+- `tests/github-output.test.mjs`
 
 ### Generated outputs
 
@@ -722,8 +743,8 @@ Owner: Buildchain adopter delivery maintainers
 - `contracts/fixtures/v4-adopter-delivery-v1/gate-positive.json`
 - `contracts/fixtures/v4-adopter-delivery-v1/gate-unknown-selector.json`
 - `contracts/fixtures/v4-adopter-delivery-v1/offline-vectors.json`
-- `.github/workflows/v4-adopter-delivery.yml`
-- `.github/workflows/v4-adopter-delivery-dogfood.yml`
+- `.github/workflows/public-build-adopter-qualification.yml`
+- `.github/workflows/self-build-adopter-dogfood.yml`
 - `docs/v4-adopter-delivery.md`
 
 ### Tests
@@ -820,7 +841,7 @@ Owner: Buildchain architecture maintainers
 - `architecture/v4-tail-reseal-parity.json`
 - `contracts/v4-tail-reseal-v1.schema.json`
 - `contracts/fixtures/v4-tail-reseal-v1/valid.json`
-- `.github/workflows/v4-tail-reseal.yml`
+- `.github/workflows/public-ops-tail-reseal.yml`
 - `docs/v4-stage-capsule.md`
 - `docs/v4-runtime-ref-resume-authority.md`
 - `docs/v4-tail-reseal.md`
@@ -935,7 +956,7 @@ Owner: Buildchain protected delivery maintainers
 - `contracts/dev-delivery-authority-v2.schema.json`
 - `dist/site/schemas/dev-delivery-authority-v2.schema.json`
 - `.github/workflows/dev-pr-auto-merge.yml`
-- `.github/workflows/buildchain-dev-delivery.yml`
+- `.github/workflows/self-ops-dev-delivery.yml`
 - `templates/native-dev-delivery.yml`
 - `docs/dev-delivery-warrant.md`
 - `docs/dev-delivery-qualification-landing-adr.md`
@@ -977,7 +998,7 @@ Owner: Buildchain publication rehearsal maintainers
 
 - `architecture/v4-publication-rehearsal-parity.json`
 - `contracts/v4-publication-rehearsal-capsule-v1.schema.json`
-- `.github/workflows/v4-publication-rehearsal-dogfood.yml`
+- `.github/workflows/self-release-rehearsal-dogfood.yml`
 - `docs/v4-publication-rehearsal.md`
 
 ### Tests
@@ -992,6 +1013,44 @@ Owner: Buildchain publication rehearsal maintainers
 
 - `node --test tests/v4-publication-rehearsal.test.mjs`
 
+## v4-universal-workflow-bootstrap
+
+Owner: Buildchain workflow maintainers
+
+### Implementation
+
+- `packages/core/v4-universal-workflow-bootstrap.js`
+- `scripts/check-v4-universal-workflow-bootstrap.mjs`
+- `scripts/generate-v4-universal-workflow-facades.mjs`
+- `scripts/v4-universal-workflow-backflow.mjs`
+- `scripts/v4-universal-workflow-engine.mjs`
+- `scripts/v4-universal-workflow-self-dogfood.mjs`
+
+### Contracts
+
+- `architecture/v4-universal-workflow-bootstrap.json`
+- `architecture/v4-universal-workflow-fault-campaign.json`
+- `architecture/v4-universal-workflow-train-admission.json`
+- `.github/workflows/bootstrap.yml`
+- `.github/workflows/self-ops-bootstrap-dogfood.yml`
+- `templates/universal-buildchain-bootstrap-recovery.yml`
+
+### Tests
+
+- `tests/v4-universal-workflow-backflow.test.mjs`
+- `tests/v4-universal-workflow-bootstrap.test.mjs`
+- `tests/v4-universal-workflow-fault-campaign.test.mjs`
+- `tests/v4-universal-workflow-self-dogfood.test.mjs`
+
+### Generated outputs
+
+- `.github/workflows/universal-bootstrap-recovery.yml`
+
+### Minimal validation
+
+- `node scripts/check-v4-universal-workflow-bootstrap.mjs`
+- `node --test tests/v4-universal-workflow-bootstrap.test.mjs tests/v4-universal-workflow-backflow.test.mjs tests/v4-universal-workflow-fault-campaign.test.mjs tests/v4-universal-workflow-self-dogfood.test.mjs`
+
 ## web-surface-delivery
 
 Owner: Buildchain web-surface maintainers