@kungfu-tech/buildchain 3.0.6 → 3.0.7-alpha.0

package/docs/publication-rehearsal.md

@@ -0,0 +1,94 @@
+---
+status: preview
+period: 2026-08-08
+theme: buildchain-publication-rehearsal
+doc_type: product-manual
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-08
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-08
+  visible_context: Public rehearsal capsule runtime, release-tail provider plane, CLI, Action, workflow, and generated consumer surfaces.
+  invisible_context_boundary: No credentials, private provider state, signed URLs, or external publication receipts were read.
+---
+
+# Publication rehearsal
+
+Buildchain publication rehearsal runs the deterministic release tail locally
+from one `kungfu.buildchain.publication-rehearsal-capsule/v1` document. The
+normative rule is [ADR 0001](../architecture/decisions/0001-release-local-constructibility.md):
+every non-external release behavior must be locally constructible, and no
+semantic path may depend on GitHub runner state.
+
+The machine-readable shape is
+[`publication-rehearsal-capsule-v1.schema.json`](../contracts/publication-rehearsal-capsule-v1.schema.json).
+
+## Exact local command
+
+Run from the repository root after restoring the content-addressed candidate:
+
+```sh
+buildchain release-tail rehearse \
+  --capsule "$PWD/.buildchain/publication/rehearsal-capsule.json" \
+  --capsule-root "$PWD/.buildchain/publication/candidate" \
+  --mode simulate \
+  --state "$PWD/.buildchain/publication/rehearsal-state.json" \
+  --evidence "$PWD/.buildchain/publication/rehearsal-evidence.json"
+```
+
+Use `--mode replay` only when the capsule contains a complete recorded
+provider-response sequence. Both modes produce rooted evidence with
+`externalPublicationClaimed: false`.
+
+## Daily fixture and sealed-candidate modes
+
+For daily development, build a synthetic capsule with
+`createPublicationRehearsalCapsule`, use synthetic files and provider
+observations, and run `--mode simulate` or `--mode replay`. This fixture mode is
+for deterministic regression evidence only.
+
+Before publication qualification, restore the exact sealed candidate bytes,
+Passport, policy roots, initial transaction and recorded observations named by
+the retained capsule, then run the exact command above. Preserve the resulting
+binding root, transaction root, state root, receipt roots and evidence root.
+These roots qualify deterministic construction only; external publication and
+public readback still require their own authorities.
+
+## Capsule contents
+
+The capsule root commits to the release-tail declaration, ordered policy roots,
+Passport path/root, initial durable transaction, complete file inventory,
+data-only provider bindings, recorded observations, portable platform policy,
+declared environment keys, and the exact list of external effects. Every input
+file is a regular non-symlink file under the explicit absolute capsule root and
+must match its size and SHA-256 root.
+
+The CLI never reads `GITHUB_*`, infers a runner workspace, selects behavior from
+`process.platform`, or accepts executable hooks. An explicit environment JSON
+object must match the capsule declaration exactly.
+
+## Hosted parity
+
+The reusable `release-tail.yml` workflow passes the explicit capsule to the
+`actions/release-tail` wrapper. The wrapper supplies only GitHub/HTTP transport
+and declared secret inputs, then invokes the same
+`executePublicationRehearsal` public core used locally. Provider requests,
+responses, failures, transaction roots, receipt roots, and the final evidence
+root are retained together.
+
+Simulation or replay is development evidence. Provider mode can record real
+external observations, but it still does not replace Release Passport,
+attestation, registry, activation, public-readback, or protected-delivery
+authority.
+
+## Failure handling
+
+Diagnostics use
+`kungfu.buildchain.publication-rehearsal-diagnostic/v1`. Preserve the capsule,
+diagnostic root, binding root, and exact failed files. Repair the shared core or
+capsule locally and rerun before spending another hosted runner attempt.

package/docs/release-tail-contract.md

