@kungfu-tech/buildchain 2.8.15 → 2.8.16-alpha.1

package/dist/site/release-provenance.json

@@ -14,6 +14,7 @@
       "./buildchain-contract": "./packages/core/buildchain-contract.js",
       "./diagnostics": "./packages/core/diagnostics.js",
       "./issue-reporting": "./packages/core/issue-reporting.js",
+      "./readme-badges": "./packages/core/readme-badges.js",
       "./logging": "./packages/core/logging.js",
       "./kfd-gate": "./packages/core/kfd-gate.js",
       "./release-candidate": "./packages/core/release-candidate.js",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-07T13:50:19.556Z",
-  "publishedAt": "2026-07-07T13:50:19.556Z",
+  "generatedAt": "2026-07-07T14:53:34.643Z",
+  "publishedAt": "2026-07-07T14:53:34.643Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "2c3127f2954960ad89f5658a090fb9fe19b442ce",
+  "sourceRevision": "3f3734348d6c4217a0aaea924b3537c519ab141a",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.8.15",
+    "version": "2.8.16-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:b5cfef531ba8ca655d8d66ffe0e530a0ca2c971daad5880943d2b824216ed043"
+      "digest": "sha256:46fa21a0fd496ba1b2afc4209e4e923aba3656e4fe83f757108f24ceef977741"
     },
     {
       "id": "install",
@@ -79,6 +79,14 @@
       "exists": true,
       "digest": "sha256:190e3537075f37cf8a7e52bf8254606e1d9450d87c5a81dc11df8b56a7d03065"
     },
