@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/retro/0108-extract-agent-type-registry.md

@@ -1,41 +0,0 @@
----
-issue: 108
-issue_title: "refactor(pi-subagents): extract AgentTypeRegistry class from module-scoped state"
----
-
-# Retro: #108 — extract AgentTypeRegistry class
-
-## Final Retrospective (2026-05-21T13:30:00Z)
-
-### Session summary
-
-Planned and implemented the `AgentTypeRegistry` class extraction from module-scoped state in `agent-types.ts`.
-The lift-and-shift approach across 7 TDD steps (9 commits including plan and docs) migrated 11 source files and 11 test files while keeping 574 tests green at every commit.
-The `reloadCustomAgents` callback was removed from `AgentToolDeps` and `AgentMenuDeps`, replaced by `deps.registry.reload()`.
-
-### Observations
-
-#### What went well
-
-- The `AgentConfigLookup` narrow interface (ISP) for `session-config.ts` kept tests simple — plain objects with 2 methods, no class instantiation needed.
-- Using `vi.spyOn` on a real `AgentTypeRegistry` instance in `agent-menu.test.ts` was cleaner than `vi.hoisted` + `vi.fn()` factories: correct types, automatic cleanup via `vi.restoreAllMocks()`.
-- Step 2 (inject through 4-file config-assembly chain) was the riskiest single step but landed cleanly because the `vi.mock("agent-types.js")` stubs were narrowed to only the free functions that `session-config.ts` still imports (`getMemoryToolNames`, `getReadOnlyMemoryToolNames`).
-
-#### What caused friction (agent side)
-
-1. `missing-context` — The plan's "Test files affected" table listed 8 files but missed 3 (`prompts.test.ts`, `tools/get-result-tool.test.ts`, `conversation-viewer.test.ts`) that directly import symbols being removed in step 7.
-   The grep during planning found `prompts.test.ts` as an importer of `registerAgents` but didn't include it in the table.
-   Impact: 3 extra test files needed updating in step 7; caught by the full-suite run, not by surprise in CI.
-
-2. `wrong-abstraction` — First `perl -0777` regex for bulk-updating 16 `ConversationViewer` constructor calls in `conversation-viewer.test.ts` failed because the character class `[^)]+` didn't match the multi-line arguments.
-   A simpler pattern targeting just the `vi.fn(),\n  );` suffix worked on the second try.
-   Impact: added friction but no rework — ~2 minutes.
-
-3. `missing-context` — Type check after step 7 revealed `promptMode: string` vs `"replace" | "append"` narrowing issue in `agent-runner-extension-tools.test.ts`.
-   The `agentConfigMock.current` object had `promptMode: "replace"` which TypeScript widened to `string` when spread into the mock `AgentConfigLookup` return.
-   Impact: one additional edit with a return-type annotation; caught by `pnpm run check` as recommended by the testing skill.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The issue description was clear, the architecture doc had the design already sketched, and no mid-session redirects were needed.

package/docs/retro/0109-extract-settings-manager.md

