@kungfu-tech/buildchain 3.0.4-alpha.0 → 3.0.4-alpha.10

package/docs/release-propagation.md

@@ -67,10 +67,12 @@ The upstream release envelope is the post-finalization fact set:
   "channel": "alpha",
   "tag": "v1.4.0-alpha.3",
   "sourceSha": "1111111111111111111111111111111111111111",
+  "tagTargetSha": "1111111111111111111111111111111111111111",
   "package": {
     "name": "@kungfu-tech/kfd",
     "version": "1.4.0-alpha.3",
-    "integrity": "sha512-..."
+    "integrity": "sha512-...",
+    "gitHead": "1111111111111111111111111111111111111111"
   },
   "releasePassport": {
     "url": "https://github.com/kungfu-systems/kfd/releases/download/v1.4.0-alpha.3/buildchain.release.json",
@@ -82,8 +84,10 @@ The upstream release envelope is the post-finalization fact set:
 }
 ```
 
-The package version and integrity must be exact. Downstream build logic should
-install that version directly, not resolve `alpha` or `latest` again.
+The package version, integrity, and npm `gitHead` must be exact. The exact tag
+must be `v<version>`, and `gitHead`, tag target, and `sourceSha` must describe
+the same source commit before propagation is admitted. Downstream build logic
+installs that version directly and never resolves `alpha` or `latest` again.
 
 Publication repositories can propagate immutable publication archive evidence
 without npm package facts. The upstream envelope then includes
@@ -95,6 +99,7 @@ without npm package facts. The upstream envelope then includes
   "channel": "alpha",
   "tag": "v0.1.0-alpha.1",
   "sourceSha": "4444444444444444444444444444444444444444",
+  "tagTargetSha": "4444444444444444444444444444444444444444",
   "releasePassport": {
     "url": "https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/buildchain.release.json",
     "sha256": "5555555555555555555555555555555555555555555555555555555555555555"
@@ -200,6 +205,157 @@ The receipt keeps four machine states separate:
 
 Package publication or alpha completion never implies either visibility state.
 
+## Agent-native work envelope
+
+Setting `agent-work-mode: capture-only` makes a finalized release emit a
+resumable delivery handoff without mutating the downstream repository. Passing
+an exact `agent-work-context-json` instead emits an already-authorized unit.
+Buildchain emits one
+`kungfu-buildchain-release-propagation-work` v1 envelope per exact release and
+downstream target. This is a Buildchain domain execution contract, not another
+Work Control database or authority.
+
+The envelope binds:
+
+- the exact normalized upstream release and release-lock roots;
+- the downstream repository, channel, base ref, expected base SHA, managed
+  branch, lock path, and propagation key;
+- exact parent and child `kungfu.assignment-graph.work-ref/v1` values derived
+  from the immutable release and downstream plan;
+- either a pending Family binding or one exact
+  `kungfu.work-control.initiative-family-state/v2` coordinate;
+- capture-only or end-to-end execution authority, including an active typed
+  execution-Warrant reference for execution;
+- explicit publish-to-production intent, deterministic commands, canonical
+  ordered stages, a recovery cursor, stage receipts, supersession policy, and
+  a content root.
+
+The ordered stages are:
+
+```text
+materialize -> verify-release -> push-branch -> pull-request -> preview
+-> independent-review -> protected-merge -> staging -> production-release
+-> production-deploy -> online-readback -> complete
+```
+
+`pull-request` and `protected-merge` are intermediate states. Only exact online
+readback followed by an accepted Work Control Decision can record `complete`.
+Every state transition uses expected-old fencing against the current work
+content root. An identical initial envelope has the same work id and root;
+newer releases receive distinct propagation keys and must name an explicit
+superseded work root when they replace unfinished work.
+
+The context has this shape (roots abbreviated here only for readability):
+
+```json
+{
+  "parentWorkRef": {
+    "schema": "kungfu.assignment-graph.work-ref/v1",
+    "workspace_identity_root": "sha256:<64 hex>",
+    "object_kind": "initiative",
+    "subject": "paper-publication",
+    "version_root": "sha256:<64 hex>",
+    "cut_root": "sha256:<64 hex>"
+  },
+  "childWorkRef": {
+    "schema": "kungfu.assignment-graph.work-ref/v1",
+    "workspace_identity_root": "sha256:<64 hex>",
+    "object_kind": "assignment",
+    "subject": "site-propagation",
+    "version_root": "sha256:<64 hex>",
+    "cut_root": "sha256:<64 hex>"
+  },
+  "familyState": {
+    "schema": "kungfu.work-control.initiative-family-state/v2",
+    "stateRoot": "sha256:<64 hex>",
+    "v1ProjectionRoot": "sha256:<64 hex>",
+    "typedBindingRoot": "sha256:<64 hex>",
+    "factWorld": "<owning fact world>",
+    "cutRoot": "sha256:<64 hex>"
+  },
+  "authority": {
+    "mode": "capture-only",
+    "publishToProduction": false,
+    "allowedActions": [],
+    "executionPrincipal": null,
+    "sourceControlPrincipal": null,
+    "executionWarrant": null
+  },
+  "supersedesWorkRoot": ""
+}
+```
+
+Automatic capture emits deterministic Buildchain-owned release and propagation
+WorkRefs, leaves `workControl.bindingState` as `pending`, emits no Family State
+or Warrant, and performs no downstream write. Claiming that unit supplies the
+exact Family State v2 coordinate and active Warrant while preserving the work
+identity. An executing input must carry an active Warrant at the same Family
+State fact world and cut, explicit production intent, and the complete supported
+action set. It also binds the acting Agent principal and the source-control
+principal that authors the PR. Buildchain never invents external Work Control
+authority.
+
+A managed Paper opts into automatic capture with a thin, source-controlled
+`.buildchain/release-propagation.json`. The sealed release workflow reads that
+exact file from the released Paper SHA only after npm, tag, Passport, and
+publication evidence agree. It emits one paused work artifact per declared
+target; publication itself does not open a Site PR.
+
+```json
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-paper-release-propagation",
+  "sourceNode": "paper-example",
+  "graph": {
+    "schemaVersion": 1,
+    "contract": "kungfu-buildchain-release-propagation-graph",
+    "nodes": [],
+    "edges": []
+  },
+  "targets": ["site-libkungfu-dev"]
+}
+```
+
+Each graph target owns an exact GitHub web-surface execution profile: workflow,
+base and managed branch, lock path, consumer commands, production status URL,
+and production artifact readback URLs. The sealed workflow rejects extra config
+fields, unknown targets, or a target whose base revision cannot be resolved.
+
+The reusable workflow keeps its prior behavior when `agent-work-mode` is
+`legacy` (the default). Managed Paper callers set `capture-only`; an Agent later
+claims the emitted artifact and resumes from its machine-readable `next_action`.
+
+Agent entrypoints are machine-readable and restart-safe:
+
+```bash
+buildchain release-propagation work create ... --output work.json --json
+buildchain release-propagation work status --work work.json --json
+buildchain release-propagation work resume --work work.json --json
+buildchain release-propagation work claim ... --output successor.json --json
+buildchain release-propagation work receipt ... --output receipt.json --json
+buildchain release-propagation work record ... --output successor.json --json
+buildchain release-propagation work repair ... --output successor.json --json
+buildchain release-propagation work complete ... --output successor.json --json
+```
+
+Known operational races (`stale-branch`, `expected-old-mismatch`,
+`lockfile-drift`, `failed-check`, `interrupted-execution`, and `ci-delay`) return
+a retryable repair action. Semantic ambiguity, missing credentials, policy
+expansion, and unknown failures stop at `needs-decision`. Release-contract
+mismatch, immutable-artifact conflict, and destructive recovery stop at a hard
+safety gate. Evidence locators containing signed or credential parameters are
+rejected.
+
+Successful stage receipts are typed, not generic progress notes. In particular,
+the pushed-branch receipt hashes the full expected-old branch reconciliation;
+review binds an approved GitHub review and must come from an identity distinct
+from both the acting Agent and PR author; production deployment carries release,
+lock, deployed artifact, expected readback digest, and rollback coordinates; and
+online readback must cover the exact execution-profile URLs with HTTP 200,
+observed non-zero bytes, exact deployed Git revision, and matching release and
+artifact digests. The final receipt binds the accepted Work Control Decision
+root.
+
 ## Reusable Workflow
 
 Upstream repositories can call
@@ -257,11 +413,13 @@ can disable that step with `refresh-managed-readme-badges: false`.
 push, so consumers can use the same check as their PR workflow. Update,
 preparation, badge refresh, and verification failures all fail closed. The
 workflow stages the complete deterministic result, signs the propagation
-commit with DCO, and then opens or updates the PR. It does not publish the
-downstream release directly. The downstream repository keeps its normal
-Buildchain governance: the PR updates source-of-truth facts, then downstream
-alpha or release publication runs through its own protected channel. A
-byte-identical rerun is an explicit successful no-op.
+commit with DCO, and then opens or updates the PR. With no agent work context,
+the reusable workflow retains this backward-compatible PR boundary. With an
+executing work context, it records materialization, verification, branch, and
+PR receipts and returns `preview` as the next action; the authorized Agent then
+continues through the downstream repository's normal protected review,
+publication, deployment, and readback entrypoints. A byte-identical rerun is an
+explicit successful no-op, never a synthetic completion.
 
 For unreleased runtime validation, keep the caller's reusable workflow reference
 on `@v3` and pass a temporary train ref through `buildchain-ref`.

package/docs/site-bundle-contract.md

@@ -58,8 +58,13 @@ those surfaces.
 `manual-registry.json` enumerates the packaged Markdown manuals with source
 digests so an agent can find complete operating documentation from the npm
 artifact. `node-api-registry.json` enumerates public Node import surfaces from
-`package.json#exports`, so agents do not have to infer supported APIs from
-internal paths.
+`package.json#exports` and closes each JavaScript subpath over its exact exported
+symbols. Each symbol includes its source-derived signature and parameters,
+conservative return/error contract, detected side effects, maturity, example
+import, and source location, so agents do not have to infer supported APIs from
+internal paths. `cli-registry.json` similarly retains every governed command
+path, syntax, option, alias, and side-effect-free help command projected from
+the runtime registry and usage authority.
 `kfd-claims.json` is the Buildchain-owned KFD claim registry. It is generated
 from `packages/core/buildchain-kfd-claims.js` and enumerates the public release
 claims plus the KFD-3 collaboration surfaces that Buildchain self-verifies