@@ -0,0 +1,160 @@
+---
+status: draft
+period: 2026-08-07
+theme: buildchain-release-tail-contract
+doc_type: architecture
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-07
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-07
+  visible_context: Buildchain dev/v3/v3.0 release workflows, promotion Action, transaction and activation code, local exact-head managed-consumer callers, and the Kungfu alpha release-tail implementation.
+  invisible_context_boundary: Did not read credentials, private logs, signed URLs, provider state, or unpublished release assets.
+---
+
+# Declarative release-tail contract
+
+Buildchain v3 currently lets a consumer repository provide shell commands at
+several points around publication. Those hooks made early adoption possible,
+but they also let a consumer redefine the final release transaction. The
+machine authority for the current inventory is
+[`architecture/release-tail-contract-inventory.json`](../architecture/release-tail-contract-inventory.json).
+The declaration schema is
+[`contracts/release-tail-capabilities-v1.schema.json`](../contracts/release-tail-capabilities-v1.schema.json).
+
+This contract freezes the replacement boundary. The Buildchain-owned provider
+implementation is documented in
+[`release-tail-provider-plane.md`](./release-tail-provider-plane.md). Adding the
+provider plane does not itself cut over a consumer, run a release, or
+reinterpret an already published release.
+
+## Current executable surfaces
+
+The reverse scan classifies 27 workflow, Action, config, and CLI coordinates
+into seven owned surface groups:
+
+| Surface                                                                  | Current role                                              | Replacement                                                 |
+| ------------------------------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------- |
+| `publication-gate-command`, `publication-consumer-qualification-command` | Consumer-owned admission and predicate logic              | Buildchain-evaluated declarative predicates                 |
+| `publish-command`, `lifecycle.publish`                                   | Artifact/package materialization and provider publication | `artifact.publish`                                          |
+| KFD-3, invariant Passport, and attachment commands                       | Product-specific evidence generation                      | Typed evidence requirements and Buildchain-owned projectors |
+| `publication-commit-command`                                             | Final signed or well-known channel authority move         | `signed-channel.commit`                                     |
+| `release-activation-command`                                             | Site activation and production readback                   | `release.activate`                                          |
+| reusable-workflow `release-passport-evidence-command`                    | Receipt-only released-evidence synthesis                  | `released-evidence.synthesize`                              |
+| Action `verification-command`                                            | Version-state verification before release-tail execution  | Separate version-state contract; not part of release tail   |
+
+One name is already ambiguous. In the reusable promotion workflow,
+`release-passport-evidence-command` means post-activation released-evidence
+synthesis. In the lower-level promotion Action, the same name is a deprecated
+alias for `release-passport-attachment-command`. New declarations reject that
+cross-layer alias collision instead of preserving it as a permanent escape
+hatch.
+
+The current v3 managed-caller snapshot covers Buildchain self-bootstrap, both
+Buildchain paper release paths, Kungfu, Libnode, KFD, and the Kungfu product
+white paper. The inventory binds every snapshot to an exact commit, tree,
+workflow path, runtime ref, and the executable surface groups it uses. The
+legacy `agent-hub-demo@v2` caller is recorded but excluded from the v3 contract.
+
+## Capability declaration
+
+A declaration contains data, never repository shell. Four capability ids cover
+the current Kungfu alpha tail:
+
+1. `artifact.publish` publishes exact artifact roles to a declared destination.
+2. `signed-channel.commit` moves a signed channel authority only after artifact
+   and Passport prerequisites are durable.
+3. `release.activate` applies the production activation policy and evaluates
+   declared public readback predicates.
+4. `released-evidence.synthesize` consumes the validated activation receipt set
+   and deterministically projects released evidence.
+
+Every capability declares:
+
+- artifact roles and content roots;
+- destination, channel/tag, activation, and readback policy;
+- standardized effect, observation, and receipt schemas;
+- stable transaction, subject, target, capability, and attempt identity;
+- idempotency behavior and a bounded local retry class;
+- exact evidence requirements.
+
+Keys named `command`, `cmd`, `script`, `shell`, or `run` are forbidden anywhere
+in the declaration. Provider adapters may translate a rooted effect into API
+calls, read providers, and return observations. They may not select state
+transitions, change identity, synthesize success, or execute repository-owned
+shell.
+
+The checked fixture
+[`kungfu-alpha.json`](../contracts/fixtures/release-tail-capabilities-v1/kungfu-alpha.json)
+represents the current Kungfu flow: public release assets, the Ed25519-signed
+Alpha channel document, production status/acquisition/product readback, and
+released-evidence synthesis from five canonical activation receipts.
+
+## One release transaction
+
+`buildchain.release-tail/v1` is the only owner of the tail lifecycle:
+
+```text
+prepare
+  -> publish artifacts
+  -> commit signed channel authority
+  -> activate
+  -> read back every declared predicate
+  -> settle receipts and released evidence
+  -> complete | blocked | repair-required | terminal-failure
+```
+
+Each effect uses one stable operation identity. A duplicate attempt performs
+readback before any retry. `never`, `readback`, and `provider-transient` are the
+only retry classes, and no local executor may exceed three attempts. Provider
+conflict, identity drift, missing readback, and exhausted retry remain explicit
+terminal classifications; an adapter cannot convert them into success.
+
+## Compatibility and migration
+
+The compatibility window begins when
+`train/v3/v3.0/release-tail-contract` is published. It closes at the earlier of
+90 days or the first v3.2 stable release, and spans at most two minor lines.
+
+During that window:
+
+- previously published tags, assets, packages, signed channel documents,
+  Passports, and receipts remain immutable;
+- only the exact enumerated callers may use the legacy adapter;
+- every exception has an owner, the common expiry, and a removal test;
+- migrated declarations create new transactions and never reinterpret settled
+  history;
+- no new arbitrary command input or generic plugin is accepted.
+
+Cutover order is the Buildchain paper callers plus a self-bootstrap no-command
+regression, Kungfu's complete Alpha tail, Libnode evidence generation,
+KFD/white-paper no-command regression, then deletion of the Action alias and
+all remaining command inputs. This card
+defines that order only; consumer migrations are separate changes.
+
+## Failure rules
+
+The contract fails closed when:
+
+- a reverse scan discovers an unregistered command-bearing release-tail input;
+- one name maps to multiple capabilities;
+- an effect lacks stable operation identity;
+- a mutation lacks readback and receipt contracts;
+- local retry is unbounded;
+- an exception lacks an owner, expiry, or executable removal test.
+
+Run the contract check with:
+
+```bash
+node scripts/check-release-tail-contract.mjs
+node --test tests/release-tail-contract.test.mjs
+```
+
+The tests mutate the inventory and declaration fixtures to prove that orphaned
+hooks, ambiguous ownership, embedded commands, missing identity/readback,
+unbounded retry, and permanent escape hatches are rejected.

