@gotgenes/pi-subagents 18.0.0 → 18.0.2

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.

package/docs/retro/0237-remove-disallowed-tools.md

@@ -1,78 +0,0 @@
----
-issue: 237
-issue_title: "Remove disallowed_tools from pi-subagents (Phase 14, Step 1)"
----
-
-# Retro: #237 — Remove disallowed_tools from pi-subagents
-
-## Stage: Planning (2026-05-27T00:52:26Z)
-
-### Session summary
-
-Produced a 6-step TDD plan to remove `disallowedTools` from `AgentConfig`, `disallowedSet` from `ToolFilterConfig`, and all parsing/serialization/UI/test code that references them.
-The plan covers 7 source files, 4 test files, README, and the architecture doc.
-
-### Observations
-
-- The issue label `pkg:pi-permission-system` was incorrect — all target files live in `packages/pi-subagents`.
-  Confirmed with the user that the plan targets pi-subagents.
-- The README still references `disallowed_tools` in the context of memory write-capability detection, but memory was already removed in #185.
-  The plan treats this as a stale reference to clean up.
-- After removing `disallowedSet`, the `filterActiveTools` `extensions === false` branch simplifies to a trivial passthrough (`return activeTools`), and both guard conditions at the call sites drop the `|| cfg.toolFilter.disallowedSet` arm.
-  This leaves the function in the exact shape that Step 3 (#239) expects.
-- The plan orders steps to follow the type dependency chain: `AgentConfig` first (surfaces all downstream errors), then `ToolFilterConfig`, then `filterActiveTools`, then UI, then docs.
-
-## Stage: Implementation — TDD (2026-05-27T00:59:19Z)
-
-### Session summary
-
-All 6 TDD steps completed in one session, producing 7 commits (6 planned + 1 fixup for dead code).
-Test count dropped from 983 to 978 (5 tests removed: 2 from `custom-agents.test.ts`, 1 from `session-config.test.ts`, 2 from `agent-runner-extension-tools.test.ts` after renaming one deleted test into a retained form).
-All checks (type check, lint, fallow dead-code gate) pass clean.
-
-### Observations
-
-- `csvListOptional` in `custom-agents.ts` was left dead after removing the `disallowedTools` parsing call; Biome flagged it as unused.
-  Removed as a separate `refactor:` commit since it couldn't be amended into the `feat!:` commit (later commits already on top of it).
-- One of the three deleted `agent-runner-extension-tools.test.ts` denylist tests ("extensions: false with no disallowedTools skips the filter") was reformulated into a new test ("extensions: false skips the filter entirely") rather than simply deleted, because it covers genuinely different behavior after the simplification: `extensions: false` now always skips the filter, not just when no denylist is present.
-  This adds coverage for the simplified code path.
-- The `filterActiveTools` `extensions === false` branch simplified from "apply denylist to built-in tools" to `return activeTools`, exactly as the plan specified.
-  Both guard conditions at the call sites simplified to `cfg.toolFilter.extensions !== false`.
-- No deviations from the plan's module-level changes list; all 7 source files and 4 test files were touched as specified.
-
-## Stage: Final Retrospective (2026-05-27T01:12:34Z)
-
-### Session summary
-
-Three-stage lifecycle (planning → TDD → ship) completed in one session for Phase 14, Step 1.
-All 6 TDD steps landed in 7 commits (6 planned + 1 fixup for dead `csvListOptional`).
-Test count: 983 → 978 (−5).
-Released as `pi-subagents-v8.0.0` (major bump from the `feat!:` breaking change).
-
-### Observations
-
-#### What went well
-
-- The plan's type-dependency-chain ordering (AgentConfig → ToolFilterConfig → `filterActiveTools` → UI → docs) meant each step produced the exact downstream type errors expected for the next step, with zero surprises.
-  This ordering pattern is worth preserving for future removal issues.
-- Incremental verification ran after every step: `pnpm run check` after type changes, `pnpm vitest run <file>` after logic changes, full suite + lint + fallow at the end.
-  No regressions discovered at the final sweep.
-- The reformulation of one deleted test into "extensions: false skips the filter entirely" added coverage for the simplified code path rather than just deleting it.
-  Good judgment call during implementation.
-
-#### What caused friction (agent side)
-
-- `missing-context` — The plan said "remove `disallowedTools: csvListOptional(fm.disallowed_tools)`" from `custom-agents.ts` but did not check whether `csvListOptional` had other callers.
-  It was the sole call site, so the function became dead code.
-  Biome caught it at the final lint sweep, requiring a separate `refactor:` commit (`f1ee7c1`).
-  Impact: one unplanned commit; no rework but added friction.
-  Self-identified at final lint.
-  Root cause: the `plan-issue.md` template had a rule for grepping removed *exports* but not for checking private-function orphans.
-
-#### What caused friction (user side)
-
-- No friction observed — the user's involvement was limited to confirming the target package (pi-subagents vs pi-permission-system) during planning, which was an appropriate clarification given the incorrect `pkg:` label on the issue.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — Added rule: when a step removes a call to a private function, grep the file for other callers and list the function for removal if the removed call was the sole call site.

package/docs/retro/0238-remove-extensions-filtering.md

@@ -1,72 +0,0 @@
----
-issue: 238
-issue_title: "Remove extensions filtering from pi-subagents (Phase 14, Step 2)"
----
-
-# Retro: #238 — Remove extensions filtering from pi-subagents
-
-## Stage: Planning (2026-05-27T01:31:01Z)
-
-### Session summary
-
-Produced a 6-step TDD plan for narrowing `extensions` from `true | string[] | false` to `boolean` across `AgentConfig`, `ToolFilterConfig`, `filterActiveTools`, custom agent frontmatter parsing, UI serialization, and tests.
-The plan mirrors the structure of the completed #237 plan (Step 1 of Phase 14) and explicitly defers `filterActiveTools` collapse to #239.
-
-### Observations
-
-- The `pkg:pi-permission-system` label on this issue is intentional context (pi-permission-system becomes the sole tool-policy authority) but all code changes are in pi-subagents.
-- The `inheritField()` helper is shared between `extensions` and `skills` parsing — it cannot be simplified since `skills` still supports `string[]`.
-  The plan coerces at the call site instead.
-- After removing the `Array.isArray(extensions)` branch, the `builtinToolNameSet.has(t)` check in `filterActiveTools` becomes logically redundant (both branches return `true`), but simplifying further is #239's scope.
-- Only 2 tests are removed and 3 updated; the boolean paths (`true`/`false`) are well-covered and unchanged.
-
-## Stage: Implementation — TDD (2026-05-27T01:39:43Z)
-
-### Session summary
-
-All 6 TDD steps completed across 6 commits.
-Test count went from 978 to 977 (net −1: 2 removed, 1 added for the deprecation warning).
-Full suite: 62 files, 977 tests, all passing; type check and lint clean.
-
-### Observations
-
-- **Plan deviation — step consolidation**: The type narrowing in step 1 caused immediate `tsc` errors in test files that the plan assigned to steps 2–4 (the `string[]`-specific tests in `agent-runner-extension-tools.test.ts`, `session-config.test.ts`, and `agent-config-editor.test.ts`).
-  All test fixes were folded into the step 1 commit to keep the build green at every commit.
-  Steps 2–4 became purely production-code changes.
-- **Plan deviation — deprecation warning**: The plan said to use `debugLog` for the deprecation warning, but `debugLog` is debug-only (requires `PI_SUBAGENTS_DEBUG=1`) and its signature requires an error object as the second argument. `console.warn` was used instead, which is user-visible without special env vars and testable with `vi.spyOn`.
-- **ESLint auto-fix in step 2**: ESLint rewrote `extensions === false` to `!extensions` and `cfg.toolFilter.extensions === false` to `!cfg.toolFilter.extensions` after the type narrowed to `boolean`.
-  Both are semantically identical; the changes were staged and included in the same commit.
-- The `resolveBoolExtensions` helper in `custom-agents.ts` is a clean seam — if `skills` is ever also simplified to `boolean`, the same pattern applies.
-
-## Stage: Final Retrospective (2026-05-27T01:48:04Z)
-
-### Session summary
-
-All three stages (planning, TDD, shipping) completed in a single continuous session.
-Six implementation commits landed as `pi-subagents-v9.0.0` (major bump from `feat!:`).
-Issue #238 closed; unblocks #239 (collapse `filterActiveTools`).
-
-### Observations
-
-#### What went well
-
-- The plan’s structure closely followed the successful #237 pattern, making execution predictable.
-- The implementer caught the type-narrowing cascade on the first `pnpm run check` and adapted immediately — no user intervention needed.
-- The `resolveBoolExtensions` helper extraction was a clean design choice that keeps `inheritField` reusable for `skills`.
-- ESLint auto-fix of `=== false` → `!` after the type narrowed to `boolean` was handled smoothly within the same commit.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` (self-identified) — The planner did not apply the testing skill’s existing rule: “When a TDD plan lists separate steps that share a type definition, changing that type in step N breaks steps N+1…N+k.”
-  The plan assigned test-fixture fixes (removing `extensions: string[]` values) to steps 2–4, but the type change in step 1 broke them all immediately.
-  Impact: no rework — the implementer folded fixes into step 1 — but the plan’s step boundaries were misleading.
-- `missing-context` — The plan recommended `debugLog` for the deprecation warning without checking its function signature (`(context: string, err: unknown)`) or its debug-only behavior.
-  Impact: minor — switched to `console.warn` during implementation with no rework, but the plan was wrong.
-
-#### What caused friction (user side)
-
-- Nothing notable — no user corrections were needed across all three stages.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — Added type-narrowing-specific TDD planning rule: when a step narrows a union type, grep test files for fixtures using the removed variant and fold those fixes into the same step.