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

package/dist/site/workflow-registry.json

@@ -467,6 +467,7 @@
         "buildchain-ref",
         "buildchain-repository",
         "channel",
+        "declarative-release-tail",
         "dry-run",
         "github-artifact-attestation-environment",
         "github-artifact-attestation-policy-json",
@@ -489,12 +490,14 @@
         "promotion-shell-sha",
         "promotion-target-ref",
         "publication-admission-json",
+        "publication-authority-workflow-path",
         "publication-auto-admission",
         "publication-auto-no-gate",
         "publication-commit-command",
         "publication-commit-evidence-path",
         "publication-consumer-predicate-id",
         "publication-consumer-qualification-command",
+        "publication-consumer-qualification-controller-sha",
         "publication-control-plane-audit-json",
         "publication-expected-json",
         "publication-gate-aggregate-json",
@@ -563,7 +566,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 107,
+      "inputCount": 110,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -600,9 +603,14 @@
         "release-candidate-artifact",
         "release-candidate-recovery-receipt-artifact",
         "release-candidate-recovery-root",
-        "release-propagation-work-artifact"
-      ],
-      "outputCount": 23,
+        "release-propagation-work-artifact",
+        "release-tail-declaration-root",
+        "release-tail-receipt-roots-json",
+        "release-tail-state-root",
+        "release-tail-transaction-root",
+        "release-tail-transaction-state"
+      ],
+      "outputCount": 28,
       "surface": "reusable-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active",
@@ -1819,6 +1827,7 @@
       "path": ".github/workflows/dev-pr-auto-merge.yml",
       "reusable": true,
       "inputs": [
+        "active-lease-context",
         "affected-paths-json",
         "allowed-head-prefixes",
         "assignment-root",
@@ -1834,6 +1843,7 @@
         "dry-run",
         "expected-head-sha",
         "expected-pr-number",
+        "handoff-workflow-id",
         "initiative-root",
         "landing-mode",
         "max-merges",
@@ -1848,11 +1858,13 @@
         "shard-evidence-roots-json",
         "source-identity-root",
         "source-patch-root",
+        "source-workflow-id",
+        "source-workflow-run-id",
         "target-branch",
         "toolchain-root",
         "warrant-lease-seconds"
       ],
-      "inputCount": 32,
+      "inputCount": 36,
       "secrets": [
         "github-token"
       ],
@@ -1926,6 +1938,118 @@
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
       "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
     },
