@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/generated/workflow-repair-policy.json

@@ -0,0 +1,448 @@
+{
+  "members": [
+    {
+      "installName": "batch-grill-me",
+      "ownership": "dependency",
+      "sourcePath": "skills/in-progress/batch-grill-me",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "code-review",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/code-review",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "codebase-design",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/codebase-design",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "diagnosing-bugs",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/diagnosing-bugs",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "domain-modeling",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/domain-modeling",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "grill-me",
+      "ownership": "dependency",
+      "sourcePath": "skills/productivity/grill-me",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "grill-with-docs",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/grill-with-docs",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "grilling",
+      "ownership": "dependency",
+      "sourcePath": "skills/productivity/grilling",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "handoff",
+      "ownership": "dependency",
+      "sourcePath": "skills/productivity/handoff",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "improve-codebase-architecture",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/improve-codebase-architecture",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "prototype",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/prototype",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "research",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/research",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "resolving-merge-conflicts",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/resolving-merge-conflicts",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "setup-matt-pocock-skills",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/setup-matt-pocock-skills",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "tdd",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/tdd",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "to-spec",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/to-spec",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "to-tickets",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/to-tickets",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "triage",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/triage",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "wayfinder",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/wayfinder",
+      "expectedSource": {
+        "id": "matt-pocock",
+        "type": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
+      }
+    },
+    {
+      "installName": "harness-runtime",
+      "ownership": "dependency",
+      "sourcePath": "skills/engineering/harness-runtime",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    },
+    {
+      "installName": "e2e-test",
+      "ownership": "owned",
+      "sourcePath": "skills/engineering/e2e-test",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    },
+    {
+      "installName": "ensure-coverage",
+      "ownership": "owned",
+      "sourcePath": "skills/engineering/ensure-coverage",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    },
+    {
+      "installName": "implement-and-pr",
+      "ownership": "owned",
+      "sourcePath": "skills/engineering/implement-and-pr",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    },
+    {
+      "installName": "resolve-issues",
+      "ownership": "owned",
+      "sourcePath": "skills/engineering/resolve-issues",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    },
+    {
+      "installName": "resolve-release",
+      "ownership": "owned",
+      "sourcePath": "skills/engineering/resolve-release",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    },
+    {
+      "installName": "review-pr",
+      "ownership": "owned",
+      "sourcePath": "skills/engineering/review-pr",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    },
+    {
+      "installName": "smoke",
+      "ownership": "owned",
+      "sourcePath": "skills/engineering/smoke",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    },
+    {
+      "installName": "engineering-runtime",
+      "ownership": "owned",
+      "sourcePath": "skills/engineering/engineering-runtime",
+      "expectedSource": {
+        "id": "first-party",
+        "type": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0"
+      }
+    }
+  ],
+  "dependencyClosures": [
+    {
+      "invokedSkill": "resolve-issues",
+      "members": [
+        "tdd",
+        "harness-runtime",
+        "e2e-test",
+        "ensure-coverage",
+        "implement-and-pr",
+        "resolve-issues",
+        "review-pr",
+        "smoke",
+        "engineering-runtime"
+      ],
+      "generatedIdentities": [
+        {
+          "member": "resolve-issues",
+          "path": "generated/workflow-repair-policy.json"
+        }
+      ]
+    },
+    {
+      "invokedSkill": "resolve-release",
+      "members": [
+        "harness-runtime",
+        "e2e-test",
+        "ensure-coverage",
+        "resolve-issues",
+        "resolve-release",
+        "review-pr",
+        "smoke",
+        "engineering-runtime"
+      ],
+      "generatedIdentities": [
+        {
+          "member": "resolve-issues",
+          "path": "generated/workflow-repair-policy.json"
+        }
+      ]
+    }
+  ],
+  "repairRecipe": {
+    "id": "engineering-workflow-dependency-first",
+    "generatedFrom": "skills/distribution/generated/recipes.json",
+    "groupId": "engineering-workflow",
+    "lifecycle": "install",
+    "renderTarget": "public-npm",
+    "stopOnFailure": true,
+    "steps": [
+      {
+        "sourceId": "matt-pocock",
+        "sourceType": "external",
+        "repository": "https://github.com/mattpocock/skills",
+        "revision": "ed37663cc5fbef691ddfecd080dff42f7e7e350d",
+        "installPath": null,
+        "members": [
+          "batch-grill-me",
+          "code-review",
+          "codebase-design",
+          "diagnosing-bugs",
+          "domain-modeling",
+          "grill-me",
+          "grill-with-docs",
+          "grilling",
+          "handoff",
+          "improve-codebase-architecture",
+          "prototype",
+          "research",
+          "resolving-merge-conflicts",
+          "setup-matt-pocock-skills",
+          "tdd",
+          "to-spec",
+          "to-tickets",
+          "triage",
+          "wayfinder"
+        ],
+        "commands": [
+          {
+            "transport": "https",
+            "command": "SKILLS_DOWNLOAD_MAX_BYTES=33554432 SKILLS_EXTRACT_MAX_FILES=4096 SKILLS_EXTRACT_MAX_BYTES=67108864 npx skills@1.5.22 add https://codeload.github.com/mattpocock/skills/tar.gz/ed37663cc5fbef691ddfecd080dff42f7e7e350d --global --agent universal claude-code --skill batch-grill-me code-review codebase-design diagnosing-bugs domain-modeling grill-me grill-with-docs grilling handoff improve-codebase-architecture prototype research resolving-merge-conflicts setup-matt-pocock-skills tdd to-spec to-tickets triage wayfinder"
+          }
+        ],
+        "onFailure": {
+          "action": "stop",
+          "message": "Source matt-pocock fetch failed; stop this recipe before running another source."
+        }
+      },
+      {
+        "sourceId": "first-party",
+        "sourceType": "first-party",
+        "package": "@1aboveio/skills",
+        "version": "0.10.0",
+        "installPath": null,
+        "members": [
+          "harness-runtime",
+          "e2e-test",
+          "ensure-coverage",
+          "implement-and-pr",
+          "resolve-issues",
+          "resolve-release",
+          "review-pr",
+          "smoke",
+          "engineering-runtime"
+        ],
+        "commands": [
+          {
+            "transport": "npm",
+            "command": "npx @1aboveio/skills@0.10.0 install --group engineering-workflow"
+          }
+        ],
+        "onFailure": {
+          "action": "stop",
+          "message": "Source first-party fetch failed; stop this recipe before running another source."
+        }
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,82 @@
+# The circuit-breaker — the threshold, the mechanized diagnosis, and what the loop decides on its own
+
+This is the full procedure behind SKILL.md's [circuit-breaker](loop.md#3--fix-then-loop). Read it when a unit stops converging. The breaker is the **only** stuck-unit escalation — there is deliberately no cheaper advisory rung above it, because a stuck unit needs a *decision* and another model's opinion defers one by a round rather than making it.
+
+It does not lower the exit bar. A unit still ends only on guarantee 3's independent verdict against its final HEAD.
+
+## The threshold — the 3rd completed review round
+
+Mechanized in [`run-state.mjs record-breaker-decision`](../scripts/run-state.mjs); the manifest records `units[].breaker.firedOn`, always `review-rounds`, so the shape stays explicit in the hand-off and in any later analysis.
+
+- **3rd completed *review* round with no PASS verdict → `firedOn: review-rounds` — the code keeps failing review.** A producer/fix spawn that dies with zero code — no completed review — does **not** advance the breaker at all: only a *completed* review round counts.
+
+The threshold and the breaker's existence rest on a founding incident: epic-848's unit #848 ran nine review rounds without converging, and its round-6 PASS was reversed by later rounds ([the distilled record](incidents/848/README.md#what-the-incident-established) — raw evidence lives in the repo-root `incidents/848/`, deliberately outside the distributed skill).
+
+### Why there is no second, produce-pass threshold (removed)
+
+There used to be a second breaker (issue #382) that counted producer/fix *spawns* and fired at 3 with no passing review — the "the contract keeps changing" #376 shape, designed to fire *before* any review ran. It was removed. It counted passes AT SPAWN TIME (`record-produce-pass`, "in the same turn you spawn it"), so a spawn that died mid-flight with zero code still incremented the count. Passes 1–2 could produce nothing, no review could have run, and the count still reached 3 and false-fired "the contract keeps changing" — a real incident this session, recovered by a human `continue`. Counting at spawn time also contradicted [`spawn-contract.md`](spawn-contract.md)'s own rule that "a partial counts exactly as a missing one for every gate". The surviving review-rounds breaker counts only *completed* reviews, so a dead spawn can never inflate it. The dropped capability — firing before any review runs (#376) — is an accepted tradeoff. (Legacy manifests that recorded `firedOn: produce-passes` still validate on read-back; the code never writes that value again.)
+
+## The diagnosis is computed, not written
+
+`run-state.mjs diagnose-breaker <slug> <unit>` reads `units[].rounds[].themeIds` and returns the signal, the recommended decision, the evidence, and the verbatim text. **Exit 0 = the loop may take this decision itself; exit 1 = this firing owes the human an answer.**
+
+| Signal | What the round log shows | Recommendation |
+|---|---|---|
+| `recurring-theme` | one theme raised in ≥ `THEME_RECURRENCE_LIMIT` (3) rounds | `continue` **with a class-complete mandate** — then `split` if the theme survives it |
+| `churning-themes` | ≥ 2× as many distinct themes as rounds that named one | `design` — the literal `/grill-with-docs` redirect |
+| `converging` | themes turning over, none recurring | `continue` |
+| `insufficient-data` | fewer than 2 rounds recorded a theme | none — the human decides |
+
+**Why this is a script and not a paragraph.** The rule was prose until 2026-07-22, and an audit of 127 run manifests (522 units, 18 that fired, 27 firings) found the recurring-theme branch had **never once been taken**:
+
+| Unit | Theme | Rounds naming it | Decision taken |
+|---|---|---|---|
+| #523 | `deploy-prod-auto-promote` | 5 of 5 | `continue`, `continue` |
+| #400 | `help-usage-accuracy` | 3 of 4 | `continue` |
+| #405 | `condition-c-prose-evidence` | 2 of 5 | `continue`, `continue` |
+
+19 of 27 decisions were `continue`. **Corrected 2026-07-26:** that audit also reported `split` "never on a real unit", and re-measuring 246 live manifests / 602 units shows otherwise — **continue 17 · design 6 · split 5 · descope 0**, with three further splits in epic-848 recorded only as blocker prose that never reached the breaker at all. `split` is the second most common explicit decision; `descope` really is zero. The stale half of that sentence was used to argue against automating `split` before anyone re-measured, which is the hazard of quoting an audit without re-running it. A rule an agent applies from memory mid-gate degrades to its cheapest branch — the same failure class as the paraphrased `/grill-with-docs` redirect and the relative-`skillsRoot` lookalike. The data that decides it was in the manifest the whole time, so the diagnosis is a computation, not a judgment.
+
+Recurrence counts **rounds, not mentions** — a round listing eight themes is one round of evidence about each, and counting mentions would let a single scattergun review outvote a genuine streak.
+
+## The recurring-theme remedy — applied once, before a human is spent
+
+A recurring theme does **not** go straight to a split. The doctrine already prescribes the fix (SKILL.md: *close the invariant class, not the counterexample*), and #523's five rounds were five *instance* fixes — the remedy was never applied. So the first firing on a recurring theme mandates it:
+
+> One more round, class-complete on that theme: force full scope (withhold `lastReviewedSha`) and require the fix to name the invariant class it closes and the adjacent members it checked.
+
+Recorded as `units[].breaker.classCompleteFor`. If the theme **survives** that round, the unit is mis-sized and the next firing takes the `split`/`descope` decision — the split is the loop's under `autonomy: autonomous` and the human's under `supervised`; a descope is the human's at every level.
+
+The mandate is spent only when its authorized round **completes** — not when it is recorded. Reading its mere existence as "already tried" flips the diagnosis to `split` the instant it is written, so the class-complete round never runs and every recurring theme escalates straight to a human: worse than the prose version, on exactly the units this exists to keep moving.
+
+## What the loop decides on its own (`breakerAutonomy`)
+
+Default **`auto`**; `run-state.mjs set <slug> breakerAutonomy ask` restores a stop on every firing (and `--autonomy ask` overrides it for one invocation). The split is by **reversibility, not convenience**:
+
+- **`continue` — autonomous.** Spends one more bounded round. Cheap, reversible, ceiling-capped.
+- **`design` — autonomous.** Routes to `/grill-with-docs`, which is *itself* a human interview, and `record-intake-reentry` already refuses it unless the contract SHA moved. Automating the decision does not remove the human; it stops asking permission to ask them.
+- **`split` — the loop's under `autonomy: autonomous`, the human's under `supervised`.** A split *re-slices*; it does not ship less, which is what separates it from `descope`. It also fires precisely where the loop hurts most: a unit that survived three failing review rounds plus a class-complete mandate carries the largest diff and the longest finding list, so every further round costs the producer and the reviewer their scarcest resource. Splitting is the one remedy that shrinks the per-round load rather than adding to it — and that matters more the tighter the implementer's context is. Enforced in state, and the record carries its own authorization: `autoApplied: true` on a split is refused unless the same breaker entry stamps `autonomyAtDecision: "autonomous"`. Auto-applied or not, a split that **drops** a slice owes a `deferrals[]` entry with a tracking issue — without one it is a `descope` wearing another label, and `deferrals` already refuses an untracked entry.
+- **`descope` — always the human's, at every level.** It is the one decision that delivers less than was asked, and the one failure that leaves no trace in the handoff: every other autonomous decision shows up as rounds spent, which is visible. Zero uses in 602 units. Enforced in state — `autoApplied: true` on a descope is a validation error however it is stamped.
+
+`record-breaker-decision --auto` takes the computed decision; it **refuses** rather than falling back to a human-shaped write, because a silent fallback there would be the loop recording a decision nobody made. Every autonomous decision is stamped `autoApplied: true` + `signal`, so the handoff separates what the loop decided from what you did.
+
+**The ceiling.** Autonomy removes the human stop that used to bound the loop, so `BREAKER_TOTAL_ROUND_CEILING` (**8**) replaces it: no auto-decision at or above it, ever. Observed round counts across the audited units were `1:23  2:14  3:10  4:5  5:3  8:1` — a unit reaching 8 has spent more rounds than any that ever converged. Past the ceiling the breaker is a hard stop-and-ask whatever the diagnosis says; the epic-848 grind is the failure this number makes unreachable. It binds the **autonomous** path only — a human deciding on round 9 has seen the round count and is making an informed call, which is exactly the state the breaker wanted to reach.
+
+## When it does reach a human
+
+**Hand a diagnosis with a recommendation, never a neutral menu** — `diagnose-breaker` emits the text; pass it through rather than re-writing it (a paraphrase like *"do a design reset"* loses the `/grill-with-docs` redirect, which is the whole point). Then list the rest (split / design pass / descope / continue).
+
+**A second consecutive NEEDS_CHANGES on the same theme is an input to the diagnosis, not a rung of its own.** It means the implementer is circling a blind spot *or the reviewer is over-blocking*, and you cannot tell which — you don't read the diff, and the reviewer grades its own bar. That ambiguity is why `THEME_RECURRENCE_LIMIT` is 3 and not 2. Carry it into the diagnosis explicitly; don't let it quietly become "the implementer is wrong."
+
+**A decision that contradicts the computed recommendation warns, never fails.** The human may see what the round log cannot. But it is surfaced by `validate` — a *logging* gate that can hard-fail is one an orchestrator learns to stop calling, and this warning is what would have flagged #523/#400/#405 while they were still running.
+
+## Routing, enforced in state
+
+- **`continue`** authorizes exactly one further round. Then the gate re-fires. Under `auto` this re-fire costs no interrupt, which is why the grant stays at 1: every firing re-runs the diagnosis against the newest round, so a unit that starts converging is re-read as converging.
+- **`design` / `split` / `descope`** block every fix and review transition until `record-intake-reentry` marks the unit as having gone back through intake (re-entering from the top — scope, design, and risk gates included), which grants a fresh round budget.
+- Rounds beyond what a decision authorizes are **invalid manifest state** — what catches a lean-lane unit that advances through `upsert-unit` and never touches a transition command.
+- **A design decision is authorized by the artifact, not by the word — and a decision cannot be taken twice.** Both are mechanized in `record-intake-reentry`, because the failure looks like progress: the human decides, the loop re-enters, and the producer runs again against the *same* contract that fired the breaker. So (i) a `design` re-entry requires `units[].contractRevision.sha` to have **moved** since the firing (the breaker stamps `contractShaAtDecision`; re-entry compares against it), and (ii) a decision that already spent a re-entry on this unit cannot buy a second one — a repeat is a hand-back, and the human takes a *different* decision or the unit leaves the loop. The other decisions stay reachable, so this is a hand-back, never a dead end.
+
+A stop-and-ask, never an auto-abandon.
+
+(Named incidents: ten rounds re-deriving an unwritten contract; a first firing that handed a recommendation-free menu and paraphrased away the `/grill-with-docs` redirect; seven rounds over ~6.4 hours with no breaker state ever written, because prose cannot refuse a transition; epic-986 unit #996, which fired → `design` → re-entry → fired again on review-rounds → `design` → re-entry, both firings correctly diagnosing the same unwritten trust boundary, ~5 of the run's 7 hours on that one unit, with the archive recording both laps and refusing neither.)

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

@@ -0,0 +1,27 @@
+# Deliverables: the shippable component, not the whole epic
+
+How a passing unit becomes a delivered, merge-ready component. Previous:
+[loop.md](loop.md). The queue mechanics this consumes live in
+[delivery.md](delivery.md).
+
+## Deliverables: the shippable component, not the whole epic
+
+Per-unit green proves each PR **in isolation**. The integration gate closes that blind spot, but the deliverable it produces is scoped to a **component**, not the epic. → [why](why.md#the-component-not-the-epic)
+
+**A component is a maximal set of units that must merge together:** units bound by a **shared surface** (the integration-risk class — one slice's test asserts a button a sibling deleted) or by an **unmerged dependency edge** (a stacked unit references its dependency's symbols, so it can't merge before that dependency is in the target). Units in separate components have neither reason to be coupled — bundling them into one epic-wide PR is what lets a single stuck unit freeze finished ones.
+
+**The integration gate runs per component, progressively and then terminally** — [references/integration-gate.md](integration-gate.md) via [`scripts/combine-and-verify.mjs`](../scripts/combine-and-verify.mjs). Every preliminary unit PASS updates the candidate so conflicts and integrated-test failures surface before the roster finishes. Once complete and clean, freeze the candidate; then run one terminal exact-head integrated CI + review + smoke and record its component-HEAD authorization. `ALIVE` plus that authorization and a combined PR (CI green on its own HEAD, `Closes #<n>` per unit, unit PRs drafted + cross-linked) is the component deliverable. Single-unit components use their unit PR but still freeze and terminally authorize the assembled target-based candidate.
+
+**When smoke genuinely cannot run** — a repo with no bootable surface and no curated golden-path manifest (this skills repo is the standing example) — record `gates.smoke = 'not-applicable'` **with a `smokeNotApplicableReason`**; the reasoned N/A reaches `ALIVE`, an unreasoned one stays DEAD, and fabricating an `ALIVE` the app never earned is still forbidden. A **`no-surface` unit takes this same path** — not a skip, and no new machinery: the only difference is that its reason is **derived from the scope class** (`scope-class.mjs`'s `scopeSmokeReason`, carried as `smokeNotApplicableReason` in the classifier's JSON) rather than written per run. Guardrails in full: [integration-gate.md § step 4](integration-gate.md).
+
+**A component is *independently shippable* when** its own bar is met — every unit merge-ready (CI-green + independent APPROVE on its HEAD), integration verdict `ALIVE` — **and every dependency it needs is already merged into the target.** Note the direction: a completed *upstream* component ships even while *downstream* dependents are stuck; a dependency never waits on its dependents.
+
+**`merge-ready` is not an exit — it means a component member is awaiting delivery, and delivery is gated like every other transition.** Once every valid declared member reaches it, the component owes one **terminal outcome**: `merged`, or `handed-back` with `blockedOn` quoting the unsatisfied condition verbatim from the merge tool. Anything else is in-flight, and the handoff reports its members **undelivered, not done**. Record the authorized generation once with `run-state.mjs record-component-delivery-attempt|observation|outcome`; older manifests lacking a component record retain the legacy unit commands.
+
+**Only ancestry is a result.** A merge tool's return code, a queue acknowledgement and an auto-merge flag are all *requests* — `merged` owes a `mergedSha` proved contained in the freshly-fetched `origin/<targetBranch>` by [`combine-and-verify.mjs delivered`](../scripts/combine-and-verify.mjs), and on a queue that SHA is the PR's **merge commit**, not its branch head. → [why](why.md#delivery-only-ancestry-is-a-result)
+
+**The merge path is a pre-flight decision (`deliveryMode` **and** `queueProvider`), probed and never assumed** — [`detect-delivery-mode.mjs`](../scripts/detect-delivery-mode.mjs). The probe fails closed, and `record-component-delivery-attempt` refuses an action that does not belong to the run's mode or current terminally authorized component generation. **The mode picks the state machine; the provider picks the mechanics** — `queue` is two flows (Mergify, GitHub-native) differing in how you enqueue, where state is read, what a dequeue reason is called, and whether a nudge or an acknowledgement exists at all. Ask `run-state.mjs delivery-flow <slug>` for this run's flow and its exact commands rather than reading prose and picking; a queue whose provider is unsettled refuses to act rather than guessing.
+
+**Merge only with the standing authorization (`mergeShippable`) and the authorized frozen component HEAD, only into `targetBranch`, never to production** — `combine-and-verify.mjs mergeable --component <id>` reads the combined PR's live `headRefOid` and fails closed unless it equals the current frozen candidate with terminal exact-head integrated evidence. Absent authorization the default holds: hand the component back merge-ready and merge nothing (guarantee 4). An epic is done when every component is either merged or handed back with its `ALIVE` verdict.
+
+The mechanics — the two flows and how to ask which one you are in, the three-step enqueue (eligible · requested · acknowledged), the stall-bounded watch with its one nudge, the dequeue-reason routing table, and the merge gate's own checks: [references/delivery.md](delivery.md).