@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/retro/0172-extract-turn-formatting.md

@@ -1,80 +0,0 @@
----
-issue: 172
-issue_title: "refactor(pi-subagents): extract shared turn-formatting logic"
----
-
-# Retro: #172 — Extract shared turn-formatting logic
-
-## Stage: Planning (2026-05-24T18:00:00Z)
-
-### Session summary
-
-Planned the extraction of duplicated turn-formatting logic from `lifecycle/agent-runner.ts` and `ui/message-formatters.ts` into a new shared module `session/content-items.ts`.
-The plan covers extracting `ToolCallContent`, `getToolCallName`, and a new `extractAssistantContent` function, with a 6-step TDD order.
-
-### Observations
-
-- Issue #170 (completed) shifted the duplication target from `conversation-viewer.ts` to `message-formatters.ts` — the issue body's line references are stale but the duplication still exists in the same form.
-- Both dependencies (#164 and #170) are closed, so this is unblocked.
-- The duplication is clearly incidental (same data extraction, different presentation) — safe to extract per the code-design skill's structural-reasons check.
-- `getToolCallName` has no direct unit tests today; the extraction enables testing it for the first time.
-- `getAgentConversation` also has no tests — noted as out of scope but worth a follow-up.
-- Considered adding `extractText` to the new module for consistency but deferred to keep scope tight.
-
-## Stage: Implementation — TDD (2026-05-24T19:05:00Z)
-
-### Session summary
-
-Completed all 6 TDD steps from the plan.
-Created `session/content-items.ts` with `getToolCallName` and `extractAssistantContent`, added 11 unit tests, then refactored both `message-formatters.ts` and `agent-runner.ts` to use the shared module.
-Test count went from 896 to 907 (+11).
-
-### Observations
-
-- Steps 1 and 2 (test-only commits) were folded into step 3's feat commit per the plan's intent — all three land together.
-- The `getToolCallName` parameter type needed widening from `{ type: string }` to `{ type: string; [key: string]: unknown }` to allow test object literals to pass excess-property checking.
-  This in turn required an `as unknown as` double cast at the `agent-runner.ts` call site, because the SDK's `TextContent | ThinkingContent | ToolCall` union lacks an index signature.
-  Same pattern already present in `conversation-viewer.ts`.
-- `message-formatters.ts` had both an import and a re-export of `getToolCallName`; simplified to a pure re-export only.
-- The lint fixup (unused import) was amended into the same refactor commit before pushing.
-- Architecture doc updated: `content-items.ts` added to session module listing, production-duplication section updated, Step 9 marked Done.
-
-## Stage: Final Retrospective (2026-05-24T20:30:00Z)
-
-### Session summary
-
-Planned, implemented, and shipped the extraction of shared turn-formatting logic from `lifecycle/agent-runner.ts` and `ui/message-formatters.ts` into `session/content-items.ts`.
-Released as `pi-subagents-v6.19.0`.
-During code review the user challenged double-casts in the initial implementation, which led to discovering that the local `ToolCallContent` type was dead code and the SDK exports the real `ToolCall` type — the final implementation is significantly cleaner than what the plan specified.
-Filed #188 for broader `any`-to-SDK-type cleanup discovered during the investigation.
-
-### Observations
-
-#### What went well
-
-- The user's Socratic challenge ("Talk to me about these double-casts") was the pivotal moment.
-  Rather than directing a fix, it prompted an investigation of the SDK's actual `ToolCall` type, which revealed that `ToolCall.name` is always required and `toolName` never appears on content items.
-  This eliminated the `ToolCallContent` interface, the `toolName` fallback, the index-signature parameter type, and all double-casts — none of which the plan anticipated.
-- Cross-session retro context worked well: the planning-stage note about #170 shifting the duplication target saved time during TDD.
-- The SDK source investigation yielded a follow-up issue (#188) for replacing `any` casts in `extractText` and `SubscribableSession` with proper SDK types.
-
-#### What caused friction (agent side)
-
-- `missing-context` — Did not check SDK type exports during planning.
-  The plan copied `ToolCallContent` verbatim from the existing code without verifying what `@earendil-works/pi-ai` exports.
-  The source comments ("SDK doesn't export the narrow type") were wrong — the types have been exported for some time.
-  Impact: the initial TDD implementation introduced a `{ type: string; [key: string]: unknown }` parameter type that forced `as unknown as` double-casts, requiring a full rework after user review.
-- `premature-convergence` — When TypeScript rejected excess properties in test object literals, I widened the parameter type to include an index signature instead of exploring alternatives.
-  The correct fix (using `ReadonlyArray<{ type: string }>` with `in` narrowing, or importing SDK types as test fixtures) was simpler and avoided the cast cascade.
-  Impact: one round of rework plus an amended commit that muddied the git history.
-
-#### What caused friction (user side)
-
-- The user's intervention at the cast review stage was well-timed and effective.
-  One earlier opportunity: if the user had flagged the `toolName` fallback or the SDK-type question during the plan review (before TDD started), the initial implementation would have been correct from the start.
-  However, this is a marginal improvement — the plan review was clean and the friction was minor.
-
-### Changes made
-
-1. `.pi/skills/code-design/SKILL.md` — Added two rules to "Pi SDK boundaries": verify SDK exports before redeclaring types locally; prefer minimal structural supertypes over index-signature types for parameters accepting SDK content.
-2. `.pi/skills/testing/SKILL.md` — Added TDD planning rule: verify SDK exports when extracting locally-declared types that shadow SDK types.

package/docs/retro/0180-reorder-append-prompt-for-kv-cache.md

@@ -1,62 +0,0 @@
----
-issue: 180
-issue_title: "perf(pi-subagents): reorder append-mode system prompt to enable KV cache reuse"
----
-
-# Retro: #180 — Reorder append-mode system prompt for KV cache reuse
-
-## Stage: Planning (2026-05-24T20:00:00Z)
-
-### Session summary
-
-Produced a plan to reorder the append-mode system prompt in `buildAgentPrompt()` so the shared inherited content (~8k tokens) comes before the varying `<active_agent>` tag and env block, enabling LLM KV cache prefix reuse across subagent invocations.
-
-### Observations
-
-- Confirmed pi-permission-system's `ACTIVE_AGENT_TAG_REGEX.exec()` is position-independent — no changes needed in that package despite the `pkg:pi-permission-system` label on the issue.
-- Only two tests assert positional ordering in append mode (`startsWith` and `tagIdx === 0`); all other prompt tests use `toContain()` and are unaffected.
-- Replace mode is a separate code path and is not touched.
-- The TDD cycle is minimal: one red step (update two positional assertions), one green step (reorder the return statement + update JSDoc).
-
-## Stage: Implementation — TDD (2026-05-24T20:15:00Z)
-
-### Session summary
-
-Completed both TDD cycles in `buildAgentPrompt()` in `src/session/prompts.ts`.
-Two positional assertions in `test/session/prompts.test.ts` were updated to expect the new ordering (red), then the append-mode return statement was reordered and the JSDoc updated (green).
-Test count unchanged at 805 across 50 files.
-
-### Observations
-
-- The JSDoc bullet for append mode also described the old ordering ("env header + parent system prompt + ...") and was corrected as part of the green step.
-- The `<active_agent>` tag is followed by a `\n\n`, so when it moves after `<sub_agent_context>`, a `\n\n` separator between the bridge and the tag was needed to maintain clean section boundaries.
-- No deviations from the plan; both steps were exactly as described.
-
-## Stage: Final Retrospective (2026-05-24T21:00:00Z)
-
-### Session summary
-
-Issue #180 went from external community observation through release (`pi-subagents-v6.18.3`) in a single continuous session.
-The plan predicted exactly two TDD steps; both executed without deviation or rework.
-
-### Observations
-
-#### What went well
-
-- End-to-end lifecycle in one session: external comment → issue → plan → TDD → ship → release.
-  No corrections, no scope drift, no rework across any stage.
-- The plan's test impact analysis was accurate — only two positional assertions needed updating; all `toContain()` tests passed untouched.
-- Confirming pi-permission-system's `ACTIVE_AGENT_TAG_REGEX.exec()` is position-independent during planning eliminated the second `pkg:*` label's scope entirely, keeping the change to a single file.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — Launched an Explore agent (75.9s, 18 tool uses) to map the prompt assembly flow when the `package-pi-subagents` skill already listed the file layout and `prompts.ts` is 107 lines.
-  Direct `read` + `grep` achieved the same confirmation in ~3 seconds during the planning phase.
-  Impact: added ~75 seconds of latency but no rework.
-- `missing-context` — The plan listed "Update the JSDoc comment" but missed that the mode-description bullet ("env header + parent system prompt + ...") also encoded the old ordering.
-  Caught during the green step and fixed in the same commit.
-  Impact: added friction but no rework.
-
-#### What caused friction (user side)
-
-- Nothing notable — the user's prompts were well-scoped and the issue description was unambiguous.

package/docs/retro/0185-remove-persistent-agent-memory.md

@@ -1,73 +0,0 @@
----
-issue: 185
-issue_title: "pi-subagents: Remove persistent agent memory feature"
----
-
-# Retro: #185 — pi-subagents: Remove persistent agent memory feature
-
-## Stage: Planning (2026-05-24T20:46:56Z)
-
-### Session summary
-
-Traced all memory-related code across 9 source files, 5 test files, and the architecture doc.
-Produced a 5-step TDD plan: extract shared utilities (`isSymlink`, `isUnsafeName`, `safeReadFile`) to `safe-fs.ts`, then remove memory consumers (session assembly, config, UI), then delete the module, then update docs.
-
-### Observations
-
-- The three utility functions in `memory.ts` are the only complication — `skill-loader.ts` imports them independently of memory.
-  Extracting to `src/session/safe-fs.ts` keeps them co-located with their sole remaining consumer.
-- The removal is consumers-first, declaration-last: session-config and prompts lose their memory logic before `MemoryScope` is removed from `types.ts`, avoiding intermediate type errors.
-- No ambiguous design choices — the issue scope section is precise about what to remove and what to extract.
-- Memory field in custom agent frontmatter will silently become a no-op (ignored by the YAML parser) — no user-facing error, just loss of the feature.
-- The `AssemblerIO` interface shrinks from 4 fields to 2 after removal, which is a welcome simplification.
-
-## Stage: Implementation — TDD (2026-05-24T22:41:23Z)
-
-### Session summary
-
-All 5 TDD steps completed across 5 commits.
-Test count went from 901 (54 files) to 848 (53 files) — a net reduction of 53 tests and 1 file, reflecting the deletion of the `memory.test.ts` file with its memory-specific tests and the removal of memory-related tests from `session-config.test.ts`, `prompts.test.ts`, `agent-types.test.ts`, and `custom-agents.test.ts`.
-New file `safe-fs.test.ts` was created with 13 tests for the extracted utilities.
-
-### Observations
-
-- Step 1 had a subtle bug: after re-exporting `isUnsafeName` from `safe-fs` in `memory.ts`, the function was not imported into the `memory.ts` module scope itself, so `resolveMemoryDir` got a `ReferenceError` at runtime.
-  Fix was trivial: add `isUnsafeName` to the import alongside `isSymlink` and `safeReadFile`.
-- Step 3 introduced a type error in `memory.ts` (still alive at that point): `MemoryScope` was imported from `#src/types` which no longer exported it.
-  Fix: inline the literal union `"user" | "project" | "local"` directly in `memory.ts` as a local type, so it compiles cleanly until deletion in step 4.
-- The `SKILL.md` for `package-pi-subagents` also listed `memory.ts` in the session domain table — updated alongside `architecture.md` in the docs commit.
-- No deviations from the plan other than the two minor bugs above (both self-corrected within the same TDD step).
-
-## Stage: Final Retrospective (2026-05-24T22:47:55Z)
-
-### Session summary
-
-Shipped issue #185 as `pi-subagents-v7.0.0`.
-CI passed, issue closed, release-please PR #190 merged.
-Three sessions total: planning, TDD (5 steps / 5 commits), shipping.
-
-### Observations
-
-#### What went well
-
-- The issue's "Scope" section was precise enough that the planning session required no `ask_user` and the Explore agent's trace matched the final commit diff exactly.
-- Consumers-first, declaration-last ordering kept each commit independently compilable (after the two self-corrected fixes).
-- The `SKILL.md` domain table update was caught naturally during the docs step even though the plan didn't list it.
-
-#### What caused friction (agent side)
-
-- `missing-context` — In TDD step 1, `memory.ts` was updated to re-export `isUnsafeName` from `safe-fs`, but the function was not imported into `memory.ts`'s own scope.
-  `resolveMemoryDir` threw a `ReferenceError` at runtime.
-  Impact: one extra test-run cycle (~5 seconds) and a trivial one-line fix; no rework commit.
-- `missing-context` — In TDD step 3, removing `MemoryScope` from `types.ts` broke `memory.ts` (scheduled for deletion in step 4).
-  The plan said "consumers-first" but didn't account for the doomed module itself being a consumer of the type.
-  Impact: one extra `pnpm run check` cycle and a local type inline; no rework commit.
-  Both share the same root cause: incremental deletion plans must account for doomed files' own imports at each intermediate step.
-
-#### What caused friction (user side)
-
-- None observed — all three sessions ran without user corrections or redirections.
-
-### Changes made
-
-1. Added a TDD planning rule to `.pi/skills/testing/SKILL.md` about accounting for doomed modules' own imports during multi-step deletion.

package/docs/retro/0188-replace-any-casts-with-sdk-types.md

@@ -1,69 +0,0 @@
----
-issue: 188
-issue_title: "refactor(pi-subagents): replace any casts with SDK types in extractText and SubscribableSession"
----
-
-# Retro: #188 — Replace any casts with SDK types
-
-## Stage: Planning (2026-05-24T20:04:58Z)
-
-### Session summary
-
-Produced a two-step refactoring plan for replacing `any` casts in `extractText` (with a `TextContent` type predicate) and `SubscribableSession` (with `AgentSessionEvent`).
-Verified that both SDK types are already imported and used in adjacent files within the package.
-Confirmed mock session compatibility via function parameter contravariance — no test changes expected.
-
-### Observations
-
-- The `extractText` parameter type stays `unknown[]` to avoid rippling through callers in `message-formatters.ts` that declare `content: unknown[]`.
-  A future cleanup could tighten those caller signatures.
-- `SubscribableSession` moves to `src/types.ts` as the shared location, matching existing cross-domain types there (`SubagentType`, `ThinkingLevel`, `ShellExec`).
-- All three `eslint-disable` top-level comments (`context.ts`, `record-observer.ts`, `ui-observer.ts`) should be removable once the `any` casts are gone, since the SDK union's discriminated members cover the property access patterns.
-- Risk: if `AgentSessionEvent` doesn't cover `assistantMessageEvent` in `ui-observer.ts`, the type checker will surface it immediately — the mitigation is to check the union members during implementation.
-
-## Stage: Implementation — TDD (2026-05-24T20:17:38Z)
-
-### Session summary
-
-Completed both TDD steps from the plan.
-Step 1 replaced the `any` filter/map chain in `extractText` with an `isTextContent` type predicate; the `??""` removal was required because `TextContent.text` is non-optional per the SDK type.
-Step 2 moved `SubscribableSession` to `types.ts` typed with `AgentSessionEvent`, removed both duplicate local interfaces, and removed all three `eslint-disable` comments.
-Test count: 902 → 901 (one test removed).
-
-### Observations
-
-- The `??` operator on `c.text` in `extractText` triggered `@typescript-eslint/no-unnecessary-condition` at commit time because `TextContent.text` is `string` (non-nullable); removing it was necessary, not just cosmetic.
-- After typing the `record-observer` callback as `AgentSessionEvent`, five additional lint errors surfaced: `event.message?.role` (optional chain unnecessary since `MessageEndEvent.message` is required), `if (u)` guard (unnecessary since `AssistantMessage.usage` is required), and three `?? 0` guards on `input`/`output`/`cacheWrite` (all required `number` fields per `Usage` interface in the Pi source at `~/development/pi/pi/packages/ai/src/types.ts`).
-- The test `"ignores message_end without usage"` was removed — it emitted a non-conforming event that the SDK types guarantee cannot occur at runtime.
-- `ui-observer.ts` had one analogous fix: `event.assistantMessageEvent?.type` → `.type` (the field is required on `MessageUpdateEvent`).
-- No test file changes were needed for `ui-observer.ts` — its existing tests all emit conforming events.
-- The plan's contravariance reasoning about mock session compatibility was correct: `pnpm run check` passed without updating `MockSession.subscribe`.
-
-## Stage: Final Retrospective (2026-05-24T20:41:42Z)
-
-### Session summary
-
-Clean two-step refactoring shipped as `pi-subagents-v6.19.1`.
-Both TDD steps completed in a single session with two minor deviations from the plan, both caught by pre-commit hooks.
-Test count: 902 → 901 (one non-conforming test removed).
-
-### Observations
-
-#### What went well
-
-- The plan's contravariance analysis of `MockSession.subscribe` vs `SubscribableSession` was correct — zero test infrastructure changes needed.
-- Pre-commit hooks (ESLint) caught both deviations from the plan at commit time, before they could reach CI.
-- The user providing the Pi source path (`~/development/pi/pi`) unblocked verification of `AssistantMessage.usage` field requirements without guesswork.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan's Risk 3 said "keep `?? ""` for safety" on `TextContent.text`, but `@typescript-eslint/no-unnecessary-condition` rejected it at commit time because `TextContent.text: string` is non-optional.
-  Impact: one failed commit attempt, immediate fix (changed `.map((c) => c.text ?? "")` to `.map((c) => c.text)`).
-- `missing-context` — The plan's step 2 didn't anticipate the five additional lint errors surfaced by properly typing the `record-observer` callback: unnecessary optional chain on `event.message?.role`, unnecessary `if (u)` guard, and three unnecessary `?? 0` guards on usage fields.
-  Impact: added ~5 minutes of investigation to verify the SDK types were truly non-optional before removing guards; required removing one test case (`"ignores message_end without usage"`).
-  Both instances stem from the same root cause: the plan checked that the SDK types *existed* but didn't trace the *field optionality* of types downstream of `AgentSessionEvent` (specifically `AgentMessage.usage` and `Usage.{input,output,cacheWrite}`).
-
-#### What caused friction (user side)
-
-- The Pi source path (`~/development/pi/pi`) was provided reactively after I'd already spent several tool calls trying to locate `AgentMessage` type definitions in `node_modules`.
-  Sharing this path earlier (or noting it in the package skill) would have saved ~4 `grep`/`find` calls.

package/docs/retro/0192-define-session-context-interface.md

@@ -1,59 +0,0 @@
----
-issue: 192
-issue_title: "Define SessionContext narrow interface"
----
-
-# Retro: #192 — Define SessionContext narrow interface
-
-## Stage: Planning (2026-05-24T16:00:00Z)
-
-### Session summary
-
-Planned the pure-additive `SessionContext` interface for `src/types.ts`.
-Traced all 5 consumed fields against the SDK's `ExtensionContext` type declarations to confirm shape alignment.
-Single TDD step: add the interface and verify with `pnpm run check`.
-
-### Observations
-
-- The interface is trivial in scope — one new export with no consumers changing.
-  This is intentionally the smallest possible first step to unblock Layer 1 (#193).
-- `ModelRegistry` already exists as a local narrow interface in `src/session/model-resolver.ts`; `SessionContext` imports it rather than redeclaring.
-- `sessionManager` uses an inline structural type (3 methods) rather than importing the SDK's `ReadonlySessionManager` (13 methods) — ISP applies here.
-- No design ambiguity required `ask_user`; the issue's proposed change section was fully specified.
-
-## Stage: Implementation — TDD (2026-05-24T19:55:00Z)
-
-### Session summary
-
-Added the `SessionContext` interface to `src/types.ts` with an `import type { ModelRegistry }` from `#src/session/model-resolver`.
-Single compile-time step — no runtime tests needed for a pure type definition.
-Baseline: 53 test files, 848 tests; final: unchanged.
-
-### Observations
-
-- Pre-existing lint failure in `docs/architecture/architecture.md` (5 unused MD053 link references for issues #164, #165, #170, #171, #172) was fixed as part of the baseline verification and included in the feat commit.
-- The interface landed exactly as planned — no deviations from the plan's Design Overview.
-
-## Stage: Final Retrospective (2026-05-24T20:00:00Z)
-
-### Session summary
-
-All three stages (plan, TDD, ship) completed in a single session.
-Released as `pi-subagents-v7.1.0`.
-No rework, no deviations from plan.
-
-### Observations
-
-#### What went well
-
-- The issue was fully specified — no ambiguity, no `ask_user` needed at any stage.
-- Trivial scope (one interface, no consumers) made the plan-to-ship pipeline fast and mechanical.
-- Pre-existing lint failures in `architecture.md` were caught during baseline verification and fixed without disrupting the flow.
-
-#### What caused friction (agent side)
-
-- None — clean execution with no rework or corrections.
-
-#### What caused friction (user side)
-
-- None — no intervention needed beyond invoking the three workflow commands.

package/docs/retro/0193-runtime-owns-context-queries.md

@@ -1,75 +0,0 @@
----
-issue: 193
-issue_title: "SubagentRuntime owns context queries"
----
-
-# Retro: #193 — SubagentRuntime owns context queries
-
-## Stage: Planning (2026-05-24T21:00:00Z)
-
-### Session summary
-
-Planned the Layer 1 change that types `SubagentRuntime.currentCtx` as `SessionContext`, adds three query methods (`buildSnapshot`, `getModelInfo`, `getSessionInfo`), and eliminates 4 `as any` casts from `index.ts`.
-The plan covers 7 TDD steps touching `runtime.ts`, `handlers/lifecycle.ts`, `parent-snapshot.ts`, `context.ts`, `service-adapter.ts`, and `index.ts`.
-
-### Observations
-
-- The `pi` field in `currentCtx` is never read back — only stored.
-  Dropping it is safe; `SessionLifecycleHandler` already holds `pi` as a constructor param.
-- `ExtensionContext` structurally satisfies `SessionContext`, so changing `buildParentSnapshot`'s param type is source-compatible with the `/agents` command handler that passes raw SDK `ctx`.
-- `service-adapter.ts` gets the biggest structural change: its two closure params (`getCtx`, `getModelRegistry`) collapse into a single `ServiceRuntimeLike` interface.
-- No design ambiguity — the architecture doc's Layer 1 spec and the issue body are fully aligned.
-- Test fixtures in `make-deps.ts` are unaffected because the `AgentToolDeps` interface shape doesn't change — only the wiring in `index.ts` that supplies the implementations changes.
-
-## Stage: Implementation — TDD (2026-05-24T20:30:00Z)
-
-### Session summary
-
-Completed all 6 implementation TDD steps plus an architecture doc update in one session.
-The `getSessionInfo` implementation needed `?.sessionManager.getSessionFile()` (not `?.sessionManager?.getSessionFile()`) since `sessionManager` is a required field of `SessionContext` — ESLint's `no-unnecessary-condition` caught this at the pre-commit hook.
-Final test count: 854 (up from 848 baseline, +6 new tests for `buildSnapshot`, `getModelInfo`, `getSessionInfo`).
-
-### Observations
-
-- The plan's Non-Goals section incorrectly said `buildParentContext` would NOT change.
-In practice it had to accept `SessionContext` instead of `ExtensionContext` — they are not substitutable in that direction.
-The Module-Level Changes list was correct; only the Non-Goals prose was wrong.
-- `context.ts` needed a local `BranchEntry` union type to handle `getBranch(): unknown[]`.
-TypeScript's discriminated union narrowing doesn't work when the union includes a catch-all `{ type: string }` arm — explicit casts within each `if` branch were required.
-- `service-adapter.ts` ended up using `runtime.currentCtx.modelRegistry` directly (no `getModelInfo()` call needed in the service adapter) — `ServiceRuntimeLike` only needs `currentCtx` and `buildSnapshot`.
-This is cleaner than the plan's `getModelInfo(): { modelRegistry: unknown }` approach.
-- Biome's `noUnusedPrivateClassMembers` warning caught the leftover `private readonly pi: unknown` in `SessionLifecycleHandler`.
-Removed `pi` from the constructor entirely (rather than adding `_` prefix), which also cleaned up `index.ts`.
-- The `eslint-disable` directive at the top of `index.ts` had two now-unused entries (`no-unsafe-member-access`, `no-unsafe-call`) removed by `eslint --fix`.
-
-## Stage: Final Retrospective (2026-05-24T20:45:00Z)
-
-### Session summary
-
-All three stages (plan, TDD, ship) completed in a single session.
-Released as `pi-subagents-v7.2.0`.
-One plan contradiction required a judgment call during implementation; otherwise clean mechanical execution.
-
-### Observations
-
-#### What went well
-
-- The architecture doc's Phase 11 Layer 1 spec was precise enough that no `ask_user` was needed at any stage — the issue body, architecture doc, and #192 retro were fully aligned.
-- `ServiceRuntimeLike` ended up simpler than planned (only `currentCtx` + `buildSnapshot` instead of also requiring `getModelInfo()`) — the implementation found a cleaner design than the plan specified.
-- Test count increase (+6) validates the design: methods that were previously untestable as anonymous closures now have dedicated unit tests.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan's Non-Goals section claimed `buildParentContext` would not change, contradicting Module-Level Changes item #4 which explicitly listed the file.
-  The planning stage didn't cross-check these sections before committing.
-  Impact: brief confusion during step 3 about which section to trust (resolved by following Module-Level Changes); no rework, added ~30s of deliberation.
-- `missing-context` — TypeScript's discriminated union narrowing limitation with a `{ type: string }` catch-all arm was not anticipated.
-  Impact: required adding a local `BranchEntry` union type and explicit casts in `context.ts`; no rework but ~2 min of debugging the type error.
-
-#### What caused friction (user side)
-
-- None — no user intervention was needed at any point across all three stages.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added a Non-Goals vs Module-Level Changes cross-check instruction under the Module-Level Changes bullet.

package/docs/retro/0194-align-tool-interfaces-for-structural-typing.md

@@ -1,62 +0,0 @@
----
-issue: 194
-issue_title: "Align tool interfaces for structural typing"
----
-
-# Retro: #194 — Align tool interfaces for structural typing
-
-## Stage: Planning (2026-05-24T12:00:00Z)
-
-### Session summary
-
-Produced an implementation plan for three targeted alignment changes: moving `getMaxConcurrent` off manager interfaces to the settings accessor, renaming `SubagentRuntime.updateWidget()` → `update()`, and removing the dead `getToolCallName` re-export.
-The plan includes a 4-step TDD order with type-check gates after each refactoring step.
-
-### Observations
-
-- Issue #193 (Layer 1) is already closed/implemented, confirming this layer can proceed immediately.
-
-## Stage: Implementation — TDD (2026-05-24T21:00:00Z)
-
-### Session summary
-
-Completed all 4 TDD steps: renamed `SubagentRuntime.updateWidget()` → `update()`, moved `getMaxConcurrent` from manager interfaces to the `settings` narrow type, removed the dead `getToolCallName` re-export, and updated the architecture doc.
-Test count stayed flat at 854 (53 files) — all green.
-The `pnpm run check` type-gate caught a previously-unnoticed `test/helpers/make-deps.test.ts` that also validated `getMaxConcurrent` and the old `settings` shape; this file was updated as part of step 2.
-
-### Observations
-
-- An unexpected file `test/helpers/make-deps.test.ts` had three type errors after removing `getMaxConcurrent` (one test asserting `manager.getMaxConcurrent()`, one structural compatibility check referencing it, and one settings override that only passed `defaultMaxTurns`).
-  All three were fixed in the same commit as step 2 — no deviation from the plan.
-- Adding `settings` to `BackgroundParams` (instead of as a 5th function parameter) was the right call: it keeps `spawnBackground` at 4 arguments and groups all spawn-context values together.
-- The health metric update: dead exports 1 → 0, adapter closures 41 → 40 (only `getMaxConcurrent` was removed in this layer; the remaining 8 widget/manager adapter closures need #195 class conversion to collapse).
-- The `background-spawner.ts` module is the only consumer of `getMaxConcurrent` — grep confirms no other call sites beyond `agent-tool.ts`'s interface definition.
-- The `NotificationManager` constructor takes `updateWidget` as a positional callback parameter name — this does NOT need renaming (it's not a structural interface member).
-- The rename from `updateWidget` → `update` is safe because the `WidgetLike` interface in `runtime.ts` already uses `update()` — no naming conflict within the class.
-- All three changes are independent of each other and could be committed in any order, but the plan sequences them for clean `pnpm run check` passes at each step.
-
-## Stage: Final Retrospective (2026-05-24T21:15:00Z)
-
-### Session summary
-
-Planning, TDD implementation, and shipping completed in one continuous session.
-Released as `pi-subagents-v7.2.1` with zero rework or deviations from the plan.
-
-### Observations
-
-#### What went well
-
-- Clean execution end-to-end: 3 refactor commits + 1 docs commit, all planned in advance.
-- The `pnpm run check` gate after step 2 caught `test/helpers/make-deps.test.ts` — a file the plan didn't list — preventing a broken intermediate state.
-  This validates the "run type-check after each step" pattern for interface-alignment work.
-- Phased architecture approach paid off: Layers 0 and 1 being done made Layer 2 entirely mechanical.
-
-#### What caused friction (agent side)
-
-- None identified.
-  The issue scope was tight, the plan was unambiguous, and no rabbit-holes arose.
-
-#### What caused friction (user side)
-
-- None identified.
-  The issue body and architecture doc provided complete context with no ambiguity.

package/docs/retro/0195-convert-tool-factories-to-classes.md

@@ -1,84 +0,0 @@
----
-issue: 195
-issue_title: "Convert tool factories to classes"
----
-
-# Retro: #195 — Convert tool factories to classes
-
-## Stage: Planning (2026-05-24T12:00:00Z)
-
-### Session summary
-
-Produced a 5-step TDD plan converting `createAgentTool`, `createGetResultTool`, and `createSteerTool` to classes with constructor-injected dependencies.
-Verified both prerequisites (#193, #194) are closed and their effects visible in the current source.
-Designed narrow interfaces (`AgentToolRuntime`, `GetResultToolManager`, `SteerToolManager`, `SteerToolEvents`, etc.) that `SubagentRuntime`, `AgentManager`, and `NotificationManager` satisfy structurally.
-
-### Observations
-
-- The conversion is mechanical — no behavioral changes, just structural.
-  Existing tests cover all paths; only test helpers need updating.
-- `steerAgent` and `getAgentConversation` are pure functions that can be imported directly by the classes rather than injected — simplifies the constructor signature.
-- `agentDir` doesn't fit neatly on any existing collaborator, so it remains a constructor param for `AgentTool`.
-- The `AgentToolWidget` interface may become redundant once `AgentToolRuntime` replaces it as the type passed to `spawnBackground`/`runForeground`, but this is deferred to implementation.
-- Ordered TDD steps from smallest (SteerTool) to largest (AgentTool) to build confidence incrementally.
-
-## Stage: Implementation — TDD (2026-05-24T21:26:00Z)
-
-### Session summary
-
-Completed all 5 planned TDD cycles (SteerTool → GetResultTool → AgentTool → `index.ts` wiring → architecture doc).
-All 854 tests pass; type check and lint clean.
-Total: 5 commits across source + test files, plus 1 cleanup fix commit.
-
-### Observations
-
-- `steerAgent` was inlined as `session.steer(message)` directly in `SteerTool.execute()` rather than imported as a module function.
-  This eliminated the dep entirely — the mock session's `steer` vi.fn() handles it in tests without `vi.mock`.
-- The `verbose` test in `get-result-tool.test.ts` was upgraded to drive the real `getAgentConversation` function via `createMockSession({ messages: [...] })` overrides, making it a stronger integration test.
-- `AgentToolWidget` was eliminated: `AgentToolRuntime` (a superset) replaced it, and `background-spawner` and `foreground-runner` already define their own narrow `BackgroundWidgetDeps`/`ForegroundWidgetDeps` interfaces.
-- `createToolDeps()` changed shape from `AgentToolDeps` bag to `AgentToolFixture` (`{ manager, runtime, settings, registry, agentDir }`).
-  This required updating `background-spawner.test.ts` and `foreground-runner.test.ts` (not listed in the plan) to destructure `{ manager, runtime }` instead of `{ manager, widget, agentActivity }`.
-- Biome flagged an unused `import type { AgentSession }` in `get-result-tool.ts` (left by ESLint's cast removal in step 2) — caught by `pnpm run lint` and fixed in a separate commit.
-- The `ReturnType<typeof vi.fn>` annotation on `makeNotifications()` in the get-result-tool test triggered a TypeScript error; fixed by removing the return type annotation entirely (per testing skill guidance).
-
-## Stage: Final Retrospective (2026-05-25T14:06:00Z)
-
-### Session summary
-
-Shipped #195 (three tool factory-to-class conversions), then discovered and fixed a process gap: the fallow dead-code gate was advisory (`continue-on-error: true`) and the `/tdd-plan` and `/ship-issue` prompts didn't run `pnpm fallow dead-code` at all.
-Resulting follow-up work promoted all dead-code rule categories to `error` severity, split the CI fallow step into a hard gate plus advisory full report, and removed the genuinely dead `steerAgent` export and unused `@eslint/js` devDependency.
-
-### Observations
-
-#### What went well
-
-- The user reading CI output carefully and asking "why did fallow check fail yet we proceeded to release?"
-  surfaced a real process gap that would have silently accumulated dead code over time.
-- Incremental severity promotion was effective: checking each category's violation count before promoting let us ratchet from 3 error-level rules to 9 in three commits with zero cleanup work (all categories were already clean except the `steerAgent` export we'd just created).
-
-#### What caused friction (agent side)
-
-- `missing-context` — During the TDD session, I didn't run `pnpm fallow dead-code` after removing all callers of `steerAgent`, so the dead export shipped.
-  The existing `/tdd-plan` prompt's "after last step" checks didn't include fallow.
-  Impact: dead code shipped to a release, required a follow-up fix commit and re-release (`v7.2.2` → `v7.2.3`).
-- `missing-context` — Used `// fallow-ignore-next-line unused-class-member -- reason text` but fallow parses every space-separated token after the rule name as additional rule names.
-  The existing codebase uses bare comments with no trailing text.
-  Impact: 12 stale-suppression warnings until the comment was fixed; no rework but added noise.
-- `missing-context` — During planning, the Module-Level Changes section didn't list `background-spawner.test.ts` or `foreground-runner.test.ts`, even though both destructure `{ widget, agentActivity }` from `createToolDeps()`.
-  The testing skill already has guidance ("grep for ALL test files that construct a compatible mock") but I didn't apply it during planning.
-  Impact: caught immediately by running the full test suite; added friction but no rework.
-
-#### What caused friction (user side)
-
-- The fallow dead-code gap could have been caught earlier if the CI workflow had been configured to block on fallow findings from the start.
-  The `continue-on-error: true` was a reasonable initial setting during adoption but had outlived its usefulness.
-
-### Follow-up ideas
-
-- **Pre-completion reviewer subagent** — a `.pi/agents/pre-completion-reviewer.md` dispatched before `/ship-issue` that runs deterministic checks (`pnpm fallow dead-code`, `pnpm run check`, `pnpm run lint`, `pnpm vitest run`) and judgment checks (conventional commits, architecture doc staleness) in a fresh read-only context.
-  Modeled after RepOne's `pre-completion-reviewer` but scoped to this monorepo's needs.
-  This would be a separate issue.
-
-### Changes made
-
-1. `.pi/prompts/tdd-plan.md` — added `pnpm fallow dead-code` as step 4 in "After the last TDD step" (renumbered steps 4–7 → 5–8).

package/docs/retro/0196-convert-runner-menu-to-classes.md

@@ -1,73 +0,0 @@
----
-issue: 196
-issue_title: "Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts"
----
-
-# Retro: #196 — Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts
-
-## Stage: Planning (2026-05-25T14:35:46Z)
-
-### Session summary
-
-Produced a 6-step TDD plan covering the final two closure-factory-to-class conversions (`createAgentRunner` → `ConcreteAgentRunner`, `createAgentsMenuHandler` → `AgentsMenuHandler`) and the subsequent `index.ts` simplification.
-Confirmed that `AgentManager` structurally satisfies `AgentMenuManager`, enabling direct pass-through without adapter closures.
-
-### Observations
-
-- The issue's proposed `AgentsMenuHandler` constructor omits `agentActivity`, but the class needs it for `viewAgentConversation`.
-  Plan includes it as a constructor param — minimal deviation from the issue.
-- `getModelLabel` can be internalized into `AgentsMenuHandler` since it only uses two pure imported functions (`resolveModel`, `getModelLabelFromConfig`) plus the registry (already a constructor param).
-  This eliminates a 7-line closure from `index.ts`.
-- Tests for `agent-runner` call `runAgent`/`resumeAgent` directly — no test uses `createAgentRunner`, so the runner conversion has zero test impact.
-- The `agent-menu.test.ts` file is 215 lines and needs call-site updates (factory → class constructor + `.handle()`), but no logic changes.
-- After both conversions, `index.ts` loses ~5 imports and ~4 adapter closures.
-  The remaining ~15 closures are structural (event registrations, SDK factory callbacks) and cannot be eliminated.
-
-## Stage: Implementation — TDD (2026-05-25T14:56:11Z)
-
-### Session summary
-
-Completed all 6 plan steps (collapsed into 5 commits: steps 3 and 5 merged).
-Baseline was 854 tests across 53 files; final suite is 856 tests across 54 files (+2 tests, +1 file for `concrete-agent-runner.test.ts`).
-All type-check, lint, and dead-code gates pass clean.
-
-### Observations
-
-- Plan steps 3 and 5 had to be merged into a single commit: removing `createAgentsMenuHandler` immediately broke `index.ts` imports, so the `index.ts` update could not wait for a separate commit.
-  This is a known coupling when a factory's only call site is in `index.ts`.
-- The `AgentsMenuHandler` class constructor includes `agentActivity` as planned (the issue's proposed signature omitted it; the plan's deviation was correct).
-- `getModelLabel` internalization was clean: `resolveModel` and `getModelLabelFromConfig` are pure functions the class imports directly.
-- `AgentManager` structurally satisfies `AgentMenuManager` with no adapter closures — confirmed by `pnpm run check` passing immediately.
-- The `agent-menu.test.ts` refactor replaced `Partial<AgentMenuDeps>` overrides with a `makeHandler(opts)` helper that returns both the handler and collaborator stubs, which is cleaner for assertion.
-- `rumdl` emitted 3 warnings in `pnpm run lint` — these are pre-existing and unrelated to this change (lint passes for markdown linting, the warnings are from biome/eslint steps that auto-fixed nothing).
-
-## Stage: Final Retrospective (2026-05-25T15:04:47Z)
-
-### Session summary
-
-Completed all three stages (planning, TDD, shipping) in one sitting.
-Issue #196 shipped as `pi-subagents-v7.2.5`.
-All closure factories in pi-subagents are now classes; Phase 11 (Layers 3 + 4) is complete.
-
-### Observations
-
-#### What went well
-
-- The three-session lifecycle (plan → TDD → ship) completed cleanly in a single sitting with no user corrections.
-- Structural typing confirmation during planning paid off — `AgentManager` satisfied `AgentMenuManager` without adapter closures, and `pnpm run check` passed immediately after the wiring change.
-- The `makeHandler(opts)` test helper pattern (returning handler + collaborator stubs) was cleaner than the `Partial<AgentMenuDeps>` spread approach it replaced.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — The plan separated factory removal (step 3) from call-site update (step 5), even though the testing skill already has a rule: "When a TDD step changes an interface that has a single call site, the step must include updating that call site."
-  The planner treated this as a testing concern and didn't apply it during plan authoring.
-  Impact: steps 3 and 5 had to be merged at implementation time, producing a commit message explaining the deviation.
-  Added a cross-reference to `plan-issue.md`.
-
-#### What caused friction (user side)
-
-Nothing notable — the user's issue was well-specified and the three `/` commands ran without intervention.
-
-### Changes made
-
-1. Added single-call-site rule to `.pi/prompts/plan-issue.md` TDD Order section: when a step removes a factory/export with one call site, include the call-site update in the same step.