@kungfu-tech/buildchain 4.0.2-alpha.37 → 4.0.2-alpha.38

package/dist/site/workflow-registry.json

@@ -2746,7 +2746,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.2-alpha.37",
+      "introducedVersion": "4.0.2-alpha.38",
       "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.37",
+      "introducedVersion": "4.0.2-alpha.38",
       "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.37",
+      "introducedVersion": "4.0.2-alpha.38",
       "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.37",
+      "introducedVersion": "4.0.2-alpha.38",
       "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.37",
+      "introducedVersion": "4.0.2-alpha.38",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -6628,126 +6628,6 @@
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
       "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
-    },
-    {
-      "id": "v4-adopter-delivery",
-      "path": ".github/workflows/v4-adopter-delivery.yml",
-      "reusable": true,
-      "inputs": [
-        "archive-path",
-        "bootstrap-path",
-        "consumer",
-        "consumer-ref",
-        "consumer-repository",
-        "input-path",
-        "invocation-source-path",
-        "node-version",
-        "universal-request-json"
-      ],
-      "inputCount": 9,
-      "secrets": [],
-      "secretCount": 0,
-      "outputs": [],
-      "outputCount": 0,
-      "taxonomy": {
-        "id": "v4-adopter-delivery",
-        "role": "public",
-        "category": "build",
-        "purpose": "adopter-qualification",
-        "status": "active",
-        "canonicalPath": ".github/workflows/public-build-adopter-qualification.yml",
-        "compatibilityAlias": true
-      },
-      "surface": "repository-workflow",
-      "capabilityGroup": "api-cli-reference",
-      "status": "active",
-      "owner": "buildchain-workflows",
-      "maturity": "active",
-      "introducedVersion": "pre-3.0.2-alpha.4",
-      "compatibilityPromise": "preserved-through-the-v3-major-line",
-      "deprecationReplacement": "",
-      "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
-      "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
-    },
-    {
-      "id": "v4-stage-capsule-canary",
-      "path": ".github/workflows/v4-stage-capsule-canary.yml",
-      "reusable": true,
-      "inputs": [
-        "build-artifact-path",
-        "consumer",
-        "go-version",
-        "install-artifact-path",
-        "node-version",
-        "universal-request-json",
-        "verify-artifact-path"
-      ],
-      "inputCount": 7,
-      "secrets": [],
-      "secretCount": 0,
-      "outputs": [],
-      "outputCount": 0,
-      "taxonomy": {
-        "id": "v4-stage-capsule-canary",
-        "role": "public",
-        "category": "build",
-        "purpose": "stage-capsule-canary",
-        "status": "active",
-        "canonicalPath": ".github/workflows/public-build-stage-capsule-canary.yml",
-        "compatibilityAlias": true
-      },
-      "surface": "repository-workflow",
-      "capabilityGroup": "api-cli-reference",
-      "status": "active",
-      "owner": "buildchain-workflows",
-      "maturity": "active",
-      "introducedVersion": "pre-3.0.2-alpha.4",
-      "compatibilityPromise": "preserved-through-the-v3-major-line",
-      "deprecationReplacement": "",
-      "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
-      "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
-    },
-    {
-      "id": "v4-tail-reseal",
-      "path": ".github/workflows/v4-tail-reseal.yml",
-      "reusable": true,
-      "inputs": [
-        "artifact-retention-days",
-        "consumer-policy-receipt-json",
-        "macos-finalization-command",
-        "request-json",
-        "universal-request-json"
-      ],
-      "inputCount": 5,
-      "secrets": [
-        "BUILDCHAIN_EVIDENCE_READ_TOKEN",
-        "BUILDCHAIN_SIGNING_TOKEN"
-      ],
-      "secretCount": 2,
-      "outputs": [
-        "release-candidate-passport-json",
-        "tail-reseal-receipt-root"
-      ],
-      "outputCount": 2,
-      "taxonomy": {
-        "id": "v4-tail-reseal",
-        "role": "public",
-        "category": "ops",
-        "purpose": "tail-reseal",
-        "status": "active",
-        "canonicalPath": ".github/workflows/public-ops-tail-reseal.yml",
-        "compatibilityAlias": true
-      },
-      "surface": "repository-workflow",
-      "capabilityGroup": "api-cli-reference",
-      "status": "active",
-      "owner": "buildchain-workflows",
-      "maturity": "active",
-      "introducedVersion": "pre-3.0.2-alpha.4",
-      "compatibilityPromise": "preserved-through-the-v3-major-line",
-      "deprecationReplacement": "",
-      "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
-      "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
     }
   ],
   "actionSource": "actions/*/action.yml reverse input enumeration",

