@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/retro/0054-decompose-index-into-modules.md

@@ -1,53 +0,0 @@
----
-issue: 54
-issue_title: "refactor: decompose src/index.ts into tool + menu modules"
----
-
-# Retro: #54 — decompose index.ts into tool + menu modules
-
-## Final Retrospective (2026-05-18T02:20:00Z)
-
-### Session summary
-
-Decomposed `src/index.ts` from 1,619 lines to 265 lines across 8 commits.
-Extracted 7 new modules (`tools/helpers.ts`, `renderer.ts`, `notification.ts`, `tools/agent-tool.ts`, `tools/get-result-tool.ts`, `tools/steer-tool.ts`, `ui/agent-menu.ts`) with 66 new tests (379 → 445 total).
-Released as `pi-subagents-v4.1.1`.
-Filed follow-up #66 (replace `as any` casts with proper SDK types) and #67 (flaky `pi-autoformat` acceptance test).
-
-### Observations
-
-#### What went well
-
-- Leaf-first extraction order worked cleanly — helpers, then renderer, then notification, then tools, then menu.
-  Each step left the repo green with no cascading breakage.
-- The `createNotificationSystem` factory pattern with arrow-closure capture of `widget` (assigned after `AgentManager` construction) preserved the existing deferred-reference semantics without restructuring initialization order.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — Applied the code-style skill's "keep Pi SDK imports out of business-logic modules" rule to tool/menu modules, which are SDK consumers, not business logic.
-  Used `unknown` for `ExtensionContext`, `AgentSession`, `ModelRegistry` in factory dep interfaces, requiring 9 `as any` casts in `index.ts`.
-  User caught this post-ship.
-  Impact: filed #66 as a follow-up cleanup; the casts are cosmetic (no runtime effect) but degrade type safety.
-  Fixed the code-style skill to clarify the boundary. (user-caught)
-
-- `missing-context` — Four test files (`notification.test.ts`, `get-result-tool.test.ts`, `steer-tool.test.ts`, `agent-tool.test.ts`) omitted `compactionCount: 0` from `AgentRecord` factories.
-  Caught at the final `pnpm run check` step, not during test writing.
-  The testing skill already says "grep for ALL test files that construct a compatible mock."
-  Impact: one extra fix cycle delegated to a subagent, no rework beyond that step. (self-identified)
-
-- `other` — `Edit` tool failed 3 times matching the UTF-8 middle dot (`·`, U+00B7) in the steer tool's `stateParts.join(" · ")` line.
-  The third attempt produced a partial match that left the file in a broken state (dangling orphan code after the replacement anchor).
-  Required `git restore` and a fallback to `python3` line-range replacement.
-  The same `python3` approach for the menu extraction lost the closing `}` of the default export function.
-  Impact: ~5 minutes of rework across the two extraction steps, plus one `git restore`.
-
-#### What caused friction (user side)
-
-- The `as any` casts could have been caught earlier if the user had flagged the `unknown` types during the planning phase.
-  However, the plan didn't prescribe exact interface types — that was an implementation decision.
-  The user's post-ship review ("Why did we have to cast `as any`?
-  Take a look at `packages/pi-permission-system/` as a model") was an efficient redirect that immediately scoped the investigation.
-
-### Changes made
-
-1. `.pi/skills/code-style/SKILL.md` — Clarified SDK-boundary guidance: tool definitions, event handlers, and command handlers may import SDK types directly; the restriction targets pure helpers and domain modules.

package/docs/retro/0057-structured-debug-logging.md

