Execute Backlog

---
name: execute-backlog
description: Use when ready to attack the GitHub issue backlog with discipline. Scans open issues, bundles related work into an efficient execution plan, executes the bundle with verification, then closes issues + writes a retrospective that includes self-improvement notes for this skill. Trigger phrases — "execute backlog", "work the backlog", "knock down P1 issues", "ship a bundle", "/execute-backlog".
user-invocable: true
---

# Execute Backlog

**Purpose:** turn the GitHub issue backlog into shipped work using a deterministic loop: SCAN → BUNDLE → PLAN → EXECUTE → VERIFY → UPDATE → RETRO. Each pass closes a coherent bundle of issues, leaves the repo greener than it found it, and writes a retro that improves the skill itself.

**Operating principle (Extreme Ownership):** every issue in the bundle is "owned" by the executing agent for the duration of the pass. No half-finished issues. No "punted" verification. If a bundle can't ship clean, the bundle gets descoped — not the verification.

---

## When to Use

- Backlog has ≥5 open issues with `priority:p1` or higher
- A sprint / release-gate moment: pick the next high-impact bundle
- User says "let's work the backlog", "execute audit-2026-05-21", "knock down the killswitch issues"
- Agentic team handoff: spawn one of these per worker, each owning a label-scoped bundle

**Don't use for:**
- One-off bug fixes (use `agent-tdd` directly)
- Backlog audit / re-prioritization (use `architecture-audit`)
- New feature work (use `reactive-feature-dev`)

---

## Inputs (declared by caller)

The skill MUST be invoked with at least one filter — never run unfiltered.

```yaml
filter:
  labels:       # optional: ["area:providers", "audit-2026-05-21"]
  priority:     # optional: "p0" | "p1" | "p2"
  phase:        # optional: "phase:C" | "phase:E"
  max_bundle_size: 5  # default 5; cap on issues per execution pass
  budget_minutes: 90  # default 90; abort if exceeded, descope cleanly
```

Caller examples:
- `/execute-backlog labels=audit-2026-05-21 priority=p1`
- `/execute-backlog labels=area:providers,phase:E`
- `/execute-backlog labels=health-sweep,priority:p1 max_bundle_size=3`

---

## Phase 1 — SCAN

Query GitHub for candidate issues matching the filter.

```bash
gh issue list \
  --state open \
  --label "<comma-joined labels>" \
  --json number,title,labels,body,createdAt,updatedAt \
  --limit 100
```

For each candidate, parse:
- Issue number, title
- All labels (especially `area:*`, `priority:*`, `verified`)
- Primary file/location (regex from body: `**Location:**` line)
- Verified-by present? (boolean — `**Verified-by:**` block in body)

**Filter rules:**
1. Drop any issue without `verified-by:` evidence — file a comment asking for verification; do not execute on unverified claims (the 2026-05-21 inflation pattern is the reason this rule exists)
2. Drop `phase:` mismatches if `phase:` filter was provided
3. Drop issues with the `blocked` label
4. Drop issues assigned to someone else
5. **Stale-premise check (added 2026-09-19).** If the issue body names a specific class/module/mechanism as the integration point (e.g., "alongside `OpenInferenceTracerLayer`", "extend the `X` table"), grep for it before planning a fix. If it no longer exists, the issue's whole fix-direction may be written against an architecture that has since changed shape — not just a file:line drift, a *premise* drift. Comment the grounding finding (what exists now, what the likely new fix shape is) and drop from the bundle for re-scoping; do not force an implementation against a stale design. (Reason: 2026-09-19 #31/#32/#33 spawn — three exporter/tracing issues all referenced `OpenInferenceTracerLayer` and a fixed "5 event pairs" mapping table, neither of which exist; tracing had since moved to a generic OTel `withSpan()` design. Implementing against the old premise would have shipped code nobody could review against the issue's own description.)

