@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/retro/0218-push-sdk-boundary-in-settings.md

@@ -1,72 +0,0 @@
----
-issue: 218
-issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
----
-
-# Retro: #218 — Push SDK boundary in settings.ts
-
-## Stage: Planning (2026-05-26T17:01:55Z)
-
-### Session summary
-
-Produced a 3-step TDD plan to inject `agentDir: string` into `SettingsManager` and `loadSettings`, removing the only Pi SDK import from `settings.ts`.
-The change is straightforward — a single parameter addition threading through constructor, free function, and boundary wiring.
-
-### Observations
-
-- The change is entirely mechanical: no design ambiguity, no new abstractions, no breaking public API.
-- The main implementation effort is in test updates (~35 `new SettingsManager(...)` call sites plus ~15 `loadSettings(...)` calls), all requiring an `agentDir` argument.
-- All test `describe` blocks that manipulate `PI_CODING_AGENT_DIR` env var can drop that scaffolding entirely, simplifying setup/teardown.
-- `saveSettings` has no SDK dependency and needs no signature change — only `loadSettings` calls `globalPath()`.
-
-## Stage: Implementation — TDD (2026-05-26T17:13:26Z)
-
-### Session summary
-
-Completed all 3 plan steps across 2 commits plus 1 doc commit.
-All 970 tests pass; `settings.ts` now has 0 Pi SDK imports and all `PI_CODING_AGENT_DIR` env var manipulation is gone from `settings.test.ts`.
-
-### Observations
-
-- **Steps 1+2 combined:** Changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` forced updating `SettingsManager.load()` in the same commit — they were inseparable (esbuild skips type checks, so the old call compiled but produced wrong runtime behavior).
-  The two production changes landed in one commit with a note in the body.
-- **Test simplification was significant:** Removed `originalAgentDirEnv` save/restore scaffolding from 5 `describe` blocks; the test code shrank by 32 lines net.
-- **`/nonexistent` sentinel:** Tests that construct `SettingsManager` but never call `load()` pass `agentDir: "/nonexistent"` — a clear signal the field is unused in that scope.
-- Architecture doc Step 5 heading marked `✓` and folded into the last `feat:` commit by `pi-autoformat`.
-
-## Stage: Final Retrospective (2026-05-26T17:22:11Z)
-
-### Session summary
-
-Issue #218 went from plan to shipped release (`pi-subagents-v7.8.0`) in a single continuous session.
-Planning, TDD (2 feat commits + 1 doc commit), shipping, CI verification, issue close, and release-please merge all completed without user intervention beyond stage transitions.
-
-### Observations
-
-#### What went well
-
-- **Clean mechanical execution:** The entire change was 2 production files (`settings.ts`, `index.ts`) and 1 test file, with zero unexpected test breakage and zero rework commits.
-- **Test simplification payoff:** Removing `PI_CODING_AGENT_DIR` env var scaffolding from 5 `describe` blocks shrank the test file by 32 lines net — a tangible improvement in test readability.
-- **Ship stage model efficiency:** The `/ship-issue` stage ran on `deepseek-v4-flash`, which was appropriate for the purely mechanical push/CI/close/merge workflow.
-
-#### What caused friction (agent side)
-
-1. `wrong-abstraction` — The plan split steps 1 and 2 into separate commits, but changing `loadSettings(cwd)` to `loadSettings(agentDir, cwd)` immediately broke `SettingsManager.load()` which calls it.
-   The agent recognized this during the red phase and combined them into one commit.
-   The existing testing skill rule ("When a TDD plan lists separate steps that share a type definition… fold them into one step") already covers this — the plan just didn't apply it.
-   Impact: added friction but no rework; recognized on first test run.
-2. `missing-context` — Attempted to add `| ✓ #218 |` as an extra column to one row of the architecture doc's findings table, creating a column-count mismatch.
-   The autoformatter reverted the broken table.
-   The agent then spent ~5 tool calls (`git show --stat`, `git status`, `grep` ×2, `read`) investigating what happened before switching to the Step 5 heading approach.
-   Impact: ~2 minutes of investigation; no rework beyond the heading edit.
-
-#### What caused friction (user side)
-
-- The user asked "Are we ready for shipping?"
-  which surfaced that the TDD retro stage notes were still uncommitted.
-  This was a useful checkpoint — the ship stage committed them before pushing.
-  Opportunity: the `/tdd-plan` prompt could commit retro notes as part of its final step, but the current flow (write notes, then commit in ship) is lightweight enough that enforcing it would add complexity for marginal gain.
-
-### Changes made
-
-1. Retro file updated at `packages/pi-subagents/docs/retro/0218-push-sdk-boundary-in-settings.md` — no other files changed.

package/docs/retro/0219-reduce-test-duplication-top-3-clone-families.md

