@kungfu-tech/buildchain 3.0.9-alpha.8 → 4.0.0-alpha.0

package/docs/engineering-housekeeper.md

@@ -29,9 +29,17 @@ their heads are already ancestors of a mainline.
 The reusable entrypoint is:
 
 ```yaml
-uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v4
 ```
 
+The v4 surface is a traceable forward-port of protected v3 merge
+`c9d53c69e90393b2178ad7cdbf00f17e403e17f9` and exact source
+`518990c4118a12562eb9847cb2e1b704983909a0`. It preserves the same `v1`
+contract, temporary-family allowlist, provider adapter, mutation fences, and
+evidence roots. The v4 manifest records that TypeScript remains the sole
+legacy-authoritative writer; the forward-port does not create another contract
+or provider authority. Existing v3 callers retain their original interface.
+
 ## Report mode
 
 `report` is the default. The caller grants only read permissions and receives
@@ -40,7 +48,7 @@ separate plan, Markdown report, and dry-run receipt artifacts:
 ```yaml
 jobs:
   housekeeper:
-    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v4
     permissions:
       contents: read
       pull-requests: read
@@ -81,7 +89,7 @@ An unattended scheduled caller can set both values in committed policy.
 ```yaml
 jobs:
   housekeeper:
-    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v4
     permissions:
       contents: write
       pull-requests: write
@@ -120,7 +128,7 @@ continue.
 | `max-actions`               | number  | `20`                        | Positive global apply limit.                                                      |
 | `artifact-retention-days`   | number  | `30`                        | Retention for plan, report, and receipts.                                         |
 | `buildchain-repository`     | string  | `kungfu-systems/buildchain` | Runtime source repository.                                                        |
-| `buildchain-ref`            | string  | `v3`                        | Runtime ref; trusted manual qualification may pass a train or exact SHA.          |
+| `buildchain-ref`            | string  | `v4`                        | Runtime ref; trusted qualification may pass a train or exact SHA.                 |
 
 Stable outputs are `plan-root`, `report-receipt-root`, optional
 `branch-receipt-root` and `pull-request-receipt-root`, `action-count`,

package/docs/getting-started.md

@@ -83,7 +83,7 @@ The generated caller should contain one reusable `uses:` edge and a manual
 ```bash
 rg -n 'uses:|buildchain-ref:' .github/workflows/build.yml
 pnpm exec buildchain release --dry-run \
-  --target-ref alpha/v3/v3.0 \
+  --target-ref alpha/v4/v4.0 \
   --json
 ```
 

package/docs/install.md

@@ -6,8 +6,8 @@ adopting a new version.
 
 ## Standalone Binary
 
-Buildchain v3.0.0 does not publish standalone platform archives. This section
-documents the verified legacy binary release contract; v3 consumers should use
+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.
 
 Use the archive that matches the platform:
@@ -64,7 +64,7 @@ Stable consumers should pin the exact Buildchain version they have validated,
 for example:
 
 ```bash
-pnpm add -D @kungfu-tech/buildchain@3.0.0
+pnpm add -D @kungfu-tech/buildchain@4.0.0
 ```
 
 If a repository dogfoods a just-published Buildchain version and pnpm's release
@@ -74,7 +74,7 @@ all packages:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@kungfu-tech/buildchain@3.0.0'
+  - '@kungfu-tech/buildchain@4.0.0'
 ```
 
 Remove that entry after the package is old enough for the repository's normal
@@ -89,7 +89,7 @@ packages.
 ```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/v3/v3.0
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v4/v4.0
 ```
 
 Use `.buildchain/buildchain.toml` to declare lifecycle commands. The commands may use Node

package/docs/kfd-support.md

@@ -77,13 +77,8 @@ KFD records and evidence by SHA-256. The result uses
 `buildchain kfd support project` derives a compatibility projection from the
 standard adopter manifest and its exact passing gate. The adopter manifest is
 the sole KFD-1..13 declaration authority; the command rejects stale package,
-source, witness, registry, verifier-set, and KFD-4/5/7 gate roots. Gate creation
-accepts an explicit `expectedAdopterId`, `expectedSourceRepository`, and
-`expectedSourceSha`; omitting the first two preserves the Buildchain
-self-release default. The gate, every product-gate projection, the legacy
-matrix, Release Passport, and artifact evidence all retain that exact
-adopter/repository/source closure. The emitted matrix is not an independent
-declaration and cannot widen adopter claims.
+source, witness, registry, verifier-set, and KFD-4/5/7 gate roots. The emitted
+matrix is not an independent declaration and cannot widen adopter claims.
 
 ## KFD-1
 

package/docs/lifecycle-protocol.md

@@ -301,10 +301,8 @@ and optionally `lifecycle.publish`.
 The verify stage runs after Buildchain has applied the generated version-state
 changes to the local checkout, and before it creates release commits or moves
 refs. After the command finishes, Buildchain checks that only declared
-`version.files` and `version.derived_files` changed. The latter declares tracked
-outputs regenerated by `lifecycle.version-state` that do not directly contain a
-version field. This prevents verification from quietly adding extra source
-changes to the release commit while keeping generated evidence explicit.
+version-state files changed. This prevents verification from quietly adding
+extra source changes to the release commit.
 
 Buildchain-owned untracked runtime evidence is excluded only through an exact
 internal allowlist. This includes contract-drift issue material under