@kungfu-tech/buildchain 2.8.7-alpha.1 → 2.8.7

package/dist/site/release-provenance.json

@@ -22,6 +22,7 @@
       "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
       "./site/site-manifest.json": "./dist/site/site-manifest.json",
+      "./site/page-registry.json": "./dist/site/page-registry.json",
       "./site/cli-registry.json": "./dist/site/cli-registry.json",
       "./site/manual-registry.json": "./dist/site/manual-registry.json",
       "./site/node-api-registry.json": "./dist/site/node-api-registry.json",

package/dist/site/site-manifest.json

@@ -11,7 +11,20 @@
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
+  "source": {
+    "homepageTextSource": "README.md",
+    "docsMap": "docs/MAP.md",
+    "siteFactsDir": "dist/site"
+  },
   "docs": [
+    {
+      "id": "map",
+      "title": "Buildchain documentation map",
+      "path": "docs/MAP.md",
+      "plane": "use",
+      "exists": true,
+      "digest": "sha256:b5cfef531ba8ca655d8d66ffe0e530a0ca2c971daad5880943d2b824216ed043"
+    },
     {
       "id": "install",
       "title": "Install and verify Buildchain",
@@ -44,6 +57,22 @@
       "exists": true,
       "digest": "sha256:36899140a9b2e9ce1565ed41f3d64f73a8829fad3d59a04b9498d9479c85c4be"
     },
+    {
+      "id": "consumer-issue-reporting",
+      "title": "Consumer issue reporting",
+      "path": "docs/consumer-issue-reporting.md",
+      "plane": "use",
+      "exists": true,
+      "digest": "sha256:8e2159312e47b42ab0bb644cb195362150acc8872e6ac0e7380ece0c5cf36955"
+    },
+    {
+      "id": "infra-contract",
+      "title": "Infra Contract",
+      "path": "docs/infra-contract.md",
+      "plane": "use",
+      "exists": true,
+      "digest": "sha256:7826e8c70ac2d90ddd8d4e38bcdd1bcfa36eef5106431d7ad94b2fe9c8d3d5dc"
+    },
     {
       "id": "toolkit-observability",
       "title": "Toolkit observability",
@@ -58,7 +87,23 @@
       "path": "docs/site-bundle-contract.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:e6b4f2e76c713063ff750b0a8d6d96595addae2fd48f913744dc86559add0641"
+      "digest": "sha256:1977091fc18b816208e7af50a177fd15e114498bfa49041573812405b46585aa"
+    },
+    {
+      "id": "migration-inventory",
+      "title": "Migration inventory",
+      "path": "docs/migration-inventory.md",
+      "plane": "verify",
+      "exists": true,
+      "digest": "sha256:80018cf78785431e67bbc5278d82dda80d0baa320cdb5e4abda26a0b05e5c0bc"
+    },
+    {
+      "id": "ownership",
+      "title": "Ownership",
+      "path": "docs/ownership.md",
+      "plane": "why",
+      "exists": true,
+      "digest": "sha256:49074fb520c404d3c9f5b49b33562d4bdc4e3ed407cf22543fa8e19e312a6b8e"
     },
     {
       "id": "product-mechanism",
@@ -116,6 +161,14 @@
       "exists": true,
       "digest": "sha256:0a2f46501a64905067cc5872b45ac4824f9e632d59bfdfb2f6a794dfc5f959ea"
     },
+    {
+      "id": "runtime-train-validation",
+      "title": "Runtime train validation",
+      "path": "docs/runtime-train-validation.md",
+      "plane": "verify",
+      "exists": true,
+      "digest": "sha256:bb053594407bd0f78aa43352a249a2ffa19825374147cc712cd56ca6ad50dfa3"
+    },
     {
       "id": "versioning",
       "title": "Versioning",
@@ -130,18 +183,11 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:796e891819f03f0a7ac91f56f1bb74d9e3443d8bb0bee33a3cd053d70bde6a62"
-    },
-    {
-      "id": "infra-contract",
-      "title": "Infra Contract",
-      "path": "docs/infra-contract.md",
-      "plane": "use",
-      "exists": true,
-      "digest": "sha256:7826e8c70ac2d90ddd8d4e38bcdd1bcfa36eef5106431d7ad94b2fe9c8d3d5dc"
+      "digest": "sha256:61891635707e9ed27b8754b83713db61cf9a7a6bdf65beb6a9ac8aa39356e168"
     }
   ],
   "facts": [
+    "page-registry.json",
     "cli-registry.json",
     "manual-registry.json",
     "node-api-registry.json",

package/dist/site/workflow-registry.json

@@ -54,6 +54,11 @@
       "id": "promote-buildchain-ref",
       "path": "actions/promote-buildchain-ref",
       "status": "active"
+    },
+    {
+      "id": "report-buildchain-issue",
+      "path": "actions/report-buildchain-issue",
+      "status": "active"
     }
   ]
 }

