@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/retro/0166-extract-parent-session-info.md

@@ -1,66 +0,0 @@
----
-issue: 166
-issue_title: "refactor(pi-subagents): extract ParentSessionInfo from AgentSpawnConfig (13 fields)"
----
-
-# Retro: #166 — Extract ParentSessionInfo from AgentSpawnConfig
-
-## Stage: Planning (2026-05-24T16:00:00Z)
-
-### Session summary
-
-Produced a 6-step TDD plan to extract `ParentSessionInfo` from `AgentSpawnConfig`.
-The refactoring groups three co-traveling fields (`parentSessionFile`, `parentSessionId`, `toolCallId`) into a named value object, reducing `AgentSpawnConfig` from 13 to 11 fields.
-
-### Observations
-
-- The `SubagentsService` boundary (`service-adapter.ts`) does not pass any of the three fields, so this is a purely internal refactoring with no public API impact.
-- `getSessionInfo` in `AgentToolDeps` returns only `parentSessionFile` and `parentSessionId`; `toolCallId` comes from the `execute` callback's first argument — the plan keeps this separation and merges them at the `agent-tool.ts` boundary.
-- `RunOptions` in `agent-runner.ts` never carried `toolCallId` (it was consumed in `AgentManager.spawn` before reaching the runner), so the nested `parentSession` on `RunOptions` only holds the two session fields.
-- The deep-merge trap from the testing skill is relevant: `background-spawner.test.ts` has a `makeParams` factory that spreads flat fields — must be converted to nested `parentSession` construction.
-- Issue #165 (decompose `ResolvedSpawnConfig`) is closed, so this plan builds on stable ground.
-
-## Stage: Implementation — TDD (2026-05-24T17:00:00Z)
-
-### Session summary
-
-All 5 TDD cycles completed across `agent-manager.ts`, `agent-runner.ts`, `background-spawner.ts`, `foreground-runner.ts`, and `agent-tool.ts`.
-Test count held steady at 805 (no net new tests — refactor only).
-Type check and lint both clean after all steps.
-
-### Observations
-
-- The `AgentSpawnConfig` field count went from 15 to 13 (not 13 → 10 as originally estimated) — the architecture doc quoted the issue's stale count; the actual pre-refactor interface had 15 fields (`bypassQueue` and others were already present).
-  The architecture doc was updated to reflect "done" with a note about the nested group rather than a specific before/after number.
-- The deep-merge trap (noted in planning) did materialise: `background-spawner.test.ts`'s `makeParams` spread `Partial<BackgroundParams>` with flat fields.
-  Fixed by replacing the three flat fields with a single `parentSession` object at the factory level — top-level spread still works correctly since `parentSession` is one field.
-- `RunOptions` in `agent-runner.ts` needed a new import of `ParentSessionInfo` from `agent-manager.ts`; no circular dependency since `agent-runner.ts` already imports from `agent-manager.ts`.
-- `agent-tool.ts` still imports `AgentSpawnConfig` (needed by `AgentToolManager` interface) — the new `ParentSessionInfo` import was added alongside it.
-- All 5 commits are clean `refactor:` messages; architecture doc update is a separate `docs:` commit.
-
-## Stage: Final Retrospective (2026-05-24T18:00:00Z)
-
-### Session summary
-
-Planning, TDD implementation (5 steps), shipping, and CI verification all completed in a single session.
-Released as `pi-subagents-v6.18.2`.
-Zero rework — every TDD step went green on first attempt.
-
-### Observations
-
-#### What went well
-
-- The planning session's identification of the deep-merge trap in `background-spawner.test.ts`'s `makeParams` factory paid off — the TDD implementation handled it without friction because the risk was anticipated.
-- The 5-step inside-out TDD order (manager → runner → background → foreground → agent-tool) was the right sequence.
-  Each step only introduced type errors in files that subsequent steps would fix, with no circular breakage.
-- Clean mechanical execution — 805 tests before and after, zero rework commits, lint and type-check clean throughout.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan repeated the issue body's stale "13 fields" count without verifying against the actual `AgentSpawnConfig` interface (which had 15 fields after `bypassQueue` was added in a prior issue).
-  The plan also inconsistently claimed the extraction would reduce the count to both "11" and "10" in different places.
-  Impact: required corrections in the architecture doc update, but no implementation rework.
-
-#### What caused friction (user side)
-
-- None observed — the user let the session run autonomously through all stages without intervention.

