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

package/dist/site/release-model.json

@@ -44,5 +44,13 @@
       "release passport assets"
     ],
     "owner": "promote-buildchain-ref"
+  },
+  "distributionIndexes": {
+    "homebrewTap": {
+      "projectType": "distribution-index",
+      "manifest": "tap-manifest.json",
+      "command": "buildchain homebrew check",
+      "sourceOfTruth": "upstream release passport and sibling evidence"
+    }
   }
 }

package/dist/site/release-provenance.json

@@ -13,7 +13,9 @@
       "./artifact-passport": "./packages/core/artifact-passport.js",
       "./buildchain-contract": "./packages/core/buildchain-contract.js",
       "./diagnostics": "./packages/core/diagnostics.js",
+      "./homebrew": "./packages/core/homebrew.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-07T15:32:30.986Z",
+  "publishedAt": "2026-07-07T15:32:30.986Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "2c3127f2954960ad89f5658a090fb9fe19b442ce",
+  "sourceRevision": "d61c8a864e12e34bc6c6e2aac2e7ad60e6caebfd",
   "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.2",
     "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:f4300eed89765cee0df38eb92de4d9d3adce4fbf954c735aead3bea74f05d975"
     },
     {
       "id": "install",
@@ -79,6 +79,22 @@
       "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": "homebrew",
+      "title": "Homebrew distribution indexes",
+      "path": "docs/homebrew.md",
+      "plane": "use",
+      "exists": true,
+      "digest": "sha256:2fc4e8411f35ca86d19d61c7843b9a1fa440f7afea25df13d3aa03342f09f90c"
+    },
     {
       "id": "binary-distribution",
       "title": "Binary distribution contract",
@@ -149,7 +165,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:a8a348181d6419b746e863d1cacc9d6a91aa6ac5cc2b60819843d44487957c49"
+      "digest": "sha256:cfb0bf32f2b8b44bf352e79c27e34b7980e0f66e5fa10e4f202975fbb4780ad1"
     },
     {
       "id": "lifecycle-protocol",
@@ -213,7 +229,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:f42cc7a81dbeb1b31bec21de61e9807af317bda4055f693ab807b15d9ec77367"
+      "digest": "sha256:4c7334fe2284fec3c1249124b0ff85f1242eb7a76d4b2c537c8b2cb6e0e598c1"
     }
   ],
   "facts": [

package/docs/MAP.md

@@ -25,6 +25,8 @@ 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) |
+| Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.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 +61,8 @@ 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 generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | 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 +119,10 @@ 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).
+- **Homebrew taps / distribution indexes / Formula drift checks** ->
+  [`homebrew.md`](homebrew.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

@@ -64,7 +64,9 @@ Current public import families include:
 ```js
 import * as buildchain from "@kungfu-tech/buildchain";
 import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+import { checkHomebrewTap } from "@kungfu-tech/buildchain/homebrew";
 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" };
@@ -90,6 +92,8 @@ Supported presets:
   validation, observation, contract publication, and downstream propagation
   planning without default mutation. Provider adapters expose built-in command
   plans by default, and only configured `[infra.commands]` hooks can execute.
+- `--type distribution-index` for Homebrew taps and other index repositories
+  whose files are projections of upstream release passport evidence.
 - `--type anchored-package` for packages whose version is anchored to an
   explicit upstream release manifest.
 
@@ -244,9 +248,42 @@ 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`, `buildchain homebrew`, 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.
+
+Generate or check Homebrew tap projections from upstream release passports:
+
+```bash
+buildchain homebrew update-formula \
+  --package buildchain \
+  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain.release.json \
+  --write
+
+buildchain homebrew check --json
+```
+
+`update-formula` writes `Formula/buildchain.rb` and `tap-manifest.json` from
+upstream release passport evidence. `check` fails closed when the Formula,
+manifest, artifact digests, or KFD status drift from the upstream passport. See
+[`homebrew.md`](homebrew.md) for the distribution-index project contract.
 
 `buildchain collect github-release` creates a release passport bundle from
 GitHub Release assets or a local asset directory:

package/docs/homebrew.md

@@ -0,0 +1,116 @@
+# Homebrew Distribution Indexes
+
+Buildchain treats a Homebrew tap as a distribution-index project: the tap
+contains Formula or Cask files, but those files are projections of upstream
+release passports. Version, download URLs, SHA-256 digests, KFD status, and
+evidence links come from the upstream product release, not from hand-maintained
+tap prose.
+
+## Configuration
+
+Use `project.type = "distribution-index"` for tap repositories:
+
+```toml
+schema = 1
+
+[project]
+type = "distribution-index"
+name = "homebrew-tap"
+
+[lifecycle.verify]
+command = "buildchain homebrew check"
+```
+
+The tap manifest is the repository-owned declaration of which upstream releases
+are indexed. Buildchain writes `tap-manifest.json` as a machine-readable
+projection:
+
+```json
+{
+  "schema": 1,
+  "contract": "kungfu-buildchain-homebrew-tap-manifest",
+  "kind": "homebrew-tap",
+  "entries": [
+    {
+      "type": "formula",
+      "name": "buildchain",
+      "path": "Formula/buildchain.rb",
+      "upstream": {
+        "repository": "kungfu-systems/buildchain",
+        "tag": "v2.8.15",
+        "releasePassportUrl": "https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain.release.json"
+      },
+      "version": "2.8.15",
+      "kfd": {
+        "kfd-1": "passed",
+        "kfd-2": "passed",
+        "kfd-3": "passed"
+      },
+      "artifacts": [
+        {
+          "platform": "darwin-arm64",
+          "url": "https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain-aarch64-apple-darwin.tar.gz",
+          "sha256": "..."
+        }
+      ]
+    }
+  ]
+}
+```
+
+## CLI
+
+Update a formula and manifest from an upstream passport:
+
+```bash
+buildchain homebrew update-formula \
+  --package buildchain \
+  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain.release.json \
+  --write
+```
+
+Check that the tap still matches upstream evidence:
+
+```bash
+buildchain homebrew check --json
+```
+
+`check` fails closed when:
+
+- the upstream release passport or its sibling evidence does not verify;
+- `Formula/buildchain.rb` drifts from the projected version, URLs, or SHA-256
+  digests;
+- `tap-manifest.json` drifts from the projected upstream evidence;
+- the tap claims KFD-1, KFD-2, or KFD-3 passed without a verified upstream
+  passport section.
+
+## Node API
+
+Use the public `@kungfu-tech/buildchain/homebrew` export:
+
+```js
+import {
+  collectHomebrewTapFacts,
+  renderHomebrewFormula,
+  checkHomebrewTap,
+  updateHomebrewTap,
+} from "@kungfu-tech/buildchain/homebrew";
+```
+
+The API is the single implementation source. The CLI is a thin wrapper over
+these functions, so CI and local update commands evaluate the same facts.
+
+## Trust Model
+
+Formula metadata is not source of truth. A tap entry may claim `kfd-1`,
+`kfd-2`, or `kfd-3` passed only when the upstream release passport verifies and
+the corresponding passport section is `status = "passed"`. If verification
+fails, Buildchain downgrades the projected KFD status to `unverified` and
+`buildchain homebrew check` fails.
+
+In short: KFD passed in a tap means the upstream release passport passed, not
+that the tap author typed a passing status.
+
+This makes Homebrew taps suitable for automated distribution-index CI: the tap
+can move quickly while still proving that every download URL and digest is
+bound to release passport evidence.

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/docs/web-surface-deployments.md

@@ -264,12 +264,32 @@ rollback:
       "alias": "sha-abcdef123456",
       "url": "https://sha-abcdef123456.preview.libkungfu.dev",
       "sourcePath": "/",
+      "artifactPathPrefix": "",
+      "viewerPathPrefix": "/",
+      "directoryIndex": "index.html",
+      "directoryIndexResolution": true,
       "canonicalUrl": "https://libkungfu.dev",
       "bucket": "libkungfu-dev-preview",
       "distributionId": "E-PREVIEW",
       "originPath": "",
       "objectPrefix": "sha-abcdef123456",
       "manifestKey": ".buildchain/deployments/sha-abcdef123456/hub.json",
+      "routing": {
+        "contract": "kungfu-buildchain-web-surface-path-prefix-rewrite",
+        "viewerPathPrefix": "/",
+        "artifactPathPrefix": "",
+        "objectPrefix": "sha-abcdef123456",
+        "directoryIndex": "index.html",
+        "directoryIndexResolution": true
+      },
+      "smokeUrls": [
+        {
+          "kind": "root",
+          "requestPath": "/",
+          "url": "https://sha-abcdef123456.preview.libkungfu.dev/",
+          "required": true
+        }
+      ],
       "noindex": true,
       "accessControl": "none"
     }