@@ -130,6 +135,7 @@ import siteManifest from "@kungfu-tech/buildchain/site/site-manifest.json" with
 ## Generation
 
 ```bash
+pnpm run generate:reference
 pnpm run generate:site
 pnpm run check:site
 ```
@@ -148,9 +154,9 @@ The P0 bundle includes:
   Node API overview, and fixtures;
 - site manifest;
 - publication archive registry for downstream papers surfaces;
-- CLI command registry;
+- CLI command registry plus full-path generated human reference;
 - manual registry for packaged agent-facing documentation;
-- Node API registry for public package exports;
+- Node API registry plus per-symbol generated human reference for public package exports;
 - workflow/action registry;
 - release model facts;
 - artifact and evidence schema index;

package/docs/versioning.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-08-01
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -79,9 +79,10 @@ repository changes are patch".
 
 | Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |
 | ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| 2026-07-31 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add an opt-in responsive profile that binds source-resolution and exact 1280x720 MP4/WebM/GIF renditions to one Gate and receipt while rejecting upscales, aspect-ratio drift, and profile changes between Gate-only and full-render paths.                                                                                              |       |
-| 2026-07-31 | extend-minor | `v3.0`  | release-candidate-family-evidence, release-passport-evidence-attachment, promotion-action, release-passport-cli                                                             | additive | Restore all-ref v2 parity for optional Initiative-family candidate binding and typed product-owned release evidence attachments while retaining Kungfu native Family State authority and the newer v3 post-activation released-evidence stage.                                                                                         | #2089 |
-| 2026-07-30 | extend-minor | `v3.0`  | reusable-build-workflow, observed-evidence-bundle, release-passport-json-reader, web-surface-release-governance                                                               | additive | Add bounded artifact compression and remote-read controls plus transactional derived evidence projections while repairing release-PR runtime handoff so production remains protected-main-only.                                                                                                                                       |       |
+| 2026-08-01 | extend-minor | `v3.0`  | cli-reference-registry, node-api-symbol-registry, golden-path-manual                                                                                                         | additive | Add generated, drift-checked CLI and Node API reference registries to the public site bundle, plus a package-tested first-user Golden Path; existing command execution and import semantics remain unchanged.                                                                                                                          |       |
+| 2026-07-31 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add an opt-in responsive profile that binds source-resolution and exact 1280x720 MP4/WebM/GIF renditions to one Gate and receipt while rejecting upscales, aspect-ratio drift, and profile changes between Gate-only and full-render paths.                                                                                            |       |
+| 2026-07-31 | extend-minor | `v3.0`  | release-candidate-family-evidence, release-passport-evidence-attachment, promotion-action, release-passport-cli                                                              | additive | Restore all-ref v2 parity for optional Initiative-family candidate binding and typed product-owned release evidence attachments while retaining Kungfu native Family State authority and the newer v3 post-activation released-evidence stage.                                                                                         | #2089 |
+| 2026-07-30 | extend-minor | `v3.0`  | reusable-build-workflow, observed-evidence-bundle, release-passport-json-reader, web-surface-release-governance                                                              | additive | Add bounded artifact compression and remote-read controls plus transactional derived evidence projections while repairing release-PR runtime handoff so production remains protected-main-only.                                                                                                                                        |       |
 | 2026-07-29 | extend-minor | `v3.0`  | artifact-signing-config, apple-developer-id-authority, artifact-signing-evidence                                                                                             | additive | Extend the consumer-neutral signing declaration to macOS compound archives, including nested wheel Mach-O signing, PEP 427 RECORD repair, safe archive reconstruction, and whole-product notarization under the same protected authority.                                                                                              |       |
 | 2026-07-28 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add opt-in archive, web-delivery, and site-hero profiles; independently bind codec, container, audio, layout, byte-budget, role, and fast-start facts into a v2 media receipt while preserving the existing archive default.                                                                                                           |       |
 | 2026-07-26 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-evidence                                                                                                                             | additive | Forward-port the consumer-neutral reusable Gate that binds exact same-run GitHub Artifacts to checked-in adapters and immutable renderer evidence, with optional media rendering only from the exact passing Gate bundle.                                                                                                              | #1862 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.4-alpha.0",