@@ -1,64 +0,0 @@
----
-issue: 219
-issue_title: "Reduce test duplication — top 3 clone families (Phase 13, Step 6)"
----
-
-# Retro: #219 — Reduce test duplication — top 3 clone families
-
-## Stage: Planning (2026-05-26T20:00:00Z)
-
-### Session summary
-
-Analyzed duplication patterns in the three target test files (`agent-manager.test.ts`, `conversation-viewer.test.ts`, `agent-config-editor.test.ts`).
-Produced a 5-step TDD plan with shared `manager-stubs.ts` helper for runner/worktree factories, plus inline factories for the two UI test files.
-
-### Observations
-
-- The agent-manager test has the most diverse clone families (runner stubs, worktree stubs, run-result shapes) — these benefit from a shared helper file since the patterns are reused across 15+ describe blocks.
-- The conversation-viewer and config-editor duplication is more localized — inline factories within each test file are the right granularity to avoid over-extraction.
-- Gated runners (using `Promise.withResolvers`) were deliberately kept inline since they encode test-specific flow control that a factory would obscure.
-- Both dependencies (#214, #216) are closed, so the production code is stable and the tests won't shift under us during implementation.
-
-## Stage: Implementation — TDD (2026-05-26T17:42:41Z)
-
-### Session summary
-
-Completed all 4 TDD cycles: created `test/helpers/manager-stubs.ts` + `manager-stubs.test.ts` (13 smoke tests), migrated `agent-manager.test.ts`, `conversation-viewer.test.ts`, and `agent-config-editor.test.ts`.
-Test count delta: 970 → 983 (+13 from smoke tests).
-All 4 commits landed cleanly; full suite green at every step.
-
-### Observations
-
-- Target file line savings: `agent-manager.test.ts` −63, `conversation-viewer.test.ts` −58, `agent-config-editor.test.ts` −16; offset by +211 for the new helper files.
-  Net LOC is positive, but the _clone_ lines fallow detects are eliminated — the metric the issue targets.
-- The `createSessionRunner` + `createRunResult` chain required careful identity-check verification: `createRunResult(sess)` calls `toAgentSession(sess)` which casts without creating a new object, so `toBe(session)` assertions in the execution-state tests still pass. ✓
-- ESLint auto-fixed two cosmetic issues on commit (`activity = undefined` → `activity` destructuring, `session as unknown` cast removal) — caught by pre-commit hooks, not a problem in practice.
-- The `assertRenderFitsWidths` helper in `conversation-viewer.test.ts` reduced the 10 render-safety tests from ~8 lines each to 1–4 lines each; the `setupDetail` helper in `agent-config-editor.test.ts` eliminated 3 repeated setup lines per test across 18 `showAgentDetail` tests.
-
-## Stage: Final Retrospective (2026-05-26T17:50:31Z)
-
-### Session summary
-
-All three stages (planning, TDD, ship) completed in a single session with zero user corrections.
-Four TDD commits landed cleanly, CI passed on first push, issue #219 closed, and `pi-subagents-v7.8.1` released.
-
-### Observations
-
-#### What went well
-
-- Clean incremental verification: `pnpm vitest run <file>` ran after every code change, full suite at the end.
-  No regressions at any step.
-- The plan's decision to keep gated runners inline proved correct — tests with `Promise.withResolvers` flow control stayed readable without abstraction.
-- The `write` tool was the right choice for `conversation-viewer.test.ts` and `agent-config-editor.test.ts` (pervasive changes), while `edit` with 16 targeted replacements worked cleanly for `agent-manager.test.ts` (scattered but formulaic substitutions).
-- Ship stage used `deepseek-v4-flash` for purely mechanical CI/release steps — appropriate model-task alignment.
-
-#### What caused friction (agent side)
-
-- `other` — ESLint pre-commit hooks auto-fixed two cosmetic patterns (`activity = undefined` → bare destructuring; `session as unknown` cast removal), requiring re-stage + re-commit.
-  Impact: ~10 seconds per occurrence, no rework.
-  This is routine and inherent to the workflow.
-
-#### What caused friction (user side)
-
-- None observed.
-  The user's three-stage prompt chain (`/plan-issue` → `/tdd-plan` → `/ship-issue`) provided sufficient context at each stage with no manual intervention needed.

package/docs/retro/0227-evolve-agent-record-into-agent.md

@@ -1,80 +0,0 @@
----
-issue: 227
-issue_title: "Evolve AgentRecord into Agent with behavior (Phase 15, Step 1)"
----
-
-# Retro: #227 — Evolve AgentRecord into Agent with behavior
-
-## Stage: Planning (2026-05-27T12:00:00Z)
-
-### Session summary
-
-Produced an 8-step TDD plan to move per-agent behavior (`abort`, `queueSteer`/`flushPendingSteers`, `setupWorktree`) from `AgentManager` into `AgentRecord`, then rename `AgentRecord` → `Agent` across the codebase.
-The plan follows a "add behavior first, rename last" strategy to keep behavior diffs small and the rename commit purely mechanical.
-
-### Observations
-
-- `AgentRecord` is internal-only (public API is `SubagentRecord` in `service.ts`), so the rename is non-breaking.
-- The `queueSteer` method can be removed from `AgentManagerLike` and `SteerToolManager` interfaces entirely — both callers (`steer-tool`, `service-adapter`) already hold the agent reference from `getRecord()`, so they can call `agent.queueSteer()` directly.
-- Queue removal in `abort()` must stay on `AgentManager` until #230 extracts `ConcurrencyQueue`.
-- `RunHandle` ownership explicitly deferred to #228 — the plan does not touch `RunHandle` at all.
-- The rename step (step 7) touches ~30 files but is purely mechanical; all behavior changes land in steps 1–6.
-
-## Stage: Implementation — TDD (2026-05-27T13:00:00Z)
-
-### Session summary
-
-Completed all 8 TDD steps from the plan.
-Added 9 new tests (steer buffering, `abort()`, `setupWorktree()`) and migrated 977 existing tests to the renamed `Agent` class.
-Test count went from 977 to 986 across 62 test files.
-
-### Observations
-
-- Fallow reported `AgentInit` and `AgentStatus` as unused type exports from `types.ts`; suppressed with `// fallow-ignore-next-line unused-type` (correct singular form — tool's error message hints at this).
-- `ESLint` auto-removed an `as any` cast in the `setupWorktree` test (the mock `WorktreeManager` already satisfied the interface structurally); staged and re-committed cleanly.
-- Biome auto-formatted several test files during the rename commit; re-staged and re-committed.
-- Pre-completion reviewer returned **WARN** for 4 stale diagram/table references in `architecture.md` and the `package-pi-subagents` skill table; all fixed before the final commit.
-- No deviations from the plan's behavior design; the `queueSteer` removal from manager interfaces worked exactly as anticipated in the retro notes.
-
-## Stage: Final Retrospective (2026-05-27T17:22:00Z)
-
-### Session summary
-
-Completed all stages in a single session: planning, 8 TDD steps, pre-completion review, shipping, and release as `pi-subagents-v10.1.0`.
-Three behaviors (`abort`, steer buffering, worktree setup) moved from `AgentManager` to `Agent`, followed by a codebase-wide rename (33 files).
-
-### Observations
-
-#### What went well
-
-- The "add behavior first, rename last" strategy kept behavior-adding commits small (1–2 files each) and the rename commit purely mechanical.
-- Planning identified that `queueSteer` could be removed from `AgentManagerLike` and `SteerToolManager` entirely — this simplified the delegation step and eliminated an unnecessary indirection layer.
-- Pre-completion reviewer caught 4 stale Mermaid diagram references and a skill table entry that the plan's step 8 did not anticipate; all fixed before shipping.
-
-#### What caused friction (agent side)
-
-1. `scope-drift` — Added `AgentInit` and `AgentStatus` to the `types.ts` re-export barrel during the rename step without verifying any file imports them from that path.
-   Impact: fallow flagged dead code, triggering a 4-call suppression trial (`unused-export` → `unused-types` → `unused-type`), then the user identified the real fix (remove the speculative re-exports entirely), requiring a follow-up `fix:` commit after docs were already done.
-2. `missing-context` — During the mechanical rename (step 7), `sed` commands matched `#test/helpers/make-record` but missed the relative import `"./helpers/make-record"` in `conversation-viewer.test.ts`.
-   Impact: `pnpm run check` caught it in 1 tool call; minimal rework.
-3. `missing-context` — The fallow skill documents `unused-export` as a suppression kind but not `unused-type`.
-   Impact: 3 wrong guesses before the correct suppression syntax.
-   Self-identified after fallow's error message suggested the correct kind name.
-
-#### What caused friction (user side)
-
-- The user's question about whether the fallow suppressions could be removed in a future step was a valuable prompt — it surfaced that the re-exports were speculative and could be removed immediately.
-  Earlier intervention (e.g., during the TDD stage when the suppressions were added) would have avoided the `fix:` commit.
-
-### Diagnostic details
-
-- **Model-performance correlation** — Pre-completion reviewer ran as `pre-completion-reviewer` subagent (default model); appropriate for judgment-heavy work (doc staleness, code design review).
-  No model mismatches.
-- **Feedback-loop gap analysis** — `pnpm run check` was run after every delegation step (steps 2, 4, 6, 7) and after every behavior-adding step (steps 1, 3, 5).
-  Verification was incremental throughout, not deferred to the end.
-  The `conversation-viewer.test.ts` import miss in step 7 was caught immediately by the type checker.
-
-### Changes made
-
-1. `.pi/skills/fallow/SKILL.md` — Added `unused-type` suppression example alongside existing `unused-export` example.
-2. `AGENTS.md` — Added "no speculative re-exports" rule to Code Style section.

package/docs/retro/0228-async-start-agent-dissolve-run-handle.md

@@ -1,80 +0,0 @@
----
-issue: 228
-issue_title: "Convert startAgent to async/await, move run lifecycle to Agent (Phase 15, Step 2)"
----
-
-# Retro: #228 — Convert startAgent to async/await, move run lifecycle to Agent
-
-## Stage: Planning (2026-05-27T20:00:00Z)
-
-### Session summary
-
-Planned the async `startAgent` conversion and decided to dissolve `RunHandle` into Agent methods rather than moving it as a separate class.
-Identified three preparatory steps (narrow promise type, add Agent methods, hoist worktree setup) that make the final async conversion a minimal diff.
-
-### Observations
-
-- The original issue proposed `Agent.createRunHandle()` as a factory, keeping RunHandle as a separate class.
-  Analysis showed 5 of 6 RunHandle concerns are Agent state mutations — RunHandle is doing work that belongs on Agent.
-  The clincher was `resume()` in `agent-manager.ts`: it duplicates RunHandle's pattern manually, and #232 wants to unify them.
-  Dissolving RunHandle gives both `startAgent` and `resume` the same primitives (`completeRun`, `failRun`, `releaseListeners`).
-- The synchronous-throw contract in `spawn()` for worktree failures requires hoisting `record.setupWorktree()` out of `startAgent` before the async conversion.
-  Without this prep step, async `startAgent` would turn the throw into a rejected promise that `spawn()` doesn't catch.
-- `promise: Promise<string>` → `Promise<void>` is safe because the resolved string is dead — every consumer reads `record.result` instead.
-  Only one test assertion reads the resolved value.
-- `completeRun`/`failRun` take `worktrees: WorktreeManager` as a parameter rather than storing it on Agent (ISP — only needed at run end, exactly two callers).
-
-## Stage: Implementation — TDD (2026-05-27T20:40:00Z)
-
-### Session summary
-
-Implemented all 6 TDD steps: narrowed `promise` to `Promise<void>`, added 6 run lifecycle methods to Agent (+19 tests), replaced `RunHandle` with Agent methods (-85 LOC), hoisted worktree setup to callers, converted `startAgent` to async/await, and updated architecture docs.
-Test count: 986 → 1005.
-
-### Observations
-
-- Step 1 (promise narrowing) required fixing 3 additional test files not listed in the plan: `make-agent.test.ts`, `service-adapter.test.ts`, `get-result-tool.test.ts`.
-  All were trivial `Promise.resolve("done")` → `Promise.resolve()` changes and a cast removal.
-- The lift-and-shift approach worked cleanly — each of the 5 implementation commits was small and independently green.
-  The most impactful commit was step 3 (replace RunHandle, -96/+6 lines) which was risk-free because step 2 had already introduced the Agent methods.
-- Pre-completion reviewer returned WARN for stale `AgentRecord` and `run-handle.ts` references in `architecture.md` class diagram and layout listing.
-  These were pre-existing staleness from #227's rename that wasn't fully propagated to Mermaid diagrams.
-  Fixed by amending the docs commit.
-
-## Stage: Final Retrospective (2026-05-27T21:46:00Z)
-
-### Session summary
-
-Completed all stages (plan, TDD, ship, retro) in a single session.
-Dissolved `RunHandle` into 6 Agent methods, converted `startAgent` to async/await, released as `pi-subagents-v10.2.0`.
-Test delta: 986 → 1005 (+19).
-
-### Observations
-
-#### What went well
-
-- The user's two redirecting questions during planning ("What's the change that makes this easier?"
-  and "Tell me more about RunHandle — is there something that should replace it?") transformed a mechanical "move the class" plan into a "dissolve the abstraction" plan.
-  The dissolve approach is architecturally superior and sets up #232 (resume unification) for free.
-- The lift-and-shift decomposition (introduce Agent methods alongside `RunHandle`, then swap and delete) produced 5 independently-green commits.
-  The riskiest commit (step 3: delete `RunHandle`, -96/+6 lines) was trivially safe because step 2 had already proven the replacement methods.
-
-#### What caused friction (agent side)
-
-- `premature-convergence` — The agent planned around the issue's proposed `Agent.createRunHandle()` factory without questioning whether `RunHandle` should exist as a separate class.
-  The user had to ask two redirecting questions to push the analysis deeper.
-  Impact: plan was rewritten before commit (no wasted implementation), but the user spent two turns guiding analysis the agent should have done proactively.
-- `missing-context` — Plan step 1 (narrow `Promise<string>` to `Promise<void>`) listed only `agent-manager.test.ts` for updates but missed 3 additional test files (`make-agent.test.ts`, `service-adapter.test.ts`, `get-result-tool.test.ts`) that construct `Promise<string>` values.
-  The testing skill says "grep for all test files" for type changes — this was not applied during planning.
-  Impact: caught by `pnpm run check` in the same step, no rework.
-
-#### What caused friction (user side)
-
-- No friction observed.
-  The user's questioning style (asking "what does it do?
-  who needs it?"
-  rather than prescribing the solution) was collaborative and effective.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added relocation-dissolution heuristic: when an issue proposes moving a class, list callers and fields touched to check if it should be dissolved into the owner instead.

