@kungfu-tech/buildchain 4.0.2-alpha.9 → 4.0.3-alpha.0

package/AGENTS.md

@@ -79,21 +79,30 @@ 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
+`architecture/platform-stage-checkpoints.json`. Agents must use that single
 platform/stage declaration for shadow emission and clean-process restore. Do
 not add undeclared runner-only inputs, outputs, environment, provider effects,
 credentials, or production stage-skipping authority.
 
 Stage Capsule resume planning is governed by
-`architecture/v4-stage-capsule-resume-planner.json`. Keep its Rust core and
+`architecture/stage-capsule-resume-planner.json`. Keep its Rust core and
 TypeScript projection pure and byte-identical; explicit provider/release-tail
 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
+`architecture/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`,
@@ -123,7 +132,7 @@ failures in the train/public contract; never solve recursion with an internal ex
 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-v4-public-dogfood-contract.mjs`; changing this rule, its gate, or
+`scripts/check-public-dogfood-contract.mjs`; changing this rule, its gate, or
 the protected caller requires independent `@kungfu-origin` review.
 
 `pnpm run check` validates inventory data, generated public references and site

package/CONTRIBUTING.md

@@ -1,3 +1,22 @@
+---
+status: active
+period: ongoing
+theme: buildchain-contributing
+doc_type: process-rule
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-07
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-07
+  visible_context: Repository contribution rules and implementation naming and release transition changes.
+  invisible_context_boundary: No private credentials or unpublished external release state.
+---
+
 # Contributing to Buildchain
 
 Thanks for your interest in Buildchain. This guide covers how to build the
@@ -73,6 +92,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
@@ -143,3 +186,18 @@ By contributing you agree that your contributions are licensed under the
 project's [Apache License 2.0](LICENSE). Buildchain uses the Developer
 Certificate of Origin (DCO) and does not require a Contributor License Agreement
 (CLA).
+
+## Implementation names
+
+Name implementation directories, scripts, functions, and runtime work directories
+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
+domains, selectors, runner labels, API compatibility keys, and exact historical
+evidence keep their established identities; they do not name new implementations.
+
+Stable completion under `semver/auto` prepares the next patch at `alpha.0` from
+the exact current protected development commit. See the generated
+[next-development contract](docs/next-development-transition.md) for retry,
+independent review, and publication-preservation behavior.

package/README.md

@@ -291,7 +291,7 @@ direct consumer integration actions:
 - `actions/promote-buildchain-ref`
 - `actions/report-buildchain-issue`
 - `actions/release-tail`
-- `actions/v4-release-candidate-promote`
+- `actions/release-candidate-promote`
 
 Two additional release-authority components are also registered and versioned:
 
@@ -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/release-candidate-promote/README.md

@@ -0,0 +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.