@kungfu-tech/buildchain 3.0.9-alpha.1 → 3.0.9-alpha.11

package/docs/dev-delivery-qualification-landing-adr.md

@@ -0,0 +1,137 @@
+---
+status: accepted
+period: ongoing
+theme: dev-delivery-qualification-landing-authority
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-12
+---
+
+# ADR: Qualification Leases and the exclusive Landing Warrant
+
+## Decision
+
+Buildchain has two explicit protected-dev authority modes:
+
+1. `single-flight-warrant` is the default and continues to use the
+   `kungfu-buildchain-dev-delivery-warrant-queue` v1 state and
+   `buildchain dev warrant` commands unchanged.
+2. `bounded-qualification-landing` is opt-in and uses the
+   `kungfu-buildchain-dev-delivery-authority` v2 state. It may issue up to the
+   configured number of Qualification Leases, but it may issue exactly one
+   Landing Warrant.
+
+The modes use different contracts, state refs, and CLI command families. There
+is no implicit reinterpretation of a v1 Warrant. A consumer turns the new mode
+on only by explicitly migrating the exact current v1 state and deploying the
+v2 controller against the dedicated
+`buildchain/dev-delivery-authority/<dev-line>` state ref.
+
+Migration preserves the immutable v1 `stateRoot`, candidate identity, source
+and proof roots, fencing token, generation, and lease times in a rooted
+migration receipt. An active provisional Warrant becomes a
+qualification-only lease and remains unable to admit `merge_group`; an active
+qualified Warrant becomes the one exclusive Landing Warrant. The migration is
+one-shot: a v2 state is never accepted as v1 input, and source/evidence bytes
+are not regenerated. The legacy ref remains immutable rollback evidence.
+
+## Authority invariants
+
+A Qualification Lease carries:
+
+- `authority = qualification-only`;
+- `mergeGroupAdmission = false`;
+- one exact candidate id, token, generation, issue time, and expiry; and
+- a place in a list bounded by `policy.maxQualificationLeases`.
+
+It authorizes expensive qualification work only. It cannot authorize GitHub
+`merge_group`, cannot be upgraded in place to landing authority, and is removed
+when qualification evidence is recorded. Each new candidate declares a sorted
+set of rooted `qualificationDomains`. Candidates with disjoint sets may hold
+leases concurrently. An overlapping set is serialized; an empty set is treated
+as unknown and therefore conflicts with every active candidate. The scheduler
+returns a content-rooted reason for either refusal.
+
+The Landing Warrant carries:
+
+- `authority = merge-group-admission`;
+- `mergeGroupAdmission = true`;
+- one exact qualified candidate id, token, generation, issue time, and expiry;
+  and
+- the only non-null `landingWarrant` slot in the durable state.
+
+Only `admitDevDeliveryMergeGroup` and `buildchain dev authority
+admit-merge-group` consume Landing authority. They bind the exact current state
+root, candidate, protected base, source head, merge-group head, token, and
+generation. A Qualification Lease fails closed at this boundary.
+
+The state normalizer rejects a lease beyond the configured bound, duplicate
+Qualification Leases for one candidate, a candidate holding qualification and
+Landing authority together, a Landing Warrant without its exact landing
+candidate, and any state-root drift. Git expected-old, non-force ref advancement
+continues to serialize durable mutations. These checks retain the existing
+two-phase safety rule: source/native qualification is evidence, while the
+exclusive final authority is candidate- and integration-specific.
+
+## Bounded scheduler and recovery
+
+Landing selection is FIFO among candidates that have completed qualification.
+When a later candidate receives a Landing Warrant, each older nonterminal
+candidate consumes one durable overtake from its
+`policy.maxLandingOvertakes` budget. Once an older candidate reaches that
+bound, later candidates cannot receive a Warrant. The older candidate receives
+the next landing priority after qualification, or reaches a rooted terminal
+failure after `policy.maxQualificationAttempts` heartbeat expiries. This makes
+the bound independent of controller restart frequency or later arrival rate;
+setting it to zero enforces strict FIFO landing priority.
+
+Qualification Leases and Landing Warrants both support fenced heartbeats. A
+missed heartbeat is recovered at expiry; recovery releases capacity and emits
+a deterministic content-rooted wake instruction for the next domain-eligible
+qualification candidates and the next fair landing candidate. Completion,
+cancellation, terminal failure, dequeue, and already-merged settlement emit the
+same wake shape. Exact duplicate heartbeats, recovery, and terminal events are
+state-root-preserving no-ops. Competing controllers still commit through one
+expected-old, non-force ref update, so only one transition can become durable.
+
+## Terminal settlement
+
+Terminal provider evidence is authoritative cleanup input. A matching merged,
+failed, dequeued, or cancelled candidate releases its Qualification Lease or
+Landing Warrant in the same expected-old state transition, even when the lease
+TTL has not expired. An active authority requires its exact token and
+generation for that transition. Repeating the same outcome and evidence is a
+root-preserving no-op; outcome or evidence drift fails closed. A terminal event
+for a candidate that never entered the state is also an explicit no-op.
+
+TTL recovery remains crash recovery, not the normal terminal cleanup path.
+
+## Public contract
+
+- Machine schema:
+  [`contracts/dev-delivery-authority-v2.schema.json`](../contracts/dev-delivery-authority-v2.schema.json),
+  packaged as `dist/site/schemas/dev-delivery-authority-v2.schema.json`.
+- Node API: `@kungfu-tech/buildchain/dev-delivery-authority` exports the v2
+  state, migration, lease, heartbeat, recovery, Landing, admission,
+  observation, and settlement functions. `@kungfu-tech/buildchain/dev-delivery-warrant`
+  remains byte- and behavior-compatible for v1 consumers.
+- CLI: `buildchain dev authority
+<migrate|submit|lease-qualification|heartbeat-qualification|complete-qualification|lease-landing|heartbeat-landing|recover|admit-merge-group|settle|observe>`.
+- Generated references: [`cli-reference.md`](cli-reference.md) and
+  [`node-api-reference.md`](node-api-reference.md).
+
+All mutations are plan-only unless `--execute` is supplied. Merge-group
+admission is always a read-only authority check; it never mutates GitHub Merge
+Queue itself.
+
+## Consequences
+
+Qualification throughput can increase without increasing the number of
+candidates permitted to land. Consumers retain the byte- and behavior-compatible
+single-flight default until they deliberately deploy the v2 mode. The tradeoff
+is a second state contract and controller family; Buildchain keeps that
+separation explicit so a rollout cannot silently weaken Warrant semantics.