package/docs/runtime-train-validation.md

@@ -0,0 +1,123 @@
+# Runtime Train Validation
+
+Buildchain consumers should keep stable workflow refs such as `@v2` in
+committed workflow YAML. Runtime trains provide a temporary validation pointer
+for Buildchain changes that are ready for downstream testing but not yet
+promoted through the normal `dev -> alpha -> release` chain.
+
+## Train refs
+
+A train ref is a branch in the Buildchain repository:
+
+```text
+train/v2/v2.3/<capability>
+```
+
+It is a validation pointer, not a release channel:
+
+- it does not move `v2`, `vX.Y`, `vX.Y-alpha`, exact tags, npm dist-tags, or
+  production refs;
+- it must not be pinned as a long-term production dependency;
+- it should point at the Buildchain commit that downstream maintainers are
+  expected to validate;
+- it is not a pending merge target or a delivery state;
+- the final durable path is still a pull request into the active `dev/*`
+  channel, followed by the requested alpha or release promotion.
+- it may remain for a retention window after release so initiating repositories
+  have a stable fast-use and rollback channel while stable refs, caches, or
+  rollout windows settle.
+
+## Buildchain contributor requirement
+
+When a Buildchain change needs downstream validation before stable refs move,
+publish a train ref before asking consumers to test it:
+
+```sh
+git push origin HEAD:refs/heads/train/v2/v2.3/<capability>
+```
+
+Use a capability slug that names the behavior being validated, for example:
+
+```text
+train/v2/v2.3/runtime-loader
+train/v2/v2.3/toolkit-diagnostics
+train/v2/v2.3/site-source-of-truth
+```
+
+The pull request or validation request should include the train ref, the exact
+commit SHA it points to, and the downstream evidence expected from consumers.
+If the train is refreshed, state the new SHA in the validation thread.
+
+After downstream validation succeeds, close out through the normal release
+path. Merge the Buildchain pull request into the active `dev/*` mainline, run
+the requested alpha or release promotion, and record the final mainline commit
+plus release ref or tag in the delivery thread. Do not leave the train as the
+item that still needs to be merged; it is only a temporary fast-use,
+diagnostic, and rollback channel for initiating repositories. Retained trains
+are cleaned up by a separate periodic Buildchain cleanup task.
+
+## Consumer workflow requirement
+
+Consumers keep their reusable workflow pinned to the stable shell:
+
+```yaml
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+```
+
+To validate a train without committing temporary workflow refs, expose a
+trusted manual pass-through once:
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      buildchain-ref:
+        description: "Temporary Buildchain runtime ref for trusted manual validation"
+        required: false
+        default: ""
+
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    with:
+      buildchain-ref: ${{ inputs.buildchain-ref || '' }}
+```
+
+Buildchain initializes new package workflows with this pass-through. Existing
+consumers that do not have it should add it once before validating a train.
+
+## Validation request
+
+Use this short request when a train is ready:
+
+```text
+Buildchain train ready: buildchain-ref=train/v2/v2.3/<capability>.
+Keep uses: ...@v2; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.
+```
+
+The consumer should run a trusted `workflow_dispatch`, paste the train ref into
+`buildchain-ref`, and report the workflow summary or aggregate Buildchain
+summary. The evidence should include:
+
+- workflow shell ref;
+- requested runtime ref;
+- resolved runtime ref;
+- resolved runtime SHA;
+- stability class;
+- trust decision;
+- rollback ref.
+
+## Trust and limitation
+
+Runtime overrides fail closed unless the event is `workflow_dispatch` and the
+actor has write, maintain, or admin permission on the caller repository.
+Pull requests, including fork-originated pull requests, cannot use a non-empty
+`buildchain-ref`.
+
+Runtime train validation covers Buildchain runtime scripts, CLI code, local
+actions, configuration parsing, and lifecycle behavior. It cannot validate
+changes that require the outer reusable workflow YAML itself to change, such as
+new jobs, permissions, workflow outputs, or matrix topology. Those changes need
+a canary workflow path or a temporary explicit workflow ref.

package/docs/site-bundle-contract.md

@@ -27,6 +27,17 @@ dist/site/
 ```
 
 `buildchain-site.json` is the top-level bundle entrypoint.
