verified-delivery

name	verified-delivery
description	Implement and deliver an authorized change end to end — verify, open the PR, merge, and confirm post-merge state — using live-state gates, durable interruption handoffs, and live-state-first resumption. Use when a user grants end-to-end delivery authority for a specific change and the work may cross tool-call limits, context exhaustion, worker loss, or session interruptions before the delivery boundary is reached. Do not use for plain fixes with no delivery directive, for granting merge or post-merge authority the user did not grant, or for designing release pipelines (use release-engineering for that).
license	MIT
compatibility	No runtime dependency.

Verified Delivery

Carry an authorized change from implementation through merge and post-merge verification through a sequence of live-state gates. Every gate is verified against the actual state of the repository, PR, CI, and review system before the next step runs, and every gate verdict is bound to the exact head SHA it was verified on. Because hard limits (tool-call budgets, context exhaustion, worker replacement, session interruptions) can end the work before the delivery boundary is reached, this skill defines a durable interruption handoff and a resumption protocol that treats the next re-entry as a resume of the same directive — not a request to restate it.

Authorization boundary

Delivery proceeds only under an explicit user directive that names the change and the gates it authorizes. Never infer permission from context, tone, or a partial handoff.

Confirm the target, scope, and rollback path before acting. Read-only discovery may proceed without confirmation.

Apply this confirmation before the first mutation, including on resumption. The target names the repository and PR when one exists, the scope names the next authorized gated steps, and the rollback path states how the next mutation can be reversed or contained. A handoff records this confirmation; it does not widen it.

• The directive states which gated steps are authorized (for example: open a PR, merge when CI is green and reviews are satisfied, verify post-merge).
• Steps outside the stated boundary stop at their gate with the exact missing authorization reported. Asking the user for an explicit new decision is the correct response to a gap; acting anyway is not.
• The authorization travels with the work: it is restated verbatim in the interruption handoff (below) so a resumed session inherits the same boundary, never a wider one.

Preserved boundaries at every gate:

• Merge boundary — merge only when merge is explicitly authorized and the CI and review gates pass on the exact head being merged.
• Review boundary — address review feedback inside a bounded loop; never force past unresolved review objections.
• Security boundary — security findings from CI or review are gates, not warnings; they are never bypassed, weakened, or retried until clean by suppression.
• Exact-head boundary — all gate evidence binds to the exact head SHA. A moved head invalidates prior evidence until it is re-verified on the new head.
• Non-convergence boundary — after three non-converging fix or review passes at any gate, stop and report the evidence.
• Post-merge verification boundary — the delivery is not complete until the merged state is verified after the merge.

Delivery gates

Run the gates in order. At each gate, check live state first, then act, then record evidence bound to the current head SHA.

1. Change ready — implementation complete and local verification passes at the working head.
2. PR open — the PR exists and its identity and head SHA are recorded.
3. CI green — CI passes on the exact PR head SHA.
4. Review satisfied — review requirements of the repository's policy are met on the exact head SHA.
5. Merge — only when gates 3 and 4 hold on the exact head and merge is within the granted authorization.
6. Post-merge verification — the merged state is confirmed (branch, PR status, post-merge checks) before any completion claim.

Interruption handoff

Any ending — session end, turn end, worker shutdown, or an approaching hard limit — while a delivery directive is still authorized and gated steps remain must first record a durable handoff. Ending with remaining steps and no durable handoff is a protocol failure, even if the remaining steps are reported clearly. A remaining-steps report is never terminal success for an end-to-end directive.

The handoff is machine-readable JSON stored durably: by default as a file at .verified-delivery/handoff.json in the repository working tree, excluded locally from Git and checked as untracked before every commit; alternatively in a fenced machine-readable block in the PR description after confirming that external disclosure and its rollback path, or in host-provided durable storage when configured. The record names its own store. Durability means the next re-entry can find and read it without user assistance.

Required fields — schema (handoff schema version), status (open or closed), store (durable location), directive (verbatim user directive), authorization_boundary (gates authorized, and anything explicitly out of scope), repository (remote identity), pull_request (PR identity or null), branch (delivery branch), head_sha (head at handoff time), completed_steps (gates done, with SHA-bound evidence), pending_steps (next authorized gated steps in order), watchers (active watcher, process, or worker identifiers, or empty), stop_reason (observed interruption class), and updated_at. The full field schema, durability rules, and worked examples are in references/interruption-handoff.md.

Resumption on re-entry

Re-entry means a new session, turn, or worker touching the repository while a handoff with status: open exists. Scan the documented store locations at re-entry. An open handoff makes the re-entry a resume of the recorded directive: do not ask the user to restate or repeat the instruction, and do not re-plan from scratch.

First action: read-only live-state verification. No mutation before it completes.

1. Repository — the remote matches the handoff's repository; branch state is identified.
2. PR — it exists, is open, and its head SHA is compared with the handoff's head_sha.
3. CI — status on the exact head.
4. Reviews — state against the repository's policy on the exact head.
5. Watchers — whether recorded watchers, processes, or workers are still alive; never spawn a duplicate of a live one.

Then continue with the next already-authorized gated step. Gate evidence recorded in the handoff stays valid only for the head it was verified on. If the head moved (new commits, rebase, force push), reconcile first: fetch, re-verify CI and review on the new head, update the handoff's head_sha, and only then continue. Mutations — commits, pushes, merges, comments — happen only after verification.

Stop at the boundary

Stop and report the exact reason, taking no further action, when:

• there is no directive and no open handoff (treat the input as a fresh request, not a resume);
• the handoff is corrupt — unparseable, missing required fields, or internally inconsistent;
• the handoff is stale — the PR was closed without the recorded change, rolled back, merged with a conflicting head, the repository does not match, or the recorded authorization no longer applies; a matching completed merge with authorized post-merge verification pending is reconciled and resumed;
• authorization for the next step is absent or ambiguous;
• live state is ambiguous — a gate result or the merge state cannot be determined.

Never infer permission from a partial or stale handoff. The stop report states what was found, what could not be verified, and the exact reason for stopping.

Closing an end-to-end directive

• Delivery boundary reached — close the handoff (status: closed) and report the SHA-bound evidence for the boundary.
• Steps remain — record the handoff first, then close with a message that names the handoff store and the explicit next trigger: the next re-entry resumes the directive. This is the only acceptable way to end with steps outstanding.

Runtime honesty

No skill content can force a host runtime to continue past a hard tool-call or context limit, and this protocol never promises that. What it guarantees is observable behavior: a durable handoff written before the limit lands, and a resumption path that the next re-entry can follow from verified live state. Do not claim that the runtime will resume automatically — the next trigger is an explicit re-entry.

Completion and exit conditions

Exit when one of these holds:

• the delivery boundary is reached, the handoff is closed, and the evidence is reported; or
• work stopped at a boundary, the exact reason is reported, and — when steps remain — an open durable handoff exists.

After three non-converging passes at any gate, stop and report rather than looping.

When not to use

Do not use this skill for a plain fix, refactor, or review that carries no end-to-end delivery directive — a normal change workflow is the nearest alternative. Do not use it to design release pipelines, trains, or progressive-delivery mechanics — use release-engineering. Do not use it to manufacture authority: this skill executes only what the user explicitly granted.

Related skills

• release-engineering — release pipeline mechanics, progressive delivery, and rollback planning beyond a single authorized change.
• verification-methodology — evidence and verdict standards for the live-state checks at each gate.

Reference files

Reference	When to load
references/interruption-handoff.md	You are recording, locating, validating, or reconciling an interruption handoff — field schema, durability rules, and worked examples