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

package/docs/aws-us-elastic-runner-burst-plane.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-08-02
+last_reviewed: 2026-08-03
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-08-01
+  generated_at: 2026-08-03
   invisible_information: No hidden model checkpoint, parameters, or private training data were available.
 ---
 
@@ -189,7 +189,7 @@ and atomically refuses a sixth accepted instance. Five accepted instances
 therefore reserve at most USD 21.75. The campaign also persists the
 operator-observed spend from earlier Windows work, and refuses to arm unless
 that baseline, all five reservations, and one USD 4.35 fail-closed race
-allowance remain below the USD 80 phase cap.
+allowance remain below the USD 110 phase cap.
 
 The campaign starts unarmed and expires within 24 hours. Its `CONTROL` record
 can be created only once: a killed or expired campaign cannot be re-armed by
@@ -199,16 +199,38 @@ paid launch. Reservations are never refunded: a controller crash, ambiguous
 launch, or successful launch all remain charged to the campaign, favoring a
 false stop over an accidental budget overrun.
 
+The 2026-08-03 timeout-only campaign decision narrows the campaign to two
+accepted instances with one active instance at a time. The second reservation
+is an operator-gated repair retry: it may be used only after the first attempt
+is classified as non-counting and runner, EC2, EBS, SSM, and workflow residue
+have returned to zero. The two-slot ledger is a maximum spend boundary, not an
+authorization to consume both reservations.
+
 Each stack owns a stack-scoped reaper log group, so an independent retained
 one-shot campaign stack can be created without colliding with another
 campaign's audit log resource.
 
-The tag-filtered AWS Budget is defense in depth, not the authoritative launch
-gate. It is disabled by default because a linked account cannot activate a
-cost-allocation tag. Set `EnableTagFilteredBudget=true` only after the AWS
-Organizations management account has activated `kungfu:provider` and a Cost
-Explorer readback proves that `windows-ec2-jit` spend is visible. The DynamoDB
-reservation cap remains mandatory in either mode.
+The account-native AWS Budget is defense in depth, not the authoritative launch
+gate. It is owned by the singleton
+`kungfu-buildchain-windows-jit-budget-guard` stack rather than any retained
+campaign stack. This prevents Budget-name collisions and prevents a stale
+campaign reaper from becoming the provider-wide cost authority. The Budget
+filters exactly `USAGE_TYPE=BoxUsage:c7i.4xlarge`,
+`OPERATION=RunInstances:0002` (Windows), and `REGION=us-east-1`; its 80% and
+95% actual notifications persist the provider kill sentinel, terminate every
+tagged Windows JIT instance, and delete scoped JIT parameters. Every launch
+controller refuses to proceed when the sentinel exists or when the Budget
+identity or dimension filter does not match.
+
+Budget installation is intentionally deployable by the workload account without
+AWS Organizations management-account access. It fails closed unless Cost
+Explorer exposes all three AWS-owned billing dimensions in the requested phase
+window. The `kungfu:provider=windows-ec2-jit` resource tag remains mandatory for
+ownership, cleanup, and IAM scoping, but it is not a billing filter. Do not
+create an unfiltered fallback Budget or treat an incomplete dimension readback
+as evidence.
+The DynamoDB campaign reservation remains the atomic launch authority because
+Cost Explorer and AWS Budgets can lag provider activity.
 
 Qualification requires one runner-profile smoke and three trusted exact-source
 full Windows jobs all bound to the same campaign, independent cancellation and
@@ -216,82 +238,94 @@ timeout cleanup exercises, and zero repository runner, EC2 instance,
 disposable volume, min capacity, and desired capacity within 15 minutes of the
 final job.
 