6. **Reachability probe for "silent swallow / fallback" reports (added 2026-09-28 v19).** When an issue alleges a swallowed error, silent no-op, or graceful fallback, **prove the branch is reachable before planning a fix**. Establish three facts in the SCAN output:
   - **(a) Error channel:** if the guarded effect is `Effect<_, never>`, a `catchAll` over it is **dead code** — the handler can never run.
   - **(b) Error vs defect:** `Effect.catchAll` catches typed errors only. A missing `Context.Tag` service is a **defect**, which it does not catch (the code will reject loudly, not fall back).
   - **(c) Precondition reachability:** is the service/tag optional or mandatory? If the runtime always provides it (e.g. `EventBus` is merged unconditionally in `createRuntime`), the "failure" cannot occur.

   Run a one-line probe (e.g. `bun run` the exact guarded pattern with the service unprovided) and record the observed result. If the branch is unreachable, the **honest root fix is deletion + an invariant comment**, and the issue closes as "premise falsified / dead code removed" — **never** wire observability (`emitErrorSwallowed`) into a branch that cannot execute. If the claimed *behavior* is disproven (not merely drifted), record the probe evidence on the issue and re-scope the deliverable; do not drop the issue and do not implement against the false description. (Reason: 2026-09-28 #224 — issue claimed `agent.subscribe()` "silently falls back to a no-op on EventBus resolution failure." Probe of the exact `catchAll` pattern with no EventBus supplied REJECTED with `Service not found: EventBus`; `subscribe`/`on` are `never`-error and `EventBus` is mandatory. The suggested `emitErrorSwallowed` fix would have added unreachable code; the shipped fix deleted the dead fallback and pinned delivery with 4 end-to-end tests.)

**Drift check (added 2026-05-21):** for any candidate carrying a verified-by command with file:line references, re-run the command. If the emitted line numbers differ from the issue body's claimed lines by **>5** on any row, mark the candidate `🟡 drift detected` and re-read the cited spans to confirm the semantic cast/pattern still matches. Counts can match while locations move 25+ lines — that means the surrounding logic refactored and the fix shape may no longer apply. Acceptable to proceed; not acceptable to skip the check.

**Drift check addendum (added 2026-05-21 v3): semantic-equivalent pattern grep.** When the issue body claims N sites but the primary grep returns fewer, the gap may be a *syntactic variant of the same anti-pattern*, not real drift. Before declaring `🟡 drift detected`, additionally grep the known equivalence classes:

| Primary pattern | Semantic equivalents to also grep |
|-----------------|-----------------------------------|
| `(x as any)` | `(x as unknown as {…})`, `(x as unknown as Record<…>)` |
| `: any` | `: unknown` (intentional widening), `: Record<string, any>`, untyped function-type `Function` |
| `as Function` | `(...args: any[]) => any`, `Callable` aliases |

If the **sum** of equivalence-class matches reproduces the claimed count, proceed (no drift — issue author counted across both forms). If the sum still falls short, mark drift and re-read the cited spans. (Reason: 2026-05-21 #71 spawn — issue claimed 7 sites; primary grep `(state as any)` returned 3; the other 4 lived under `as unknown as { … }` narrowings. Including both forms recovered the exact 7.)

**Exact-location parity (added 2026-09-25).** When an issue enumerates both a site count and file:line locations, rerun the pattern against every cited file and compare the complete emitted location set with the issue list. A count can be close while the location list omits a real site (e.g. #225 listed 8 but the four cited files contained 9, including an unlisted HITL builder chain). Record the actual paths/lines and mark the issue `🟡 drift detected` before bundling.

Output: candidate set, sorted by `priority:p0` > `p1` > `p2` > `p3`, then by `verified` label (verified issues rank higher), then drift-clean before drift-detected.

**Cross-package consistency probe (added 2026-05-22 v9).** When the issue touches per-framework / per-platform packages providing equivalent APIs (e.g., `@reactive-agents/react` + `@reactive-agents/svelte` + `@reactive-agents/vue` all exporting `useAgentStream`-style hooks/factories), briefly diff the impl shape across siblings:

```bash
# Side-by-side compare of equivalent files
diff packages/<sibling-a>/src/<file>.ts packages/<sibling-b>/src/<file>.ts | head -40
```

Same name + equivalent signature + **divergent behavior** = latent defect. Surface in the plan's "Adjacent improvement found" section. Fix opportunistically per the test+fix combo rule (Phase 4 v9). (Reason: 2026-05-22 #82 closeout — vue's `useAgentStream.StreamError` branch threw + was caught by inner try/catch; svelte's equivalent branch used direct `next.error = …; next.status = "error"` and worked correctly. Sibling diff would have flagged the divergence before the test had to.)

---

## Phase 2 — BUNDLE

Group candidates into one **bundle** (max `max_bundle_size`) that ships together. A bundle is *coherent* when ≥1 of these holds:

| Cohesion signal | Example |
|-----------------|---------|
| Same `area:*` label across all members | All `area:providers` |
| Primary files overlap (same dir, same package) | All under `packages/runtime/src/builder/` |
| Root-cause cluster | HS-06/07/08 all share "untyped state shape" |
| Cross-cutting fix shape | "Remove `as any` from N hook surfaces" |
| Untyped schema field needs structured access in callers | Local widening type + boundary helper inside the consuming package — see "default fix shape" below |

**Default fix shape for typing issues (added 2026-05-21 v5).** When the cited `as any` casts all narrow the same schema-typed-`unknown` field, default to:
1. Create `<domain>-context.ts` (or `-state.ts`) in the consuming dir.
2. Define `<Domain>Context = ExecutionContext & { <field>: <ConcreteShape> }` (interface mirroring runtime usage, NOT the schema source-of-truth).
3. Export `as<Domain>Context(c)` boundary helper — single named cast.
4. Migrate each cited site through the helper; delete the cast at sources where the field was already typed (dead-cast sweep — see Phase 4).

Three shipped precedents to copy from: #71 `HandlerState` (`packages/reactive-intelligence/src/controller/handler-state.ts`), #72 typed `BuilderState` option groups (`packages/runtime/src/builder/to-config.ts`), #73 `ThinkContext` (`packages/runtime/src/engine/phases/agent-loop/think-context.ts`). The pattern keeps each fix inside its consuming package (cross-package descope gate satisfied automatically).

**Bundling algorithm:**
1. Take the highest-priority candidate as seed
2. Greedily add candidates that share ≥1 cohesion signal with the bundle
3. Stop at `max_bundle_size` OR when no remaining candidate has cohesion ≥1 with the bundle
4. If the bundle has <2 issues after greedy growth → still proceed (singleton bundles are fine)

**Hard gate (added 2026-05-21): cross-package descope.** Before locking the bundle, re-grep each candidate's verified-by command and inspect the file paths it emits. If those paths span **≥2 packages** (`packages/<a>/…` vs `packages/<b>/…`), descope to a per-package bundle even if the issue body's "Fix direction" suggests otherwise. The body lies; the grep doesn't. (Reason: 2026-05-21 #73 spawn — body said "type properly in the think phase" but the actual `as any` targets resolved to types owned by `@reactive-agents/llm-service` and the kernel-context shape, both other packages.)

**Multi-package test-infra split (added 2026-05-22 v7).** The cross-package gate isn't only for typing/refactor issues — it applies the same way when an issue cites adding tests / infra / docs to N packages. Ship N bundles (one per package), each with its own PR. Name the follow-up bundles in the seed bundle's PR description so the queue is explicit. (Reason: 2026-05-22 #82 spawn — issue cited zero tests across `packages/react/`, `packages/svelte/`, `packages/vue/`. Shipped `bundle/react-smoke-tests` first; named `bundle/svelte-smoke-tests` and `bundle/vue-smoke-tests` as follow-ups in the PR body. Disjoint scopes, independent CI, no cross-package merge conflicts.)

**Output:** named bundle. Pattern: `<area>-<theme>` (e.g., `providers-untyped-hooks`, `runtime-builder-as-any-sweep`).

Open a new GH issue or use an existing tracker as the *bundle parent* — link it to all members via `Tracks: #N` lines. Apply the `tracking` label.

---

## Phase 3 — PLAN

For the bundle, write a concrete execution plan to `wiki/Planning/Implementation-Plans/YYYY-MM-DD-<bundle-name>.md`.

**Plan must contain:**

```markdown
# Bundle: <name>
Date: YYYY-MM-DD
Budget: <budget_minutes> min
Issues: #N, #N, #N

## Acceptance criteria (per issue)
- #N: <one-sentence done definition tied to the verified-by claim>

## Execution units (ordered)
1. **Unit 1:** <one or two issues, ≤45 min, files touched, tests touched>
2. **Unit 2:** ...

## Risk register
- <risk> → <mitigation>

## Verification protocol (cross-cutting)
- `bun test packages/<changed>/` — full pass
- `bun run build` — green
- `bunx turbo run typecheck --filter=<changed>` — green
- Sample replay or trace test if behavior change

## Out-of-scope (explicit)
- <thing> — punt to next bundle
```

**Root-cause direction check (added 2026-09-19).** When an issue proposes a root-cause hypothesis without having confirmed it end-to-end (e.g. "the suspect is X, needs a bisect"), grep the *consumer* of the broken value first — where it's read, aggregated, or reported — before chasing the *producer* the issue suspects. Metric/reporting bugs (a count computed via a fallback derivation, a field silently defaulting) commonly masquerade as behavior regressions in the producer's domain. (Reason: 2026-09-19 #207 spawn — issue suspected an entropy-scoring commit changed kernel termination behavior. The actual bug was in the gate runner's `iterations` metric, which had no real source field and fell back to counting `entropy-scored` trace events — a duplicate-event bug in the suspected commit inflated that count, but the kernel's actual iteration behavior never changed. Bisect correctly found the commit; several minutes were then spent reading kernel/entropy producer code before checking the metric's consumer, which held the answer immediately.)

**Plan gates:**
- If total estimated effort > `budget_minutes` → descope to fit; do NOT skip verification
- If any unit depends on infra not in the repo → mark `blocked` on that issue, drop from bundle
- If two units conflict (same file, conflicting changes) → sequence them, never parallelize
- If the fix arms a mechanism scoped to a lifecycle LONGER than the call site (a per-run meter armed per service call, a per-session cache armed per request), find the true once-per-scope boundary and arm there; make the inner service REUSE the ambient value. Arming at the nearest service seam lets sibling invocations with a different argument shape escape the scope (see "Scope-boundary arming" below).

**Scope-boundary arming (added 2026-10-05 v23).** A mechanism's arm site must match its declared SCOPE, not merely sit at a nearby seam. When an issue says "per run" / "per session" / "per agent" but the implementation arms it inside one service call, enumerate every OTHER way that service (or the enclosing lifecycle) is invoked and check whether each escapes the arm. If any does, move the arm to the true once-per-scope boundary and have the inner service prefer the ambient value. (Reason: 2026-10-05 #232 Gap 2 — the run-scoped budget meter was armed in `ReasoningService.execute`, so auxiliary passes that call `execute` WITHOUT `budgetLimits` (the verification THINK retry, the post-think continuation hooks) armed no meter and were unbudgeted. Fix: arm once at the runtime's `ExecutionEngine.execute` boundary (`engine/run-budget-arm.ts`) and make `ReasoningService.execute` reuse the ambient meter. Generalizes the production-seam test rule from "test at the seam" to "the seam must match the scope".)

**Extract-from-oversized-file (added 2026-10-05 v23).** When the wiring for a fix lands in a file already flagged by a size/decomposition issue, put the pure rule in a NEW module and test the helper in isolation rather than growing the flagged file. (Reason: 2026-10-05 #232 Gap 2 — the arming rule went into new `engine/run-budget-arm.ts` instead of inline in the already-oversized `execution-engine.ts` (#221), making it unit-testable and not worsening the size debt.)

**Substrate-aware test strategy (added 2026-05-22 v8).** When the bundle adds tests to a new framework/package, identify the test substrate up front. Three classes:

| Substrate | Examples | Default coverage |
|-----------|----------|------------------|
| **Render-bound** | React hooks, Vue `setup()`, web components | Public-surface smoke + type contracts. Behavioral via render = follow-up bundle (justify the `@testing-library/X` + happy-dom investment separately). |
| **Framework-agnostic** | Svelte stores (`writable`), Solid signals, Effect.Effect | Behavioral coverage with mocked I/O (e.g., `globalThis.fetch = async () => new Response(...)`). No DOM/render needed. |
| **Pure** | Plain JS factories, helpers, parsers | Behavioral coverage directly. No mocking infrastructure beyond stub inputs. |

Picking the wrong default = scope creep (render-bound bundle pulled into the test-infra rabbit hole) or coverage gap (framework-agnostic bundle capped at smoke when behavioral was cheap). (Reason: 2026-05-22 #82 spawn — react bundle (#100) capped at 6 smoke cases due to render-context requirement; svelte bundle (#101) shipped 13 cases including 9 behavioral because stores work in any runtime. Coverage gap would have been ~half if both bundles defaulted to "smoke only".)

When in doubt, write one case at the framework-agnostic tier and see if it runs under bare `bun:test`. If yes, proceed behavioral. If "Invalid hook call" / setup errors → drop to smoke + name the follow-up bundle.

**Cast-ceiling impact of new test files (added 2026-09-25 v17).** Before designing any new test file under `packages/*/tests/`, check whether it will introduce `as unknown as` casts. This repo enforces TWO separate ratchets in `packages/runtime/test/as-unknown-as-ceiling.test.ts`: a `packages/*/src` ceiling (`CEILING = 78`, includes colocated `__tests__`) and a `packages/*/tests` ceiling (`TESTS_CEILING = 237`). **Neither is seen by a package suite or typecheck** — they are separate gates, and both may already be red from unrelated drift. Require the new test to contribute **zero** `as unknown as` sites. Build fixtures with typed constructors (e.g. `initialKernelState` + `transitionState`, a fully-typed service double) rather than `as unknown as`. `{} as never` is the existing sanctioned placeholder for unavoidable structural gaps and is NOT counted, but prefer a real typed stub. Add `bun test packages/runtime/test/as-unknown-as-ceiling.test.ts` to the bundle's verification protocol and record the pre/post site counts. Do not bump either ceiling to accommodate the bundle. (Reason: 2026-09-25 reasoning-silent-failure #223 — warden pass 1 added 3 test-fixture casts, taking the tests-scope count 266 → 269 on an already-red gate; caught only by the parent running the ceiling test, corrected to 0 net with typed fixtures.)

Read the `superpowers:writing-plans` skill conventions (location override: `wiki/Planning/Implementation-Plans/`).

**Extraction/dedup bundles must cover every call site (added 2026-09-28 v18).** When a bundle extracts duplicated logic into a shared helper, the bundle's test net must exercise **every former owner** of that logic. If an existing parity test covers only one of N call sites, add tests for the uncovered sites in the same bundle (a test+refactor combo). Otherwise a behavior divergence at the uncovered site ships silently — the extraction "succeeds" while one provider regresses. Acceptance check: grep the duplicated symbol to **0** in every former owner (not merely "the helper exists", which can coexist with leftover duplicates). (Reason: 2026-09-28 providers-stream-accum #216 — the shared accumulator extraction was pinned for litellm by `litellm-stream-tool-calls.test.ts`, but openai's stream path had no tool-call coverage at all; the bundle added `openai-stream-tool-calls.test.ts` (2 parity cases), which is what actually proves the openai rewrite preserved behavior.)

**Fire-site reachability check (added 2026-05-21 v4):** before designing integration-style tests for any unit, grep the call graph to verify the test scenario will actually exercise the code under fix. A hook/handler/wrapper can be **registered** without being **fired** if the test scenario routes through an alternate code path (e.g., `withTestScenario` short-circuits the reactive loop and bypasses `runner.ts:683` `runPhaseHooks`). Quick check:

```bash
# 1. Locate where the unit under fix gets invoked
grep -rn "<wrapper-or-helper-name>\|<registered-fn-pattern>" packages/

# 2. Confirm at least one fire site is reached by the planned test config
#    (provider, reasoning, strategy, test scenario, etc.)
```

If reachability is uncertain, **default to direct-invocation tests** (instantiate the helper / pull from registry / call wrapper directly) rather than full-stack `agent.run()` tests. Reason: 2026-05-21 #74 spawn — initial test design called `agent.run()` with `withTestScenario` + `withReasoning()`, expecting the harness `before('think')` wrapper to fire. It never did. Probes confirmed the wrapper was registered but the kernel-loop fire site was bypassed. Direct invocation via `RegistrationHarness._collected` pinned the unit in 6 tests, 0 flakes.

**Adjacent-improvement detection at baseline (added 2026-05-25 v11).** When the post-branch baseline `bun test` or `bunx turbo run typecheck` reports failures in the SAME package as the bundle, scan each failure's fix-shape against the bundle's root-cause class:

| Baseline failure type | Adjacent-improvement test |
|------------------------|---------------------------|
| Typecheck red w/ identical anti-pattern as cited verified-by | Add to bundle. Same helper / fix shape. No scope creep. |
| Pre-existing test fail in untouched code path | File follow-up issue; don't block bundle. |
| Lint warning in adjacent file with shared fix recipe | Add to bundle iff ≤5 LOC delta and same package. |

If adjacent improvement adopted, **update the plan doc's "Adjacent improvement found" section** AND broaden the verified-by recheck command from per-file to workspace-wide (or per-package-wide). Generalization of the v9 "test+fix combo" rule. (Reason: 2026-05-25 #85 spawn — baseline typecheck flagged 5 errors in `tests/controller/dispatcher-compose-bridge.test.ts` with identical `InterventionHandler<TDecision>` contravariance root cause as the cited 9 sites in `handlers/index.ts`. Bundling them added 9 helper applications, 0 LOC of new design, silenced all 5 errors. Excluding them would have left a follow-up bundle with one-line diff each — wasteful.)

---

## Phase 3.5 — BRANCH (mandatory)

Before any code edits land, create a dedicated feature branch off `main` for the bundle.

**Local-main-ahead check (added 2026-08-16 v13).** Some repos hold work on local `main` unpushed until a release/tag event (e.g. `reactive-agents-ts` itself — see `.agents/MEMORY.md`'s repo-workflow note). Branching from `origin/main` in that case silently drops every local-only commit from the new branch's base. Check first:

```bash
git fetch origin main
git log --oneline origin/main..main | wc -l
```

If non-zero, branch from local `main` instead — those commits are real, intentional, and the bundle should build on top of them:

```bash
git checkout -B bundle/<bundle-name> main
```

If zero (origin and local main agree), the original form is correct:

```bash
git checkout -B bundle/<bundle-name> origin/main
```

Naming pattern: `bundle/<area>-<theme>` (e.g., `bundle/runtime-builder-state-typing`). The branch is the unit-of-work for the entire bundle. All commits in Phase 4 land here; the Phase 6 PR (or local merge, see Phase 6a's hold-until-tag note) ships them together.

If the working tree is dirty when this skill is invoked, **stop** and surface the dirt — do not stash silently. The caller decides: commit, discard, or move out of the way. (Reason: per `feedback_commit_before_branch.md`, exploratory state must not get mixed into bundle commits.)

**Live-peer check (added 2026-08-16 v12).** A clean/acknowledged dirty-tree check at branch time is a snapshot, not a lock — it says nothing about whether another agent session is actively mutating the same checkout during EXECUTE. Before the first `git add` in Phase 4, and again immediately before every `git commit` in this bundle, call `ListAgents` (or the harness equivalent) and check for other **non-idle** sessions. If one is active on the same repo path, treat it as a hard-stop: wait for it to go idle before staging/committing, don't proceed on a guess. `git add <specific files>` does NOT protect against this — the index is shared process-wide, not per-agent-session, so a peer's `git commit` (even a plain `git commit -m ...` with no path args) sweeps up whatever you staged a moment earlier into THEIR commit. The only real isolation from a genuinely concurrent session is a dedicated worktree (`superpowers:using-git-worktrees`); the `ListAgents` check is the cheap mitigation when a worktree wasn't set up. (Reason: 2026-08-16 #198 spawn — a second live session's `git commit` on the same checkout swept 8 staged bundle files into an unrelated commit; recovery via `git reset --soft HEAD~1` itself raced the same peer recommitting mid-recovery. Caught only by manually running `ListAgents` and confirming the peer had gone idle before redoing the split.)

**Branch-before-edit discipline (added 2026-08-18 v15).** SCAN/BUNDLE/PLAN research (reading files, grepping, running `madge`/`grep`/`find` to verify claims) is allowed on `main` before the branch exists. The moment a fix's shape is understood well enough to write one line of it, `git checkout -B bundle/<bundle-name> <base>` MUST run first — do not let "I'm just confirming the fix works" turn into an Edit/Write call while still on `main`. If it happens anyway, don't panic-revert: `git checkout -b bundle/<name>` from the current commit carries uncommitted working-tree changes onto the new branch (same commit, so nothing is lost), then `git add` only the intended files before the first commit — leave any unrelated pre-existing dirt (build-generated timestamp files, etc.) unstaged. (Reason: 2026-08-18 #184 spawn — investigation flowed directly into a type-extraction edit on `main` with no branch created; caught before the first commit, recovered via post-hoc branch-from-same-commit + selective staging, zero actual harm, but the skill's own Phase 3.5 ordering should have prevented needing the recovery at all.)

**Baseline capture (added 2026-05-21):** immediately after branching, pin the pre-EXECUTE state:

```bash
bun run build 2>&1 | tail -3   # → record "Tasks: N/N successful"
bun test 2>&1 | tail -3        # → record pass/fail/skip counts
```

Stash the numbers in the plan doc under a `## Baseline` heading. Phase 5 compares against these; pre-existing reds get filed as follow-up issues (see #93 pattern) rather than blocking the bundle. Without this baseline, a pre-existing failure surfaced by your edits looks like a regression and you'll burn budget chasing it.

---

## Phase 4 — EXECUTE

For each execution unit, follow `agent-tdd` discipline:

```
RED   → write/find failing test demonstrating the issue
GREEN → minimum fix that turns the test
REVIEW → run review-patterns; address findings
COMMIT → conventional commit, citing GH issue numbers
```

**Warden-brief test-seam rule (added 2026-09-28 v18).** When a MissionBrief asks a warden to add a provider/adapter streaming test, specify the package's **established mock seam** — never "drive the real SDK through `globalThis.fetch`/`Response`". Module mocks in Bun (`mock.module`) are process-global and leak across test files in the same package: a preceding suite's SDK mock shadows the real one, making real-SDK streaming non-deterministic in-suite. Point the warden at an existing test that already uses the correct seam (e.g. `openai-nonok-guard.test.ts` / `openai-cache-usage.test.ts` for the openai SDK), and name the caveat in the brief. (Reason: 2026-09-28 providers-stream-accum #216 — the brief mandated a real-`Response` fetch mock; it passed in isolation but failed in the full suite due to `mock.module` leakage documented at `provider-adapter-wiring.test.ts:102`; the warden correctly fell back to the module-mock seam after one round-trip.)

**Mechanism-isolation rule for integration tests (added 2026-10-05 v22).** When a bundle adds a mechanism whose observable effect is *masked by a pre-existing fallback or gate*, an integration test that only asserts the final outcome does NOT prove the new mechanism works — the old gate can produce the same outcome. Two acceptable discharges: (a) construct a scenario where ONLY the new mechanism can produce the result (e.g. each sub-kernel stays under the limit but the cumulative sum crosses it), or (b) pin the isolation at the unit level (call the new consumer directly with inputs that distinguish new from old) and state in the retro that the end-to-end tests prove *wiring*, not *causation*. (Reason: 2026-10-05 run-level-budget-meter #231 — the warden's plan-execute/blueprint strategy tests halted on `tokenLimit: 1`, which also trips the pre-existing strategy gates AND the per-kernel guard; the meter's unique run-scoped contribution was isolated only in the unit test. Honest retro recorded this rather than claiming a clean per-strategy proof.)

**Production-seam test requirement (added 2026-10-05 v22).** When a mechanism is wired at a service entry point (the changed module is one layer, but the value is *armed/created* in a caller), a MissionBrief that asks only for module-unit tests is under-specified: unit tests that set the value up manually bypass the production wiring entirely. Require a test at the real entry seam (the service's `execute`/`run`/handler) that proves the wiring arms the value and the downstream consumer sees it. (Reason: 2026-10-05 #231 — the warden's kernel tests called strategies directly with the meter pre-set, so `ReasoningService.execute` arming the meter was untested; the parent added `services/reasoning-service-run-budget.test.ts` and the first draft failed typecheck, caught only by the full workspace typecheck.)

**Warden dispatch under a harness without warden agent types (added 2026-10-05 v22).** Not every harness exposes the repo's `.claude/agents/*-warden` definitions to its subagent tool (this repo's OpenCode harness exposes only `explore`/`general`). When the warden type is unavailable, dispatch the generic subagent with the warden's `.md` definition + domain primer + a valid MissionBrief embedded in the prompt, require the `upward-report` block, and record the deviation in the retro. Do NOT silently skip the warden gate or implement the domain edit on the main thread without saying so.

**RED authority check (added 2026-05-25 v10).** Before relying on a RED test to pin a missing type or field, check **two harness conditions** that can silently mask the RED:

1. **Tests excluded from typecheck.** Run `grep -A2 '"exclude"' packages/<X>/tsconfig.json` — if `"tests/**/*"` is excluded, missing-type errors in the RED test will NOT fail typecheck. The "RED" passes against pre-fix state at type level.
2. **TaggedError / structural-type leniency.** Effect's `Data.TaggedError` stores any field passed to its constructor, even if the payload type doesn't declare it. `expect(err.newField).toBeDefined()` will pass against pre-fix state if the test constructs the error with `newField`. Same for plain TS structural types — passing extra properties to a struct constructor is accepted at runtime.

When either holds, the RED is post-hoc regression coverage only — it doesn't prove the pre-fix state was broken. Acceptable; just note in the plan's risk register and don't claim "test failed before fix, passes after" in the retro unless you confirmed it. To strengthen RED authority for type fields: write a temporary `src/.test-types.ts` smoke file that imports and destructures the new field, run `tsc --noEmit` on src/, then delete the smoke file before commit. Overkill for most fixes; flag only when the pre-fix RED must be authoritative.

**File-swap RED technique (added 2026-09-25 v17).** For a behavior-additive fix (diagnostics, event emission, logging — where the new test asserts an artifact the pre-fix code cannot produce), prove RED without `git stash`: `cp <wired-file> /tmp/opencode/<file>.wired.ts` → `git checkout -- <file>` → run the new test (expect fail) → `cp /tmp/opencode/<file>.wired.ts <file>` → confirm `git diff --stat` is restored. `git stash` risks a conflicting pop if the tree moved; the `/tmp` copy is unconditionally reversible. This is the cheapest authoritative RED for "the event/return value did not exist before". (Reason: 2026-09-25 reasoning-silent-failure #223 — file-swap gave a clean 2-fail/0-events pre-fix proof with zero stash risk.)

**Fiber-interruption regression test construction (added 2026-08-16 v14).** When a regression test forks a fiber specifically to interrupt it later (proving fiber-supervised cancellation — e.g. "does interrupting this Effect actually stop the underlying work"), keep the fork, the wait-for-condition, and the `Fiber.interrupt` call inside ONE `Effect.gen` / single `Effect.runPromise` call. A bare `Effect.runPromise(Effect.fork(effect))` returns a `Fiber` handle, but the ephemeral scope created for that one `runPromise` call closes immediately after `fork` returns — which can interrupt the child fiber before the test ever gets to observe or deliberately interrupt it. This reads as "the fix doesn't work" (the condition you're polling for never becomes true) when it's actually a test-authoring bug, not a fix bug — verify with a quick throwaway debug script logging fiber state before concluding the production fix is wrong. (Reason: 2026-08-16 #35 spawn — a code-action Worker-interruption regression test's first draft forked outside the observing `Effect.gen`, silently self-interrupting before the sandboxed code reached its first tool call; cost several minutes chasing an unrelated red herring (`effect` version dual-package hazard in a `/tmp` debug script) before finding the real cause.)

(Reason: 2026-05-25 #75 spawn — RED test `parse-error-attempts.test.ts` was written expecting typecheck failure on `ParseAttemptError` not-yet-exported and `LLMParseError.attempts` not-yet-declared. Both conditions held: `packages/llm-provider/tsconfig.json` excludes tests; `Data.TaggedError` stored `attempts` field at runtime regardless of type declaration. The "RED" passed against pre-fix state. Fix still landed clean; lesson is to not over-claim RED→GREEN narrative in retros when these conditions hold.)

**Single-area mechanical-scaffold bundle template (added 2026-05-25 v10).** When N sites in **one package** share an identical scaffold (same imports, same control flow, same fix shape), prefer **mechanical in-place edit** over helper extraction. Heuristic:

| Condition | Action |
|-----------|--------|
| N ≤ 10 sites, same package, identical scaffold | Mechanical push/edit at each site. Verified-by = `grep -c '<new-pattern>'` returns N. |
| N > 10 sites, OR scaffold spans packages, OR scaffold has 3+ divergent variants | Extract helper. Test helper directly with mocked inputs. |

Mechanical edit wins on review surface (one shape to verify N times) and ships faster. Helper extraction trades that for de-duplication; only worth it when the dup cost exceeds the abstraction cost. (Reason: 2026-05-25 #75 — 5 providers × ~50 LOC identical retry loop. In-place push of 2 lines per provider beat extracting `parseStructuredWithRetry` helper on budget AND eliminated SDK-mock test complexity. Verified-by `grep -c parseAttempts.push` → 10 caught all sites in one check.)

**Cross-runtime RED-test misattribution (added 2026-09-19 v16).** When the mechanical fix is environment-specific (e.g. code that branches on `isBun`/`isNode`/`isWorkerd`), a RED test simulating the *target* environment (workerd) still runs inside the *actual* test environment (Bun/Node) — the mock only fakes the failing primitive, not the runtime-detection flags the code branches on. A failure can then come from a branch that's real in the test's actual environment but unreachable in the real target environment. Before concluding the fix under test is wrong, read the failure's stack trace for which branch fired and check whether that branch is even reachable on the real target runtime. (Reason: 2026-09-19 #205 spawn — `database.ts`'s eager `export const Database = loadDatabase()` hit its unguarded `isBun` branch under `bun test`, not the guarded non-Bun branch a real workerd run would take. Looked like the lazy-`createRequire` fix was broken; was actually a pre-existing missing try/catch in a branch the real bug report never touches.)

**Dead-cast sweep (added 2026-05-21 v5).** Before migrating each cited `as any` site through a new helper, check whether the underlying type already supports the access pattern (the schema may have been tightened since the cast was added; the cast was historic). Delete dead casts outright — lighter diff, no helper indirection, less maintenance. Procedure for each site:

```bash
# Read the cited line's surrounding context
# Check the field's type in the schema (e.g., `packages/runtime/src/types.ts`)
# If the type already covers the access → delete the cast
# If `unknown` / `any` / missing field → migrate via the boundary helper
```

(Reason: 2026-05-21 #73 spawn — 2 of 9 cited `(c as any).selectedStrategy` casts were dead because `selectedStrategy` was already `Schema.optional(Schema.String)` on the schema. The casts were historic from a pre-typing era and could be deleted without any helper plumbing.)

**sed-after-Edit hazard (added 2026-05-25 v11).** When mixing the `Edit` tool (precise per-site) with bulk `sed -i 's/A/B/g'` in the same file/session, sed's pattern may **re-match Edit-wrapped sites** when the post-wrap suffix overlaps the search pattern's tail. Example: wrapping `fixedHandler(...)` with `asInterventionHandler(fixedHandler(...))`, then running `sed 's/registerHandler(dispatcher, fixedHandler(.*));$/.../' ` will re-match Edit-wrapped sites because both pre-wrap and post-wrap lines end with `));`. Result: extra paren on already-wrapped sites, syntax break, lost minutes.

Procedure:

```bash
# Before bulk sed, verify no prior-wrapped sites exist
grep -c "<post-state-tail>" <file>   # e.g., grep -c "asInterventionHandler(fixedHandler" file
# If > 0 → DO NOT use sed. Use Edit with replace_all=true per unique site.
# If == 0 → safe to sed; verify with typecheck immediately after.
```

(Reason: 2026-05-25 #85 spawn — 4 Edit-wrapped sites at lines 104, 129, 130, 131 ended up with extra `)` after sed re-matched them. Caught by `tsc TS1005: ';' expected` within seconds; fixed with one `replace_all` Edit. Cheap to fix, but trivially avoidable by pre-grepping post-state.)

**Same-session multi-bundle protocol (added 2026-05-21 v5).** When chaining bundles in one session, **each subsequent branch MUST be created from `origin/main`, not from the previous bundle's branch.** Stacking bundles undermines the verified-by gate — a subtle regression in bundle 1 would mask in bundle 2's tests (or worse: cause bundle 2 to attribute its failures incorrectly). Each bundle:

1. branches off `origin/main` clean (`git checkout -B bundle/<name> origin/main`)
2. ships its own PR
3. is merged independently — never auto-merged

This session (2026-05-21 night+1) shipped #97 + #98 disjoint via this protocol; total ~1h45m. Worth pinning.

**Commit message template:**
```
fix(<package>): <short description>

Closes #N (bundle: <bundle-name>)
<one line on what changed>
<one line on what verified it>
```

**Test-path fallback (added 2026-05-21 v4):** if a planned RED integration test cannot reach the unit under fix after one debug round (e.g., wrapper registers but never fires), **stop debugging the test scaffold and switch to direct invocation**. Pull the registered handler/wrapper/helper from its registry (e.g., `RegistrationHarness._collected`, `LifecycleHookRegistry.list()`) and call it directly. Direct-invocation tests:

- pin the unit faster (sub-second runs vs full agent.run loops)
- isolate the fix from orthogonal config (provider, reasoning, scenario)
- match the cohesion signal: if the issue cites a *single file:line*, the test should hit *that line* without depending on a deep call chain

When in doubt, write the direct-invocation test first; expand to integration coverage only if multi-component interaction is actually under fix.

**Path-aware verified-by (added 2026-05-21 v4):** when a single file:line cited by an issue is fired from **multiple call-graph paths** (e.g., engine `LifecycleHookRegistry` AND harness `HarnessPipeline` both invoke the same hook handler), the issue's symptom may already be partially fixed by one path while the other still has the bug. Before locking the bundle scope, grep callers of the cited site and document in the plan which paths actually exhibit the symptom. The fix may be narrower than the verified-by suggests. (Reason: 2026-05-21 #74 — the engine path already escalated sync throws as defects through `Effect.catchAll`, surfacing them to `reactive-agent.ts:549` and firing `_errorHandler`. Only the harness duplicate-fire path was truly silent. A naive fix targeting "all hook error paths" would have overscoped.)

**Dead-code sweep (added 2026-05-22 v6).** Before applying the issue's prescribed fix, check whether the cited code is **dead in the current codebase state**. Deletion is preferable to migration/replacement when the original purpose is already satisfied elsewhere. The check applies broadly:

| Cited surface | Dead-code check |
|---------------|------------------|
| `as any` cast | does the underlying type already cover the access? → delete cast |
| `test.skip("RED…")` placeholder | did the targeted mechanism ship ✅ KEEP per phase-1/health-sweep evidence? → delete block |
| Helper function only referenced by deleted code | grep for inbound refs → delete |
| Interface/type only used inside a deleted span | same — delete |
| `TODO` on live code path | does the followup issue exist OR is the work obsolete? → wire or remove per HS-23 pattern |

When deletion is the right action, also confirm the issue's verified-by points at a stable external artifact (phase-1 evidence, MEMORY.md verdict, audit report) — that's what makes "delete" safe vs "replace with TBD". (Reason: 2026-05-22 #80 spawn — `m1-dispatcher-validation.test.ts:65` `test.skip("RED phase…")` was 110 LOC of placeholder. M1 had already shipped ✅ KEEP per `harness-reports/phase-1-mechanism-validation-2026-05-04.md`. Pure deletion was correct; replacement would have invented coverage that doesn't exist.)

**Cast-removal follow-through (added 2026-09-25).** If deleting a cast exposes a compiler error downstream, trace the diagnostic to the value producer and correct its source type or invalid literal; do not restore the cast or label the error generic-inference friction without evidence. In #225, removing the builder cast exposed `ProviderInfo.provider: string` and the unsupported `"google"` value; the root fix used `ProviderName` and `"gemini"`. **Dead-branch variant (2026-09-28 v19):** after deleting an unreachable branch, re-check nearby plain `as` casts for redundancy and remove them if typecheck still passes — e.g. #224 removed the now-pointless `as Effect.Effect<() => void>` on both `subscribe()` `runPromise` calls. This is noise reduction, not a ratchet action (`as` ≠ `as unknown as`).

**Cwd-relative path bug sweep (added 2026-09-28 v20).** When the fix is "anchor a path to the repo root instead of `process.cwd()`", do NOT stop at the obvious constant. Grep the **whole package** for every relative-path assumption and fix all of them in the same bundle:
- bare `"wiki/`, `"packages/`, `"src/`, `"tests/` string literals;
- `existsSync` / `readFileSync` / `writeFileSync` / `copyFileSync` on paths not derived from `import.meta.url`;
- `process.cwd()`.

Then centralize the workspace-root resolution in **one** module (e.g. `repo-root.ts` exporting `REPO_ROOT` + `findRepoRoot`) and import it everywhere — never duplicate a walk-up across runner/scenario/script files. Walk **up** to a root marker (require the workspace marker — `turbo.json` — *and* a `wiki/` dir, so a stale gitignored `packages/<pkg>/wiki/` snapshot cannot shadow the real root); a **fixed relative depth is wrong** when the same module resolves from both `src/` and a bundled `dist/`. (Reason: 2026-09-28 #230 — anchoring `REPORTS_DIR` left `cf-10`'s `WIRING_TEST_PATH = "packages/runtime/..."` still cwd-relative, so the package-cwd suite stayed red until the sweep caught the second site.)

**Pure-deletion verified-by (added 2026-05-22 v6).** When the bundle is purely deletion (no new helper, no migration, no replacement), the standard "grep target → 0" recheck is structurally weaker than for typing/refactor bundles. Strengthen by also asserting:

1. **Test count delta matches expectation.** If you deleted `test.skip(...)`, the package test runner's `skip` count should drop by exactly that number. Capture in retro alongside pass/fail.
2. **No inbound references remain.** For any symbol deleted (helper fn, interface, type), grep workspace-wide for references and confirm zero matches outside the touched file itself: `grep -rn "<DeletedSymbol>" packages/ | grep -v "<touched-file>"` → 0. If any inbound ref survives, your deletion shipped a compile-time break.
3. **No dangling imports.** `grep -n "import.*<DeletedSymbol>" packages/` → 0.

Failing any of these means the deletion missed adjacent dead-code; either expand scope or undo and re-bundle.

**Pause conditions (descope rather than skip):**
- Build goes red → revert unit, reopen issue with new failure mode, continue with remaining units
- Test suite gains net-new failures → same as above
- Effort blows past unit estimate by 2× → mark issue `over-budget` label, defer, continue

**Test+fix combo bundles (added 2026-05-22 v9).** When a behavioral RED test surfaces an impl bug during a test-coverage bundle, the fix lands in the same PR. The PR title combines verbs: `test(X): add coverage; fix Y`. Allowed when **all** apply:

1. The fix is ≤10 lines.
2. The fix mirrors an existing-working pattern in a sibling package, OR passes a code-reviewer agent for correctness.
3. The fix is covered by the same test that surfaced it (test serves as regression check).

If any of those fail, **descope**: file the bug as a separate issue and ship the bundle with the test marked `test.skip` / `xfail` referencing the new issue. (Reason: 2026-05-22 #82 vue portion — behavioral SSE-error test failed because `use-agent-stream.ts:76-78` threw inside an inner `JSON.parse try/catch` that swallowed it. Svelte sibling used direct assignment, no throw. 2-line mirror fix landed in PR #102 alongside the regression test. Defended over "test-only PR + separate fix PR" because the swallow is invisible to types and would have stayed latent.)

**Do NOT:**
- Skip tests for time pressure
- Use `as any` to silence types from the very issues you're closing
- Mix unrelated changes into a single commit (test+fix combo is NOT mixed — it's one observably-correct concern)

---

## Phase 5 — VERIFY (cross-cutting, after all units commit)

Run the bundle-wide verification gate:

```bash
bun run build           # all packages green
bun test                # full suite, no net-new failures vs pre-bundle baseline
bun run typecheck       # workspace-wide
```

For each issue in the bundle, re-check the original verified-by claim against the new code state:

```
issue #N verified-by said: `grep -c "as any" packages/X/Y.ts` → 5
new check:                  `grep -c "as any" packages/X/Y.ts` → 0
✅ resolved
```

If a verified-by check fails to come down → the fix didn't actually address the claim. Reopen the issue with the new count + commit ref.

**Duplication-elimination check for extraction bundles (added 2026-09-28 v18).** For a dedup/extraction bundle, the verified-by must be "the duplicated symbol/inline block now appears **0** times in every former owner" — not "a helper exists". Grep each former owner for the old symbol/pattern and assert 0; then confirm the shared helper is the sole owner. A helper can be added while the old duplicated code remains beside it (dead or still-live), which would make the bundle a no-op. Also confirm the extraction's parity tests for **every** call site pass unchanged or are newly added. (Reason: 2026-09-28 #216 — `grep -c toolCallAccum` → 0/0 across both providers was the crisp acceptance check; "helper file exists" would not have caught a half-done rewire.)

**Red-on-cut spot-check for security-sensitive coverage bundles (added 2026-09-28 v21).** For a bundle whose new tests guard a security-critical invariant (signature/HMAC validation, redaction, auth, allow-listing), "tests pass" is not sufficient proof — prove they would **catch a regression**. Mutate the guarded line (a `/tmp` file-swap, or a one-line `sed`, e.g. `crypto.timingSafeEqual(...)` → `true`), run the new test file, confirm it goes **red**, then restore and confirm a clean diff. Record the fail count and which assertion fired in the retro. This upgrades "we added coverage" to "the coverage is load-bearing". (Reason: 2026-09-28 #227 — mutating the generic webhook adapter's `timingSafeEqual` return failed exactly the wrong-same-length-signature test; also revealed that only 1 of 14 tests guards that specific branch, which a shape-only check would have missed.)

**Workspace-test-flake protocol (added 2026-05-22 v7).** When `bun test` (workspace, run from repo root) shows failures but per-package isolation runs clean, treat as test-order / fixture-state flake. Verification is acceptable when:

1. The bundle's touched package suite passes in isolation: `bun test packages/<touched>/` → 0 fail.
2. The failing tests live in packages NOT touched by the bundle. (`bun test packages/<failing-pkg>/` → 0 fail confirms it's flake, not real.)
3. The failing tests are not the verified-by recheck for any bundle issue.

Document the flake in the PR body (test name + isolation evidence). Do NOT block the bundle. CI may surface the same flake; if so, rerun the failed job. (Reason: 2026-05-22 #82 spawn — workspace `bun test` showed 2 fails in `packages/diagnose/`; `bun test packages/diagnose/` → 35/0. Pre-existing test-order issue, unrelated to the react smoke bundle. CI on #100 will rerun cleanly. Same pattern surfaced on #99 — `httpbin.org` external-network flake resolved on rerun.)

Track flakes that recur across ≥2 bundles in their own follow-up issue (e.g., "test-order flake in packages/diagnose under workspace `bun test`") — separately from any active bundle.

**Turbo-cache masking + cwd-relative-fixture triage (added 2026-09-25 v17).** Before attributing a full-workspace red to the bundle, run this two-step triage:

1. **Re-run the failing package from repo-root cwd** (`bun test packages/<failing>/`). If it passes there but fails under `bun run test`, the failure is invocation-dependent, not a code regression.
2. **grep the failing test for cwd-relative paths**: `grep -n "process.cwd()\|join(\"wiki\|REPORTS_DIR\|import.meta" <test>`. A test that resolves fixtures/baselines relative to `process.cwd()` reads DIFFERENT files under turbo (cwd = package dir) than under root-cwd `bun test` — and turbo CACHES the task, so a pre-existing red can stay hidden until some other change invalidates the cache. A uniform divergence across many cases (same field, identical expected→actual delta) is a stale-baseline signature, not a behavior change.

Do not block the bundle on such a red; file it as its own issue with the cwd evidence and note it in the PR/retro. (Reason: 2026-09-25 reasoning-silent-failure #223 — `@reactive-agents/testing`'s North Star gate resolves `REPORTS_DIR = "wiki/Research/Harness-Reports"` relative to cwd, so turbo read a stale gitignored `packages/testing/wiki/...` baseline (2026-06-16) instead of the committed root one (2026-09-19), producing 14 phantom regressions; turbo cache had masked it until the reasoning change invalidated the testing task. Filed #230.)

**Triage addendum (added 2026-09-28 v20).**
- **Path fixes must be verified from ≥2 cwds.** "End to end" for a gate/path bug = run the real consumer suite from BOTH the repo root and the package directory (the two cwds turbo visits), not just `bun test packages/X` from root. Only the dual-cwd pair proves cwd-independence.
- **Fixing a cached red can expose a DIFFERENT pre-existing red.** Turbo may have been caching a *second* failing task green from an older state; once the bundle de-caches it, that task runs and fails for unrelated reasons. Re-run the full workspace and attribute each remaining failure against a fresh baseline (e.g. run that package's suite directly) before claiming green or blaming the bundle. (Reason: 2026-09-28 #230 — after the testing gate was fixed, `bun run test` failed on `@reactive-agents/runtime#test`, which turned out to be the pre-existing #214 `as unknown as` ceiling, reproducible on the untouched base.)

---

## Phase 6 — UPDATE

**6a — Open the PR (mandatory) — OR merge to local main (hold-until-tag repos only, added 2026-08-16 v13).** Every execution session ships its bundle as one PR against `origin/main`. Exception: if Phase 3.5's local-main-ahead check found local `main` running ahead of `origin/main` (this repo's own convention), a PR against `origin/main` right now would show every one of those unrelated unpushed commits as part of the diff, not just the bundle. In that case, merge the bundle branch directly into local `main` instead (`git checkout main && git merge --no-ff bundle/<bundle-name>`), verify the merged result (build + test), delete the bundle branch (local and any pushed remote copy), and note the deviation + why in the retro. Everything else in this phase (issue close, board move, knowledge sync) still applies — it just runs against the local-main merge instead of a merged PR.

```bash
git push -u origin bundle/<bundle-name>
gh pr create \
  --base main \
  --head bundle/<bundle-name> \
  --title "<bundle-name>: <one-line summary>" \
  --body "$(cat <<'EOF'
## Bundle: <name>

Closes #N
Closes #N

## Summary
<2-3 lines on what changed>

## Verification
- `bun run build` ✅
- `bun test` ✅ (delta: +X / -Y vs baseline)
- `bunx turbo run typecheck --filter=<changed>` ✅
- Verified-by rechecks (per issue):
  - #N: `<command>` → <new result> (was <old>)

## Plan + Retro
- Plan: wiki/Planning/Implementation-Plans/YYYY-MM-DD-<bundle>.md
- Retro: wiki/Research/Debriefs/YYYY-MM-DD-<bundle>-execution-debrief.md
EOF
)"
```

PR body MUST include `Closes #N` for every issue in the bundle — GitHub auto-closes them on merge, no manual `gh issue close` needed. If a bundle issue was descoped mid-EXECUTE, drop its `Closes #N` line and explain in the PR body.

The skill's job ends at PR open. **Merge is a human decision** — do not auto-merge.

**6b — Project board + knowledge sync.** Move bundle issues to **In Review** column (not Done — done happens on merge). Then:

Sync local knowledge:
- `wiki/Hot.md` — append session note (bundle name, issues closed, key learnings)
- `.agents/MEMORY.md` — if a pattern emerged worth remembering, add a one-line entry under the relevant section
- `wiki/Issues/Running Issues Log.md` — if any HS-NN items closed, mark them in the migration table

---

## Phase 7 — RETRO (mandatory, self-improving)

Write a retrospective to `wiki/Research/Debriefs/YYYY-MM-DD-<bundle>-execution-debrief.md`:

```markdown
# Execution Retro: <bundle-name>
Date: YYYY-MM-DD
Budget: <budget_minutes> min | Actual: <actual> min

## Outcomes
- Issues closed: #N, #N, ...
- Issues descoped: #N (reason)
- Net test delta: +X / -Y
- Net LOC delta: +X / -Y

## What worked
- <one-line wins; reference commits>

## What didn't
- <friction points; missed estimates; surprises>

## Skill improvements (apply on next pass)
- <concrete change to SKILL.md — phase wording, gate, bundling heuristic, verification command>
- <e.g., "Bundling missed that HS-07 and HS-08 share a root cause — add 'shared untyped shape' as cohesion signal">

## Process inflation guard (HS-18/22/31 lesson)
- Did any unit's verified-by claim turn out to be inflated? If yes, document the inflation shape so the audit-finding template can catch it next time.
```

**Self-improvement loop:** the `Skill improvements` section gets applied to this very file before the retro is committed. Read this SKILL.md, find the section the retro says to amend, make the edit, commit alongside the retro.

This is non-negotiable. A bundle without a retro is not finished. A retro without a SKILL.md amendment leaves regression risk on the table.

---

## Anti-patterns to Reject

| Anti-pattern | Why it's banned |
|--------------|-----------------|
| "Just commit and we'll verify later" | Verification IS the deliverable; deferred = skipped |
| Closing an issue without re-running its verified-by | Pattern that produced HS-18/22/31 inflation |
| Bundling >5 issues for "efficiency" | Token + attention cost grows superlinearly; correlation between bundle-size and bug-introduction is documented |
| Cross-package bundles | Higher diff conflict risk; descope to per-package bundles |
| Retro that says "everything went great, no improvements" | Either (a) untrue (b) skill is at local maximum and needs harder scope — challenge the next run |

---

## Inputs This Skill Reads

- GH issues — `gh issue list ...`
- GH labels — existing taxonomy (`area:*`, `phase:*`, `priority:*`, `health-sweep`, `architecture-debt`, `verified`, `audit-2026-05-21`)
- `wiki/Hot.md` — recent state to avoid stepping on in-flight work
- `wiki/Issues/Running Issues Log.md` — historical context for HS-NN items
- AGENTS.md, CODING_STANDARDS.md — patterns the fixes must conform to
- Skill: `agent-tdd` — TDD discipline during EXECUTE
- Skill: `review-patterns` — gate before COMMIT
- Skill: `writing-plans` (with `wiki/Planning/Implementation-Plans/` override)
- Skill: `codebase-health-sweep` — for any opportunistic finding flagged during EXECUTE that wasn't in the bundle

## Outputs This Skill Writes

- Commits per execution unit (conventional format, citing GH #N)
- One bundle plan at `wiki/Planning/Implementation-Plans/`
- One execution retro at `wiki/Research/Debriefs/`
- GH issue closes + comments
- Project-board column moves
- Self-amendment to this SKILL.md (only the "Skill improvements" section can drive this; never silent edits)

---

## Recommended Invocation Patterns

**Solo run:**
```
/execute-backlog labels=audit-2026-05-21 priority=p1
```

**Parallel agent team (Extreme Ownership):**
Spawn one agent per `area:*` label with disjoint bundle scopes — each owns its area end-to-end. Coordinate via the tracker parent issue.

```
agent-providers:   /execute-backlog labels=audit-2026-05-21,area:providers
agent-reasoning:   /execute-backlog labels=audit-2026-05-21,area:reasoning
agent-harness:     /execute-backlog labels=audit-2026-05-21,area:harness
```

**Daily/weekly cadence:**
Schedule via `/loop` — `/loop 1d /execute-backlog labels=priority:p1 max_bundle_size=3` — but ONLY if budget + verification rigor is non-negotiable in the loop body.

---

## Quick Reference Card

```
SCAN     gh issue list --label … --json
BUNDLE   greedy cohesion grow, cap at max_bundle_size
PLAN     wiki/Planning/Implementation-Plans/YYYY-MM-DD-<bundle>.md
BRANCH   git checkout -B bundle/<bundle-name> origin/main (clean tree only)
EXECUTE  TDD per unit, conventional commits cite #N
VERIFY   build + test + typecheck + cast-ceiling + re-run each verified-by
UPDATE   gh pr create with Closes #N (auto-close on merge), board → In Review, Hot.md note
RETRO    wiki/Research/Debriefs/, AMEND THIS SKILL.md
```

If any phase output is missing → the bundle is not finished. There is no "good enough."