@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/references/high-risk.md

@@ -0,0 +1,29 @@
+# The high-risk protocol (deep lane — auth/money/tenancy/migration only)
+
+This file is the **expensive lane, on purpose**. The first-pass failure class that dominates recovery rounds is domain-semantic bugs on four surfaces — auth/authz/token/session, money/tax/pricing, tenancy/org-scope/isolation, DB migrations/schema — where "balanced-coder implement + frontier review" reliably costs 2–3 extra rounds. Since 2026-08-02 the reviewer slot defaults to `gpt-5.5` (deep-reasoner) rather than being asked, so a run that takes the default gets a reviewer *below* the frontier pairing named here — this lane's warning applies more sharply, not less. Naming a frontier reviewer at the gate is the cheapest thing to do for a run that lands in this lane. These are the low-first-pass surfaces because their governing contract is the hardest to pin down up front — a **spec-maturity** signal, not a reviewer- or code-quality one. Units flagged `high-risk` by the intake heuristic run everything below **in addition to** the lean loop. Nothing here applies to any other unit: applying this lane broadly is exactly the process-weight regression the [removal path](../SKILL.md#the-removal-path-keep-this-skill-small) exists to stop.
+
+## Producer additions (step 1)
+
+- **Domain-hazard hunt, producer side.** Carry into the producer spawn (and its self-review) the instruction to hunt the diff against the **domain-hazards catalog** (`<skillsRoot>/review-pr/references/domain-hazards.md` — absolute, per SKILL.md's leaf-spawn contract; a repo-relative path reads as nothing once this skill is installed elsewhere and the producer hazard-hunts from memory on exactly the surfaces this lane exists for) **and** the repo hazards file (`docs/domain-hazards.md`, via the `Domain hazards` index in `AGENTS.md`/`CLAUDE.md`). No repo hazards file on a high-risk surface → the producer **seeds** it as part of the unit (implement-and-pr owns seeding).
+
+## Reviewer additions (step 2)
+
+Append to the reviewer spawn contract:
+
+> This unit is HIGH-RISK. **(a) Hazard hunt:** read the repo hazards file plus review-pr's domain-hazards catalog and adversarially hunt the diff against every item — fail-open vs fail-closed, replay/idempotency, clock-skew, issuer/audience/scope, conversion direction, minor-unit precision + storage range, cross-org isolation. Any hit is a blocking code-correctness finding, and every blocking domain-semantic finding carries a `hazard_candidate` (the ready-to-paste hazards-file row, or `covered_by: <id>`) — you are read-only; the fix commit writes the row, the re-review verifies it. **(b) Round-1 depth:** before your first verdict, probe each changed live endpoint against the real running surface (authorization, boundary, pagination/filter, failure cases) and trace the changed contract through every shared first-party consumer; record concrete evidence for both, or `not-applicable` with a specific reason — never a silent deferral to a later round.
+
+A prior finding with a `hazard_candidate` needs **two locators** to reconcile as Resolved: the code fix and its hazards-file row (or an explicit covered-by) — code-only is Partially resolved; the lesson wasn't banked.
+
+## Theme discipline and class-complete fixes (steps 2–3)
+
+- **Findings carry stable themes.** A recurrence of the same underlying contract keeps its `theme.id` — the reviewer restates the general violated contract, not just the new counterexample. A second consecutive finding on the same theme is a signal the unit may be stuck *or* the reviewer over-blocking; carry it into the circuit-breaker diagnosis (SKILL step 3) rather than resolving it yourself.
+- **State-machine/concurrency themes get class-complete fixes.** The fix enumerates the governing contract's full `state × task-kind` space, attaches a test + execution-evidence locator to every cell, and self-reviews every adjacent state under the same rule — a single counterexample test never closes the theme (it's how the same bug returns wearing a different input).
+- **Deep-audit matrix only in this lane** (#792). `record-review-round` / `record-fix-round` accept a **lean** payload for routine units (`headSha`, `themeIds`, `reviewSubject`, `authorizationBoundary`, minimal findings; changed surfaces are diff-derived) without `migrate-unit` or the coverage matrix. The full state/task matrix (`coverage` + `selfReview` + finding `theme` objects) is required **here** — when the high-risk deep protocol is active, or when the payload itself carries those deep fields. **You run these**, from the `fixRound` matrix the fix spawn returns — the spawn never writes the manifest itself. Reach for the deep shape when durability of the audit trail matters more than speed; do not tax every NEEDS_CHANGES with it.
+
+## Integration (epics)
+
+A high-risk unit is **always included** in the epic integration gate's integrated review, even when its surface looks disjoint — cross-org leaks, wrong issuer/audience, and fail-open defaults surface only once a sibling's caller exists, invisible to any per-unit diff review.
+
+## Cost expectation
+
+A high-risk unit is not a 45-minute unit and is not supposed to be. The budget goes to round-1 depth so the domain-semantic bug is caught **once**, early — not discovered on round 3 after two shallow fixes.

package/skills/engineering/resolve-issues/references/incidents/848/README.md

@@ -0,0 +1,156 @@
+# Incident #848 — the circuit-breaker's founding incident
+
+This is the distilled, **shippable** record of the resolve-issues run behind the
+round circuit-breaker's existence and threshold. It carries the incident's
+metadata, its round profile, the finding **class labels** (theme ids), and the
+lessons — **never the finding bodies**. The bodies describe real, now-fixed
+concurrency and authorization defects in a production payments/risk repo;
+they are preserved out of the distributed skill. See
+[Data provenance](#data-provenance) for where the raw evidence lives and why.
+
+## What the incident established
+
+Epic `issue-848-849` (resolve-issues, target branch `dev`) is the primary source
+behind four decisions:
+
+- **The design gate + the round circuit-breaker (#344).** The breaker threshold
+  was set to 4 and lowered to 3 a minute later — this run is why. Unit #848 ran
+  nine review rounds without converging; a mechanized stop-and-ask is the direct
+  response.
+- **The evidence for `units[].rounds` (#359).** Reconstructing what actually
+  happened here required a per-round record the manifest did not yet keep.
+- **A PASS is not terminal.** Unit #848's round-6 PASS was reversed by later
+  rounds — one of only three known cases of a PASS being overturned, and the
+  flagship one. See [The PASS reversal](#the-pass-reversal).
+- **The loop earns its cost on production code.** Across the rounds the review
+  surfaced ~15 distinct real implementation defects — concurrency and
+  authorization bugs in a payments risk engine — one adversarial round at a
+  time. This is the strongest available evidence that the loop pays for itself
+  on high-risk code.
+
+## The two units
+
+| Unit | Review rounds | Final status | Final verdict | Role |
+|------|---------------|--------------|---------------|------|
+| #849 | 1 | merge-ready | PASS | The control case — the well-specified sibling that passed on the first review. |
+| #848 | 9 | in-progress | NEEDS_CHANGES | Never reached merge-ready; the founding evidence. |
+
+#849 passing in a single round while its sibling took nine is the contrast that
+matters: the loop is cheap on a well-specified unit and expensive exactly where
+the specification (and the underlying implementation) was not sound.
+
+## Unit #848 — round profile
+
+Verdict sequence, reconstructed from the surviving per-round result files plus
+the manifest. The initial review is **round 1**, recorded as the `runner` result
+file (`review-848-runner-result.json`) — its four themes match the manifest's
+round-1 entry one-to-one. Only the `r7` result file decayed from OS temp before
+rescue; its round survives solely through the manifest.
+
+| Round | Verdict | Findings |
+|-------|---------|----------|
+| r1 (runner, initial) | NEEDS_CHANGES | 4 |
+| r2 | NEEDS_CHANGES | 1 |
+| r3 | NEEDS_CHANGES | 2 |
+| r4 | NEEDS_CHANGES | 3 |
+| r5 | NEEDS_CHANGES | 1 |
+| **r6** | **PASS** | 1 (non-blocking note) |
+| r7 *(result file lost)* | NEEDS_CHANGES | 2 themes (manifest) |
+| r8 | NEEDS_CHANGES | 1 |
+| r9 | NEEDS_CHANGES | 1 |
+| r10 | NEEDS_CHANGES | 4 |
+
+Manifest metadata: `reviewRounds: 9`, `status: in-progress`,
+`lastVerdict: NEEDS_CHANGES`.
+
+### The PASS reversal
+
+The **round-6 PASS was reversed by r7/r8/r9/r10** (r7's NEEDS_CHANGES survives in
+the manifest even though its result file is lost). This is the flagship evidence
+that a PASS is not a terminal state — a later round, looking wider or at a fix
+that introduced a new blocker, can and did overturn it. It is one of three known
+cases and the one most worth citing when the PASS-reliability question is
+revisited.
+
+### The defect class
+
+All ~15 defects landed on **one subsystem**, and every **defect-class** theme id
+shares the `blacklist-repair-*` prefix. The theme ids are safe class labels —
+they name the invariant a finding violated, not the exploit — so they are
+recorded here; the finding bodies are not. The distinct defect-class themes
+observed (the round-7 theme survives only in the manifest, its result file having
+decayed — see [Data provenance](#data-provenance)):
+
+- `blacklist-repair-live-claim-fence`
+- `blacklist-repair-already-correct-case-reconciliation`
+- `blacklist-repair-immutable-cutoff-cohort`
+- `blacklist-repair-mandatory-package-postflight`
+- `blacklist-repair-preflight-execution-parity`
+- `blacklist-repair-transactional-cohort-revalidation`
+- `blacklist-repair-authoritative-case-postflight` *(round 7 — manifest only)*
+- `blacklist-repair-terminal-winning-case-authority`
+
+Three further round-10 ids — `blacklist-repair-orchestrate-runtime-proof`,
+`blacklist-repair-exact-head-attestation`, and
+`blacklist-repair-manual-postflight-binding` — plus the
+`review-evidence-full-range-diff-check` note (rounds 6 and 7) are
+**process/evidence** themes (review-artifact and runtime-proof obligations), not
+defect classes, so they sit outside the census above.
+
+The shape — one subsystem, many rounds, a recurring family of concurrency and
+authorization invariants re-raised at a wider scope each round — is exactly the
+"fix the class, not the counterexample" failure the SKILL.md fix-round rules and
+the breaker exist to catch.
+
+## Models
+
+A Pi/GPT run (`confirmedAt` 2026-07-17):
+
+- Implementer: `gpt-5.6-terra`
+- Reviewer / oracle: `gpt-5.6-sol`
+
+(The oracle slot has since been removed from resolve-issues; it is recorded here
+only as a fact of this historical run.)
+
+## Data provenance
+
+- **Lost:** only the `r7` per-round result file had decayed from OS temp before
+  this rescue. **Round 1's result survives** — it is the `runner` result file
+  (`review-848-runner-result.json`), whose four themes match the manifest's
+  round-1 `reviewHistory` entry one-to-one. `r7` is the single lost file; its
+  verdict (`NEEDS_CHANGES`) and themes are reconstructable only through the
+  manifest, not from a result file. The mirror case is round 10: the manifest
+  `reviewHistory` recorded rounds 1–9 (`reviewRounds: 9`), so the round-10 review
+  survives **only** as the `r10` result file, with no manifest entry.
+- **Raw artifacts (committed, in-repo, NOT shipped with the skill):** the
+  surviving per-round result JSONs and the run manifest live at the repo root
+  under [`incidents/848/`](../../../../../../incidents/848/) — deliberately
+  outside `skills/` because that directory is distributed to team members via a
+  symlink farm, and the raw files contain the full finding bodies. See
+  [`incidents/README.md`](../../../../../../incidents/README.md).
+- **Excluded for size:** `review-848-r5-scan.json` (~1.6 MB) is raw
+  over-mock scan output, not incident evidence. It was preserved out-of-band but
+  is not committed.
+- **Round-7 timestamp corruption — already fixed by #379.** The manifest's
+  round-7 timing had `startedAt` (`2026-07-17T15:09:41Z`) *after* `endedAt`
+  (`07:24:57Z`): a local CST (UTC+8) value stamped with a `Z` as if it were UTC.
+  The cause was the orchestrator **hand-writing** `units[].timings` per a prose
+  step. **#379 deleted `units[].timings`.** Its replacement, `units[].rounds[].at`,
+  is written through `run-state.mjs`'s `nowIso()`, which returns
+  `new Date().toISOString()` — correct UTC, machine-written, never hand-stamped.
+  So #386's "fix the timestamp-field bug" acceptance criterion is
+  **satisfied-by-#379**; no further fix is needed, and none was made here.
+
+## Manifest durability (recommendation recorded, change deferred)
+
+The broader risk this incident exposes: run manifests are the only record of how
+the loop actually behaves, and they live only in `$TMPDIR/resolver-runs/`, which
+OS cleanup collects. At the time of rescue, **211 manifests covering 432 units**
+sat there with no durable copy — one #848 file was already gone.
+
+**Recommendation (not implemented in #386):** give the run store a durable
+default — e.g. honor a `RESOLVER_RUN_DIR` env var pointing at a durable path, or
+archive a run's manifest on completion into a tracked location. This is filed as
+a tracked follow-up: **#418**. The change is deliberately out of scope for the
+rescue unit (#386), which only preserves the #848 evidence and records this
+decision.

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

@@ -0,0 +1,86 @@
+# Intake and scheduling
+
+How issues become units, how units are scheduled against interference, and what is
+*not* a unit. Pre-flight runs before all of this and is indexed from
+[SKILL.md](../SKILL.md#pre-flight-once-before-intake--never-mid-run). Next phase:
+[loop.md](loop.md).
+
+## Intake & scheduling
+
+- **Classify every unit before scheduling it.** Run `scripts/unit-kind.mjs classify --stdin`
+  with the issue title/body and record its returned `unitKind`, `kindRecommendation`, and
+  `kindConfirmation`. The closed kinds are `implementation`, `external-verification`,
+  `human-decision`, and `prerequisite`. External dispatch, physical presence, credentials,
+  hardware, provider observation, third-party approval, or a human decision requires
+  explicit confirmation with `confirmedBy` and `confirmedAt`.
+- **Classify evidence/authorization lifecycle semantics at the same intake boundary.** Pass
+  `declaredScope` and planned `changedSurfaces` to `unit-kind.mjs`; each declaration is
+  `ordinary` or `evidence-authorization`, and unknown/malformed entries fail toward the
+  required class. Sensitive required-check, admission, enqueue, synthetic queue-head, and
+  delivery-ancestry surfaces override an `ordinary` declaration. A classified unit records
+  `evidenceLifecycle` and a versioned `evidenceLifecycleContract` covering every discovered
+  condition's phase, immutable SHA kind, producer, provider/acquisition operation, consuming
+  transition, and failure behavior. Run `evidence-lifecycle-contract.mjs validate <artifact.json>`;
+  the same validator runs inside `spawn-contract`, so missing, unsupported, mismatched, or
+  circular contracts refuse before implementation. This is focused workflow-design admission,
+  not an expansion of the auth/money/tenancy/migration high-risk tier. Ordinary unclassified
+  units retain the lean path with no artifact.
+- **Only `implementation` enters produce/review/CI/delivery.** An external unit may own a
+  runbook, validator, or harness artifact, but artifact `PASS` is preparation evidence only:
+  never external completion or delivery. Never dispatch or claim a human-only operation
+  from a harness result.
+- **External verification carries its protocol in state.** `externalProtocol` records
+  prerequisites, authorized actors, environment identity, allowed operations, stop/retry
+  policy, required evidence keys, and completion source. `externalCompletion` is valid only
+  when its source, actor, environment, operation, and evidence match that protocol exactly.
+- **Completion dependency differs from code interference.** `completionDependsOn` allows
+  implementation to build/review while external/human work is pending, but blocks delivery.
+  Omit it for independently shippable code; progress reports both kinds separately.
+- **Normalize to units.** Non-trivial work without approved test criteria → **stop and request them** (ensure-coverage create mode needs human sign-off); every unit owes baseline coverage for every surface it touches, ACs or not.
+- **Decomposition gate (epics only, at intake, before any producer spawn).** An epic's children are not evidence they cover it. Map every parent requirement — numbered stories, constraints, named buckets/enums/reason codes, testing decisions — to the child that owns it, and diff the two sets. Every unowned requirement is either written into a child's ACs or deferred to a tracked issue named in the handoff. **An epic whose parent requirements live nowhere in its children does not start.** Re-run the same diff at the exit audit; children drift after intake. Fires **once per epic, never per unit** — the cost is a set-difference over two issue bodies. → [why](why.md#decomposition-gate)
+- **A roster that grows mid-run re-runs the decomposition gate, at the moment it grows.** When units are added to a live roster, re-run the set-difference and answer one further question explicitly: **which of the new units block a component that is already merge-ready?** The default answer is **none** — a unit that did not exist when a component reached its bar cannot retroactively become its prerequisite. Record the answer in the manifest rather than leaving it to scheduling order. → [why](why.md#a-roster-that-grows-mid-run)
+- **A surface every sibling disclaims has no owner.** When two or more children each place the same surface outside their own scope — *"X changes only indirectly"*, *"X remains agnostic"*, *"X is handled by \<sibling\>"* — that surface is unowned. At the decomposition gate, collect the disclaimed surfaces across the roster and give each an explicit owner or a tracked issue. → [why](why.md#a-surface-every-sibling-disclaims)
+- **Prior-art check before any code** (epics: fan out via `prior-art-scan.workflow.js`): search PRs (`gh pr list --search`), the codebase, and issue state. Route true prior art to the `already-done` disposition; an open PR resumes at review/fix; partial work scopes the remainder; otherwise implement. A human descope is never prior art: record it only with `record-scope-decision`, including the human evidence and issue/PR dispositions. Unsure → ask, do not silently re-implement.
+- **Scope double-check — verify the sizing yourself.** Before spawning, ask of each unit: would implementing this plausibly mean a **new subsystem**, **several separable deliverables**, or a diff far beyond a routine unit (one surface, a few hundred lines)? If yes, **propose the split before any code** — named slices in dependency order, one HITL ask; the human confirms, since scope is their call, but the proposal is your job, made from the issue's content. → [why](why.md#scope-double-check)
+- **Design gate (before any producer spawn — implement-and-pr's design-input rule, enforced here because leaf spawns can't ask the human).** Apply the two-questions test to each unit: *would two reasonable implementers build materially different things from this issue?* and *does correctness depend on never-happens — orderings, failures, retries, partial states — the ACs don't state?* Either yes with no design/ADR in the source → **hand the unit back; do not produce the design here.** This is a terminal answer, not a problem to solve in-run: **no `autonomy` level drafts a missing contract**, and the one that briefly did was cut. Say what is missing, name `/grill-with-docs`, and stop that unit — the human lands the design and re-enters intake with it as the unit's design input. **Do not interview the human yourself, and do not route the resulting doc through the loop** ([prerequisites are not units](#prerequisite-artifacts-are-not-units)). Mechanically: set the unit's status to `blocked` (`run-state.mjs` accepts `queued|in-progress|merge-ready|blocked|skipped-already-done`, so record the "needs design" cause in the unit note, not as a status the schema rejects). When the human returns with the doc, re-enter intake and carry it into both the producer and reviewer spawns as the contract to build and verify against. Other units keep moving — a design-blocked unit never halts its siblings. **Most routine units answer no-no** — the issue is the design; blocking those on a brief is the over-triggering failure, not rigor. → [why](why.md#design-gate)
+  - **On a [`high-risk`](high-risk.md) unit the second question is presumed *yes* — it owes an enumerated invariant list, not a judgment call.** The gate inverts for them: a high-risk unit spawns its producer only when the source already enumerates the invariants the implementation must hold — fail-open vs fail-closed, replay/idempotency, issuer/audience/scope, conversion direction and precision, cross-org isolation, as its surface demands. An issue that merely *describes* the change does not clear it. **A contract pointer is not an invariant list.** → [why](why.md#high-risk-units-owe-an-invariant-list)
+- **These gates bind resumed and in-flight units, not just fresh ones** — including units that entered the loop before the gates existed. Re-apply the scope and design checks before the next producer or fix spawn on a resumed unit. → [why](why.md#the-gates-bind-resumed-units)
+- **Contract-revision gate (before every producer/reviewer spawn, and on resume).** Fetch the target branch and resolve the unit's authoritative approved design/test criteria **there**, not from a stale PR summary or the implementation branch's copy. Record the target-branch commit and refs in `units[].contractRevision`; derive freshness with the mechanized gate — `contract-revision.mjs check --in <manifest> --unit <id> --head <unit HEAD>` (exit 1 = HEAD lacks the approved revision → re-enter; **exit 2 = the pointer itself is unusable** — malformed, or it cites an artifact that does not exist at the approved commit, which no rebase can repair: fix the citation or land the missing doc, and do not spawn against a contract that is not in the tree; a `FRESH but review is stale` result means proceed but the exit gate owes a full-scope review), never a hand-eyeballed ancestry. If an approved revision affecting the unit landed after its recorded base or the contract used by its last review, stop the loop and re-enter intake: re-apply scope/design/risk, rebase onto the target branch containing the revision, and reconcile the **whole implementation** to the current invariant list before another review. Pre-revision review verdicts, CI, runtime evidence, and `lastReviewedSha` are historical only; they cannot authorize exit, and the next review is full-scope. An implementation PR cannot make itself compliant by weakening its own source/test criteria unless that source change is itself explicitly approved. → [why](why.md#contract-revision-gate)
+- **Risk-tier each unit (this decides how much process it gets).** Auto-flag **`high-risk`** when ACs or diff touch auth/authz/token/session, money/tax/pricing, tenancy/org-scope, or a DB migration/schema change. A high-risk unit runs the loop below **plus** [references/high-risk.md](high-risk.md) — the deep protocol (hazard hunt, round-1 depth probing, theme-complete fixes, forced integration review). **Everything else runs only the lean loop — keep it cheap; that is the point of the tier.** Record the flag in the manifest.
+- **Epic scheduling — [interference](#interference-scheduling-and-workspaces) is the primitive.** Record it as you find it: `dependsOn` carries the **blocking** edges (`{"unit":"#879","source":"symbol"|"premise"}`; a **premise** edge also owes `"invariant":"<the specific wrong behavior that would be live>"`, because the dependent is now built concurrently *against that sentence* rather than waiting — [interference.md](interference.md) has the counterfactual that decides the grade, and `runnable` prints `NO INVARIANT RECORDED` when it is missing), `sharedSurfaces` carries the **assembly** ones (units touching the same route/component/schema — individually green can be collectively red). Then everything else is derived: `run-state.mjs runnable <slug>` gives the capped runnable set, `plan` gives the [component](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic) grouping. A dependent unit **stacks** (branches off its dependency's branch — off bare `targetBranch` its diff references missing symbols, or rests on an invariant that is not there yet; a co-delivered unit's PR is a review artifact within its component, not an individual merge). Read-only stages — reviews and prior-art — parallelize as they always have. A blocked unit never halts siblings, and its **component** ships when ready regardless of a stuck sibling in another component. Mirror roster transitions via `run-state.mjs upsert-unit`.
+- **All blocked, nothing movable:** hand the human the decision batch with a recommendation each — say for every unit whether you read it as a mis-diagnosed blocker or as genuinely re-scopable, and which.
+- **Report the plan before the first producer spawn — `run-state.mjs plan <slug>`, pasted whole.** It names the roster and its dependency order, the components, the risk tiers, what the decomposition gate deferred and to which issue, and every unit still owing an answer — once, at the moment it is all settled and nothing has been built yet. **Rendered, not narrated.** Record the two things intake owes the manifest rather than holding them in your head — **`upsert-unit` carries `dependsOn`, `merge` carries `deferrals`**:
+
+  ```
+  run-state.mjs upsert-unit <slug> '{"id":"#880","status":"queued","dependsOn":["#879"]}'
+  run-state.mjs merge <slug> '{"deferrals":[{"requirement":"<parent requirement>","trackedIn":"#<issue>"}]}'
+  ```
+
+  `dependsOn` is the stacking edge — a dangling or circular one is refused. `deferrals` needs the issue tracking it; an untracked deferral is refused. **This is a report, not a gate:** it stops nothing. What stops the loop is what it *contains* — a unit blocked on design, a scope split to confirm, missing test criteria — and those asks were already owed by their own gates; the plan is where they arrive together instead of one interruption at a time. → [why](why.md#plan-and-progress-reports)
+- **Report progress each time a unit reaches a terminal disposition — `run-state.mjs progress <slug>`.** The rendered headline separates delivered, handed back, already done, human-descoped, blocked, and unresolved totals. Descoped requirements never enter the delivered, already-done, or resolved counts. It also names any unit sitting `merge-ready` with no terminal disposition. → [why](why.md#plan-and-progress-reports)
+
+## Interference, scheduling and workspaces
+
+**Interference is the primitive** — one unit's correctness depending on another's tree — and both boundaries this loop cares about are derived from it. Design input: [ADR 0001](../../../../docs/adr/0001-interference-is-the-scheduling-primitive.md); vocabulary: [CONTEXT.md](../../../../CONTEXT.md). Mechanics, the reap procedure and the cap's reasoning: [references/interference.md](interference.md).
+
+**Two grades, and they do not have the same effect — nor, since 2026-08-04, do the two *sources* within the blocking grade.** **Blocking** interference means the dependent cannot be *correctly shipped* until the other unit is in the tree; both sources block **delivery**, only one blocks the **build** — a **symbol edge** (the diff references symbols the other unit creates, so its base branch does not exist yet; fails loudly, derivable from the diff) and a **premise edge** (correctness rests on an invariant the other establishes; builds and passes in isolation while encoding a false premise, so it fails *silently* and **can only be declared, never derived** — if intake does not record it, every later gate agrees the work is fine and it ships in the wrong order). **Assembly** interference — a shared surface — prevents independent *validation* only.
+
+**A premise edge does not hold the build back; it holds the *merge* back.** The dependent compiles, its surface is its own, and it is scheduled concurrently with the unit it rests on — carrying that unit's `invariant` verbatim into its producer and reviewer spawns, which is what makes the premise *declared* rather than silent. What keeps it from shipping first is the merge gate, which already refuses a component whose dependencies are not in the target. Blocking the schedule as well was a third enforcement of one ordering, and it cost the whole graph's depth: `epic-25-proposal-generator` ran 12 units at 1.7× parallelism behind 18 premise edges. → [interference.md](interference.md)
+
+**Only the blocking grade constrains scheduling — and within it, only the symbol source.** Shared-surface units build concurrently and the integration gate re-validates them; that gate is already mandatory for every multi-unit component, so serializing them buys detection that exists either way and costs the most on the common epic shape. **Only the co-delivering sources — symbol and assembly — define a [component](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic).** A premise edge *orders* two components; it does not bundle them.
+
+**A unit is `runnable` when every unit it blocking-interferes with is pushed** — pushed, not merged, which is the whole win. **A run advances as a continuously refilled, capped runnable set:** ask `run-state.mjs runnable <slug>` whenever a unit reaches any milestone, admit what it names, and never wait for a barrier. There is no wave, batch or epoch here, deliberately. The **in-flight cap** bounds disk and dependency-install cost, **not correctness** — `inFlightCap` is **4, and the loop does not choose it**; `1 for fully serial` stays expressible for a human who has measured a reason, but it is never this skill's decision. → [why](why.md#the-in-flight-cap-and-its-default)
+
+**A workspace belongs to a unit**, from its first producer spawn until the unit is delivered or handed back. Fix rounds reuse it, so the install is paid once per unit rather than once per round, and a dead spawn's replacement resumes in place. Two units never share a tree — `validate` refuses it.
+
+**The orchestrator's checkout is not a unit's workspace, and no unit's workspace is the orchestrator's checkout.** You coordinate; you do not write code. **Do not run git in a workspace while its spawn is live**, and do not point a unit at the tree you are working in — `validate` refuses that too, and the reap refuses to remove it. → [why](why.md#the-orchestrator-is-a-writer-too)
+
+**Preserved on death, reaped only on success.** A workspace is removed only when its unit is delivered or handed back **and** the tree holds nothing unpublished — no uncommitted change, no untracked file, no commit that is on no remote. Anything unreadable or ambiguous preserves. Orphans from dead sessions are collected by an explicit reap that reads recorded paths *and* `git worktree list`: `workspaces.mjs reap <slug>` plans, `--apply` removes.
+
+## Prerequisite artifacts are not units
+
+**A design, ADR, or test-criteria document is an *input* to this loop, never a *deliverable* of it.** Whatever produces it — a human, `/grill-with-docs`, an earlier session — it does **not** get a producer spawn, an independent-review spawn, a PR of its own, a merge-queue delivery, or an ancestry gate. It is landed by the human, or it rides along in the unit's own branch as part of the unit's diff.
+
+The failure this exists to stop is not hypothetical and not an agent misbehaving — it is what the gates say to do when nothing scopes them. The design gate blocks; the [contract-revision gate](#intake--scheduling) requires the approved contract to exist at a commit; a commit becomes a branch, a branch becomes a PR, and a PR is owed guarantee 2's independent review, guarantee 3's fresh verdict, and delivery's ancestry proof. Each step follows correctly from the last, and the result is the whole pipeline running against a documentation file. **Measured: 64 minutes, 5 spawns, ~$2, zero lines of the feature — $1.07 of it spent adversarially reviewing a 91-line ADR whose `scan-diff` was empty because there was no code in it.** → [why](why.md#the-design-gate-hands-back)
+
+The rule in one line: **if the artifact contains no code, it does not enter the loop.** Route it back to the human and stop the unit.

package/skills/engineering/resolve-issues/references/integration-gate.md

@@ -0,0 +1,53 @@
+# Epic integration gate — the full procedure (assemble → gates → review → smoke → verdict → combined PR → authorized merge)
+
+This is the complete procedure behind SKILL.md's [epic integration gate](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic). Start it when the first unit reaches preliminary PASS, update it as each later unit becomes ready, and finish it only after the complete component candidate is frozen and terminally authorized. The gate is **mechanized in [`combine-and-verify.mjs`](../scripts/combine-and-verify.mjs)** (assemble, gate arithmetic, verdict, merge gate); run `combine-and-verify.mjs --help` and treat the script as the source of truth for exit codes, flags, and merge order. This file is the **why** and the **judgment the script does not encode**: which spawns the orchestrator drives, and the incidents that shaped the gate.
+
+## Why the gate exists
+
+The per-unit loop proves each PR merge-ready **against its own base, in isolation.** That is exactly the blind spot behind a whole class of post-merge bugs: every slice of an epic is green on its own branch, yet the slices **contradict or conflict once combined** on the integration branch. This is not hypothetical — it is the **#235** failure mode (the per-org login epic): one slice's tests asserted a *"Continue with Feishu"* button while a sibling slice replaced that button with an embedded QR panel; e2e specs assumed bare `/login` showed the credential card until a sibling made it show org-entry first; a second responsive logo a sibling added tripped strict-mode locators. Each slice passed review alone; the combination was red. No per-PR review can see this, because the conflicting sibling isn't in the PR's diff.
+
+A prose-described, late-in-a-long-run gate degrades to a lookalike or gets skipped ("no cluster"); a script cannot be forgotten. That is why the gate is `combine-and-verify.mjs`, which emits **`integration-verdict.json`** — `ALIVE` **only when** the combined tree assembled clean AND its CI, integrated review, and smoke each came back green. Anything else (including the `pending` the assemble step writes) stays DEAD: the forcing artifact a merge/promote step refuses to proceed without.
+
+Once the verdict is `ALIVE`, the integration branch is **not throwaway** — it *is* the deliverable, **published as one combined PR** (step 6). The component hands back a *single* CI-green PR rather than N per-unit PRs. (`resolve-release` still owns promoting→deploying to production, but the assembly + integration verification it would otherwise do at promotion time is already done here, so it consumes pre-combined, integration-verified PRs — its promotion-time assembly is a no-op re-verification of the tip, principle 2, not a fresh N-way merge.)
+
+## Scope: the deliverable is a component, not the epic
+
+This gate runs once per multi-unit [component](deliverables.md#deliverables-the-shippable-component-not-the-whole-epic) (a shared-surface cluster or a dependency chain), **not** once over every unit an epic contains. Two units in *different* components — no shared surface, no dependency edge — are not assembled together; bundling them is what lets one stuck unit freeze finished ones (the **epic-848** incident). A completed upstream component ships even while a downstream one is still stuck (a dependency doesn't wait on its dependents).
+
+**Why one combined PR *per component*, not N PRs merged one-by-one.** Under "require branches up to date before merging," a dependency chain merged unit-by-unit pays for itself twice: every merge advances `targetBranch` and invalidates the up-to-date status of every other open PR in the chain, forcing each to update + re-run required CI — N serialized merges and a re-CI on every step. Stacked PRs don't escape it (merging the bottom of the stack puts everything above it behind the base). The combined PR collapses the chain into **one** branch → **one** up-to-date check → **one** CI → **one** merge; dependency order is resolved *internally* at assembly. That churn argument is exactly why a component is a dependency chain, not an arbitrary bag of units — and why it does **not** justify combining *unrelated* components (two disjoint components share no branch and no up-to-date dependency, so merging one never invalidates the other; combining them creates only head-of-line blocking).
+
+## The steps — what the orchestrator drives (the script owns the arithmetic)
+
+`combine-and-verify.mjs` owns the decidable shell: `assemble` (integration branch off the freshly-fetched `origin/<targetBranch>`, merge units in dependency order, record conflicts, gates start `pending`), `verdict` (exit 0 = ALIVE, 1 = DEAD), and `mergeable` (the step-7 gate). It never owns the **judgment (review)** or the **driving (smoke)** — those are the orchestrator's, and they are what this section exists for.
+
+1. **Progressively assemble (mechanized).** As soon as a unit reaches preliminary PASS, assemble every currently-ready unit in dependency order and record the snapshot with `run-state.mjs record-component-candidate <slug> <component> --stdin` using `roundClass: "unit-discovery"`. Re-run this after each newly-ready unit so conflicts and integrated-test failures appear before the roster finishes. A merge conflict is a finding. If it exposes a unit-owned defect, reopen that unit with typed `integration-finding`; if the correction only reconciles the combined tree, own it on the integration branch and record the next snapshot as `roundClass: "integration-fix"` with `integrationFix.owner: "integration"`. Never silently rewrite a passed unit branch.
+2. **Re-run integrated tests on every progressive snapshot; run the full gates on the complete candidate, not the per-unit diff** — the whole unit suite (`lint-tests` whole-tree + `coverage-ledger validate`), the **presentation sweep on every shared surface the cluster touched** (the real render of the *integrated* page, the only place a sibling-induced regression like the invisible button or the strict-mode double-logo shows up), and CI on the integration branch. Green-per-unit does not substitute for green-combined.
+
+   **Discover and freeze `required-check-plan.json` before freeze.** Query the live GitHub ruleset/branch conditions and Mergify merge-admission conditions, preserve them in the plan, and bind the plan to the complete candidate HEAD. GitHub rulesets retain their live `ref_name` include/exclude/default-branch scope and only applicable target-branch rulesets contribute checks; unsupported or ambiguous rule shapes fail closed. Mergify conditions retain source and phase identity: queue entry, auto-enqueue, and merge protections are `pr-head`; merge conditions are `queue-head`. Every discovered check has exactly one `locally-reproduced` or `publish-only` classification with evidence and explicit phase membership. Exact-head CI derives only PR-head local jobs from this plan; it does not accept hand-authored `requiredJobs`. Changed-path exemptions remain structural in their phase tree, and a skip never counts as success. Epic-892 is the incident: the terminal component suite passed 1,060 resolver tests plus distribution/lifecycle checks, but omitted deterministic `skill-size`; the combined PR then failed and moved the reviewed head. An omitted live check therefore refuses authorization even when supplied jobs are green. A genuinely PR-head publish-only check remains explicit; keep the candidate frozen, publish the unchanged frozen head, bind the provider result to that same SHA, then authorize. Legacy evidence without a plan fails with migration guidance rather than claiming complete coverage.
+
+   Record the combined CI result into `gates.ci`. When CI requires PR mutation, run the [exact-head CI adapter](exact-head-ci.md), then `combine-and-verify.mjs record-exact-head --in integration-verdict.json --artifact exact-head-artifact.json`; a pending/failing artifact or an artifact SHA that differs from the assembled tip keeps the candidate DEAD. A queue-head condition is retained in the plan but is not PR-head authorization evidence: its plan entry must name a provider/acquisition mapping before enqueue. The queue watcher captures provider-issued `queue-execution` evidence only after the provider creates and tests a distinct synthetic queue head. It is post-delivery proof, not a prerequisite for `ALIVE` or enqueue eligibility.
+3. **Freeze, then run one terminal independent review of the integrated diff.** Once every component unit is included and assembly/tests are clean, call `run-state.mjs freeze-component-candidate <slug> <component> --stdin` with the exact candidate HEAD. No commits are allowed between freeze and the terminal gates. Then run one independent review of the integrated diff — `read <skillsRoot>/review-pr/SKILL.md and follow it`, don't improvise; spawn it on the confirmed **review model at its confirmed effort** (SKILL.md's leaf-spawn contract, clauses (a) and (d)), scoped to `target...integration-branch`. It carries [step 2](loop.md#2--review--ci-same-breath-same-head)'s contract in full, **including its two proof artifacts** — the `coverage-checklist.mjs validate` result and the `scan-diff.mjs` findings channel — and a verdict arriving without them is rejected before it is read. For every lifecycle-classified unit, it also receives the validated `evidenceLifecycleContract` and compares the integrated implementation against each condition's phase, SHA kind, provider/acquisition path, consuming transition, and failure behavior. That artifact is design input, never a substitute for this independent review or provider-issued evidence. On top of that contract, this review reconciles the cluster's tests against each other: does any unit's test assert behavior a sibling changed? does each shared surface still render and behave correctly with all slices present? Record the verdict into `gates.review`.
+
+   *Why this step spells the contract out instead of linking it:* a markdown link can't be pasted into a spawn prompt, and until 2026-07-20 this step offered nothing else — no read instruction, no model, no proof bar — while the `smoke` gate one line below was fully mechanized. That asymmetry is the class-(A) failure this file's own opening warns about, sitting on the **latest-firing gate in a long run**, where a prose verdict written into `gates.review` is read by `verdict` as a green gate on the way to `ALIVE`.
+4. **Run the curated E2E happy-path smoke gate (skill: `smoke`).** The combined suite being green is necessary but not sufficient — the **#237** bugs (an invisible primary button, a component that crashed on mount) shipped *with* a green suite, caught only by **running the real app**. Boot the assembled integration branch (`--target local`), drive the selected golden paths into `smoke-results.json`, then reduce them to `smoke-verdict.json` — `read <skillsRoot>/smoke/SKILL.md and follow it`, don't improvise. It returns ALIVE / DEAD; record it into `gates.smoke`.
+
+   **The honest not-applicable path (#393).** A component in a repo with **no bootable surface and no curated golden-path manifest** genuinely cannot run smoke — this skills repo is the standing example (no root `package.json`, no app to boot, only the smoke skill's own shipped example manifest). For that case, and only that case, record `gates.smoke = 'not-applicable'` **plus** a top-level `smokeNotApplicableReason` on the verdict naming why (`combine-and-verify.mjs` then lets the smoke gate reach ALIVE on that reasoned N/A). This is the **same honesty pattern as green-gate's N/A**: an N/A-with-reason is *not* a pass fabricated to get green. The guardrails are sharp and enforced by the script:
+   - **Fabricating `smoke: 'ALIVE'` where the app never ran is still forbidden** — writing a gate result no gate produced is the exact defect the forcing function exists to prevent. The reasoned N/A is the honest *alternative* to that fabrication, not a new way to skip smoke where it could run.
+   - **A reason is mandatory.** `smoke: 'not-applicable'` with no `smokeNotApplicableReason` fails closed — the verdict stays DEAD, treated exactly like a missing gate.
+   - **A `no-surface` unit reuses this path unchanged** (#515) — it is not a skip and adds no machinery. The one difference: its reason is **derived from the scope class**, not authored per run — take `smokeNotApplicableReason` straight from `scope-class.mjs classify --json` (`scopeSmokeReason`), which names the matched classes. Everything above still applies: no reason, still DEAD.
+   - **Missing ≠ N/A.** A verdict with no smoke field at all is still DEAD; the N/A is a deliberate, reasoned third state, never a silent default for a missing result. `pending` / `DEAD` / `EMPTY` all stay DEAD too.
+   - **A repo that CAN boot still owes a real `ALIVE`.** The N/A is scoped to repos with no runnable surface; it does not excuse an un-run smoke where a golden path exists.
+   - The N/A + reason is **surfaced in the handoff** — `verdict` and `mergeable` print it, and it is written into `integration-verdict.json` — so a merge-without-smoke is a recorded, visible decision, not one buried in a transcript (#393's core ask).
+5. **Authorize the exact frozen head or keep it frozen for a publish-only check.** Reduce the locally runnable CI/review/smoke evidence into `integration-verdict.json`. When every required check was reproduced, call `run-state.mjs authorize-component-candidate <slug> <component> --stdin` with all three artifacts bound to the frozen SHA. When a mapped required check is genuinely publish-only, do not invent a provisional authorization: leave the candidate `frozen`, publish the unchanged head in step 6, bind the resulting green check to that SHA, then call the same authorization transition. Any movement after freeze first routes through the owned fix path (and after authorization first calls `reopen-component-candidate` with a #888 typed reason and changed boundary), then freezes a new generation and runs fresh terminal review + CI + smoke. Never weaken a sibling test to make the combined suite pass.
+6. **Publish the combined PR (the component deliverable).** *For a multi-unit component*, push the complete frozen integration head and open (or update) one combined PR into the confirmed `targetBranch` after all locally runnable terminal gates pass. Normally the candidate is already authorized and the verdict is `ALIVE`; the only pre-authorization publication is step 5's explicitly mapped publish-only required check, with the candidate still frozen and no head movement.
+
+   **Push order (epic-867 / #947).** The integration branch must be on the remote **before** unit PRs are converted to draft or cross-linked as superseded. If `git push -u origin <integration-branch>` is rejected by a **Mergify stack** pre-push hook (`use mergify stack push` / stack-only push), that hook is for stacked *unit* series — not for an assembly artifact. Recovery: `git push --no-verify -u origin <integration-branch>` (or the repo's documented non-stack push path). Do not stall on drafting unit PRs while the combined branch is still local-only.
+
+   Title the PR for the component; the body lists every unit with `Closes #<n>`, links each unit's PR, and carries the integrated Review Contract + the `integration-verdict.json` evidence. **Confirm CI is green on the combined PR's own HEAD** — opening the PR is what wires the repo's required checks to this branch, so re-watch `gh pr checks <combinedPr>` rather than trusting the pre-publish `gates.ci`; a required gate unwired or red on the published PR means the component is **not** done (re-route to the owning unit, never weaken a check). A publish-only check that succeeds on the unchanged frozen SHA completes step 5 authorization; it does not buy another review. Then **convert each per-unit PR to draft and cross-link it** — keep them as the per-slice review record; they close out when the combined PR lands and the unit branches are cleaned up (a stacked unit's PR closes when its dependency's branch is deleted). Don't close them by hand first. Record the combined PR ref into the run manifest (`components[].pr`) and into `integration-verdict.json` (`combinedPr`). *(A single-unit component has just one unit PR from [step 1](loop.md#1--produce-one-spawn-implement--e2e--gates--pr) — already the deliverable; publish-only checks run there unchanged.)*
+7. **Deliver the component through the recorded provider, only into `targetBranch`.** Fetch `origin/<targetBranch>` before assemble and record it as `baseShaAtAssemble`; fetch again before delivery and record the observed tip with `record-component-target-base … phase:enqueue`. The combined PR's live `headRefOid` must still equal the authorized frozen component HEAD. For **direct** delivery, `combine-and-verify.mjs mergeable` requires exact target-tip integration; reconcile, re-test/smoke, and delta-review before `gh pr merge`. For a **queue** provider, `combine-and-verify.mjs enqueue-eligible` permits forward target movement when `baseShaAtAssemble` is still an ancestor of the live target: keep the source HEAD immutable and let the batched queue test its synthetic current-base plus candidate tree. Mere target movement or pre-enqueue GitHub `DIRTY` is not a rebase trigger. Rewritten/divergent target history, a changed source HEAD, or a provider-observed conflict remains blocking. Only after the mode-specific gate exits 0 may the loop issue one provider enqueue; `gh pr merge` is forbidden in queue mode. The watcher must capture valid queue-head execution evidence, and completion requires that artifact plus fresh merged ancestry. `mergeShippable` is read from the manifest, never a flag; absent authorization stops at step 6. Never promote past `targetBranch`.
+
+## The skip rules in full
+
+There is no terminal-review skip: that review is the event that authorizes the frozen component HEAD, including a single-unit or disjoint low-risk component. Keep the existing high-risk additions intact: auth/tenancy/token/money/migration components still run the high-risk integrated review protocol and smoke may be `not-applicable` only through the reasoned path above. Progressive snapshots do not buy full reviews; only the frozen generation does. Even one unit is assembled onto the target and smoked: that is where the real-render class shows up, independent of sibling clusters.
+
+**Step 6 (publish) is governed by the component's unit count:** a multi-unit component publishes its combined PR; a single-unit component skips the publish because its one unit PR is already the deliverable. **Step 7 (merge) is governed by the `mergeShippable` authorization, not by unit count** — a single-unit component merges its own PR when authorized and shippable, exactly as a multi-unit one merges its combined PR. `combine-and-verify.mjs` over a single unit is a clean no-conflict assemble plus the gate arithmetic — cheap, and it still produces the forcing `integration-verdict.json` the handoff requires. When the user opted into multi-agent orchestration, the re-gate and review can fan out per component, same contract.

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

@@ -0,0 +1,87 @@
+# Interference, the runnable set, and the workspaces it hands out
+
+The full procedure behind SKILL.md's [interference section](intake.md#interference-scheduling-and-workspaces). Read it at intake, when you record the roster's edges, and again at the handoff, when you reap. The design input is [ADR 0001](../../../../docs/adr/0001-interference-is-the-scheduling-primitive.md) and the vocabulary is [CONTEXT.md](../../../../CONTEXT.md); this file is the mechanics and the judgment neither of those encodes.
+
+## Recording interference at intake
+
+Two fields, and the difference between them is the whole design:
+
+```
+run-state.mjs upsert-unit <slug> '{"id":"#880","status":"queued",
+  "dependsOn":[{"unit":"#879","source":"symbol"}],
+  "sharedSurfaces":["app/settings/page.tsx"]}'
+```
+
+- **`dependsOn`** — the **blocking** edges. `source` is `symbol` or `premise`. A bare string (`"dependsOn":["#879"]`) still reads, as a **symbol** edge: that is the safe interpretation, because symbol co-delivers and the other reading would split a component that must merge together. An unrecognized source is **refused** at the write rather than coerced — a typo'd `premis` would take the co-delivering reading silently.
+- **`sharedSurfaces`** — the **assembly** edges. Units naming the same surface id co-deliver. It never holds a unit back from building.
+
+**Which source is it?** One question, and phrase it as the *counterfactual*: **if this unit merged tonight and the other never merged at all, what specific incorrect behavior would be live?** The build doesn't compile → **symbol**. A concrete wrong behavior you can name ("parallel manifest writes race and drop updates") → **premise**, and *that sentence is the edge's `invariant` field* — write it down, because it is what the dependent gets built against. Nothing, until the sibling lands and the pair is red → **assembly** (`sharedSurfaces`, not `dependsOn`). "It comes later in the plan", or "it builds on the other's work" → **no edge at all**.
+
+The counterfactual's *never merged at all* clause is the load-bearing part. Asked as "should this come after?", plan order gets transcribed into the graph and step 2 depends on step 1 all the way down — which is exactly what the manifests show: 63 runs split into declaring **no** edges (depth 1, 10–33× parallelism) or a **chain** (depth 5–19, 1.2–2.4×), with almost nothing between. Asked as the counterfactual, step 2 of a plan is almost always still correct if step 1 shipped alone, so the edge is never drawn.
+
+**The two grades do not cost the same, and since 2026-08-04 they do not block the same thing.** A **symbol** edge blocks *scheduling* — physically, since there is no tree to compile against. A **premise** edge blocks *delivery only*: the dependent is built **concurrently**, with its `invariant` carried verbatim into the producer and reviewer spawns, and the merge gate ([`combine-and-verify.mjs mergeable`](../scripts/combine-and-verify.mjs)) is what keeps it from shipping first. Declaring the assumption is what cures the silent-false-premise hazard; ordering the build never did — a dependent encodes its premise whenever it is built, and waiting only makes the premise true at that moment.
+
+**A premise edge is the one nothing can recover for you.** A symbol edge announces itself the first time the diff fails to compile. A premise edge produces a green unit encoding a false assumption — the reviewer sees a green PR, and the integration gate sees two units that never touched the same file. If intake does not declare it, nothing downstream will.
+
+That is an argument for **declaring** it, and it is worth being precise about what declaring buys, because it used to buy the wrong thing. The unit is *meant* to be runnable — building it later never removed the false premise from its code, it only made the premise true by the time the code ran. What the declaration buys is that the premise is **named**: it reaches the producer as an assumption to design against and the reviewer as a claim to check, and it reaches the merge gate as an ordering. An undeclared premise edge is still the silent failure this paragraph describes; a declared one is no longer silent, whenever it was built.
+
+**Do not over-record.** A **symbol** edge you are not sure about costs a serialization; a **premise** edge you are not sure about now costs only a delivery ordering; a `sharedSurfaces` entry costs only an integration re-validation that was probably running anyway. When in doubt between premise and assembly, assembly is still the cheaper wrong answer — but the expensive mistake to avoid is calling something a **symbol** edge when the diff references nothing the other unit creates. That one you can check: name the identifier. If you cannot, it is not a symbol edge.
+
+## Running the set
+
+```
+run-state.mjs runnable <slug>          # who holds a workspace, who may be admitted, who waits
+run-state.mjs runnable <slug> --json   # the same, for the turn that acts on it
+```
+
+Ask it **whenever a unit finishes** — a push, a delivery, a hand-back. It is a read: it computes the admission, you take it, and you record the workspace you handed out (the orchestrator is the manifest's only writer, ADR 0001 decision 5).
+
+`ADMIT NOW` is already dependency-ordered, so taking it in order never spends the last free slot on a unit that unblocks nobody. A unit under `WAITING` is waiting on a **push**, not a merge — record `units[].pushedSha` as soon as a producer's branch is up, or its dependents sit there while the branch they need is already on the remote.
+
+**The cap is a cost bound, not a correctness bound.** `inFlightCap` is **4, unconditionally, and the loop never picks a different number** — not at pre-flight, not from a judgement about how slow this repo's install looks. Nothing about correctness changes at any value: the scheduling predicate is what keeps units apart, and the cap only decides how many run at once. `1 for fully serial` remains expressible so a human who has *measured* a slow-install repo can set it, but that is a human's field to write and never an ask this skill raises. The reason it is no longer tunable by the loop is that a tunable default gets tuned down: `epic-563-admin-transactions` set 2, and its own manifest replayed through `runnable` admits nothing at 2 and admits `#573` at 4 — a five-hour serialization bought by a number nobody was ever going to revisit mid-run. → [why](why.md#the-in-flight-cap-and-its-default)
+
+## Handing out a workspace
+
+```
+workspaces.mjs path <slug> <unitId>    # the path this unit's tree takes
+git worktree add <path> <base>         # base: origin/<targetBranch> — or, for a SYMBOL
+                                       # dependent only, the dependency's branch. A premise
+                                       # dependent references nothing in that branch, so
+                                       # stacking it buys no symbols and exposes it to the
+                                       # upstream's squash/rebase (which silently widens the
+                                       # next delta re-review to full scope — loop.md § re-reviews)
+run-state.mjs upsert-unit <slug> '{"id":"#880","workspacePath":"<path>"}'
+```
+
+The tree belongs to that unit until it is delivered or handed back. **A fix round reuses it** — pass the same `workspacePath` in the spawn, and the dependency install is paid once per unit instead of once per round. A spawn that dies leaves a partial there, and the replacement resumes in place.
+
+**Path reserved ≠ holding (epic-867 / #945).** Assign `workspacePath` at admit/spawn, not as a bulk intake roster write. `runnableState` counts a unit toward `inFlightCap` only when the path is *held* — status `in-progress`/`merge-ready`, or produce/review evidence (`rounds`, `reviewRounds`, `pr`, `pushedSha`). A pure `queued` unit with a pre-written path does not fill the cap (and `validate` warns).
+
+**Never hand a unit the tree you are coordinating from,** and never do git work in a unit's tree while its spawn is live. `validate` refuses a unit whose `workspacePath` is the run's own checkout, and refuses two units sharing one path; the reap refuses to remove the orchestrator's checkout at all. The incident behind that rule is in [why.md](why.md#the-orchestrator-is-a-writer-too).
+
+## Reaping
+
+```
+workspaces.mjs reap <slug>            # the plan — removes nothing
+workspaces.mjs reap <slug> --apply    # remove the rows marked REAP
+```
+
+It reads the manifest's recorded paths **and** `git worktree list`, because those two sets differ in exactly the case that matters: a session that died after creating a tree and before recording it. A manifest walk alone leaves those orphans forever.
+
+**Four verdicts.** `REAP` — the unit is delivered or handed back and the tree holds nothing unpublished. `PRESERVE` — something is unpublished, or the unit still holds it, or git could not be read. `REFUSE` — the path is, contains, or sits inside the orchestrator's checkout; **or** its identity on disk cannot be established (a relative path, a dangling symlink, a permission refusal); **or** two units claim it, which is a corrupt manifest the reap will not resolve by guessing. `absent` — recorded but not on disk.
+
+**Paths are compared as trees, not as strings.** `/tmp` is a symlink to `/private/tmp` on macOS, so a workspace created under one spelling and a guard written in the other name one directory and match no text. Every comparison here resolves symlinks first, and anything it cannot resolve is treated as protected.
+
+**"Nothing to collect" and "could not look" are different answers.** With no scope established, nothing on disk is examined and the plan says `orphan collection: NOT RUN` with the reason. That is exit **4** — it outranks 1, because the orchestrator's own checkout is refused on nearly every run and a code ranked under 1 would never be seen. The same applies one row down: a worktree whose identity will not resolve gets a `REFUSE` row rather than being silently skipped as "out of scope", because *out of scope* and *I could not tell* are the same two answers again.
+
+**The sweep's scope is declared, not inferred from an arbitrary entry.** `workspaceRoot` on the manifest is the run saying where its trees live, and it wins outright. With none declared the scope is inferred from the recorded `units[].workspacePath`s, which must all **agree on one parent tree** — several recorded paths make "the first one's parent" a coin toss, so a disagreement yields no scope rather than one of them. A declaration that cannot be **read** is refused, not quietly replaced by an inferred one: "declared none" means absent, `null` or a blank string, and any other value present — a non-string, a slashes-only `/`, a path that will not resolve — is a scope the run *stated* and the reap could not use, which is exit 4 rather than a scope the manifest never named. Declared or inferred, a root that is, contains, or sits inside a protected tree is **refused**: `dirname` of a unit mis-recorded as the checkout itself is the repo's *parent*, a scope holding every other checkout on the machine, whose worktrees are not this run's orphans. The filesystem root is refused on its own account, under every spelling — `/`, `///`, `/.`, a symlink to it — because it contains every protected tree there could be. Every one of those answers is a "could not look" — record `workspacePath` as you hand each workspace out, `set <slug> workspaceRoot <abs-path>` when the paths cannot agree, and read `git worktree list` by hand until you have.
+
+**Unpublished means three things,** and the third is the one a `git status` check misses: an uncommitted change, an untracked file, **or a commit contained in no remote-tracking ref**. That last case has a spotless working tree and the entire unit living on one machine.
+
+**A pre-authorization to keep working is a LOCK on those trees.** Before `reap --apply`, confirm every agent ever pointed at a workspace has *reported done* **and** gone idle. "It sent me its final result" is not enough on its own: if you told an agent it could keep going — more repeats, another measurement, a confirmation run — then it may still be executing in a tree whose contents look finished. The reap reads the tree, never the process table, so a clean, published, delivered workspace with a live worker inside it plans as `REAP`.
+
+What that costs is not a lost commit — it is lost work *in flight*, and it can also **manufacture evidence**. In fmm-express epic-894 the orchestrator pre-authorized repeat E2E runs, read an interim report as terminal, and reaped: git de-registered the worktree and half-deleted `node_modules` under a live Playwright worker. One run collapsed with 36 `worker process exited unexpectedly`; the crash put a red mark on a test that read as a genuine regression until the agent opened the JSON and found a crash artifact rather than an assertion failure. A destroyed measurement does not merely vanish — it returns a plausible wrong answer. (`reap` now preserves a tree with a live process in it, but the doctrine is what stops you reaching for `--force` when it does.)
+
+**A preserved row is a fact for the handoff, not an obstacle.** Report it — the path, the unit, and what it holds. Do not `--force`, do not `rm -rf`, do not push somebody else's branch to make it reapable. Removing a tree that holds unpublished work is the one action in this loop that destroys something no gate can recover, and a directory left on disk costs a human ten seconds.
+
+Exit codes: `0` all clear **and the orphan sweep ran** · `1` something preserved or refused, **or `--apply` could not remove a tree and left it in place** · `2` usage · `3` no manifest · `4` the orphan sweep could not run (no scope could be established, or no `git worktree list`).