-### Phase 2 campaign controller
-
-`scripts/aws-windows-jit-campaign.mjs` is the one-shot operator boundary.
-Without a mutation mode it emits the arm plan. `arm-campaign` requires the
-campaign id, exact source SHA, state table, observed prior phase spend, and a
-bounded one-to-five accepted-instance ceiling to be repeated as confirmations,
-then creates `CONTROL` and `CAMPAIGN#<id>` with
-`attribute_not_exists`
-conditions. DynamoDB therefore refuses a second campaign in the same retained
-state table. The operator can always use `kill-campaign`; there is deliberately
-no clear or re-arm operation.
-
-Every `scripts/aws-windows-jit-controller.mjs --execute` call must provide the
-same `--campaign-id`, `--confirm-campaign-id`, `--state-table`, and
-`--confirm-state-table`. After the GitHub, AMI, active-instance, SSM, and EC2
-DryRun checks pass, the controller
-atomically reserves one run. Duplicate run-attempt-qualification identities,
-source mismatch, expiry, `KILLED`, the sixth accepted instance, or a
-reservation that would exceed the baseline-adjusted USD 80 phase ceiling all
-fail closed before `RunInstances`.
-
-Example dry-run and arm boundary (do not execute without a new campaign budget
-decision):
+### Phase 2 operator workflow
+
+`pnpm operator:windows-jit` is the reusable lifecycle entrypoint. Its default
+mode is `plan`, which performs no AWS or GitHub call. A plan binds the account,
+region, unique campaign and stack names, source SHA/ref, Cost Explorer window,
+workflow id, network, OIDC provider, expiry, slot ceiling, singleton Budget
+identity, and exact confirmation digest.
+
+The modes are deliberately separated:
+
+- `plan` emits the deterministic mutation boundary and digest.
+- `audit` reads AWS and GitHub only. It verifies the account, disabled workflow,
+  singleton guard stack, exact Budget filter, SNS thresholds/subscribers,
+  provider kill sentinel, campaign stack, and zero EC2/EBS/SSM/JIT/runner
+  residue.
+- `install-budget --execute` deploys or updates only the singleton Budget guard.
+  It refuses to mutate unless all exact Windows billing dimensions are visible,
+  the Windows workflow is disabled, and the account, campaign, source, Budget,
+  and plan digest confirmations match.
+- `prepare --execute` requires the installed Budget guard, absent kill
+  sentinel, fresh Cost Explorer readback filtered by `BoxUsage:c7i.4xlarge`,
+  `RunInstances:0002`, and `us-east-1`, zero residue, a
+  never-used campaign stack name, and the disabled workflow. The receipt binds
+  the query timestamp and exact filter identity. Preparation deploys the
+  campaign stack and atomically arms the ledger with that provider-spend
+  baseline. It never enables or dispatches the workflow and never creates EC2
+  capacity.
+- `close --execute` disables the workflow first, persists `KILLED`, publishes
+  the campaign kill switch, and reports terminal success only after EC2, EBS,
+  SSM, JIT parameter, and GitHub runner residue is zero. It is safe to rerun
+  while the reaper settles.
+
+All mutating modes require `--execute`, `--confirm-plan-digest`,
+`--confirm-account-id`, `--confirm-campaign-id`, and
+`--confirm-source-sha`. Budget installation and preparation additionally
+require `--confirm-budget-name`. A future paid workload still requires a
+separate exact workflow/run authorization and uses
+`scripts/aws-windows-jit-controller.mjs`; preparation is not paid-launch
+authority.
+
+Start by recording one reproducible plan:
 
 ```bash
-windows_campaign=win-REPLACE_WITH_CAMPAIGN_ID
-windows_source=REPLACE_WITH_EXACT_40_CHARACTER_SHA
-windows_state_table=REPLACE_WITH_CAMPAIGN_STATE_TABLE
-windows_expires_at=REPLACE_WITH_ISO_TIMESTAMP_WITHIN_24_HOURS
-windows_phase_spend_baseline_usd=REPLACE_WITH_OBSERVED_PRIOR_WINDOWS_SPEND
-windows_max_accepted_instances=REPLACE_WITH_INTEGER_FROM_1_THROUGH_5
-
-node scripts/aws-windows-jit-campaign.mjs plan-arm \
-  --campaign-id "$windows_campaign" \
-  --source-sha "$windows_source" \
-  --state-table "$windows_state_table" \
-  --expires-at "$windows_expires_at" \
-  --phase-spend-baseline-usd "$windows_phase_spend_baseline_usd" \
-  --max-accepted-instances "$windows_max_accepted_instances"
-
-node scripts/aws-windows-jit-campaign.mjs arm-campaign \
-  --campaign-id "$windows_campaign" \
-  --confirm-campaign-id "$windows_campaign" \
-  --source-sha "$windows_source" \
-  --confirm-source-sha "$windows_source" \
-  --state-table "$windows_state_table" \
-  --confirm-state-table "$windows_state_table" \
-  --expires-at "$windows_expires_at" \
-  --phase-spend-baseline-usd "$windows_phase_spend_baseline_usd" \
-  --confirm-phase-spend-baseline-usd "$windows_phase_spend_baseline_usd" \
-  --max-accepted-instances "$windows_max_accepted_instances" \
-  --confirm-max-accepted-instances "$windows_max_accepted_instances"
+pnpm operator:windows-jit plan \
+  --aws-profile us \
+  --account-id 727884401362 \
+  --campaign-id win-REPLACE \
+  --source-sha REPLACE_WITH_EXACT_40_CHARACTER_SHA \
+  --source-ref refs/heads/dev/v4/v4.0 \
+  --observed-at REPLACE_WITH_ISO_TIMESTAMP \
+  --expires-at REPLACE_WITH_ISO_TIMESTAMP_WITHIN_24_HOURS \
+  --cost-start REPLACE_WITH_PHASE_START_DATE \
+  --cost-end REPLACE_WITH_EXCLUSIVE_END_DATE \
+  --max-accepted-instances 1 \
+  --workflow-id 322620360 \
+  --vpc-id REPLACE_WITH_VPC_ID \
+  --subnet-id REPLACE_WITH_SUBNET_ID \
+  --oidc-provider-arn REPLACE_WITH_GITHUB_OIDC_PROVIDER_ARN
 ```
 