@@ -1,55 +0,0 @@
----
-issue: 109
-issue_title: "refactor(pi-subagents): extract SettingsManager class"
----
-
-# Retro: #109 — extract SettingsManager class
-
-## Final Retrospective (2026-05-21T17:30:00Z)
-
-### Session summary
-
-Planned and implemented the `SettingsManager` class extraction across 8 TDD cycles plus doc updates.
-The class owns `defaultMaxTurns`, `graceTurns`, and `maxConcurrent` with normalizing property accessors, a `load()` method for merged config, and `saveAndNotify()` for persistence + lifecycle events.
-Six settings-related callback fields in `AgentMenuDeps` collapsed to a single `settings` collaborator (13 → 8 fields), and `SettingsAppliers`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged` were removed.
-A follow-up issue (#118) was filed for a LoD/Tell-Don't-Ask violation the user identified in the post-implementation review.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift TDD approach worked cleanly: the new class was built and tested in isolation (cycles 1–2), consumers migrated one at a time (cycles 3–5), wiring consolidated (cycle 6), and old code removed last (cycles 7–8).
-  Each commit left the repo in a valid state.
-- The user's design critique (LoD / Tell-Don't-Ask on `deps.settings.saveAndNotify()` orchestration) was sharp and led to a concrete follow-up issue (#118) with a clear fix.
-  The session handled it well — acknowledged, designed the fix, filed the issue, updated the architecture doc, and stopped without scope-creeping into implementation.
-
-#### What caused friction (agent side)
-
-1. `wrong-abstraction` — The plan did not anticipate that changing `AgentMenuDeps` (cycle 3) would immediately break `index.ts` type-checking.
-   Each interface change in cycles 3, 4, and 5 required a same-commit bridge fix in `index.ts` to keep `pnpm run check` clean.
-   The plan's separation of "migrate consumers" (cycles 3–5) from "wire in index.ts" (cycle 6) was too coarse — interface changes propagate to the call site immediately.
-   Impact: three unplanned bridge edits in `index.ts`, each small but requiring context-switching mid-cycle.
-
-2. `missing-context` — The `sed` command in cycle 5 (`sed -i '' 's/maxConcurrent: 1,/getMaxConcurrent: () => 1,/g'`) missed two call sites where `maxConcurrent: 1` had no trailing comma (end of object literal).
-   A `grep` check after the `sed` would have caught this immediately.
-   Impact: two tests failed unexpectedly; required a follow-up read + manual edit before the cycle could complete.
-
-3. `missing-context` — The Edit tool failed on `runtime.ts` because the file uses `─` (U+2500, BOX DRAWINGS LIGHT HORIZONTAL) in section separators, not `—` (U+2014, EM DASH).
-   The Unicode characters looked identical in the terminal, and the Edit tool's exact-match requirement meant the mismatch was silent until the replacement failed.
-   Impact: three failed Edit attempts before falling back to a Python script for the replacement.
-   This is the same class of issue seen in previous sessions with Unicode characters in source files.
-
-4. `premature-convergence` — The plan designed `SettingsManager` as a data holder with persistence methods but didn't consider whether the menu should orchestrate across `settings` and `manager` or whether `SettingsManager` should own the full consequence chain.
-   The user caught this as a LoD/Tell-Don't-Ask violation in post-implementation review.
-   Impact: no rework (filed as follow-up #118), but the design could have been better from the start if the plan had applied the design-review checklist's LoD check to the proposed `showSettings` interaction pattern.
-
-#### What caused friction (user side)
-
-- The user's LoD critique was well-timed — after implementation was complete, avoiding mid-stream rework.
-  If the critique had surfaced during planning (e.g., by the agent applying the design-review checklist to the proposed consumer interaction pattern), the follow-up issue might have been part of the original scope.
-  This is an opportunity for the planning step to simulate the consumer's call sites before finalizing the design, not just the class interface.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — Added consumer call-site sketch heuristic to the "Design Overview" section: when a new collaborator is introduced, sketch 3–5 lines of consumer pseudocode to verify Tell-Don't-Ask and LoD.
-2. `.pi/skills/testing/SKILL.md` — Added TDD planning rule: when a step changes an interface with a single call site, the step must include updating that call site (type checker enforces co-location).

package/docs/retro/0110-agent-activity-tracker.md

@@ -1,44 +0,0 @@
----
-issue: 110
-issue_title: "refactor(pi-subagents): wrap AgentActivity in AgentActivityTracker class"
----
-
-# Retro: #110 — wrap AgentActivity in AgentActivityTracker class
-
-## Final Retrospective (2026-05-21T23:30:00Z)
-
-### Session summary
-
-Planned and implemented `AgentActivityTracker` class across 6 TDD cycles plus doc updates, released as `pi-subagents-v6.7.0`.
-The 7-field mutable `AgentActivity` interface was replaced with a class exposing explicit transition methods (`onToolStart`, `onToolEnd`, `onMessageStart`, `onMessageUpdate`, `onTurnEnd`, `onUsageUpdate`, `setSession`) and read-only accessors.
-All 7 source files and 3 test files were migrated incrementally without any big-bang commit.
-
-### Observations
-
-#### What went well
-
-- **TDD Red phase caught all three implementation bugs.**
-  1. `onToolEnd` initially incremented `toolUses` unconditionally (ported from original code), but the plan specified no-op defensive behavior.
-     The Red phase test `"onToolEnd with no matching tool is a no-op"` caught it instantly.
-  2. `Date.now()` key collision in `activeTools` Map — two `onToolStart("Read")` calls in the same millisecond produced identical keys, so the second overwrote the first.
-     The Red phase test `"multiple concurrent tools with same name tracked independently"` caught it.
-  3. `describeActivity` signature needed `ReadonlyMap<string, string>` after the accessor change — caught by `pnpm run check` in step 3.
-  All three were fixed immediately with no cascading rework.
-- **Incremental migration avoided type breakage.**
-  The plan kept `AgentActivity` alive in `agent-widget.ts` until step 3, so steps 1–2 compiled without touching downstream files.
-  Each step only broke the files it was about to migrate, keeping intermediate states valid.
-- **Monotonic counter is strictly better than `Date.now()` for tool keys.**
-  The extraction enabled replacing the `toolName + "_" + Date.now()` key strategy with `toolName + "_" + (++this._toolKeySeq)`, which never collides regardless of timing.
-  This is a concrete improvement the original inline code couldn't easily adopt.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan specified the `Date.now()` key strategy from the original code, but didn't account for same-millisecond collisions in test execution.
-  Impact: ~1 minute debugging in step 1; trivial fix to monotonic counter.
-- `premature-convergence` — Initial `onToolEnd` implementation copied the original's unconditional `toolUses++` before checking the plan's specified no-op behavior.
-  Impact: caught immediately by the Red phase test, single-line fix.
-
-#### What caused friction (user side)
-
-- No material friction observed.
-  The session ran end-to-end (plan → implement → ship → release) without user intervention.

package/docs/retro/0111-split-agent-record-lifecycle.md

@@ -1,61 +0,0 @@
----
-issue: 111
-issue_title: "refactor(pi-subagents): split AgentRecord lifecycle state into phase-specific objects"
----
-
-# Retro: #111 — split AgentRecord lifecycle state into phase-specific objects
-
-## Final Retrospective (2026-05-22T01:50:00Z)
-
-### Session summary
-
-Planned and implemented the `AgentRecord` lifecycle split across 12 TDD cycles plus doc updates, released as `pi-subagents-v6.8.0`.
-Three new phase-specific collaborators (`ExecutionState`, `WorktreeState`, `NotificationState`) replace 9 post-construction mutable fields.
-`pendingSteers` moved to a `Map` on `AgentManager`; stats (`toolUses`, `lifetimeUsage`, `compactionCount`) encapsulated behind mutation methods with read-only getters.
-`AgentRecordInit` trimmed from 19 optional fields to 4.
-
-### Observations
-
-#### What went well
-
-- **Lift-and-shift scaled from 7 files (#110) to 18 files (#111) without any intermediate test breakage.**
-  Every commit left all 41 test files passing.
-  The pattern — add new alongside old, migrate consumers with fallbacks (`record.execution?.session ?? record.session`), strip fallbacks in a final commit — is reliable for multi-step encapsulation refactors.
-- **Stats encapsulation was simpler than expected.**
-  Converting `toolUses`, `lifetimeUsage`, `compactionCount` to private fields with getters and mutation methods required zero changes to read-only consumers because the getter names match the old field names.
-  Only `record-observer.ts` (the sole writer) needed updating.
-- **The `createTestRecord` factory intersection type trick preserved backward compatibility.**
-  The factory accepts `toolUses?: number` via `Partial<AgentRecordInit> & { toolUses?: number; ... }` and internally calls `record.incrementToolUses()` in a loop.
-  This let 10+ test files continue passing `toolUses: 5` without rewriting each to call mutation methods directly.
-- **`Promise.withResolvers` timing analysis in the plan was unnecessary.**
-  The plan spent ~40 lines analyzing whether `promise` should live inside `ExecutionState` and concluded it should stay separate.
-  Implementation confirmed: `record.execution` is set in `onSessionCreated` (async callback), `record.promise` is set after `runner.run()` (synchronous return) — different moments, straightforward.
-
-#### What caused friction (agent side)
-
-- `missing-context` — In the step 7 test for `record.execution`, the initial mock runner used `mockResolvedValue(...)` which doesn't call `onSessionCreated`, so `record.execution` stayed `undefined`.
-  Had to switch to `mockImplementation(async (..., opts) => { opts.onSessionCreated?.(session); ... })`.
-  The existing tests in the same file already use this pattern for record-observer tests, but I didn't check them first.
-  Impact: one test rewrite (~2 minutes), no rework to production code.
-- `scope-drift` — Step 4 absorbed step 5 (adding collaborator fields) without noting the merge in the commit or session log.
-  Step 5 became a no-op.
-  Impact: no rework, but the session narrative skipped a plan step without explanation.
-- `wrong-abstraction` — Step 12 was planned as a simple cleanup ("remove old fields and trim `AgentRecordInit`") but required coordinated changes across 18 files: removing 9 fields from `AgentRecordInit`, updating the `createTestRecord` factory, fixing 5 test files that passed removed fields, and stripping all fallback patterns.
-  This was 2-3 steps' worth of work compressed into one.
-  Impact: step 12 took significantly longer than other steps, though it landed cleanly.
-- `missing-context` — Did not proactively flag the `as ReturnType<typeof vi.fn>` cast smell in `service-adapter.test.ts` while migrating that file.
-  The user noticed it and asked about it.
-  Filed as #123.
-  Impact: added friction but no rework; follow-up issue created.
-  User-caught.
-
-#### What caused friction (user side)
-
-- No material friction observed.
-  The user's `ask_user` decisions during planning (NotificationState collaborator, Map on AgentManager) gave clear direction.
-  Quick "follow-up" response on the cast smell kept scope tight.
-
-### Changes made
-
-1. `packages/pi-subagents/docs/retro/0111-split-agent-record-lifecycle.md` — this retro file.
-2. `.pi/skills/testing/SKILL.md` — added field-removal rule symmetric to the existing field-addition rule (esbuild silent pass-through on unknown init properties).

package/docs/retro/0112-replace-agent-manager-callbacks.md

@@ -1,35 +0,0 @@
----
-issue: 112
-issue_title: "refactor(pi-subagents): replace AgentManager callbacks with observer interface"
----
-
-# Retro: #112 — replace AgentManager callbacks with observer interface
-
-## Final Retrospective (2026-05-21T21:00:00-04:00)
-
-### Session summary
-
-Replaced three fire-and-forget callback fields (`onStart`, `onComplete`, `onCompact`) on `AgentManagerOptions` with a single `AgentManagerObserver` interface.
-The refactoring touched `agent-manager.ts`, `index.ts`, and `agent-manager.test.ts` with zero test-count delta (652/652).
-Released as `pi-subagents-v6.8.2`.
-
-### Observations
-
-#### What went well
-
-- The issue description was thorough and unambiguous — no `ask_user` needed during planning, and the design mapped directly to implementation.
-- Self-identified the testing skill's single-call-site rule during execution: the plan split Steps 2 and 3 into separate commits, but `AgentManagerOptions` has one call site in `index.ts`, so both had to land together.
-  Merged them without rework.
-- Pre-existing lint issue (unused `ExecutionState` import in `agent-manager.ts`) caught and fixed proactively during the lint step.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` (self-identified) — The plan wrote TDD Steps 2 and 3 as separate commits, but the testing skill says "when a TDD step changes an interface that has a single call site, the step must include updating that call site."
-  The planning phase loaded the testing skill but didn't apply this specific rule when structuring the TDD order.
-  Impact: added friction but no rework — caught during execution when `pnpm run check` surfaced the expected type error in `index.ts` after Step 2.
-- `other` (tool interaction) — One `Edit` tool `oldText` match failure in `agent-manager.ts` because the selected block included a blank line that didn't exist between `subscribeRecordObserver` and `options.onSessionCreated`.
-  Impact: one extra read + edit cycle (~30 seconds).
-
-#### What caused friction (user side)
-
-- Nothing — the session ran without user corrections or redirections.