+It includes a `homepage` object generated from `README.md`, including
+`homepage.sections`, `homepage.displayPlan`, and a
+`homepage.rendererContract` that is implementation metadata rather than
+ordinary homepage copy. Site repositories should consume those fields instead
+of parsing `README.md` themselves.
+It also includes a `pages` collection that mirrors `page-registry.json`, so a
+site repository can build the full Buildchain public documentation surface from
+the npm package without scanning the source checkout.
+`page-registry.json` is the complete page fact source: README homepage content,
+all packaged `docs/*.md` manuals, action README files, the Node API package
+overview, and fixture guides.
 `buildchain-contract.json` is the machine-readable Buildchain runtime contract
 world used by floating-ref contract locks. It records public workflow/action/CLI
 surfaces, compatibility digests, and audit digests for the files that implement
@@ -73,6 +84,9 @@ this gate, so release candidates cannot publish an out-of-date site bundle.
 
 The P0 bundle includes:
 
+- README-derived homepage fields and display plan;
+- complete markdown page registry for public Buildchain docs, action manuals,
+  Node API overview, and fixtures;
 - site manifest;
 - CLI command registry;
 - manual registry for packaged agent-facing documentation;
@@ -96,3 +110,19 @@ schema metadata without breaking existing consumers.
 release chain model. The site bundle exposes that document and the
 `release-propagation` CLI entry so downstream sites can render the current
 Buildchain-owned propagation contract instead of hand-writing it.
+
+## Rendering Boundary
+
+Buildchain owns the homepage wording, section ordering intent, complete
+markdown page registry, release model facts, workflow/action registry, CLI
+registry, manual registry, Node API registry, KFD claim registry, and
+release-passport evidence vocabulary. The site owns HTML, CSS, responsive
+layout, navigation, visual assets, decorative media, markdown-to-HTML rendering,
+and progressive disclosure within the Buildchain-provided
+`homepage.displayPlan` and page metadata.
+
+The page registry is also part of Buildchain's KFD-3 collaboration-interface
+surface. Releases declare it as a site-consumption contract, and Buildchain's
+KFD-3 witness generation includes the underlying markdown sources as public
+documentation surfaces. If a page is public enough for the site to render, it
+must be declared and hash-bound in the package-owned site bundle.

package/docs/web-surface-deployments.md

@@ -416,7 +416,7 @@ The reusable workflow maps GitHub events to Buildchain web-surface semantics:
 | --- | --- |
 | `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |
 | `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |
-| `push` to `main` | validate, build, verify, and plan `staging` from the merged `main` SHA |
+| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |
 | `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |
 | `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |
 
@@ -493,10 +493,18 @@ When enabled, Buildchain owns the full release apply state machine:
   role, then write a staging release feedback passport artifact and comment the
   associated merged PR with the staging URL, source SHA, artifact identity, run
   URL, and failure context when apply did not complete.