package/docs/retro/0229-agent-born-complete.md

@@ -1,89 +0,0 @@
----
-issue: 229
-issue_title: "Agent born complete: Agent.run() absorbs startAgent (Phase 15, Step 4)"
----
-
-# Retro: #229 — Agent born complete: Agent.run() absorbs startAgent
-
-## Stage: Planning (2026-05-27T18:00:00Z)
-
-### Session summary
-
-Produced a 9-step TDD plan for absorbing `AgentManager.startAgent()` into `Agent.run()`.
-Key design decisions: per-agent `AgentLifecycleObserver` interface passed at construction (chosen over callback fields and EventEmitter), and fully async worktree error surface (chosen over split sync/async).
-
-### Observations
-
-- **Observer pattern chosen over callbacks:** The per-agent `AgentLifecycleObserver` interface replaces three separate mechanisms (`onSessionCreated` callback, `setOnRunFinished`, `onCompact` callback).
-  All methods are optional, composed by `AgentManager.buildObserver()` per spawn.
-- **`ParentSessionInfo`/`CompactionInfo` relocation needed:** `agent.ts` importing from `agent-manager.ts` would create a circular type import (agent-manager already imports `Agent`).
-  Moving both types to `types.ts` in step 1 avoids the cycle.
-- **`AgentInit` grows wide (15+ optional fields):** Making run-config fields optional preserves backward compat for the 55+ `new Agent()` calls in tests.
-  Noted as a known smell — follow-up issues (#230 ConcurrencyQueue, potential `AgentInit` restructuring) may address this.
-- **Async error surface changes tool behavior:** `background-spawner.ts`'s try/catch around `manager.spawn()` becomes unreachable for worktree errors.
-  Keeping it for robustness; the error surfaces on `record.error` instead.
-- **Lift-and-shift TDD order:** Steps 3–5 incrementally change `AgentInit`, `setupWorktree`, and `completeRun`/`failRun` before step 6 adds `Agent.run()`.
-  This avoids a single massive step that rewrites everything at once.
-
-## Stage: Implementation — TDD (2026-05-28T01:00:00Z)
-
-### Session summary
-
-Completed all 9 TDD steps in 9 commits (plus 2 planning/retro docs commits).
-Test count went from 1005 to 1020 (+15 tests).
-`AgentManager.startAgent()`, `SpawnArgs`, and `onSessionCreated` callback are deleted.
-`Agent.run()` now owns the full execution lifecycle.
-
-### Observations
-
-- **Steps 7–8 merged in practice:** The tool-layer `onSessionCreated` → `observer` migration (step 8) had to be done alongside the `AgentSpawnConfig` change (step 7) because removing the `onSessionCreated` field broke compilation of `background-spawner.ts` and `foreground-runner.ts`.
-  This was expected — they share the same type.
-- **`setupWorktree` kept public:** The plan called for making it private in step 4, but it was kept public through step 6 since the manager still called it.
-  After step 7 (Agent.run() absorbs the call), it could be made private; left as a minor follow-up (reviewer flagged as WARN).
-- **`isBackground` removed from Agent storage:** The field was declared on `AgentInit` but Agent never reads it — the manager resolves `isBackground` before construction (setting initial status and composing the observer).
-  Biome flagged it as unused; removed from stored fields, kept on `AgentInit` for the manager's use.
-- **Worktree error surface confirmed async:** The `agent-manager.test.ts` test for synchronous worktree throw was rewritten to verify the error surfaces on `record.error` after awaiting the promise.
-  `background-spawner.ts` try/catch around `spawn()` retained for robustness.
-- **Pre-completion reviewer:** WARN — 3 non-blocking findings: `setupWorktree` not marked private, `isBackground` dead field on `AgentInit`, and `package-pi-subagents` SKILL.md Phase 15 description referencing deleted `startAgent`.
-
-## Stage: Final Retrospective (2026-05-28T01:30:00Z)
-
-### Session summary
-
-Planned, implemented (9 TDD steps), shipped, and released `pi-subagents-v11.0.0` in a single session spanning planning → TDD → ship → retro.
-Test count: 1005 → 1020 (+15).
-Also filed #249 (`pi-permission-system` bash external-directory gate bug) discovered during the pre-completion review.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift TDD strategy (steps 1–5 incrementally preparing, step 6 adding `Agent.run()`, step 7 rewriting `spawn()`) kept every commit compilable and green.
-  No step required backtracking.
-- The `ask-user` call during planning (observer pattern vs callbacks, sync vs async error surface) front-loaded design decisions that would have caused rework if deferred.
-- Pre-commit hooks caught both lint failures (`no-unnecessary-condition` on `abortController?.abort()`, `unbound-method` on observer forwarding) before they reached CI.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — The plan separated step 7 (remove `onSessionCreated` from `AgentSpawnConfig`) and step 8 (update tool-layer consumers) as distinct commits.
-  Removing the field immediately broke `background-spawner.ts` and `foreground-runner.ts` at compilation, forcing a merge.
-  Impact: added friction but no rework — the merge was straightforward since both files needed the same `onSessionCreated` → `observer` transformation.
-  Added a testing skill rule to catch this pattern in future plans.
-
-#### What caused friction (user side)
-
-- The pre-completion reviewer's Mermaid validation (`mmdc -o /tmp/mermaid-check.svg`) triggered a permission prompt from `pi-permission-system` despite `/tmp/*` being configured as `"allow"` in the global config.
-  This was a genuine bug (#249) in the bash external-directory gate, not a config mistake.
-  The prompt interrupted the automated review flow, requiring manual approval.
-
-### Diagnostic details
-
-- **Model-performance correlation** — Pre-completion reviewer ran on `claude-sonnet-4-6-20260526`; appropriate for judgment-heavy review work (code design, acceptance criteria, mermaid validation).
-  No mismatches detected.
-- **Feedback-loop gap analysis** — `pnpm run check` and `pnpm run test` were run after every TDD step commit, not just at the end.
-  `pnpm run lint` ran at the end (post-TDD checks) and at pre-push, which is correct since lint is slower and pre-commit hooks catch most issues incrementally.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — added TDD planning rule: when a step removes a field from a shared interface, all downstream readers must update in the same step.
-2. `packages/pi-subagents/docs/retro/0229-agent-born-complete.md` — appended Final Retrospective stage entry.

package/docs/retro/0230-extract-concurrency-queue.md

@@ -1,38 +0,0 @@
----
-issue: 230
-issue_title: "Extract ConcurrencyQueue from AgentManager (Phase 15, Step 5)"
----
-
-# Retro: #230 — Extract ConcurrencyQueue from AgentManager
-
-## Stage: Planning (2026-05-28T20:00:00Z)
-
-### Session summary
-
-Produced a 3-step TDD plan for extracting the scheduling concern (3 fields, 3 methods) from `AgentManager` into a new `ConcurrencyQueue` class.
-Both dependencies (#229 Agent.run(), #231 runner self-contained) are confirmed closed.
-
-### Observations
-
-- The issue's proposed API has `drain(start: (id: string) => void)` but also `markFinished()` as no-arg with "running--, drain()" semantics — a contradiction.
-  Resolved by storing the `startAgent` callback at construction, making both `drain()` and `markFinished()` no-arg.
-  This follows Tell-Don't-Ask and matches the established forward-reference-via-closure pattern already used for `onMaxConcurrentChanged`.
-- `markFinished()` auto-drain changes the ordering from "decrement → observer → drain" to "decrement + drain → observer."
-  Verified this is safe: observer notification only processes the completed agent and drain only starts promises without awaiting.
-- `SettingsManager` does not change — only the callback wiring in `index.ts` changes target from `manager.notifyConcurrencyChanged()` to `queue.drain()`.
-- The `agent.ts` `abort()` method has a comment referencing #230 that should be updated in the implementation step.
-
-## Stage: Implementation — TDD (2026-05-28T21:35:00Z)
-
-### Session summary
-
-Implemented all 3 TDD steps: (1) `ConcurrencyQueue` class + 22 unit tests, (2) migrated `AgentManager` to use injected `ConcurrencyQueue` and updated `index.ts` wiring + test helper, (3) architecture docs and SKILL.md updates.
-Test count delta: 1020 → 1042 (+22 new `ConcurrencyQueue` tests, 0 removed).
-
-### Observations
-
-- The `createManager` test helper required the forward-reference-via-closure pattern (`let mgr` then closure then assignment) with a `prefer-const` ESLint suppression — same pattern used in production `index.ts` for `onMaxConcurrentChanged`.
-- Pre-completion reviewer returned WARN for one stale comment (`drainQueue` reference in `waitForAll`) — fixed by amending the docs commit.
-- No plan deviations.
-  All module-level changes matched the plan exactly.
-- Pre-completion reviewer: WARN → fixed (stale comment).

package/docs/retro/0231-push-exec-registry-to-runner.md

@@ -1,71 +0,0 @@
----
-issue: 231
-issue_title: "Push exec/registry relay deps to runner construction (Phase 15, Step 3)"
----
-
-# Retro: #231 — Push exec/registry relay deps to runner construction
-
-## Stage: Planning (2026-05-27T21:53:10Z)
-
-### Session summary
-
-Produced a 6-step TDD plan to move `exec` and `registry` from `AgentManager` to `ConcreteAgentRunner` via a new `RunnerDeps` interface.
-The plan keeps `RunContext` (shrunk to 2 per-call fields) rather than dissolving it — #229 will likely dissolve it when `Agent.run()` calls the runner directly.
-
-### Observations
-
-- Confirmed `exec` and `registry` are pure relay deps on `AgentManager` — stored at construction, used only at lines 193–194 to forward into `runner.run()`.
-- Chose `RunnerDeps` bag over separate positional params on `ConcreteAgentRunner` and `runAgent()` — groups all three runner-owned deps (`io`, `exec`, `registry`) in one interface, and `runAgent()` stays at 5 parameters.
-- `AgentManagerOptions.registry` uses the concrete `AgentTypeRegistry` class; `RunContext.registry` uses the narrow `AgentConfigLookup` interface.
-  The new `RunnerDeps.registry` uses `AgentConfigLookup` (ISP).
-- Test churn is moderate (~20 `runAgent()` call sites change last param pattern) but mechanical — assertions stay identical.
-- Added a `createRunnerDeps()` test helper to `runner-io.ts` to reduce per-file boilerplate in runner tests.
-
-## Stage: Implementation — TDD (2026-05-27T22:05:32Z)
-
-### Session summary
-
-Implemented the 6-step plan in 4 commits (steps 3–5 merged).
-All 1005 tests pass; no test count change.
-Pre-completion reviewer returned PASS.
-
-### Observations
-
-- Plan steps 3, 4, and 5 could not be separate commits: removing `exec`/`registry` from `RunContext` (step 3) immediately caused TypeScript excess-property errors in `AgentManager` (step 4) and `index.ts` (step 5).
-  Merged all three into one commit.
-  The testing skill’s rule “when a TDD step changes an interface that has a single call site, the step must include updating that call site” applies.
-- Shrinking `RunContext` to all-optional fields made pre-existing `as never` casts in `test/helpers/manager-stubs.test.ts` unnecessary (eslint `no-unnecessary-type-assertion`).
-  Fixed as a lint cleanup in the doc commit.
-- The `sed`-based bulk replacement for `runAgent(..., io)` → `runAgent(..., { io, exec, registry: mockAgentLookup })` missed one multi-line call site (the `rejects.toThrow` test wrapping the call in `expect()`).
-  Caught immediately by the test run.
-
-## Stage: Final Retrospective (2026-05-27T22:43:52Z)
-
-### Session summary
-
-Shipped #231 cleanly: CI passed on first push, issue closed, release `pi-subagents-v10.2.1` published.
-The entire issue (plan → TDD → ship) completed in one sitting with no user intervention needed.
-
-### Observations
-
-#### What went well
-
-- The `RunnerDeps` design was unambiguous — the `ask_user` gate in planning correctly identified the one genuine design choice (`RunContext` fate) and got user input before proceeding.
-- Pre-completion reviewer returned PASS with zero findings, confirming the mechanical refactoring was clean.
-- Merging plan steps 3–5 during TDD was the right call; the testing skill rule about single-call-site interfaces caught the plan's error before any broken commit landed.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — The plan listed steps 3, 4, and 5 as separate commits and claimed "each commit is independently valid," but removing fields from `RunContext` (step 3) immediately caused TypeScript excess-property errors in `AgentManager` (step 4) and `index.ts` (step 5).
-  The existing `/plan-issue` rule (line 109) covers removing exports with single call sites, but did not trigger recognition because this was *shrinking* an interface, not removing one.
-  Impact: the TDD agent had to merge three steps on the fly — no rework, but the plan was misleading.
-- `missing-context` — The `sed`-based bulk replacement for `runAgent(..., io)` missed one multi-line call site where `}, io)` appeared on a different line than the opening `runAgent(`.
-  Impact: one extra manual edit; caught immediately by the test run.
-
-#### What caused friction (user side)
-
-- No friction observed — the user's involvement was limited to confirming the `RunContext` design choice during planning.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added a rule under TDD Order: when a step removes fields from an interface, include downstream object-literal call-site updates in the same step (TypeScript excess property checking).

package/docs/retro/0232-agent-resume-internal-observer-lifecycle.md

@@ -1,109 +0,0 @@
----
-issue: 232
-issue_title: "Agent.resume() with internal observer lifecycle (Phase 15, Step 6)"
----
-
-# Retro: #232 — Agent.resume() with internal observer lifecycle (Phase 15, Step 6)
-
-## Stage: Planning (2026-05-28T18:00:00Z)
-
-### Session summary
-
-Produced a 3-step plan to move the observer subscribe/use/release pattern out of `AgentManager.resume()` into a new `Agent.resume(prompt, signal?)`, mirroring the `run()` wiring added in #229.
-This is the last "manager reaches into Agent" duplication in the Phase 15 roadmap (Step 6, priority 8).
-Confirmed the prerequisite #229 is closed and `Agent` already holds `_runner`, `observer`, `attachObserver`/`releaseListeners`, and `resetForResume`.
-
-### Observations
-
-- Non-breaking (`feat:`) — `AgentManager.resume()` keeps its signature and `Agent | undefined` contract; `Agent.resume()` is additive.
-  No `ask_user` needed; the issue's proposed change is concrete and unambiguous.
-- Observer routing equivalence verified: old code wired `onCompact` → `AgentManagerObserver.onAgentCompacted`; new code routes through the per-agent `AgentLifecycleObserver.onCompacted`, which `buildObserver()` forwards to `onAgentCompacted`.
-  Net routing identical.
-- Abort semantics intentionally preserved — `signal` flows straight to `runner.resume({ signal })`, not through the agent's `abortController` (resume differs from `run()` here; flagged as a Non-Goal to avoid accidental behavior change).
-- Removing the `subscribeAgentObserver` import from `agent-manager.ts` must land in the same commit as the body rewrite (type checker flags the unused import). `grep` confirmed `agent.ts` remains the importer and `record-observer.ts` keeps the export live.
-- Discovered the `architecture.md` class diagram is stale from #229 (missing `Agent.run()`, stale `setupWorktree`/`completeRun`/`setOnRunFinished` signatures, old `resume(id, snapshot, exec)`).
-  Scoped only a light touch (resume-related entries + Step 6 ✅); full diagram refresh deferred as a follow-up.
-- Lift-and-shift TDD order: step 1 introduces `Agent.resume()` alongside the old manager logic; step 2 collapses the manager method and removes the import together.
-  Existing manager-level resume tests act as the integration safety net and stay.
-
-## Stage: Implementation — TDD (2026-05-28T19:00:00Z)
-
-### Session summary
-
-Completed all 3 TDD steps in 3 commits plus a bonus `fix:` commit, totalling 4 new commits.
-`Agent.resume()` added with full observer lifecycle, `AgentManager.resume()` collapsed to guard-plus-delegation, `subscribeAgentObserver` import removed from `agent-manager.ts`, and `architecture.md` updated.
-Test count: 1042 → 1053 (+11).
-
-### Observations
-
-- **Bonus fix found mid-session:** A user question revealed a listener leak introduced in #229 — `Agent.run()` called `wireSignal()` before `setupWorktree()`, but the worktree-failure catch block returned without `releaseListeners()`, leaving the parent `AbortSignal` holding a reference to the errored agent.
-  Fixed TDD-style: failing test first (`"releases the parent-signal listener when worktree setup fails"` in `agent.test.ts`), then one-line fix adding `this.releaseListeners()` to the catch block in `run()`.
-  Committed as a separate `fix:` commit with a body attributing the regression to #229.
-- **Pre-completion reviewer: WARN** — one non-blocking finding: the Phase 15 findings-summary table in `architecture.md` didn't mark the resolved rows (consistent pre-existing pattern from #229–#231).
-  Fixed by adding strikethrough + ✅ to all four resolved finding rows (#229 "Agent cannot run itself", #230 "Scheduling", #231 "exec/registry", #232 "resume()") in an additional `docs:` commit.
-  All other reviewer checks passed (Mermaid diagrams validated with `mmdc`, fallow clean, code design clean).
-- **Reviewer warning resolved:** The findings table gap was pre-existing across four issues; closing it in this commit makes the table accurate going into Phase 16.
-
-## Stage: Final Retrospective (2026-05-28T20:31:35Z)
-
-### Session summary
-
-Planned, implemented (3 TDD steps), fixed a latent #229 bug surfaced by a user question, shipped, and released `pi-subagents-v11.2.0` in a single continuous session.
-Test count: 1042 → 1053 (+11).
-The dominant friction was capturing the `pre-completion-reviewer`'s verdict: foreground subagent dispatch surfaced only the completion banner, not the report body, forcing several retrieval attempts and a near-miss where shipping began before a clean verdict existed.
-
-### Observations
-
-#### What went well
-
-- **User-prompted latent-bug discovery, fixed TDD-style.**
-  The user's question "did we introduce a bug in a prior issue?"
-  led to finding the `Agent.run()` abort-signal listener leak (regression from #229: `wireSignal()` ran before `setupWorktree()`, and the worktree-failure catch returned without `releaseListeners()`).
-  Fixed red→green: failing test `"releases the parent-signal listener when worktree setup fails"` first, then a one-line `releaseListeners()` addition.
-  The `fix:` commit body attributes the regression to #229 so release-please categorizes it correctly.
-- **Lift-and-shift plan executed without backtracking.**
-  Step 1 introduced `Agent.resume()` alongside the old manager logic; step 2 collapsed the manager method and removed the `subscribeAgentObserver` import together (type checker would reject splitting them).
-  Every commit stayed green.
-- **Incremental verification.** `pnpm run check` + targeted `vitest run` after each TDD step; full suite, lint, and `pnpm fallow dead-code` (from repo root) after the last step.
-
-#### What caused friction (agent side)
-
-- `other` (tooling) — Foreground `pre-completion-reviewer` dispatch returned only the completion banner (`Agent completed in Xs, N tool uses`), not the report body.
-  Two foreground dispatches yielded a truncated line and an empty body; `get_subagent_result` reported the foreground agent was "cleaned up"; `read_session` omits tool-result bodies.
-  Only a background dispatch retrieved via `get_subagent_result(wait: true, verbose: true)` surfaced the full PASS/WARN report.
-  Impact: ~5 wasted retrieval/re-dispatch tool calls and one long thrashing reviewer run (232 tool uses, with repeated `fatal: bad revision` git lookups) before a clean verdict.
-- `instruction-violation` (user-caught) — The `pre-completion` skill says "proceed to Summarize only after the reviewer returns PASS or WARN," but I began `/ship-issue` (pushed, started `ci_watch`) without ever cleanly capturing a verdict.
-  The user interrupted: "we should have verified our fix … can we try dispatching pre-completion again?"
-  Impact: aborted `ci_watch`, re-dispatched the review, then re-shipped — no incorrect release, but a redundant push/CI cycle.
-  Root cause is shared with the tooling friction above: because the verdict was never captured, the gate silently passed.
-
-#### What caused friction (user side)
-
-- The user's prior-issue-bug question was high-value strategic redirection — it surfaced a real defect the `pre-completion-reviewer` itself examined (`completeRun`/`failRun`/`abort`) but did not flag.
-  Opportunity: the reviewer's code-design lens could check resource-cleanup symmetry across all early-return paths, not just the happy/`failRun` paths.
-- The user caught the "shipped before verifying" gap that should have been the agent's own gate.
-  Framed as opportunity: a reliable verdict-capture step removes the need for this manual oversight.
-
-### Diagnostic details
-
-- **Model-performance correlation** — The `pre-completion-reviewer` ran on `claude-sonnet-4-6`; appropriate for judgment-heavy review (code design, acceptance criteria, Mermaid validation).
-  No mismatch.
-  Note: the first (truncated) run used 232 tool calls vs 26 for the clean run — the long run thrashed on failed `git rev-parse` lookups of abbreviated SHAs.
-- **Escalation-delay tracking** — The verdict-capture rabbit hole ran >5 consecutive tool calls (foreground re-dispatch → `get_subagent_result` → `read_session` → background dispatch) before the background+verbose approach worked.
-  Switching to background dispatch after the first truncation would have resolved it immediately.
-- **Feedback-loop gap analysis** — No gap: verification ran incrementally after each TDD step, and `fallow` ran from the repo root (not a package subdir), matching CI.
-
-### Changes made
-
-1. `.pi/skills/pre-completion/SKILL.md` — added a Step 3 guard (P2, safety net): a missing `Overall: PASS|WARN|FAIL` line is treated as "report not captured" and triggers a re-dispatch; do not proceed to "Summarize" on a banner-only result.
-2. `.pi/agents/pre-completion-reviewer.md` — reviewer-side durable fix: (a) the final message must be the report block ending with `### Overall`, never a trailing tool call; (b) thrash guard — use the dispatcher-provided base tag and modified-files list, do not retry `git rev-parse` on abbreviated SHAs.
-3. Proposal P1 (background dispatch + verbose retrieval) was presented but **not** adopted; with the reviewer's output contract fixed, foreground dispatch should return the report directly.
-   Recorded as a fallback if banner-only foreground results recur.
-
-### Root-cause follow-up: reviewer verdict-capture failure
-
-After the initial retro commit we examined *why* foreground dispatches returned only a banner.
-Ruled out the #229 abort-signal leak: it only fires on `isolation: "worktree"` setup failure (never exercised by the reviewer dispatches, which used no worktree), and a leaked listener cannot truncate a healthy agent's output — wrong code path and wrong symptom.
-The `/reload` after the fix is a confounder (it clears in-session state) but does not implicate the leak itself.
-Best explanation (≈70% confidence): the reviewer ended long, thrashing runs (232 tool calls, repeated `fatal: bad revision` lookups) *on tool activity rather than a final report*, so foreground returned the last text it saw.
-Note: the running extension loads `../packages/pi-subagents` from this working tree (per `.pi/settings.json`), so source edits take effect after `/reload` — an earlier claim that the session ran an installed build was wrong.