@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/references/delivery.md

@@ -0,0 +1,108 @@
+# Delivery — from `merge-ready` to a verified merge
+
+This is the full procedure behind SKILL.md's [delivery rules](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic). Read it when a component reaches `merge-ready`. The guarantee-4 statements it rests on stay in SKILL.md; this file is the mechanics, the probe rationale, the watch bound, and the dequeue routing.
+
+**The one sentence everything here serves:** a merge tool's return code, a queue acknowledgement, and an auto-merge flag are all *requests*. Only ancestry is a result.
+
+**And ancestry of *which* commit is the whole correctness of that check.** Pass the PR to `combine-and-verify.mjs delivered --sha <merge-sha> --target <branch> --pr <n>`: it takes the SHA from the PR's own merge record and refuses one that is merely the branch head. Under a merge-commit queue the head is an ancestor of the merge commit and passes by accident; under a **squash or rebase** queue the head lands nowhere, so the same honest caller gets "delivered" on one repo and "NOT delivered" for a genuinely merged PR on the next — and the loop hands back work that shipped. (PR #529 is the live case: merged as `bdbece5`, head `c770ae5`, both contained in `main`, which is exactly why this went unnoticed.)
+
+**`merge-ready` is not an exit — it is a unit awaiting delivery, and delivery is gated like every other transition.** Every other move in this loop is refused in state when it is invalid; `merge-ready → merged` had no gate, no counter, and nothing refusable, so a unit could sit there forever and the manifest was never wrong. A component whose members reach `merge-ready` owes one **terminal delivery outcome**: `merged` — with a `mergedSha` **proved contained in the freshly-fetched `origin/<targetBranch>`** by [`combine-and-verify.mjs delivered`](../scripts/combine-and-verify.mjs) — or `handed-back`, with `blockedOn` quoting the unsatisfied condition **verbatim from the merge tool**. Anything else is in-flight, and the handoff reports every member **undelivered, not done**. A merge tool's return code, a queue acknowledgement, and an auto-merge flag are all *requests*; only ancestry is a result.
+
+**Enqueue attempt stages (epic-867 / #946).** For canonical component delivery, the outward enqueue is one `attempt` (`outcome: "requested"` when the `@mergifyio queue` command is posted); acknowledgement, queue membership, unmet conditions, and subsequent queue states are component `observations`, not second attempts. A duplicate enqueue action in the same authorized generation is refused. The canonical record already owns the component PR, so a supplied attempt `pr` must match it. Historical unit delivery retains its original requested/waiting and one-pre-admission-requeue semantics for compatibility.
+
+If those provider facts arrive while an actual resolver dependency is incoherent, append them to the [terminal provider evidence journal](terminal-evidence-journal.md). Appending changes no state. After coherence is restored, `run-state.mjs reconcile-terminal-evidence` reacquires provider/check/queue facts and fresh ancestry before the ordinary delivery transition can land. This is resolver delivery recovery only; #996 owns package/npm coherence and trusted repair.
+
+**Enqueue attempt stages (epic-867 / #946).** For `queue:mergify`, do not invent an ack on the first post. Record `outcome: "requested"` when the `@mergifyio queue` comment is posted and there is not yet a 👍/status payload; promote to `outcome: "waiting"` with `ack: {kind, ref}` once the command is acknowledged **or** queue membership is observed. Optional field `pr` stores the PR number on multi-PR components. **One** re-queue at the same HEAD is allowed when every prior attempt at that HEAD is still pre-admission (`requested`, or `waiting` with `queueState: "not-enqueued"`); a second re-request or any prior `dequeued`/`rejected` at that HEAD still refuses (that is a failed-merge retry, not admission limbo). Example first post: `{"at":"…","action":"enqueue","headSha":"abc","outcome":"requested","pr":892}`.
+
+(Named incident: epic-986 — manifest recorded `mergeShippable: true`, four units `merge-ready` with `lastVerdict: PASS` and their PR refs, and `mergedSha: null` on every one; the loop posted its queue request, got "waiting for queue conditions", and moved to the next unit. Twelve hours, one unsatisfied condition — `-draft`. epic-867 reconfirmed admission-limbo bookkeeping thrash under the old schema.)
+
+**The merge path is a pre-flight decision (`deliveryMode`), and the wrong one fails silently in both directions.** `gh pr merge` on a merge-queue repo bypasses the queue or errors; an enqueue on a direct repo does nothing at all. Settle it with the mechanized probe — [`detect-delivery-mode.mjs`](../scripts/detect-delivery-mode.mjs) — never by reading repo files, and never by assuming. **A queue is a runtime fact, so ask it:** queue configuration commonly lives *outside* the repo (a Mergify `default` queue rule set dashboard-side), so a `.mergify.yml` check answers the wrong question. The probe fails closed — "no probe could run" and "probed and found no queue" are different states, and it returns `null` (exit 2) rather than a silent `direct` for the first. `record-component-delivery-attempt` refuses an action that does not belong to the run's mode (the legacy unit command enforces the same rule).
+
+**`queue` is itself two flows, and the mode does not tell them apart.** `deliveryMode` picks the *state machine*; **`queueProvider` (`mergify` | `github`) picks the mechanics** — how you enqueue, where state is read, what the dequeue reasons are called, and whether a re-evaluation request or an acknowledgement exists at all. This file used to offer "`@mergifyio queue`, or `gh pr merge --auto`" as if those were two spellings of one action. They are not, and getting it wrong fails the same silent way the wrong *mode* does. Both come from the same probe, and **`run-state.mjs delivery-flow <slug>` answers which flow this run is in, with the exact commands** — ask it rather than reading the paragraphs below and choosing.
+
+- **`direct`** — `gh pr merge`, one synchronous action, then the `delivered` post-condition. There is no queue to watch: a `delivery.watch` record in this mode is refused, because it means the run believes it is enqueueing.
+- **`queue`** — **enqueue is three steps: make the PR eligible, request admission, and confirm the request was *processed*.**
+  - **Eligibility is a query, not a checklist.** Read the queue's own unmet-condition list for this PR and satisfy or hand back on each. Do not hardcode one: epic-986's twelve hours were spent on `-draft`, and the repo that taught us that has since *removed* `-draft` from its `queue_conditions` — while draft-ness still blocks the merge itself, because GitHub cannot merge a draft PR. The condition moved; it did not stop mattering. Hardcoding the last incident's condition is how the next one hides.
+  - **Open non-self `CHANGES_REQUESTED` is an eligibility failure, not a note** (epic-876 / #941). After independent PASS and before enqueue, list reviews whose `state` is `CHANGES_REQUESTED` and whose author is not the PR author (and not this run's own self-authored COMMENT). If any remain open, **do not enqueue**: reopen the unit with `reopenReason: external-review` and a new `authorizationBoundary: {kind: head, value: <fix-head>}`, fix the named class, and re-review. A bot that catches a dropped pre-move matrix row is a real AC gap; postmortem must not demote that round as a probable rebase.
+  - **Admission** is the provider's enqueue op (`ops.enqueue` from `delivery-flow`).
+  - **Acknowledgement**, where the provider has one. Mergify's enqueue is a PR comment, so it can simply go unread; the 👍 reaction (or its status-comment payload) is the evidence it did not. Recorded as `ack` on the attempt, and **required** — without it, "the queue is holding this PR" and "nobody read the comment" are the same manifest record. GitHub's native enqueue is an API call that returns its own receipt, so it owes no ack.
+
+  Then **watch to a terminal queue outcome**. `waiting_for_batch`, `preparing`, `running`, `bisecting`, `waiting_for_previous_batches` and `waiting_for_merge` are all *keep watching* — and so is **`waiting-for-queue-conditions`**, the pre-admission state this model did not name until PR #529 spent minutes in it: command acknowledged, every condition green, and `mergify queue show` answering *"PR #529 is not in the merge queue"* while `queue status` answered *"Queue is empty"*. Both read exactly like "your enqueue never happened", which is the genuinely different state **`not-enqueued`**. Read pre-admission state from the provider's `ops.readPreAdmissionState` (for Mergify, its status comment carries a machine-readable payload plus the rendered condition tree), and record the unmet leaves verbatim in the observation — they are what a hand-back must quote, and an empty list is what makes a nudge legitimate.
+
+**The nudge: one re-evaluation request, where the provider has one.** Pre-admission, unchanged past `DELIVERY_NUDGE_AFTER_MINUTES` (5), with nothing listed unmet, `record-component-delivery-observation` exits **5** and names the command — `@mergifyio refresh`. Spend it once (`record-component-delivery-nudge`), which restarts the stall clock once. This is **not** a retry of the merge path: it attempts nothing and touches no HEAD. It is capped at one because the evidence behind it is one observation — #529 was admitted within a poll of its refresh, which is correlation, not proof; if the refresh does nothing the stall bound still fires and the unit still hands back. What the cap buys is that being wrong costs one comment, while being right saves a healthy unit from handing back at the stall bound. The nudge is due at 5 minutes against that 10-minute bound, and spending it restarts the clock, so a nudged unit still gets a full bound afterwards. `github` has no such command, so no nudge is ever due there and recording one is refused.
+
+**A queued PR's branch is frozen.** A push under an enqueued PR ejects it (`pull-request-updated`) — and this loop pushes for several ordinary reasons: an evidence-lane commit, a rebase, `mergify stack push`. Dequeue explicitly before writing to an enqueued branch. `validate` reports the drift (the head sitting in the queue vs the unit's latest round) rather than refusing the write, because the write is often already done by the time anyone looks.
+
+**Do not empty-commit to re-trigger CI while a review or delivery is in flight** (epic-876 / #941). Prefer non-SHA-moving re-triggers (`gh run rerun`, workflow_dispatch, `@mergifyio refresh`). An empty commit under a live reviewer forces **head-drift** and buys a full re-review of an identical production tree. If the tip must move for CI, freeze the tip *before* spawning the reviewer — or, when `git diff OLD NEW` is empty of production paths, route as an **evidence re-attest** (`reviewSubject: evidence`, no adversarial re-read of unmoved code) rather than a full-scope review. Never use an empty commit as the default answer to "CI didn't fire after retarget/rebase."
+
+**Hybrid/auto observation path (enqueueTrigger ∈ {hybrid, auto}) — #791 / issue-664 / identity#669.**
+
+On a hybrid or pure-auto repo a PR can reach `targetBranch` **without** this loop posting `@mergifyio queue`. GitHub/Mergify merge on their auto conditions the moment the review is posted as an approval (or CI turns green). The skill used to optimise only for enqueue → watch queue → record outcome, so a unit could be **actually merged** while the run manifest still said `merge-ready` / **UNDELIVERED**, and the postmortem invented a multi-hour "delivery wait." Measured: PASS ~02:48, PR merged 03:01:28, `record-delivery-outcome` only at 10:23 after a human "check the progress."
+
+After `lastVerdict: PASS` (any `enqueueTrigger`) with a known `pushedSha` / PR — **one background pipeline** (#792 / issue-664 / identity#669):
+
+```
+node watch-delivery.mjs --pr <n> --repo <owner/name> --head <pushedSha> …
+  poll CI on exact HEAD + PR lifecycle together
+  on MERGED (hybrid/auto may land without enqueue) → exit 0 + mergedSha + mergedAt
+  on CI red while OPEN                             → exit 5 + reason ci-failed  (fold into fix round)
+  on head-drift (PR tip ≠ --head)                  → exit 4 + reason head-drift  (re-review new head;
+                                                     never merged/ci-failed for the old SHA)
+  on dequeued / closed / stalled                   → exit 4 + reason
+  on CI green + still OPEN                         → keep watching (enqueue/auto-merge may still fire;
+                                                     pure-queue: enqueue first, then this same watch)
+```
+
+**Exact-HEAD is fail-closed.** With `--head`, every terminal classification is for that SHA only. The watch compares `headRefOid` to the supplied tip before merge/CI outcomes: if the branch moved after PASS, exit 4 with `reason: head-drift` so the orchestrator re-reviews the rewritten head rather than recording delivery or CI failure against a stale SHA (guarantee 3).
+
+The orchestrator only **records and routes** the terminal JSON — no foreground poll turns. Exit codes distinguish merged (0) / not-merged hand-back (4) / CI failed (5); never "still going" as success. Absolute ceiling is the existing stall + max minutes.
+
+Rules that follow:
+
+- **Do not require a prior `@mergifyio queue` before watching for terminal merge.** `watch-delivery.mjs` / `classifyPrState` already treat `state=MERGED` as terminal regardless of `everQueued`; the gap was the orchestrator only launching the watch after enqueue.
+- **Launch the watch in the same turn as PASS+CI-pending**, not only after explicit enqueue. Pass `--head <pushedSha>` so CI red is a distinct exit 5. A hybrid unit that auto-merges mid-watch still ends the watch with exit 0 + `mergedSha` + `mergedAt` (merge wins over CI red while checks settle).
+- **Record `mergedAt` on `record-component-delivery-outcome`** (from the watch terminal JSON / `gh pr view --json mergedAt`) so postmortem prefers the provider's merge clock over the separate canonical `outcomeAt` bookkeeping clock.
+- **Do not leave the terminal outcome write until a human asks for progress.** `run-state.mjs progress` must not still report UNDELIVERED for a PR whose merge commit is already on `origin/<targetBranch>` once the watch has run.
+
+For pure `manual` enqueueTrigger: make eligible → enqueue → same `--head` watch. Hybrid/auto adds the *observation without enqueue* branch; it does not replace the manual enqueue path.
+
+**Run the watch as one launch, not as a foreground poll loop — [`watch-delivery.mjs`](../scripts/watch-delivery.mjs).** It observes only: it never enqueues, never merges, never records, and takes no merge authorization — the enqueue decision and the outcome write stay with the orchestrator, because those are guarantee 4's authorization and the audit trail. What moves off the main thread is the waiting.
+
+The reason is context, not convenience. The orchestrator is a thin scheduler, and polling is the largest consumer of its turns: delivering one PR in this repo took **13 foreground `gh pr view` calls**, and a Pi session delivering an epic spent **71 polling calls** (36 `gh pr view`, 18 `gh pr checks`, 17 `mergify queue`) — none of which produced a decision. That run ended with the orchestrator hand-patching its own manifest JSON, which is what a full context window looks like from the outside. Launch it in the background (or as a spawn) and record the terminal answer when it lands; **exit 0 = merged with the merge commit, exit 4 = terminal but not merged** — it never exits 0 on a timeout, because "still going" and "finished" collapsing into one code is the epic-986 shape. Exit 0 is still not a proved merge: the ancestry check remains owed.
+
+**Watching is bounded on stall, not on elapsed time** (`record-component-delivery-observation`, exit **4** = the component watch owes a hand-back). A unit can sit in `waiting_for_previous_batches` for a long time while genuinely progressing, so a flat timeout hands back healthy units; what separates wedged from slow-but-moving is whether the observed delivery surface ever changes. The stall key is **(PR state, queue state, position, labels, queue membership, CI fingerprint)** — not labels alone. Only a change to that key restarts the clock; a poll that observes the same picture is evidence of a stall, not of life. Past `deliveryWatchBoundMinutes` (default **10**) with no movement, the watch process exits 4 with the reason quoted. That default is deliberately the same number the watcher scripts use for their own stall bound (`--bound-minutes` / `--stall-minutes`): the script bounds the process doing the watching and this bounds what gets recorded about it, so a manifest bound larger than the script's would never be reached — the script hands back first and the orchestrator stops observing. Recording an observation is **refusable only on its own shape** — a missing `queueState`, or a delivery record already invalid for the run's mode — never on unrelated unit state, because a logging call that can hard-fail is one an orchestrator learns to stop making and a watch nobody writes is the failure this bound exists to end. For everything else the signal is the exit code and the `validate` warning, never a throw. **`frozen` and `waiting_schedule` hand back on first sight**, without waiting out the bound: the queue is already telling you what is wrong and no amount of waiting changes it (`waiting_schedule` can legitimately mean *Monday*, and holding a session open until then is never the answer). (epic-986 sat twelve hours on a queue state that never moved once.)
+
+**A stalled watch is not always a stalled unit.** Exit 4 carries two different reasons that used to share one name:
+
+| reason | What it means | Orchestrator route |
+|---|---|---|
+| `conditions-unmet` | Picture frozen **and** the queue is not holding the PR (or membership is unknown and labels do not say queued) | Unit-level hand-back; quote the condition; do not re-enqueue the same HEAD |
+| `stall-while-queued` | Picture frozen **but** the queue still holds the PR (`queueActive` or `queued` label) — typically "Preparing checks" with no position movement while CI runs | **Not** a unit hand-back. In the same turn: `gh pr view --json state,mergedAt,mergeCommit` once; if MERGED, record `merged` + ancestry. If still OPEN, **relaunch** `watch-delivery.mjs` with the same `--head` (the absolute `--max-minutes` ceiling still bounds total wall time). Never record `outcome: handed-back` for the unit and never re-enqueue. |
+| `unreadable` | Polls could not be read | Same as conditions-unmet for routing; fix the tool surface first |
+
+Named incident: `issue-799-800-resolve-release` #807 / PR #810 — watch exited `conditions-unmet` after 10m of OPEN+`queued` with no key change while Mergify was preparing checks; the PR merged two minutes later; `record-delivery-outcome` landed only after a multi-hour session gap (`outcome-write-lag`). The root cause was the stall key ignoring queue membership and CI progress, plus treating every exit-4 stall as unit-terminal.
+
+**And bounded absolutely at one hour, whatever the stall bound says.** The stall bound cannot catch a queue that keeps *moving* without ever finishing — movement is exactly what resets it — so `--max-minutes` is the backstop for that case, and it is capped at **60 minutes** in both watchers rather than left to the caller. A larger value is refused (exit 2), not clamped: a watch that outlives the session that launched it produces no verdict at all, while one that hands back at an hour produces a routable one. A batch takes minutes, so an hour of continuous movement without a merge is already a queue for a human to look at. Relaunch after a `stall-while-queued` or ceiling hand-back; do not raise the ceiling.
+
+**Where the dequeue is *observed* is the queue skill's business, not this one's.** This file owns the routing — what a reason means for the loop's state machine — and it is deliberately provider-neutral, because `checks-failed` re-enters the loop whoever reported it. **How you notice a dequeue at all is Mergify-specific mechanics**, and the local `mergify` skill holds them in [`references/watch-contract.md`](../../../cicd-pipeline/mergify/references/watch-contract.md): the `queued`/`dequeued` label lifecycle, the fact that a still-open PR *losing* `queued` is a possible dequeue transition (GitHub can briefly expose neither label before adding `dequeued`), and the rule that a watcher which has already observed queue entry must **never** keep reporting `{"queued": false}` as a routine healthy snapshot — that reading is a queue exit unless the PR merged. Read it there rather than re-deriving it here; two watch disciplines that each know half of this is how a wedged unit reads as a healthy one. For Mergify-backed simple deliveries, prefer `../../../cicd-pipeline/mergify/scripts/watch-pr-delivery.mjs`; `watch-delivery.mjs` remains the resolve-issues wrapper that records and routes the terminal answer.
+
+The one premise worth carrying across the seam, because a reader who skips the pointer will otherwise build the wrong shape: **a watch observes a progression, not a state.** No single reading distinguishes "not admitted yet" from "dequeued" — that verdict is a *transition*, and it depends on what the watcher already saw. So a watch is one long-lived process carrying its own history (`everQueued`, the absent-read streak, readable-vs-absent, the change clock), never a stateless predicate a background runner re-evaluates each tick. Both watchers here are that process; do not wrap either in an outer poller, and do not hand-roll a `gh pr view` snippet in its place. Pi session `019fae8f` is what that costs: four hand-rolled watchers for one PR, none able to see a dequeue, one reporting a false `DEQUEUED` on a healthy PR.
+
+**The skill never retries the merge path — the queue already retries exactly what should be retried.** A red batch is resolved by the queue's own `bisecting` state and the innocent PRs carry on; what a queue pointedly does *not* auto-retry is a PR whose own checks failed, because that loops forever on broken code. So a second attempt at an unchanged HEAD is refused. Re-entry to the merge path is earned by a fix and a fresh verdict, never repeated by the orchestrator. A dequeue is classified by a reason **read from the queue tool, never inferred** (the same rule as the reviewer's `subject: code|evidence` — the tool observed it and you did not):
+
+**Record the queue's own string in `rawReason`; the routing class in `reason`.** The canonical classes below are *routes*, and the queue's vocabulary is wider than they are — Mergify's `queue-dequeue-reason` type alone carries ~40 values. Demanding one of five "read from the tool, never inferred" was self-contradictory: the tool says `pull-request-updated` and the taxonomy accepted neither that string nor any honest translation. `dequeueRouting()` owns the mapping, a `reason` that contradicts its `rawReason` is refused, and **anything unmapped routes to a hand-back** — a reason the table has never seen is not evidence about the code.
+
+| reason (raw → class) | routing |
+|---|---|
+| `checks-failed` | back to `in-progress` → fix round → **fresh independent verdict** (guarantee 3) → a new enqueue. The queue tests *PR merged with base* — a tree that never existed at review time and that per-PR CI structurally cannot have covered, so an ejection there is new information about code about to land, and it is a round of this loop rather than a delivery retry. |
+| `pull-request-updated`, `draft-pull-request-changed` | same route, different cause: **HEAD moved under the queue**, so the verdict that authorized this delivery is stale. Usually the loop's own push — see the branch freeze above. |
+| `conflict`, `conflict-with-base-branch` | **Provider-observed conflict only:** enter the [evidence lane](loop.md#3--fix-then-loop), reconcile according to the repository's queue policy, re-verify, then enqueue the new HEAD. Mere target advancement or GitHub `DIRTY` before enqueue is not this route in a batched Mergify queue: Mergify owns synthetic current-base integration. |
+| `conditions-unmet` / `frozen` / `manual` / `pr-manually-dequeued` / `checks-timeout` | **hand back**, naming the condition and, for a pause, its reason — never queue over a human. A timeout is not evidence the code is broken, and re-enqueueing the same HEAD is refused anyway. |
+| `stall-while-queued` | **not a unit hand-back** — the *watch process* ended on a frozen picture while the queue still holds the PR. Re-observe once (`gh pr view`); if MERGED, record delivery; if still OPEN, relaunch the same `--head` watch. Do not re-enqueue. (Watch-local reason from `watch-delivery.mjs`; not a Mergify dequeue class.) |
+| anything else | **hand back** — the fail-closed default, with the raw string quoted |
+
+**Deliver a shippable component into `targetBranch` only when pre-flight recorded `mergeShippable` and the mode-specific live gate passes.** The decision is read from the manifest, never supplied as a flag. For direct delivery, `combine-and-verify.mjs mergeable` requires exact target-tip integration before `gh pr merge`. For queue delivery, `combine-and-verify.mjs enqueue-eligible` requires the immutable frozen PR head, PR-head CI, dependencies, required-check evidence mapping, and live proof that `baseShaAtAssemble` remains an ancestor of the target. Forward target movement is allowed because a batched Mergify queue tests a synthetic current-base plus candidate tree; rewritten or divergent target history is blocked. Post one provider enqueue only after exit 0, then use the canonical watcher. **Do not rebase merely because the target advanced, and never run `gh pr merge` in a Mergify queue flow.** Absent authorization, hand the component back merge-ready and merge nothing.
+
+**Queue execution proof is post-delivery evidence, not enqueue evidence.** The canonical watcher receives `--required-check-plan` and `--queue-execution-provider <resolve-issues>/scripts/exact-head-github-provider.mjs`, and sends the same exact `read-queue-execution` JSON request to that provider on every poll. While Mergify is active, the provider reads the status payload's `speculative_check_pr`, resolves that draft's distinct head, and returns a non-authorizing `queue-execution-observation` with the synthetic PR/SHA and available required queue-head check names/states. Synthetic checks changing queued → running → success restart the no-change clock even when the source PR's queue-only check is expectedly skipped; repeated observations still stall, and all progress remains subject to the absolute ceiling.
+
+On `MERGED`, the provider read performs: (1) `gh pr view <pr> --json headRefOid,comments`, requiring the frozen PR SHA and exactly one Mergify merged-status `Checks passed on draft #<n>` identity; (2) `gh api repos/<owner>/<repo>/pulls/<n>` to resolve the distinct synthetic queue head; and (3) `gh api --paginate --slurp repos/<owner>/<repo>/commits/<queue-sha>/check-runs?per_page=100` to capture every required queue-head conclusion. The watcher independently validates the returned version-1 `queue-execution` artifact against repository, source PR/head, synthetic PR/head, planned provider, and every required successful check before exit 0. Empty output, malformed JSON, non-zero exit, timeout, any stderr, missing/duplicate/skipped/stale evidence, or an invalid artifact returns a distinct `evidenceBlocked` error and exit 4, never delivery success. On `MERGED`, prove both fresh `origin/<target>` ancestry and that artifact with `combine-and-verify.mjs queue-delivered`; if capture is blocked, record/hand back `evidence-blocked`. A red/dequeued batch follows ordinary routing; raw queue checks are diagnostic only and never forged into success.

package/skills/engineering/resolve-issues/references/evidence-lane.md

@@ -0,0 +1,21 @@
+# The evidence lane — a round that corrects a claim, not the code
+
+This is the full procedure behind SKILL.md's [evidence lane](loop.md#3--fix-then-loop). Read it when a round looks like it is about the artifacts rather than the diff.
+
+**Not every PASS is an evidence round (epic-867 / #948).** `evidenceClasses` and the evidence-audit warn apply when the round is correcting claims/evidence (typed `reviewSubject: "evidence"`, or a legacy `productionMoved: false` after the unit already saw a `NEEDS_CHANGES`). A clean first-pass PASS — single PASS, no prior fix loop — is ordinary produce+review success, not an evidence-lane spend. Do not invent `evidenceClasses` on those rounds; `evidence-audit` stays silent on a 4× first-pass epic.
+
+**The routing rule stays in SKILL.md and is repeated here because getting it wrong skips the adversarial review:** both signals must hold — the production diff unmoved *and* every surviving finding classed `subject: evidence` by the reviewer. Either absent is an ordinary round.
+
+Note the lane's own dependency: it reads production-diff emptiness from `evidence-block.mjs` as a **screen**, which still runs every round. That is unaffected by the attestation retiming — what moved to the terminal round is the stamped block, not the check.
+
+- **This lane should now be rare.** Retiming the attestation to the terminal round (step 2) removes the *cause* of most evidence-only rounds rather than making them cheap: a stamp that is never regenerated mid-loop cannot go stale mid-loop. What remains is the residual — a rebase that moves the base, a checklist row citing a superseded locator. If this lane is still the common path after that change, the finding to chase is why the screens are not catching what the reviewer is catching, not how to make the lane faster.
+- **Is this round even about the code? (check every round, healthy units included).** Two independent signals must both hold, and neither is your judgment about code you did not read. **(a) The production diff did not move** — read this from `evidence-block.mjs` (`--source`, comma-separated in one token), never a hand-rolled `git diff`: the tool already computes production-diff emptiness, stamps it to a HEAD, and surfaces it as a validate warning, and a second command in prose is how the two drift apart. Its hazard is documented in its own header and is worth knowing before you trust an `EMPTY`: git exits 0 on a pathspec matching nothing, so a mistyped or space-separated `--source` reads EMPTY on every run and would route every round into this lane. **`EMPTY` from a `--source` whose paths you have not seen resolve is not signal (a)** — that is the one failure this check cannot afford, since it fails *open*, straight past the adversarial review. **(b) The reviewer classed every surviving finding `subject: evidence`** (review-pr § Verdicts and the blocking bar) — the reviewer read the diff and you did not, so the classification is read, never inferred. Signal (a) alone is not enough: a forced full-scope round can surface a genuine code defect in code that has not moved since `lastReviewedSha`, and routing that into this lane skips exactly the adversarial re-review it needs. **Either signal absent → ordinary round.** With both, don't buy a producer spawn + adversarial re-review for a claim correction on unchanged code. Spend a narrow **evidence-fix spawn** instead — and note what it is *not*: it is not you editing the files. You coordinate, never implement, and that rule does not lapse because the diff is small; an orchestrator that hand-fixes a checklist is the same row-1 violation as one that hand-implements a unit.
+
+  > Read `<skillsRoot>/ensure-coverage/SKILL.md` (absolute) and follow its evidence/checklist doctrine; do not improvise. Subject: the findings classed `subject: evidence` on `<prRef>`, plus any validator left red by the step-2 pre-spawn check. **Touch no source file.** Your whole diff is confined to the evidence artifacts — the Review Contract block, the coverage checklist, the evidence block, and the docs the contract cites. **`@covers`/`@level` tags are not on that list**, because they live inside test files: editing one moves the production diff, and a lane that skips the adversarial review is the last place that should be able to touch a test — "fixing a tag" is exactly the cover an assertion-weakening edit would ride in under. If a finding cannot be fixed without a source change, **stop and report it unfixed** rather than making the change: that means the round was mis-routed and owes an ordinary fix round. Land one commit, then re-run `evidence-block.mjs validate` and `coverage-checklist.mjs validate <checklist> --diff <merge-base>` at the new HEAD and return both results stamped with that SHA. **The `--diff` is what makes the second one a re-check rather than a re-typing:** it resolves every locator you just wrote against the tree, so a correction that swaps one dead locator for another dead locator fails here instead of coming back as the same finding next round.
+
+  **Proof:** both validators green at the new HEAD **and** signal (a) still holding against it — the same `evidence-block.mjs` run that routed the round into this lane verifies the spawn honored its constraint, so the guard costs nothing extra. A source file in that diff means the lane was mis-routed: discard it and take an ordinary round, including the adversarial review. Then request the terminal review directly. The claims still have to be true — what changes is that a corrected claim over unmoved code is the validator's job, not an adversarial reviewer's.
+  - **A rebase or restack is this lane, not a new unit.** Moving the base changes which SHA the evidence cites while the production diff stays identical; that is an evidence refresh, and the correct response is to regenerate the block and revalidate — not to spend a fresh adversarial review re-reading code that did not move. (The contract-revision gate is the exception that overrides this: an *approved contract* landing on the target branch forces a full-scope review regardless.)
+  - **Batch them; one evidence round is the budget.** Fix every outstanding evidence finding in a single commit and revalidate once. A *second* consecutive evidence-only round means the validator is not catching what the reviewer is catching — fix that gap (or hand it to the human) rather than iterating claim corrections one at a time, and count the repeat toward the circuit-breaker like any other round.
+  - **A red external dependency is not a finding.** A flaky third-party gate or an unrelated CI timeout blocks *exit*, not the round: retry the gate, don't spend a review round rendering a verdict on it.
+
+  (Named incidents: three consecutive rounds of evidence-fidelity findings over an empty production diff; a unit whose reviewer wrote *"the implementation itself is correct at this head"* and blocked solely on a checklist citing a pre-restack base — then spent the next round rejecting the checklist fix; and two closing rounds on one PR where the second reviewed the identical SHA as the first, proving no code delta, because a flaky external gate had held the verdict.)

package/skills/engineering/resolve-issues/references/exact-head-ci.md

@@ -0,0 +1,287 @@
+# Exact-head CI adapter
+
+The adapter has two equally authoritative collection modes for one exact pull-request
+head:
+
+- `choreographed` temporarily mutates PR state, dispatches a workflow, restores the
+  original state, and proves restoration.
+- `observed-existing-run` reads an already-running or completed provider workflow and
+  proves that the live PR head did not move while workflow and publish-only evidence
+  were acquired. It performs no PR mutation and makes no restoration claim.
+
+Both modes use the same required-check plan, raw-job classification, publish-only
+evidence validation, and downstream exact-head validator. Observation is not a
+fallback or weaker evidence path; its provenance is different because no state was
+mutated.
+
+## The full check set at a head
+
+The adapter above, and the required-check plan it consumes, answer **the name question**:
+are the checks the plan names green? Neither asks **the set question**: what else is red at
+this SHA? [`scripts/head-check-set.mjs`](../scripts/head-check-set.mjs) is that question. It
+is a separate tool rather than a plan field because it has to be able to report a state the
+plan has no vocabulary for.
+
+```sh
+node <resolve-issues>/scripts/head-check-set.mjs collect \
+  --repository owner/name --head <40-sha> \
+  [--plan required-check-plan.json] [--out head-check-set.json] [--markdown] [--strict]
+```
+
+**Why three channels and not one.** #1081 shipped two workflows GitHub rejected at
+validation time. At `ee5dd91a211d85f3158cbc4da8537b0cb1aee2d8` the observation was:
+
+| channel | what it said |
+|---|---|
+| `GET /commits/{sha}/check-runs` | 4 entries — every one `success`, `neutral` or `skipped` |
+| `GET /commits/{sha}/status` | `pending`, zero statuses |
+| `GET /actions/runs?head_sha=` | 3 runs — **two `failure`, zero jobs, `name` equal to `path`** |
+
+Reading *all* check-runs rather than the named ones would still have reported that head
+clean. A workflow GitHub cannot parse creates a run and produces no check-run to be red, so
+the Actions channel is the only place it exists at all. The post-fix head `284d6ca6…`
+reports `green` with those two runs **absent** — a workflow that merely stopped failing
+would not have been proof.
+
+**What it reports.** Three states that used to blur into one: a check that is required and
+red; a check that is **not** required and red (informational); and a check that never ran at
+all — the last carrying which absence it is: `no-run-anywhere` (the event was never
+delivered; waiting is futile), `pending` (waiting is right), `dispatched-out-of-band`
+(honest exact-head evidence that satisfies no queue condition), or
+`absent-though-runs-completed` (#1058). Zero-job runs are named one by one in
+`signatures.startupFailures`, never folded into a count.
+
+**What it refuses to do.** `collect` exits **1 only on the required set** — a required check
+red or absent, which the merge-admission contract already blocks on — and **0 on undeclared
+red**, however loudly it reports it. Whether a non-required red check should stop a merge is
+a policy decision belonging to the human and to `.mergify.yml`; a reporting script that
+quietly changed what merges would be a worse defect than the one it fixes. `--strict` opts
+in and nothing in the loop passes it. Omit `--plan` and nothing is classified required,
+which degrades the tool to a pure observation of the SHA rather than a verdict.
+
+## Choreographed Run
+
+Before creating the request, discover and commit a versioned `required-check-plan.json` bound to the frozen component HEAD. The plan is the complete merge-admission contract, not a caller-selected job list. Use `required-check-plan.mjs` with live GitHub ruleset data, the live `.mergify.yml`, and explicit per-check mappings; it refuses an unmapped condition.
+
+Create a request JSON that embeds that exact plan and run:
+
+```sh
+node <resolve-issues>/scripts/exact-head-ci.mjs run \
+  --input exact-head-request.json \
+  --out exact-head-artifact.json
+```
+
+For GitHub, point the provider at the bundled adapter:
+
+```json
+{
+  "version": 1,
+  "collectionMode": "choreographed",
+  "repository": "owner/repository",
+  "pr": 123,
+  "expectedHeadSha": "0123456789abcdef0123456789abcdef01234567",
+  "provider": {
+    "command": "node",
+    "args": ["<resolve-issues>/scripts/exact-head-github-provider.mjs"],
+    "config": {
+      "ghCommand": "gh",
+      "queueProvider": "mergify",
+      "queueActiveLabels": ["queued"],
+      "queueDeactivateArgs": [
+        "pr",
+        "comment",
+        "{pr}",
+        "--repo",
+        "{repository}",
+        "--body",
+        "@mergifyio dequeue"
+      ],
+      "creationTimeoutMs": 60000,
+      "creationPollIntervalMs": 1000
+    }
+  },
+  "temporaryBase": "integration/epic-42",
+  "choreography": ["retarget", "close", "reopen", "dispatch"],
+  "workflow": {
+    "id": "CI Stages",
+    "ref": "feature-branch",
+    "inputs": {
+      "exact_head": "0123456789abcdef0123456789abcdef01234567"
+    }
+  },
+  "requiredCheckPlan": {
+    "version": 1,
+    "kind": "required-check-plan",
+    "repository": "owner/repository",
+    "targetBranch": "main",
+    "headSha": "0123456789abcdef0123456789abcdef01234567",
+    "discovery": {
+      "github": { "conditions": ["required_status_checks: Mergify Merge Protections"] },
+      "mergify": { "conditions": ["check-success = unit"] },
+      "requiredChecks": ["Mergify Merge Protections", "unit"]
+    },
+    "checks": [
+      { "name": "Mergify Merge Protections", "admission": "required", "classification": "publish-only", "sources": ["github-ruleset"], "evidence": { "provider": "github", "reason": "published after PR creation" } },
+      { "name": "unit", "admission": "required", "classification": "locally-reproduced", "sources": ["mergify"], "evidence": { "command": "node --test", "job": "unit", "result": "success" } }
+    ],
+    "allowedSkippedJobs": ["merge-queue-only"]
+  },
+  "policy": {
+    "pollIntervalMs": 2000,
+    "timeoutMs": 1200000
+  }
+}
+```
+
+## Observe An Existing Run
+
+For a natural `pull_request` workflow already attached to the exact PR head, supply
+its provider workflow and run identity. Do not include `temporaryBase`, `choreography`,
+workflow dispatch `ref`, or workflow `inputs`:
+
+```json
+{
+  "version": 1,
+  "collectionMode": "observed-existing-run",
+  "repository": "owner/repository",
+  "pr": 123,
+  "expectedHeadSha": "0123456789abcdef0123456789abcdef01234567",
+  "provider": {
+    "command": "node",
+    "args": ["<resolve-issues>/scripts/exact-head-github-provider.mjs"],
+    "config": {
+      "ghCommand": "gh",
+      "queueProvider": "mergify",
+      "queueActiveLabels": ["queued"]
+    }
+  },
+  "workflow": {
+    "id": "CI Stages",
+    "runId": 123456789
+  },
+  "requiredCheckPlan": "<the same complete plan shape shown above>",
+  "policy": {
+    "pollIntervalMs": 2000,
+    "timeoutMs": 1200000
+  }
+}
+```
+
+The collector snapshots the live PR before reading the named run, polls that run to
+completion, acquires provider-issued publish-only checks, then snapshots the live PR
+again. Either snapshot, the workflow, or publish-only evidence naming another head
+fails the artifact. The artifact contains `observation.before` and
+`observation.after`; a `restoration`, `choreography`, or top-level choreography
+`snapshot` field is invalid in this mode.
+
+For `choreographed`, all repository-specific mutation and dispatch values are input:
+repository, temporary base, choreography, workflow id/ref/inputs, a complete
+`requiredCheckPlan`, provider executable, and queue detection/deactivation. For
+`observed-existing-run`, the existing workflow/run identity replaces mutation and
+dispatch values. `policy.requiredJobs` and `policy.allowedSkippedJobs` are legacy and rejected
+with migration guidance; exact-head CI derives local required jobs and allowed skips from
+the plan. `main` and `CI Stages` are examples, never defaults.
+
+`queueActiveLabels` must describe the provider's live queue-membership signal. Use an
+empty array only where no label represents membership. `queueDeactivateArgs` is a configured
+`gh pr comment {pr} --repo {repository} --body <deactivation>` argument vector. The GitHub
+provider accepts that exact shape only, requires the body to name `dequeue` or `unqueue`,
+and rejects extra arguments or enqueue/approve/merge/review intent before invoking `gh`.
+It may remove membership created during choreography but has no enqueue counterpart. The
+adapter refuses an active queue snapshot before mutation: restoring it would require
+enqueueing, which this adapter is structurally forbidden to do. Dequeue explicitly under
+the delivery provider's own policy before collecting exact-head CI.
+
+## Provider contract
+
+The provider receives one JSON request on stdin and returns one JSON object. The only
+operations are:
+
+- `snapshot`
+- `retarget`
+- `set-open`
+- `set-draft`
+- `set-labels`
+- `set-queue-inactive`
+- `dispatch-workflow`
+- `read-workflow`
+- `read-publish-only-checks`
+- `read-queue-execution`
+
+There is no enqueue, approve, merge, review-write, or queue-write operation. A custom
+provider may implement another host, but it must preserve the same operation vocabulary
+and snapshot shape: base, full head SHA, open/draft booleans, exact label set, queue
+object with boolean `active`, and relevant review state.
+
+`read-workflow` receives the expected `runId`, `workflowId`, and full `headSha`. Its
+response preserves the provider-issued workflow identity as
+`workflow: { id, name, path? }` alongside the provider run id, head, status,
+conclusion, and jobs. The adapter compares the configured selector with the provider
+id, name, full path, or path basename before accepting jobs. The GitHub provider reads
+`repos/<repository>/actions/runs/<runId>`, performs the same comparison against the
+REST response's `workflow_id`, `name`, and `path`, and refuses a run-id, workflow, or
+head mismatch before reading jobs.
+
+## Artifact truth
+
+Version 2 artifacts declare exactly one closed-vocabulary `collectionMode`. Every
+artifact binds repository, PR, expected/workflow SHA, the requested workflow selector,
+provider-issued workflow id/name/path, provider run identity, the versioned
+required-check plan, derived provider-neutral policy, every raw job conclusion,
+provider-issued publish-only evidence, and the derived outcome.
+`choreographed` additionally records the original snapshot, mutation choreography,
+all restoration attempts, final live snapshot, and whether restoration was proved.
+`observed-existing-run` instead records live `before`/`after` observations and forbids
+restoration or mutation claims. Every discovered check is classified
+`locally-reproduced` or `publish-only`
+with evidence. The plan preserves each Mergify lifecycle source as a `pr-head` or
+`queue-head` phase: exact-head CI validates only PR-head evidence. Changed-path
+exemptions remain structural and explicit in the phase tree; `skipped` remains
+`skipped`, never satisfies a required job, and never becomes `success`.
+
+A queue-head check is never bound to the frozen PR SHA. Its required-check-plan entry names a provider and acquisition path before enqueue, but no synthetic evidence is required for terminal PR-head authorization. During the queue watch, the canonical watcher sends one exact `read-queue-execution` request per poll to `exact-head-github-provider.mjs`. An active Mergify status payload's `speculative_check_pr` identifies the synthetic draft; the provider resolves its `head.sha` and required check runs, then returns a non-authorizing observation whose queued/running/success changes count as delivery progress.
+
+After Mergify merges, the same request reads the merged status comment's unique synthetic draft PR, resolves that draft's `head.sha` through `gh api repos/<repo>/pulls/<draft>`, then reads `gh api --paginate --slurp repos/<repo>/commits/<queue-sha>/check-runs?per_page=100`. It emits a version-1 `queue-execution` artifact with the frozen `prHeadSha`, distinct synthetic `queuePr`/`queueHeadSha`, provider identity, and every required queue-head conclusion. The watcher validates the complete artifact before reporting success; provider IPC errors and absent, skipped, mismatched, ambiguous, or PR-SHA-bound queue evidence are `evidence-blocked`, never a completed delivery. `combine-and-verify.mjs queue-delivered` still requires both that valid artifact and fresh merge-commit ancestry.
+
+A legacy artifact without `requiredCheckPlan` fails validation with actionable migration
+guidance. This is deliberate: epic-892 passed a supplied resolver job set while omitting
+deterministic `skill-size`, then moved the reviewed head after publication.
+
+Both modes fail closed on malformed input/provider output, head drift, missing or
+duplicate evidence, workflow identity mismatch, zero jobs, job failure/cancellation,
+and disallowed skips. `choreographed` additionally fails on active queue membership,
+workflow-creation failure, interruption, or restoration proof failure; `SIGINT` and
+`SIGTERM` are recorded at the next operation boundary and still enter `finally`
+restoration. `observed-existing-run` never enters a restoration path because it never
+mutates PR state.
+
+Validate independently at the SHA a consumer expects:
+
+```sh
+node <resolve-issues>/scripts/exact-head-ci.mjs validate exact-head-artifact.json --head <sha>
+```
+
+Consumers recompute passability from raw jobs plus policy and enforce the selected
+mode's provenance contract. A forged `status: pass`, green summary over failed jobs,
+synthetic restoration on observation, or missing restoration after choreography is
+rejected.
+
+## Consumers
+
+Review evidence:
+
+```sh
+node <ensure-coverage>/scripts/evidence-block.mjs collect \
+  --base <merge-base> --exact-head exact-head-artifact.json -o evidence.json
+```
+
+Integration evidence:
+
+```sh
+node <resolve-issues>/scripts/combine-and-verify.mjs record-exact-head \
+  --in integration-verdict.json --artifact exact-head-artifact.json
+```
+
+Newly assembled integration verdicts stamp `integrationHeadSha` and start
+`gates.exactHead` at `pending`; they cannot reach `ALIVE` until this command accepts a
+same-SHA artifact. The reduced integration evidence keeps every job conclusion.

package/skills/engineering/resolve-issues/references/fan-out.md

@@ -0,0 +1,33 @@
+# Fan-out phases (Workflow harness)
+
+Two **stages** — and only these two — are fanned out via the `Workflow` harness scripts shipped beside this skill (`workflows/`): the analysis stages in the table below. Everything else stays in the main loop, because the harness is headless (can't hit a human gate) and its agents must be *leaves* (it nests one level only):
+
+- **Produce (step 1)** and **fix (step 3)** write code and can trip the "non-trivial unit lacks approved test criteria → stop and request them" gate — a human touchpoint. They stay in the main loop, spawned per-unit at depth 1 as the loop describes — **one at a time**, since every code-writing spawn works in the run's single checkout (see the scheduling rules); "main loop" means who launches them.
+- **CI** pushes — outward-facing — and the review→fix→re-review loop is stateful against a moving HEAD. Main loop.
+
+What's left for the harness is the no-code, non-interactive, fan-out analysis:
+
+| Stage | Workflow script | Shape | Why it's safe to fan out |
+|---|---|---|---|
+| **Prior-art** (epics) | `workflows/prior-art-scan.workflow.js` | one read-only investigator per unit → routing verdict | Read-only `gh`/`git` queries. Writes no code, opens no PR, asks nothing. |
+| **Independent review** | `workflows/independent-review.workflow.js` | one reviewer per unit's PR, **on the review model** | Read-only adversarial review. **Both independence guarantees hold:** fresh context (new subagent) + model diversity (`opts.model = reviewModel ≠ implementationModel`). |
+
+**Why moving the review to a workflow does *not* break the depth-1 model-diversity rule:** the danger this skill guards against is nesting a *whole orchestrator* that then has to sub-spawn its reviewer (main → resolve-issues-subagent → review = depth 2, capped). A review *workflow* is different — **the main-loop orchestrator launches it directly**, and each review agent is a **leaf** that runs on the review model and never sub-spawns. So the reviewers sit at the single nesting level the harness allows, on a different model than the implementer — exactly the depth-1 sibling guarantee, just fanned out. The script hard-fails without a `reviewModel` and tags every result `independent: false` when `reviewModel === implementationModel`, so a same-model review can never be passed off as real (SKILL.md **guarantee 2** — independent review on a different model).
+
+Both are **opt-in and optional** (running a workflow requires the user to opt into multi-agent orchestration). With one unit, or no opt-in, run prior-art and the review **inline** exactly as the step text describes — identical result, just sequential. The orchestrator scouts the work-list first (the unit roster; per-unit PR refs + prior findings for a re-review) and passes it via the host runner; the scripts don't discover their own inputs. To run one:
+
+```
+Workflow({ scriptPath: "<skillsRoot>/resolve-issues/workflows/<name>.workflow.js", args: {...} })
+```
+
+That generic form applies to both workflows, independent review included.
+
+`<skillsRoot>` is the **absolute** skills directory resolved and recorded by [pre-flight](pre-flight.md) step 0 — a relative `skills/engineering/...` path only resolves inside the skills repo. The same rule applies to every skill path passed *into* a workflow: `independent-review.workflow.js` hard-fails unless `reviewSkillPath` is absolute, because a reviewer that can't read `review-pr/SKILL.md` silently improvises a lookalike review.
+
+## Prior-art scan inputs/outputs
+
+With more than a unit or two, run `prior-art-scan.workflow.js` (one read-only investigator per unit). It returns, per unit: the finding (`merged` / `open-pr` / `partial` / `nothing`), the evidence locators, a recommendation, and where the unit enters the loop (`skip` / `review` / `implement-remaining` / `implement`). Feed those into scheduling; with a single unit, just check inline.
+
+## Review — independent-review inputs/outputs
+
+To review (or re-review) several units' PRs at once, run `independent-review.workflow.js` (one reviewer per unit, each on `reviewModel` via `opts.model`, spawned at `reviewEffort` — the effort of the banked [operating point](model-catalog.md) confirmed for the review slot, defaulting to high). Pass `reviewModel`, `implementationModel`, `reviewSkillPath` (**absolute** — the script rejects a relative one), and per unit: `prRef`, `baseRef`, `contractPath`, its `highRisk` flag (routes the [high-risk reviewer additions](high-risk.md) — hazard hunt + round-1 depth), its own `implementationModel` when it differs from the run-level one (a substitute re-confirmed at spawn time — the diversity guard compares per unit), its `lastReviewedSha` on a re-review when delta scope applies (review-pr § Re-review; omit it to force full scope — high-risk, round 3+, delta outside the original files, or a rebase), and (on a re-review) its `priorFindings` so the reviewer emits the Previous Findings — Resolution Status table. The reviewer computes its own merge-base/range with review-pr's `pr-context.mjs` — no caller-supplied SHA plumbing. A state-machine/concurrency finding carries a durable theme `{ id, kind, contract, stateSpace }` (routine findings may omit `theme`); a recurring theme keeps the same id. The script enforces the diversity guard deterministically. Re-run against the new HEAD each round; the fix step stays in the main loop.

package/skills/engineering/resolve-issues/references/finalization.md

@@ -0,0 +1,68 @@
+# Correctness-only finalization
+
+`run-state.mjs reconcile-contained-unit-prs <slug>` is the pre-finalization transition that can close a delivery-linked unit PR superseded by a merged combined component. It does so only after fresh target ancestry, exact reviewed-head identity, and live component merge-SHA verification. Terminal PRs are recorded no-ops; ambiguous facts leave the PR open.
+
+`run-state.mjs finalize <slug>` remains the only transition that marks a `resolve-issues`
+run complete. It does not trust reconciliation observations: it independently re-fetches and re-verifies the live facts below. A free-form completion object is never evidence: `completionAudit` is rejected by generic writes, validation, and finalization.
+
+## What the transition proves
+
+1. Every implementation unit has one honest typed disposition: `delivered`,
+   `handed-back`, `already-done`, or human `descoped`. Blocked, merge-ready without an
+   outcome, and missing/contradictory evidence fail closed.
+2. Every external-verification, human-decision, and prerequisite unit is **settled**: complete
+   under its #884 protocol, **or** human-`descoped`. Independent code components may deliver
+   earlier, but the whole run does not finalize while one remains pending. Descoping is not
+   restricted by kind — `record-scope-decision` never restricted it, and `external-verification`,
+   the kind that exists for work no agent session can perform, is the one most likely to need it,
+   so refusing a descoped unit here left such a run with no reachable terminal state (#1087). It
+   is not a bypass either: the disposition is re-derived through `terminalDisposition()`, which
+   re-validates the whole scope decision, so a loop-applied, non-human, or delivery-claiming
+   "descope" leaves the unit pending and the run unfinalizable. `finalization.scope` counts
+   `descoped` separately from `complete`, and the handoff names each descoped unit and its reason.
+3. The command freshly fetches `origin/<targetBranch>`. A canonical component delivery contributes one component merge-SHA ancestry claim regardless of member count; legacy unit delivery contributes its historical unit claim. Every claim must be an ancestor of that fetched ref. A merge command or cached boolean is not ancestry proof.
+4. Unit issues and every recorded unit/component PR are read live. Delivered/prior-art
+   claims require terminal GitHub state; delivered component PRs must be merged at the
+   recorded SHA; a `closed-not-planned` human descope must be closed unmerged with the
+   matching decision record. Every returned observation must carry the exact positive
+   integer issue/PR number requested at the boundary. Missing, malformed, or mismatched
+   identities fail the attempt before persistence, and the requested number remains the
+   canonical identity in immutable evidence.
+5. The checkout is restored to `originalBranch` without discarding local changes. The
+   workspace reap then removes only clean, published trees. A failed removal, an unreaped
+   clean tree, an unreadable tree, or preserved unpublished work blocks finalization and is
+   reported without deletion.
+6. The final handoff is rendered from the validated record. It includes delivery, scope,
+   cleanup, deferrals/known debt, and autonomous breaker decisions.
+
+## What the loop owes finalization
+
+These are the loop’s obligations, and finalization cannot repair a missed one. Every `merge-ready` unit carries a terminal `delivery.outcome` — `merged` with a verified `mergedSha`, or `handed-back` quoting the blocking condition; **a unit with neither is reported *undelivered*, never as done**. An epic hands back **one deliverable per [component](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic)**, and its exit gate is the closed-world ensure-coverage **audit** of the delivered tree against its source — the PRD/spec when one exists, **otherwise the epic issue's own body**, which is the spec when nothing else is. **Merge only what `mergeShippable` authorizes, only into `targetBranch`; never promote to production.** Push every unit branch **before** finalization. **Reap the workspaces last** — through `finalize`, after those pushes. **Never `--force` a worktree removal and never delete one by hand**: preserved unpublished work blocks finalization and stays on disk. On a `worktree` run the orchestrator's own checkout is removed separately, after the reap, and only once the finalization record exists.
+
+## What the handoff shows, per unit
+
+PR + branch (epic: one deliverable per [component](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic) — its combined PR, or the merge SHA when `mergeShippable` merged it); the terminal `delivery.outcome`; CI status; the review verdict on the current HEAD with **review model and per-unit implementation model** (showing they differ) and every finding's resolution; the authoritative `contractRevision` SHA + refs, proof HEAD contains it, and `reviewedContractSha` equal to it; the checklist validate result plus any `Unverified`/quarantined rows with dated exits; hazard rows banked; known gaps as tracked issues.
+
+Then the **round profile** from `rounds` — round count and per-round `at`/`scope` where recorded (both optional in `validateRoundLog`) for a delta-vs-full time read, the diff-derived `changedSurfaces` profile (`runtime|tests|verification-harness|evidence|docs|none`), each independent `reviewSubject`, and how many rounds re-raised a theme an earlier round had already named: the numbers that say whether the loop converged or circled. For rounds whose `reviewSubject` is `evidence`, `run-state.mjs evidence-audit <slug>` answers *what they were spent on* and therefore what to repair — read it as [run-state.md](run-state.md) describes, `sameHeadAsPrevious` before the count.
+
+**Epic extras:** the roster, per-component integration verdicts, which components merged vs. handed back, the [decomposition gate](intake.md#intake--scheduling) re-run against the final roster, and the closed-world ensure-coverage audit that is the exit gate.
+
+On success the command writes immutable `finalization` state and prints its `handoff`.
+`run-state.mjs validate <slug>` recomputes the manifest-derived portions and rejects a
+forged or stale record, including nonnumeric or mismatched persisted GitHub identities.
+The complete candidate passes that same validator before the success write. A failed
+attempt leaves no partial finalization, and a corrected rerun remains safe.
+
+## Diagnostics are separate
+
+`run-state.mjs postmortem <slug> [--json]` is an explicit, read-only diagnostic. It does
+not run from `progress` or `finalize`, save a series, authorize completion, require finding
+adjudication, or generate a process issue.
+
+## What the handoff reports, per unit
+
+Moved here from `SKILL.md` when that file was restored to an index. `finalize` generates this from
+validated state — the list below is what to expect in it, and what a reader should check is present.
+
+Per unit, with evidence: PR + branch (epic: **one deliverable per [component](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic)** — its combined PR, or the merge SHA when `mergeShippable` merged it); **the canonical `components[].delivery.outcome` resolved through each member's `deliveryRef` — `merged` with the one verified component `mergedSha`, or `handed-back` with the condition that blocked it; a member with neither is reported *undelivered*, never as done** (older singleton/unit manifests retain the legacy `units[].delivery` read); CI status; the review verdict on the current HEAD with **review model and per-unit implementation model** (showing they differ) and every finding's resolution; the authoritative `contractRevision` SHA + refs, proof that HEAD contains it, and `reviewedContractSha` equal to it; checklist validate result + any `Unverified`/quarantined rows with dated exits; hazard rows banked; the **round profile** from `rounds` (round count and per-round `at`/`scope` where recorded (both optional in `validateRoundLog`) for a delta-vs-full time read, the diff-derived `changedSurfaces` profile (`runtime|tests|verification-harness|evidence|docs|none`) and each independent `reviewSubject`, and how many re-raised a theme an earlier round had already named — the numbers that say whether this loop is converging or circling); **`run-state.mjs evidence-audit <slug>` for rounds whose `reviewSubject` is `evidence`** — not how many, which the round profile already gives, but *what they were spent on* and therefore what to repair: a recurring **screened** class (`stale-locator`, `unrun-gate-row`, `stale-stamp`) means a screen this repo already has was skipped or run without `--diff`, and a recurring unscreened one (`contract-drift`, `checklist-row`) is the named incident a new screen would be added with. **Read its `sameHeadAsPrevious` before you read the count**: an evidence-subject round at the same HEAD as the round before it had no commit between them at all, so it is usually a double-record (one entry per loop *action* rather than per verdict) rather than a round bought on unmoved code — `epic-25-proposal-generator` read as 54% evidence rounds and was 15%. Its repair is `fix-the-recording`, and no screen, existing or new, would ever have caught it; known gaps as tracked issues. Epic extras: the roster, per-component integration verdicts, which components merged vs. handed back, the [decomposition gate](intake.md#intake--scheduling) re-run against the final roster, and a closed-world ensure-coverage **audit** of the delivered tree against the source — the PRD/spec when one exists, **otherwise the epic issue's own body**, which is the spec when nothing else is (that audit is the exit gate). **Merge only what `mergeShippable` authorizes, and only into `targetBranch`; never promote to production.** Push every unit branch before finalization. **Reap the workspaces last** through `finalize`, after those pushes; it restores the recorded branch and invokes the existing evidence-driven reap engine. **Never `--force` a worktree removal and never delete one by hand**: preserved unpublished work blocks finalization and stays on disk. On a `worktree` run, the **orchestrator's own checkout is removed separately, after the reap** and only after the successful finalization record exists.
+

package/skills/engineering/resolve-issues/references/guarantees.md

@@ -0,0 +1,10 @@
+# The four guarantees, in full
+
+The four bars are stated on [SKILL.md](../SKILL.md) and never move; this file is each one's operative detail — what it refuses, what satisfies it, and the state that records it. Each guarantee's incident record: [why.md](why.md#the-four-guarantees).
+
+## The four guarantees
+
+1. **Real tests, honestly green.** Never skip, guard, weaken or `.only` a test to pass; never mock a first-party internal seam or intercept first-party routes in a journey; an assertion against a 404/empty/error page is a defect. A missing precondition is the test's *arrange* step — **seed it**. Flaky → quarantine lane (runs, non-blocking, `Unverified`); obsolete → delete. Gate the net `merge-base...HEAD` diff.
+2. **An independent review that actually ran.** Fresh context **and** a different model than the one that wrote the diff. The reviewer loads `review-pr` and returns its proof artifacts; a review-shaped prose answer does not count.
+3. **The loop exits on a fresh verdict on the current authorization boundary, never on a claim.** "I addressed the findings" is not a terminal state. A unit PASS is terminal for that branch and becomes preserved **preliminary evidence** (its notes become `deferrals[]`, never another round). **Component delivery is authorized separately** ([delivery.md](delivery.md)): movement after its terminal PASS requires a typed `reopenReason: ci-red|head-rewritten|contract-revised|integration-finding|external-review`, a changed matching `ci|head|contract|integration` boundary, and a fresh freeze. A bar the orchestrator may raise after the fact is not a bar.
+4. **Merging requires a recorded human authorization, and only ever targets the integration branch.** That authorization is `mergeShippable`, set only by a human answering pre-flight. With it, an [independently-shippable component](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic) merges into `targetBranch` at its full bar; without it the loop hands components back merge-ready and merges nothing — never to production, which is `resolve-release`'s with its own authorization. Pre-flight *recommends* `autonomous`, but an **unset** field resolves to `supervised`: no recorded answer, no merge.