package/docs/dev-delivery-warrant.md

@@ -1,5 +1,5 @@
 ---
-status: draft
+status: accepted
 period: ongoing
 theme: dev-delivery-warrant
 doc_type: technical-reference
@@ -7,7 +7,7 @@ source_level: local-files
 confidence: high
 sensitivity: public
 evidence_grade: A
-review_state: unreviewed
+review_state: self-reviewed
 last_reviewed: 2026-08-11
 ai_provenance:
   model_family: GPT-5
@@ -38,10 +38,17 @@ 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.
+candidate receives a `provisional` leased Warrant containing a fencing token,
+lease generation, expected-old state root, expiry, and the complete exact
+source binding. It reserves the next protected-dev landing before expensive
+native shards start, but it is not GitHub Merge Queue admission authority.
+Heartbeat extends only that generation. Native proof success atomically
+upgrades the same token and generation to `qualified`; only then may enqueue
+begin. Expiry fences further mutations by the old token, but it does not prove
+that the old native process stopped. The active Warrant therefore remains in
+place until bounded termination is proven by rooted terminal evidence. Only
+that exact fenced settlement may clear the holder and permit successor
+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
@@ -51,7 +58,12 @@ 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,
+The reusable terminal controller classifies authoritative completion,
+cancellation, supersession, native failure, and transient dequeue separately.
+`dequeued` alone never clears an active Warrant: a fresh holder continues with
+the same generation and token, while an expired holder waits for proof that its
+fenced worker stopped. Queued work may still settle as dequeued because it never
+started native execution. The 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
@@ -73,23 +85,37 @@ That lane outranks not-yet-leased ordinary work, but never preempts or rewrites
 an active Warrant; unrelated, conflicted, mismatched, or fabricated claims fail
 closed before selection.
 
-## Split proof authority
+## Three proof authorities
 
-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.
+Source Qualification Proof is created from the cheap source-acceptance gate. It
+binds the semantic source, exact source head and patch/tree intent, plan,
+affected closure, dependencies, toolchain, covered paths, and exact acceptance
+evidence. Ready state and approval are established before provisional
+selection.
 
-Before reuse, the consumer classifies the dev delta:
+Native Qualification Proof is separate. It binds semantic source and patch,
+plan, affected closure, dependency graph, toolchain, the exact execution
+environment contract, covered paths, native shard evidence, and the exact dev
+base used by the native composition. Before reuse, the consumer roots the
+complete attributed Dev delta, including both sides of every rename, then
+classifies it:
 