+- When `production-release-on-main=true`, successful staging applies open or
+  update a Buildchain-owned release PR from
+  `release/<channel>-<short-sha>` to `main`, unless the current push already
+  came from a matching release PR merge. The release PR contains one empty
+  release-intent commit, carries `production-release-label`, and includes the
+  staging URLs, source SHA, artifact hash, and staging release-passport artifact
+  link in the PR body.
 - Release pull requests that match the configured production gate get a
   Buildchain review comment with the staging URL and production target, so the
   operator can verify staging from the PR page and use merge as the approval
-  action.
+  action. Consumers do not need to hand-write `gh pr create` or production
+  release-intent glue.
 - Production runs when `production-apply` is true and either:
   - a trusted `workflow_dispatch` passes `production-approved=true`; or
   - `production-release-on-main=true` and the `main` push commit is associated
@@ -535,15 +543,17 @@ jobs:
       production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
       production-release-on-main: true
       production-release-label: buildchain-release
-      production-release-head-prefix: feature/release-
+      production-release-head-prefix: release/
+      production-release-branch-channel: production
       production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions
       production-environment: production
 ```
 
 The merge button becomes the production approval only for a PR that carries the
-release label and comes from the configured source-branch prefix. Ordinary
-pull requests merged into `main` keep the staging plan behavior and do not
-publish production.
+release label and comes from the configured source-branch prefix. Ordinary pull
+requests merged into `main` deploy staging and open a release-intent PR; merging
+that release PR triggers production. A release PR merge push does not open
+another release PR.
 
 Apply-only inputs are validated before the caller build or verification command
 runs. If the current event would run preview, staging, or production apply,
@@ -552,9 +562,12 @@ on manual dispatch fail immediately instead of spending the build and plan jobs
 first.
 
 Callers must grant `id-token: write` for OIDC role assumption. Preview comments
-also need `pull-requests: write`. The AWS roles remain caller-owned and should
-be scoped by channel: preview can mutate only preview resources, staging can
-mutate only staging resources, and production can mutate only production
+need `pull-requests: write`. Automatic release PR creation also needs
+`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can
+create the release branch, write the empty release-intent commit, open or update
+the PR, and apply the release label. The AWS roles remain caller-owned and
+should be scoped by channel: preview can mutate only preview resources, staging
+can mutate only staging resources, and production can mutate only production
 resources.
 
 Apply mode fails closed when the deploy config still contains placeholder AWS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.7-alpha.1",
+  "version": "2.8.7",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -25,6 +25,7 @@
     "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
     "./site/site-manifest.json": "./dist/site/site-manifest.json",
+    "./site/page-registry.json": "./dist/site/page-registry.json",
     "./site/cli-registry.json": "./dist/site/cli-registry.json",
     "./site/manual-registry.json": "./dist/site/manual-registry.json",
     "./site/node-api-registry.json": "./dist/site/node-api-registry.json",
@@ -48,27 +49,7 @@
     "dist/site/",
     "README.md",
     "SECURITY.md",
-    "docs/MAP.md",
-    "docs/binary-distribution.md",
-    "docs/cli.md",
-    "docs/install.md",
-    "docs/infra-contract.md",
-    "docs/consumer-issue-reporting.md",
-    "docs/lifecycle-protocol.md",
-    "docs/migration-inventory.md",
-    "docs/ownership.md",
-    "docs/product-mechanism.md",
-    "docs/publish-transaction.md",
-    "docs/release-passport.md",
-    "docs/release-propagation.md",
-    "docs/release-candidate.md",
-    "docs/release-flow.md",
-    "docs/release-governance.md",
-    "docs/reusable-build-surface.md",
-    "docs/site-bundle-contract.md",
-    "docs/toolkit-observability.md",
-    "docs/versioning.md",
-    "docs/web-surface-deployments.md",
+    "docs/*.md",
     "actions/*/README.md",
     "fixtures/*/README.md"
   ],