+    {
+      "id": "engineering-housekeeper-daily",
+      "path": ".github/workflows/engineering-housekeeper-daily.yml",
+      "reusable": false,
+      "inputs": [],
+      "inputCount": 0,
+      "secrets": [],
+      "secretCount": 0,
+      "outputs": [],
+      "outputCount": 0,
+      "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
+      "status": "preview",
+      "owner": "buildchain-workflows",
+      "maturity": "preview",
+      "introducedVersion": "3.0.7-alpha.1",
+      "compatibilityPromise": "preserved-through-the-v3-major-line",
+      "deprecationReplacement": "",
+      "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
+      "nonDuplicationRationale": "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."
+    },
+    {
+      "id": "engineering-housekeeper-monthly",
+      "path": ".github/workflows/engineering-housekeeper-monthly.yml",
+      "reusable": false,
+      "inputs": [],
+      "inputCount": 0,
+      "secrets": [],
+      "secretCount": 0,
+      "outputs": [],
+      "outputCount": 0,
+      "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
+      "status": "preview",
+      "owner": "buildchain-workflows",
+      "maturity": "preview",
+      "introducedVersion": "3.0.7-alpha.1",
+      "compatibilityPromise": "preserved-through-the-v3-major-line",
+      "deprecationReplacement": "",
+      "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
+      "nonDuplicationRationale": "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."
+    },
+    {
+      "id": "engineering-housekeeper-weekly",
+      "path": ".github/workflows/engineering-housekeeper-weekly.yml",
+      "reusable": false,
+      "inputs": [],
+      "inputCount": 0,
+      "secrets": [],
+      "secretCount": 0,
+      "outputs": [],
+      "outputCount": 0,
+      "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
+      "status": "preview",
+      "owner": "buildchain-workflows",
+      "maturity": "preview",
+      "introducedVersion": "3.0.7-alpha.1",
+      "compatibilityPromise": "preserved-through-the-v3-major-line",
+      "deprecationReplacement": "",
+      "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
+      "nonDuplicationRationale": "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."
+    },
+    {
+      "id": "engineering-housekeeper",
+      "path": ".github/workflows/engineering-housekeeper.yml",
+      "reusable": true,
+      "inputs": [
+        "apply-enabled",
+        "artifact-prefix",
+        "artifact-retention-days",
+        "buildchain-ref",
+        "buildchain-repository",
+        "max-actions",
+        "mode",
+        "protected-patterns",
+        "repository",
+        "retained-patterns",
+        "stale-days",
+        "stale-pull-request-label",
+        "target-branch"
+      ],
+      "inputCount": 13,
+      "secrets": [
+        "github_app_id",
+        "github_app_private_key",
+        "github_token"
+      ],
+      "secretCount": 3,
+      "outputs": [
+        "action-count",
+        "branch-receipt-root",
+        "outcome",
+        "plan-artifact",
+        "plan-root",
+        "pull-request-receipt-root",
+        "receipt-artifact",
+        "report-artifact",
+        "report-receipt-root"
+      ],
+      "outputCount": 9,
+      "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
+      "status": "preview",
+      "owner": "buildchain-workflows",
+      "maturity": "preview",
+      "introducedVersion": "3.0.7-alpha.1",
+      "compatibilityPromise": "preserved-through-the-v3-major-line",
+      "deprecationReplacement": "",
+      "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
+      "nonDuplicationRationale": "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."
+    },
     {
       "id": "github-artifact-attestation",
       "path": ".github/workflows/github-artifact-attestation.yml",
@@ -2371,6 +2495,7 @@
         "buildchain-repository",
         "buildchain-stable-contract-lock-path",
         "channel",
+        "declarative-release-tail",
         "dry-run",
         "github-artifact-attestation-environment",
         "github-artifact-attestation-policy-json",
@@ -2388,6 +2513,7 @@
         "publication-commit-evidence-path",
         "publication-consumer-predicate-id",
         "publication-consumer-qualification-command",
+        "publication-consumer-qualification-controller-sha",
         "publication-control-plane-audit-json",
         "publication-expected-json",
         "publication-gate-aggregate-json",
@@ -2456,7 +2582,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 99,
+      "inputCount": 101,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -2505,9 +2631,14 @@
         "release-candidate-artifact",
         "release-candidate-recovery-receipt-artifact",
         "release-candidate-recovery-root",
-        "release-propagation-work-artifact"
-      ],
-      "outputCount": 35,
+        "release-propagation-work-artifact",
+        "release-tail-declaration-root",
+        "release-tail-receipt-roots-json",
+        "release-tail-state-root",
+        "release-tail-transaction-root",
+        "release-tail-transaction-state"
+      ],
+      "outputCount": 40,
       "surface": "release-governance",
       "capabilityGroup": "reusable-build",
       "status": "active",
@@ -2647,6 +2778,42 @@
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
       "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
     },