-Arming creates a permanent one-shot control record and admits only the
-explicitly confirmed number of paid instances, never more than five. Its
-rollback is fail-closed, not deletion: `kill-campaign` first
-persists `KILLED`, then publishes to the dedicated SNS topic so the reaper
-terminates active card-owned instances and removes their JIT parameters. The
-command is idempotent, but the operator must read back DynamoDB, EC2, SSM, and
-GitHub runners before treating cleanup as complete:
+Reuse those exact arguments for `audit`, `install-budget`, `prepare`, or
+`close`; never regenerate `--observed-at` between the plan and its confirmed
+mutation. Capture stdout as the operator receipt. Do not put credentials,
+tokens, JIT configuration, or signed URLs in arguments or receipts.
 
-```bash
-windows_kill_topic=REPLACE_WITH_DEDICATED_KILL_SWITCH_TOPIC_ARN
-
-node scripts/aws-windows-jit-campaign.mjs kill-campaign \
-  --campaign-id "$windows_campaign" \
-  --confirm-campaign-id "$windows_campaign" \
-  --source-sha "$windows_source" \
-  --confirm-source-sha "$windows_source" \
-  --state-table "$windows_state_table" \
-  --confirm-state-table "$windows_state_table" \
-  --kill-switch-topic "$windows_kill_topic" \
-  --confirm-kill-switch-topic "$windows_kill_topic" \
-  --reason operator-kill
-```
+### Lower-level campaign and launch controllers
+
+`scripts/aws-windows-jit-campaign-core.mjs` owns the pure one-shot ledger
+contract used by the operator and launch controller. Arming creates `CONTROL`
+and `CAMPAIGN#<id>` with `attribute_not_exists` conditions, so DynamoDB refuses
+a second campaign in the same retained state table. There is deliberately no
+clear or re-arm operation.
+
+Every `scripts/aws-windows-jit-controller.mjs --execute` call must provide the
+same `--account-id`, `--campaign-id`, `--confirm-campaign-id`, `--state-table`,
+and `--confirm-state-table`. Before GitHub JIT material is created, the
+controller verifies the exact provider Budget/dimension filter and proves the
+global Budget kill sentinel absent. After the GitHub, AMI, active-instance,
+SSM, and EC2 DryRun checks pass, the controller
+atomically reserves one run. Duplicate run-attempt-qualification identities,
+source mismatch, expiry, `KILLED`, the sixth accepted instance, or a
+reservation that would exceed the USD 110 ceiling after combining the persisted
+fresh Cost Explorer baseline with all in-flight campaign reservations all fail
+closed in one DynamoDB transaction before `RunInstances`. AWS Budget alarms are
+defense in depth for delayed billing telemetry; the atomic ledger is the
+authoritative launch-time guard. The operator is the only supported mutation
+surface for campaign preparation and closeout; direct imports of the core are
+not operator authority.
 
 ## Phase 3 contract
 

package/docs/cli-reference.md

