@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/retro/0134-reduce-as-any-casts.md

@@ -1,56 +0,0 @@
----
-issue: 134
-issue_title: "Reduce `as any` casts in test suite"
----
-
-# Retro: #134 — Reduce as-any casts in test suite
-
-## Final Retrospective (2026-05-22T17:00:00Z)
-
-### Session summary
-
-Reduced `as any` casts from 93 to 15 across the pi-subagents package.
-Production changes added type guards (`getToolCallName`, `isBashExecution`), narrowed `SubagentRuntime.widget` to `WidgetLike`, typed `CreateSessionOptions.settingsManager` as `SettingsManager`, and fixed `ResourceLoaderOptions.appendSystemPromptOverride` to match the SDK.
-Test improvements introduced `toAgentSession()`, `STUB_CTX`, and `makeRegistry()` helpers to centralise unavoidable bridge casts.
-Also fixed 3 pre-existing lint issues.
-
-This session also included #133 (plan + implement + ship) which preceded the #134 work.
-
-### Observations
-
-#### What went well
-
-- The user's Kent Beck prompt ("make the change that makes the change easy") redirected the plan from test-only fixes to targeted production changes, yielding cleaner results — `WidgetLike`, type guards, and SDK-typed options eliminated casts that would have been impossible to remove from tests alone.
-- The user's TDA observation on the `MenuCtx` step caught a deep architectural issue (context threaded 4 layers just to relay to `buildParentSnapshot`).
-  Skipping step 4 was the right call — attempting it would have added a production cast or cascaded changes through 6+ files.
-
-#### What caused friction (agent side)
-
-1. `rabbit-hole` — Step 1 planning involved extensive analysis of whether `CreateSessionOptions` could use full SDK types.
-   Spent significant reasoning tracing `ModelRegistry` / `SessionManager` private fields, structural compatibility, `ParentSnapshot` constructibility, and `ResourceLoader` interface width before concluding that only `settingsManager` and the callback signature could be fixed.
-   The plan's claim "widen to SDK types" was optimistic about class-with-private-fields constraints.
-   Impact: added friction but no rework — the conclusion was correct, just slow to reach.
-
-2. `wrong-abstraction` — Step 4 (`MenuCtx`) attempted to mechanically narrow the handler parameter without questioning why `ctx` was threaded 4 layers deep.
-   Partially implemented the `MenuCtx` interface before the user's "What am I misunderstanding?"
-   prompt exposed the real issue: a TDA violation where intermediate functions carry `ExtensionContext` only to relay it.
-   Impact: partial implementation reverted via `git checkout src/ui/agent-menu.ts`; ~10 minutes of wasted edits.
-
-3. `instruction-violation` (user-caught) — Used `pnpm exec biome check --write --unsafe` instead of `pnpm run lint:fix` to fix pre-existing lint issues.
-   The `/tdd-plan` prompt explicitly says "run `pnpm run lint:fix`."
-   Impact: no functional difference (same result), but violated the established convention and used an unnecessary `--unsafe` flag.
-
-4. `instruction-violation` (user-caught) — Dismissed pre-existing lint issues as "not from our changes" without fixing them.
-   The user asked "Why do we have pre-existing lint issues?"
-   — the correct action was to fix them immediately rather than noting and ignoring them.
-   Impact: required an extra commit (`style: fix pre-existing lint issues`) that should have been folded into an earlier step.
-
-#### What caused friction (user side)
-
-- The user's interventions on the `MenuCtx` step and lint issues were both valuable redirections that improved the outcome.
-  No mechanical overhead identified — each intervention was strategic judgment that the agent couldn't have reached alone.
-
-### Changes made
-
-1. `.pi/prompts/tdd-plan.md` — added "Verify green baseline" section (check + lint + test before starting TDD); added "Fix all failures — including pre-existing ones" to the end-of-cycle lint step.
-2. `.pi/prompts/build-plan.md` — same baseline check and fix-all rule for non-TDD plans.