@@ -1,77 +0,0 @@
----
-issue: 57
-issue_title: "feat: structured debug logging for silenced catch blocks"
----
-
-# Retro: #57 — structured debug logging for silenced catch blocks
-
-## Final Retrospective (2026-05-19T10:30:00Z)
-
-### Session summary
-
-Added `src/debug.ts` with `debugLog` and `isDebug()`, then threaded `debugLog` into ~20 silent `catch` blocks across 9 files.
-All 7 TDD cycles went green on the first pass with no rework.
-Shipped as `pi-subagents-v5.1.0`, then followed up with a `refactor:` commit converting `DEBUG` (module-level constant) to `isDebug()` (function getter) during the retro.
-
-### Observations
-
-#### What went well
-
-- The plan's "Non-Goals" section correctly excluded `usage.ts` and `settings.ts` before implementation started, and a post-TDD `grep -rn 'catch\s*{'` confirmed only those two in-scope-excluded files remained.
-  Closing the loop with a verification query is worth repeating.
-- The scope of the change was so well-defined (the issue listed exact file names) that no `ask_user` call was needed during planning.
-
-#### What caused friction (agent side)
-
-- `missing-context` — When loading the `ask-user` skill I guessed `.pi/skills/ask-user/SKILL.md` before reading the actual `<location>` tag in `AGENTS.md`, triggering an ENOENT error and a follow-up `find` call.
-  Impact: 2 extra tool calls, no rework. (self-identified)
-
-- `other` — The plan's TDD Order step 1 stated *"the test skill documents this pattern"* for `vi.resetModules()` + dynamic import when testing module-level env constants — but the testing skill does not have that entry.
-  The aspiration was recorded rather than verified.
-  During the retro, the user's question ("should that be a function getter instead?") led to a better outcome: replace the module-level constant with `isDebug()` so `vi.stubEnv()` alone works, consistent with how every other `process.env` read in this codebase is structured.
-  Impact: one retro-phase `refactor:` commit; the approach shipped in `v5.1.0` was technically correct but unnecessarily complex to test.
-
-#### What caused friction (user side)
-
-- The initial issue proposal chose the module-level-constant pattern (common in Node.js tooling like the `debug` package).
-  A note in the issue or plan about preferring function-based env reads for testability would have caught this at design time rather than post-ship.
-  That said, the retro question was efficient — a single targeted redirect resolved it cleanly.
-
-### Changes made
-
-1. `packages/pi-subagents/src/debug.ts` — replaced `export const DEBUG` with `export function isDebug()`.
-2. `packages/pi-subagents/test/debug.test.ts` — simplified to static import + `vi.stubEnv()` only; removed all `vi.resetModules()` + dynamic `import()` calls.
-3. `.pi/skills/testing/SKILL.md` — added bullet: prefer reading `process.env` inside functions; `vi.stubEnv()` alone is insufficient for module-level constants.
-
-## Follow-up Retrospective (2026-05-19T11:15:00Z)
-
-### Session summary
-
-The user asked how many `process.*` reads exist in `pi-subagents`.
-Audit found 9 sites: 4 acceptable (wiring layer, detection functions, injectable defaults), 2 genuine injection gaps, and 1 mild case.
-Filed #76 (`AgentManager.dispose()` reads `process.cwd()` without a stored `cwd`) and #77 (`createAgentsMenuHandler` hardcodes `process.cwd()` when `AgentMenuDeps` already injects the personal-side equivalent).
-
-### Observations
-
-#### What went well
-
-- The `isDebug()` refactor naturally led the user to ask a broader design question about `process.*` access patterns, producing two well-scoped follow-up issues without manual triage.
-- The audit categorization (genuinely problematic vs. acceptable) was clean — presenting a table with verdicts per site let the user decide scope without re-reading source.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — The original plan accepted the module-level `DEBUG` constant without checking how the rest of the codebase reads `process.env`.
-  The code-style skill said "keep IO at the edges" but didn't name `process.*` specifically, so the rule wasn't applied.
-  Impact: one post-ship `refactor:` commit to replace `DEBUG` with `isDebug()`; the pattern was technically correct but inconsistent with codebase conventions. (user-caught)
-
-#### What caused friction (user side)
-
-- Nothing notable.
-  The user's two redirecting questions ("should that be a function?"
-  and "how many places access `process.*`?") were well-timed interventions that broadened scope productively.
-
-### Changes made
-
-1. `.pi/skills/code-style/SKILL.md` — added bullet: do not read `process.env`, `process.cwd()`, or `process.platform` inside library/utility functions; accept the value as a parameter.
-2. Filed #76 — inject `cwd` into `AgentManager` constructor.
-3. Filed #77 — add `projectAgentsDir` to `AgentMenuDeps`.

package/docs/retro/0061-session-format-transcript.md