@@ -223,6 +223,160 @@ buildchain dev
 buildchain dev merge-queue --repository <owner/repo> --branch <dev/vN/vN.M> [--from-config | --workflow <required-workflow.yml>...] [--cwd <dir>] [--check-response-timeout-minutes <n>] [--max-entries-to-build <n>] [--apply]
 ```
 
+### `buildchain dev pr-admit`
+
+- Help: `buildchain dev pr-admit --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--expected-head`, `--json`, `--output`, `--pull-request`, `--repository`
+- Syntax:
+
+```text
+buildchain dev pr-admit --repository <owner/repo> --branch <dev/vN/vN.M> --pull-request <n> --expected-head <sha> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev proof classify`
+
+- Help: `buildchain dev proof classify --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof integration`
+
+- Help: `buildchain dev proof integration --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof replay`
+
+- Help: `buildchain dev proof replay --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof source`
+
+- Help: `buildchain dev proof source --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof verify-integration`
+
+- Help: `buildchain dev proof verify-integration --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof verify-source`
+
+- Help: `buildchain dev proof verify-source --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev warrant cancel-queued`
+
+- Help: `buildchain dev warrant cancel-queued --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant close`
+
+- Help: `buildchain dev warrant close --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant heartbeat`
+
+- Help: `buildchain dev warrant heartbeat --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant observe`
+
+- Help: `buildchain dev warrant observe --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant recover`
+
+- Help: `buildchain dev warrant recover --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant select`
+
+- Help: `buildchain dev warrant select --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant submit`
+
+- Help: `buildchain dev warrant submit --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
 ## `diagnostics`
 
 ### `buildchain diagnostics`

package/docs/dev-alpha-candidate-patrol.md

@@ -8,12 +8,12 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-03
+last_reviewed: 2026-08-04
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-29
-  visible_context: Existing Buildchain source locks, Kungfu exact-source Alpha preflight, Dev Patrol, protected auto-merge policy, repository release governance, and the consumer-owned settlement renderer threat model.
+  generated_at: 2026-08-04
+  visible_context: Existing Buildchain source locks, Kungfu exact-source Alpha preflight, Dev Patrol, cancelled duplicate runs, protected auto-merge policy, repository release governance, and the consumer-owned settlement renderer threat model.
   invisible_context_boundary: No credentials, private logs, or private configuration were used.
 ---
 
@@ -27,8 +27,10 @@ bounded development history from newest to oldest (stopping early at the Alpha
 head), and selects the newest commit that satisfies all of these conditions:
 
 - the source is strictly ahead of the recorded target head;
-- the latest completed Dev Patrol for that exact commit SHA succeeded;
-- the latest completed Alpha preflight for the same commit SHA succeeded; and
+- the latest completed, non-cancelled Dev Patrol for that exact commit SHA
+  succeeded;
+- the latest completed, non-cancelled Alpha preflight for the same commit SHA
+  succeeded; and
 - both runs are within the caller's evidence age limit.
 
 The selected commit can be behind the observed development head when newer
@@ -37,6 +39,12 @@ head, selected SHA, and count of skipped newer commits. This makes a slow native
 verification lane live under continuous development without silently treating
 an unqualified head as releasable.
 
+A cancelled workflow run carries no qualification verdict, so a newer
+cancelled duplicate does not erase the prior completed verdict for the same
+workflow and source SHA. Other non-success conclusions remain authoritative:
+a newer failed, timed-out, skipped, or otherwise non-successful completed run
+still excludes that SHA and forces the controller to fall back or fail closed.
+
 History discovery is bounded to the newest 1000 development commits. The
 controller then compares the selected SHA to the exact Alpha head before it can
 be eligible, so a bounded scan cannot turn a commit outside the promotion

package/docs/dev-delivery-warrant.md