@@ -343,6 +363,19 @@ node scripts/web-surface.mjs \
   --output .buildchain/web-surface-staging-apply.json
 ```
 
+For multi-surface sites, each surface host is treated as a root-relative view
+of that surface's artifact path prefix. For example, a `buildchain` surface with
+`path = "/buildchain/"` and preview URL
+`https://buildchain-pr-29.preview.libkungfu.dev` syncs the artifact subtree
+`dist/buildchain/` to the preview object prefix `pr-29/buildchain`. A viewer
+request for `https://buildchain-pr-29.preview.libkungfu.dev/docs/` therefore
+resolves against the artifact's `dist/buildchain/docs/index.html`, not
+`dist/docs/index.html` and not the hub surface root. The deployment manifest
+records this as `routing.contract =
+"kungfu-buildchain-web-surface-path-prefix-rewrite"` with
+`viewerPathPrefix = "/"`, `artifactPathPrefix = "buildchain"`, and
+`directoryIndexResolution = true`.
+
 It can also execute a previously saved deploy plan. In that mode Buildchain
 recomputes the local artifact hash before running AWS commands and fails closed
 if the artifact no longer matches the saved plan:
@@ -414,7 +447,7 @@ The production preflight checks that:
   `kfd.libkungfu.dev`;
 - DNS resolves for every surface host.
 
