@kungfu-tech/buildchain 3.0.7-alpha.0 → 3.0.7

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

package/docs/engineering-housekeeper.md

@@ -0,0 +1,138 @@
+---
+status: preview
+period: ongoing
+theme: engineering-housekeeper
+doc_type: operational-contract
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: reviewed
+last_reviewed: 2026-08-10
+---
+
+# Engineering Housekeeper
+
+Engineering Housekeeper is a reusable GitHub workflow for evidence-backed
+branch and pull-request hygiene. It inventories the complete GitHub branch and
+open pull-request surfaces, produces a rooted plan, and defaults to report-only
+execution. It never closes pull requests and never deletes a branch from its
+name alone.
+
+The reusable entrypoint is:
+
+```yaml
+uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+```
+
+## Report mode
+
+`report` is the default. The caller grants only read permissions and receives
+separate plan, Markdown report, and dry-run receipt artifacts:
+
+```yaml
+jobs:
+  housekeeper:
+    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+    permissions:
+      contents: read
+      pull-requests: read
+    with:
+      target-branch: dev/v3/v3.0
+      mode: report
+```
+
+The plan records the exact repository, target branch and target OID, every
+observed branch and open pull request, each retain/delete/report/label decision,
+and stable reason codes. The report receipt records dry-run outcomes and binds
+them to the plan root.
+
+## Apply mode
+
+Mutation has a two-part positive gate. The caller must set both `mode: apply`
+and `apply-enabled: true`; either value alone fails closed. Apply jobs consume
+the uploaded exact plan, re-read provider state, and revalidate exact branch
+and target OIDs, ancestry, protection, retention, active pull requests, rename
+state, pull-request state, and staleness before each mutation.
+
+```yaml
+jobs:
+  housekeeper:
+    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+    permissions:
+      contents: write
+      pull-requests: write
+    with:
+      target-branch: dev/v3/v3.0
+      mode: apply
+      apply-enabled: true
+      stale-pull-request-label: stale-housekeeping
+      max-actions: 10
+```
+
+Branch deletion and pull-request labeling run in separate jobs. The branch job
+has `contents: write` plus `pull-requests: read` for the final active-PR fence.
+The labeling job has `contents: read` and `pull-requests: write`. Inventory is a
+separate read-only job. The reusable workflow declares no workflow-level write
+permission.
+
+The action limit applies to the globally ordered plan before actions are split
+by permission surface. A race, missing branch, advanced head, target movement,
+new pull request, new protection, ambiguous ancestry, provider error, or stale
+plan/input mismatch is an explicit receipt outcome rather than permission to
+continue.
+
+## Inputs and outputs
+
+| Input                      | Type    | Default                     | Contract                                                                          |
+| -------------------------- | ------- | --------------------------- | --------------------------------------------------------------------------------- |
+| `repository`               | string  | caller repository           | Exact `owner/repo` target.                                                        |
+| `target-branch`            | string  | required                    | Exact ancestry target; the observed OID is recorded in the plan.                  |
+| `mode`                     | string  | `report`                    | `report` or `apply`. Other values fail.                                           |
+| `apply-enabled`            | boolean | `false`                     | Required positive gate for `apply`. Invalid with `report`.                        |
+| `protected-patterns`       | string  | version/release families    | Comma or newline separated branch globs.                                          |
+| `retained-patterns`        | string  | train/authority families    | Comma or newline separated retention globs.                                       |
+| `stale-days`               | number  | `30`                        | Positive stale pull-request age.                                                  |
+| `stale-pull-request-label` | string  | empty                       | Empty keeps pull requests report-only; non-empty permits labeling, never closure. |
+| `max-actions`              | number  | `20`                        | Positive global apply limit.                                                      |
+| `artifact-retention-days`  | number  | `30`                        | Retention for plan, report, and receipts.                                         |
+| `buildchain-repository`    | string  | `kungfu-systems/buildchain` | Runtime source repository.                                                        |
+| `buildchain-ref`           | string  | `v3`                        | Runtime ref; trusted manual qualification may pass a train or exact SHA.          |
+
+Stable outputs are `plan-root`, `report-receipt-root`, optional
+`branch-receipt-root` and `pull-request-receipt-root`, `action-count`,
+`outcome`, and the plan/report/default-receipt artifact names. Apply receipts
+are uploaded under the same caller-selected artifact prefix with branch and
+pull-request scope names.
+
+Artifacts and job summaries contain exact repository coordinates, observed
+refs, decisions, reason codes, outcomes, and semantic roots. They never contain
+tokens, application private keys, or authorization headers.
+
+## Caller-owned authentication
+
+The default credential is the caller-scoped `github.token`. A caller may pass
+an alternative token as `github_token`, or pass the paired `github_app_id` and
+`github_app_private_key` secrets to mint an installation token for the exact
+target repository. The workflow contains no repository-specific personal
+credential name or value.
+
+GitHub App credentials must be supplied as a pair. The caller owns App
+installation and permission policy and should grant only repository contents
+read/write and pull-request read/write scopes required by its selected mode.
+Secrets are used only as step environment or action inputs and are not written
+to plans, reports, receipts, summaries, or artifacts.
+
+## Scheduled callers
+
+Buildchain dogfoods the reusable contract through three thin callers:
+
+- `engineering-housekeeper-daily.yml` uses a 30-day window and a 10-action cap;
+- `engineering-housekeeper-weekly.yml` uses a 45-day window and a 20-action cap;
+- `engineering-housekeeper-monthly.yml` uses a 60-day window and a 50-action cap.
+
+Schedules are report-only and read-only. Apply is available only through a
+manual dispatch that selects `apply` and positively enables the apply gate.
+The callers contain schedules and policy values only; inventory, planning,
+revalidation, mutation, evidence, and authentication stay in the reusable
+workflow and its runtime.

package/docs/lifecycle-protocol.md

@@ -301,8 +301,10 @@ and optionally `lifecycle.publish`.
 The verify stage runs after Buildchain has applied the generated version-state
 changes to the local checkout, and before it creates release commits or moves
 refs. After the command finishes, Buildchain checks that only declared
-version-state files changed. This prevents verification from quietly adding
-extra source changes to the release commit.
+`version.files` and `version.derived_files` changed. The latter declares tracked
+outputs regenerated by `lifecycle.version-state` that do not directly contain a
+version field. This prevents verification from quietly adding extra source
+changes to the release commit while keeping generated evidence explicit.
 
 Buildchain-owned untracked runtime evidence is excluded only through an exact
 internal allowlist. This includes contract-drift issue material under