@kungfu-tech/buildchain 4.0.2-alpha.42 → 4.0.2-alpha.44

package/dist/site/public-surface-audit.json

@@ -10929,8 +10929,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "fbc23073bbae240489a2f826b2c26daadc58e704050c5f8df366509f5c5a1c3e",
-    "workflowRegistryDigest": "0143633ac365cc3bbd4b8c3aead36b3fa336375acc56d10bff0292866f46dda4",
-    "pageRegistryDigest": "77db2ba380ab0206b07b6db59a702a995077b5570732c9851caec15c65b717be"
+    "workflowRegistryDigest": "6391219ad0dae43ff217202a74a7e3d45669799cd142d590e9f0bafecaeb9912",
+    "pageRegistryDigest": "de1ba89591aeb5f0e24f1c5e455c21e8477e1094ec616ffddc2c1163f02c53b9"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-09-06T11:33:49.000Z",
-  "publishedAt": "2026-09-06T11:33:49.000Z",
+  "generatedAt": "2026-09-06T13:21:07.000Z",
+  "publishedAt": "2026-09-06T13:21:07.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "9c053766731017a319479923df0ae6cc6de1a54f",
+  "sourceRevision": "cf1b8e029ee3ef8b615cfc3c3814cfc8b7bf3c5c",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.42",
+    "version": "4.0.2-alpha.44",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-09-06T11:33:49.000Z",
-  "publishedAt": "2026-09-06T11:33:49.000Z",
+  "generatedAt": "2026-09-06T13:21:07.000Z",
+  "publishedAt": "2026-09-06T13:21:07.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "9c053766731017a319479923df0ae6cc6de1a54f",
+  "sourceRevision": "cf1b8e029ee3ef8b615cfc3c3814cfc8b7bf3c5c",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.2-alpha.42",
+    "version": "4.0.2-alpha.44",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -237,7 +237,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:b90266a341f7c7f904e5a5a8df7dd669ba30e6934633889ef221288ce698f784"
+      "digest": "sha256:fc2e0cd3f5718e05101d85f6363cefcd2336609c05dd6626b6a062b44c3a1a0d"
     },
     {
       "id": "cli-reference",
@@ -253,7 +253,7 @@
       "path": "docs/node-api-reference.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:3b4b475408bb16915854aa2d7969cc9db4faecdfdc0f2f6af5174e7d91188cf2"
+      "digest": "sha256:df073c14c12f15c851eb4507cbeb2919add936ac3079b10f222478138720d092"
     },
     {
       "id": "build-facts",

package/dist/site/workflow-registry.json

@@ -2746,7 +2746,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.44",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -3943,7 +3943,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.44",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -5970,7 +5970,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.44",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6001,7 +6001,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.44",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6032,7 +6032,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.42",
+      "introducedVersion": "4.0.2-alpha.44",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",

package/docs/cli.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-09-06
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-31
+  generated_at: 2026-09-06
   invisible_context: not asserted
 ---
 
@@ -169,6 +169,9 @@ The safety and authority boundary is explicit:
   and verify callers use `@v4-alpha`; release callers select `@v4-alpha` for
   Alpha and `@v4` for stable releases. Both channel contract locks and their
   distinct resolved source coordinates are bound into provisioning authority.
+  Verify callers grant the reusable Check workflow its required read permissions.
+  Paper agent guidance resolves next-development scripts from the installed
+  Buildchain package and links to the upstream transition ADR.
   Migration reads the other channel from its fetched Git tag. Installed-package
   operators can supply `--stable-buildchain-root` or `--alpha-buildchain-root`
   pointing to the corresponding exact source checkout instead.
@@ -182,6 +185,10 @@ The safety and authority boundary is explicit:
   the pull-request source and target from GitHub context and fails closed on a
   non-work source branch or a target other than the configured development
   line.
+- Installed npm runtimes resolve their source from registry `gitHead`, or from
+  the official exact version tag when that field is absent. Missing, malformed,
+  duplicate, or unexpected tag results fail closed; floating tags are never
+  used as the installed package's source identity.
 - `work start` derives the protected development branch from the configured
   publication semver line and creates a safe local work branch only when the
   worktree is clean, the sole `origin` is the canonical `kungfu-systems`

package/docs/node-api-reference.md

@@ -150,8 +150,8 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `collectModuleBuildFacts` | function: function collectModuleBuildFacts({ cwd = process.cwd(), moduleId = "", moduleRoot = "", scope = "", versionSource = undefined, versionSourceId = "", outputs = [], lifecycle = "", platform = currentPlatform(), dependencies = [], now = nowIso(), } = {}) | { cwd = process.cwd(), moduleId = "", moduleRoot = "", scope = "", versionSource = undefined, versionSourceId = "", outputs = [], lifecycle = "", platform = currentPlatform(), dependencies = [], now = nowIso(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectModuleBuildFacts } from "@kungfu-tech/buildchain";` | `packages/core/build-facts.js:310` |
 | `collectNativeDiagnostics` | function: function collectNativeDiagnostics({ cwd = process.cwd(), profile = undefined, runCommand = defaultDiagnosticCommandRunner, } = {}) | { cwd = process.cwd(), profile = undefined, runCommand = defaultDiagnosticCommandRunner, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectNativeDiagnostics } from "@kungfu-tech/buildchain";` | `packages/core/diagnostics.js:295` |
 | `collectPaperFleetAudit` | function: function collectPaperFleetAudit({ root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {}) | { root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperFleetAudit } from "@kungfu-tech/buildchain";` | `packages/core/paper-fleet.js:158` |
-| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2041` |
-| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:1140` |
+| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2025` |
+| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:1124` |
 | `collectProcessTreeSnapshot` | function: function collectProcessTreeSnapshot({ rootPid = process.pid, cwd = process.cwd(), platform = process.platform, runCommand = defaultDiagnosticCommandRunner, } = {}) | { rootPid = process.pid, cwd = process.cwd(), platform = process.platform, runCommand = defaultDiagnosticCommandRunner, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectProcessTreeSnapshot } from "@kungfu-tech/buildchain";` | `packages/core/diagnostics.js:1029` |
 | `collectPublicationArtifact` | function: function collectPublicationArtifact({ cwd = process.cwd(), sourceSha = "", sourceBundle = true, sourceBundlePath = "", generatedAt = "", manifestPath = "", passportPath = "", } = {}) | { cwd = process.cwd(), sourceSha = "", sourceBundle = true, sourceBundlePath = "", generatedAt = "", manifestPath = "", passportPath = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { collectPublicationArtifact } from "@kungfu-tech/buildchain";` | `packages/core/publication-artifact.js:271` |
 | `collectPublicationPackageFacts` | function: function collectPublicationPackageFacts({ cwd = process.cwd(), packageName = "", outputDir = ".buildchain/publication/npm-package", } = {}) | { cwd = process.cwd(), packageName = "", outputDir = ".buildchain/publication/npm-package", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { collectPublicationPackageFacts } from "@kungfu-tech/buildchain";` | `packages/core/publication-package.js:74` |
@@ -219,9 +219,9 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `createManualUpstreamPickupCapture` | function: function createManualUpstreamPickupCapture({ plan, expectedDownstreamBaseSha, }) | { plan, expectedDownstreamBaseSha, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createManualUpstreamPickupCapture } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-pickup.js:361` |
 | `createManualUpstreamPickupPlan` | function: function createManualUpstreamPickupPlan({ config: configInput, sourceId, channel, currentVersion, upstreamRelease, }) | { config: configInput, sourceId, channel, currentVersion, upstreamRelease, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createManualUpstreamPickupPlan } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-pickup.js:303` |
 | `createPackageReleasePropagationCapture` | function: function createPackageReleasePropagationCapture({ config: configInput, upstreamRelease: upstreamReleaseInput, expectedBaseShas = {}, } = {}) | { config: configInput, upstreamRelease: upstreamReleaseInput, expectedBaseShas = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPackageReleasePropagationCapture } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-capture.js:101` |
-| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2283` |
-| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2220` |
-| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2341` |
+| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2267` |
+| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2204` |
+| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2325` |
 | `createPaperWorkStartPlan` | function: function createPaperWorkStartPlan({ cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {}) | { cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkStartPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper-work.js:41` |
 | `createPaperWorkSubmitPlan` | function: function createPaperWorkSubmitPlan({ cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {}) | { cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkSubmitPlan } from "@kungfu-tech/buildchain";` | `packages/core/paper-work.js:207` |
 | `createPortableDevCachePlan` | function: function createPortableDevCachePlan(manifest) | manifest | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPortableDevCachePlan } from "@kungfu-tech/buildchain";` | `packages/core/portable-dev-cache.js:172` |
@@ -293,7 +293,7 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `evaluateGithubGovernanceSnapshot` | function: function evaluateGithubGovernanceSnapshot({ descriptor = createBuildchainGithubGovernanceAuthority(), repository, targetRef, organizationPlan, codeowners, effectivePolicy, memberships, apiEvidence = {}, observedAt, expiresAt, verifier = {}, } = {}) | { descriptor = createBuildchainGithubGovernanceAuthority(), repository, targetRef, organizationPlan, codeowners, effectivePolicy, memberships, apiEvidence = {}, observedAt, expiresAt, verifier = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { evaluateGithubGovernanceSnapshot } from "@kungfu-tech/buildchain";` | `packages/core/github-governance-authority.js:697` |
 | `evaluateKfdProductGate` | function: async function evaluateKfdProductGate({ cwd = process.cwd(), input, expectedSourceSha = "", checkedAt = new Date().toISOString(), } = {}) | { cwd = process.cwd(), input, expectedSourceSha = "", checkedAt = new Date().toISOString(), } = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { evaluateKfdProductGate } from "@kungfu-tech/buildchain";` | `packages/core/kfd-product-gates.js:419` |
 | `evaluatePublicationControlPlaneSnapshot` | function: function evaluatePublicationControlPlaneSnapshot({ repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {}) | { repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { evaluatePublicationControlPlaneSnapshot } from "@kungfu-tech/buildchain";` | `packages/core/publication-control-plane-audit.js:245` |
-| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2468` |
+| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain";` | `packages/core/paper.js:2452` |
 | `executePaperWorkStart` | function: function executePaperWorkStart(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkStart } from "@kungfu-tech/buildchain";` | `packages/core/paper-work.js:169` |
 | `executePaperWorkSubmitPush` | function: function executePaperWorkSubmitPush(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkSubmitPush } from "@kungfu-tech/buildchain";` | `packages/core/paper-work.js:357` |
 | `executeReleasePropagationPush` | function: function executeReleasePropagationPush({ work, expectedWorkRoot, cwd = process.cwd(), remote = "origin", } = {}) | { work, expectedWorkRoot, cwd = process.cwd(), remote = "origin", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { executeReleasePropagationPush } from "@kungfu-tech/buildchain";` | `packages/core/release-propagation-push.js:231` |
@@ -839,8 +839,8 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `collectModuleBuildFacts` | function: function collectModuleBuildFacts({ cwd = process.cwd(), moduleId = "", moduleRoot = "", scope = "", versionSource = undefined, versionSourceId = "", outputs = [], lifecycle = "", platform = currentPlatform(), dependencies = [], now = nowIso(), } = {}) | { cwd = process.cwd(), moduleId = "", moduleRoot = "", scope = "", versionSource = undefined, versionSourceId = "", outputs = [], lifecycle = "", platform = currentPlatform(), dependencies = [], now = nowIso(), } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectModuleBuildFacts } from "@kungfu-tech/buildchain/core";` | `packages/core/build-facts.js:310` |
 | `collectNativeDiagnostics` | function: function collectNativeDiagnostics({ cwd = process.cwd(), profile = undefined, runCommand = defaultDiagnosticCommandRunner, } = {}) | { cwd = process.cwd(), profile = undefined, runCommand = defaultDiagnosticCommandRunner, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectNativeDiagnostics } from "@kungfu-tech/buildchain/core";` | `packages/core/diagnostics.js:295` |
 | `collectPaperFleetAudit` | function: function collectPaperFleetAudit({ root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {}) | { root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperFleetAudit } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-fleet.js:158` |
-| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2041` |
-| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:1140` |
+| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2025` |
+| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:1124` |
 | `collectProcessTreeSnapshot` | function: function collectProcessTreeSnapshot({ rootPid = process.pid, cwd = process.cwd(), platform = process.platform, runCommand = defaultDiagnosticCommandRunner, } = {}) | { rootPid = process.pid, cwd = process.cwd(), platform = process.platform, runCommand = defaultDiagnosticCommandRunner, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectProcessTreeSnapshot } from "@kungfu-tech/buildchain/core";` | `packages/core/diagnostics.js:1029` |
 | `collectPublicationArtifact` | function: function collectPublicationArtifact({ cwd = process.cwd(), sourceSha = "", sourceBundle = true, sourceBundlePath = "", generatedAt = "", manifestPath = "", passportPath = "", } = {}) | { cwd = process.cwd(), sourceSha = "", sourceBundle = true, sourceBundlePath = "", generatedAt = "", manifestPath = "", passportPath = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | local-filesystem-write | `import { collectPublicationArtifact } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-artifact.js:271` |
 | `collectPublicationPackageFacts` | function: function collectPublicationPackageFacts({ cwd = process.cwd(), packageName = "", outputDir = ".buildchain/publication/npm-package", } = {}) | { cwd = process.cwd(), packageName = "", outputDir = ".buildchain/publication/npm-package", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { collectPublicationPackageFacts } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-package.js:74` |
@@ -908,9 +908,9 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `createManualUpstreamPickupCapture` | function: function createManualUpstreamPickupCapture({ plan, expectedDownstreamBaseSha, }) | { plan, expectedDownstreamBaseSha, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createManualUpstreamPickupCapture } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-pickup.js:361` |
 | `createManualUpstreamPickupPlan` | function: function createManualUpstreamPickupPlan({ config: configInput, sourceId, channel, currentVersion, upstreamRelease, }) | { config: configInput, sourceId, channel, currentVersion, upstreamRelease, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createManualUpstreamPickupPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-pickup.js:303` |
 | `createPackageReleasePropagationCapture` | function: function createPackageReleasePropagationCapture({ config: configInput, upstreamRelease: upstreamReleaseInput, expectedBaseShas = {}, } = {}) | { config: configInput, upstreamRelease: upstreamReleaseInput, expectedBaseShas = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPackageReleasePropagationCapture } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-capture.js:101` |
-| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2283` |
-| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2220` |
-| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2341` |
+| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2267` |
+| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2204` |
+| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2325` |
 | `createPaperWorkStartPlan` | function: function createPaperWorkStartPlan({ cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {}) | { cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkStartPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-work.js:41` |
 | `createPaperWorkSubmitPlan` | function: function createPaperWorkSubmitPlan({ cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {}) | { cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkSubmitPlan } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-work.js:207` |
 | `createPortableDevCachePlan` | function: function createPortableDevCachePlan(manifest) | manifest | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPortableDevCachePlan } from "@kungfu-tech/buildchain/core";` | `packages/core/portable-dev-cache.js:172` |
@@ -982,7 +982,7 @@ Target: `./packages/core/index.js`. Public symbols: 636.
 | `evaluateGithubGovernanceSnapshot` | function: function evaluateGithubGovernanceSnapshot({ descriptor = createBuildchainGithubGovernanceAuthority(), repository, targetRef, organizationPlan, codeowners, effectivePolicy, memberships, apiEvidence = {}, observedAt, expiresAt, verifier = {}, } = {}) | { descriptor = createBuildchainGithubGovernanceAuthority(), repository, targetRef, organizationPlan, codeowners, effectivePolicy, memberships, apiEvidence = {}, observedAt, expiresAt, verifier = {}, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { evaluateGithubGovernanceSnapshot } from "@kungfu-tech/buildchain/core";` | `packages/core/github-governance-authority.js:697` |
 | `evaluateKfdProductGate` | function: async function evaluateKfdProductGate({ cwd = process.cwd(), input, expectedSourceSha = "", checkedAt = new Date().toISOString(), } = {}) | { cwd = process.cwd(), input, expectedSourceSha = "", checkedAt = new Date().toISOString(), } = {} | Promise<unknown> | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { evaluateKfdProductGate } from "@kungfu-tech/buildchain/core";` | `packages/core/kfd-product-gates.js:419` |
 | `evaluatePublicationControlPlaneSnapshot` | function: function evaluatePublicationControlPlaneSnapshot({ repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {}) | { repository, workflowPath, publisherWorkflowPath = workflowPath, environment, branch, packageName, publisherMode = "npm-trusted-publisher", requiredStatusCheck = "check", snapshot, observedAt, expiresAt, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { evaluatePublicationControlPlaneSnapshot } from "@kungfu-tech/buildchain/core";` | `packages/core/publication-control-plane-audit.js:245` |
-| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2468` |
+| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain/core";` | `packages/core/paper.js:2452` |
 | `executePaperWorkStart` | function: function executePaperWorkStart(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkStart } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-work.js:169` |
 | `executePaperWorkSubmitPush` | function: function executePaperWorkSubmitPush(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkSubmitPush } from "@kungfu-tech/buildchain/core";` | `packages/core/paper-work.js:357` |
 | `executeReleasePropagationPush` | function: function executeReleasePropagationPush({ work, expectedWorkRoot, cwd = process.cwd(), remote = "origin", } = {}) | { work, expectedWorkRoot, cwd = process.cwd(), remote = "origin", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | may-write-or-invoke-external-actions | `import { executeReleasePropagationPush } from "@kungfu-tech/buildchain/core";` | `packages/core/release-propagation-push.js:231` |
@@ -2325,26 +2325,26 @@ Target: `./packages/core/paper.js`. Public symbols: 48.
 
 | Symbol | Kind and signature | Parameters | Return | Errors | Side effects | Example | Source |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| `collectPaperAgentEntry` | function: function collectPaperAgentEntry({ cwd = process.cwd(), buildchainSha = "", mode = "contract", env = process.env, runtimeAdmission, } = {}) | { cwd = process.cwd(), buildchainSha = "", mode = "contract", env = process.env, runtimeAdmission, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperAgentEntry } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:255` |
+| `collectPaperAgentEntry` | function: function collectPaperAgentEntry({ cwd = process.cwd(), buildchainSha = "", mode = "contract", env = process.env, runtimeAdmission, } = {}) | { cwd = process.cwd(), buildchainSha = "", mode = "contract", env = process.env, runtimeAdmission, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperAgentEntry } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:279` |
 | `collectPaperFleetAudit` | function: function collectPaperFleetAudit({ root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {}) | { root = process.cwd(), repositories = [], buildchainRoot = process.cwd(), buildchainVersion = "", buildchainSha = "", governance = {}, } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperFleetAudit } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-fleet.js:158` |
-| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2041` |
-| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:1140` |
-| `createPaperAgentEntry` | function: function createPaperAgentEntry({ buildchainVersion, buildchainSha, developmentRef, }) | { buildchainVersion, buildchainSha, developmentRef, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAgentEntry } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:95` |
-| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2283` |
-| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2220` |
-| `createPaperProvisioningAuthority` | function: function createPaperProvisioningAuthority({ repository, packageName, buildchainVersion, buildchainSha, contractLock, buildWorkflow, verifyWorkflow, releaseWorkflow, agentEntry, agentInstructions, environment = "", }) | { repository, packageName, buildchainVersion, buildchainSha, contractLock, buildWorkflow, verifyWorkflow, releaseWorkflow, agentEntry, agentInstructions, environment = "", } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperProvisioningAuthority } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:527` |
-| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2341` |
+| `collectPaperPreflight` | function: function collectPaperPreflight({ cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {}) | { cwd = process.cwd(), buildchainRoot = process.cwd(), buildchainVersion = "", buildchainRef = "v3", buildchainSha = "", registry = NPM_REGISTRY, offline = false, agentEntryMode = "contract", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperPreflight } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2025` |
+| `collectPaperStatus` | function: function collectPaperStatus({ cwd = process.cwd() } = {}) | { cwd = process.cwd() } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { collectPaperStatus } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:1124` |
+| `createPaperAgentEntry` | function: function createPaperAgentEntry({ buildchainVersion, buildchainSha, developmentRef, }) | { buildchainVersion, buildchainSha, developmentRef, } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAgentEntry } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:101` |
+| `createPaperAlphaPlan` | function: function createPaperAlphaPlan({ cwd = process.cwd(), sourceRef = "", targetRef = "", } = {}) | { cwd = process.cwd(), sourceRef = "", targetRef = "", } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperAlphaPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2267` |
+| `createPaperBuildPlan` | function: function createPaperBuildPlan({ cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {}) | { cwd = process.cwd(), sourceSha = "", pullToolchain = true, } = {} | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperBuildPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2204` |
+| `createPaperProvisioningAuthority` | function: function createPaperProvisioningAuthority({ repository, packageName, buildchainVersion, buildchainSha, contractLock, buildWorkflow, verifyWorkflow, releaseWorkflow, agentEntry, agentInstructions, environment = "", }) | { repository, packageName, buildchainVersion, buildchainSha, contractLock, buildWorkflow, verifyWorkflow, releaseWorkflow, agentEntry, agentInstructions, environment = "", } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { createPaperProvisioningAuthority } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:511` |
+| `createPaperResumePlan` | function: function createPaperResumePlan({ cwd = process.cwd(), buildchainRef = "", } = {}) | { cwd = process.cwd(), buildchainRef = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | local-filesystem-write | `import { createPaperResumePlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2325` |
 | `createPaperWorkStartPlan` | function: function createPaperWorkStartPlan({ cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {}) | { cwd = process.cwd(), topic = "", branch = "", buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkStartPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:41` |
 | `createPaperWorkSubmitPlan` | function: function createPaperWorkSubmitPlan({ cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {}) | { cwd = process.cwd(), pullRequests = [], pullRequestObservation = { ok: true }, buildchainSha = "", } = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { createPaperWorkSubmitPlan } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:207` |
 | `discoverPaperFleet` | function: function discoverPaperFleet(root = process.cwd()) | root = process.cwd() | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { discoverPaperFleet } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-fleet.js:23` |
-| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2468` |
+| `executePaperNpmBootstrap` | function: function executePaperNpmBootstrap(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperNpmBootstrap } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:2452` |
 | `executePaperWorkStart` | function: function executePaperWorkStart(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkStart } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:169` |
 | `executePaperWorkSubmitPush` | function: function executePaperWorkSubmitPush(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { executePaperWorkSubmitPush } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:357` |
-| `mergePaperAgentEntryInstructions` | function: function mergePaperAgentEntryInstructions(current = "", { developmentRef }) | current = "", { developmentRef } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { mergePaperAgentEntryInstructions } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:63` |
-| `PAPER_AGENT_ENTRY_CONTRACT` | constant: const PAPER_AGENT_ENTRY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_AGENT_ENTRY_CONTRACT } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:18` |
-| `PAPER_AGENT_ENTRY_SCHEMA_VERSION` | constant: const PAPER_AGENT_ENTRY_SCHEMA_VERSION | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_AGENT_ENTRY_SCHEMA_VERSION } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:19` |
-| `PAPER_AGENT_ENTRY_SECTION_END` | constant: const PAPER_AGENT_ENTRY_SECTION_END | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_AGENT_ENTRY_SECTION_END } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:22` |
-| `PAPER_AGENT_ENTRY_SECTION_START` | constant: const PAPER_AGENT_ENTRY_SECTION_START | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_AGENT_ENTRY_SECTION_START } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:20` |
+| `mergePaperAgentEntryInstructions` | function: function mergePaperAgentEntryInstructions(current = "", { developmentRef }) | current = "", { developmentRef } | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { mergePaperAgentEntryInstructions } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:69` |
+| `PAPER_AGENT_ENTRY_CONTRACT` | constant: const PAPER_AGENT_ENTRY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_AGENT_ENTRY_CONTRACT } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:24` |
+| `PAPER_AGENT_ENTRY_SCHEMA_VERSION` | constant: const PAPER_AGENT_ENTRY_SCHEMA_VERSION | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_AGENT_ENTRY_SCHEMA_VERSION } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:25` |
+| `PAPER_AGENT_ENTRY_SECTION_END` | constant: const PAPER_AGENT_ENTRY_SECTION_END | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_AGENT_ENTRY_SECTION_END } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:28` |
+| `PAPER_AGENT_ENTRY_SECTION_START` | constant: const PAPER_AGENT_ENTRY_SECTION_START | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_AGENT_ENTRY_SECTION_START } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:26` |
 | `PAPER_ALPHA_PLAN_CONTRACT` | constant: const PAPER_ALPHA_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_ALPHA_PLAN_CONTRACT } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:98` |
 | `PAPER_BUILD_PLAN_CONTRACT` | constant: const PAPER_BUILD_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_BUILD_PLAN_CONTRACT } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:97` |
 | `PAPER_FLEET_AUDIT_CONTRACT` | constant: const PAPER_FLEET_AUDIT_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_FLEET_AUDIT_CONTRACT } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-fleet.js:19` |
@@ -2361,13 +2361,13 @@ Target: `./packages/core/paper.js`. Public symbols: 48.
 | `PAPER_VISIBILITY_CONTRACT` | constant: const PAPER_VISIBILITY_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_VISIBILITY_CONTRACT } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:100` |
 | `PAPER_WORK_START_PLAN_CONTRACT` | constant: const PAPER_WORK_START_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_WORK_START_PLAN_CONTRACT } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:17` |
 | `PAPER_WORK_SUBMIT_PLAN_CONTRACT` | constant: const PAPER_WORK_SUBMIT_PLAN_CONTRACT | none | value | Import does not declare a throw contract. | none-on-import | `import { PAPER_WORK_SUBMIT_PLAN_CONTRACT } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-work.js:19` |
-| `paperAgentEntryFiles` | function: function paperAgentEntryFiles({ cwd, buildchainVersion, buildchainSha, developmentRef = "", }) | { cwd, buildchainVersion, buildchainSha, developmentRef = "", } | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { paperAgentEntryFiles } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:152` |
-| `paperAgentEntryInstructions` | function: function paperAgentEntryInstructions({ developmentRef }) | { developmentRef } | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { paperAgentEntryInstructions } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:38` |
+| `paperAgentEntryFiles` | function: function paperAgentEntryFiles({ cwd, buildchainVersion, buildchainSha, developmentRef = "", }) | { cwd, buildchainVersion, buildchainSha, developmentRef = "", } | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { paperAgentEntryFiles } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:176` |
+| `paperAgentEntryInstructions` | function: function paperAgentEntryInstructions({ developmentRef }) | { developmentRef } | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { paperAgentEntryInstructions } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:44` |
 | `paperFleetTransitionWorkspace` | function: function paperFleetTransitionWorkspace(workspaceText, lockText) | workspaceText, lockText | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { paperFleetTransitionWorkspace } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-fleet.js:290` |
 | `planPaperFleetUpdate` | function: function planPaperFleetUpdate(options = {}) | options = {} | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { planPaperFleetUpdate } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-fleet.js:209` |
 | `planPaperMigration` | value: planPaperMigration | none | unknown | No narrower error contract was mechanically discoverable. | unknown | `import { planPaperMigration } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:1` |
 | `planPaperScaffold` | value: planPaperScaffold | none | unknown | No narrower error contract was mechanically discoverable. | unknown | `import { planPaperScaffold } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:1` |
-| `resolvePaperBuildchainSha` | function: function resolvePaperBuildchainSha(buildchainRoot, buildchainSha = "") | buildchainRoot, buildchainSha = "" | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { resolvePaperBuildchainSha } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:181` |
+| `resolvePaperBuildchainSha` | function: function resolvePaperBuildchainSha(buildchainRoot, buildchainSha = "") | buildchainRoot, buildchainSha = "" | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { resolvePaperBuildchainSha } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-agent-entry.js:205` |
 | `resolvePaperRepository` | function: function resolvePaperRepository(cwd = process.cwd()) | cwd = process.cwd() | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | none-detected-by-static-source-scan | `import { resolvePaperRepository } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-repository.js:133` |
 | `resolvePaperRuntimeGitSha` | function: function resolvePaperRuntimeGitSha(buildchainRoot, buildchainVersion = "") | buildchainRoot, buildchainVersion = "" | unknown | May throw an Error on rejected input or failed operations; follow the linked source contract. | none-detected-by-static-source-scan | `import { resolvePaperRuntimeGitSha } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper.js:253` |
 | `writePaperFleetUpdate` | function: function writePaperFleetUpdate(plan) | plan | unknown | Errors from called operations may propagate; no narrower throw contract is declared in source. | may-write-or-invoke-external-actions | `import { writePaperFleetUpdate } from "@kungfu-tech/buildchain/paper";` | `packages/core/paper-fleet.js:271` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.0.2-alpha.42",
+  "version": "4.0.2-alpha.44",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

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

@@ -13,7 +13,13 @@ import {
   stableJson,
   workCheck,
 } from "./paper-repository.js";
-import { mergeNextDevelopmentAgentInstructions } from "./next-development-projection.js";
+import {
+  mergeNextDevelopmentAgentInstructions,
+  NEXT_DEVELOPMENT_AGENT_SECTION_START,
+  NEXT_DEVELOPMENT_AGENT_SECTION_END,
+  NEXT_DEVELOPMENT_LOCAL_COMMAND,
+} from "./next-development-projection.js";
+import { NEXT_DEVELOPMENT_ADR } from "./next-development-transition.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -149,6 +155,24 @@ export function createPaperAgentEntry({
   };
 }
 
+function mergePaperNextDevelopmentInstructions(current) {
+  const merged = mergeNextDevelopmentAgentInstructions(current);
+  const start = merged.indexOf(NEXT_DEVELOPMENT_AGENT_SECTION_START);
+  const end = merged.indexOf(NEXT_DEVELOPMENT_AGENT_SECTION_END);
+  const section = merged.slice(start, end)
+    .replace(
+      `\`${NEXT_DEVELOPMENT_ADR}\``,
+      `[Buildchain next-development ADR](https://github.com/kungfu-systems/buildchain/blob/v4/${NEXT_DEVELOPMENT_ADR})`,
+    )
+    .replace(
+      NEXT_DEVELOPMENT_LOCAL_COMMAND,
+      NEXT_DEVELOPMENT_LOCAL_COMMAND.replace(
+        "node scripts/", "node node_modules/@kungfu-tech/buildchain/scripts/",
+      ),
+    );
+  return `${merged.slice(0, start)}${section}${merged.slice(end)}`;
+}
+
 export function paperAgentEntryFiles({
   cwd,
   buildchainVersion,
@@ -169,7 +193,7 @@ export function paperAgentEntryFiles({
     [PAPER_PATHS.agentEntry, jsonText(entry)],
     [
       PAPER_PATHS.agentInstructions,
-      mergeNextDevelopmentAgentInstructions(
+      mergePaperNextDevelopmentInstructions(
         mergePaperAgentEntryInstructions(currentAgents, {
           developmentRef: resolvedDevelopmentRef,
         }),

package/packages/core/paper-runtime-channels.js

@@ -8,6 +8,7 @@ import {
   sha256Json,
 } from "./buildchain-contract.js";
 import {
+  commandResult,
   gitValue,
   readJson,
   sha256Text,
@@ -16,6 +17,70 @@ import {
 
 export const PAPER_ALPHA_LOCK = ".buildchain/alpha-contract-lock.json";
 
+export function resolvePaperNpmRuntimeSha(cwd, identity) {
+  if (!identity.version) return "";
+  const observed = commandResult(
+    "npm",
+    [
+      "view",
+      `${identity.name}@${identity.version}`,
+      "gitHead",
+      "--json",
+      "--registry=https://registry.npmjs.org",
+    ],
+    { cwd },
+  );
+  if (!observed.ok) return "";
+  let parsed;
+  try {
+    parsed = JSON.parse(observed.stdout || "null");
+  } catch {
+    return "";
+  }
+  const gitHead =
+    typeof parsed === "string" ? parsed : String(parsed?.gitHead || "");
+  return /^[0-9a-f]{40}$/i.test(gitHead)
+    ? gitHead
+    : resolvePaperPublishedTagSha(cwd, identity);
+}
+
+function resolvePaperPublishedTagSha(cwd, identity) {
+  if (
+    identity.name !== "@kungfu-tech/buildchain" ||
+    !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(
+      identity.version,
+    )
+  )
+    return "";
+  const ref = `refs/tags/v${identity.version}`;
+  const observed = commandResult(
+    "git",
+    [
+      "ls-remote",
+      "--exit-code",
+      "https://github.com/kungfu-systems/buildchain.git",
+      ref,
+      `${ref}^{}`,
+    ],
+    { cwd },
+  );
+  if (!observed.ok || !observed.stdout) return "";
+  const refs = new Map();
+  for (const line of observed.stdout.split(/\r?\n/)) {
+    const [sha, name, extra] = line.split(/\s+/);
+    if (
+      !/^[0-9a-f]{40}$/.test(sha) ||
+      ![ref, `${ref}^{}`].includes(name) ||
+      extra ||
+      refs.has(name)
+    )
+      return "";
+    refs.set(name, sha);
+  }
+  if (!refs.has(ref)) return "";
+  return refs.get(`${ref}^{}`) || refs.get(ref);
+}
+
 function fileDigestMatches(cwd, relative, digest) {
   if (!relative || !/^sha256:[0-9a-f]{64}$/.test(digest || "")) return false;
   const absolute = path.resolve(cwd, relative);

package/packages/core/paper.js

@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-import { bindPaperV4Authority, paperV4Channels, selectPaperRuntime, paperRuntimeLockPath, paperProvisioningWorkflowErrors } from "./paper-runtime-channels.js";
+import { bindPaperV4Authority, paperV4Channels, selectPaperRuntime, paperRuntimeLockPath, paperProvisioningWorkflowErrors, resolvePaperNpmRuntimeSha } from "./paper-runtime-channels.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -257,23 +257,7 @@ export function resolvePaperRuntimeGitSha(
   const value = resolvePaperBuildchainSha(buildchainRoot);
   if (GIT_SHA_PATTERN.test(value)) return value;
   const identity = buildchainPackageIdentity(buildchainRoot, buildchainVersion);
-  if (!identity.version) return "";
-  const observed = commandResult(
-    "npm",
-    [
-      "view",
-      `${identity.name}@${identity.version}`,
-      "gitHead",
-      "--json",
-      `--registry=${NPM_REGISTRY}`,
-    ],
-    { cwd: buildchainRoot },
-  );
-  if (!observed.ok) return "";
-  const parsed = safeParseJson(observed.stdout);
-  const gitHead =
-    typeof parsed === "string" ? parsed : String(parsed?.gitHead || "");
-  return GIT_SHA_PATTERN.test(gitHead) ? gitHead : "";
+  return resolvePaperNpmRuntimeSha(buildchainRoot, identity);
 }
 
 function runtimeAcceptedAt(buildchainRoot, sha, buildchainVersion = "") {
@@ -426,7 +410,7 @@ jobs:
 `;
 }
 
-function scaffoldVerifyWorkflow(buildchainSha) {
+function scaffoldVerifyWorkflow(buildchainSha, buildchainVersion = "") {
   return `${nextDevelopmentWorkflowHeader()}name: Verify
 
 on:
@@ -439,7 +423,7 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
+${buildchainVersion.startsWith("4.") ? "  actions: read\n  contents: read\n  pull-requests: read" : "  contents: read"}
 
 jobs:
   check:
@@ -637,7 +621,7 @@ function scaffoldFiles({
     artifactPaths: "_build/main.pdf",
     releasePassportProductName: title,
   });
-  const verifyWorkflow = scaffoldVerifyWorkflow(buildchainSha);
+  const verifyWorkflow = scaffoldVerifyWorkflow(buildchainSha, buildchainVersion);
   const agentEntry = paperAgentEntryFiles({
     cwd,
     buildchainVersion,
@@ -772,7 +756,7 @@ function migrationFiles({
     artifactPaths: config.publication.artifactPaths.join(","),
     releasePassportProductName: config.publication.title,
   });
-  const verifyWorkflow = scaffoldVerifyWorkflow(runtimeSha);
+  const verifyWorkflow = scaffoldVerifyWorkflow(runtimeSha, runtimeIdentity.version);
   const agentEntry = paperAgentEntryFiles({
     cwd,
     buildchainVersion: runtimeIdentity.version,