-- unchanged roots plus an unrelated attributed delta reuse source
-  qualification and run only a cheap Project Cut replay. GitHub's `behind`
+- unchanged semantic roots plus an unrelated fully attributed base delta reuse
+  native 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.
+- an overlapping delta reruns affected native shards or the full native plan;
+- an unknown or truncated graph, ambiguous rename, missing attribution, or
+  changed source, plan, closure, dependency, toolchain, or environment root
+  fails closed to full native qualification.
+
+The reuse decision binds the exact old and current Dev heads, normalized changed
+paths and rename pairs in `baseDeltaRoot`. This makes local and hosted replay of
+the same inputs byte-deterministic. Generated outputs that participate in the
+affected closure must be listed in `affected-paths-json`; a delta touching one
+of those surfaces is overlap, not a documentation-only advance.
 
 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
@@ -113,6 +139,19 @@ buildchain dev warrant submit --repository owner/repository \
 buildchain dev warrant select --repository owner/repository \
   --branch dev/v4/v4.0 --execute
 
+buildchain dev proof native --branch dev/v4/v4.0 \
+  --qualified-base <sha> --environment-root <root> \
+  --affected-paths-json '["packages/native"]' ...
+
+buildchain dev proof classify-native --source-proof native-proof.json \
+  --current-base <sha> --graph-known true --attribution-complete true \
+  --changed-paths-json '[]' --renames-json '[]' ...
+
+buildchain dev warrant qualify --repository owner/repository \
+  --branch dev/v4/v4.0 --fencing-token <root> --lease-generation 1 \
+  --native-proof native-proof.json \
+  --native-reuse-decision native-reuse-decision.json --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> \
@@ -120,10 +159,17 @@ buildchain dev warrant cancel-queued --repository owner/repository \
   --evidence-root <terminal-event-root> --execute
 ```
 
-`heartbeat`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.
+`heartbeat`, `qualify`, `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.
 
