@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/retro/0152-add-prompt-snippet.md

@@ -1,34 +0,0 @@
----
-issue: 152
-issue_title: "Add promptSnippet to pi-subagents tools"
----
-
-# Retro: #152 — Add `promptSnippet` to pi-subagents tools
-
-## Final Retrospective (2026-05-22)
-
-### Session summary
-
-Added `promptSnippet` to the `Agent`, `get_subagent_result`, and `steer_subagent` tool registrations in pi-subagents, matching the convention used by pi-github-tools and pi-colgrep.
-The full plan→TDD→ship pipeline completed in one session with zero rework.
-Released as `pi-subagents-v6.14.0`.
-
-### Observations
-
-#### What went well
-
-- Clean single-cycle execution: the issue was unambiguous, the plan correctly scoped it as one TDD step, and the implementation matched the plan exactly.
-- Cross-package convention check (grepping sibling packages for `promptSnippet` usage) confirmed the `"tool_name: One-liner."` format before writing the plan, avoiding any wording rework.
-
-#### What caused friction (agent side)
-
-No friction points identified.
-The issue was a straightforward property addition with no design decisions, no interface changes, and no downstream breakage.
-
-#### What caused friction (user side)
-
-No friction points identified.
-
-### Changes made
-
-1. Created `packages/pi-subagents/docs/retro/0152-add-prompt-snippet.md` (this file).

package/docs/retro/0164-reorganize-into-domain-directories.md

@@ -1,82 +0,0 @@
----
-issue: 164
-issue_title: "refactor(pi-subagents): reorganize source into domain directories"
----
-
-# Retro: #164 — refactor(pi-subagents): reorganize source into domain directories
-
-## Stage: Planning (2026-05-23T00:00:00Z)
-
-### Session summary
-
-Read issue #164, confirmed #157 (import normalization) was a prerequisite and had been completed.
-Explored the full `src/` and `test/` structure, mapped every relative import in the 26 files to be moved, and produced a four-commit plan that moves files domain-by-domain in dependency order.
-
-### Observations
-
-- Issue #157 removed `.js` suffixes and introduced `#src/*` aliases in `test/` files.
-  This makes the reorganization cleaner: test imports are flat `#src/agent-manager` → `#src/lifecycle/agent-manager` with no depth variation.
-- `lifecycle/` and `observation/` have a circular dependency (`agent-manager` ↔ `record-observer`), so they must be moved in a single commit (Step 3).
-  All other domains can be committed independently.
-- `vitest.config.ts` uses `"test/**/*.test.ts"` — test files in new subdirectories are
-  auto-discovered without config changes.
-- Three UI test files (`conversation-viewer.test.ts`, `display.test.ts`,
-  `widget-renderer.test.ts`) are misplaced at `test/` root; left out of scope for this issue.
-- No `default-agents.test.ts`, `context.test.ts`, or `execution-state.test.ts` exist —
-  those src modules have no dedicated test files.
-- The import tables in the plan enumerate every path change; `pnpm run check` will catch
-  any missed update before each commit.
-
-## Stage: Implementation — TDD (2026-05-23T16:55:00Z)
-
-### Session summary
-
-Executed all four plan steps (config, session, lifecycle+observation, service) plus a fifth unplanned step converting all `src/` internal imports to `#src/` aliases.
-All 50 test files and 805 tests pass throughout.
-Updated `docs/architecture/architecture.md` to reflect the completed restructuring.
-
-### Observations
-
-- The plan's consumer tables were mostly complete but missed a few files: `src/ui/widget-renderer.ts` and `src/session-config.ts` (still at root during step 1) both imported `agent-types`; `src/service-adapter.ts` imported `model-resolver`; `test/parent-snapshot.test.ts` had a `vi.mock("#src/context")` path.
-  All caught immediately by `pnpm run check` or a failing test.
-- `src/service-adapter.ts` and `src/service.ts` (still at root during step 3) imported `parent-snapshot` and `usage` which moved in that step, so they had to be fixed as part of step 3's commit rather than step 4's.
-- The `#src/` alias conversion (fifth commit) was added after the user correctly observed that `src/` files should use the same alias style as `test/` files.
-  This eliminates all `../` relative cross-directory imports from `src/`.
-  Future file moves in `src/` now only require updating the `#src/domain/name` string — no relative depth arithmetic.
-- Biome auto-fixed 14 files (import sorting / trailing whitespace) during the `#src/` conversion step; committed via `git add -A` after the pre-commit hook run.
-
-## Stage: Final Retrospective (2026-05-23T17:10:00Z)
-
-### Session summary
-
-Shipped #164 (6 commits, `pi-subagents-v6.17.2`), filed #174 (ESLint for type-aware rules + import path enforcement), and reviewed the full issue lifecycle across planning, implementation, and shipping sessions.
-
-### Observations
-
-#### What went well
-
-- The user's mid-implementation redirect to use `#src/` aliases in `src/` files was the highest-impact intervention across the entire issue.
-  It eliminated the `../` depth-arithmetic problem, simplified the final commit to a one-liner `sed` command across 40 files, and directly motivated #174.
-- `pnpm run check` (`tsc --noEmit`) caught every missed consumer immediately — no broken commit ever landed.
-- The four-step dependency ordering (config → session → lifecycle+observation → service) kept every commit green despite the circular dependency between `lifecycle` and `observation`.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — Used ~60 individual `Edit` tool calls across steps 1–4 for what was a mechanical find-and-replace.
-  The fifth commit proved `sed` handles bulk import rewrites across 40 files in a single command.
-  Impact: hundreds of unnecessary tool calls and significant token waste across four commits.
-- `missing-context` — The plan's consumer tables missed 4 files (`src/ui/widget-renderer.ts`, `src/session-config.ts`, `src/service-adapter.ts`, `test/parent-snapshot.test.ts` `vi.mock` path).
-  The plan manually traced imports instead of using `grep` to enumerate all consumers of each moving module.
-  Impact: mid-step rework in steps 1, 2, and 3 to fix un-updated imports caught by `tsc`.
-- `missing-context` — Did not recognize that `src/` files should use `#src/` aliases (same as `test/` files) even though #157 set up the aliases for exactly this purpose.
-  Impact: all four domain-move commits used relative `../` imports, requiring a fifth unplanned commit to convert them.
-  User-caught.
-- `wrong-abstraction` — The agent lacks access to LSP-level refactoring tools ("Move to file", "Rename symbol") that a human developer would use for this kind of reorganization.
-  A human with an LSP would have completed the entire issue in minutes with zero missed consumers.
-  This is a fundamental capability gap — the agent compensated with low-level text manipulation, which is error-prone and token-expensive.
-
-#### What caused friction (user side)
-
-- The `#src/` alias convention was established in #157 but the user didn't flag it during the planning session.
-  Had this been raised during planning, all four domain-move commits would have used `#src/` from the start.
-  The user did catch it during implementation, which was still early enough to save the final result.