+  "version": "3.0.4-alpha.10",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -108,11 +108,14 @@
   },
   "packageManager": "pnpm@11.7.0",
   "scripts": {
-    "check": "pnpm run check:static && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && node scripts/check-action-bundles.mjs",
-    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json bin/internal/command-registry.mjs scripts/authorize-promotion-runtime-override.cjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/maintainability-metrics.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs",
+    "check": "pnpm run check:static && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
+    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json bin/internal/command-registry.mjs scripts/authorize-promotion-runtime-override.cjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/maintainability-metrics.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs",
     "check:workflows": "bash scripts/check-workflows.sh",
-    "generate:site": "node scripts/generate-site-bundle.mjs",
-    "check:site": "node scripts/generate-site-bundle.mjs --check",
+    "generate:reference": "node scripts/generate-public-reference.mjs",
+    "check:reference": "node scripts/generate-public-reference.mjs --check",
+    "generate:site": "pnpm run generate:reference && node scripts/generate-site-bundle.mjs",
+    "check:site": "pnpm run check:reference && node scripts/generate-site-bundle.mjs --check",
+    "check:golden-path": "node scripts/verify-golden-path.mjs",
     "test:unit": "node --test tests/*.test.mjs",
     "build": "pnpm -r --filter \"./actions/**\" build",
     "binary:build": "node scripts/build-standalone-binary.mjs",

package/packages/core/buildchain-agent-manuals.js

@@ -0,0 +1,37 @@
+export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
+  { id: "map", title: "Buildchain documentation map", path: "docs/MAP.md", plane: "use" },
+  { id: "getting-started", title: "Golden Path", path: "docs/getting-started.md", plane: "use" },
+  { id: "auditable-demo", title: "Auditable demo artifact pipeline", path: "docs/auditable-demo.md", plane: "verify" },
+  { id: "install", title: "Install and verify Buildchain", path: "docs/install.md", plane: "use" },
+  { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
+  { id: "github-artifact-attestation", title: "GitHub-native Linux artifact attestation", path: "docs/github-artifact-attestation.md", plane: "verify" },
+  { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },
+  { id: "publication-authority", title: "Sealed publication authority", path: "docs/publication-authority.md", plane: "verify" },
+  { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
+  { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
+  { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
+  { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
+  { id: "homebrew", title: "Homebrew distribution indexes", path: "docs/homebrew.md", plane: "use" },
+  { id: "binary-distribution", title: "Binary distribution contract", path: "docs/binary-distribution.md", plane: "verify" },
+  { id: "consumer-issue-reporting", title: "Consumer issue reporting", path: "docs/consumer-issue-reporting.md", plane: "use" },
+  { id: "infra-contract", title: "Infra Contract", path: "docs/infra-contract.md", plane: "use" },
+  { id: "toolkit-observability", title: "Toolkit observability", path: "docs/toolkit-observability.md", plane: "use" },
+  { id: "site-bundle-contract", title: "Site bundle contract", path: "docs/site-bundle-contract.md", plane: "use" },
+  { id: "migration-inventory", title: "Migration inventory", path: "docs/migration-inventory.md", plane: "verify" },
+  { id: "ownership", title: "Ownership", path: "docs/ownership.md", plane: "why" },
+  { id: "product-mechanism", title: "Product mechanism", path: "docs/product-mechanism.md", plane: "why" },
+  { id: "cli", title: "CLI and npm package", path: "docs/cli.md", plane: "use" },
+  { id: "cli-reference", title: "Generated CLI reference", path: "docs/cli-reference.md", plane: "use" },
+  { id: "node-api-reference", title: "Generated Node API reference", path: "docs/node-api-reference.md", plane: "use" },
+  { id: "build-facts", title: "Build Facts", path: "docs/build-facts.md", plane: "use" },
+  { id: "kfd-support", title: "KFD support and KFD-3 surface registration", path: "docs/kfd-support.md", plane: "verify" },
+  { id: "kfd-agent-hub", title: "KFD Agent Hub Builder flow", path: "docs/kfd-agent-hub.md", plane: "use" },
+  { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
+  { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
+  { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
+  { id: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
+  { id: "release-flow", title: "Release flow", path: "docs/release-flow.md", plane: "verify" },
+  { id: "runtime-train-validation", title: "Runtime train validation", path: "docs/runtime-train-validation.md", plane: "verify" },
+  { id: "versioning", title: "Versioning", path: "docs/versioning.md", plane: "why" },
+  { id: "web-surface-deployments", title: "Web surface deployments", path: "docs/web-surface-deployments.md", plane: "use" },
+]);

package/packages/core/buildchain-kfd-claims.js

@@ -7,45 +7,13 @@ import {
   collectPublicSurfaceReverseAudit,
 } from "./public-surface-audit.js";
 import { normalizeKfd3DistributionDeclaration } from "./kfd3-surface-register.js";
+import { BUILDCHAIN_AGENT_MANUALS } from "./buildchain-agent-manuals.js";
+
+export { BUILDCHAIN_AGENT_MANUALS } from "./buildchain-agent-manuals.js";
 
 export const BUILDCHAIN_KFD_CLAIM_REGISTRY_CONTRACT = "kungfu-buildchain-kfd-claim-registry";
 export const BUILDCHAIN_KFD_COLLABORATION_INTERFACE_CONTRACT = "kungfu-buildchain-kfd-collaboration-interface";
 
-export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
-  { id: "map", title: "Buildchain documentation map", path: "docs/MAP.md", plane: "use" },
-  { id: "auditable-demo", title: "Auditable demo artifact pipeline", path: "docs/auditable-demo.md", plane: "verify" },
-  { id: "install", title: "Install and verify Buildchain", path: "docs/install.md", plane: "use" },
-  { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
-  { id: "github-artifact-attestation", title: "GitHub-native Linux artifact attestation", path: "docs/github-artifact-attestation.md", plane: "verify" },
-  { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },
-  { id: "publication-authority", title: "Sealed publication authority", path: "docs/publication-authority.md", plane: "verify" },
-  { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
-  { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
-  { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
-  { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
-  { id: "homebrew", title: "Homebrew distribution indexes", path: "docs/homebrew.md", plane: "use" },
-  { id: "binary-distribution", title: "Binary distribution contract", path: "docs/binary-distribution.md", plane: "verify" },
-  { id: "consumer-issue-reporting", title: "Consumer issue reporting", path: "docs/consumer-issue-reporting.md", plane: "use" },
-  { id: "infra-contract", title: "Infra Contract", path: "docs/infra-contract.md", plane: "use" },
-  { id: "toolkit-observability", title: "Toolkit observability", path: "docs/toolkit-observability.md", plane: "use" },
-  { id: "site-bundle-contract", title: "Site bundle contract", path: "docs/site-bundle-contract.md", plane: "use" },
-  { id: "migration-inventory", title: "Migration inventory", path: "docs/migration-inventory.md", plane: "verify" },
-  { id: "ownership", title: "Ownership", path: "docs/ownership.md", plane: "why" },
-  { id: "product-mechanism", title: "Product mechanism", path: "docs/product-mechanism.md", plane: "why" },
-  { id: "cli", title: "CLI and npm package", path: "docs/cli.md", plane: "use" },
-  { id: "build-facts", title: "Build Facts", path: "docs/build-facts.md", plane: "use" },
-  { id: "kfd-support", title: "KFD support and KFD-3 surface registration", path: "docs/kfd-support.md", plane: "verify" },
-  { id: "kfd-agent-hub", title: "KFD Agent Hub Builder flow", path: "docs/kfd-agent-hub.md", plane: "use" },
-  { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
-  { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
-  { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
-  { id: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
-  { id: "release-flow", title: "Release flow", path: "docs/release-flow.md", plane: "verify" },
-  { id: "runtime-train-validation", title: "Runtime train validation", path: "docs/runtime-train-validation.md", plane: "verify" },
-  { id: "versioning", title: "Versioning", path: "docs/versioning.md", plane: "why" },
-  { id: "web-surface-deployments", title: "Web surface deployments", path: "docs/web-surface-deployments.md", plane: "use" },
-]);
-
 const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/buildchain-site.json",
   "dist/site/site-manifest.json",
@@ -203,7 +171,6 @@ function uniqueById(entries) {
     return true;
   });
 }
-
 function uniquePaths(paths) {
   return [...new Set(paths.filter(Boolean))].sort();
 }
@@ -411,7 +378,7 @@ export function createBuildchainPublicClaimDefinitions() {
     },
     {
       id: "claim:buildchain-release-propagation",
-      claim: "Buildchain can propagate upstream alpha or stable releases to downstream repositories while preserving release channels through exact release locks.",
+      claim: "Buildchain can propagate exact upstream releases as Family State v2 and WorkRef-bound, resumable downstream work that preserves protected review and completes only after production readback.",
       sourcePaths: [
         "packages/core/release-propagation.js",
         "scripts/release-propagation.mjs",

package/packages/core/controller-evidence.js

@@ -103,10 +103,16 @@ const CONTROLLER_SPECS = [
     id: "release-propagation",
     workflowId: "release-propagation",
     version: 1,
-    capabilities: ["release-propagation-plan", "downstream-lock", "pull-request-handoff"],
+    capabilities: [
+      "release-propagation-plan",
+      "downstream-lock",
+      "agent-native-work-envelope",
+      "resumable-production-handoff",
+    ],
     stages: [
       "resolve-runtime",
       "plan",
+      "emit-work",
       "write-lock",
       "prepare-consumer",
       "refresh-badges",
@@ -119,6 +125,7 @@ const CONTROLLER_SPECS = [
       "refresh-badges",
       "verify-consumer",
       "open-pr",
+      "emit-work",
     ],
     evidence: ["propagation-plan", "propagation-lock", "controller-receipt"],
   },

package/packages/core/index.js

@@ -590,19 +590,7 @@ export {
   writeKfd3SurfaceRegistry,
 } from "./kfd3-surface-register.js";
 
-export {
-  RELEASE_PROPAGATION_GRAPH_CONTRACT,
-  RELEASE_PROPAGATION_LOCK_CONTRACT,
-  RELEASE_PROPAGATION_PLAN_CONTRACT,
-  RELEASE_PROPAGATION_RECEIPT_CONTRACT,
-  createReleasePropagationReceipt,
-  createReleasePropagationLock,
-  normalizeReleasePropagationGraph,
-  planReleasePropagation,
-  readReleasePropagationJson,
-  resolvePropagationChannel,
-  writeReleasePropagationLock,
-} from "./release-propagation.js";
+export * from "./release-propagation.js";
 
 export {
   RELEASE_ACTIVATION_CONTRACT,

package/packages/core/paper-agent-entry.js

@@ -181,12 +181,8 @@ export function resolvePaperBuildchainSha(buildchainRoot, buildchainSha = "") {
   return GIT_SHA_PATTERN.test(observed) ? observed : "";
 }
 
-function expectedCiBranches(developmentRef) {
-  return [
-    developmentRef,
-    developmentRef.replace(/^dev\//, "alpha/"),
-    developmentRef.replace(/^dev\//, "release/"),
-  ];
+function expectedCiBranches(ref) {
+  return ["dev", "alpha", "release"].map((c) => ref.replace(/^dev/, c));
 }
 
 function ciContext({ env, developmentRef }) {
@@ -201,10 +197,17 @@ function ciContext({ env, developmentRef }) {
     env.GITHUB_REF_NAME || env.BUILDCHAIN_PAPER_REF_NAME || "",
   );
   const pullRequest = ["pull_request", "pull_request_target"].includes(event);
+  const channelBranches = expectedCiBranches(developmentRef);
+  const channelIndex = channelBranches.indexOf(targetBranch);
+  const versionStatePrefix = `buildchain/version-state/${targetBranch.replaceAll("/", "-")}/`;
+  const generatedVersionState =
+    channelBranches.includes(targetBranch) &&
+    sourceBranch.startsWith(versionStatePrefix) &&
+    /^[0-9a-f]{12}$/i.test(sourceBranch.slice(versionStatePrefix.length));
   const branchOk = pullRequest
-    ? PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) &&
-      targetBranch === developmentRef
-    : expectedCiBranches(developmentRef).includes(refName);
+    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) && targetBranch === developmentRef) ||
+      (channelIndex > 0 && sourceBranch === channelBranches[channelIndex - 1]) || generatedVersionState
+    : channelBranches.includes(refName);
   return {
     mode: "ci",
     event,
@@ -214,8 +217,8 @@ function ciContext({ env, developmentRef }) {
     pullRequest,
     ok: branchOk,
     message: pullRequest
-      ? `Pull requests must use an allowed work branch and target ${developmentRef}.`
-      : `Channel checks must run on ${expectedCiBranches(developmentRef).join(", ")}.`,
+      ? `Pull requests must target ${developmentRef} from an allowed work branch, promote adjacent protected channels, or carry an exact target-bound generated version state.`
+      : `Channel checks must run on ${channelBranches.join(", ")}.`,
   };
 }
 

package/packages/core/paper-fleet.js

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
-import { planPaperMigration, writePaperMigration } from "./paper.js";
+import {
+  planPaperMigration,
+  resolvePaperRuntimeGitSha,
+  writePaperMigration,
+} from "./paper.js";
 import {
   PAPER_PATHS,
   PAPER_WORK_BRANCH_PATTERN,
-  gitValue,
   paperWorkSource,
   readJson,
   rootedPlan,
@@ -51,10 +54,7 @@ function legacyBuildchainWorkflowRefs(cwd) {
   if (!fs.existsSync(workflowRoot)) return [];
   return fs
     .readdirSync(workflowRoot, { withFileTypes: true })
-    .filter(
-      (entry) =>
-        entry.isFile() && /\.ya?ml$/i.test(entry.name),
-    )
+    .filter((entry) => entry.isFile() && /\.ya?ml$/i.test(entry.name))
     .filter((entry) =>
       /uses:\s*kungfu-systems\/buildchain\/[^\s]+@v2(?:[-.][^\s]+)?/i.test(
         fs.readFileSync(path.join(workflowRoot, entry.name), "utf8"),
@@ -188,7 +188,9 @@ export function collectPaperFleetAudit({
     root: resolvedRoot,
     runtime: {
       version: buildchainVersion,
-      sha: buildchainSha || gitValue(buildchainRoot, ["rev-parse", "HEAD"]),
+      sha:
+        buildchainSha ||
+        resolvePaperRuntimeGitSha(buildchainRoot, buildchainVersion),
     },
     summary: {
       repositories: entries.length,
@@ -284,3 +286,28 @@ export function writePaperFleetUpdate(plan) {
     results,
   };
 }
+
+export function paperFleetTransitionWorkspace(workspaceText, lockText) {
+  const source = String(workspaceText || "");
+  if (!/@kungfu-tech\/buildchain@[0-9A-Za-z]/.test(String(lockText || ""))) {
+    return source;
+  }
+  const lines = source.replace(/\r\n/g, "\n").split("\n");
+  const keyIndex = lines.findIndex((line) =>
+    /^minimumReleaseAgeExclude:\s*(?:#.*)?$/.test(line),
+  );
+  if (keyIndex < 0) {
+    throw new Error(
+      "paper fleet lock refresh requires a generated minimumReleaseAgeExclude block",
+    );
+  }
+  const retained = lines.filter(
+    (line, index) =>
+      index <= keyIndex ||
+      !/^\s*-\s+['"]?@kungfu-tech\/buildchain(?:@[^'"\s]+)?['"]?\s*(?:#.*)?$/.test(
+        line,
+      ),
+  );
+  retained.splice(keyIndex + 1, 0, "  - '@kungfu-tech/buildchain'");
+  return retained.join("\n");
+}