package/docs/retro/0167-narrow-runner-io.md

@@ -1,63 +0,0 @@
----
-issue: 167
-issue_title: "refactor(pi-subagents): narrow RunnerIO (9 methods → 2 focused interfaces)"
----
-
-# Retro: #167 — narrow RunnerIO (9 methods → 2 focused interfaces)
-
-## Stage: Planning (2026-05-24T20:00:00Z)
-
-### Session summary
-
-Produced a plan to split the `RunnerIO` interface in `agent-runner.ts` into two focused sub-interfaces (`EnvironmentIO` and `SessionFactoryIO`) while keeping `RunnerIO` as a backward-compatible type alias for their intersection.
-The change is a pure refactoring with zero runtime behavior change.
-
-### Observations
-
-- The split is mechanical and low-risk: `RunnerIO` becomes `type RunnerIO = EnvironmentIO & SessionFactoryIO`, and all existing consumers (production code and test factories) continue to compile via structural typing.
-- Dependency #164 (reorganize into domain directories) is already closed, so file paths are current.
-- The two test `createRunnerIO()` factories are unannotated (intentionally, per testing skill guidelines), so they don't need type-level updates — only comment updates for documentation.
-- This is a two-commit TDD plan, suitable for `/build-plan` rather than full TDD cycles since no new tests are required.
-
-## Stage: Implementation — TDD (2026-05-24T20:45:00Z)
-
-### Session summary
-
-Completed both TDD steps in full.
-Step 1 added `EnvironmentIO` and `SessionFactoryIO` interfaces and converted `RunnerIO` to a type alias in `agent-runner.ts`; step 2 updated comments in both test factories.
-Test count held steady at 805/805 (50 files) — no behavioral changes.
-
-### Observations
-
-- The type check (`pnpm run check`) passed immediately after the interface split — structural typing meant zero call-site changes in `index.ts` or test factories.
-- `RunnerIO` JSDoc was split: `EnvironmentIO` got the environment-discovery description, `SessionFactoryIO` got the original "decouples from Pi SDK imports" description, and `RunnerIO` itself got a short backward-compatibility note.
-- Architecture doc updated: wide-interface table row and Step 4 roadmap entry both marked done.
-- No deviations from the plan.
-
-## Stage: Final Retrospective (2026-05-24T21:30:00Z)
-
-### Session summary
-
-Issue #167 completed across three sessions: planning, TDD implementation, and ship.
-The `RunnerIO` interface was split into `EnvironmentIO` and `SessionFactoryIO` with a backward-compatible type alias.
-Released as `pi-subagents-v6.18.4`.
-
-### Observations
-
-#### What went well
-
-- The plan correctly identified that structural typing would make this zero-friction — no call-site changes were needed in `index.ts` or either test factory.
-- The two-step TDD plan was right-sized for a pure refactoring: step 1 for the interface split, step 2 for comment updates.
-  No new tests were needed, and the existing 805 tests validated the change without modification.
-- Ship session was clean: CI passed first try, release-please PR merged, issue closed.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The TDD session's architecture doc update (`824fd72`) only touched the `RunnerIO`-specific table row and Step 4 roadmap entry.
-  It missed that the same file's "Current layout" section still showed the pre-#164 flat file structure and retained a redundant "Proposed directory restructuring" section.
-  The user had to request a follow-up update (`d4a98aa`) in the ship session.
-  Impact: one extra commit and user prompt; no rework of prior commits.
-
-#### What caused friction (user side)
-
-- No friction observed.

package/docs/retro/0168-extract-tool-filter-config.md