@@ -0,0 +1,158 @@
+---
+status: draft
+period: ongoing
+theme: dev-delivery-warrant
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-05
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-04
+  invisible_context: not asserted
+---
+
+# Dev Delivery Warrant Queue
+
+Buildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a
+durable, non-preemptive delivery turn without replacing GitHub Merge Queue as
+the final protected-ref authority.
+
+The queue is stored on a dedicated Git ref below
+`buildchain/dev-delivery-warrant/`. Every update creates a child Git commit and
+advances the ref without force. The transition receipt binds the expected old
+state root; a competing controller receives a visible non-fast-forward failure
+instead of a second authority claim.
+
+## Contract
+
+A submission binds the repository, protected dev line, pull request, semantic
+source identity, exact source head, native Assignment and Initiative roots,
+source patch or tree intent, reusable Source Qualification Proof, plan,
+affected closure, dependencies, toolchain, delivery class, priority, attempts,
+and retained enqueue time.
+
+Selection is deterministic FIFO plus aging with bounded priority. Priority may
+reorder queued work, but it cannot preempt the active Warrant. Exactly one
+candidate receives a leased Warrant containing a fencing token, lease
+generation, expected-old state root, expiry, and the complete exact source
+binding. Heartbeat extends only that generation. Expiry recovery rejects the
+old token, retains queue age, and returns the candidate to selection.
+
+A terminal event may cancel a candidate before selection without minting a
+Warrant. This transition is limited to an exact non-active queued candidate and
+binds its candidate root, pull request, recorded source head, event-observed
+source head, terminal event action, evidence root, and expected-old queue root.
+An active candidate still requires its current fencing token and lease
+generation. Exact duplicate cancellation evidence is a visible no-op; identity,
+state, event, or evidence drift fails closed.
+
+The reusable terminal controller uses one `settle` operation for active,
+queued, already-terminal, and never-admitted pull requests. An active Warrant
+still requires its exact fence and evidence. A matching queued cancellation is
+persisted normally. A duplicate terminal event or a pull request that never
+entered Warrant authority returns a rooted explicit no-op instead of failing
+the workflow or inventing queue state.
+
+The supported priority classes are `ordinary`, `expedited`, and `emergency`.
+The queue does not infer an emergency: callers must choose it explicitly under
+their reviewed policy. Delivery classes are `non-native-fast`,
+`native-proof-required`, `cross-platform`, and `release`.
+
+## Split proof authority
+
+Source Qualification Proof is independent of the moving dev base. It binds the
+semantic source, exact source head and patch/tree intent, plan, affected
+closure, dependencies, toolchain, covered paths, and shard evidence.
+
+Before reuse, the consumer classifies the dev delta:
+
+- unchanged roots plus an unrelated attributed delta reuse source
+  qualification and run only a cheap Project Cut replay. GitHub's `behind`
+  state is accepted only when a rooted replay proof binds the exact current
+  protected base, unchanged PR head and source patch, replay tree, required
+  context roots, and a qualified `project.cut.merge-queue-admission/v1`
+  receipt;
+- an overlapping delta reruns the affected source shards;
+- an unknown graph or changed source, plan, closure, dependency, or toolchain
+  root fails closed to full source qualification.
+
+Integration Delivery Proof is separate and cannot be cached across candidates.
+It binds the exact current dev base, replay tree, GitHub `merge_group` head and
+tree, active Warrant fencing generation, Source Qualification Proof root, and
+final required-context roots. GitHub's exact merge-group checks remain the
+final integration authority.
+
+## CLI
+
+Queue commands are dry-run by default:
+
+```sh
+buildchain dev warrant submit --repository owner/repository \
+  --branch dev/v4/v4.0 --pull-request 123 --source-head <sha> \
+  --assignment-root <root> --initiative-root <root> \
+  --source-identity-root <root> --source-patch-root <root> \
+  --source-proof-root <root> --plan-root <root> --closure-root <root> \
+  --dependency-root <root> --toolchain-root <root> \
+  --delivery-class native-proof-required
+
+buildchain dev warrant select --repository owner/repository \
+  --branch dev/v4/v4.0 --execute
+
+buildchain dev warrant cancel-queued --repository owner/repository \
+  --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \
+  --expected-source-head <queued-sha> --observed-source-head <event-sha> \
+  --expected-old <queue-root> --event-action closed --outcome cancelled \
+  --evidence-root <terminal-event-root> --execute
+```
+
+`heartbeat`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.
+Warrant-scoped mutations require the exact fencing token and lease generation.
+`close` also requires a rooted terminal evidence object.
+
+Proof commands create, verify, classify, and compose the two proof layers:
+
+```sh
+buildchain dev proof source ...
+buildchain dev proof classify --source-proof source-proof.json ...
+buildchain dev proof replay ...
+buildchain dev proof replay-proof \
+  --qualification-receipt project-cut-admission.json ...
+buildchain dev proof integration --warrant-result warrant.json ...
+```
+
+## Workflow rollout and rollback
+
+The reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:
+
+- `off` preserves the previous exact-head admission controller;
+- `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.
+
+Consumers should deploy `shadow` first, inspect receipts, then change their
+protected caller to `required`. Rollback is a reviewed caller change back to
+`off`; it does not delete queue history or reinterpret old receipts. The
+terminal reusable workflow creates the exact Integration Delivery Proof for a
+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.
+
+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
+all native/source proof roots, pins the runtime to the caller commit, selects
+`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not
+offer an `off` switch: rollback is a reviewed change to this caller, not an
+operator-time weakening of a specific delivery attempt.
+
+This mechanism schedules protected delivery only. It does not serialize local
+development, source-only checks, unrelated channels, release publication, or
+runner provisioning. It never grants authority to enable cloud runner
+campaigns.