package/docs/retro/0113-disambiguate-spawn-options.md

@@ -1,29 +0,0 @@
----
-issue: 113
-issue_title: "refactor(pi-subagents): disambiguate SpawnOptions (public vs internal)"
----
-
-# Retro: #113 — disambiguate SpawnOptions (public vs internal)
-
-## Final Retrospective (2026-05-21T21:10:00-04:00)
-
-### Session summary
-
-Renamed the internal `SpawnOptions` in `agent-manager.ts` to `AgentSpawnConfig` to disambiguate it from the public `SpawnOptions` in `service.ts`.
-Pure mechanical rename across 4 files with zero test-count delta (652/652).
-Released as `pi-subagents-v6.8.3`.
-
-### Observations
-
-#### What went well
-
-- Completely frictionless execution — single-step plan executed exactly as written with no corrections, rework, or failed edits.
-- The session benefited from context already loaded during the preceding #112 cycle (same package, same skills, same source files), which made planning and execution faster.
-
-#### What caused friction (agent side)
-
-- Nothing — the rename was purely mechanical and the plan matched reality exactly.
-
-#### What caused friction (user side)
-
-- Nothing — no user intervention needed.

package/docs/retro/0114-narrow-agent-tool-menu-deps.md

@@ -1,38 +0,0 @@
----
-issue: 114
-issue_title: "refactor(pi-subagents): narrow AgentToolDeps and AgentMenuDeps"
----
-
-# Retro: #114 — narrow AgentToolDeps and AgentMenuDeps
-
-## Final Retrospective (2026-05-21T21:43:48-04:00)
-
-### Session summary
-
-Narrowed `AgentToolDeps` from 9 to 6 fields and `AgentMenuDeps` from 8 to 7 fields.
-Moved `subagents:created` event emission from the Agent tool to a new `AgentManagerObserver.onAgentCreated` method.
-Extracted `buildTypeListText` to `tools/helpers.ts`, derived description text inside `createAgentTool`, removed dead `emitEvent` from `AgentMenuDeps`, and narrowed `agentActivity` to typed `AgentActivityAccess`/`AgentActivityReader` interfaces.
-Test count increased from 638 to 660.
-Released as `pi-subagents-v6.9.0`.
-
-### Observations
-
-#### What went well
-
-- The `ask_user` gate during planning was well-targeted.
-  The first question (where to move `emitEvent`) had a clear answer.
-  The second (description-text derivation) genuinely needed user input, and the user requested more context via the "I could use more context" response — the follow-up `preview`-type question with fenced code blocks handled this cleanly.
-- The 6-step TDD plan mapped to implementation with only one deviation (see below), caught exactly where the workflow is designed to catch it (the `pnpm run check` step).
-- All 6 prerequisites (#108, #109, #110, #112, #113, #118) were verified as closed before planning.
-  The observer issue (#112) was correctly identified from a `gh issue list` grep despite not being explicitly numbered in the issue body (the issue said "the observer issue").
-
-#### What caused friction (agent side)
-
-- `missing-context` (self-identified) — Step 6 narrowed `agentActivity` from `Map<string, AgentActivityTracker>` to `AgentActivityAccess` (which exposes only `get`/`set`/`delete`), but the test in `agent-tool.test.ts` used `.has()` on the map.
-  The `pnpm run check` typecheck caught `Property 'has' does not exist on type 'AgentActivityAccess'`.
-  Fixed by replacing `.has(id)` with `.get(id) !== undefined` in the same commit.
-  Impact: one extra read + edit cycle (~30 seconds), no rework.
-
-#### What caused friction (user side)
-
-- Nothing — no user corrections or redirections needed during the session.

package/docs/retro/0115-decompose-agent-tool.md

@@ -1,51 +0,0 @@
----
-issue: 115
-issue_title: "refactor(pi-subagents): decompose agent-tool.ts into foreground/background modules"
----
-
-# Retro: #115 — decompose agent-tool.ts into foreground/background modules
-
-## Final Retrospective (2026-05-21T22:30:00-04:00)
-
-### Session summary
-
-Decomposed the 579-line `tools/agent-tool.ts` into focused modules: `foreground-runner.ts` (spinner, streaming, cleanup) and `background-spawner.ts` (activity setup, notification wiring), with `agent-tool.ts` remaining as the orchestrator (411 lines).
-Before extracting, fixed two upstream API gaps: widened `onSessionCreated` callback to `(session, record)` to eliminate a `listAgents()` reverse-search, and added `toolCallId` to `AgentSpawnConfig` so the manager wires `NotificationState` at spawn time.
-Test count increased from 641 to 690.
-Released as `pi-subagents-v6.9.1`.
-
-### Observations
-
-#### What went well
-
-- The revised plan (after user feedback) was structurally clean — fixing API gaps first made the extraction trivial; each extracted module received only what it needed without workarounds.
-- TDD execution was smooth: 6 steps, all green after each commit, only minor deviations (type annotation issue, `index.ts` call-site fix).
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` (user-caught) — The initial plan was a mechanical code-move that defined 4 new interfaces (`ForegroundRunDeps`, `BackgroundSpawnDeps`, `ForegroundRunParams`, `BackgroundSpawnParams`) to paper over two upstream API gaps: a `listAgents()` reverse-search in the foreground `onSessionCreated` callback, and a post-spawn `record.notification` mutation in the background path.
-  The user asked *"What dependencies are still missing for these split tools, that they want, rather than some low level state or collaborators that they have?"*
-  — redirecting me to fix the API surface before extracting.
-  Impact: entire plan rewritten (~15 minutes), but the revised plan was significantly cleaner and the implementation went smoothly.
-
-- `missing-context` (self-identified) — During step 5 (foreground extraction), two tests in `foreground-runner.test.ts` failed because mock sessions were `{}` objects lacking a `subscribe` method required by `subscribeUIObserver`.
-  The function's dependency on `SubscribableSession` (requiring `.subscribe()`) wasn't accounted for in the test mock.
-  Impact: one test fix cycle (~2 minutes), no rework.
-
-- `missing-context` (self-identified) — Annotating `runForeground` with an explicit `Promise<AgentToolResult<any>>` return type widened the content array type from `{ type: "text", text: string }[]` to `(TextContent | ImageContent)[]`, breaking existing `content[0].text` patterns in tests.
-  Fixed by removing the explicit annotation and letting TypeScript infer the narrow type.
-  Impact: three edit cycles to diagnose and fix (~5 minutes).
-
-- `missing-context` (self-identified) — Step 1 removed `listAgents` from `AgentToolManager` but didn't update the construction site in `index.ts`.
-  `pnpm run check` caught it in step 4.
-  Impact: one-line fix in the same commit, no rework.
-
-#### What caused friction (user side)
-
-- The initial plan's size and mechanical nature required a user redirect.
-  The `/plan-issue` prompt's Design Overview section asks to sketch consumer call sites for *new collaborators*, but the same Tell-Don't-Ask check should apply to *extracted* modules' interactions with their upstream dependencies.
-  A prompt tweak could help the agent catch this pattern earlier.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added extraction-specific Tell-Don't-Ask verification step to the Design Overview section: sketch the extracted module's upstream interactions before planning the extraction, fix API gaps first.

package/docs/retro/0116-type-housekeeping.md

@@ -1,42 +0,0 @@
----
-issue: 116
-issue_title: "refactor(pi-subagents): type housekeeping and small structural cleanups"
----
-
-# Retro: #116 — type housekeeping and small structural cleanups
-
-## Final Retrospective (2026-05-21T23:00:00Z)
-
-### Session summary
-
-Planned and executed 6 refactoring steps for issue #116: relocated 3 misplaced types from `types.ts` to their natural home modules, converted `createNotificationSystem` closure to a `NotificationManager` class, switched `ConversationViewer` to an options-bag constructor, and defined `AgentIdentity`/`AgentPromptConfig` narrow subset interfaces.
-All 690 tests stayed green throughout; no behavioral changes.
-Released as `pi-subagents-v6.9.2`.
-
-### Observations
-
-#### What went well
-
-- The Python script approach for bulk-converting 16 `ConversationViewer` positional constructor calls to options-bag syntax was efficient and correct on the first attempt — all 17 tests passed immediately after the conversion.
-- Proactive `grep -rn 'new ConversationViewer'` before step 5 caught the `agent-menu.ts` call site that the plan's Module-Level Changes section had omitted, avoiding a broken commit.
-- The architecture doc update was clean — 5 targeted edits to mark E2 done, update smells table, and fix metrics.
-
-#### What caused friction (agent side)
-
-- `missing-context` — In all three type-relocation steps (1–3), I updated source-file imports but did not pre-flight grep for test-file imports of the relocated symbol.
-  Each time, `pnpm run check` caught the stale test import, requiring an extra edit-check round trip.
-  This happened with `test/renderer.test.ts` (step 1), `test/agent-runner.test.ts` + `test/agent-runner-extension-tools.test.ts` (step 2), and `test/prompts.test.ts` (step 3).
-  Impact: 3 unnecessary edit-check cycles; no broken commits since the type checker caught every case before `git commit`.
-
-- `missing-context` — In step 4, the first `Edit` call on `src/index.ts` failed because the autoformatter had merged the `NotificationDetails` type import (added in step 1) into the existing notification import line, changing the text I expected.
-  Had to re-read the file to find the current import text.
-  Impact: one wasted edit call plus a file read; added ~10 seconds of friction.
-
-#### What caused friction (user side)
-
-- No friction observed — the user's prompts were clear and the `/tdd-plan` and `/ship-issue` templates provided all needed structure.
-
-### Takeaway
-
-When relocating a type or symbol, always run `grep -rn 'SymbolName' src/ test/` before editing to identify *all* importers upfront — both source and test files.
-This avoids the repeated pattern of "edit source → type-check fails on test → fix test → type-check again."

package/docs/retro/0118-settings-manager-apply-methods.md

@@ -1,40 +0,0 @@
----
-issue: 118
-issue_title: "refactor(pi-subagents): SettingsManager apply methods — eliminate cross-collaborator orchestration"
----
-
-# Retro: #118 — SettingsManager apply methods
-
-## Final Retrospective (2026-05-21T21:00:00Z)
-
-### Session summary
-
-Planned and implemented 3 `apply*` methods on `SettingsManager` (`applyMaxConcurrent`, `applyDefaultMaxTurns`, `applyGraceTurns`) across 5 TDD cycles plus doc updates, released as `pi-subagents-v6.6.0`.
-Each method owns the full consequence chain (normalize → set → callback → persist → emit → return toast), eliminating the LoD/Tell-Don't-Ask violation in `showSettings` that was identified during the #109 retro.
-`notifyConcurrencyChanged` was removed from `AgentMenuManager`; the menu no longer coordinates between settings and the agent manager.
-
-### Observations
-
-#### What went well
-
-- **Retro-driven improvement validated.**
-  Issue #118 was filed during the #109 retro as a LoD/Tell-Don't-Ask follow-up, and the plan-issue prompt's consumer call-site sketch heuristic (added in #109's retro) was already in the plan template.
-  The plan for #118 included concrete before/after call-site sketches that made the design unambiguous — no `ask-user` decision needed.
-- **Interface-then-wiring TDD order worked cleanly.**
-  The #109 retro noted that interface changes propagate to `index.ts` immediately, forcing unplanned bridge edits.
-  This time the plan accounted for it: Cycle 4 committed only menu files (leaving a known `index.ts` type error), and Cycle 5 fixed the wiring in a separate commit.
-  The intermediate type error was contained and expected.
-- **`defaultMaxTurns` branch consolidation.**
-  During Cycle 4, the separate `n === 0` and `n >= 1` branches in `showSettings` were consolidated to a single `n >= 0` check, since `applyDefaultMaxTurns` handles the 0→unlimited mapping internally.
-  This was a minor but correct simplification that emerged naturally from the Tell-Don't-Ask refactor.
-
-#### What caused friction (agent side)
-
-- No material friction.
-  All 5 TDD cycles completed without rework, failed edits, or unexpected test failures.
-  The plan was tight and the issue's "Proposed change" section was unambiguous.
-
-#### What caused friction (user side)
-
-- No material friction observed.
-  The session ran end-to-end (plan → implement → ship → release) without user intervention.

package/docs/retro/0123-remove-vi-fn-cast-smell.md

@@ -1,49 +0,0 @@
----
-issue: 123
-issue_title: "refactor(pi-subagents): remove vi.fn() cast smell from test helpers"
----
-
-# Retro: #123 — remove vi.fn() cast smell from test helpers
-
-## Final Retrospective (2026-05-22T00:00:00Z)
-
-### Session summary
-
-Planned and implemented removal of all 9 `as ReturnType<typeof vi.fn>` casts and 5 `vi.mocked()` calls across 3 test files, replacing them with named typed mock variables.
-Released as `pi-subagents-v6.8.1`.
-Pure test hygiene — no production code changes, no behavioral changes, 652 tests unchanged.
-
-### Observations
-
-#### What went well
-
-- **Three-file scope executed cleanly once the plan was right.**
-  Each file was an independent commit with no cross-file dependencies.
-  The named-variable pattern (`const mockGetRecord = vi.fn<AgentManagerLike["getRecord"]>()`) worked identically across all three test files despite different mock construction styles (factory function vs `beforeEach` assignment).
-
-#### What caused friction (agent side)
-
-- `scope-drift` — The initial plan scoped the fix to `service-adapter.test.ts` only, listing `lifecycle.test.ts` and `tool-start.test.ts` as explicit Non-Goals — despite the planning-phase grep showing all 9 cast sites across 3 files.
-  The user redirected with "let's eliminate this pattern of behavior."
-  Updated the GitHub issue body, rewrote the plan, and amended the commit.
-  Impact: plan rewrite (~2 minutes), no implementation rework.
-  User-caught.
-- `missing-context` — Imported `MockInstance` from `vitest` during step 1 (`service-adapter.test.ts`) but actually used `ReturnType<typeof vi.fn<...>>` — matching the pattern used in the other two files.
-  The unused import was caught by `pnpm run lint` at the post-implementation check, not proactively.
-  Impact: one extra edit + amend cycle.
-  Self-identified (via lint).
-- `other` — Ran `git commit --amend` to fix the unused import but HEAD was step 3's commit (`tool-start`), not step 1's (`service-adapter`).
-  The amend landed the `service-adapter.test.ts` change into the wrong commit with the wrong message.
-  Required `git reset --soft` back to the plan commit and recommitting all 3 files.
-  Impact: ~1 minute of git surgery, clean result.
-  Self-identified.
-
-#### What caused friction (user side)
-
-- The issue body scoped the fix to `service-adapter.test.ts` only, which the agent followed literally.
-  The broader intent ("eliminate this pattern") was implicit.
-  Flagging the desired scope as "all files with this pattern" in the issue body would have avoided the plan rewrite.
-
-### Changes made
-
-1. Wrote retro file at `packages/pi-subagents/docs/retro/0123-remove-vi-fn-cast-smell.md`.

package/docs/retro/0131-consolidate-shared-test-fixtures.md

@@ -1,46 +0,0 @@
----
-issue: 131
-issue_title: Consolidate shared test fixtures
----
-
-# Retro: #131 — Consolidate shared test fixtures
-
-## Final Retrospective (2026-05-22T11:30:00Z)
-
-### Session summary
-
-Planned and implemented the consolidation of six duplicated test factories into two shared helpers (`createMockSession` in `test/helpers/mock-session.ts`, `createToolDeps` in `test/helpers/make-deps.ts`).
-All 715 tests pass, released as `pi-subagents-v6.9.4`.
-The implementation was a pure test refactor with no production code changes.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift approach worked cleanly: create factory → migrate one consumer at a time → verify green after each step.
-  Each migration commit was small and isolated, making failures easy to diagnose.
-- Structural typing as a strategy proved out — `createToolDeps()` returns `AgentToolDeps` (the superset), and `spawnBackground(deps, ...)` and `runForeground(deps, ...)` accept their narrow `BackgroundDeps`/`ForegroundDeps` interfaces without any casting.
-
-#### What caused friction (agent side)
-
-- `missing-context` — Plan used `registry.resolve("general-purpose", "/dir")` in the `make-deps.test.ts` test, but `AgentTypeRegistry` has no `resolve` method — the correct method is `resolveAgentConfig()`.
-  Impact: one test failure during step 5 red→green, fixed immediately with no rework.
-
-- `missing-context` — Default values differed between the old narrow factories and the new shared factory: `"bg-1"` vs `"agent-1"` for spawn IDs (`background-spawner.test.ts`), `"Task done."` vs `"All done."` for result text (`foreground-runner.test.ts`).
-  Impact: two test failures in step 7, one in step 8, each requiring assertion updates before the migration step could pass.
-
-- `missing-context` — `MockSession` interface used `ReturnType<typeof vi.fn>` which expands to `Mock<Procedure | Constructable>` in Vitest v4 — a union type TypeScript cannot call.
-  Impact: `pnpm run check` failed after all TDD steps were done, requiring a separate `style:` commit to switch to explicitly parameterized `Mock<() => void>` etc.
-
-- `missing-context` — Removed the `AgentToolDeps` import from `agent-tool.test.ts` without checking that the `execute()` helper still referenced it.
-  Impact: caught in the same `pnpm run check` pass, fixed in the same `style:` commit.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The plan was unambiguous, and the session ran autonomously through all 8 TDD steps plus post-checks without intervention.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — added TDD planning rule for diffing default values when consolidating duplicate test factories.
-2. `.pi/skills/testing/SKILL.md` — added Vitest mock pattern rule for typing mock fields with `Mock<specific-signature>` instead of `ReturnType<typeof vi.fn>`.

package/docs/retro/0132-inject-io-into-session-config.md

@@ -1,33 +0,0 @@
----
-issue: 132
-issue_title: "Inject IO collaborators into `assembleSessionConfig`"
----
-
-# Retro: #132 — Inject IO collaborators into `assembleSessionConfig`
-
-## Final Retrospective (2026-05-22T12:25:00Z)
-
-### Session summary
-
-Defined an `AssemblerIO` interface bundling four IO/prompt collaborators, injected it into `assembleSessionConfig`, and updated `agent-runner.ts` to pass real implementations.
-Eliminated all 4 `vi.mock()` calls in `session-config.test.ts`, flattened the `vi.hoisted()` block into plain `vi.fn()` declarations, and shifted assertions from mock-call verification to output-property checks.
-Released as `pi-subagents-v6.10.0`.
-
-### Observations
-
-#### What went well
-
-- Perl two-pass replacement (multi-line then single-line) handled 40+ `assembleSessionConfig` call-site updates in one command with zero manual errors.
-- Flattening `vi.hoisted()` into regular `vi.fn()` declarations in step 3 was a clean simplification — hoisting was only needed when the mocks were referenced inside `vi.mock()` factories.
-- Real `getMemoryToolNames` / `getReadOnlyMemoryToolNames` worked as drop-in replacements with no test rework needed — the pure functions' behavior matched what the mocks were configured to return for all existing test scenarios.
-
-#### What caused friction (agent side)
-
-- `missing-context` — `mockBuildAgentPrompt` was declared as `vi.fn(() => "assembled system prompt")` which inferred `Mock<() => string>`.
-  When step 4 used `mockImplementationOnce` with a parameterized function, TypeScript rejected it.
-  The testing skill already documents `Mock<specific-signature>` for this exact case.
-  Impact: one type-check failure, fixed by adding `Mock<AssemblerIO["buildAgentPrompt"]>` annotation; added friction but no rework.
-
-#### What caused friction (user side)
-
-- Nothing notable — standard prompt-template workflow with no corrections needed.

package/docs/retro/0133-inject-sdk-boundary-into-agent-runner.md

@@ -1,45 +0,0 @@
----
-issue: 133
-issue_title: "Inject SDK boundary into `agent-runner`"
----
-
-# Retro: #133 — Inject SDK boundary into agent-runner
-
-## Final Retrospective (2026-05-22T13:15:00Z)
-
-### Session summary
-
-Injected all SDK and IO dependencies into `runAgent()` via a `RunnerIO` interface and `createAgentRunner(io)` factory.
-Eliminated all 14 `vi.mock()` calls across `agent-runner.test.ts` (7) and `agent-runner-extension-tools.test.ts` (7).
-Released as `pi-subagents-v6.11.0`.
-
-### Observations
-
-#### What went well
-
-- The `createAgentRunner(io)` factory pattern was a clean design choice that kept the `AgentRunner` interface and `AgentManager` completely unchanged — zero downstream impact.
-- Folding plan steps 1 and 2 into a single commit was the right call given `tsconfig.json` includes `test/` — recognized the constraint before attempting a broken intermediate commit.
-
-#### What caused friction (agent side)
-
-1. `wrong-abstraction` — Annotated `createRunnerIO(): RunnerIO` in the test helper, which erased the `Mock<...>` type information from `vi.fn()` stubs.
-   TypeScript then rejected `.mockResolvedValue()` on `io.createSession` across 18 call sites.
-   Required removing the annotation plus a follow-up edit to remove the now-unused `type RunnerIO` import flagged by Biome.
-   Impact: two extra edit rounds and a type-check cycle before the fix landed.
-
-2. `missing-context` — Added `SettingsManager` to the SDK import block in `index.ts` without checking that the name was already imported from `./settings.js`.
-   Biome caught the redeclaration and the `noRedeclare` lint error required an alias fix (`SettingsManager as SdkSettingsManager`).
-   Impact: one extra edit round triggered by the autoformat failure.
-
-3. `premature-convergence` — Spent excessive reasoning time deliberating commit-boundary strategy (whether to combine steps 1+2, how to handle broken intermediate states, whether step 4 would have remaining work).
-   The answer was straightforward once the `tsconfig` `include` was checked, but the check came late in the deliberation.
-   Impact: added friction but no rework — the final decision was correct.
-
-#### What caused friction (user side)
-
-- None identified.
-  The plan and issue were well-specified, and the user's only intervention was "Please, continue" after a message boundary, which was appropriate.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — added rule: do not annotate test factory return types with production interface types (erases `Mock<...>` methods).