package/docs/next-development-transition.md

@@ -77,7 +77,7 @@ invalid.
 ## Public self-dogfood and adoption
 
 `.github/workflows/self-build-public-consumer-dogfood.yml` remains the exact thin
-consumer of the public `v4-stage-capsule-canary.yml@v4-alpha` contract. Its
+consumer of the public `public-build-stage-capsule-canary.yml@v4-alpha` contract. Its
 declared `lifecycle.verify` runs `pnpm run check`, so the same public path
 executes pure recovery tests that inject a transient durable-state write
 failure, restore the adapter operation on a fresh runner, supersede stale work

package/docs/v4-adopter-delivery.md

@@ -110,7 +110,7 @@ artifact_profile_selector = "package"
 ```
 
 The public reusable workflow is
-`kungfu-systems/buildchain/.github/workflows/v4-adopter-delivery.yml@v4` for
+`kungfu-systems/buildchain/.github/workflows/public-build-adopter-qualification.yml@v4` for
 stable use and `@v4-alpha` during prerelease evaluation. It resolves the exact
 called-workflow SHA, enforces floating selector plus dual-lock consumer
 admission, and runs the same CLI on Linux, macOS, and Windows. Buildchain

package/docs/v4-stage-capsule.md

@@ -136,7 +136,7 @@ shadow-only: it does not skip a v3 production stage or move v3 authority.
 `architecture/v4-stage-capsule-qualification.json` closes the Wave 2
 qualification boundary. Buildchain and external repositories use the same
 Buildchain-owned public reusable workflow,
-`.github/workflows/v4-stage-capsule-canary.yml`. Buildchain's caller is the thin
+`.github/workflows/public-build-stage-capsule-canary.yml`. Buildchain's caller is the thin
 `.github/workflows/self-build-public-consumer-dogfood.yml`; it has no steps, copied
 orchestration, local action, direct qualification invocation, or private
 consumer profile. Candidate recursion is resolved only by publishing the exact

package/docs/v4-tail-reseal.md

@@ -56,7 +56,7 @@ receipt creation and verification.
 ## Reusable workflow
 
 Consumers invoke
-`kungfu-systems/buildchain/.github/workflows/v4-tail-reseal.yml@v4-alpha` from a
+`kungfu-systems/buildchain/.github/workflows/public-ops-tail-reseal.yml@v4-alpha` from a
 trusted, same-repository workflow. The caller supplies the rooted request, the
 original candidate consumer-policy receipt, a reviewed macOS finalization
 command, and the explicitly named signing secret. The command must write:

package/docs/workflow-catalog.md

@@ -56,6 +56,8 @@ must explain its scope in review. New aliases cannot be invented: compatibility
 must name an exact migration source with a reason and removal condition.
 The policy, generator, checker, tests, required CI chain and CODEOWNERS require
 independent `kungfu-origin` review. No wildcard compatibility admission is allowed.
+Workflow filenames cannot contain version tokens such as `v4` or `v5`.
+Retired aliases cannot be recreated or called; see [path migration](workflow-path-migration.md).
 
 A role, category or implementation edit must preserve or deliberately update
 all related declarations. Run `pnpm run generate:workflows` and
@@ -65,12 +67,12 @@ all related declarations. Run `pnpm run generate:workflows` and
 
 | Canonical workflow | Category | Invocation | Status | Purpose | Compatibility path |
 | --- | --- | --- | --- | --- | --- |
-| [public-build-adopter-qualification.yml](../.github/workflows/public-build-adopter-qualification.yml) | build | reusable | active | V4 Adopter Delivery | `v4-adopter-delivery.yml` |
+| [public-build-adopter-qualification.yml](../.github/workflows/public-build-adopter-qualification.yml) | build | reusable | active | V4 Adopter Delivery | — |
 | [public-build-candidate.yml](../.github/workflows/public-build-candidate.yml) | build | reusable | active | Buildchain Channel Build | `build.yml` |
 | [public-build-check.yml](../.github/workflows/public-build-check.yml) | build | reusable | active | Buildchain Check | `check.yml` |
 | [public-build-demo.yml](../.github/workflows/public-build-demo.yml) | build | reusable | active | Buildchain Declarative Binary Auditable Demo | `.declarative-auditable-demo.yml` |
 | [public-build-publication.yml](../.github/workflows/public-build-publication.yml) | build | reusable | active | Buildchain Publication Artifact | `publication-artifact.yml` |
-| [public-build-stage-capsule-canary.yml](../.github/workflows/public-build-stage-capsule-canary.yml) | build | reusable | active | V4 Stage Capsule Canary | `v4-stage-capsule-canary.yml` |
+| [public-build-stage-capsule-canary.yml](../.github/workflows/public-build-stage-capsule-canary.yml) | build | reusable | active | V4 Stage Capsule Canary | — |
 | [public-ops-alpha-candidate-patrol.yml](../.github/workflows/public-ops-alpha-candidate-patrol.yml) | ops | reusable | active | Buildchain Dev to Alpha Candidate Patrol | `dev-alpha-candidate-patrol.yml` |
 | [public-ops-bootstrap-recovery.yml](../.github/workflows/public-ops-bootstrap-recovery.yml) | ops | reusable | active | Universal Buildchain Bootstrap Recovery | `universal-bootstrap-recovery.yml` |
 | [public-ops-bootstrap.yml](../.github/workflows/public-ops-bootstrap.yml) | ops | reusable | active | Buildchain Universal Bootstrap | `bootstrap.yml` |
@@ -84,7 +86,7 @@ all related declarations. Run `pnpm run generate:workflows` and
 | [public-ops-patrol.yml](../.github/workflows/public-ops-patrol.yml) | ops | reusable | active | Buildchain Patrol | `buildchain-patrol.yml` |
 | [public-ops-release-governance.yml](../.github/workflows/public-ops-release-governance.yml) | ops | reusable | active | Release Governance Reconcile | `release-governance-reconcile.yml` |
 | [public-ops-stable-candidate-patrol.yml](../.github/workflows/public-ops-stable-candidate-patrol.yml) | ops | reusable | active | Buildchain Stable Candidate Patrol | `stable-candidate-patrol.yml` |
-| [public-ops-tail-reseal.yml](../.github/workflows/public-ops-tail-reseal.yml) | ops | reusable | active | V4 Retained Candidate Tail Reseal | `v4-tail-reseal.yml` |
+| [public-ops-tail-reseal.yml](../.github/workflows/public-ops-tail-reseal.yml) | ops | reusable | active | V4 Retained Candidate Tail Reseal | — |
 | [public-ops-warrant-cancel.yml](../.github/workflows/public-ops-warrant-cancel.yml) | ops | reusable | active | Dev Delivery Warrant Queued Candidate Cancel | `dev-delivery-warrant-cancel.yml` |
 | [public-ops-warrant-close.yml](../.github/workflows/public-ops-warrant-close.yml) | ops | reusable | active | Dev Delivery Warrant Close | `dev-delivery-warrant-close.yml` |
 | [public-release-artifact-attestation.yml](../.github/workflows/public-release-artifact-attestation.yml) | release | reusable | active | Buildchain GitHub Artifact Attestation | `github-artifact-attestation.yml` |

package/docs/workflow-path-migration.md

@@ -0,0 +1,109 @@
+---
+status: draft
+period: ongoing
+theme: workflow-path-migration
+doc_type: migration-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-06
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-05
+  visible_context: Exact GitHub channel refs and workflow files on 23 organization default branches
+  invisible_context_boundary: Other branches, private or unlisted consumers and future floating ref updates were not established by this audit
+---
+
+# Version-prefixed workflow path migration
+
+This source change retires three filenames. Their reusable capabilities, inputs,
+outputs, jobs and permission envelopes remain at the canonical paths below.
+Keep the existing channel selector and dual contract-lock policy when migrating.
+
+| Retired path | Canonical path |
+| --- | --- |
+| `v4-adopter-delivery.yml` | `public-build-adopter-qualification.yml` |
+| `v4-stage-capsule-canary.yml` | `public-build-stage-capsule-canary.yml` |
+| `v4-tail-reseal.yml` | `public-ops-tail-reseal.yml` |
+
+All paths are beneath `.github/workflows/`. The taxonomy gate rejects version
+segments in filenames and calls to version-prefixed Buildchain workflows. An
+explicit retirement record keeps the original migration identity for historical
+metrics and frozen facade source; generators resolve that identity to the
+canonical implementation and cannot recreate the removed file.
+
+## Development merge and channel rollout
+
+The development change retires these filenames on `dev/v4/v4.0`, updates the
+Buildchain-owned callers, and enforces the canonical paths through generators
+and required checks. Its delivery boundary is the protected development merge.
+External-repository migration and stable publication are separate follow-up
+work and do not block this development merge.
+
+The published channel boundary still requires the following rollout order:
+
+1. Publish and verify the canonical entries on every affected channel while the
+   old entries remain available. The admission identity must match the actual
+   invoked canonical workflow, rather than its previous filename.
+2. Migrate consumers on their existing floating channels, refresh locks through
+   the supported contract acceptance path if required, and verify real consumer
+   runs. Stable callers remain on stable; alpha callers remain on alpha.
+3. Before publishing the retirement into a channel, recheck its live consumers
+   and resolve any remaining old-path calls. A protected development merge does
+   not by itself establish this channel readiness.
+
+## Initial consumer readback
+
+On 2026-09-05, all workflow files from 23 accessible `kungfu-systems` repository
+_default branches_ were read at their returned Git revisions. Five calls were
+found in three repositories. This is a bounded inventory, not evidence that
+unknown or non-default-branch consumers do not exist.
+
+| Repository and observed revision | Caller | Existing selector |
+| --- | --- | --- |
+| Buildchain `d434a73d2d4fb010ee80fede2bf3ce872b1d04c8` | `self-build-adopter-dogfood.yml` | `v4-alpha` |
+| Buildchain `d434a73d2d4fb010ee80fede2bf3ce872b1d04c8` | `self-build-public-consumer-dogfood.yml` | `v4-alpha` |
+| agent-hub-demo `3f5de882b63464d70c50df0fd7ca418f487b794b` | `v4-adopter-delivery-qualification.yml` | `v4-alpha` |
+| agent-hub-demo `3f5de882b63464d70c50df0fd7ca418f487b794b` | `v4-stage-capsule-canary.yml` | `v4` |
+| taolu `6dcccdc3bd2c8b1801c7f6decea08ae7877aac2b` | `verify.yml` | `v4-alpha` |
+
+The initial published channel readback was `v4` at
+`da5e2db8384313e899eace87aea0a1a8e28c0aa8` and `v4-alpha` at
+`dd87f43f7122b41c4ce7f1f6d1888521cc7f892f`. Neither contained the three canonical
+filenames at that initial readback. The later evidence below records progress
+without changing the scope or revisions of that initial inventory.
+
+## Rollout evidence as of 2026-09-06
+
+The canonical invocation-identity preparation was merged in
+[Buildchain PR 3508](https://github.com/kungfu-systems/buildchain/pull/3508).
+All three canonical paths are available in the immutable `v4.0.2-alpha.35`
+release (`feab078f5d7c9927a3525154003e321700e8ca30`) and the later
+`v4.0.2-alpha.37` release (`f5fa1a4a3e8d83eccee79c077e5f48417760c9df`).
+The floating `v4-alpha` readback selects alpha.37.
+
+[Taolu PR 30](https://github.com/kungfu-systems/taolu/pull/30) migrated its
+Stage Capsule call on `@v4-alpha`, preserving the existing dual locks.
+Its exact source `b3f4c12578d733ff44165ff1acafe131251b8907` passed
+[consumer Verify](https://github.com/kungfu-systems/taolu/actions/runs/33975786413)
+on all declared platforms and
+[native delivery](https://github.com/kungfu-systems/taolu/actions/runs/34005576362).
+The protected dev landing is `7e15123733110ad8ce484241934bbf0ef99fbb45`.
+
+The stable `v4` readback remains
+`da5e2db8384313e899eace87aea0a1a8e28c0aa8`, which does not contain the canonical
+paths. Stable publication and the agent-hub-demo migration remain **pending**
+outside this development change's completion boundary. The alpha.35
+[Build Surface Fixture](https://github.com/kungfu-systems/buildchain/actions/runs/34005360217)
+passed, but this individual result does not establish complete stable
+qualification or authorize moving the stable channel.
+
+## Recovery
+
+Before channel retirement, revert consumer changes to the still-available old
+paths if verification fails. After retirement, restore the exact previous
+provider implementation through a reviewed corrective commit and normal
+publication; do not rewrite immutable release tags or bypass admission checks.

package/package.json

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

package/packages/core/next-development-projection.js

@@ -244,7 +244,7 @@ invalid.
 ## Public self-dogfood and adoption
 
 \`.github/workflows/self-build-public-consumer-dogfood.yml\` remains the exact thin
-consumer of the public \`v4-stage-capsule-canary.yml@v4-alpha\` contract. Its
+consumer of the public \`public-build-stage-capsule-canary.yml@v4-alpha\` contract. Its
 declared \`lifecycle.verify\` runs \`pnpm run check\`, so the same public path
 executes pure recovery tests that inject a transient durable-state write
 failure, restore the adapter operation on a fresh runner, supersede stale work

package/scripts/check-v4-floating-consumer-policy-contract.mjs

@@ -148,7 +148,7 @@ export function checkV4FloatingConsumerPolicyContract() {
     "Resolve controller identities",
     "Install Buildchain runtime dependencies",
   ]);
-  const stageCanary = read(".github/workflows/v4-stage-capsule-canary.yml");
+  const stageCanary = read(".github/workflows/public-build-stage-capsule-canary.yml");
   if (
     !stageCanary.includes("consumer-admission:") ||
     !stageCanary.includes("needs: consumer-admission")

package/scripts/check-v4-public-dogfood-contract.mjs

@@ -10,7 +10,7 @@ const DEFAULT_ROOT = path.resolve(
   "..",
 );
 const CALLER_PATH = ".github/workflows/self-build-public-consumer-dogfood.yml";
-const REUSABLE_PATH = ".github/workflows/v4-stage-capsule-canary.yml";
+const REUSABLE_PATH = ".github/workflows/public-build-stage-capsule-canary.yml";
 export const V4_PUBLIC_DOGFOOD_ALPHA_REF = "v4-alpha";
 const PRIVATE_CONSUMER = ["buildchain", "self", "dogfood"].join("-");
 const PRIVATE_SHADOW = ["kungfu", "shadow"].join("-");
@@ -27,7 +27,7 @@ permissions:
 
 jobs:
   dogfood:
-    uses: kungfu-systems/buildchain/.github/workflows/v4-stage-capsule-canary.yml@${validationRef}
+    uses: kungfu-systems/buildchain/.github/workflows/public-build-stage-capsule-canary.yml@${validationRef}
     with:
       consumer: buildchain
       node-version: "24"
@@ -114,7 +114,7 @@ function assertWorkflowInventory(root) {
       fail(`${relative} invokes the private qualification script directly`);
     if (
       relative !== CALLER_PATH &&
-      text.includes(".github/workflows/v4-stage-capsule-canary.yml@")
+      text.includes(".github/workflows/public-build-stage-capsule-canary.yml@")
     )
       fail(`${relative} creates a second v4 dogfood caller`);
     if (relative !== REUSABLE_PATH && relative !== CALLER_PATH)
@@ -162,7 +162,7 @@ function assertArchitecture(root) {
     !dogfood ||
     dogfood.callerWorkflow !== CALLER_PATH ||
     dogfood.reusableWorkflow !==
-      "kungfu-systems/buildchain/.github/workflows/v4-stage-capsule-canary.yml" ||
+      "kungfu-systems/buildchain/.github/workflows/public-build-stage-capsule-canary.yml" ||
     dogfood.runtimeBinding !== "job.workflow_sha" ||
     dogfood.consumerSourceBinding !== "github.sha" ||
     JSON.stringify(dogfood.executableStages) !==

package/scripts/check-v4-universal-workflow-bootstrap.mjs

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { projectWorkflowIdentities } from "./workflow-taxonomy.mjs";
+import { currentWorkflowPath, projectWorkflowIdentities } from "./workflow-taxonomy.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -48,7 +48,7 @@ assert.deepEqual(
 );
 for (const relative of contract.inventoryWorkflows)
   assert.ok(
-    fs.statSync(path.join(root, relative)).isFile(),
+    fs.statSync(path.join(root, currentWorkflowPath(root, relative))).isFile(),
     `inventoried workflow is unavailable: ${relative}`,
   );
 assert.deepEqual(
@@ -87,7 +87,7 @@ for (const relative of contract.bootstrapGovernedWorkflows) {
     contract.inventoryWorkflows.includes(relative),
     `Bootstrap-governed workflow is outside the inventory: ${relative}`,
   );
-  const source = fs.readFileSync(path.join(root, relative), "utf8");
+  const source = fs.readFileSync(path.join(root, currentWorkflowPath(root, relative)), "utf8");
   assert.ok(
     relative === contract.bootstrap.publicWorkflow ||
       /uses:\s+(?:\.\/)?\.github\/workflows\/bootstrap\.yml/u.test(source) ||

package/scripts/generate-v4-universal-workflow-facades.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import crypto from "node:crypto";
-import { writeWorkflowSource, rewriteRepositoryWorkflowPaths } from "./workflow-taxonomy.mjs";
+import { currentWorkflowPath, writeWorkflowSource, rewriteRepositoryWorkflowPaths } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -426,14 +426,15 @@ function main() {
     );
   }
   for (const relative of activeFacadePaths()) {
-    const target = path.join(root, relative);
+    const current = currentWorkflowPath(root, relative);
+    const target = path.join(root, current);
     const source = fresh
       ? frozenFacadeSource(relative)
       : fs.readFileSync(target, "utf8");
     if (check) verify(source, relative);
     else
       writeWorkflowSource(
-        root, relative,
+        root, current,
         migrateV4UniversalWorkflowFacade(source, relative),
       );
   }

package/scripts/v4-universal-workflow-engine.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import crypto from "node:crypto";
 import fs from "node:fs";
+import { currentWorkflowPath } from "./workflow-taxonomy.mjs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import {
@@ -192,7 +193,7 @@ function executeBootstrapConformance(request, admission) {
     fail("candidate Bootstrap conformance does not close execution semantics");
   for (const relative of architecture.bootstrapGovernedWorkflows) {
     const source = fs.readFileSync(
-      new URL(`../${relative}`, import.meta.url),
+      path.join(path.resolve(import.meta.dirname, ".."), currentWorkflowPath(path.resolve(import.meta.dirname, ".."), relative)),
       "utf8",
     );
     if (

package/scripts/workflow-taxonomy.mjs

@@ -12,6 +12,7 @@ const ROLES = ["public", "component", "self"];
 const CATEGORIES = ["build", "release", "ops"];
 const SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
 const WORKFLOW = /^\.github\/workflows\/[.a-z0-9-]+\.ya?ml$/u;
+const VERSION_TOKEN = /(?:^|[.-])v\d+(?:[.-]|$)/iu;
 const PROTECTED = [
   TAXONOMY_PATH,
   "scripts/workflow-taxonomy.mjs",
@@ -40,6 +41,10 @@ function validateEntryRole(entry, errors) {
     errors.push(`${entry.id}: invalid category`);
   if (!SLUG.test(entry.purpose || ""))
     errors.push(`${entry.id}: invalid purpose slug`);
+  if (VERSION_TOKEN.test(path.posix.basename(workflowPath(entry))))
+    errors.push(
+      `${entry.id}: workflow filenames cannot contain version tokens`,
+    );
   for (const field of ["summary", "owner", "rationale"]) {
     if (typeof entry[field] !== "string" || !entry[field].trim())
       errors.push(`${entry.id}: missing ${field}`);
@@ -57,6 +62,15 @@ function validateEntryRole(entry, errors) {
 }
 
 function validateMigration(policy, entry, declared, errors) {
+  if (entry.retiredAlias) {
+    if (
+      entry.compatibility ||
+      entry.retiredAlias.path !== entry.migration?.previousPath ||
+      !entry.retiredAlias.reason?.trim() ||
+      entry.retiredAlias.migrationGuide !== "docs/workflow-path-migration.md"
+    )
+      errors.push(`${entry.id}: invalid alias retirement record`);
+  }
   if (entry.migration) {
     if (
       !WORKFLOW.test(entry.migration.previousPath || "") ||
@@ -73,6 +87,10 @@ function validateMigration(policy, entry, declared, errors) {
   }
   if (entry.compatibility) {
     const alias = entry.compatibility;
+    if (VERSION_TOKEN.test(path.posix.basename(alias.path || "")))
+      errors.push(
+        `${entry.id}: version-prefixed compatibility aliases are retired`,
+      );
     if (entry.role === "self")
       errors.push(
         `${entry.id}: repository event wrappers cannot have duplicate aliases`,
@@ -167,6 +185,14 @@ function validateWorkflow(root, entry, declared, errors) {
   const absolute = path.join(root, file);
   if (!fs.existsSync(absolute) || !fs.lstatSync(absolute).isFile()) return;
   const text = fs.readFileSync(absolute, "utf8");
+  if (
+    entry.retiredAlias &&
+    text.includes("BUILDCHAIN_INVOKED_WORKFLOW:") &&
+    !text.includes(`BUILDCHAIN_INVOKED_WORKFLOW: ${file}\n`)
+  )
+    errors.push(
+      `${file}: consumer admission must bind the canonical invoked workflow`,
+    );
   const document = parseWorkflowDocument(text);
   if (entry.role === "self")
     validateRepositoryReferences(file, document, text, declared, errors);
@@ -195,6 +221,13 @@ function validateWorkflow(root, entry, declared, errors) {
       );
   }
   for (const call of parseYamlUses(text)) {
+    const remote = call.value.match(
+      /^kungfu-systems\/buildchain\/(\.github\/workflows\/[^@]+)@/u,
+    );
+    if (remote && VERSION_TOKEN.test(path.posix.basename(remote[1])))
+      errors.push(
+        `${file}:${call.line}: retired version-prefixed workflow call ${remote[1]}`,
+      );
     const local = call.value.match(/^\.\/(\.github\/workflows\/[^@]+)$/u);
     if (local && !declared.has(local[1]))
       errors.push(
@@ -276,6 +309,8 @@ export function checkWorkflowTaxonomy(
   );
   const observed = new Set(discoverWorkflowFiles(root));
   for (const file of observed) {
+    if (VERSION_TOKEN.test(path.posix.basename(file)))
+      errors.push(`workflow filenames cannot contain version tokens: ${file}`);
     if (!declared.has(file)) errors.push(`unregistered workflow: ${file}`);
     if (!fs.lstatSync(path.join(root, file)).isFile())
       errors.push(`workflow must be a regular file: ${file}`);
@@ -334,6 +369,8 @@ export function writeWorkflowSource(root, relative, text) {
     (item) =>
       workflowPath(item) === relative || item.compatibility?.path === relative,
   );
+  if (policy?.entries.some((item) => item.retiredAlias?.path === relative))
+    throw new Error(`${relative}: cannot regenerate a retired workflow alias`);
   const outputs = entry
     ? [
         workflowPath(entry),
@@ -345,19 +382,10 @@ export function writeWorkflowSource(root, relative, text) {
 
 export function rewriteRepositoryWorkflowPaths(root, text) {
   for (const entry of readWorkflowTaxonomy(root)?.entries || []) {
-    if (
-      ["v4-adopter-delivery", "v4-stage-capsule-canary"].includes(entry.id) &&
-      entry.compatibility
-    ) {
-      const canonical = workflowPath(entry);
-      const legacy = entry.compatibility.path;
-      text = text.replaceAll(
-        `BUILDCHAIN_INVOKED_WORKFLOW: ${legacy}\n`,
-        `BUILDCHAIN_INVOKED_WORKFLOW: \${{ startsWith(job.workflow_ref, 'kungfu-systems/buildchain/${canonical}@') && '${canonical}' || '${legacy}' }}\n`,
-      );
-    }
     if (entry.role === "self" && entry.migration)
       text = text.replaceAll(entry.migration.previousPath, workflowPath(entry));
+    if (entry.retiredAlias)
+      text = text.replaceAll(entry.retiredAlias.path, workflowPath(entry));
     if (entry.id === "build-surface-fixture")
       text = text.replaceAll(
         "build-surface-fixture.yml",
@@ -367,6 +395,15 @@ export function rewriteRepositoryWorkflowPaths(root, text) {
   return text;
 }
 
+// Historical inventories and debt ledgers retain their original identity. File
+// access resolves only explicitly retired aliases to the registered implementation.
+export function currentWorkflowPath(root, relative) {
+  const entry = readWorkflowTaxonomy(root)?.entries.find(
+    (item) => item.retiredAlias?.path === relative,
+  );
+  return entry ? workflowPath(entry) : relative;
+}
+
 export function workflowCompatibilityIdentity(root, relative, text) {
   const entry = readWorkflowTaxonomy(root)?.entries.find(
     (item) => workflowPath(item) === relative && item.compatibility,
@@ -441,6 +478,8 @@ export function renderWorkflowCatalog(policy) {
     "must name an exact migration source with a reason and removal condition.",
     "The policy, generator, checker, tests, required CI chain and CODEOWNERS require",
     "independent `kungfu-origin` review. No wildcard compatibility admission is allowed.",
+    "Workflow filenames cannot contain version tokens such as `v4` or `v5`.",
+    "Retired aliases cannot be recreated or called; see [path migration](workflow-path-migration.md).",
     "",
     "A role, category or implementation edit must preserve or deliberately update",
     "all related declarations. Run `pnpm run generate:workflows` and",