+Expensive native commands must run through `dev-delivery-native-run.mjs` (or an
+equivalent exact consumer). It performs an exact fenced heartbeat before spawn,
+renews throughout the complete child lifetime, performs a final renewal before
+accepting success, and terminates the process group on heartbeat or fencing
+failure. Missing, stale, expired, or mismatched Warrant state therefore blocks
+native spawn instead of becoming qualification evidence.
+
 Proof commands create, verify, classify, and compose the two proof layers:
 
 ```sh
@@ -137,7 +183,7 @@ buildchain dev proof integration --warrant-result warrant.json ...
 
 ## Bounded-concurrency shadow qualification
 
-The production queue remains single-flight. A separate effect-disabled shadow
+The default 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
@@ -168,14 +214,71 @@ 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.
 
+## Opt-in bounded qualification and exclusive landing
+
+Buildchain also defines an explicit production opt-in that turns successful
+shadow evidence into a separate v2 authority state. It does not widen or
+reinterpret the v1 Warrant queue. The accepted
+[`Qualification Lease and Landing Warrant ADR`](dev-delivery-qualification-landing-adr.md)
+and `contracts/dev-delivery-authority-v2.schema.json` are authoritative.
+
+In `bounded-qualification-landing` mode, a configured number of exact
+Qualification Leases may coexist. Each lease carries
+`authority = qualification-only` and `mergeGroupAdmission = false`. Completing
+qualification records evidence and releases that lease. Qualified candidates
+then wait for the one `Landing Warrant`, which alone carries
+`authority = merge-group-admission` and may be checked for `merge_group`
+admission.
+
+Concurrency is granted only across disjoint rooted `qualificationDomains`.
+Overlap and unknown domains are held behind the active safety boundary with an
+explicit content-rooted reason. `maxLandingOvertakes` prevents a slow older
+candidate from being bypassed indefinitely, while `maxQualificationAttempts`
+turns repeated heartbeat loss into a rooted terminal failure. Every release
+returns a deterministic rooted wake instruction; an exact duplicate release or
+recovery is a state-root-preserving no-op.
+
+The public command family is explicit:
+
+```sh
+buildchain dev authority migrate --repository owner/repository \
+  --branch dev/v3/v3.0 --legacy-state v1-queue.json --execute --json
+buildchain dev authority lease-qualification --repository owner/repository \
+  --branch dev/v4/v4.0 --execute
+buildchain dev authority heartbeat-qualification --repository owner/repository \
+  --branch dev/v4/v4.0 --candidate-id <root> \
+  --authority-token <root> --authority-generation 1 --execute
+buildchain dev authority complete-qualification --repository owner/repository \
+  --branch dev/v4/v4.0 --candidate-id <root> \
+  --authority-token <root> --authority-generation 1 \
+  --evidence-root <qualification-root> --execute
+buildchain dev authority lease-landing --repository owner/repository \
+  --branch dev/v4/v4.0 --execute
+buildchain dev authority heartbeat-landing --repository owner/repository \
+  --branch dev/v4/v4.0 --candidate-id <root> \
+  --authority-token <root> --authority-generation 1 --execute
+buildchain dev authority recover --repository owner/repository \
+  --branch dev/v4/v4.0 --execute
+buildchain dev authority admit-merge-group --repository owner/repository \
+  --branch dev/v4/v4.0 --candidate-id <root> \
+  --authority-token <root> --authority-generation 1 \
+  --merge-group-head <sha>
+```
+
+Terminal settlement releases either authority immediately from exact evidence;
+it does not wait for TTL. Exact duplicate settlement is a state-root-preserving
+no-op. The default `buildchain dev warrant` commands, v1 state bytes, and
+single-flight behavior do not change while this mode is off.
+
 ## 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
+- `required` persists the submission, selects a provisional Warrant, runs or
+  reuses semantic native proof under heartbeat, atomically qualifies the same
+  fence, and refuses GitHub enqueue unless the immutable queue commit, state root, active Warrant, and
   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
@@ -188,6 +291,25 @@ The reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:
   configured consumer workflow is dispatched immediately for that exact PR,
   head, and source run; the candidate is not left waiting for a patrol cron.
 
+The controller persists a completed native proof before its final base
+reclassification. A later exact retry can supply that proof and avoid the
+expensive native command when the rooted delta still proves reuse safe. A
+duplicate dispatch against the same already-qualified Warrant returns the same
+proof and reuse roots without another queue mutation. Both result forms carry
+`landingAuthority: false`: only the live qualified Warrant plus exact-head
+GitHub merge-queue admission can authorize landing.
+
+The required controller checks the protected base again after native work. A
+disjoint attributed delta reuses the proof. Overlap or unknown attribution
+triggers one automatic revalidation on the latest base; continued overlap,
+native failure, cancellation, semantic head movement, or an unrecoverable merge
+conflict closes the exact fence. The next queued candidate is notified through
+the `buildchain-dev-delivery-wake` repository event. Its complete semantic
+candidate is carried under the single `client_payload.candidate` envelope so
+GitHub's ten-property top-level limit cannot discard proof bindings. If
+cancellation prevents cleanup, lease expiry recovers retained queue age and
+mints a new fence.
+
 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
@@ -202,11 +324,16 @@ 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
-all native/source proof roots, pins the runtime to the caller commit, selects
+semantic source roots, accepts an optional reusable native proof, 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.
 
+`buildchain init --type native` generates the corresponding protected-dev
+consumer workflow. It supports both explicit dispatch and the bounded wake
+event, uses the same reusable controller, and keeps the native command in the
+consumer repository rather than inventing provider-specific shards.
+
 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

package/docs/kfd-support.md

@@ -77,8 +77,13 @@ KFD records and evidence by SHA-256. The result uses
 `buildchain kfd support project` derives a compatibility projection from the
 standard adopter manifest and its exact passing gate. The adopter manifest is
 the sole KFD-1..13 declaration authority; the command rejects stale package,
-source, witness, registry, verifier-set, and KFD-4/5/7 gate roots. The emitted
-matrix is not an independent declaration and cannot widen adopter claims.
+source, witness, registry, verifier-set, and KFD-4/5/7 gate roots. Gate creation
+accepts an explicit `expectedAdopterId`, `expectedSourceRepository`, and
+`expectedSourceSha`; omitting the first two preserves the Buildchain
+self-release default. The gate, every product-gate projection, the legacy
+matrix, Release Passport, and artifact evidence all retain that exact
+adopter/repository/source closure. The emitted matrix is not an independent
+declaration and cannot widen adopter claims.
 
 ## KFD-1
 

package/docs/next-development-transition.md

@@ -0,0 +1,119 @@
+---
+status: preview
+period: ongoing
+theme: next-development-transition
+doc_type: generated-contract-guidance
+source_level: generated-from-node-contract
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-11
+---
+
+# Next-development Transition
+
+This document is generated from
+`packages/core/next-development-transition.js` and
+`packages/core/next-development-controller.js` and
+`packages/core/next-development-projection.js`. Edit those sources and run
+`node scripts/generate-next-development-guidance.mjs`; direct edits fail the
+projection drift check.
+
+## Contract
+
+- Contract: `kungfu-buildchain-next-development-transition/v1`
+- Durable controller: `kungfu-buildchain-next-development-controller/v1`
+- ADR: [ADR 0002](../architecture/decisions/0002-next-development-transition.md)
+- States: `planned`, `waiting-anchor`, `materialized`, `pr-pending`, `merged`, `verified`
+- Legal version models: `semver/auto` and `anchored/manual`
+- Invariant: A completed Alpha remains successful and its refs remain immutable while the next-development transition is incomplete.
+
+An Alpha publication is terminal success independently of this transition.
+The idempotency key is a deterministic hash of the completed-Alpha root,
+repository, legal model, and sorted declared paths. Incomplete Dev preparation
+therefore cannot relabel Alpha N as failed, and replay cannot select a different
+Alpha or path set.
+
+## Durable controller
+
+`scheduleNextDevelopmentController` atomically creates one child for the
+repository and completed-Alpha root. Identical wakes reuse it. The store
+boundary requires read, create-if-absent, and compare-and-swap operations; the
+controller root fences every checkpoint. Materialization uses an operation key
+derived from the child, exact current protected Dev SHA, and reviewed target,
+so a fresh runner can recover an already-created commit instead of rebuilding
+the Alpha candidate or depending on the original runner workspace.
+
+Before opening the protected version PR, the controller reads Dev again. A
+moved head makes the prepared attempt `superseded`; the following wake
+regenerates only declared version material from that latest SHA. After merge,
+`verified` remains unreachable until protected Dev readback contains the
+prepared commit and its target version, source roots, and derived roots exactly
+match the checkpoint. The executor surface contains no Alpha publication, tag,
+release, or package operation.
+
+Alpha finalization no longer treats a non-fast-forward Dev update as successful
+bookkeeping. It requires an exact checkout of the current Dev head, regenerates
+the declared version lifecycle there, and uses a non-force merge or reusable
+protected version PR. Candidate Patrol ignores both the generated preparation
+commit and its two-parent integration commit. Before a later product candidate
+can settle, Patrol reads every prepared version path at the candidate SHA and
+requires the exact reserved blob identities; missing or stale state blocks
+before a Release Cut or heavy candidate build.
+
+## Version models
+
+`semver/auto` increments the Alpha sequence on the same semantic patch. For
+example, completed `1.4.2-alpha.7` plans `1.4.2-alpha.8`. It must not accept an anchor or an
+operator-selected target.
+
+`anchored/manual` enters `waiting-anchor` until the caller provides both a
+semantic target and the exact digest of the configured anchor manifest. The
+adapter verifies the manifest already present in the checkout; it never invents
+or edits upstream anchor facts. `semver/manual` and `anchored/auto` are
+invalid.
+
+## Hosted self-dogfood and adoption
+
+`.github/workflows/buildchain-alpha-self-dogfood.yml` calls the same public
+`build.yml@v3-alpha` router as a consumer. After the hosted build succeeds, one
+runner uses the real version-state adapter and checkpoints an injected transient
+durable-state write failure. A separate runner restores the adapter operation
+without rebuilding Alpha, supersedes it when protected Dev moves, and preserves
+`pr-pending` while the protected PR is delayed. The final artifact roots the
+exact runtime SHA, controller transaction, both legal version-model outcomes,
+and an exact hosted protected Dev readback. Stable qualification recomputes and
+rejects evidence that omits or drifts any of those bindings.
+
+Production consumers, including Kungfu, adopt the proved contract through
+`kungfu-systems/buildchain/.github/workflows/build.yml@v3`. The evidence retains
+the exact resolved SHA for audit, but the committed production coordinate is the
+floating major contract rather than an exact-SHA pin.
+
+## Local adapter
+
+From a normal Buildchain checkout:
+
+```sh
+node scripts/next-development-transition.mjs materialize --cwd . --input <request.json>
+```
+
+The command prints a rooted plan and performs no write by default. `--write`
+may change only regular, non-symlink source files listed by `version.files`
+in the loaded Buildchain config. The rooted adapter contract separately names
+`version.derived_files` as allowed changes, `version.manifest` as read-only,
+`BUILDCHAIN_VERSION` as the target input, `lifecycle.version-state` as the
+derived-material stage, and `lifecycle.verify` as the truth gate. The
+reference writer fails closed when derived files exist because transaction
+execution is outside this contract slice. It performs no Git operation, ref
+update, network request, provider call, lifecycle command, or anchor edit.
+
+Preparing development state creates no tag, Release, public package, or
+candidate. Those public effects remain outside the local adapter contract.
+
+The request schema is
+`contracts/next-development-request-v1.schema.json`; the durable record schema
+is `contracts/next-development-transition-v1.schema.json`. Positive and
+negative examples live under
+`contracts/fixtures/next-development-transition-v1/`.