-After production apply, the workflow runs:
+After preview, staging, and production apply, the workflow runs:
 
 ```bash
 node scripts/web-surface.mjs \
@@ -424,13 +457,18 @@ node scripts/web-surface.mjs \
   --output .buildchain/web-surface-production-health.json
 ```
 
-The health check fetches every surface URL from the apply result and fails
-production if a response is unreachable, returns an unexpected status, or still
-sends `x-robots-tag: noindex`. It also verifies that each surface binding
-recorded a deployment manifest pointer. The production release passport embeds
-the deploy plan, apply result, production preflight, and health check so a
-reviewer or agent can audit why the production site changed and whether every
-declared host was actually covered.
+The health check fetches every surface root URL and the nested smoke URLs
+recorded in each surface binding. Nested smoke URLs are derived from the
+artifact files under the surface path prefix, with directory index resolution
+such as `dist/buildchain/docs/index.html` becoming `/docs/` on the buildchain
+preview host. This fails closed when a deploy reports success but a child page
+returns 403 or another unexpected status. Production additionally fails if a
+response is unreachable, returns an unexpected status, or still sends
+`x-robots-tag: noindex`. The health check also verifies that each surface
+binding recorded a deployment manifest pointer. The production release passport
+embeds the deploy plan, apply result, production preflight, and health check so
+a reviewer or agent can audit why the production site changed and whether every
+declared host and nested route was actually covered.
 
 ## Cleanup Plans
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.15",
+  "version": "2.8.16-alpha.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -16,7 +16,9 @@
     "./artifact-passport": "./packages/core/artifact-passport.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
     "./diagnostics": "./packages/core/diagnostics.js",
+    "./homebrew": "./packages/core/homebrew.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-config.js

@@ -9,7 +9,7 @@ const RESERVED_LIFECYCLE_KEYS = new Set(["env", "shell"]);
 const SUPPORTED_VERSION_FILE_TYPES = new Set(["json", "toml", "regex"]);
 const SUPPORTED_VERSION_STRATEGIES = new Set(["semver", "anchored"]);
 const SUPPORTED_VERSION_NEXT = new Set(["auto", "manual"]);
-const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface", "infra-contract"]);
+const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface", "infra-contract", "distribution-index"]);
 const SUPPORTED_PUBLISH_MODES = new Set(["publish-final-version", "promote-existing-version"]);
 const SUPPORTED_PUBLISH_AUTH = new Set(["trusted-publishing", "npm-token"]);
 const SUPPORTED_PACKAGE_SET_ORDER = new Set(["as-provided", "platforms-first-main-last"]);
@@ -237,7 +237,7 @@ function normalizeProjectSection(project) {
   assertPlainObject(project, "project");
   const type = assertString(project.type, "project.type");
   if (!SUPPORTED_PROJECT_TYPES.has(type)) {
-    throw new Error("project.type must be one of package, web-surface, or infra-contract");
+    throw new Error("project.type must be one of package, web-surface, infra-contract, or distribution-index");
   }
   const normalized = { type };
   for (const key of ["name", "site"]) {

package/packages/core/buildchain-contract.js

@@ -309,6 +309,9 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
       optionalInputs: [
         "validate",
         "lifecycle",
+        "badges readme",
+        "homebrew update-formula",
+        "homebrew check",
         "collect github-release",
         "verify release-passport",
         "release-propagation",
@@ -316,6 +319,59 @@ 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: "homebrew-distribution-index",
+      kind: "node-api",
+      path: "packages/core/homebrew.js",
+      requiredInputs: ["upstream release passport"],
+      requiredOutputs: [
+        "kungfu-buildchain-homebrew-tap-facts",
+        "kungfu-buildchain-homebrew-tap-manifest",
+        "Formula/*.rb",
+      ],
+      breakingDefaults: {
+        projectType: "distribution-index",
+        tapManifest: "tap-manifest.json",
+        kfdPassedSource: "verified upstream release passport",
+      },
+      optionalInputs: [
+        "buildchain.toml [project] type=distribution-index",
+        "Formula path",
+        "manifest path",
+        "release passport URL or local path",
+      ],
+      guarantees: [
+        "Formula metadata is a deterministic projection of upstream release passport evidence",
+        "tap-manifest.json is checked against upstream version, URLs, SHA-256 digests, and KFD status",
+        "KFD passed claims fail closed unless the upstream release passport verifies the corresponding section",
+        "CLI and JavaScript callers use the same Node API implementation",
+      ],
+    }),
+    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, {