@@ -1,76 +0,0 @@
----
-issue: 168
-issue_title: "refactor(pi-subagents): extract ToolFilterConfig from SessionConfig (11 fields)"
----
-
-# Retro: #168 — extract ToolFilterConfig from SessionConfig
-
-## Stage: Planning (2026-05-24T19:00:00Z)
-
-### Session summary
-
-Produced a 2-step plan to extract `ToolFilterConfig` (grouping `toolNames`, `disallowedSet`, `extensions`) from `SessionConfig` and update `filterActiveTools` to accept the named type.
-The change is a pure internal refactoring — `SessionConfig` is not exported from the package.
-
-### Observations
-
-- The issue says "11 fields" but `SessionConfig` currently has 10 — likely a minor count discrepancy from when the issue was filed.
-  The extraction still reduces top-level fields from 10 to 8.
-- `toolNames` serves dual duty: it's both the session-creation tool list and the `filterActiveTools` allowlist reference.
-  Nesting it under `toolFilter` is still correct since both uses originate from the same assembled config.
-- `agent-runner-extension-tools.test.ts` exercises tool filtering end-to-end via `runAgent` and never references `SessionConfig` fields directly — it serves as a zero-change regression canary for this refactoring.
-- The plan has only 2 TDD steps because the refactoring is mechanical and behavior-preserving.
-  Step 1 handles the interface change + assembler + tests; step 2 handles the consumer (`filterActiveTools` + `runAgent`).
-
-## Stage: Implementation — TDD (2026-05-24T19:30:00Z)
-
-### Session summary
-
-Completed both refactoring steps cleanly.
-`ToolFilterConfig` is now exported from `session-config.ts`, nested as `SessionConfig.toolFilter`, and consumed by `filterActiveTools` as a single named argument.
-All 805 tests continue to pass; no new tests were added (pure structural refactoring with no behavior change).
-
-### Observations
-
-- Step 1 left intentional type errors in `agent-runner.ts` (expected: the consumer hadn't been updated yet); committing mid-step-1 was correct because the session-config tests were green in isolation.
-- The autoformatter ran on `agent-runner.ts` after the Step 2 edits (Biome reformatted the two condensed filter-call lines); the committed diff was already formatted.
-- All 9 flat-field assertions in `session-config.test.ts` (`result.toolNames`, `result.extensions`, `result.disallowedSet`) were correctly migrated to `result.toolFilter.*` — grep confirmed no stragglers.
-- `agent-runner-extension-tools.test.ts` required zero changes, confirming its role as a regression canary.
-- Architecture doc updated: `SessionConfig` row in the wide-interface table marked `✓ done`; Step 5 narrative updated to reflect actual field count (10 → 8, not 11 → 8 as the issue stated).
-
-## Stage: Final Retrospective (2026-05-24T20:00:00Z)
-
-### Session summary
-
-Issue #168 completed across three sessions (Planning → TDD → Ship) with zero friction, rework, or plan deviations.
-Total diff: 3 files changed, 37 insertions, 41 deletions (net reduction).
-Released as `pi-subagents-v6.18.5`.
-
-### Observations
-
-#### What went well
-
-- **Grep-before-commit safety net.**
-  The planning session identified 9 flat-field assertions in `session-config.test.ts` that would silently pass as `undefined` if missed during migration.
-  The TDD session grepped for all three field names before committing step 1, catching all 9 in one pass.
-  This is the testing skill’s "grep for all test files" rule applied to assertion migration.
-- **Regression canary identification during planning.**
-  The planning session called out `agent-runner-extension-tools.test.ts` as a zero-change regression canary.
-  The TDD session confirmed this prediction — no changes needed, all existing tests green.
-  Identifying canary tests during planning gave confidence that the two refactoring steps were correctly scoped.
-- **2-step granularity was right.**
-  Step 1 (interface + assembler + tests) left intentional type errors in the consumer.
-  Step 2 (consumer update) resolved them.
-  This kept each commit reviewable and type-check-green at the session-config boundary.
-
-#### What caused friction (agent side)
-
-None.
-
-#### What caused friction (user side)
-
-None.
-
-### Changes made
-
-No process changes — clean execution with no proposals warranted.

package/docs/retro/0169-extract-run-context-from-run-options.md

@@ -1,68 +0,0 @@
----
-issue: 169
-issue_title: "refactor(pi-subagents): extract RunContext from RunOptions (12 fields)"
----
-
-# Retro: #169 — extract RunContext from RunOptions
-
-## Stage: Planning (2026-05-24T17:07:10Z)
-
-### Session summary
-
-Produced a plan to extract 4 parent-context fields (`exec`, `registry`, `cwd`, `parentSession`) from `RunOptions` into a nested `RunContext` interface.
-The plan is a single-step refactor (all changes in one commit) plus a comment-update commit, affecting 3 source files and 3 test files.
-
-### Observations
-
-- The issue body proposed flat `parentSessionFile`/`parentSessionId` fields on `RunContext`, but #166 already grouped these into `ParentSessionInfo`.
-  The plan uses `parentSession?: ParentSessionInfo` instead, preserving the existing grouping.
-- `RunOptions` is purely internal — not exported via `service.ts` — so the refactor is non-breaking.
-- All test call sites construct `RunOptions` inline (no `Partial<RunOptions>` spread patterns), so TypeScript will catch any missing `context` field at compile time.
-- The change is small enough to land in a single TDD step — no lift-and-shift needed.
-- Prerequisite #164 (directory reorganization) is already implemented.
-
-## Stage: Implementation — TDD (2026-05-24T17:14:32Z)
-
-### Session summary
-
-Completed both TDD steps in one session.
-Step 1 defined `RunContext`, updated `RunOptions`, migrated `runAgent()` reads to `options.context.*`, restructured `AgentManager.startAgent()`, and updated all 16 test call sites across 3 test files.
-Step 2 updated comment references in `runtime.ts` and `session-config.ts`.
-Test count unchanged (50 files, 805 tests — pure refactor with no behavior change).
-
-### Observations
-
-- The `agent-manager.test.ts` update also added two new assertions (`context.exec` and `context.registry` are defined) to each existing `getRunConfig` threading test, confirming the context object is wired correctly; these were not in the plan but add useful coverage.
-- All 16 `runAgent()` call sites in tests used inline option literals (no spread patterns), so TypeScript caught any missed site at compile time — the plan's risk mitigation held.
-- No deviations from the plan otherwise; the comment-only step was trivial.
-
-## Stage: Final Retrospective (2026-05-24T17:32:52Z)
-
-### Session summary
-
-Completed the full issue lifecycle (plan → TDD → ship → retro) in a single conversation.
-The refactor extracted 4 parent-context fields from `RunOptions` into a nested `RunContext` interface, updating 3 source files and 3 test files.
-Released as `pi-subagents-v6.18.6`.
-
-### Observations
-
-#### What went well
-
-- The plan correctly adapted the issue's stale proposed interface (flat `parentSessionFile`/`parentSessionId`) to match the already-implemented `ParentSessionInfo` grouping from #166.
-  This prevented a design conflict and kept the extraction consistent with prior work.
-- All 16 test call sites used inline option literals — no spread patterns — so TypeScript caught every missed migration site at compile time.
-  The plan's risk analysis predicted this correctly.
-- Single-step TDD was appropriate for this scope; no lift-and-shift was needed.
-
-#### What caused friction (agent side)
-
-- `missing-context` — After the TDD step, checked the architecture doc for staleness by running `grep` for the exact symbols `RunOptions` and `RunContext`.
-  The doc's "Dependency bag inventory" table and "Proposed bag decompositions" section used prose descriptions ("12 fields", "High") rather than code identifiers, so the grep found no matches and the agent skipped the update.
-  The user then asked "Is the architecture doc up to date?"
-  which prompted a three-fix commit (`ea49fe1`).
-  Impact: one extra round-trip with the user; no rework to code, but an extra commit that could have been folded into the TDD step.
-
-#### What caused friction (user side)
-
-- No friction observed on the user side.
-  The user's single question ("Is the architecture doc up to date?") was well-timed and caught the only gap.

package/docs/retro/0170-reduce-build-content-lines-complexity.md

@@ -1,72 +0,0 @@
----
-issue: 170
-issue_title: "refactor(pi-subagents): reduce buildContentLines complexity (cognitive 71)"
----
-
-# Retro: #170 — reduce buildContentLines complexity
-
-## Stage: Planning (2026-05-24T20:00:00Z)
-
-### Session summary
-
-Produced a plan to extract per-content-type formatters from `buildContentLines` (cognitive complexity 71) into a new `ui/message-formatters.ts` module.
-The plan includes 8 TDD steps: 6 red→green steps for unit tests covering each formatter and the dispatcher, then 2 refactor steps to create the module and simplify `buildContentLines` to a dispatch loop.
-
-### Observations
-
-- The extraction is mechanical — each `if`/`else if` branch in the loop becomes a standalone pure function returning `string[] | null`.
-- `FormatterContext` is deliberately narrow (2 fields: `theme` + `wrapText`) to avoid growing a dependency bag.
-- File-local types (`ToolCallContent`, `BashExecutionMessage`) and helpers (`getToolCallName`, `isBashExecution`) move with the formatters since they have no other consumers.
-- Existing `conversation-viewer.test.ts` tests are integration-level width-safety tests and remain unchanged — they exercise `render()` → `buildContentLines` → `truncateToWidth`, which is orthogonal to per-message formatting.
-- Issue #164 (domain directory reorganization) is already implemented, so the file is at `src/ui/conversation-viewer.ts`.
-
-## Stage: Implementation — TDD (2026-05-24T21:00:00Z)
-
-### Session summary
-
-Completed all 8 TDD steps: 6 red→green cycles building up `src/ui/message-formatters.ts` (one formatter per step), then 2 refactor steps moving helpers out of `conversation-viewer.ts` and replacing `buildContentLines` with a dispatch loop.
-Test count went from 805 to 853 (+48 new unit tests in `test/message-formatters.test.ts`).
-`conversation-viewer.ts` shrank from 325 to 251 lines.
-
-### Observations
-
-- `getToolCallName` needed to be exported (not just file-local) so `conversation-viewer.ts` could import it during the intermediate step 7 state; it stays exported since `message-formatters.ts` owns it permanently.
-- The `AgentMessage` SDK type does not have an index signature, so the `formatMessage` call in `buildContentLines` required `as unknown as { role: string; [key: string]: unknown }` to satisfy TypeScript's structural checker — this is consistent with the existing `as any` pattern in the codebase for untyped SDK boundaries.
-- The `formatStreamingIndicator` uses `◍` (U+25CD CIRCLE WITH VERTICAL FILL) to match the original `▍` character in `buildContentLines` — confirmed identical output.
-- Pre-existing lint warning (`Theme` unused import in `conversation-viewer.test.ts`) was fixed as a `style:` commit alongside the final step.
-
-## Stage: Final Retrospective (2026-05-24T22:00:00Z)
-
-### Session summary
-
-Shipped issue #170 (CI green, issue closed, released as `pi-subagents-v6.18.7`), then reviewed the full three-session lifecycle (planning → TDD → shipping) for friction patterns.
-
-### Observations
-
-#### What went well
-
-- The extraction was clean: 48 new unit tests, no behavioral change, all 853 tests green throughout.
-- The `FormatterContext` interface stayed at exactly 2 fields — the narrow-interface discipline held.
-
-#### What caused friction (agent side)
-
-1. `wrong-abstraction` — The plan decomposed 8 TDD steps for a mechanical extraction.
-   Six separate test-only commits (one per formatter) added commit noise without meaningful red→green insight.
-   Impact: added friction but no rework; a 2–3 step plan would have been cleaner for a copy-and-extract refactoring.
-2. `missing-context` — Step 7 (move helpers) and step 8 (rewire `buildContentLines`) were planned as separate commits, but the intermediate state required temporarily exporting `getToolCallName` and keeping `extractText`/`describeActivity` imports.
-   The plan didn't account for this intermediate dependency chain.
-   Impact: one extra edit cycle to add then remove the temporary export.
-3. `instruction-violation` (self-identified, user-caught) — The `/tdd-plan` prompt's step 5 says to check `packages/<PKG>/docs/architecture/` after the last TDD step.
-   I did not update the architecture doc until the user asked.
-   Impact: one extra commit and a user intervention; the rule was clear but missed during execution.
-4. `missing-context` — The `formatMessage` dispatcher used `{ role: string; [key: string]: unknown }` as its parameter type, which required `as unknown as` at the call site because the SDK's `AgentMessage` union includes `CompactionSummaryMessage` without an index signature.
-   The plan's design overview didn't anticipate this SDK type mismatch.
-   Impact: one extra edit cycle during step 8, no rework.
-
-#### What caused friction (user side)
-
-- No friction observed — the user's single intervention (architecture doc) was a legitimate catch of a missed step.
-
-### Changes made
-
-1. Updated `packages/pi-subagents/docs/retro/0170-reduce-build-content-lines-complexity.md` with final retrospective stage entry.

package/docs/retro/0171-reduce-render-result-complexity.md

@@ -1,77 +0,0 @@
----
-issue: 171
-issue_title: "refactor(pi-subagents): reduce renderResult complexity (cognitive 43)"
----
-
-# Retro: #171 — refactor(pi-subagents): reduce renderResult complexity
-
-## Stage: Planning (2026-05-24T20:00:00Z)
-
-### Session summary
-
-Produced a plan to extract per-status rendering from `renderResult` in `tools/agent-tool.ts` into a new `tools/result-renderer.ts` module with seven pure functions and a dispatcher.
-The TDD order has 9 steps: 7 test-first steps (one per function) followed by 2 refactor steps (extract, then simplify).
-
-### Observations
-
-- No existing tests cover `renderResult` — all `agent-tool.test.ts` tests exercise `execute` paths and tool metadata only.
-  This means the TDD steps write tests against a not-yet-existing module, which is clean red→green.
-- The inline `stats()` closure is used by 4 of 6 status branches, making it a natural shared function.
-- Completed/steered share 90% of logic (icon color + collapsed text differ); error/aborted share icon+stats structure.
-  Keeping each pair in one function avoids wrong-abstraction duplication.
-- The `Theme` type in `display.ts` and the `widget-renderer.ts` pattern in `ui/` provide a proven template for pure rendering modules — the new module follows the same shape.
-- Dependency #164 (domain directory reorganization) is already merged, so file paths use the `tools/` subdirectory.
-
-## Stage: Implementation — TDD (2026-05-24T21:00:00Z)
-
-### Session summary
-
-Completed all 9 TDD steps from the plan: 7 test-first commits adding `renderStats`, `renderRunning`, `renderBackground`, `renderCompleted`, `renderStopped`, `renderFailed`, and `renderAgentResult` to `result-renderer.ts`, followed by a refactor commit simplifying `renderResult` in `agent-tool.ts` to a 10-line guard + dispatcher.
-Test count increased from 853 to 896 (+43 new tests across 52 test files).
-A docs commit updated the architecture file to remove `renderResult` from the complexity hotspot table and add `result-renderer.ts` to the tools layout.
-
-### Observations
-
-- Steps 1–7 built `result-renderer.ts` function by function; the implementation was written upfront from a careful reading of the original `renderResult` body, making each subsequent test step immediately green.
-  This is valid TDD for an extraction refactor: the tests lock in expected behavior before the extraction is done.
-- The ESLint pre-commit hook correctly removed `@typescript-eslint/no-unsafe-return` from `agent-tool.ts`'s `eslint-disable` comment — that rule was only needed by the old `renderResult` body, not the new dispatcher.
-- No deviations from the plan: all 7 functions in `result-renderer.ts`, `renderResult` is now a guard + dispatcher as designed, and all 3 unused imports (`SPINNER`, `formatMs`, `formatTurns`) were removed.
-- The `Theme` type from `display.ts` worked cleanly for the pure functions — the `widget-renderer.ts` precedent held.
-
-## Stage: User Note (2026-05-24T21:30:00Z)
-
-We need to update `/plan-issue` so the plan includes updating any architecture documents.
-
-## Stage: Final Retrospective (2026-05-24T22:00:00Z)
-
-### Session summary
-
-Issue #171 shipped cleanly across three sessions: planning produced a 9-step TDD plan, implementation added 43 tests and extracted `renderResult` into `tools/result-renderer.ts` (cognitive complexity 43 → dispatcher), and shipping released `pi-subagents-v6.18.8` with no deviations.
-The only friction was an incomplete architecture doc update that required a second manual pass.
-
-### Observations
-
-#### What went well
-
-- The plan-to-implementation pipeline worked smoothly for a mechanical extraction refactor — zero deviations from the plan across all 9 TDD steps.
-- The `Theme` type from `display.ts` and the `widget-renderer.ts` pattern provided a proven template, making the extraction straightforward.
-- ESLint pre-commit hooks caught a stale `eslint-disable` rule (`no-unsafe-return`) automatically during the refactor commit.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The TDD session's initial architecture update (commit `1183522`) only updated the complexity hotspot table and layout listing, missing health metrics, the Mermaid domain diagram, the Phase 10 structural refactoring table, and the SKILL.md domain table.
-  The user had to explicitly request the fuller update, which landed as a second commit (`1510dc7`).
-  Impact: extra user round-trip and a second commit for what should have been one complete update.
-- `missing-context` — The `git add ../../.pi/skills/...` path triggered a `pi-permission-system` permission denial because the relative path escaped the package directory.
-  Switched to repo-root-relative path to resolve.
-  Impact: minor — one failed commit attempt, immediately retried.
-
-#### What caused friction (user side)
-
-- The `/plan-issue` prompt did not instruct the planner to check architecture docs for sections affected by the change.
-  Because the plan's Module-Level Changes omitted `docs/architecture/architecture.md`, the TDD session treated architecture updates as an afterthought rather than a planned deliverable.
-  Impact: the user had to intervene with an explicit request and a retro note.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — Added architecture-doc check to the Module-Level Changes bullet: "When the change adds, removes, or moves a module, check `packages/<PKG>/docs/architecture/` for layout listings, complexity tables, health metrics, or domain diagrams that reference the affected files and list them as doc updates."

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.