package/docs/retro/0135-extract-display-helpers.md

@@ -1,38 +0,0 @@
----
-issue: 135
-issue_title: "Extract display helpers from `agent-widget.ts`"
----
-
-# Retro: #135 — Extract display helpers from agent-widget.ts
-
-## Final Retrospective (2026-05-22T19:00:00Z)
-
-### Session summary
-
-Extracted 11 helper functions, 3 constants, and 2 types from `agent-widget.ts` into a new `ui/display.ts` module.
-Updated 10 source consumers and 2 test consumers.
-Pure code-motion refactoring — no behavior change, no test-count delta (714 tests throughout).
-
-### Observations
-
-#### What went well
-
-- Plan accurately identified all 10 source and 2 test import sites with no misses — the consumer import table in the plan mapped 1:1 to actual changes.
-- TDD execution was mechanical and smooth: create module → update source imports → rename test file → verify.
-  Zero surprises or deviations from the plan.
-
-#### What caused friction (agent side)
-
-- `rabbit-hole` — During `/ship-issue`, wasted ~6 tool calls investigating whether `pi-subagents-v6.12.0` was at HEAD.
-  Ran `git log --oneline HEAD --not --remotes=origin/main` which dumped the entire repo history (50KB truncation), then misread `git describe --tags --abbrev=0` (nearest ancestor tag) as confirming the tag was at HEAD.
-  `git tag --points-at HEAD` returned empty, disproving the assumption, but I still spent cycles reasoning about CI release-please behavior.
-  Impact: added friction but no rework — the close comment and release-please merge were correct.
-
-#### What caused friction (user side)
-
-- None observed.
-  The issue was unambiguous, the architecture doc prescribed the exact extraction set, and no user intervention was needed during implementation.
-
-### Changes made
-
-1. Created `packages/pi-subagents/docs/retro/0135-extract-display-helpers.md` (this file).

package/docs/retro/0136-decompose-agent-menu.md

@@ -1,43 +0,0 @@
----
-issue: 136
-issue_title: "Decompose `agent-menu.ts`"
----
-
-# Retro: #136 — Decompose `agent-menu.ts`
-
-## Final Retrospective (2026-05-22T20:10:00-04:00)
-
-### Session summary
-
-Decomposed `agent-menu.ts` (668 lines) into four focused modules: `agent-file-ops.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts`, and a slimmed-down `agent-menu.ts` (296 lines).
-Three TDD cycles shipped cleanly, adding 47 tests (714 → 761) and eliminating `vi.mock("node:fs")` from the menu test file.
-Released as `pi-subagents-v6.13.0`.
-
-### Observations
-
-#### What went well
-
-- The three-cycle TDD plan (file-ops → config-editor → creation-wizard) produced clean incremental commits with no rework.
-  Each cycle left the repo green for both tests and type-check.
-- The creation wizard naturally produced narrower interfaces (`WizardManager`, `WizardRegistry`) than the plan specified — a positive deviation from the plan's `AgentTypeRegistry` concrete type, following ISP more strictly.
-- The large edit removing ~170 lines of extracted functions from `agent-menu.ts` in Cycle 2 landed correctly on the first attempt, thanks to using exact `oldText` matching with the full function bodies.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The config-editor test factory used `Partial<AgentConfigEditorDeps>` for the overrides parameter.
-  The `...overrides` spread created a union type that erased `Mock<...>` methods from `fileOps`, producing 28 `TS2339` errors on `pnpm run check`.
-  The testing skill warns about return-type annotations but not about `Partial<Interface>` in overrides — the same erasure mechanism applies through a different path.
-  Impact: one extra edit-check cycle to remove the `Partial<>` annotation and overrides parameter.
-  Self-identified (caught on `pnpm run check` before commit).
-
-- `missing-context` — The config-editor test had an unused `ctx` variable from an earlier draft of the "disable-only file" test, caught only by the linter after the Cycle 3 commit.
-  Impact: required amending the Cycle 3 commit; added friction but no rework.
-  Self-identified (caught by `pnpm run lint`).
-
-#### What caused friction (user side)
-
-- None observed — the user's plan was unambiguous and the prerequisite (#135) was already implemented.
-
-### Changes made
-
-1. Added a `Partial<Interface>` type-erasure bullet to `.pi/skills/testing/SKILL.md`.