package/docs/release-tail-provider-plane.md

@@ -0,0 +1,120 @@
+---
+status: draft
+period: 2026-08-07
+theme: buildchain-release-tail-provider-plane
+doc_type: architecture
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-07
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-07
+  visible_context: Buildchain release-tail declaration, provider adapters, durable transaction implementation, CLI, Action, reusable workflow, tests, and frozen consumer inventory.
+  invisible_context_boundary: Did not read credentials, private provider state, signed URLs, unpublished release assets, or production receipts.
+---
+
+# Declarative release-tail provider plane
+
+Buildchain owns the final release tail as one versioned transaction. A consumer
+supplies a sealed capability declaration and data-only provider bindings; it
+does not supply shell, JavaScript, executable paths, callbacks, or plugins.
+The frozen boundary and migration inventory remain in
+[`release-tail-contract.md`](./release-tail-contract.md).
+
+## Public entry points
+
+- Node: `@kungfu-tech/buildchain/release-tail-provider-plane`,
+  `release-tail-provider-adapters`, `release-tail-compatibility`, and
+  `publication-rehearsal-runtime`.
+- CLI: `buildchain release-tail plan|init|status|verify|compat|rehearse`.
+- Action: `kungfu-systems/buildchain/actions/release-tail@<exact-ref>`.
+- reusable workflow: `kungfu-systems/buildchain/.github/workflows/release-tail.yml@<exact-ref>`.
+
+The CLI and Action both invoke the public publication rehearsal runtime over
+the same core transaction implementation. The Action is a thin provider
+transport wrapper; callers cannot inject an execution command or runner state.
+
+## Inputs and secrets
+
+The declaration follows
+[`release-tail-capabilities-v1.schema.json`](../contracts/release-tail-capabilities-v1.schema.json).
+Provider file and endpoint bindings follow
+[`release-tail-provider-bindings-v1.schema.json`](../contracts/release-tail-provider-bindings-v1.schema.json).
+Bindings contain paths, asset names, HTTP methods, and evidence input paths.
+GitHub and HTTP bearer tokens are separate secret inputs and never enter the
+effect plan, checkpoint, observation, receipt, or output.
+
+## Transaction semantics
+
+Declaration parsing rejects unknown fields, identity drift, unsupported
+capability/adapter pairs, unbounded retries, and executable keys recursively.
+Compilation produces deterministic effect and plan roots. Execution persists
+one atomic checkpoint containing ordered operations, rooted observations, and
+rooted receipts.
+
+For each effect Buildchain performs readback before mutation, applies at most
+the declared bounded local attempts, then performs readback again. Buildchain
+core alone compares the declared subject and target roots and chooses
+`complete`, `blocked`, `repair-required`, or `terminal-failure`. An adapter can
+report observed, absent, transient, or conflict; it cannot declare success.
+
+The built-in adapters are:
+
+- `github-release-assets`: exact GitHub Release tag and immutable named assets;
+- `signed-static-channel`: rooted HTTPS JSON channel commit with optional CAS;
+- `site-release-activation`: rooted HTTPS activation and public readback;
+- `activation-receipt-projector`: deterministic released-evidence synthesis.
+
+Duplicate execution is a readback no-op. A lost mutation response is recovered
+by the next local readback. A stale rooted object requires repair, immutable
+provider collision is terminal, and credential/network uncertainty remains a
+bounded blocked result rather than synthesized success.
+
+## Local verification
+
+```bash
+buildchain release-tail plan --declaration release-tail.json
+buildchain release-tail init --declaration release-tail.json --state .buildchain/release-tail/state.json
+buildchain release-tail verify --state .buildchain/release-tail/state.json
+```
+
+For complete local release semantics, use the exact capsule command in
+[`publication-rehearsal.md`](publication-rehearsal.md). Simulation and replay
+exercise planning, validation, transaction, retry, and evidence without
+claiming external provider truth. Provider execution belongs in the Action or
+reusable workflow so token handling and transport capabilities remain explicit.
+Retain the state and rehearsal evidence artifacts.
+
+## Buildchain self-dogfood route
+
+Buildchain self-release calls the same public reusable workflow coordinate as a
+consumer:
+
+```text
+kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@9a0cdf8d84aacf8c7daaac82efa43d1b34696a03
+```
+
+The caller pins the public router and runtime to the same exact implementation
+SHA. Its internal alpha shell remains on the named train, so automatic
+`workflow_run` publication uses the immutable-router path without a manual
+runtime override. For alpha self-release, the promotion Action materializes the
+sealed GitHub Release asset declaration, executes it through this provider
+plane, and retains the
+declaration root, transaction root, state root, receipt roots, controller
+receipt, and route-parity evidence. The legacy GitHub Release helper is not a
+fallback when `declarative-release-tail` is enabled; a provider or readback
+failure fails the authoritative run.
+
+Stable routing remains on the existing `v3` shell and does not receive the new
+alpha-train input. Stable cutover is a separate gate after prerelease dogfood.
+
+## v3 compatibility boundary
+
+`release-tail compat --hooks-json <json-or-path>` recognizes only the frozen v3
+hook names. It emits diagnostics for enumerated legacy callers and rejects any
+new command-bearing release-tail field. Compatibility never converts legacy
+shell into a new provider plugin and never reinterprets settled release history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.6",
+  "version": "3.0.7-alpha.0",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -57,6 +57,11 @@
     "./release-passport-contract": "./packages/core/release-passport-contract.js",
     "./release-propagation": "./packages/core/release-propagation.js",
     "./release-activation-transaction": "./packages/core/release-activation-transaction.js",