+    {
+      "id": "release-tail",
+      "path": ".github/workflows/release-tail.yml",
+      "reusable": true,
+      "inputs": [
+        "buildchain-ref",
+        "capsule-contract",
+        "capsule-path",
+        "capsule-root",
+        "evidence-path",
+        "state-path"
+      ],
+      "inputCount": 6,
+      "secrets": [
+        "http-token"
+      ],
+      "secretCount": 1,
+      "outputs": [
+        "binding-root",
+        "evidence-root",
+        "state-root",
+        "transaction-root",
+        "transaction-state"
+      ],
+      "outputCount": 5,
+      "surface": "release-tail-provider-plane",
+      "capabilityGroup": "release-passport-trust",
+      "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": "release-verify",
       "path": ".github/workflows/release-verify.yml",
@@ -2856,6 +3023,7 @@
         "branch-protection-bypass-apps",
         "branch-protection-bypass-teams",
         "branch-protection-bypass-users",
+        "declarative-release-tail",
         "dry-run",
         "expected-publication-version",
         "generated-pull-request-token",
@@ -2865,6 +3033,7 @@
         "github-release-artifact-paths",
         "github-release-notes",
         "github-release-title",
+        "plan-before-target-advance",
         "promote-only-release-candidate",
         "publication-capability-json",
         "publication-gate-aggregate-json",
@@ -2879,6 +3048,7 @@
         "publish-package-set-order",
         "publish-rematerialize-on-resume",
         "publish-required-artifacts-json",
+        "publish-required-artifacts-path",
         "publish-sealed-bundle-manifest",
         "publish-sealed-bundle-root",
         "publish-source-locked",
@@ -2917,6 +3087,7 @@
         "release-passport-platform-manifest-paths",
         "release-passport-product-name",
         "release-passport-promotion-routing-json",
+        "release-tail-state-path",
         "require-governance",
         "require-publication-qualification",
         "require-publish-source-lock",
@@ -2929,7 +3100,30 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 76,
+      "inputCount": 80,
+      "capabilityGroup": "release-passport-trust",
+      "status": "active",
+      "owner": "buildchain-actions",
+      "maturity": "stable",
+      "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 action identity retained as the canonical composite or JavaScript action boundary."
+    },
+    {
+      "id": "release-tail",
+      "path": "actions/release-tail/action.yml",
+      "inputs": [
+        "capsule",
+        "capsule-contract",
+        "capsule-root",
+        "evidence-path",
+        "github-token",
+        "http-token",
+        "state-path"
+      ],
+      "inputCount": 7,
       "capabilityGroup": "release-passport-trust",
       "status": "active",
       "owner": "buildchain-actions",

package/docs/MAP.md

@@ -59,7 +59,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Capability group | Primary facts | Primary manuals |
 | --- | --- | --- |
 | Getting Started | `capability-registry.json`, `product-mechanism.json` | [`getting-started.md`](getting-started.md), [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |
-| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `publication-authority-registry.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`github-artifact-attestation.md`](github-artifact-attestation.md), [`publication-authority.md`](publication-authority.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |
+| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `publication-authority-registry.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`github-artifact-attestation.md`](github-artifact-attestation.md), [`publication-authority.md`](publication-authority.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`release-tail-contract.md`](release-tail-contract.md), [`publication-rehearsal.md`](publication-rehearsal.md), [`binary-distribution.md`](binary-distribution.md) |
 | Reusable Build and Lifecycle | `workflow-registry.json`, `controller-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`controller-evidence.md`](controller-evidence.md), [`shifu-gate-profiles.md`](shifu-gate-profiles.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
 | KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |
 | Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |
@@ -109,17 +109,21 @@ replace them.
 | How do I import Buildchain toolkit APIs from JavaScript build code? | [`node-api-reference.md`](node-api-reference.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |
 | How do I initialize a new repository? | [`getting-started.md`](getting-started.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |
+| What freezes the v4 dependency direction, writer authority, complexity budgets, exceptions, and N-1 qualification? | [`../architecture/v4-architecture-constitution.md`](../architecture/v4-architecture-constitution.md) | why/verify | preview |
 | How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |
 | How do slow required checks land reliably on a busy dev channel? | [`release-governance.md`](release-governance.md#protected-dev-branches) + [`cli.md`](cli.md#commands) | use | preview |
 | How does the durable fair Dev Delivery Warrant Queue prevent slow-candidate starvation?                                                       | [`dev-delivery-warrant.md`](dev-delivery-warrant.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | use/verify | preview |
 | How do I coalesce rapid Dev changes, preserve release runner priority, and retry only transient failed jobs? | [`dev-qualification-patrol.md`](dev-qualification-patrol.md) | use/verify | preview |
 | How do I run daily, weekly, or monthly repository patrols? | [`release-governance.md`](release-governance.md#buildchain-patrol) | use | stable |
+| How do I report or safely apply branch and pull-request engineering hygiene? | [`engineering-housekeeper.md`](engineering-housekeeper.md) | use/verify | preview |
 | How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |
 | What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |
 | What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |
 | What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |
 | How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
+| How are consumer-owned release-tail commands inventoried and replaced by declarative capabilities? | [`release-tail-contract.md`](release-tail-contract.md) | verify | draft |
+| How do I reproduce publication semantics locally without GitHub runner state? | [`publication-rehearsal.md`](publication-rehearsal.md), [`../architecture/decisions/0001-release-local-constructibility.md`](../architecture/decisions/0001-release-local-constructibility.md) | use/verify | preview |
 | How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
 | How do I keylessly attest Linux release artifacts with GitHub and bind them to a Release Passport? | [`github-artifact-attestation.md`](github-artifact-attestation.md) | verify/use | preview |
@@ -154,7 +158,7 @@ replace them.
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
 | How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |
 | How do I operate a repeatable, disabled-by-default, budget-fail-closed AWS Windows JIT campaign? | [`aws-us-elastic-runner-burst-plane.md`](aws-us-elastic-runner-burst-plane.md#phase-2-operator-workflow) | use/verify | preview |
-| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md), [`../actions/github-artifact-attestation/README.md`](../actions/github-artifact-attestation/README.md), [`../actions/macos-credential-island/README.md`](../actions/macos-credential-island/README.md); `dist/site/workflow-registry.json#actions` is authoritative for the six-entry inventory. | use | stable |
+| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md), [`../actions/github-artifact-attestation/README.md`](../actions/github-artifact-attestation/README.md), [`../actions/macos-credential-island/README.md`](../actions/macos-credential-island/README.md), [`../actions/release-tail/README.md`](../actions/release-tail/README.md); `dist/site/workflow-registry.json#actions` is authoritative for the seven-entry inventory. | use | stable |
 | How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |
 | What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md), [`../fixtures/publication-artifact-shaped/README.md`](../fixtures/publication-artifact-shaped/README.md) | verify | stable |
 | What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |

package/docs/auditable-demo.md

@@ -47,7 +47,7 @@ literal argv steps. Steps in one demo share a disposable workspace; separate
 demos and the two rendition captures do not. Commands are never accepted as a
 shell string. An omitted or explicit `standard` duration class remains bounded
 to 60 seconds. A reviewed `execution.durationClass: long-form` declaration may
-raise the scenario and literal step ceilings to 180 seconds; it does not change
+raise the scenario and literal step ceilings to 360 seconds; it does not change
 the default. Both classes retain 4 MiB per step, a clean Home/XDG environment,
 no inherited credentials, and a network-disabled read-only container with
 bounded tmpfs.
@@ -155,7 +155,7 @@ scene.json
 
 It may additionally emit one declared `terminal-capture.json` using
 `kungfu.terminal-capture/v1`. The optional capture is bounded to 60 seconds by
-default or 180 seconds only when its scene explicitly declares `long-form`,
+default or 360 seconds only when its scene explicitly declares `long-form`,
 fixed 80-200 by 24-80 terminal cells, 10,000 events, and 4 MiB of canonical
 base64 bytes. It must contain a qualified completion sentinel and an explicitly
 empty authority-grant list. Existing three-file adapters remain valid.

package/docs/cli-reference.md

@@ -22,6 +22,63 @@ ai_provenance:
 
 Every listed help command is intercepted before dispatch, exits zero, and performs no command side effects.
 
+## `architecture`
+
+### `buildchain architecture`
+
+- Help: `buildchain architecture --help`
+- Canonical id: `architecture`
+- Options: none declared
+- Syntax:
+
+```text
+buildchain architecture
+```
+
+### `buildchain architecture list`
+
+- Help: `buildchain architecture list --help`
+- Canonical id: `architecture`
+- Options: `--cwd`, `--json`
+- Syntax:
+
+```text
+buildchain architecture list [--cwd <dir>] [--json]
+```
+
+### `buildchain architecture qualify`
+
+- Help: `buildchain architecture qualify --help`
+- Canonical id: `architecture`
+- Options: `--authority-revision`, `--candidate-revision`, `--cwd`, `--json`
+- Syntax:
+
+```text
+buildchain architecture qualify --authority-revision <git-revision> [--candidate-revision <git-revision>] [--cwd <dir>] [--json]
+```
+
+### `buildchain architecture show`
+
+- Help: `buildchain architecture show --help`
+- Canonical id: `architecture`
+- Options: `--cwd`, `--json`
+- Syntax:
+
+```text
+buildchain architecture show <capability-id> [--cwd <dir>] [--json]
+```
+
+### `buildchain architecture validate`
+
+- Help: `buildchain architecture validate --help`
+- Canonical id: `architecture`
+- Options: `--cwd`, `--json`
+- Syntax:
+
+```text
+buildchain architecture validate [--cwd <dir>] [--json]
+```
+
 ## `audit`
 
 ### `buildchain audit`
