@1aboveio/skills 0.10.0

package/skills/engineering/implement-and-pr/references/evidence-rules.md

@@ -0,0 +1,39 @@
+# Evidence rules — what a terminal round attests, and how
+
+Read when a round is the one that requests the terminal review. Intermediate fix rounds owe the *fixes* and their RED/GREEN plus green screens, not this. The screens themselves (`scan-diff` findings channel, `coverage-checklist validate`) run every round and are stated in SKILL.md's gate — they are not deferred here.
+
+## Evidence Rules
+
+Capture evidence in the PR body:
+
+- Local test commands run and pass/fail result.
+- Runtime smoke result: the repo run/start command (or `e2e-test` smoke run for a browser surface) and the observed happy-path output (boot log, HTTP status + body snippet, exit code, screenshot/trace for a route). Captured as the runtime-smoke Coverage Checklist row with the command as locator.
+- Golden-path smoke verdict (when a critical journey is touched): `smoke-verdict.json` at **ALIVE**, with the manifest path and `smoke-results.json` evidence — proof the do-not-ship journeys are live against the real app (the per-PR golden-path floor, `ensure-coverage` gate 8).
+- In TDD mode, RED/GREEN command evidence for each behavior slice.
+- CI link/status once available.
+- Test files and test names added or updated.
+- Logs, screenshots, traces, or API responses for UI/async/manual checks.
+- For a `presentation:visual` surface: the durable committed-baseline link + the ephemeral diff-artifact URL posted by `e2e-test`'s evidence step (`post-visual-evidence.mjs`).
+- Any known failure that remains unresolved.
+
+Never claim tests passed without command output or CI evidence. If tests cannot run locally, state the blocker and rely on CI only if acceptable for the repo.
+
+**Generate the volatile evidence; never transcribe it.** Scan counts, the exact-head CI job table, SHAs, and the docs-only-tail proof come from `ensure-coverage/scripts/evidence-block.mjs collect --base <merge-base> [--since <implementation sha> --source <paths>]`, which stamps them with the HEAD they describe; repo-specific suite results are fed in with `--ingest` and carry the same stamp. Reference the generated block from the contract instead of restating its numbers, and `evidence-block.mjs validate` it — a block stamped at anything but the current HEAD fails, so staleness is caught by a command rather than by a reviewer. Reuse of a prior probe must be `reused: true` with a note and cannot be `Pass`; a skipped CI job is reported skipped, never passed. (Named incident: a hand-written attestation claiming `leadCount=0` for a diff whose real scan had 1,749 leads — a full review round spent on a transcription error.)
+
+**Generate it *last within the round that ships it*, and re-generate after any later commit — the stamp is the whole mechanism.** `validate` passes only while the stamp equals current HEAD, so "collect, then fix a lint error, then push" ships a stale block just as surely as transcribing one by hand. Make the block the final act before that push; if anything lands after it, re-collect. Don't rely on remembering: the **`evidence-block` CI job** (`e2e-test/assets/ci-gates.*`, audited by `ci-audit`) re-runs `validate` on every push, including the push that broke the stamp — wire it in any repo running this loop, because an instruction to do something last is the kind of instruction a fix round breaks silently.
+
+**"Last" is scoped to the round, not to every push.** Read without that scope this rule and the terminal-round rule below contradict each other: one says re-generate after *any* commit, the other says produce the attestation *once* at the end, and a producer cannot satisfy both — whether a round is terminal is only knowable *after* the verdict and CI land, i.e. after the producer has already finished. The resolution is that only the round which actually requests the terminal review owes a stamped block; intermediate rounds owe green screens and no attestation, so there is no stamp for a later commit to invalidate. Where a repo runs the `evidence-block` CI job, it is asserting the stamp *of whatever block is present* — it does not oblige an intermediate round to produce one.
+
+**A design input's citations must resolve.** When the unit carries an ADR/design/test-criteria doc, verify each cited artifact actually exists at the commit you are citing (`git cat-file -e <sha>:<path>`) before you build against it or list it in the contract — under `resolve-issues` the mechanized form is `contract-revision.mjs check` ([its contract-revision gate](../../resolve-issues/references/intake.md#intake--scheduling)), which fails closed with exit 2 on a path-shaped ref that is not in the tree. A citation to a file nobody wrote reads as a contract but supplies no contract, and the reviewer finds nothing to verify against. (Named incident: a unit that spent a review round correcting contract citations pointing at two design files that did not exist.)
+
+**Resolving is not conforming — a design source owes a parity claim, not a citation.** The rule above proves the artifact *exists*; it says nothing about whether the code matches it, and a citation that resolves perfectly is exactly what a drifted implementation looks like. So when the cited artifact is a **design source** (prototype branch/path, mockup, a doc that fixes layout), the contract owes one more line: the `design-parity.mjs validate <manifest> --observed <results.json>` verdict, plus the side-by-side render of source and deliverable at the floor viewports. Cite the manifest by path, never by row range — the same stable-identity rule as tests. (Named incident, fmm-express #521: the issue cited the settled prototype by exact branch **and** file path, the citation resolved, and the page still shipped with the wrong measure, a card plane the design did not have, a lost responsive type step, and a secondary field at primary weight — four rounds of user correction, one image rendered in the whole session, and it was the user's. See [ensure-coverage → presentation/axis.md](../../ensure-coverage/references/presentation/axis.md) → `presentation:fidelity`.)
+
+**Cite tests by stable identity, never by line range.** `@covers` tags, test names, and file paths survive an edit; `foo.integration.test.ts:252-274` goes stale the moment anything above line 252 moves — and under `resolve-issues` the fix rounds edit exactly those files, so every stale citation returns as a review finding. Cite the test name or tag and let the reader search.
+
+**Exact-head evidence is a terminal-round obligation, not a per-round one.** Under `resolve-issues`, intermediate fix rounds owe the *fixes* and their RED/GREEN, not a fresh whole-PR attestation: re-deriving exact-head scans, exact-head CI tables, and an immutable head attestation on every round costs a full document rewrite that the next commit invalidates within the hour, and each rewrite is a fresh chance to overclaim. Refresh the durable claims when a claim changes; produce the exact-head evidence once, when the unit is otherwise ready to exit. (Named incident: five docs-only "record round N evidence" commits on one PR, each invalidated by the next, generating evidence-fidelity findings for three consecutive rounds.)
+
+**What this does NOT relax — the line the whole rule depends on.** Every mechanized *screen* still runs on every round, and a red one still blocks the handoff exactly as before: `scan-diff.mjs`'s findings channel must be empty, `coverage-checklist.mjs validate` must pass. Those cost seconds and each prevents a wasted review round, so they were never the expense. What moves is the **attestation** — the pasted proof block, the exact-head CI table, the immutable head stamp — which is a document, costs a rewrite, and is void the moment anything else lands.
+
+The distinction is worth holding precisely, because collapsing it in the other direction is how this becomes a route to dishonest green: "exact-head evidence is terminal-round-only" must never be read as "the screens are terminal-round-only." A reviewer must still be unable to receive a PR whose findings channel is non-empty, on any round.
+
+**And "terminal-round-only" is not "unchecked".** On the round that requests the terminal review, `resolve-issues` re-runs `evidence-block.mjs validate` before it spawns the reviewer — so the attestation is owed once *and verified on the round it is owed*, rather than owed once and first read by the reviewer. Without that, the retiming would have moved the stamp off every round and onto no round: a stale one would surface as an evidence finding on the terminal review, costing the fix plus a fresh re-review to exit. Producing it green here is what makes that check cost nothing.

package/skills/engineering/implement-and-pr/references/incremental-plan.md

@@ -0,0 +1,16 @@
+# The incremental plan — a work list that outlives the run
+
+Read when the unit has several slices, or when resuming a producer spawn that died mid-flight. The rule that matters most is in SKILL.md: point a replacement spawn at the same artifact so it resumes rather than restarts.
+
+## Incremental plan: the work list outlives the run
+
+The code you write is already durable — it is in git. What dies with the run is everything *around* it: which ACs are done, which slice was mid-flight, what you verified, what you deliberately deferred. A replacement producer that has the branch but not that state re-derives the plan from scratch and often re-implements what is already committed.
+
+So write the step-4 map to a durable file before implementing, and update it as each slice lands — one line per AC/obligation, its slice, its state (`todo` / `in-progress` / `done`), and once done, the `file:line` of the test that proves it. That file is a work list, not a narrative: if updating it feels like writing prose, it is too detailed.
+
+Two rules, the same ones the review artifact carries:
+
+- **Done means proven, not written.** A slice moves to `done` when its test runs and asserts the behavior — not when the code compiles. An honest `in-progress` left behind by a dead run is useful; a `done` that was only aspirational sends the next run past the gap.
+- **Match the plan to the branch before trusting it.** On resume, reconcile the file against `git log` and the actual tree. The plan is a cache of intent and can be stale — commits are the truth. Where they disagree, the tree wins and the plan gets corrected.
+
+Keep it cheap. A routine single-AC unit needs three lines, and inventing ceremony for one is the over-triggering failure, not diligence. It earns its keep on multi-slice work and on anything that has already died once.

package/skills/engineering/implement-and-pr/references/self-review.md

@@ -0,0 +1,23 @@
+# The adversarial self-review pass
+
+**Trigger: a high-risk diff** — auth/authz/token/session, money/tax/pricing, tenancy/org-scope,
+DB migration/schema (#471). It is no longer a routine obligation: an independent review does the
+same job with a different model and fresh context, so on a routine diff this pass bought "catch it
+one round earlier", not "catch what nothing else would".
+
+**That substitution depends on a review actually being required before merge.** Where it is not —
+and consumer repos do not inherit the skills-authoring repo's config — nothing replaces this pass, and the
+scoping should be revisited. The evidence that argued the other way is kept in SKILL.md rather
+than deleted, because it is the argument for revisiting.
+
+## Self-Review Before Handoff (adversarial pass)
+
+Coverage gates prove the tests exist and are honest; they do **not** prove the code is *correct*. The recurring reason a fresh PR fails independent review is a **domain-semantic bug the happy-path implementer never thought to attack** — an auth check that fails open, an FX conversion in the wrong direction, a tenant scope that leaks across orgs. These pass CI and the coverage gate; a review round is expensive — **catch your own before handoff.** Before opening/updating the PR, run one **adversarial self-review of the net diff** — the same four axes `review-pr` will use (read review-pr's SKILL.md for the method, same skills root). This is a self-check on your *own* model, **not** the independent review, and never satisfies it.
+
+- **Code correctness** — try to *break* each new branch with the value the app actually produces at runtime (not the convenient fixture): boundary inputs, empty/legacy/migrated data, the failure path, the second concurrent caller. Produce the counterexample, not an opinion.
+- **State-space correctness** — for every state-machine/concurrency finding, write down the governing contract, enumerate the complete `state × child/task kind` matrix, and check the adjacent states that the same rule governs. A self-review that only repeats the reported counterexample is incomplete; record the matrix and each test/evidence locator in the fix-round artifact.
+- **Spec outcome** — for each AC, confirm the *user-visible outcome for the real input*, not the presence of the right call/component/constant.
+- **Coverage honesty** — would each cited test go **red** if the behavior were removed? A test that passes for the wrong reason (a fixture that early-returns before the code runs, an assertion pinned to a proxy value the real provider never emits) is vacuous evidence — fix it now, not in review. **For high-risk ACs and bug-fix regression tests, don't reason it — run it: the fails-if-broken spot-check.** Actually break the behavior (revert the guard, flip the predicate, delete the bound), capture the cited test going **red**, restore, capture green — this catches the fixture that never contained the discriminating row. Record each spot-check (what you broke, the red output) in the Self-Review block; the vacuous-test class is the single largest cause of NEEDS_CHANGES.
+- **Repo domain hazards (high-risk surfaces).** A diff touching **auth/authz/token, money/tax, tenancy/org-scope, or a DB migration** is hunted against the [domain-hazards catalog](../../review-pr/references/domain-hazards.md) **and** the repo hazards file — `docs/domain-hazards.md`, via the `Domain hazards` index in `AGENTS.md`/`CLAUDE.md` (location/schema/admission: the catalog's [repo hazards file section](../../review-pr/references/domain-hazards.md#the-repo-hazards-file-location-schema-lifecycle)). No hazards file + a high-risk surface touched → **seed it**: create `docs/domain-hazards.md` with the rows you actually hunted (repo-specific values, `What to prove` + `Source`) plus the index pointer; a bug caught in this self-review earns its row. Seeding is in-scope by declaration, never "unrelated changes."
+
+**Proof-of-execution:** a short **Self-Review** block in the PR body — the axes checked, each high-risk surface with its hazard items cleared (or "seeded `docs/domain-hazards.md` with rows X, Y"), and any counterexample found and fixed. A high-risk diff whose PR carries no Self-Review block is a producer step that did not run; `review-pr` treats it as such. This does not replace the independent review — it stops the cheap-to-catch class from consuming a review round.

package/skills/engineering/implement-and-pr/references/tdd-mode.md

@@ -0,0 +1,18 @@
+# TDD mode — the red-green discipline for criteria-backed work
+
+Read when the work item carries acceptance criteria and TDD mode is active. Characterization-test detail is canonical in `ensure-coverage`; this file is the loop and its evidence.
+
+## TDD Mode
+
+Use TDD mode when the source work item is a PRD, design document, feature spec, bug brief, or approved test criteria, or when the user asks for test-first work. Skip only for clearly trivial docs/config changes, purely generated code, throwaway prototypes, or an explicit approved exception (generated code may still owe generator-level/consumer behavior tests; behavior-affecting config may still owe behavior/integration tests).
+
+Apply the `tdd` skill for the red-green-refactor loop itself, and `ensure-coverage` for *what each test must assert* (required level per AC; mock boundary — real internals, faked externals). This skill adds only what those two don't own:
+
+- Map each AC **and each changed-surface obligation** to its own slice — no required behavior, including a surface with no AC, goes without a failing-test-first slice.
+- Capture RED/GREEN evidence per slice for the Review Contract: RED proves the test fails for the intended reason (not a syntax/setup error); GREEN proves the minimal implementation passes it.
+- For bug fixes, the first slice is a failing test that reproduces the bug.
+- **Characterize before you change.** A slice that *edits or removes* existing behavior starts with the inverse of TDD: a **characterization test that pins the current behavior and passes on the pre-change tree**, tagged `// @characterizes <surface>`; then change and confirm it still passes — unless a declared intended behavior change, in which case update the test so the assertion delta is visible in the diff. Capture the pre-change pass as evidence. Waive only with a cited pre-existing behavior test that still passes unchanged, or a trivial/generated/non-behavioral edit. Full doctrine: `ensure-coverage` → [depth/characterization.md](../../ensure-coverage/references/depth/characterization.md); the reviewer raises the `modifies-existing-behavior` lead and resolves the `depth.characterization` row against your evidence.
+- **Consolidating twin / moved pure modules: matrix completeness vs origin base, not only body byte-identity** (epic-876 / #941). When two app-local modules are collapsed into `shared/`, body identity proves the *implementation* moved; it does **not** prove the *test matrix* survived. Diff each pre-move suite's cases (`origin/<base>:…/*.test.ts`) row-by-row into the authoritative shared suite. A dropped case (e.g. `Refund succeeded → neutral` present on both twins, missing after consolidate) is product-assertion weakening even when every exported function body is byte-identical. The independent model review can miss this; an external bot review may not — treat that as `external-review` reopen, not as optional polish.
+- If RED cannot be produced because the behavior already exists, state that in evidence and map the existing passing test to the AC (subject to reviewer attestation) or move on.
+
+For a **high-risk unit's** state-machine/concurrency finding, the fix commit also carries the contract-complete round record — see [Fix rounds](../SKILL.md#fix-rounds). On a routine lean-lane fix, the cause-fix plus its test is the whole *edit* obligation; re-verifying the surface's own neighborhood is owed on every fix round, per that same section.

package/skills/engineering/resolve-issues/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/engineering/resolve-issues/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: resolve-issues
+description: "Drive GitHub issues (single or epic) to merge-ready PRs: implement → e2e → independent review on a different model ∥ CI → fix, looped until the review passes; an epic is assembled, integration-verified, and delivered one PR per independently-shippable component. Orchestrates implement-and-pr, e2e-test, ensure-coverage, review-pr, smoke. NOT one implement+PR alone, review alone, or releasing to production (resolve-release)."
+dependencies:
+  - implement-and-pr
+  - e2e-test
+  - ensure-coverage
+  - review-pr
+  - smoke
+---
+
+# Resolve issues (produce → review ∥ CI → fix, looped)
+
+Drive GitHub issues to **merge-ready PR(s)**. You orchestrate: schedule spawns, run the loop, enforce the guarantees below. One issue or an epic is the same pipeline — normalize the input to a `units[]` list (a plain issue is one unit, an epic one per sub-issue) and loop over it.
+
+At intake, classify every unit as `implementation`, `external-verification`,
+`human-decision`, or `prerequisite` with `scripts/unit-kind.mjs`. The same intake
+classifies evidence/authorization lifecycle semantics from declared scope and changed
+surfaces, deny-by-default; classified implementation work must carry a valid
+`evidenceLifecycleContract` before `spawn-contract` admits it. Only confirmed
+`implementation` units enter the produce/review/CI/delivery loop; other kinds retain
+their own completion protocols and remain separate in progress reporting.
+
+## The four guarantees (everything here serves one of these)
+
+A step that serves none of these does not belong in this skill — see [The removal path](#the-removal-path-keep-this-skill-small). Each guarantee's incident record: [references/why.md](references/why.md#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; assertions against 404/empty/error pages are defects. A missing precondition is the test's *arrange* step — **seed it**. Un-sandboxable/flaky → quarantine lane (runs, non-blocking, `Unverified`); obsolete → delete. Diff-discipline: gate the net `merge-base...HEAD` diff; pre-existing issues are notes.
+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 prose review-shaped 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 review PASS is terminal for that unit branch and becomes preserved **preliminary evidence**; notes inside it become `deferrals[]`, never another unit round. Component delivery is authorized separately: progressively assemble those passed unit heads, freeze one complete clean candidate, then run one terminal exact-head integrated review + CI + smoke whose `authorizationBoundary` is the component HEAD. Any movement after that 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 + terminal authorization. (`external-review` is the epic-876 shape: independent PASS, then a non-self `CHANGES_REQUESTED` naming a real AC gap — not a note-chase; boundary kind is still `head`.) 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.** The authorization is `mergeShippable` on the run manifest, and the *only* thing that sets it is a human answering pre-flight — the recommended `autonomous` level turns it on, `supervised` leaves it off, and an explicit field wins over either. With it, an [independently-shippable component](references/deliverables.md#deliverables-the-shippable-component-not-the-whole-epic) merges into `targetBranch` (e.g. `dev`) at its full bar; without it the loop hands components back merge-ready with evidence and merges nothing. Never to production, which stays `resolve-release`'s with its own authorization.
+
+   **Two different things are called "the default" around this field, and conflating them is how the guarantee gets read backwards.** What pre-flight *recommends* to a human who is present is `autonomous` (authorization on). What an *unset* field resolves to, on a manifest nobody was ever asked about, is `supervised` (authorization off) — the fail-safe, because a recommendation may change what a human is offered but must never change what silence already meant. This guarantee rests on the second: no recorded answer, no merge.
+
+## How to invoke me
+
+**Main loop only — never nested in a subagent. All spawns at depth 1, launched by you — and you coordinate, never implement**, single-issue runs included. Why both halves matter: [references/why.md](references/why.md#main-loop-only-and-the-spawn-contract). Be a **thin scheduler**: every heavy step runs in a spawn that returns a compact, schema'd result (verdict + `file:line` pointers + PR ref, never a transcript); durable state lives in the [run manifest](references/run-state.md). **Waiting is not a foreground activity either** — an enqueued PR is watched by one launch of [`watch-delivery.mjs`](scripts/watch-delivery.mjs), not a poll loop that spends a turn per check.
+
+**The leaf-spawn contract (every spawn, both steps).** A spawned agent does not inherit your loaded skills — everything it must know has to be *in the spawn*, and each clause fails **silently** when omitted. So **render it, don't compose it: [`run-state.mjs spawn-contract <slug> <unit> --kind producer|fix|review`](scripts/run-state.mjs)** fills every clause from state and prints a block to paste (exit 4 = state is missing a clause; fix the state). A composed contract is written once per run and then repeated — measured, it decays rather than being re-derived, which is how gate flags go missing. All five clauses in full: [references/spawn-contract.md](references/spawn-contract.md). → [why](references/why.md#the-spawn-contract-is-rendered-not-composed)
+
+**(e) Pass the working directory** is the clause worth restating here: the *unit's own* `units[].workspacePath`, never the orchestrator's checkout. A spawn inherits *your* cwd otherwise, so an unset one quietly writes into the tree you are coordinating from — the workspace is recorded, reported, and doing nothing. Every code-writing spawn, every round; and a fix round gets the **same** path its producer used, so it resumes rather than reinstalls.
+
+**A spawn that dies mid-flight leaves a partial, and the partial beats a clean slate** — point the replacement at the same path so it resumes. But a partial is **never** proof: `status: in-progress` counts exactly as missing for every gate, and the response is a re-spawn, not an exit.
+
+**Fan-out (opt-in, Workflow harness):** only read-only/advisory stages — prior-art and independent review — via `workflows/`; everything that writes code or hits a human gate stays in the main loop ([references/fan-out.md](references/fan-out.md)). An epic's *implementers* run as plain depth-1 spawns regardless, concurrently up to the in-flight cap, each in its own unit's workspace.
+
+## Pre-flight (once, before intake — never mid-run)
+
+**Before creating or resuming a run, use [`run-state.mjs init|resume`](scripts/run-state.mjs).** That shared lifecycle boundary runs `engineering-runtime`'s read-only coherence verifier first; an incoherent, unavailable or malformed verdict fails closed with findings and a pinned repair recipe, and never runs the repair itself.
+
+**Then read [references/pre-flight.md](references/pre-flight.md) and run its seven steps (0–6)** — it owns the procedure and every non-negotiable in it. Four rules decide whether the rest of the run means anything, so they are named here too:
+
+- **Both model slots are filled individually by the human**, each as an operating point (a model *and* its banked effort), with alternates shown. **`reviewer ≠ implementer`** is hard — it is what makes guarantee 2 an independent review rather than a second opinion from the same blind spots.
+- **Probe, never assume, the merge path** — `deliveryMode`, `queueProvider`, and above all **`enqueueTrigger`**: on a repo that auto-merges once conditions hold, *posting the review verdict as an approval **is** the merge*. Ask [`run-state.mjs approval-gate <slug> [componentId]`](scripts/run-state.mjs) before any verdict reaches GitHub. → [why](references/why.md#the-enqueue-trigger)
+- **`autonomy` is one ask that subsumes `mergeShippable`** (guarantee 4). Ask the manifest what it resolved to — `run-state.mjs autonomy <slug>` — never re-derive it from prose. No level lifts the design gate, the breaker's `descope`, or its round ceiling.
+- **No silent fallback:** read back the model every spawn actually ran on and record it per unit. A reviewer read-back ≠ the confirmed review model means the verdict does not count.
+
+## Routing (read this first)
+
+**This file is an index, and must stay one** — a truncated skill silently becomes a shorter skill and nothing warns you. The doctrine lives in `references/`, one file per phase.
+
+| Phase | Read | The rule you must not miss |
+|---|---|---|
+| Know the bar any step must serve | [references/guarantees.md](references/guarantees.md) | The four guarantees in full. |
+| **Once, before intake** — pre-flight | [references/pre-flight.md](references/pre-flight.md) | Seven steps, **once**, before intake, never mid-run. |
+| Turn issues into scheduled units | [references/intake.md](references/intake.md) | A prerequisite artifact is **not a unit**; schedule against [interference](references/interference.md), not dependency order alone. |
+| Decide what runs next | [references/interference.md](references/interference.md) | **`runnable <slug>` is the scheduler — ask it at every milestone** and spawn what it names. The bar is *pushed*, never *merged*; `inFlightCap` is 4 on every repo. |
+| Run a unit: produce → review ∥ CI → fix | [references/loop.md](references/loop.md) | **Review on a different model than the implementer**, same breath as CI, **same HEAD**. A PASS is preliminary component evidence — **record it with typed `reviewSubject` + `authorizationBoundary`, then feed `record-component-candidate`. The log is append-only: a legacy-shape round can never become component evidence.** |
+| Deliver a merge-ready component | [references/deliverables.md](references/deliverables.md) | One PR per **independently-shippable component** — an epic is not one PR. |
+| Enqueue, watch, route a dequeue | [references/delivery.md](references/delivery.md) | A watch observes a **progression**, not a state. Never hand-roll a watcher. |
+| Preserve terminal facts while coherence blocks a transition | [references/terminal-evidence-journal.md](references/terminal-evidence-journal.md) | Journal append is evidence only; reconciliation revalidates coherence and live facts before one state transition. |
+| Persist / resume run state | [references/run-state.md](references/run-state.md) | Durable state lives in the manifest, not your context. |
+| Reconcile superseded unit PRs, then finalize | [references/finalization.md](references/finalization.md) | Run the pre-finalization `reconcile-contained-unit-prs` operation `next` emits for delivered combined components. **`finalize <slug>` remains the sole completion transition** — fails closed on dispositions, live ancestry/GitHub state, branch restoration and cleanup, then renders the handoff. |
+
+**`references/why.md` is not on this list, and never is.** It is the archive — the incident behind each rule — read when you **edit** this skill, never while running it. The `→ [why]` citations are provenance, not steps: every rule you need is stated where the rule is.
+
+
+The four guarantees, the spawn contract, the step map and the definition of done
+stay on this page: a reader who takes nothing else from this skill should still
+take those.
+
+## The four guarantees (everything here serves one of these)
+
+A step that serves none of these does not belong in this skill ([the removal path](#the-removal-path-keep-this-skill-small)). Each bar in full — what it refuses, what satisfies it, the state that records it — is [references/guarantees.md](references/guarantees.md); each one's incident record is [references/why.md](references/why.md#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.
+2. **An independent review that actually ran.** Fresh context **and** a different model than the one that wrote the diff, loading `review-pr` and returning its proof artifacts.
+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, and a bar the orchestrator may raise after the fact is not a bar.
+4. **Merging requires a recorded human authorization** (`mergeShippable`, set only by a human answering pre-flight) **and only ever targets the integration branch** — never production, which is `resolve-release`'s. An **unset** field resolves to `supervised`: no recorded answer, no merge.
+
+## How to invoke me
+
+**Main loop only — never nested in a subagent. All spawns at depth 1, launched by you — and you coordinate, never implement**, single-issue runs included. Be a **thin scheduler**: every heavy step runs in a spawn returning a compact schema'd result (verdict + `file:line` + PR ref, never a transcript), durable state lives in the [run manifest](references/run-state.md), and **waiting is not foreground work** — an enqueued PR gets one launch of [`watch-delivery.mjs`](scripts/watch-delivery.mjs), never a poll loop.
+
+**The leaf-spawn contract (every spawn, both steps).** A spawned agent inherits none of your loaded skills, and each clause fails **silently** when omitted. **Render it, don't compose it — [`run-state.mjs spawn-contract <slug> <unit> --kind producer|fix|review`](scripts/run-state.mjs) fills every clause from state and prints a block to paste** (exit 4 = state is missing a clause; fix the state): a composed contract decays across a run. Each clause in full, with its failure mode: [references/spawn-contract.md](references/spawn-contract.md).
+
+- **(a) Read the skill** — `<skillsRoot>/<skill>/SKILL.md`, **absolute**, resolved at [pre-flight](references/pre-flight.md) step 0.
+- **(b) Name the proof** — an artifact the next step verifies; output without it did not run the skill.
+- **(c) Use the harness's own agent primitive** — one whose result returns *into this session as a value*. A launch with no result channel back (detached job, background CLI, queued task) does not qualify.
+- **(d) Pass the model *and* its effort** — `models.<slot>` + `models.<slot>Effort` (absent = `high`). A slot is an operating point, not a model.
+- **(e) Pass the working directory** — the **unit's own** `units[].workspacePath`, never yours; unset, the spawn inherits *your* cwd and writes into the tree you coordinate from. Every code-writing spawn, every round — and a fix round gets the **same** path its producer used.
+
+**A spawn that dies mid-flight leaves a partial, and the partial beats a clean slate** — point the replacement at the same path. But a partial is **never** proof: `status: in-progress` counts as missing for every gate.
+
+**Fan-out (opt-in, Workflow harness):** read-only/advisory stages only — prior-art and independent review — via `workflows/`; anything that writes code or hits a human gate stays in the main loop ([references/fan-out.md](references/fan-out.md)). An epic's *implementers* are plain depth-1 spawns either way, concurrent up to the in-flight cap, each in its own unit's workspace.
+
+## Pre-flight (once, before intake — never mid-run)
+
+**Before creating or resuming a run, use [`run-state.mjs init|resume`](scripts/run-state.mjs).** That lifecycle boundary runs `engineering-runtime`'s read-only Workflow coherence verifier first: an incoherent, unavailable or malformed verdict fails closed with structured findings and a generated repair recipe it never executes. Inspection commands stay available for diagnosis.
+
+Read [references/pre-flight.md](references/pre-flight.md) and run its seven steps (0-6) — **once**, before intake, never mid-run. One neutral question batch through [`scripts/preflight-questions.mjs`](scripts/preflight-questions.mjs); invoke only the calls it plans; record the completed patch atomically (a cancelled gate records nothing). The non-negotiables it elaborates rather than replaces:
+
+- **Models** — the **implementer** is asked with alternates shown; the **reviewer is filled from the ranking, never asked**, and stated in the gate. **Reviewer ≠ implementer** is hard; a slot is an **operating point** (model + banked `models.<slot>Effort`). **No silent fallback:** read back the model each spawn ran on (`units[].implementationModel` when it differs) — a reviewer read-back ≠ the confirmed model voids the verdict for guarantee 2.
+- **Everything else is probed, never assumed** — `targetBranch` from fetched remote heads; `deliveryMode` + `queueProvider` + `enqueueTrigger` from [`detect-delivery-mode.mjs`](scripts/detect-delivery-mode.mjs), UNKNOWN being a human ask; `autonomy` one ask recommending `autonomous`, subsuming `mergeShippable`, lifting neither the design gate nor the breaker's `descope` or ceiling. Where a repo auto-merges on its conditions, **posting the verdict as an approval *is* the merge** — ask [`run-state.mjs approval-gate <slug> [componentId]`](scripts/run-state.mjs) first.
+- **Design first** — pre-flight **skims for units that already owe a design and hands them back** before anything else is settled.
+
+An outer orchestrator that already ran an equivalent gate → inherit, don't re-prompt.
+
+## The loop (per unit)
+
+Loop each unit through these three steps until the review passes — all three in [references/loop.md](references/loop.md).
+
+| Step | What it does | Ends when |
+|---|---|---|
+| 1 — Produce | One spawn: implement + e2e + gates + PR | A PR exists carrying its Review Contract |
+| 2 — Review ∥ CI | Independent review on a **different model**, same breath as CI, same HEAD | A verdict lands: PASS / NEEDS_CHANGES / FAIL / BLOCKED |
+| 3 — Fix, then loop | Address the verdict, then re-review the delta | The review PASSes — preserve it and update the component candidate |
+
+## Promotion / release lane
+
+A unit PR based on a production branch is a **promotion**, not a feature PR: fast-forward required (review-pr § Promotion PRs), gate on the promoted SHA's already-green PR-lane result, and read-only smoke (under a read-only production profile, `prod-preview`/`prod-active`) against a 0%-traffic candidate before any traffic shifts. Full releases belong to `resolve-release`.
+
+## Definition of done (handoff)
+
+**Run the operations emitted by `run-state.mjs next <slug>`.** For a delivered combined component with distinct published unit PRs, `next` first emits `reconcile-contained-unit-prs`: it freshly fetches `origin/<targetBranch>`, verifies the live combined PR at its recorded merge SHA, compares every live unit PR exact head with the component's recorded reviewed-unit evidence, and closes only open heads proved contained in the fresh target. Drift, missing ancestry, or unreadable state leaves that unit PR open and blocks finalization; terminal unit PRs are recorded no-ops.
+
+**Then run `run-state.mjs finalize <slug>`.** This remains the only completion transition. It independently fetches the target again, proves every delivered merge SHA is an ancestor, verifies issue and PR terminal states live, restores `originalBranch`, and applies the fail-closed workspace reap — refusing on any unresolved unit, stale GitHub state, missing ancestry, or preserved unpublished work. On success it writes immutable `finalization` evidence and prints the canonical handoff from that validated state.
+
+**Do not retype that handoff or replace it with a prose completion claim.** `run-state.mjs progress <slug>` is the standing progress report, never a completion gate; [the profiler](references/postmortem.md) is an explicitly invoked, non-blocking diagnostic that authorizes nothing.
+
+Three rules the generated handoff exists to enforce:
+
+- **A component whose members are `merge-ready` owes one terminal `components[].delivery.outcome`** — `merged` with a verified component `mergedSha`, or `handed-back` with the blocking condition. Member units derive dispositions through `deliveryRef`; a member with neither canonical nor legacy evidence is reported **undelivered, never done**.
+- **Merge only what `mergeShippable` authorizes, and only into `targetBranch`.** Never promote to production — that is `resolve-release` with its own authorization.
+- **Reap the workspaces last**, through `finalize`, after every unit branch is pushed — removing them first destroys what was never published. **Never `--force` a worktree removal and never delete one by hand**: preserved unpublished work blocks finalization and stays on disk, and a forced removal is the one action in this loop that destroys work no gate can recover. 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 reports per unit, and how to read the round profile: [references/finalization.md](references/finalization.md).
+
+## The removal path (keep this skill small)
+
+This skill accretes, so every new gate/artifact/validator must name the incident it would have caught in the same commit and in [references/why.md](references/why.md). Recommend retirement only from a configurable durable cross-run window of readable executions with zero unique findings and zero rejections; one clean run is never enough, and `not run`, `skipped`, or `unreadable` breaks the streak. Fingerprint findings by stable `class + locator`, keep value separate from raw volume, and leave every retirement decision to the human. Process weight is a regression ([regression checklist](references/regression-checklist.md)). → [why](references/why.md#the-removal-path) Editing this skill? Run the sandbox self-test first: [references/sandboxed-testing.md](references/sandboxed-testing.md).
+
+## Reference Map
+
+**`run-state.mjs guide [what you are trying to do]`** — 29 routed answers, each naming the reference
+that owns it and the script that runs it. `guide` with no query lists them all; `--json` for a
+machine-readable answer. It needs no run and no manifest.
+
+```
+run-state.mjs guide reap          # -> references/interference.md, scripts/workspaces.mjs
+run-state.mjs guide breaker       # -> references/breaker.md, run-state.mjs diagnose-breaker
+```
+
+This table used to live here, at 24 rows and 3.6KB of a file that is loaded into **every** run
+whether the table is consulted or not — and it is consulted one row at a time, when you already
+know what you are doing next. That is a query, not doctrine. The [phase routing](#routing-read-this-first)
+above stayed, because it is read once at the start and is what makes a truncated read survivable.