@@ -1,41 +0,0 @@
----
-issue: 61
-issue_title: "feat: port subagent transcript logging to Pi's official JSONL session format"
----
-
-# Retro: #61 — port subagent transcript logging to Pi's official JSONL session format
-
-## Final Retrospective (2026-05-20T17:15:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped a migration from the bespoke `output-file.ts` transcript format to Pi's official JSONL session format via `SessionManager.create()`.
-The change replaced 143 lines of manual streaming code with 3 lines leveraging the SDK's native persistence, nested subagent sessions under the parent session directory with `parentSession` header linking.
-Released as `pi-subagents-v6.0.0` (major version bump due to breaking transcript format change).
-
-### Observations
-
-#### What went well
-
-- The plan-to-implementation translation was clean: 6 TDD steps mapped to 7 commits (one extra `fix:` for biome lint).
-  No steps needed reordering or merging.
-- The `ask_user` design decision gates during planning (persistence strategy, file location) produced clear answers that avoided rework during implementation.
-- Research into nicobailon/pi-subagents, edxeth/pi-subagents, and HazAT/pi-interactive-subagents provided useful reference for the session directory layout, confirming the parent-relative nesting pattern.
-- The biome lint catch on the unused `cwd` parameter led to a better design — incorporating `cwd` into the temp fallback path for project namespacing — rather than a mechanical underscore prefix.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan listed test impact for `agent-runner.test.ts` but didn't grep for other test files mocking `SessionManager` or `ctx.sessionManager`.
-  Three additional files needed updating: `agent-runner-extension-tools.test.ts`, `print-mode.test.ts`, and `test/tools/agent-tool.test.ts`.
-  The testing skill explicitly says "grep for ALL test files that construct a compatible mock — not just factory helpers."
-  Impact: ~5 minutes of reactive fixes during Step 4.
-  Self-identified at implementation time.
-
-- `missing-context` — The plan didn't account for the timing difference between the old synchronous `record.outputFile` assignment (immediately after `spawn()`) and the new asynchronous availability (after `SessionManager.create()` runs inside `runAgent()`).
-  This required adding `session.sessionManager.getSessionFile()` in the `onSessionCreated` callback — a design decision made during implementation.
-  Impact: minor within-step rework, no extra commit needed.
-
-#### What caused friction (user side)
-
-- The dependency update to 0.75.4 was a reasonable pre-plan request, but it added ~10 minutes of tangential work (diagnosing `pnpm update` resolution behavior, normalizing version specifiers).
-  This could have been a separate commit/session, though batching it was pragmatic since it gave the plan access to the latest SDK types.

package/docs/retro/0066-replace-as-any-with-sdk-types.md

@@ -1,44 +0,0 @@
----
-issue: 66
-issue_title: "refactor: replace `as any` casts in extracted tool/menu factories with proper SDK types"
----
-
-# Retro: #66 — replace `as any` casts with proper SDK types
-
-## Final Retrospective (2026-05-20T18:50:00Z)
-
-### Session summary
-
-Replaced all 14 `as any` casts in `src/index.ts` by typing 5 factory dep interfaces with proper SDK types (`ExtensionContext`, `AgentSession`, `ExtensionAPI`, `ModelRegistry`) and the newly-exported `SpawnOptions`.
-Released as `pi-subagents-v5.8.1` with zero behavioral change across 520 tests.
-The plan, implementation, and shipping were completed in a single session with 6 implementation commits.
-
-### Observations
-
-#### What went well
-
-- Thorough context-gathering during planning paid off: reading all 5 dep interfaces, the SDK `.d.ts` files, test mock helpers, and the `ExtensionUIContext` shape before writing the plan meant most steps landed on first `pnpm run check`.
-- The plan's risk table anticipated the cascading `as any` issue on `createAgentTool` and prepared a mitigation ("add explicit `satisfies ToolDefinition<…>` if needed"), which was close to the actual fix needed.
-- Steps 4 and 5 (`GetResultDeps`, `SteerToolDeps`) were trivially clean — single-type-import changes that compiled immediately.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan assumed `NotificationDeps.sendMessage.display` could be optional (`display?: boolean`) but the SDK's `CustomMessage.display` is required `boolean`.
-  First `pnpm run check` after step 2 failed; required one extra edit-verify cycle.
-  Impact: added friction but no rework (fixed in the same commit).
-
-- `missing-context` — The plan did not check the `execute` function's full signature in `agent-tool.ts`.
-  Removing the outer `as any` on `createAgentTool({...})` exposed three additional type mismatches: `onUpdate` parameter type (`unknown` vs `AgentToolResult<any>`), `signal` optionality (`AbortSignal` vs `AbortSignal | undefined`), and `params.description` (`unknown` vs `string`).
-  The plan flagged cascading risk but assumed only the return type would be affected.
-  Impact: step 3 required three extra edits and two extra `pnpm run check` cycles, noted as a deviation in the commit body.
-
-- `missing-context` — Steps 6 and 7 had to be folded into one commit.
-  The plan listed them as independent steps but typing `AgentMenuManager.spawnAndWait(ctx: ExtensionContext)` immediately made `MenuContext` incompatible — `showGenerateWizard` passes `ctx: MenuContext` to the dep callback that now expects `ExtensionContext`.
-  The testing skill already warns: "when a TDD plan lists separate steps that share a type definition, changing that type in step N breaks steps N+1…N+k."
-  The planner failed to recognize that `MenuContext` and `AgentMenuManager.spawnAndWait` share a type dependency through `ctx`.
-  Impact: no rework — the steps were folded successfully — but the plan's step count was inaccurate.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The user ran three sequential prompts (`/plan-issue 66`, `/tdd-plan`, `/ship-issue`) with no corrections or redirects needed.