@@ -98,7 +79,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@kungfu-tech/kfd": "github:kungfu-systems/kfd#1731900b81150ae29095329892b8d7d5670f2314",
+    "@kungfu-tech/kfd": "1.0.0-alpha.16",
     "smol-toml": "1.7.0"
   }
 }

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

@@ -7,12 +7,17 @@ export const BUILDCHAIN_KFD_CLAIM_REGISTRY_CONTRACT = "kungfu-buildchain-kfd-cla
 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: "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: "release-propagation", title: "Release propagation", path: "docs/release-propagation.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: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
@@ -20,14 +25,15 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { 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" },
-  { id: "infra-contract", title: "Infra Contract", path: "docs/infra-contract.md", plane: "use" },
 ]);
 
 const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/buildchain-site.json",
   "dist/site/site-manifest.json",
+  "dist/site/page-registry.json",
   "dist/site/cli-registry.json",
   "dist/site/manual-registry.json",
   "dist/site/node-api-registry.json",
@@ -68,6 +74,26 @@ const EXTRA_KFD1_FILES = Object.freeze([
   "scripts/ensure-github-release.mjs",
 ]);
 
+function immediateReadmes(root, dir) {
+  const absoluteDir = path.join(root, dir);
+  if (!fs.existsSync(absoluteDir)) return [];
+  return fs.readdirSync(absoluteDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => `${dir}/${entry.name}/README.md`)
+    .filter((relPath) => fileExists(root, relPath))
+    .sort();
+}
+
+function publicDocumentationFiles(root) {
+  return uniquePaths([
+    ...BUILDCHAIN_AGENT_MANUALS.map((entry) => entry.path),
+    "README.md",
+    "packages/core/README.md",
+    ...immediateReadmes(root, "actions"),
+    ...immediateReadmes(root, "fixtures"),
+  ]);
+}
+
 function readJson(root, relPath, fallback = {}) {
   const filePath = path.join(root, relPath);
   if (!fs.existsSync(filePath)) {
@@ -176,6 +202,7 @@ export function createBuildchainPublicClaimDefinitions() {
       artifactPaths: [
         "dist/site/manual-registry.json",
         "dist/site/node-api-registry.json",
+        "dist/site/page-registry.json",
         "dist/site/buildchain-site.json",
         "dist/site/site-manifest.json",
       ],
@@ -254,10 +281,14 @@ export function createBuildchainKfdSurfaceRegistry({ root = process.cwd() } = {}
         name: specifier === "." ? pkg.name : `${pkg.name}/${specifier.replace(/^\.\//, "")}`,
       },
     ));
-  const docs = BUILDCHAIN_AGENT_MANUALS.map((manual) => surface(`doc:${manual.id}`, "documentation", manual.path, {
-    name: manual.title,
-    plane: manual.plane,
-  }));
+  const manualTitles = new Map(BUILDCHAIN_AGENT_MANUALS.map((manual) => [manual.path, manual]));
+  const docs = publicDocumentationFiles(root).map((relPath) => {
+    const manual = manualTitles.get(relPath);
+    return surface(`doc:${relPath}`, "documentation", relPath, {
+      name: manual?.title || relPath,
+      plane: manual?.plane || (relPath.startsWith("actions/") ? "action" : relPath.startsWith("fixtures/") ? "fixture" : "use"),
+    });
+  });
   const schemas = SCHEMA_AND_STANDARD_FILES.map((relPath) => surface(`schema:${relPath}`, "schema", relPath));
   const standardsMetadata = [
     surface("metadata:package-json", "standards-metadata", "package.json"),
@@ -305,7 +336,7 @@ export function createBuildchainKfd1Witness({ root = process.cwd(), sourceSha =
   const registry = createBuildchainKfdClaimRegistry({ root, sourceSha });
   const registrySha256 = sha256Json(registry);
   const paths = uniquePaths([
-    ...BUILDCHAIN_AGENT_MANUALS.map((entry) => entry.path),
+    ...publicDocumentationFiles(root),
     ...SCHEMA_AND_STANDARD_FILES,
     ...SITE_CONTRACT_FILES,
     ...WORKFLOW_AND_ACTION_FILES,