@@ -1877,6 +1934,85 @@ buildchain release-propagation <plan|write-lock|work|entry|pickup> ...
 buildchain release-propagation <plan|write-lock|work|entry|pickup> ...
 ```
 
+## `release-tail`
+
+### `buildchain release-tail`
+
+- Help: `buildchain release-tail --help`
+- Canonical id: `release-tail`
+- Options: none declared
+- Syntax:
+
+```text
+buildchain release-tail
+```
+
+### `buildchain release-tail compat`
+
+- Help: `buildchain release-tail compat --help`
+- Canonical id: `release-tail`
+- Options: `--hooks-json`, `--output`
+- Syntax:
+
+```text
+buildchain release-tail compat --hooks-json <json-or-path> [--output <path>]
+```
+
+### `buildchain release-tail init`
+
+- Help: `buildchain release-tail init --help`
+- Canonical id: `release-tail`
+- Options: `--declaration`, `--state`
+- Syntax:
+
+```text
+buildchain release-tail init --declaration <json-or-path> [--state <path>]
+```
+
+### `buildchain release-tail plan`
+
+- Help: `buildchain release-tail plan --help`
+- Canonical id: `release-tail`
+- Options: `--declaration`, `--output`
+- Syntax:
+
+```text
+buildchain release-tail plan --declaration <json-or-path> [--output <path>]
+```
+
+### `buildchain release-tail rehearse`
+
+- Help: `buildchain release-tail rehearse --help`
+- Canonical id: `release-tail`
+- Options: `--capsule`, `--capsule-root`, `--environment-json`, `--evidence`, `--mode`, `--state`
+- Syntax:
+
+```text
+buildchain release-tail rehearse --capsule <path> --capsule-root <absolute-path> --mode <simulate|replay> --state <path> --evidence <path> [--environment-json <json-or-path>]
+```
+
+### `buildchain release-tail status`
+
+- Help: `buildchain release-tail status --help`
+- Canonical id: `release-tail`
+- Options: `--output`, `--state`
+- Syntax:
+
+```text
+buildchain release-tail <status|verify> [--state <path>] [--output <path>]
+```
+
+### `buildchain release-tail verify`
+
+- Help: `buildchain release-tail verify --help`
+- Canonical id: `release-tail`
+- Options: `--output`, `--state`
+- Syntax:
+
+```text
+buildchain release-tail <status|verify> [--state <path>] [--output <path>]
+```
+
 ## `sample`
 
 ### `buildchain sample`

package/docs/dev-delivery-warrant.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-08-05
+last_reviewed: 2026-08-09
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-08-04
+  generated_at: 2026-08-09
   invisible_context: not asserted
 ---
 
@@ -125,6 +125,39 @@ buildchain dev proof replay-proof \
 buildchain dev proof integration --warrant-result warrant.json ...
 ```
 
+## Bounded-concurrency shadow qualification
+
+The production queue remains single-flight. A separate effect-disabled shadow
+planner can replay the same deterministic candidate order with a bound of one
+or two lanes. It does not issue, renew, supersede, close, or persist a Warrant;
+it cannot enqueue a pull request; and its output explicitly carries no
+production or rollout authority.
+
+Each lane binds the exact queue root and generation, protected-base head,
+source head, projected-base root, Project Cut, approval, required checks,
+status, and lease evidence. An active production candidate must additionally
+match its current fencing token and lease generation. A queued shadow lane must
+not carry either. Stale evidence, an occupied native queue, cross-lane evidence
+aliasing, shared conflict keys, or an incompatible projected base fails closed.
+A failure in one lane remains visible without converting or concealing the
+other lane's result.
+
+The planner and aggregate qualification command consume immutable JSON files:
+
+```sh
+buildchain dev warrant shadow-plan --input observation.json \
+  --max-concurrency 2 --output shadow-plan.json
+
+buildchain dev warrant shadow-qualify --input qualification-input.json \
+  --output shadow-qualification.json
+```
+
+Both commands reject `--execute`. Qualification reports compare explicit
+thresholds for sample count, eligible overlap, projected queue-wait benefit,
+additional runner cost, ambiguity, and false positives. A `proceed` result is
+only evidence for a separate reviewed rollout decision; it never changes the
+live Warrant schema, queue state, merge-queue policy, or protected branch.
+
 ## Workflow rollout and rollback
 
 The reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:
@@ -133,7 +166,17 @@ The reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:
 - `shadow` qualifies the source and emits a read-only queue submission plan;
 - `required` persists the submission, selects the Warrant, and refuses GitHub
   enqueue unless the immutable queue commit, state root, active Warrant, and
-  selected candidate all pass exact readback validation.
+  selected candidate all pass exact readback validation. Immediately before
+  enqueue, the controller also rereads the current protected state ref and
+  verifies the active candidate, fencing token, generation, pull request, and
+  exact head. A previously valid result is not authority after terminal
+  closeout. Re-running qualification for the same selected head may regenerate
+  timestamped proof bytes, but it retains the immutable active Warrant and its
+  originally selected proof instead of rewriting or rejecting that attempt.
+  Each candidate also retains the exact successful source workflow run. If a
+  controller discovers that another candidate owns the active Warrant, a
+  configured consumer workflow is dispatched immediately for that exact PR,
+  head, and source run; the candidate is not left waiting for a patrol cron.
 
 Consumers should deploy `shadow` first, inspect receipts, then change their
 protected caller to `required`. Rollback is a reviewed caller change back to
@@ -143,7 +186,9 @@ merged candidate (or accepts explicit evidence for another terminal outcome),
 then closes only the current fencing generation. The separate queued
 cancellation reusable workflow cannot close an active generation; it advances
 the state ref only when the caller's complete terminal binding and expected-old
-root still match.
+root still match. A delayed `dequeued` event is ignored when GitHub readback
+shows the same exact PR head is already queued again, so an earlier queue event
+cannot close a newer active Warrant generation.
 
 Buildchain uses the same contract for its own protected dev line through
 `buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and