@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/retro/0205-decompose-render-widget-lines.md

@@ -1,64 +0,0 @@
----
-issue: 205
-issue_title: "Decompose renderWidgetLines (cognitive 44)"
----
-
-# Retro: #205 — Decompose renderWidgetLines
-
-## Stage: Planning (2026-05-25T15:27:45Z)
-
-### Session summary
-
-Planned the decomposition of `renderWidgetLines` (cognitive complexity 44) into four private helper functions: `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow`.
-Also updated `architecture.md` Phase 12 steps with issue links (#205–#208) and added a Phase 12 row to the structural refactoring issues table.
-
-### Observations
-
-- The function's complexity comes from five interwoven concerns (categorization, section building, heading, non-overflow assembly with connector fixup, overflow-budget assembly) — but the extraction is mechanical since all logic is already pure and stateless.
-- No new tests are needed — the existing 8 tests in `widget-renderer.test.ts` cover all branches end-to-end and remain the correct test level for assembly logic.
-- The tree-connector fixup (swapping `├─` → `└─` via string replacement on Unicode chars) is the most fragile part; it stays as-is inside `assembleWithinBudget` rather than being further decomposed.
-- A `sections` return object from `buildSections` bundles `finishedLines`, `runningLines`, and `queuedLine` to avoid long parameter lists on the assembly helpers.
-
-## Stage: Implementation — TDD (2026-05-25T15:35:10Z)
-
-### Session summary
-
-Completed all four TDD steps: extracted `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow` from `renderWidgetLines`.
-All 23 `widget-renderer.test.ts` tests pass throughout; no new tests were added.
-Full suite (856 tests, 54 files) is green; type check and lint are clean.
-
-### Observations
-
-- **Stray backtick during `assembleOverflow` extraction:** The Edit tool introduced a double-backtick (`\`\``) at the end of the nested template literal on the overflow indicator line — the inner template literal's closing backtick concatenated with the outer template's closing backtick, creating a parse error.
-  Required Python-based line-level surgery to fix since the Edit tool cannot reliably match nested template literals through JSON escaping.
-- The `renderWidgetLines` `else` block removal also required Python because the Edit tool's `oldText` matching is unreliable when the target contains nested template literals with backticks.
-- Aside from the template-literal matching friction, all extractions were purely mechanical; no logic changes were needed.
-- The final `renderWidgetLines` is a clean 12-line orchestrator; each helper is well under complexity 10.
-
-## Stage: Final Retrospective (2026-05-25T15:41:48Z)
-
-### Session summary
-
-All three stages (planning, TDD implementation, shipping) completed in a single session.
-Four refactor commits extracted `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow` from `renderWidgetLines`, reducing cognitive complexity from 44 to <10 per function.
-Released as `pi-subagents-v7.2.6`.
-
-### Observations
-
-#### What went well
-
-- The planning-through-shipping pipeline was efficient: plan → 4 TDD steps → ship → release in one session with no rework.
-- The plan correctly identified all four extraction targets and ordered TDD steps to avoid intermediate breakage.
-- All 23 existing `widget-renderer.test.ts` tests passed throughout with zero modifications — the existing test coverage was at the right abstraction level for this refactoring.
-- The `architecture.md` Phase 12 update (issue links, refactoring table row) was a clean opportunistic addition.
-
-#### What caused friction (agent side)
-
-- `other` (Edit tool limitation) — The Edit tool introduced a stray double-backtick when inserting `assembleOverflow`'s body, caused by JSON escaping colliding with nested template literal backticks.
-  The same limitation then prevented matching `oldText` containing nested template literals in the `renderWidgetLines` overflow block.
-  Required two Python-based line-level fixes via bash.
-  Impact: ~3 extra tool calls; self-identified and self-corrected.
-
-#### What caused friction (user side)
-
-- No friction observed.

package/docs/retro/0206-decompose-show-agent-detail.md

@@ -1,67 +0,0 @@
----
-issue: 206
-issue_title: "Decompose showAgentDetail (cognitive 33)"
----
-
-# Retro: #206 — Decompose showAgentDetail (cognitive 33)
-
-## Stage: Planning (2026-05-25T12:00:00Z)
-
-### Session summary
-
-Produced a 4-step plan to decompose `showAgentDetail` (cognitive 33) and `ejectAgent` (cognitive 20) in `ui/agent-config-editor.ts`.
-The plan extracts two exported pure functions (`buildMenuOptions`, `buildEjectContent`) with dedicated unit tests, plus three closure-internal handlers (`handleEdit`, `handleDelete`, `handleReset`).
-
-### Observations
-
-- Three of the six action handlers (`ejectAgent`, `disableAgent`, `enableAgent`) were already extracted as closure functions — only Edit, Delete, and Reset were inlined in the dispatch chain.
-- `buildMenuOptions` and `buildEjectContent` are ideal pure-function extractions: complex branching logic with no IO dependencies, previously untestable in isolation.
-- The existing 18 integration tests through `showAgentDetail` provide a strong safety net — no risk of behavior regression during extraction.
-- Chose to scope `ejectAgent` decomposition into this issue since the issue's outcome says "< 10 per function" and `ejectAgent` is at cognitive 20 in the same file.
-- `disableAgent` and `enableAgent` were explicitly deferred — their cognitive complexity is manageable and decomposing them would add scope without meaningful benefit.
-
-## Stage: Implementation — TDD (2026-05-25T11:55:00Z)
-
-### Session summary
-
-Completed all 4 TDD steps. 3 `refactor:` commits extract `buildMenuOptions`, the three inline handlers, and `buildEjectContent`; 1 `docs:` commit updates the architecture table.
-Test count grew from 21 to 33 (+12 new unit tests for the two exported pure functions).
-
-### Observations
-
-- A `newText: null` bug in the Edit tool corrupted `agent-config-editor.ts` during step 1; recovered immediately by rewriting the file with `Write`.
-- The test used `thinking: "auto"` which is not a valid `ThinkingLevel` — fixed by changing to `"low"` before the final commit; the type error was caught by `pnpm run check` after the TDD step.
-- `buildMenuOptions` extracted cleanly with early-return style (no `let menuOptions` intermediate); the refactored function passes all 5 new unit tests and all 21 existing integration tests.
-- `handleEdit`, `handleDelete`, and `handleReset` are closure-internal; they drop the outer `if (file)` guard since the menu only shows those options when `file` is defined.
-- `buildEjectContent` extracted from `ejectAgent` reduces `ejectAgent` to a thin IO function (~10 lines); no behavior change verified by the existing eject integration tests.
-
-## Stage: Final Retrospective (2026-05-25T12:10:00Z)
-
-### Session summary
-
-Completed full lifecycle — Planning, TDD (3 `refactor:` + 1 `docs:` commits, +12 tests), Ship, and Release (`pi-subagents-v7.2.7`) — in a single session with no user corrections.
-
-### Observations
-
-#### What went well
-
-- The three-stage workflow (plan → TDD → ship) executed without any user intervention between stages.
-  Each stage's retro notes provided clean context for the next.
-- Pure-function extraction pattern worked cleanly: `buildMenuOptions` and `buildEjectContent` exported for unit testing; `handleEdit`, `handleDelete`, `handleReset` kept as closure-internal, tested via existing integration tests.
-- The existing 21 integration tests caught no regressions across all 3 refactor commits — strong safety net for mechanical extraction.
-
-#### What caused friction (agent side)
-
-- `other` — Passed `newText: null` to the `Edit` tool during TDD step 1, injecting a literal `null` into `agent-config-editor.ts` and corrupting the file.
-  Self-identified immediately via Biome autoformat failure.
-  Impact: one wasted tool round-trip; recovered by rewriting the file with `Write`.
-- `missing-context` — Used `thinking: "auto"` in a `buildEjectContent` test fixture without checking `ThinkingLevel` is `"minimal" | "low" | "medium" | "high" | "xhigh"`.
-  Self-identified by `pnpm run check` post-TDD gate.
-  Impact: one `--amend` fix, no extra commit.
-- `missing-context` — Plan stated "18 tests" as the baseline count; actual baseline was 21.
-  Impact: none — just an inaccurate number in the plan text.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The user triggered each stage sequentially without needing to redirect or correct.

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.