package/docs/retro/0069-create-subagent-runtime.md

@@ -1,43 +0,0 @@
----
-issue: 69
-issue_title: "refactor: eliminate module-scope mutable state in pi-subagents — create SubagentRuntime"
----
-
-# Retro: #69 — create SubagentRuntime
-
-## Final Retrospective (2026-05-19T16:47:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped `SubagentRuntime` — a composition-root object that replaces module-scope mutable state in `agent-runner.ts` and closure-scoped state in `index.ts`.
-Six TDD steps completed with one deviation: `agent-tool.ts` and `agent-menu.ts` also imported the removed getter/setter exports, requiring unplanned fixes.
-Released as `pi-subagents-v5.2.0`.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift strategy (introduce `RunOptions` fields alongside module-scope fallback, wire consumers, then remove old path) kept the 460-test suite green through every intermediate commit.
-  No step broke existing tests.
-- `pnpm run check` caught the two missing downstream files (`agent-tool.ts`, `agent-menu.ts`) immediately after the removal step.
-  The typecheck-after-removal safety net worked exactly as intended.
-- The `pi-permission-system` prior art (`ExtensionRuntime` in #43) provided a clear structural template, reducing design decisions to near zero.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan's Module-Level Changes listed `agent-runner.ts`, `agent-manager.ts`, and `index.ts` but missed `src/tools/agent-tool.ts` and `src/ui/agent-menu.ts`, both of which imported `getDefaultMaxTurns`/`setDefaultMaxTurns`/`getGraceTurns`/`setGraceTurns` from `agent-runner.ts`.
-  A grep for all importers of the removed symbols during planning would have caught this.
-  Impact: 4 extra files touched in step 5 (the two source files + their test helpers); no rework of earlier steps, but the commit scope was wider than planned. (self-identified at `pnpm run check` time)
-
-- `missing-context` — In step 3 (`agent-manager.test.ts`), checked `vi.mocked(runAgent).mock.calls[0]` without clearing the mock first.
-  The module-level `vi.mock("../src/agent-runner.js")` is shared across all describe blocks, so `calls[0]` picked up a stale invocation from an earlier test.
-  Impact: one debug cycle adding `vi.mocked(runAgent).mockClear()` after `resolvedRun()`. (self-identified)
-
-#### What caused friction (user side)
-
-- Nothing notable.
-  The plan was unambiguous, and the session ran without user intervention beyond the initial prompts.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added grep-importers rule to the Module-Level Changes bullet: when a step removes or renames an export, grep all `src/` and `test/` files for every removed symbol before finalizing the file list.

package/docs/retro/0070-extract-event-handlers.md

@@ -1,49 +0,0 @@
----
-issue: 70
-issue_title: "refactor: extract event handlers from pi-subagents index.ts into src/handlers/"
----
-
-# Retro: #70 — extract event handlers from index.ts
-
-## Final Retrospective (2026-05-20T19:30:00Z)
-
-### Session summary
-
-Planned and implemented #70 — extracting four inline event handler lambdas from `src/index.ts` into `src/handlers/lifecycle.ts` (`SessionLifecycleHandler` class) and `src/handlers/tool-start.ts` (`ToolStartHandler` class).
-During planning, the user identified that the initial plain-function design missed shared collaborators and structural smells, prompting a redesign to class-based handlers and a predecessor issue (#87) to evolve `SubagentRuntime` from a data bag to an object with methods.
-Released as `pi-subagents-v5.8.0` with 8 new handler tests (520 total).
-
-### Observations
-
-#### What went well
-
-- The user's progressive questioning during planning ("Are you confident?", "Keep digging", Kent Beck quote) surfaced two concrete structural smells — output arguments on `runtime.currentCtx` writes and 8 LoD violations via `runtime.widget!` reach-throughs — that the initial design would have just relocated rather than fixed.
-- Filing predecessor #87 was the right sequencing call.
-  By the time #70 executed, the runtime had proper methods and the handler extraction was purely mechanical.
-- The 3-step TDD cycle executed cleanly with zero rework or deviations from the plan.
-  The only issue was a `tsc` type error (`vi.fn()` return type not assignable to `() => void`) caught during the post-TDD type check and fixed in-place before the final commit.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — The initial plan used plain functions with per-call `LifecycleDeps`/`ToolStartDeps` interfaces, the first viable approach, without analyzing whether handlers shared collaborators.
-  The user had to prompt three times before I switched to class-based handlers with constructor-injected shared deps.
-  Impact: three rounds of plan revision before the design was correct; no rework commits, but significant planning churn.
-
-- `instruction-violation` (user-caught) — The `/plan-issue` prompt says "load the `design-review` skill and run its checklist on the affected modules."
-  I loaded the skill but did not actually run the checklist (grep for access patterns, check LoD, check output arguments) until the user explicitly told me to "keep digging."
-  Had I run the checklist proactively, the output-argument and LoD findings would have surfaced on the first pass, and the predecessor issue (#87) would have been identified without user escalation.
-  Impact: user had to escalate three times; planning took ~3× longer than necessary.
-
-- `wrong-abstraction` — I initially reasoned at the mechanical level ("handlers are small, 1–5 lines, so plain functions are fine") instead of the structural level ("do these handlers share collaborators that a class captures naturally?").
-  The code-style skill explicitly says "Do not pass a shared dependency bag to functions that only use a subset" — but I applied it backwards (splitting into per-function deps) rather than recognizing the shared deps as a class cohesion signal.
-  Impact: same as premature-convergence above; folded into the same rework cycle.
-
-#### What caused friction (user side)
-
-- The progressive escalation approach (question → directive → quote) was effective pedagogically but required three turns of user attention on what a proactive design-review checklist run would have caught automatically.
-  Earlier intervention with a specific redirect (e.g., "Run the design-review checklist before writing the plan") could have resolved it in one turn.
-
-### Changes made
-
-1. Retro file created at `packages/pi-subagents/docs/retro/0070-extract-event-handlers.md`.
-2. Updated `packages/pi-subagents/docs/architecture/architecture.md` — marked #87 and #70 as done (✓), updated Phase 2 status to complete, updated next-issue pointer to #66.

package/docs/retro/0071-extract-session-config-assembler.md

@@ -1,60 +0,0 @@
----
-issue: 71
-issue_title: "refactor: extract pure agent-session assembler from agent-runner.ts"
----
-
-# Retro: #71 - extract session-config assembler
-
-## Final Retrospective (2026-05-19T22:15:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped `assembleSessionConfig()` - a pure configuration assembler extracted from `runAgent()` in `agent-runner.ts`.
-Eight TDD steps completed across three phases (plan, implement, ship), adding 33 new tests in `test/session-config.test.ts` and reducing `runAgent()` from ~390 lines to ~198.
-Released as `pi-subagents-v5.3.0`.
-Filed follow-up #80 (consolidate `getConfig`/`getAgentConfig`) and updated the architecture roadmap.
-
-### Observations
-
-#### What went well
-
-- The user's redirecting question ("Do we need more decomposition?
-  Are there any seams we can exploit?") at the `as any` fix point was perfectly timed.
-  It shifted the approach from mechanical casting (8 `as any` casts) to a structural fix: `unknown` for opaque model handles, `Array<{ provider: string; id: string }>` for the availability check.
-  The final design removed the `@earendil-works/pi-ai` import from `session-config.ts` entirely - cleaner than the plan's original specification of `Model<any>`.
-- The prior art from `pi-permission-system` (`evaluate()` extraction) provided a clear template for the pure-core-from-IO-shell pattern.
-  Design decisions were minimal.
-- All 451 existing tests stayed green through every intermediate commit.
-  The mock-at-module-boundary strategy (`vi.mock("../src/agent-types.js")` etc.) meant existing `agent-runner.test.ts` mocks continued to intercept the same module paths even after the assembler delegated to them.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` - When `pnpm run check` surfaced 10 type errors from `Model<any>` in `SessionConfig`, the first fix attempt was adding `as any` casts to the `vi.fn` factory return values and all test model objects (8 casts total).
-  This partially addressed the symptom but created new `never[]` inference errors and left a fundamentally wrong interface.
-  The user's first pushback ("Can we find a real type?") prompted a proper analysis of `Model<TApi>`'s ~10 required fields, leading to the `unknown` solution.
-  Impact: ~20 minutes of rework across 3 attempts (the `as any` factory cast, diagnosing the residual `never[]` errors, and the final `unknown` rewrite). (user-caught)
-
-- `missing-context` - The plan omitted `agentMaxTurns` from the `SessionConfig` return type.
-  `runAgent()`'s turn-limit resolution reads `agentConfig?.maxTurns`, which is no longer available after the assembly delegation.
-  Caught during step 7 (wiring) when the code wouldn't compile without it.
-  Impact: added one field to `SessionConfig` and `assembleSessionConfig`; no rework of earlier steps, but the commit body noted the deviation. (self-identified at implementation time)
-
-- `missing-context` - The `vi.fn(() => [])` → `never[]` TypeScript inference issue wasn't anticipated.
-  Five mock factories (`mockGetMemoryToolNames`, `mockGetReadOnlyMemoryToolNames`, `mockPreloadSkills`, `mockRegistry.find`, `mockRegistry.getAvailable`) needed explicit return-type annotations.
-  Impact: one debug cycle to diagnose, then a second to fix with `import type` annotations. (self-identified during `pnpm run check`)
-
-#### What caused friction (user side)
-
-- The user's second pushback ("Do we need more decomposition?") was the highest-leverage intervention in the session.
-  Without it, the `as any` approach would have landed and the `pi-ai` import would have stayed in `session-config.ts` - defeating the goal of a SDK-free business-logic module.
-  The pattern of catching design-level issues through "is there a better seam?"
-  questions is worth preserving.
-
-#### Design observations (not actionable as rules)
-
-- The `cfg.model as Model<any> | undefined` cast in `agent-runner.ts` is a legitimate interim cost — it's one line at the SDK boundary and will be resolved when #66 (replace `as any` casts with proper SDK types) and #72 (AgentManager DI) refine the interface contracts.
-  Codifying “use `unknown` + boundary cast” as a general pattern would normalize something that should feel uncomfortable and motivate further interface refinement.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — added `vi.fn()` return-type annotation rule under “Vitest mock patterns”: annotate factories that return empty arrays or narrow literals to prevent `never[]` inference.

package/docs/retro/0072-inject-agent-manager-collaborators.md

@@ -1,46 +0,0 @@
----
-issue: 72
-issue_title: "refactor: dependency-inject AgentManager's collaborators"
----
-
-# Retro: #72 — dependency-inject AgentManager's collaborators
-
-## Final Retrospective (2026-05-20T17:50:00Z)
-
-### Session summary
-
-Defined `AgentRunner` and `WorktreeManager` interfaces, converted `AgentManager`'s 6-positional-parameter constructor to an options bag with injected collaborators, migrated all 19 test sites from `vi.mock()` to `vi.fn()` stubs, and added 7 new DI-enabled tests.
-The planning phase required significant user redirection to arrive at the right abstractions; the TDD execution phase was clean with zero rework.
-Released as `pi-subagents-v5.6.0`.
-
-### Observations
-
-#### What went well
-
-- The `ask_user` interactions during planning surfaced genuine design decisions (options bag vs positional constructor, lifecycle callback grouping) that the issue body left open.
-  The user's responses were substantive and redirecting.
-- The user's "make the change that makes the change easy" framing identified #84 (`GitWorktreeManager` extraction) as a prerequisite, which made #72's implementation clean — zero type-shuffling needed.
-- The lift-and-shift test migration (Phase B → Phase C) worked exactly as planned: introduce `createManager()` helper under the old constructor, then switch it to the options bag atomically.
-  All 19 test sites migrated with no logic changes.
-- `Promise.withResolvers` (ES2024) in the new queueing test made controlled async coordination clean — no manual resolve/reject wiring.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — Spent ~4 analysis cycles on "how to move types between files" (`ToolActivity`, `RunOptions`, `WorktreeInfo` → `types.ts`) when the real question was "what objects want to exist?"
-  The user had to redirect three times: "are there real objects with state?", "what state IS in AgentRunner?", and "we haven't pulled all the threads."
-  Impact: added ~10 minutes of back-and-forth during planning, but ultimately produced a better design (stateful `WorktreeManager` vs stateless `AgentRunner` seam, plus #84 as prep).
-  The dependency-graph analysis itself was sound — it confirmed no circular deps — but it answered a question nobody was asking.
-
-- `premature-convergence` — First draft of the plan included `WorktreeManager` extraction as "Phase A step 1" inside #72.
-  The user asked "did we create another issue that we need to tackle first?"
-  — pointing out that the prep work should be its own issue.
-  Impact: minor rework to update the plan and file #84; no code rework since it was caught during planning. (User-caught.)
-
-#### What caused friction (user side)
-
-- The user's early redirect ("take a step back — does the AgentManager really need six params?") could have been even more direct — e.g., "before we discuss constructor shape, what higher-level abstractions are missing?"
-  That said, the Socratic approach ultimately led to a better shared understanding of why `WorktreeManager` is a real object and `AgentRunner` is a seam.
-
-### Changes made
-
-1. Retro file created at `packages/pi-subagents/docs/retro/0072-inject-agent-manager-collaborators.md`.

package/docs/retro/0076-inject-cwd-into-agent-manager.md

@@ -1,35 +0,0 @@
----
-issue: 76
-issue_title: "refactor: inject cwd into AgentManager constructor instead of reading process.cwd() in dispose()"
----
-
-# Retro: #76 — inject cwd into AgentManager constructor
-
-## Final Retrospective (2026-05-19T21:00:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped a single-step refactoring that injects `cwd: string` into the `AgentManager` constructor, replacing the `process.cwd()` call in `dispose()` with `this.cwd`.
-Released as `pi-subagents-v5.4.1`.
-The entire cycle (plan → TDD → ship → release) completed in one session with one minor friction point.
-
-### Observations
-
-#### What went well
-
-- Clean single-commit implementation: one `refactor:` commit touched 3 files, updated 18 test constructor calls plus one production call site, and added one new assertion — all green on first run.
-- TDD Red phase worked well despite the plan calling this a "single-step refactoring."
-  Writing a new test (`"calls pruneWorktrees with the cwd passed to the constructor"`) gave a clear Red signal before the implementation change, even though the constructor signature change had to be applied atomically.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — The plan's "Test Impact Analysis" stated "No new unit tests are needed" and framed existing tests as sufficient.
-  In practice, the existing tests only called `dispose()` in `afterEach` hooks without assertions on `pruneWorktrees` arguments, so a new test was needed for a proper Red phase.
-  The user noticed the discrepancy before TDD began ("We will at least alter some tests, right?").
-  Impact: one clarifying exchange, no rework.
-  User-caught.
-
-#### What caused friction (user side)
-
-- None observed.
-  The user's question about test changes was a useful early catch that would have surfaced during TDD anyway.

package/docs/retro/0077-inject-project-agents-dir.md

@@ -1,33 +0,0 @@
----
-issue: 77
-issue_title: "refactor: add projectAgentsDir to AgentMenuDeps instead of reading process.cwd() inline"
----
-
-# Retro: #77 — inject projectAgentsDir into AgentMenuDeps
-
-## Final Retrospective (2026-05-20T16:15:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped a refactoring that adds `projectAgentsDir: string` to `AgentMenuDeps`, replacing the inline `process.cwd()` lambda in `createAgentsMenuHandler`.
-The change mirrors the existing `personalAgentsDir` injection pattern.
-Released as `pi-subagents-v5.8.2`.
-
-### Observations
-
-#### What went well
-
-- Clean end-to-end execution: plan → TDD → ship with zero corrections or rework.
-- The Red test was well-targeted: exercised `findAgentFile` through the menu navigation path and naturally failed because `process.cwd()` produced a different path than the injected `/test-project/.pi/agents`.
-- Correctly identified at execution time that the plan's two-step TDD split was impractical (interface change is atomic) and combined into a single `refactor:` commit.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` — The plan listed two TDD commits (step 1: `test:`, step 2: `refactor:`) but adding a required field to `AgentMenuDeps` is an atomic change — the test references the new field, so both must land together.
-  The testing skill's shared-type-definition rule ("changing that type in step N breaks steps N+1…N+k — fold them into one step") should have been applied during planning.
-  Impact: added friction but no rework — the deviation was self-identified at execution time and the steps were combined.
-  Self-identified.
-
-#### What caused friction (user side)
-
-- None observed.

package/docs/retro/0080-consolidate-agent-config-lookup.md

@@ -1,35 +0,0 @@
----
-issue: 80
-issue_title: "refactor: consolidate getConfig / getAgentConfig into a single resolution path"
----
-
-# Retro: #80 — consolidate getConfig / getAgentConfig
-
-## Final Retrospective (2026-05-20T00:35:00Z)
-
-### Session summary
-
-Consolidated two overlapping agent config lookup functions (`getConfig` and `getAgentConfig`) into a single `resolveAgentConfig(type): AgentConfig` with a guaranteed-non-null return and internal fallback chain.
-Migrated all 6 source callers and 5 test files across 6 TDD commits, then shipped as `pi-subagents-v5.4.0`.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift migration strategy (add new function → migrate callers incrementally → remove old functions) kept every commit green.
-  No intermediate step broke the test suite.
-- The planning phase correctly identified an under-documented scope question (callers beyond the two mentioned in the issue) and used `ask-user` to resolve it before writing the plan.
-- The `test/prompts.test.ts` caller, missed by the plan, was caught cleanly during the final grep sweep in step 6 — no rework needed, just an additional edit in the same commit.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan specified that `resolveAgentConfig` should fall back for disabled types (matching `getConfig`'s semantics), but didn't trace what `agent-menu.ts` actually reads from disabled configs.
-  `agent-menu.ts` iterates `getAllTypes()` (including disabled agents) and needs the real config to render `✕` indicators, source badges, and `(disabled)` descriptions.
-  With fallback-for-disabled semantics, disabled agents would silently display as general-purpose.
-  Caught during step 4 while editing `agent-menu.ts`, before any wrong test assertions ran.
-  Impact: required changing `resolveAgentConfig` semantics (only fall back for unknown types, not disabled) and updating the step 1 test — a ~5 minute fix folded into the step 4 commit.
-
-#### What caused friction (user side)
-
-- Nothing notable.
-  The user's `ask-user` response during planning ("remove both, migrate all callers") was clear and included a useful directional note about computing values earlier.

package/docs/retro/0084-extract-git-worktree-manager.md

@@ -1,37 +0,0 @@
----
-issue: 84
-issue_title: "refactor: extract GitWorktreeManager class from worktree.ts free functions"
----
-
-# Retro: #84 — extract GitWorktreeManager class from worktree.ts free functions
-
-## Final Retrospective (2026-05-20T13:31:00Z)
-
-### Session summary
-
-Extracted a `WorktreeManager` interface and `GitWorktreeManager` class from the three free functions in `worktree.ts`.
-The two-step TDD cycle (add tests → add implementation) executed cleanly with no rework or deviations from the plan.
-Released as `pi-subagents-v5.5.0`.
-
-### Observations
-
-#### What went well
-
-- The issue body included an exact "Proposed Interface" section with TypeScript code, which made the plan nearly mechanical and eliminated all design ambiguity.
-  The `ask-user` step was correctly skipped.
-- The two-step TDD cycle was appropriately minimal for a thin delegation extraction — no over-engineering of the test or commit structure.
-- The full pipeline (plan → TDD → ship → release) completed in a single pass with zero corrections.
-
-#### What caused friction (agent side)
-
-No friction observed.
-The issue was well-scoped and the existing pipeline instructions handled every step.
-
-#### What caused friction (user side)
-
-No friction observed.
-The pipeline was driven cleanly with `/plan-issue` → `/tdd-plan` → `/ship-issue`.
-
-### Changes made
-
-1. Retro file created at `packages/pi-subagents/docs/retro/0084-extract-git-worktree-manager.md`.

package/docs/retro/0087-evolve-subagent-runtime-methods.md

@@ -1,42 +0,0 @@
----
-issue: 87
-issue_title: "refactor: evolve SubagentRuntime from data bag to object with methods"
----
-
-# Retro: #87 — evolve SubagentRuntime from data bag to object with methods
-
-## Final Retrospective (2026-05-20T18:00:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped #87 — converting `SubagentRuntime` from a plain interface + factory into a class with session-context methods (`setSessionContext`, `clearSessionContext`) and widget delegation methods (`setUICtx`, `onTurnStart`, `markFinished`, `updateWidget`, `ensureTimer`).
-All 10 call sites in `index.ts` were migrated, eliminating raw `currentCtx` field writes and `runtime.widget!` reach-throughs.
-Released as `pi-subagents-v5.7.0`.
-
-### Observations
-
-#### What went well
-
-- The 3-step TDD cycle executed cleanly with zero rework or deviations from the plan.
-  Test count went from 5 → 16 in `runtime.test.ts`; all 512 package tests stayed green throughout.
-- The user identified a missing architecture update and a pre-existing hallucination (`@earendil-works/pi-subagents` → `@gotgenes/pi-subagents`) after the plan commit.
-  The fix was a single well-scoped commit (`ddee1a0`) that corrected 10 scope references, updated the dependency graph to include #87 as a precursor to #70, and fixed list numbering per phase heading.
-- The plan's "Call sites to migrate" tables with exact line numbers and before/after code made step 3 (the refactoring commit) purely mechanical — no design decisions at implementation time.
-
-#### What caused friction (agent side)
-
-- `missing-context` — In TDD step 2, the new `describe` block used `vi.fn()` but the test file's import was `{ describe, expect, it }` without `vi`.
-  The first red run surfaced this immediately (`ReferenceError: vi is not defined`) and it was fixed before the green step.
-  Impact: one extra test run, no rework commits.
-- `scope-drift` — The `/plan-issue` prompt does not instruct updating `architecture.md`, but the user noticed #87 was missing from the roadmap's dependency graph.
-  The agent hadn't checked `architecture.md` during planning even though #87 is explicitly listed as a precursor to #70 in the #70 plan.
-  Impact: user-caught; required a follow-up edit pass after the plan commit.
-
-#### What caused friction (user side)
-
-No friction observed.
-The user's correction about `architecture.md` was well-targeted and caught a real gap.
-
-### Changes made
-
-1. Retro file created at `packages/pi-subagents/docs/retro/0087-evolve-subagent-runtime-methods.md`.