+    {
+      "id": "readme-badges",
+      "title": "README badge blocks",
+      "path": "docs/readme-badges.md",
+      "plane": "use",
+      "exists": true,
+      "digest": "sha256:3f4a44ea7f3b70cadc78a343fe53ade74b78fa369c19630cc9b926c1e460f66f"
+    },
     {
       "id": "binary-distribution",
       "title": "Binary distribution contract",
@@ -149,7 +157,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:a8a348181d6419b746e863d1cacc9d6a91aa6ac5cc2b60819843d44487957c49"
+      "digest": "sha256:c7928797300772ed5240ef69529af99298c32dbb74c3be7fbcad5ae0786576ce"
     },
     {
       "id": "lifecycle-protocol",

package/docs/MAP.md

@@ -25,6 +25,7 @@ manuals explain those facts and give operator examples.
 | npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |
 | GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |
 | release propagation for package/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |
+| Generated README badge blocks and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |
 | Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |
 | Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |
 
@@ -59,6 +60,7 @@ replace them.
 | How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |
 | How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |
 | How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |
+| How do I generate README status badges without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |
 | How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |
 | Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |
 | How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |
@@ -115,6 +117,8 @@ replace them.
   [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).
 - **release chains / upstream package as source of truth / site synchronization** ->
   [`release-propagation.md`](release-propagation.md).
+- **README status badges / KFD badge blocks / badge facts JSON** ->
+  [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).
 - **KFD-1 contract worlds / byte-for-byte release gates** ->
   [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).
 - **KFD-2 public release trust claim audit** ->

package/docs/cli.md

@@ -65,6 +65,7 @@ Current public import families include:
 import * as buildchain from "@kungfu-tech/buildchain";
 import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
 import { verifyKfd1ReleaseGate } from "@kungfu-tech/buildchain/kfd-gate";
+import { collectReadmeBadgeFacts } from "@kungfu-tech/buildchain/readme-badges";
 import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
 import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-propagation";
 import contractWorld from "@kungfu-tech/buildchain/site/buildchain-contract.json" with { type: "json" };
@@ -244,9 +245,26 @@ version against configured version files and the anchor manifest. The JSON
 result is shaped for future `buildchain.libkungfu.dev` fact ingestion.
 
 `buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,
-`buildchain publish-source`, and `buildchain build-contract` route to the same scripts used by Buildchain's
-GitHub Actions workflows. This keeps local inspection and CI behavior on the
-same implementation path.
+`buildchain publish-source`, `buildchain badges`, and `buildchain build-contract`
+route to the same implementation used by Buildchain's package APIs or GitHub
+Actions workflows. This keeps local inspection and CI behavior on the same
+implementation path.
+
+Generate, check, or update the managed README badge block:
+
+```bash
+buildchain badges readme --json
+buildchain badges readme --check
+buildchain badges readme --write
+```
+
+The `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.
+`--check` fails closed when the README marker block is missing or stale.
+`--write` inserts or replaces only the marked block. KFD passed badges come
+from the repository's own verified release passport; unreleased repositories
+downgrade to explicit local declarations such as `declared`, `aligned`, or
+`planned`. See [`readme-badges.md`](readme-badges.md) for the marker contract
+and `[badges]` configuration.
 
 `buildchain collect github-release` creates a release passport bundle from
 GitHub Release assets or a local asset directory:

package/docs/readme-badges.md

@@ -0,0 +1,124 @@
+# README Badge Blocks
+
+Buildchain can generate a managed README badge block from repository-owned
+facts. The README keeps only a projection; the source facts remain in
+`buildchain.toml`, package metadata, workflow files, and the repository's own
+release passport.
+
+The managed block is delimited by:
+
+```markdown
+<!-- buildchain:badges:start -->
+...
+<!-- buildchain:badges:end -->
+```
+
+Buildchain owns only that block. Everything outside the markers remains normal
+README content.
+
+## Node API
+
+Use the public package export:
+
+```js
+import {
+  collectReadmeBadgeFacts,
+  renderReadmeBadgeBlock,
+  checkReadmeBadgeBlock,
+  updateReadmeBadgeBlock,
+} from "@kungfu-tech/buildchain/readme-badges";
+```
+
+`collectReadmeBadgeFacts({ cwd })` returns a machine-readable object with
+contract `kungfu-buildchain-readme-badge-facts`. It collects repository
+identity, package name/version/license, configured platforms, configured
+workflow status badges, release passport location and verification result, and
+KFD badge state. When present, it also summarizes local KFD claim registry and
+product-mechanism facts from the package-owned site bundle, so downstream
+agents can connect README badges back to Buildchain's KFD/source-of-truth
+surfaces.
+
+`renderReadmeBadgeBlock(facts)` renders deterministic Markdown from that facts
+object. `checkReadmeBadgeBlock({ readmeText, facts })` compares the current
+README marker block against the expected block and reports missing or stale
+drift. `updateReadmeBadgeBlock({ readmeText, facts })` inserts or replaces the
+managed block.
+
+The Node API is the implementation source. The CLI delegates to it.
+
+## CLI
+
+Generate facts as JSON:
+
+```bash
+buildchain badges readme --json
+```
+
+Fail closed when the README block is missing or stale:
+
+```bash
+buildchain badges readme --check
+```
+
+Insert or replace the block:
+
+```bash
+buildchain badges readme --write
+```
+
+All commands accept `--cwd <dir>` and `--readme <path>`. Repositories can add
+`buildchain badges readme --check` to CI so badge drift is detected like any
+other generated release-facing surface.
+
+## Configuration
+
+The optional `[badges]` table in `buildchain.toml` declares local facts that
+cannot be inferred safely:
+
+```toml
+[badges]
+release_passport = "https://github.com/example/project/releases/latest/download/buildchain.release.json"
+kfd_1 = "declared"
+kfd_2 = "planned"
+kfd_3 = "aligned"
+platforms = ["macOS", "Linux", "Windows"]
+workflows = ["verify.yml", "build.yml"]
+```
+
+`release_passport` may be a local path or URL. If omitted, Buildchain tries
+`buildchain.release.json`, then `.buildchain/release-passport/buildchain.release.json`,
+then the repository's latest GitHub Release asset when the GitHub repository
+can be discovered.
+
+## KFD Badge Rules
+
+KFD passed is evidence-backed. A repository may display `KFD-1 passed`,
+`KFD-2 passed`, or `KFD-3 passed` only when its own release passport verifies
+successfully and the corresponding passport section has `status: "passed"`.
+
+When no release passport exists yet, or when the passport cannot be verified,
+Buildchain downgrades each KFD badge to the explicit local declaration such as
+`declared`, `aligned`, or `planned`. A local `passed` declaration is treated as
+`declared`; unknown local states are normalized to a non-passed fallback.
+
+Buildchain's own README may link to Buildchain's own release passport. Other
+repositories must not claim Buildchain's KFD status as their own; their badge
+links must point to their own release passport or evidence page.
+
+## CI Contract
+
+Recommended CI gate:
+
+```bash
+buildchain badges readme --check
+```
+
+The check fails when:
+
+- the marker block is missing;
+- generated Markdown differs from repository facts;
+- a previously hand-written KFD passed claim is not backed by the repository's
+  verified release passport facts.
+
+The machine-readable facts object should be used by downstream site renderers
+or audit tools when Markdown badges are not enough.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.15",
+  "version": "2.8.16-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -17,6 +17,7 @@
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./diagnostics": "./packages/core/diagnostics.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
+    "./readme-badges": "./packages/core/readme-badges.js",
     "./logging": "./packages/core/logging.js",
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",

package/packages/core/README.md

@@ -14,6 +14,8 @@ Current shared surfaces:
   `@kungfu-tech/buildchain/diagnostics`;
 - release passport creation and verification through
   `@kungfu-tech/buildchain/release-passport`.
+- managed README badge facts and marker blocks through
+  `@kungfu-tech/buildchain/readme-badges`.
 
 ## Toolkit Imports
 
@@ -53,3 +55,13 @@ const { collectRunnerDiagnostics } = await import("@kungfu-tech/buildchain/diagn
 Web-surface validation stays in core because both local scripts and GitHub
 Actions need the same fail-closed interpretation of project, channel, deploy,
 retention, and staging security declarations.
+
+README badge consumers should import the public subpath and treat Markdown as a
+projection of the returned facts:
+
+```js
+import { collectReadmeBadgeFacts, renderReadmeBadgeBlock } from "@kungfu-tech/buildchain/readme-badges";
+
+const facts = await collectReadmeBadgeFacts({ cwd: process.cwd() });
+const markdown = renderReadmeBadgeBlock(facts);
+```

package/packages/core/buildchain-contract.js

@@ -309,6 +309,7 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
       optionalInputs: [
         "validate",
         "lifecycle",
+        "badges readme",
         "collect github-release",
         "verify release-passport",
         "release-propagation",
@@ -316,6 +317,31 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
       ],
       guarantees: [
         "CLI commands are stable within the major line unless the contract major changes",
+        "README badge block checks and writes are generated from machine-readable repository facts",
+      ],
+    }),
+    surface(root, {
+      id: "readme-badge-facts",
+      kind: "node-api",
+      path: "packages/core/readme-badges.js",
+      requiredInputs: ["repository checkout"],
+      requiredOutputs: ["kungfu-buildchain-readme-badge-facts"],
+      breakingDefaults: {
+        markerStart: "<!-- buildchain:badges:start -->",
+        markerEnd: "<!-- buildchain:badges:end -->",
+        kfdPassedSource: "verified repository-owned release passport",
+      },
+      optionalInputs: [
+        "buildchain.toml [badges]",
+        "release passport URL or local path",
+        "workflow file list",
+        "platform declarations",
+      ],
+      guarantees: [
+        "README badge Markdown is a deterministic projection of badge facts",
+        "KFD passed badges require the repository's own verified release passport section",
+        "unreleased repositories downgrade KFD status to explicit non-passed declarations",
+        "CLI and JavaScript callers use the same Node API implementation",
       ],
     }),
     surface(root, {

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

@@ -11,6 +11,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { 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: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.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" },
@@ -195,9 +196,11 @@ export function createBuildchainPublicClaimDefinitions() {
       sourcePaths: [
         "scripts/generate-site-bundle.mjs",
         "packages/core/buildchain-kfd-claims.js",
+        "packages/core/readme-badges.js",
         "docs/MAP.md",
         "docs/site-bundle-contract.md",
         "docs/cli.md",
+        "docs/readme-badges.md",
       ],
       artifactPaths: [
         "dist/site/manual-registry.json",
@@ -207,6 +210,22 @@ export function createBuildchainPublicClaimDefinitions() {
         "dist/site/site-manifest.json",
       ],
     },
+    {
+      id: "claim:buildchain-readme-badge-facts",
+      claim: "Buildchain README status badges are generated from repository-owned facts and verified release-passport evidence, not hand-maintained README prose.",
+      sourcePaths: [
+        "packages/core/readme-badges.js",
+        "bin/buildchain.mjs",
+        "docs/readme-badges.md",
+        "docs/cli.md",
+        "buildchain.toml",
+      ],
+      artifactPaths: [
+        "dist/site/node-api-registry.json",
+        "dist/site/manual-registry.json",
+        "dist/site/buildchain-contract.json",
+      ],
+    },
     {
       id: "claim:buildchain-floating-contract-lock",
       claim: "Consumers using floating Buildchain refs can lock the observed runtime contract and receive drift checks before expensive build or publish work proceeds.",

package/packages/core/index.js

@@ -192,6 +192,17 @@ export {
   workflowFrictionMarker,
 } from "./issue-reporting.js";
 
+export {
+  README_BADGE_BLOCK_END,
+  README_BADGE_BLOCK_START,
+  README_BADGE_FACTS_CONTRACT,
+  checkReadmeBadgeBlock,
+  collectReadmeBadgeFacts,
+  readReadme,
+  renderReadmeBadgeBlock,
+  updateReadmeBadgeBlock,
+} from "./readme-badges.js";
+
 export {
   RELEASE_PROPAGATION_GRAPH_CONTRACT,
   RELEASE_PROPAGATION_LOCK_CONTRACT,