package/docs/retro/0144-consolidate-observation-model.md

@@ -1,39 +0,0 @@
----
-issue: 144
-issue_title: "Consolidate observation model (Phase 9, Step L)"
----
-
-# Retro: #144 — Consolidate observation model
-
-## Final Retrospective (2026-05-23)
-
-### Session summary
-
-Planned and implemented the Phase 9 Step L observation model consolidation.
-Removed dual `_toolUses`/`_lifetimeUsage` counting from `AgentActivityTracker`, added `session`/`outputFile` convenience getters to `AgentRecord`, migrated 14 callsites, and dissolved `NotificationDeps` into plain constructor parameters.
-Released as `pi-subagents-v6.16.0`.
-
-### Observations
-
-#### What went well
-
-- The plan correctly anticipated that TDD steps 4 (remove tracker stats) and 5 (migrate UI consumers) would be type-coupled and need merging.
-  This played out exactly as predicted — no surprise rework.
-- Step 2's grep sweep during `execution?.` migration found two callsites (`agent-tool.ts:315`, `agent-manager.ts:353`) that the plan's file list missed.
-  Systematic grep at migration time caught them before commit.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` — Did not load the `colgrep` skill during the planning phase despite two explicit instructions: AGENTS.md ("Use `colgrep` for intent-based codebase exploration") and the `/plan-issue` prompt ("load the `code-design` skill and the `colgrep` skill for convention discovery").
-  Loaded 4 other skills but skipped colgrep.
-  User-caught ("I noticed you didn't load or use `colgrep`").
-  Impact: one extra round-trip with the user; no rework since the plan hadn't been committed yet.
-  The colgrep searches proved useful once run — highest-scoring hit for "dependency bag converted to plain constructor parameters" was `notification.ts`, directly confirming the target.
-- `wrong-abstraction` — When editing `src/ui/ui-observer.ts` to remove the `message_end` accumulation block, the replacement text closed the `session.subscribe(...)` callback but also added the function's closing brace, producing a duplicate `}`.
-  Autoformat caught the parse error immediately.
-  Impact: one follow-up edit, no downstream rework.
-
-#### What caused friction (user side)
-
-- None observed.
-  The user's intervention on colgrep was timely — caught before plan commit, not after.

package/docs/retro/0145-decompose-execute-push-ctx-to-boundary.md

@@ -1,56 +0,0 @@
----
-issue: 145
-issue_title: "Decompose execute and push ExtensionContext to the boundary (Phase 9, Step M)"
----
-
-# Retro: #145 — Decompose execute and push ExtensionContext to the boundary
-
-## Final Retrospective (2026-05-23)
-
-### Session summary
-
-Extracted config resolution into a pure `resolveSpawnConfig` function, injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` to eliminate `ctx` reads from `execute`, pushed `ParentSnapshot` to `AgentManager`'s public API, and dissolved three small dependency bags (`ForegroundDeps`, `BackgroundDeps`, `AdapterDeps`) into plain parameters.
-Released as `pi-subagents-v6.15.0`.
-
-### Observations
-
-#### What went well
-
-- User's two escalating questions ("Are there any other missing collaborators?"
-  → "Hiding dependencies in an object bag still counts as dependencies!") caught a `premature-convergence` before it landed as committed code.
-  The reverted partial step 3 attempt was ~4 files of changes that would have needed rework.
-  The resulting design (injected collaborators) is meaningfully better than the original plan's mechanical relocation.
-- Folding tightly-coupled TDD steps (ctx elimination + params shrinking + deps dissolution) into fewer commits avoided intermediate states with broken types.
-  The plan's 12-step sequence would have required lift-and-shift gymnastics; the actual 7-commit sequence was cleaner.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — the original plan relocated `buildParentSnapshot` calls to `execute` without questioning whether `execute` should read `ctx` at all.
-  The existing `code-design` skill has DIP and parameter-relay rules that should have flagged this.
-  The `service-adapter.ts` module already demonstrated the getter-injection pattern (`getCtx`, `getModelRegistry`), but I didn't search for it during plan writing.
-  Impact: one plan rewrite commit (76bb57b), one reverted partial implementation (~15 minutes of rework).
-  User-caught.
-
-- `missing-context` — didn't use `colgrep` during initial plan writing to discover the established getter-injection convention in `service-adapter.ts`.
-  Used `grep` exclusively for exact symbol matching.
-  When prompted by the user to use `colgrep`, the results were confirmatory rather than revelatory because I'd already read the relevant files by that point.
-  The miss was not using it *earlier* for intent-based exploration ("how do existing modules inject session-scoped state?").
-  Impact: added friction but no rework — the user's questions surfaced the pattern before code was committed.
-  User-caught.
-
-- `instruction-violation` — wrote an inline `import()` type assertion (`session.ctx as import("@earendil-works/pi-coding-agent").ExtensionContext`) in `service-adapter.ts`.
-  AGENTS.md says "Use standard top-level imports only."
-  Impact: one extra edit round, caught before committing.
-  User-caught.
-
-#### What caused friction (user side)
-
-- The user's redirecting questions were well-timed and effective.
-  The escalation from "Are there any other missing collaborators?"
-  to the more pointed "Hiding dependencies in an object bag still counts as dependencies!"
-  was the right amount of pressure.
-  No friction observed on the user side.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added `colgrep` skill loading to the "Load skills" section for code-change plans, so convention discovery happens during exploration rather than after committing to a design.

