@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/retro/0207-decompose-agent-widget-update.md

@@ -1,92 +0,0 @@
----
-issue: 207
-issue_title: "Decompose update in agent-widget.ts (cognitive 31)"
----
-
-# Retro: #207 — Decompose `update` in `agent-widget.ts`
-
-## Stage: Planning (2026-05-25T04:12:00Z)
-
-### Session summary
-
-Planned the decomposition of `update` (cognitive complexity 31) into an exported pure `assembleWidgetState` function, a `clearWidget` method, and an `updateStatusBar` method.
-The plan follows the Phase 12 pattern established by Steps 1 and 2 (#205, #206) — extract pure functions where possible, otherwise extract methods, and simplify the original function to a thin orchestrator.
-
-### Observations
-
-- The sibling plans (#205, #206) provided a clear template for this plan — structure, section ordering, and test impact analysis all followed the established pattern.
-- There are **no existing tests** for `AgentWidget` — the only testable concern is the newly extracted `assembleWidgetState` pure function.
-  The rest of the refactoring is a mechanical extraction verified by the type checker.
-- `categorizeAgents` in `widget-renderer.ts` does a similar filter but returns full arrays (for rendering), while `assembleWidgetState` returns lightweight counts (for lifecycle decisions).
-  Different outputs for different consumers — no duplication concern.
-- No `ask_user` was needed — the issue's "Proposed change" section was unambiguous and the design pattern was well-established by the two preceding Phase 12 steps.
-
-## Stage: Planning — revision (2026-05-25T16:00:00Z)
-
-### Session summary
-
-Reviewed and revised the prior plan after a thorough code audit of `agent-widget.ts`, `widget-renderer.ts`, `agent-record.ts`, and `runtime.ts`.
-Three design changes were made to the original plan.
-
-### Observations
-
-- **Narrowed the input type:** Changed `assembleWidgetState` from accepting `WidgetAgent[]` (10+ fields) to a local `AgentSummary` interface (3 fields: `id`, `status`, `completedAt?`).
-  The original plan violated ISP — the function only reads 3 fields, so requiring full `WidgetAgent` fixtures in tests would be needless friction.
-  `AgentRecord` satisfies `AgentSummary` structurally, so no adapter is needed at the call site.
-- **Kept `dispose` independent:** The original plan made `dispose` delegate to `clearWidget`, but `dispose` and `update`'s idle path have different lifecycle semantics — `dispose` uses unconditional teardown (correctness guarantee), while `update`'s idle path uses guarded calls (avoiding redundant SDK calls during repeated ticks).
-  `dispose` also skips stale-entry cleanup (the Map is about to be GC'd).
-  Per the code-design skill's Sandi Metz principle, this is structural duplication that should not be extracted.
-- **Added complexity budget table:** Explicitly estimated cognitive complexity for each extracted function to verify the < 10 target is achievable across the board.
-
-## Stage: Implementation — TDD (2026-05-25T13:10:00Z)
-
-### Session summary
-
-Completed all three TDD steps from the plan.
-`assembleWidgetState` was extracted and tested with 16 unit tests covering all status combinations; `clearWidget` and `updateStatusBar` were extracted as private methods simplifying `update` to a thin orchestrator.
-Test count went from 868 to 884 (+16 tests across 55 files, up from 54).
-
-### Observations
-
-- No deviations from the plan.
-  The non-null assertion (`this.uiCtx!`) in `clearWidget` and `updateStatusBar` is safe because both methods are only called from `update` after the `if (!this.uiCtx) return` guard.
-- The `AgentSummary` interface and narrow test fixtures worked exactly as planned — test objects are plain 3-field literals, no `createTestRecord` needed.
-- The complexity hotspots table in `architecture.md` now has no rows (both `renderWidgetLines` from #205 and `update` from this issue are resolved).
-  The section note was updated to reflect that Phase 12 cleared all critical hotspots.
-- `pnpm fallow dead-code` (from repo root) passed with no issues.
-
-## Stage: Final Retrospective (2026-05-25T13:15:00Z)
-
-### Session summary
-
-Issue #207 shipped as `pi-subagents-v7.3.0` with zero deviations from the revised plan.
-The session covered plan revision, TDD implementation (16 new tests, 868 → 884), shipping, and CI verification.
-
-### Observations
-
-#### What went well
-
-- The plan revision caught three real design issues before implementation started: ISP violation in the function parameter type, incorrect `dispose` → `clearWidget` delegation, and missing complexity budget.
-  Fixing these upfront meant the TDD execution had zero deviations and zero rework.
-- The narrow `AgentSummary` type (3 fields) made test fixtures trivial plain objects — no `createTestRecord` or factory infrastructure needed.
-  This validated the ISP improvement concretely.
-- The `dispose` independence decision (Sandi Metz principle applied to lifecycle semantics) kept `dispose` at its current 10-line simplicity while `clearWidget` got its own guarded teardown logic.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The original planning session (prior to this one) used `WidgetAgent[]` as the input type without checking which fields `assembleWidgetState` actually reads.
-  The `code-design` skill already says "do not pass a shared dependency bag to functions that only use a subset of it" but the principle wasn't applied to the proposed function signature.
-  Impact: required a full plan revision session; no rework in implementation because it was caught before TDD started.
-- `wrong-abstraction` — The original plan proposed `dispose` → `clearWidget` delegation as "eliminating duplication" without evaluating whether the two methods have the same lifecycle semantics.
-  `dispose` uses unconditional teardown (shutdown correctness); `clearWidget` uses guarded calls (avoiding redundant SDK calls during repeated timer ticks).
-  Impact: same as above — caught in revision, no implementation rework.
-
-#### What caused friction (user side)
-
-- The user's "I don't yet trust the plan" intervention was the key moment that improved the design.
-  Without it, the plan would have been implemented with the wider type and the `dispose` delegation.
-  This was effective judgment — the user identified that a mechanical plan for a mechanical refactoring still warranted critical design review.
-
-### Changes made
-
-1. Added two sentences to `.pi/prompts/plan-issue.md` Design Overview section: ISP check for new function parameter types, and structural-duplication check when consolidating methods into a shared helper.

package/docs/retro/0208-extract-shared-test-fixtures.md

@@ -1,102 +0,0 @@
----
-issue: 208
-issue_title: "Extract shared test fixtures to reduce test duplication"
----
-
-# Retro: #208 — Extract shared test fixtures to reduce test duplication
-
-## Stage: Final Retrospective (2026-05-25T22:00:00Z)
-
-### Session summary
-
-Reviewed the planning, TDD, and shipping sessions for issue #208.
-The work completed Phase 12 of the pi-subagents improvement roadmap.
-Identified Vitest v4 type compatibility as the dominant friction pattern, and the user surfaced a strategic insight: shared test factories are treating symptoms of ISP violations in production interfaces.
-
-### Observations
-
-#### What went well
-
-- The planning session's duplication diff (comparing default values across all copies before writing the shared factory) prevented cascading assertion failures during migration — the testing skill rule paid off.
-- Using a Python script for the `agent-manager.test.ts` spawn consolidation (step 9) handled 42 multi-line replacements with 7 distinct patterns cleanly in one pass.
-- `pnpm run check` caught 4 separate type errors that Vitest's esbuild would have silently ignored at runtime: wrong `findAgentFile` parameter type, dropped `AgentConfig` import, unused `@ts-expect-error` directives, and `Mock<Procedure>` incompatibility.
-
-#### What caused friction (agent side)
-
-1. `missing-context` — Wrote `vi.fn().mockReturnValue([])` in the shared factory without checking whether `Mock<Procedure>` is structurally assignable to the production function signatures (`RunnerIO`, `AgentFileOps`).
-   The testing skill warns about `ReturnType<typeof vi.fn>` at the field level, but I didn't connect this to the structural-compatibility scenario where a factory's return value flows to a typed production parameter.
-   Impact: 37 type errors after step 2, requiring a fixup commit (2953adc) and removal of the `assemblerOverrides` parameter.
-2. `missing-context` — Assumed `findAgentFile` took `(dir: string, name: string)` based on test usage patterns rather than checking the `AgentFileOps` interface.
-   The actual signature is `(name: string, dirs: string[])` — the second parameter is `string[]`.
-   Impact: caught by `pnpm run check`, fixed in the same commit, no rework.
-3. `scope-drift` — Removed `import type { AgentConfig }` from `agent-config-editor.test.ts` because the symbols it was needed for (`testDefaultConfig`, `testCustomConfig`) were being removed.
-   Didn't check that `buildEjectContent` tests 400 lines later also used `AgentConfig`.
-   Impact: caught by `pnpm run check`, one-line fix, no rework.
-4. `premature-convergence` — Added `@ts-expect-error` directives for `.mock` property access in the factory tests, assuming TypeScript wouldn't know about Mock's `.mock` property.
-   Once the `vi.fn()` stubs were typed with implementations, TypeScript recognized the Mock type and `.mock` was accessible, making all 5 directives unused.
-   Impact: added friction but no rework — eslint caught them.
-
-#### What caused friction (user side)
-
-- No friction caused by the user.
-  The user's post-ship reflection ("we need to eliminate complex setup, right?") was a strategic insight that elevated the conversation from mechanical duplication reduction to ISP-driven interface narrowing.
-  This kind of mid-session reframing is valuable and came at exactly the right time — after the work was done, so it informs future phases rather than disrupting the current one.
-
-#### Phase 13 guidance: ISP narrowing targets
-
-The `test/helpers/` factory inventory is a concrete map of production interfaces worth narrowing:
-
-| Factory             | Production interface                                          | Methods                       | Consumer usage                   |
-| ------------------- | ------------------------------------------------------------- | ----------------------------- | -------------------------------- |
-| `createRunnerIO`    | `RunnerIO` (`EnvironmentIO & SessionFactoryIO`)               | 8 (7 functions + assemblerIO) | Most tests use 2–3               |
-| `makeFileOps`       | `AgentFileOps`                                                | 6                             | Most tests use `exists` + `read` |
-| `createToolDeps`    | `AgentToolManager` + `AgentToolRuntime` + `AgentToolSettings` | 12+ across 3 interfaces       | Spawners use 2–3 each            |
-| `createMockSession` | `AgentSession` (SDK class)                                    | 5 stubs                       | Observers use `subscribe` only   |
-| `createAgentLookup` | `AgentConfigLookup`                                           | 2                             | Already narrow ✓                 |
-
-When a factory needs its own unit tests, the interface it stubs is too wide for its consumers.
-The fix is ISP narrowing of the production interface, not more test infrastructure.
-
-### Changes made
-
-1. Added rule to `testing` skill: typed implementations in shared factories when return value satisfies a production interface.
-2. Added ISP signal to `improvement-discovery` skill Category D table: shared factory complexity → narrow the production interface.
-
-## Stage: Implementation — TDD (2026-05-25T21:00:00Z)
-
-### Session summary
-
-Completed all 10 TDD steps plus a type-fix commit.
-Created 4 new files (`runner-io.ts`, `runner-io.test.ts`, `ui-stubs.ts`, `ui-stubs.test.ts`) and migrated 7 existing test files.
-Test count grew from 884 → 913 (+29 tests in new helper unit tests).
-
-### Observations
-
-- Vitest v4 changed `vi.fn()` without implementation annotation to type `Mock<Procedure | Constructable>`, which is NOT assignable to specific function signatures in production interfaces.
-  The fix was to add typed implementation annotations (`vi.fn((_path: string): boolean => false)`) to all vi.fn() stubs in the shared factories.
-  This was a new friction point not anticipated in the plan.
-- The plan's `assemblerOverrides` parameter in `createRunnerIO()` was removed because the `??` union typing caused `Mock<Procedure | Constructable> | Mock<specific-fn>` which TypeScript couldn't resolve as assignable to `RunnerIO`.
-  No consumer test actually used the override parameter, so removing it simplified both the implementation and the type story.
-- The `findAgentFile` signature in `AgentFileOps` is `(name: string, dirs: string[])` — the second parameter is `string[]`, not a second string as initially assumed from test patterns.
-  This was caught by `pnpm run check`.
-- The `agent-config-editor.test.ts` migration removed the `import type { AgentConfig }` import that was still needed by `buildEjectContent` tests further down the file.
-  Also caught by `pnpm run check`.
-- `STUB_SNAPSHOT` replacement was safe: no consumer test asserts on snapshot field values.
-  The `mockSnapshot` in `agent-manager.test.ts` had `systemPrompt: "parent prompt"` vs `STUB_SNAPSHOT`'s `"test prompt"` but this caused no test failures.
-- Architecture doc was updated to reference `test/helpers/` (correcting `test/fixtures/` from the original entry).
-
-## Stage: Planning (2026-05-25T20:00:00Z)
-
-### Session summary
-
-Analyzed the three heaviest test clone families identified by fallow and designed a 10-step TDD plan to extract shared factories into `test/helpers/`.
-Decided to follow the existing `test/helpers/` convention rather than the `test/fixtures/` directory mentioned in the issue and architecture doc.
-
-### Observations
-
-- Issue #131 (closed) already extracted `createMockSession`, `createToolDeps`, and `createTestRecord` — this issue targets the remaining duplication.
-- The `createRunnerIO` factory in `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` includes stale `buildMemoryBlock` and `buildReadOnlyMemoryBlock` stubs that no longer match the `AssemblerIO` interface — the shared factory will clean these up as a side benefit.
-- Session mock factories in the runner tests are structurally specialized (each serves a different test purpose) and were explicitly scoped as non-goals — extracting them would create a confusing multi-mode factory.
-- The `agent-runner-extension-tools.test.ts` uses a mutable `agentConfigMock.current` pattern that doesn't fit into a shared static factory — only `createRunnerIO` is shared from that file.
-- `STUB_SNAPSHOT` from `stub-ctx.ts` can replace all 5 local `ParentSnapshot` definitions — verified no test asserts on the specific field values.
-- The `agent-manager.test.ts` internal duplication (~42 repetitive spawn calls) is best handled with local `spawnBg()`/`spawnFg()` helpers rather than cross-file extraction.

package/docs/retro/0214-convert-remaining-closure-factories-to-classes.md

@@ -1,66 +0,0 @@
----
-issue: 214
-issue_title: "Convert remaining closure factories to classes (Phase 13, Step 1)"
----
-
-# Retro: #214 — Convert remaining closure factories to classes
-
-## Stage: Planning (2026-05-25T20:00:00Z)
-
-### Session summary
-
-Produced a 4-step TDD plan to convert the three remaining closure factories (`createAgentConfigEditor`, `createAgentCreationWizard`, `createSubagentsService`) to classes.
-Each conversion is one commit covering source, test, and consumer updates together.
-
-### Observations
-
-- The conversions are entirely mechanical — same pattern as Phase 11 (#195, #196).
-  No design ambiguity requiring user input.
-- `AgentCreationWizardDeps` is only used within its own file, so removing it is safe.
-  The class dissolves the deps bag into positional constructor params for consistency with `AgentConfigEditor`.
-- The `agent-creation-wizard.test.ts` has ~18 inline `createAgentCreationWizard(deps)` calls; the plan suggests adding a `makeWizard(deps)` helper to centralize construction and reduce the diff size.
-- `SubagentsServiceAdapter` uses `implements SubagentsService` for compile-time verification, unlike the factory which relied on structural typing of the returned object literal.
-- Pure helper functions (`buildMenuOptions`, `buildEjectContent`, `toSubagentRecord`) and narrow interfaces (`AgentManagerLike`, `ServiceRuntimeLike`, `WizardManager`, `WizardRegistry`) remain unchanged.
-
-## Stage: Implementation — TDD (2026-05-25T21:00:00Z)
-
-### Session summary
-
-All 4 TDD steps completed in 4 commits.
-Three closure factories converted to classes (`AgentConfigEditor`, `AgentCreationWizard`, `SubagentsServiceAdapter`) with tests and consumers updated in the same commit as each production change.
-Test count held at 913 (57 files) — no new tests needed, no tests removed.
-
-### Observations
-
-- All three conversions were mechanical find-and-replace with no behavioral surprises.
-- The `makeWizard(deps)` helper in `agent-creation-wizard.test.ts` centralized 14 inline `createAgentCreationWizard(deps)` calls, keeping the diff readable.
-- `SubagentsServiceAdapter` uses `implements SubagentsService` — the TypeScript compiler confirmed the contract at compile time with no gaps.
-- Adding the `SpawnOptions` import to `service-adapter.ts` was required for the `spawn` method signature; the plan anticipated this correctly.
-- The `sed -i` command required the macOS `-i ''` form (no in-place backup extension) rather than the GNU `sed -i` form.
-- Dead-code gate (`pnpm fallow dead-code`) passed cleanly from the repo root — no suppression needed.
-
-## Stage: Final Retrospective (2026-05-25T22:00:00Z)
-
-### Session summary
-
-Shipped `pi-subagents-v7.3.2` with 3 refactor commits converting all remaining closure factories to classes.
-All 4 lifecycle stages (plan → TDD → ship → retro) completed in a single day with zero rework and zero deviations from the plan.
-
-### Observations
-
-#### What went well
-
-- Strong precedent from Phase 11 (#195, #196) made this issue zero-friction — the plan, implementation, and test updates all followed an established template.
-- The plan's prediction of a `makeWizard(deps)` helper for `agent-creation-wizard.test.ts` kept the step-2 diff readable by centralizing 14 inline constructor calls.
-- `SubagentsServiceAdapter implements SubagentsService` gave compile-time contract verification, catching any interface drift immediately via `pnpm run check`.
-- The plan correctly anticipated the `SpawnOptions` import need in `service-adapter.ts`.
-
-#### What caused friction (agent side)
-
-- None.
-  This was a textbook mechanical refactoring with no behavioral changes, no edge cases, and no test rework.
-
-#### What caused friction (user side)
-
-- None.
-  The issue was well-scoped with explicit target files and a clear precedent to follow.

package/docs/retro/0215-decompose-build-parent-context.md

@@ -1,61 +0,0 @@
----
-issue: 215
-issue_title: "Decompose buildParentContext (cognitive 30) (Phase 13, Step 2)"
----
-
-# Retro: #215 — Decompose buildParentContext
-
-## Stage: Planning (2026-05-25T12:00:00Z)
-
-### Session summary
-
-Produced a 3-step TDD plan to decompose `buildParentContext` in `src/session/context.ts`.
-Steps 1–2 add tests locking current behavior for `extractText` and `buildParentContext`; step 3 extracts three private helpers (`formatMessageEntry`, `formatCompactionEntry`, `formatBranchEntry`) and simplifies the orchestrator to map/filter/join.
-
-### Observations
-
-- No existing unit tests cover `context.ts` — `parent-snapshot.test.ts` mocks `buildParentContext` entirely, so the formatting logic is currently untested.
-- The decomposition is straightforward with no design ambiguity; the architecture roadmap specifies the exact extraction targets.
-- All extracted helpers remain private (not exported), keeping the public API surface unchanged.
-- The `eslint-disable` comment on the `getBranch()` nullability check must be preserved through the refactoring step.
-
-## Stage: Implementation — TDD (2026-05-25T22:36:00Z)
-
-### Session summary
-
-Completed all 3 TDD steps: 2 test-only commits locking `extractText` (5 tests) and `buildParentContext` (14 tests) behavior, then a refactor commit extracting `formatMessageEntry`, `formatCompactionEntry`, and `formatBranchEntry`.
-Test count increased from 939 to 958 (+19).
-All checks green: full suite, `pnpm run check`, `pnpm run lint`, `pnpm fallow dead-code`.
-
-### Observations
-
-- Because `extractText` and `buildParentContext` already existed, both test steps passed immediately (no red phase) — this is correct for behavior-locking tests before a refactor.
-- The `makeCtx` helper in the test file creates a minimal `SessionContext` satisfying only `sessionManager.getBranch()`; the extra required fields (`cwd`, `model`, `modelRegistry`, `getSystemPrompt`) are satisfied with stubs.
-- The `eslint-disable` comment on the `getBranch()` nullability check was preserved unchanged through the refactor.
-- No deviations from the plan.
-
-## Stage: Final Retrospective (2026-05-26T02:50:00Z)
-
-### Session summary
-
-Completed the full issue lifecycle (plan → TDD → ship → retro) in a single session with zero rework or user corrections.
-Released as `pi-subagents-v7.5.1`.
-Test count: 939 → 958 (+19 tests in new `test/session/context.test.ts`).
-
-### Observations
-
-#### What went well
-
-- Zero-deviation execution: the architecture roadmap specified exact decomposition targets, the plan translated them into 3 TDD steps, and implementation was a straight transcription.
-- Multi-model cost efficiency: `claude-sonnet-4-6` for planning/TDD, `deepseek-v4-flash` for shipping (~$0.002 for the entire ship workflow), `claude-opus-4-6` for retro synthesis.
-- Incremental verification at every stage: per-file test runs after each TDD step, full suite + `pnpm run check` + `pnpm run lint` + `pnpm fallow dead-code` after the last step, repo-root lint before push.
-
-#### What caused friction (agent side)
-
-None identified.
-The issue was well-scoped, the architecture roadmap was unambiguous, and the existing code had no surprising edge cases.
-
-#### What caused friction (user side)
-
-None identified.
-The user ran four prompt commands in sequence (`/plan-issue`, `/tdd-plan`, `/ship-issue`, `/retro`) with no corrections or redirections needed.

package/docs/retro/0216-decompose-start-agent.md

@@ -1,80 +0,0 @@
----
-issue: 216
-issue_title: "Decompose startAgent in agent-manager.ts (Phase 13, Step 3)"
----
-
-# Retro: #216 — Decompose startAgent in agent-manager.ts
-
-## Stage: Planning (2026-05-25T20:00:00Z)
-
-### Session summary
-
-Analyzed the `startAgent` method's structural problems beyond surface-level length.
-The original issue proposed extracting three methods (`handleRunCompletion`, `handleRunError`, `finalizeBackgroundRun`).
-Through design discussion, identified the root cause as **mutable closure state without an owner** — two `let` variables shared across three closures — and proposed a `RunHandle` lifecycle object as the missing collaborator.
-
-### Observations
-
-- The initial mechanical-extraction approach (3 methods) wouldn't have eliminated the mutable closure variables — `.then()`/`.catch()` would still close over `unsubRecordObserver` and `detach`.
-  `RunHandle` eliminates these entirely by owning the resource-release handles.
-- `WorktreeState` has an ask-tell smell: callers call `worktrees.cleanup()` then `worktreeState.recordCleanup()`.
-  Adding `performCleanup()` is a small prep step that simplifies `RunHandle`'s completion/error methods.
-- `record.description` is already available on `AgentRecord`, so `RunHandle` doesn't need `description` as a separate dependency — it can use `record.description` for worktree cleanup.
-- `RunResult` is already exported from `agent-runner.ts`, so `RunHandle.complete()` can accept it directly without a new type.
-- The `.catch()` handler doesn't wrap `onAgentCompleted` in try/catch while `.then()` does — `finalizeBackgroundRun` unifies this by always wrapping, preventing an observer error from blocking `drainQueue()`.
-- `fireOnFinished` idempotency is important: if `complete()` throws after worktree cleanup but before returning, `.catch()` → `fail()` must not double-fire the background finalization.
-  `AgentRecord`'s transition guards (`if (this._status !== "stopped")`) provide a second safety net.
-
-## Stage: Implementation — TDD (2026-05-25T23:20:00Z)
-
-### Session summary
-
-Completed all 4 TDD steps across 5 commits (one extra for the type-annotation fixup caught by `pnpm run check`).
-Added 4 new tests for `WorktreeState.performCleanup`; total test count rose from 958 to 962.
-All 60 test files pass; `pnpm run check`, `pnpm run lint`, and `pnpm fallow dead-code` all clean.
-
-### Observations
-
-- One deviation from the plan: the `makeWorktrees` test helper in `worktree-state.test.ts` needed an explicit `WorktreeCleanupResult` type annotation on its `result` parameter — TypeScript inferred `{ hasChanges: boolean }` (no optional `branch`/`path` fields) from the default argument, which caused a type error on the call site that passed `{ hasChanges: true, branch: "pi-agent-1" }`.
-  Fixed in the same commit as the `RunHandle` step.
-- `RunHandle` landed exactly as designed: `wireSignal`, `attachObserver`, `complete`, `fail`, `releaseListeners`, `fireOnFinished` (idempotent). `startAgent` is now ~40 lines with zero mutable `let` bindings and one-liner `.then()`/`.catch()` handlers.
-- `flushPendingSteers` and `setupWorktree` extracted cleanly — each about 8 lines, no surprises.
-- The `WorktreeCleanupResult` import needed to be added to the test file alongside the existing `WorktreeManager` import for the type annotation fix — minor but worth noting for the next engineer.
-- Architecture doc updated: Step 3 entry now reflects `RunHandle` rather than the original `handleRunCompletion`/`handleRunError` proposal.
-
-## Stage: Final Retrospective (2026-05-26T15:10:00Z)
-
-### Session summary
-
-Issue #216 was planned, implemented via 4 TDD steps (5 commits), shipped, CI verified (after a GitHub Actions outage), and released as `pi-subagents-v7.6.0`.
-The final design replaced the original mechanical-extraction proposal with a `RunHandle` lifecycle object that eliminated mutable closure state from `startAgent`.
-
-### Observations
-
-#### What went well
-
-- The user's two design redirections during planning ("What collaborators are still missing?"
-  and "Make the change that makes the change easy") transformed a mechanical extraction plan into a structural improvement.
-  The resulting `RunHandle` eliminated the root cause (mutable closure state) rather than just shortening the method.
-- The prep-step pattern worked exactly as intended: `WorktreeState.performCleanup` (step 1) and `finalizeBackgroundRun` (step 3) made the `RunHandle` rewrite (step 4) straightforward.
-  Step 4's large edit landed cleanly with all 962 tests passing on the first run.
-- Two Explore subagents dispatched during planning (reading collaborator files and checking `WorktreeState` details) gathered the right context efficiently — `RunResult` being already exported and `record.description` being available at cleanup time were both discovered this way and shaped the `RunHandle` interface.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — accepted the issue's proposed mechanical extraction (3 methods) at face value and spent analysis time on LOC arithmetic before the user redirected toward structural thinking.
-  Impact: two user redirections needed; no rework since no code was committed yet.
-- `instruction-violation` (self-identified) — the testing skill says "run `pnpm run check` immediately after" changing a shared interface, but step 1 added `performCleanup` to `WorktreeState` without running `pnpm run check`.
-  The type error in the test helper (`makeWorktrees` default parameter needing `WorktreeCleanupResult` annotation) went undetected for 3 commits until step 4's `pnpm run check`.
-  Impact: added friction but no rework — fixed in the same commit.
-
-#### What caused friction (user side)
-
-- The user's design redirections were necessary and well-timed.
-  No friction from the user side — the two interventions were strategic and saved significant implementation effort.
-
-### Diagnostic details
-
-- **Model-performance correlation** — two Explore subagents ran on `claude-haiku-4-5`; appropriate for read-only codebase search (reading collaborator files, checking types and test patterns).
-- **Feedback-loop gap analysis** — `pnpm run check` ran only after step 4 (the `RunHandle` commit); should have run after step 1 (`WorktreeState.performCleanup` is a shared interface change per the testing skill).
-  The gap allowed a type annotation error to persist for 3 commits.

package/docs/retro/0217-extract-overwrite-guard.md

@@ -1,63 +0,0 @@
----
-issue: 217
-issue_title: "Extract overwrite guard from UI (Phase 13, Step 4)"
----
-
-# Retro: #217 — Extract overwrite guard from UI
-
-## Stage: Planning (2026-05-26T20:00:00Z)
-
-### Session summary
-
-Produced a 5-step TDD plan to extract the duplicated overwrite-guard + write + reload + notify pattern from `AgentConfigEditor.ejectAgent` and `AgentCreationWizard.showManualWizard` into a shared `writeAgentFile` function in a new `src/ui/agent-file-writer.ts` module.
-Confirmed dependency #214 (closure-to-class conversion) is already closed.
-
-### Observations
-
-- The `showGenerateWizard` overwrite guard was explicitly scoped out — it has different lifecycle semantics (spawned agent writes the file, post-write check is conditional).
-  This avoids a leaky abstraction with a discriminator parameter.
-- Narrow ISP interfaces (`FileWriter`, `WriterUI`, `Reloadable`) keep the extracted function decoupled from the full `AgentFileOps` and `MenuUI` interfaces — 2/6 and 2/6 methods respectively.
-- Both consumer call sites hold `this.fileOps` and `this.registry` as private fields and receive `ui` as a method parameter, so no constructor or wiring changes are needed.
-- Existing tests in both consumer test files use `expect.stringContaining("already exists")` for overwrite prompts, which is stable across the extraction.
-
-## Stage: Implementation — TDD (2026-05-26T20:40:00Z)
-
-### Session summary
-
-Implemented `writeAgentFile` in new `src/ui/agent-file-writer.ts`, replaced the inline overwrite-guard blocks in `AgentConfigEditor.ejectAgent` and `AgentCreationWizard.showManualWizard`, and updated the architecture doc.
-All 5 plan steps completed across 4 commits (plan steps 1 and 2 folded into one).
-Test count: 962 → 970 (+8 new tests in `test/ui/agent-file-writer.test.ts`).
-
-### Observations
-
-- Plan steps 1 and 2 naturally collapsed into a single commit — writing all 8 tests at once and implementing the full function body (including the guard) in one pass was cleaner than splitting them artificially.
-- Both consumer refactors were straightforward one-import-add + one-block-replace edits; all existing tests passed without modification, confirming the extraction preserved exact behavior.
-- The notification label `"Ejected ${name} to"` (with trailing space absorbed by `${targetPath}`) matched the pre-existing message format `"Ejected test-agent to /path"` exactly — no test assertions changed.
-- `FileWriter`, `WriterUI`, and `Reloadable` narrow interfaces are exported from `agent-file-writer.ts`; both consumer files import the concrete types from their original sources, satisfying TypeScript's structural checker without any casts.
-
-## Stage: Final Retrospective (2026-05-26T21:00:00Z)
-
-### Session summary
-
-Full plan → TDD → ship → release lifecycle completed in a single continuous session.
-Released as `pi-subagents-v7.7.0`.
-Zero rework, zero test failures, zero CI issues.
-
-### Observations
-
-#### What went well
-
-- The Phase 13 roadmap's step-level issue decomposition produced an issue (#217) that was right-sized for fully autonomous execution — the entire lifecycle completed without any blocking questions or scope surprises.
-- ISP-narrow interfaces (`FileWriter`, `WriterUI`, `Reloadable`) structurally satisfied both consumer types without casts, confirming the plan's design.
-- Existing tests in both consumer files passed without modification after the refactors, validating that the extraction preserved exact behavior.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — The plan split TDD steps 1 (happy-path tests) and 2 (overwrite-guard tests) for a ~10-line function with a single conditional.
-  Writing all 8 tests at once and implementing the full function body in one pass was natural; splitting them would have been artificial.
-  Self-corrected by folding into one commit.
-  Impact: added friction but no rework — the plan said "implementation should already pass" for step 2, acknowledging the fold was expected.
-
-#### What caused friction (user side)
-
-- Nothing notable — the issue was well-scoped with clear target files, a concrete smell label, and an explicit dependency chain.

package/docs/retro/0218-push-sdk-boundary-in-settings.md

@@ -1,72 +0,0 @@
----
-issue: 218
-issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
----
-
-# Retro: #218 — Push SDK boundary in settings.ts
-
-## Stage: Planning (2026-05-26T17:01:55Z)
-
-### Session summary
-
-Produced a 3-step TDD plan to inject `agentDir: string` into `SettingsManager` and `loadSettings`, removing the only Pi SDK import from `settings.ts`.
-The change is straightforward — a single parameter addition threading through constructor, free function, and boundary wiring.
-
-### Observations
-
-- The change is entirely mechanical: no design ambiguity, no new abstractions, no breaking public API.
-- The main implementation effort is in test updates (~35 `new SettingsManager(...)` call sites plus ~15 `loadSettings(...)` calls), all requiring an `agentDir` argument.
-- All test `describe` blocks that manipulate `PI_CODING_AGENT_DIR` env var can drop that scaffolding entirely, simplifying setup/teardown.
-- `saveSettings` has no SDK dependency and needs no signature change — only `loadSettings` calls `globalPath()`.
-
-## Stage: Implementation — TDD (2026-05-26T17:13:26Z)
-
-### Session summary
-
-Completed all 3 plan steps across 2 commits plus 1 doc commit.
-All 970 tests pass; `settings.ts` now has 0 Pi SDK imports and all `PI_CODING_AGENT_DIR` env var manipulation is gone from `settings.test.ts`.
-
-### Observations
-
-- **Steps 1+2 combined:** Changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` forced updating `SettingsManager.load()` in the same commit — they were inseparable (esbuild skips type checks, so the old call compiled but produced wrong runtime behavior).
-  The two production changes landed in one commit with a note in the body.
-- **Test simplification was significant:** Removed `originalAgentDirEnv` save/restore scaffolding from 5 `describe` blocks; the test code shrank by 32 lines net.
-- **`/nonexistent` sentinel:** Tests that construct `SettingsManager` but never call `load()` pass `agentDir: "/nonexistent"` — a clear signal the field is unused in that scope.
-- Architecture doc Step 5 heading marked `✓` and folded into the last `feat:` commit by `pi-autoformat`.
-
-## Stage: Final Retrospective (2026-05-26T17:22:11Z)
-
-### Session summary
-
-Issue #218 went from plan to shipped release (`pi-subagents-v7.8.0`) in a single continuous session.
-Planning, TDD (2 feat commits + 1 doc commit), shipping, CI verification, issue close, and release-please merge all completed without user intervention beyond stage transitions.
-
-### Observations
-
-#### What went well
-
-- **Clean mechanical execution:** The entire change was 2 production files (`settings.ts`, `index.ts`) and 1 test file, with zero unexpected test breakage and zero rework commits.
-- **Test simplification payoff:** Removing `PI_CODING_AGENT_DIR` env var scaffolding from 5 `describe` blocks shrank the test file by 32 lines net — a tangible improvement in test readability.
-- **Ship stage model efficiency:** The `/ship-issue` stage ran on `deepseek-v4-flash`, which was appropriate for the purely mechanical push/CI/close/merge workflow.
-
-#### What caused friction (agent side)
-
-1. `wrong-abstraction` — The plan split steps 1 and 2 into separate commits, but changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` immediately broke `SettingsManager.load()` which calls it.
-   The agent recognized this during the red phase and combined them into one commit.
-   The existing testing skill rule ("When a TDD plan lists separate steps that share a type definition… fold them into one step") already covers this — the plan just didn't apply it.
-   Impact: added friction but no rework; recognized on first test run.
-2. `missing-context` — Attempted to add `| ✓ #218 |` as an extra column to one row of the architecture doc's findings table, creating a column-count mismatch.
-   The autoformatter reverted the broken table.
-   The agent then spent ~5 tool calls (`git show --stat`, `git status`, `grep` ×2, `read`) investigating what happened before switching to the Step 5 heading approach.
-   Impact: ~2 minutes of investigation; no rework beyond the heading edit.
-
-#### What caused friction (user side)
-
-- The user asked "Are we ready for shipping?"
-  which surfaced that the TDD retro stage notes were still uncommitted.
-  This was a useful checkpoint — the ship stage committed them before pushing.
-  Opportunity: the `/tdd-plan` prompt could commit retro notes as part of its final step, but the current flow (write notes, then commit in ship) is lightweight enough that enforcing it would add complexity for marginal gain.
-
-### Changes made
-
-1. Retro file updated at `packages/pi-subagents/docs/retro/0218-push-sdk-boundary-in-settings.md` — no other files changed.

package/docs/retro/0219-reduce-test-duplication-top-3-clone-families.md

@@ -1,64 +0,0 @@
----
-issue: 219
-issue_title: "Reduce test duplication — top 3 clone families (Phase 13, Step 6)"
----
-
-# Retro: #219 — Reduce test duplication — top 3 clone families
-
-## Stage: Planning (2026-05-26T20:00:00Z)
-
-### Session summary
-
-Analyzed duplication patterns in the three target test files (`agent-manager.test.ts`, `conversation-viewer.test.ts`, `agent-config-editor.test.ts`).
-Produced a 5-step TDD plan with shared `manager-stubs.ts` helper for runner/worktree factories, plus inline factories for the two UI test files.
-
-### Observations
-
-- The agent-manager test has the most diverse clone families (runner stubs, worktree stubs, run-result shapes) — these benefit from a shared helper file since the patterns are reused across 15+ describe blocks.
-- The conversation-viewer and config-editor duplication is more localized — inline factories within each test file are the right granularity to avoid over-extraction.
-- Gated runners (using `Promise.withResolvers`) were deliberately kept inline since they encode test-specific flow control that a factory would obscure.
-- Both dependencies (#214, #216) are closed, so the production code is stable and the tests won't shift under us during implementation.
-
-## Stage: Implementation — TDD (2026-05-26T17:42:41Z)
-
-### Session summary
-
-Completed all 4 TDD cycles: created `test/helpers/manager-stubs.ts` + `manager-stubs.test.ts` (13 smoke tests), migrated `agent-manager.test.ts`, `conversation-viewer.test.ts`, and `agent-config-editor.test.ts`.
-Test count delta: 970 → 983 (+13 from smoke tests).
-All 4 commits landed cleanly; full suite green at every step.
-
-### Observations
-
-- Target file line savings: `agent-manager.test.ts` −63, `conversation-viewer.test.ts` −58, `agent-config-editor.test.ts` −16; offset by +211 for the new helper files.
-  Net LOC is positive, but the _clone_ lines fallow detects are eliminated — the metric the issue targets.
-- The `createSessionRunner` + `createRunResult` chain required careful identity-check verification: `createRunResult(sess)` calls `toAgentSession(sess)` which casts without creating a new object, so `toBe(session)` assertions in the execution-state tests still pass. ✓
-- ESLint auto-fixed two cosmetic issues on commit (`activity = undefined` → `activity` destructuring, `session as unknown` cast removal) — caught by pre-commit hooks, not a problem in practice.
-- The `assertRenderFitsWidths` helper in `conversation-viewer.test.ts` reduced the 10 render-safety tests from ~8 lines each to 1–4 lines each; the `setupDetail` helper in `agent-config-editor.test.ts` eliminated 3 repeated setup lines per test across 18 `showAgentDetail` tests.
-
-## Stage: Final Retrospective (2026-05-26T17:50:31Z)
-
-### Session summary
-
-All three stages (planning, TDD, ship) completed in a single session with zero user corrections.
-Four TDD commits landed cleanly, CI passed on first push, issue #219 closed, and `pi-subagents-v7.8.1` released.
-
-### Observations
-
-#### What went well
-
-- Clean incremental verification: `pnpm vitest run <file>` ran after every code change, full suite at the end.
-  No regressions at any step.
-- The plan's decision to keep gated runners inline proved correct — tests with `Promise.withResolvers` flow control stayed readable without abstraction.
-- The `write` tool was the right choice for `conversation-viewer.test.ts` and `agent-config-editor.test.ts` (pervasive changes), while `edit` with 16 targeted replacements worked cleanly for `agent-manager.test.ts` (scattered but formulaic substitutions).
-- Ship stage used `deepseek-v4-flash` for purely mechanical CI/release steps — appropriate model-task alignment.
-
-#### What caused friction (agent side)
-
-- `other` — ESLint pre-commit hooks auto-fixed two cosmetic patterns (`activity = undefined` → bare destructuring; `session as unknown` cast removal), requiring re-stage + re-commit.
-  Impact: ~10 seconds per occurrence, no rework.
-  This is routine and inherent to the workflow.
-
-#### What caused friction (user side)
-
-- None observed.
-  The user's three-stage prompt chain (`/plan-issue` → `/tdd-plan` → `/ship-issue`) provided sufficient context at each stage with no manual intervention needed.