+    "./release-tail-provider-plane": "./packages/core/release-tail-provider-plane.js",
+    "./release-tail-provider-adapters": "./packages/core/release-tail-provider-adapters.js",
+    "./release-tail-compatibility": "./packages/core/release-tail-compatibility.js",
+    "./publication-rehearsal-runtime": "./packages/core/publication-rehearsal-runtime.js",
+    "./publication-rehearsal-projection": "./packages/core/publication-rehearsal-projection.js",
     "./surface-manifest": "./packages/core/surface-manifest.js",
     "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
@@ -111,8 +116,8 @@
   "packageManager": "pnpm@11.7.0",
   "scripts": {
     "operator:windows-jit": "bash scripts/aws-windows-jit-operator.sh",
-    "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": "pnpm run check:static && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && node scripts/check-core-mechanism-inventory.mjs && node scripts/check-release-tail-contract.mjs && node scripts/v4-architecture.mjs validate && 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 contracts/release-tail-capabilities-v1.schema.json contracts/release-tail-provider-bindings-v1.schema.json contracts/publication-rehearsal-capsule-v1.schema.json contracts/fixtures/release-tail-capabilities-v1/*.json bin/internal/command-registry.mjs scripts/authorize-promotion-runtime-override.cjs scripts/check-core-mechanism-inventory.mjs scripts/check-release-tail-contract.mjs 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/v4-architecture.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/core-mechanism-inventory.test.mjs tests/release-tail-contract.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs tests/v4-architecture.test.mjs",
     "check:workflows": "bash scripts/check-workflows.sh",
     "generate:reference": "node scripts/generate-public-reference.mjs",
     "check:reference": "node scripts/generate-public-reference.mjs --check",

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

@@ -29,6 +29,9 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { 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-tail-contract", title: "Declarative release-tail contract", path: "docs/release-tail-contract.md", plane: "verify" },
+  { id: "release-tail-provider-plane", title: "Declarative release-tail provider plane", path: "docs/release-tail-provider-plane.md", plane: "use" },
+  { id: "publication-rehearsal", title: "Publication rehearsal", path: "docs/publication-rehearsal.md", plane: "use" },
   { 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" },

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

@@ -138,7 +138,7 @@ function immediateReadmes(root, dir) {
 
 function publicDocumentationFiles(root) {
   return uniquePaths([
-    ...BUILDCHAIN_AGENT_MANUALS.map((entry) => entry.path),
+    ...(readJson(root, "dist/site/manual-registry.json").manuals || BUILDCHAIN_AGENT_MANUALS).map((entry) => entry.path),
     "README.md",
     "packages/core/README.md",
     ...immediateReadmes(root, "actions"),

package/packages/core/buildchain-publication-authority.js

@@ -50,6 +50,7 @@ const DESCRIPTORS = Object.freeze([
   [".github/workflows/release-candidate-promote.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/release-line-bootstrap.yml", "governance-write"],
   [".github/workflows/release-propagation.yml", "governance-write"],
+  [".github/workflows/release-tail.yml", "product-publication", true, ["artifact.publish", "signed-channel.commit", "release.activate", "released-evidence.synthesize"], "caller-secrets", "caller-bound", "caller-bound", "fixed"],
   [".github/workflows/release-verify.yml", "governance-write"],
   [".github/workflows/stable-candidate-patrol.yml", "governance-write"],
 ]);

package/packages/core/index.js

@@ -58,6 +58,45 @@ export {
   writeReleaseTransaction,
 } from "./publish-transaction.js";
 
+export {
+  RELEASE_TAIL_CAPABILITY_REGISTRY,
+  RELEASE_TAIL_DECLARATION_CONTRACT,
+  RELEASE_TAIL_EFFECT_SCHEMA,
+  RELEASE_TAIL_OBSERVATION_SCHEMA,
+  RELEASE_TAIL_RECEIPT_SCHEMA,
+  RELEASE_TAIL_STATES,
+  RELEASE_TAIL_TRANSACTION_POLICY,
+  RELEASE_TAIL_TRANSACTION_SCHEMA,
+  compileReleaseTailDeclaration,
+  createReleaseTailAdapterSet,
+  createReleaseTailTransaction,
+  executeReleaseTailTransaction,
+  parseReleaseTailDeclaration,
+  readReleaseTailTransaction,
+  releaseTailRetryPolicyFromDeclaration,
+  releaseTailRoot,
+  releaseTailStableJson,
+  validateReleaseTailEffectPlan,
+  validateReleaseTailTransaction,
+  writeReleaseTailTransaction,
+} from "./release-tail-provider-plane.js";
+
+export {
+  ReleaseTailProviderError,
+  createActivationReceiptProjectorAdapter,
+  createGitHubReleaseAssetsAdapter,
+  createHttpJsonReadback,
+  createSignedStaticChannelAdapter,
+  createSiteReleaseActivationAdapter,
+  githubReleaseAssetsTargetRoot,
+} from "./release-tail-provider-adapters.js";
+
+export {
+  RELEASE_TAIL_COMPATIBILITY_CONTRACT,
+  RELEASE_TAIL_LEGACY_HOOKS,
+  diagnoseLegacyReleaseTailHooks,
+} from "./release-tail-compatibility.js";
+
 export {
   createPortableDevCachePlan,
   createPortableDevCacheReceipt,

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

@@ -12,6 +12,7 @@ import {
   stableJson,
   workCheck,
 } from "./paper-repository.js";
+import { mergePublicationRehearsalAgentInstructions } from "./publication-rehearsal-projection.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -167,9 +168,11 @@ export function paperAgentEntryFiles({
     [PAPER_PATHS.agentEntry, jsonText(entry)],
     [
       PAPER_PATHS.agentInstructions,
-      mergePaperAgentEntryInstructions(currentAgents, {
-        developmentRef: resolvedDevelopmentRef,
-      }),
+      mergePublicationRehearsalAgentInstructions(
+        mergePaperAgentEntryInstructions(currentAgents, {
+          developmentRef: resolvedDevelopmentRef,
+        }),
+      ),
     ],
   ]);
 }
@@ -205,8 +208,11 @@ function ciContext({ env, developmentRef }) {
     sourceBranch.startsWith(versionStatePrefix) &&
     /^[0-9a-f]{12}$/i.test(sourceBranch.slice(versionStatePrefix.length));
   const branchOk = pullRequest
-    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) && targetBranch === developmentRef) ||
-      (channelIndex > 0 && sourceBranch === channelBranches[channelIndex - 1]) || generatedVersionState
+    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) &&
+        targetBranch === developmentRef) ||
+      (channelIndex > 0 &&
+        sourceBranch === channelBranches[channelIndex - 1]) ||
+      generatedVersionState
     : channelBranches.includes(refName);
   return {
     mode: "ci",

package/packages/core/paper-repository.js

@@ -13,6 +13,7 @@ export const PAPER_PATHS = Object.freeze({
   buildWorkflow: ".github/workflows/build.yml",
   verifyWorkflow: ".github/workflows/verify.yml",
   releaseWorkflow: ".github/workflows/paper-release.yml",
+  rehearsalWorkflow: ".github/workflows/publication-rehearsal.yml",
   pnpmWorkspace: "pnpm-workspace.yaml",
   reproducibilityReceipt:
     ".buildchain/publication/reproducibility-receipt.json",

package/packages/core/paper-scaffold-content.js

@@ -1,3 +1,10 @@
+import {
+  PUBLICATION_REHEARSAL_CAPSULE_CONTRACT,
+  PUBLICATION_REHEARSAL_COMMAND,
+  RELEASE_LOCAL_CONSTRUCTIBILITY_ADR,
+  RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT,
+} from "./publication-rehearsal-runtime.js";
+
 function jsonText(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -47,6 +54,7 @@ export function paperPackageScripts(current = {}) {
     "paper:work:start": "buildchain paper work start",
     "paper:work:submit": "buildchain paper work submit",
     "paper:status": "buildchain paper status --json",
+    "publication:rehearse": PUBLICATION_REHEARSAL_COMMAND,
   };
 }
 
@@ -106,6 +114,7 @@ pnpm paper:preflight
 pnpm paper:agent:verify
 pnpm paper:work:start -- <topic>
 pnpm paper:work:submit
+pnpm publication:rehearse
 make pdf
 \`\`\`
 
@@ -114,6 +123,11 @@ artifact generation, sealed publication, npm Trusted Publishing, and recovery;
 this repository owns the paper source and review history.
 
 See [docs/MAP.md](docs/MAP.md) for the repository map.
+
+Publication qualification follows the Buildchain
+\`${RELEASE_LOCAL_CONSTRUCTIBILITY_ADR}\` invariant:
+${RELEASE_LOCAL_CONSTRUCTIBILITY_INVARIANT} The capsule contract is
+\`${PUBLICATION_REHEARSAL_CAPSULE_CONTRACT}\`.
 `;
 }
 
@@ -129,10 +143,17 @@ export function scaffoldMap() {
 - \`.github/workflows/build.yml\`: thin read-only build and reproducibility caller.
 - \`.github/workflows/verify.yml\`: thin required check that enforces the Paper entry and acceptance policy.
 - \`.github/workflows/paper-release.yml\`: thin protected sealed-release caller.
+- \`.github/workflows/publication-rehearsal.yml\`: thin hosted adapter over the same local capsule runtime.
 
 The repository does not own npm transaction logic, publication authority,
 release-state recovery, or site deployment mechanics. Those remain Buildchain,
 npm/GitHub, and downstream site responsibilities respectively.
+
+The exact local pre-publication command is:
+
+\`\`\`sh
+${PUBLICATION_REHEARSAL_COMMAND}
+\`\`\`
 `;
 }