package/docs/retro/0165-decompose-resolved-spawn-config.md

@@ -1,78 +0,0 @@
----
-issue: 165
-issue_title: "refactor(pi-subagents): decompose ResolvedSpawnConfig (15 fields)"
----
-
-# Retro: #165 — decompose ResolvedSpawnConfig (15 fields)
-
-## Stage: Planning (2026-05-24T13:41:41Z)
-
-### Session summary
-
-Produced a 5-step TDD plan to decompose the 15-field `ResolvedSpawnConfig` into three nested sub-interfaces (`SpawnIdentity`, `SpawnExecution`, `SpawnPresentation`).
-Also improved skill descriptions for `colgrep` and `markdown-conventions` to signal decision-relevant content rather than tool reference material.
-
-### Observations
-
-- The proposed decomposition in the issue aligns well with actual field usage patterns — no adjustments needed.
-- `modelName` and `agentTags` are never accessed by external consumers; they're intermediate computation exposed on the return type.
-  Keeping them on `SpawnPresentation` is harmless and aids debuggability.
-- Step 1 (interface change + return restructure) will break type checking for all consumers simultaneously.
-  The plan addresses this by landing steps 1–4 in rapid succession on the same branch.
-- Both test files have `makeConfig()` factories that must be updated in lock-step with their respective source files.
-- Issue #164 (directory reorganization) is closed, so import paths are already in their final `#src/<domain>/` form.
-
-## Stage: Implementation — TDD (2026-05-24T14:32:58Z)
-
-### Session summary
-
-Completed all 4 TDD cycles plus full-suite verification in one session.
-The decomposition touched 7 files (4 source, 3 test) and kept the test count flat at 805 — no new tests needed for a pure structural refactor.
-
-### Observations
-
-- The `Partial<ResolvedSpawnConfig>` spread pattern in `makeConfig` factories doesn't deep-merge into nested sub-objects.
-  Two tests (`foreground-runner.test.ts` and `background-spawner.test.ts`) used flat field overrides (`{ fellBack: true }`, `{ description: "my task" }`) that silently stopped working after nesting.
-  Fixed by writing out the full nested sub-object at the override call site.
-  Future factories for nested config types should either deep-merge or avoid the `Partial<T>` spread pattern — see the `testing` skill's warning about this.
-- Step 1 breaking all consumers simultaneously was handled smoothly by completing all steps before pushing, as planned.
-  No transitional alias was needed.
-- The `background-spawner.test.ts` description-override test was the only unexpected friction point — the flat spread issue wasn't caught by the plan.
-
-## Stage: Final Retrospective (2026-05-24T15:00:14Z)
-
-### Session summary
-
-Shipped issue #165 (CI green, released as `pi-subagents-v6.18.1`) and ran the final retrospective.
-The most impactful outcome across all three sessions was the skill description improvements (commit `51f52ef`), which addressed a recurring `instruction-violation` pattern.
-
-### Observations
-
-#### What went well
-
-- The user's probing question ("This is consistent, though.
-  Why?") turned a simple skill-loading skip into a generalizable improvement to three skill descriptions and two prompt instructions.
-  This is a good example of the user investing a redirecting question instead of a correction.
-- TDD execution was clean — 4 cycles, no rework, no type errors at the end.
-  The plan's risk mitigation ("land steps 1–4 on the same branch") worked as intended.
-- Ship stage had zero friction: push, CI, close, release-please merge, tag — all first-try.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` — Skipped loading the `colgrep` skill during planning despite explicit instructions.
-  Root cause: skill descriptions that read like tool reference manuals get deprioritized because the agent perceives them as redundant with the tool schema already in context.
-  Impact: no rework on the plan itself, but triggered a productive detour to improve skill descriptions.
-  User-caught.
-- `missing-context` — The plan didn't anticipate that `Partial<ResolvedSpawnConfig>` spread in test factories would silently break after nesting.
-  The `testing` skill already warns about spread-related pitfalls, but not this specific variant (flat keys ignored by top-level spread on a nested structure).
-  Impact: one test failure during step 4 that required a verbose inline fix (writing out the full `execution` sub-object).
-  Self-identified during implementation.
-
-#### What caused friction (user side)
-
-- None observed.
-  The user's intervention on the `colgrep` skill was well-timed and produced a higher-value outcome than skipping it would have.
-
-### Changes made
-
-1. Added a TDD planning rule to `.pi/skills/testing/SKILL.md` warning about `Partial<T>` spread not deep-merging into nested interfaces after a flat-to-nested refactor.

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."