package/docs/retro/0146-narrow-ui-context.md

@@ -1,70 +0,0 @@
----
-issue: 146
-issue_title: "Narrow UI context for menu handlers (Phase 9, Step N)"
----
-
-# Retro: #146 — Narrow UI context for menu handlers
-
-## Final Retrospective (2026-05-23T10:00:00Z)
-
-### Session summary
-
-Introduced a `MenuUI` interface in `agent-menu.ts` capturing the 6 `ctx.ui` methods used by menu handlers.
-Replaced `ExtensionContext` with `MenuUI` (plus explicit `ModelRegistry` and `ParentSnapshot`) in all inner functions across `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts`.
-Dissolved three ≤4-field dependency bags (`AgentConfigEditorDeps`, `GetResultDeps`, `SteerToolDeps`) into plain parameters; destructured `AgentMenuDeps` and `AgentCreationWizardDeps` in their factory signatures.
-Eliminated 42 `ctx as any` casts across 5 test files.
-Released as `pi-subagents-v6.16.2`.
-
-### Observations
-
-#### What went well
-
-- **User-initiated plan review caught three ordering bugs before implementation.**
-  The user asked the agent to "review the plan and judge its quality and clarity" after the initial commit.
-  The review identified three execution-blocking problems in the TDD order: `MenuUI` not defined before consumers, `ParentSnapshot` not threaded through the handler return type, and `index.ts` call sites not updated alongside their factories.
-  All three were fixed before TDD execution began, saving significant implementation friction.
-- The plan's TDD order (after fixes) worked well for a pure-refactoring change — all 806 tests stayed green throughout every step.
-- The type checker served as an effective safety net: every call-site mismatch was caught immediately by `pnpm run check`, preventing runtime surprises.
-
-#### What caused friction (agent side)
-
-##### Planning session
-
-- `missing-context` — The initial plan had three TDD ordering bugs: (1) `MenuUI` used before defined, (2) `ParentSnapshot` not threaded through handler return type, (3) `index.ts` call sites not updated alongside factory signature changes.
-  These were caught by a user-prompted plan review, not by the planning agent itself.
-  Impact: would have caused type-check failures during TDD execution; fixed before implementation started.
-
-- `wrong-abstraction` — After fixing the plan, the agent ran `git commit --amend --no-edit` to update the plan commit, but it landed on the wrong commit (a stacked prompt-changes commit from a different session).
-  This caused divergent history with origin.
-  Recovery required `git reset --hard origin/main` and re-applying the plan fixes as a new commit (`3d5b591`).
-  Impact: ~5 minutes of git recovery and re-application of edits.
-
-##### Implementation session
-
-- `missing-context` — In Step 3, the plan listed the `WizardManager.spawnAndWait` signature change (to accept `ParentSnapshot`) and the `AgentMenuManager.spawnAndWait` change as separate steps (3 and 4).
-  But `agent-menu.ts` passes `deps.manager` (typed as `AgentMenuManager`) to `createAgentCreationWizard`, which expects `WizardManager`.
-  Changing `WizardManager` without also changing `AgentMenuManager` broke the type checker.
-  I had to pull the `AgentMenuManager` change forward from Step 4 into Step 3.
-  Impact: minor — a few minutes of diagnosis and one extra edit, no rework.
-
-- `missing-context` — In Step 2, after dissolving `AgentConfigEditorDeps` and changing `showAgentDetail(ctx)` to `showAgentDetail(ui: MenuUI)`, I forgot to update the call site in `agent-menu.ts` from `editor.showAgentDetail(ctx, agentName)` to `editor.showAgentDetail(ctx.ui, agentName)`.
-  The type checker caught it immediately.
-  Impact: added friction but no rework — one extra `pnpm run check` cycle.
-
-- `missing-context` — In Step 4, the `makeUI()` test helper used `modelRegistry: {}` which didn't satisfy the `ModelRegistry` interface (requires `find` and `getAll`).
-  Impact: one extra `pnpm run check` cycle and a one-line fix.
-
-- `missing-context` — In Step 5, two tests called `createGetResultTool(makeDeps())` directly (not via the `execute()` helper).
-  After dissolving deps, the factory signature changed but I only updated `execute()`.
-  The type checker caught the two direct calls.
-  Impact: one extra `pnpm run check` cycle.
-
-#### What caused friction (user side)
-
-- None observed — the session ran autonomously with no user corrections needed.
-
-#### What caused friction (user side — planning)
-
-- The user had to explicitly ask for a plan review (“I'd like you to review the plan and judge its quality and clarity”) to surface three ordering bugs.
-  The planning agent should have caught these during plan authoring — the testing skill already contains rules about TDD step ordering and shared interface changes.
-  The user's intervention prevented significant implementation friction.

package/docs/retro/0147-inject-wrap-text-into-conversation-viewer.md

@@ -1,90 +0,0 @@
----
-issue: 147
-issue_title: "Inject text wrapping into ConversationViewer (Phase 9, Step O)"
----
-
-# Retro: #147 — Inject text wrapping into ConversationViewer (Phase 9, Step O)
-
-## Stage: Planning (2026-05-23T00:00:00Z)
-
-### Session summary
-
-Read the issue, loaded package-pi-subagents, code-design, testing, and markdown-conventions skills.
-Explored `src/ui/conversation-viewer.ts`, `src/ui/agent-menu.ts`, `test/conversation-viewer.test.ts`, and the Phase 9 architecture roadmap.
-Wrote and committed the plan at `packages/pi-subagents/docs/plans/0147-inject-wrap-text-into-conversation-viewer.md`.
-
-### Observations
-
-- The change is tightly scoped: two source files (`conversation-viewer.ts`, `agent-menu.ts`) and one test file.
-- `wrapTextWithAnsi` is called in exactly four places inside `buildContentLines` — all in the same private method, making the replacement straightforward.
-- The only production call site for `new ConversationViewer({…})` is `viewAgentConversation` in `agent-menu.ts`.
-  `wrapTextWithAnsi` is added as a static import there and passed as `wrapText` — no threading through `AgentMenuDeps` needed.
-- All `new ConversationViewer({…})` calls in the test file are inline (no shared factory helper), so every call site needs the new `wrapText` field added.
-  Grep confirms the count: 11+ calls, all in `test/conversation-viewer.test.ts`.
-- The plan uses 2 TDD cycles: Cycle 1 adds the field and updates all call sites (with the `vi.mock` still present for safety); Cycle 2 removes the mock and converts dynamic `await import()` to static imports.
-  This ordering avoids a large simultaneous change and gives the suite a stable intermediate state.
-- The "mock is intercepting wrapTextWithAnsi" test is deleted in Cycle 1 (it verified the mock mechanism, not production behavior).
-- No exported API symbols are removed; `wrapText` is a new required field on `ConversationViewerOptions`, which is a breaking change only for external constructors of `ConversationViewer` — confirmed none exist outside this package.
-
-## Stage: Implementation — TDD (2026-05-23T11:36:00Z)
-
-### Session summary
-
-Completed both TDD cycles from the plan.
-Cycle 1 added `wrapText` to `ConversationViewerOptions`, destructured options in the constructor, replaced all four `wrapTextWithAnsi` calls with `this.wrapText`, updated `agent-menu.ts` to import and pass `wrapTextWithAnsi`, and updated all 16 test constructor call sites (11 render-width-safety + 5 safety-net) while keeping the `vi.mock` shim in place.
-Cycle 2 removed the `vi.mock` block, `wrapOverride`, and `beforeEach` reset, then converted the dynamic `await import()` calls to ordinary static imports.
-Test count: 806 → 805 (deleted the mock-mechanism sentinel test).
-Full suite 50 files, 805 tests, all green.
-
-### Observations
-
-- The plan said the render-width-safety constructor calls numbered "11+" — the actual count was 16 total (11 render-width-safety + 5 safety-net), all in `test/conversation-viewer.test.ts`.
-  No external call sites existed.
-- `wrapTextWithAnsi` needed to be added to the dynamic import in Cycle 1 (`const { visibleWidth, wrapTextWithAnsi } = await import(...)`) because the render-width-safety tests reference it by name.
-  The plan didn't call this out explicitly — minor omission.
-- Used a Python script (inline via bash) to make the 17 constructor-call edits rather than 17 separate Edit-tool calls.
-  The safety-net tests each had a different stub character (`X`, `Y`, `Z`, `B`, `W`) which required a regex capture group to preserve.
-  The script worked on the first attempt.
-- Cycle 2 was a single Edit call replacing the entire mock block + the two dynamic imports + `beforeEach`.
-  The autoformatter then cleaned up import ordering automatically.
-- Architecture doc updated: smells table row struck-through and Step O marked ✓.
-
-## Stage: Final Retrospective (2026-05-23T11:45:00Z)
-
-### Session summary
-
-Planned, implemented, shipped, and released issue #147 across a single session chain.
-Two TDD cycles completed cleanly; CI passed; issue closed; `pi-subagents-v6.17.0` released.
-Test count: 806 → 805 (deleted mock-mechanism sentinel test).
-
-### Observations
-
-#### What went well
-
-- Python script for bulk constructor edits worked first-try on 17 call sites with per-test regex capture groups.
-  This is now a proven pattern — #116 and #147 both used it successfully for `ConversationViewer` constructor changes.
-- Two-cycle TDD approach (Cycle 1: add DI with mock still present; Cycle 2: remove mock) gave a stable intermediate state and caught the missing `wrapTextWithAnsi` import before proceeding.
-- Scope was tight: 3 files changed, 2 commits of substance, no rework on the production code.
-
-#### What caused friction (agent side)
-
-1. `instruction-violation` — Failed to load the `colgrep` skill during planning.
-   Constructed the path by pattern (`.pi/skills/colgrep/SKILL.md`) instead of using the `<location>` listed in the `<available_skills>` block (`packages/pi-colgrep/skills/colgrep/SKILL.md`).
-   Got ENOENT and silently moved on.
-   Impact: user-caught; required a follow-up exchange to load the skill and re-review the plan.
-   No rework needed — the plan was already correct.
-2. `wrong-abstraction` — Cycle 2 Edit replaced the entire `vi.mock` block + dynamic imports as one chunk, leaving the `ConversationViewer` static import stranded after `const testRegistry` instead of at the top with other imports.
-   Impact: user-caught ("Wait, we have a dynamic import?"); required a follow-up edit and amend into the retro commit.
-3. `missing-context` — Plan stated "11+" constructor call sites; actual count was 16 (11 render-width-safety + 5 safety-net).
-   The grep output during planning showed all 16 but the count wasn't verified.
-   Impact: no rework — the Python script handled all 17 (16 test + 1 production) regardless.
-
-#### What caused friction (user side)
-
-- No friction identified — user interventions were timely and precise.
-
-### Changes made
-
-1. Appended this final retrospective entry to `packages/pi-subagents/docs/retro/0147-inject-wrap-text-into-conversation-viewer.md`.
-2. Separated `colgrep` skill loading into its own bullet in `.pi/prompts/plan-issue.md` to reduce pattern-matching shortcuts.
-3. Replaced deterministic step in `.pi/prompts/retro.md` with a "Sync with remote" section matching the other prompts.

package/docs/retro/0148-split-agent-widget-rendering.md

@@ -1,39 +0,0 @@
----
-issue: 148
-issue_title: "Split AgentWidget rendering from lifecycle (Phase 9, Step P)"
----
-
-# Retro: #148 — Split AgentWidget rendering from lifecycle
-
-## Final Retrospective (2026-05-23T06:20:00Z)
-
-### Session summary
-
-Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
-The widget shrank from 374 to 198 lines — now a thin lifecycle wrapper. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
-Released as `pi-subagents-v6.16.1`.
-
-### Observations
-
-#### What went well
-
-- TDD cycles were fast and clean: 9 commits, all tests green on first or second try, zero test regressions across the full 806-test suite.
-- The `WidgetAgent` / `WidgetActivity` interfaces worked well as structural subsets — `AgentRecord` and `AgentActivityTracker` satisfy them without mapping code.
-- The stub `Theme` pattern from `test/renderer.test.ts` (`fg: (c, t) => \`[\${c}:\${t}]\``) transferred cleanly to the new test file, keeping assertions readable.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan's `renderWidgetLines` API spec omitted `theme` from its parameters, even though the heading, tree connectors, and per-agent render calls all require it.
-  Caught immediately at step 4 (first `renderWidgetLines` test) and fixed by adding `theme` to the params.
-  Impact: deviation note in commit body; no rework.
-
-- `missing-context` — Step 3 (`renderRunningLines` implementation) initially missed importing `SPINNER` from `display.ts`.
-  The test caught it as a runtime `ReferenceError`, fixed in the same Red→Green cycle.
-  Impact: added friction but no rework.
-
-- `wrong-abstraction` — Step 8 ("Extract into `widget-renderer.ts`") was a no-op because the module was created incrementally during steps 1–7 (tests must import from the new module to run).
-  Impact: step skipped; noted in summary.
-
-#### What caused friction (user side)
-
-- None observed — the session ran autonomously from plan through ship with no user corrections needed.

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.