@gotgenes/pi-subagents 18.0.1 → 18.0.2

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.

package/docs/retro/0239-collapse-filter-active-tools.md

@@ -1,70 +0,0 @@
----
-issue: 239
-issue_title: "Collapse filterActiveTools to recursion guard (Phase 14, Step 3)"
----
-
-# Retro: #239 — Collapse filterActiveTools to recursion guard
-
-## Stage: Planning (2026-05-27T20:00:00Z)
-
-### Session summary
-
-Produced a 3-step TDD plan to flatten `SessionConfig.toolFilter` into top-level `toolNames` and `extensions` fields, simplify `filterActiveTools` to a one-liner recursion guard, remove the pre-bind filter call, and update architecture docs.
-Both dependencies (#237, #238) are confirmed closed.
-
-### Observations
-
-- The `builtinToolNameSet` membership check in `filterActiveTools` is fully dead code — both branches return `true` after #238 removed the `string[]` extensions path.
-- `ToolFilterConfig` is only imported by `agent-runner.ts` and never referenced in test files, so deletion is clean.
-- The pre-bind filter call is safe to remove because `EXCLUDED_TOOL_NAMES` tools (`subagent`, `get_subagent_result`, `steer_subagent`) are registered by this extension during `bindExtensions`, not before — they cannot appear in the pre-bind active set.
-- The `agent-runner-extension-tools.test.ts` file has 4 tests; 1 becomes structurally impossible (pre-bind/post-bind ordering) and the remaining 3 need assertion index adjustments (`calls[1]` → `calls[0]`).
-- `SessionConfig` is internal-only (not package-exported), so flattening has no external API impact.
-
-## Stage: Implementation — TDD (2026-05-27T22:00:00Z)
-
-### Session summary
-
-Completed all 3 TDD cycles: (1) flattened `SessionConfig` and deleted `ToolFilterConfig`, (2) simplified `filterActiveTools` to a one-liner and removed the pre-bind filter call, (3) updated architecture docs to mark Phase 14 Step 3 complete.
-Test count held at 977 (no net change — the extension-tools test file was rewritten, removing 1 test and updating 3 others while keeping the same total count).
-A follow-up skill maintenance commit updated `.pi/skills/package-pi-subagents/SKILL.md` to remove stale Patch 2 references.
-
-### Observations
-
-- The plan's step order (SessionConfig first → expected compile errors in `agent-runner.ts` → green after runner update) worked exactly as designed with no surprises.
-- `agent-runner.test.ts` needed no changes — the default test config has `extensions: false`, so the filter call never ran in those tests.
-- Pre-completion reviewer returned **WARN** for stale `package-pi-subagents` skill content: the "Patch 2 scheduled for removal" note and the `// Patch 2 (RepOne` grep instruction were both stale after #239 completion.
-  Fixed immediately as a follow-up `docs:` commit before writing retro notes.
-- `pnpm fallow dead-code` passed with 0 issues — no orphaned exports left behind.
-
-## Stage: Final Retrospective (2026-05-27T14:40:00Z)
-
-### Session summary
-
-Completed the full issue lifecycle (plan → TDD → ship → retro) in a single continuous session.
-Issue #239 shipped as `pi-subagents-v10.0.1` with 7 commits (2 refactor, 4 docs, 1 release).
-Phase 14 is now fully complete, unblocking Phase 15 (#227–#232).
-
-### Observations
-
-#### What went well
-
-- The plan's type-dependency-chain ordering (`SessionConfig` first → expected compile errors → `agent-runner.ts` resolves them) produced zero surprises during TDD.
-  Each step's red/green boundary was exactly where the plan predicted.
-- Pre-completion reviewer caught stale `package-pi-subagents` skill content ("Patch 2 scheduled for removal" and a `// Patch 2 (RepOne` grep instruction) that no longer matched source.
-  Fixed before shipping — the reviewer earned its keep.
-- Multi-model routing was well-matched: `claude-sonnet-4-6` for planning and TDD (judgment + code), `deepseek-v4-flash` for shipping (mechanical checklist), `claude-opus-4-6` for retrospective (synthesis).
-- Feedback loops were incremental: `pnpm vitest run` after each test change, `pnpm run check` after Step 1 to confirm expected errors, full suite + lint + dead-code after all steps.
-
-#### What caused friction (agent side)
-
-No friction points identified.
-This was the final step of a 3-step phase with both dependencies already closed, a well-scoped plan, and internal-only API changes — the simplest possible lifecycle.
-
-#### What caused friction (user side)
-
-None observed.
-The user's involvement was limited to issuing the four standard lifecycle commands (`/plan-issue`, `/tdd-plan`, `/ship-issue`, `/retro`) with no corrections or redirections needed.
-
-### Changes made
-
-1. Appended Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0239-collapse-filter-active-tools.md`.

package/docs/retro/0242-rename-agent-tool-to-subagent.md

@@ -1,82 +0,0 @@
----
-issue: 242
-issue_title: "Rename `Agent` tool to `subagent`"
----
-
-# Retro: #242 — Rename `Agent` tool to `subagent`
-
-## Stage: Planning (2026-05-27T13:45:29Z)
-
-### Session summary
-
-Produced a plan for renaming the `Agent` tool to `subagent` across pi-subagents source, tests, README, and architecture docs.
-Verified that pi-permission-system docs do not reference the `Agent` tool name and require no changes.
-Scoped the plan to two commits: one `feat!:` for source + tests, one `docs:` for documentation.
-
-### Observations
-
-- The general-purpose agent type's `displayName` (`"Agent"` in `default-agents.ts` and `agent-types.ts` fallback) is a separate concept from the tool name and stays unchanged.
-  Several test files assert this `displayName` — they are not affected by the rename.
-- Issue #239 (Step 3, collapse `filterActiveTools`) is still open but independent — #242 only changes the string value in `EXCLUDED_TOOL_NAMES`, not its structure.
-- The architecture doc already contains `(née \`Agent\`)` in the "What the core owns" section, anticipating the rename.
-- The `widget-renderer.test.ts` comment references `"Agent"` as the general-purpose display name, not the tool name — only the comment text needs updating for clarity.
-
-## Stage: Implementation — TDD (2026-05-27T13:55:33Z)
-
-### Session summary
-
-Completed 2 TDD cycles: one `feat!:` commit renaming the tool in source + tests, one `docs:` commit updating `README.md` and `docs/architecture/architecture.md`.
-Baseline was 977 tests; test count unchanged at 977 after the changes.
-Pre-completion reviewer returned **PASS**.
-
-### Observations
-
-- All changes were pure string-literal replacements in 2 source files, 4 test files, `README.md`, and the architecture doc — no logic, type, or structural changes.
-- The general-purpose agent type's `displayName: "Agent"` in `default-agents.ts` and `agent-types.ts` fallback was correctly left unchanged; `display.test.ts` still passes with `"Agent"`.
-- The description body inside the `agent-tool.ts` template literal needed separate edits because the guideline lines are not tab-indented (inside a backtick template literal, tab indentation does not apply).
-- Pre-completion reviewer: PASS — all deterministic checks, conventional commits, documentation, code design, tests, Mermaid diagrams, and dead-code gate all passed.
-
-## Stage: Final Retrospective (2026-05-27T14:07:32Z)
-
-### Session summary
-
-Completed the full plan→TDD→ship→retro lifecycle for #242 in a single session.
-Released as `pi-subagents-v10.0.0` (major bump from `feat!:` breaking change).
-Found and fixed one stale `Agent` tool reference in `.pi/skills/pre-completion/SKILL.md`.
-
-### Observations
-
-#### What went well
-
-- Three-model pipeline (opus for planning, sonnet for TDD, deepseek-flash for shipping) matched task complexity to model capability with no quality issues.
-- The plan's distinction between tool name (`"Agent"`) and agent-type `displayName` (`"Agent"`) prevented false-positive test updates — 8 test files reference `"Agent"` but only 4 needed changes.
-- Pre-completion reviewer caught no issues (PASS), confirming thorough planning.
-
-#### What caused friction (agent side)
-
-1. `missing-context` — Two failed `Edit` calls on `agent-tool.ts` line 175: the template literal's guideline lines have no tab indentation, but the agent initially assumed tab depth from the surrounding function.
-   Impact: 3 extra tool calls (grep to inspect actual indentation, then successful edit); no rework.
-   Self-identified.
-2. `wrong-abstraction` — Retro file edit duplicated Planning observations into the TDD stage because the `Edit` `oldText` matched from the Observations heading and the replacement included both old and new content.
-   Impact: 2 extra tool calls (read file, full `write` to fix); no rework.
-   Self-identified.
-3. `missing-context` — `.pi/skills/pre-completion/SKILL.md` line 32 references the `Agent` tool by name but was not in the plan's scope.
-   The plan checked pi-permission-system docs, `README.md`, and architecture docs but did not grep skill files for the old tool name.
-   Impact: discovered during retro; fixed as a retro change.
-
-#### What caused friction (user side)
-
-- None — the full pipeline ran with zero user corrections.
-
-### Diagnostic details
-
-- **Model-performance correlation** — Pre-completion reviewer ran as a default-model subagent (292.7s, 36 tool uses, 63.9k tokens).
-  Appropriate for the judgment-heavy review task.
-  Ship stage on `deepseek-v4-flash` was notably efficient for purely mechanical work.
-- **Feedback-loop gap analysis** — Verification was incremental: baseline check before TDD, per-file tests after Red and Green phases, full suite after implementation, then check + lint + fallow.
-  No gaps.
-
-### Changes made
-
-1. `.pi/skills/pre-completion/SKILL.md` — updated stale `Agent` tool reference to `subagent` on line 32.
-2. `.pi/agents/pre-completion-reviewer.md` — added rename-grep heuristic to the Skills bullet under Forward documentation checks: "When the change renames a symbol, grep `.pi/skills/` and `.pi/prompts/` for the old name."

package/docs/retro/0256-extract-worktree-isolation.md

@@ -1,89 +0,0 @@
----
-issue: 256
-issue_title: "Extract WorktreeIsolation collaborator"
----
-
-# Retro: #256 — Extract WorktreeIsolation collaborator
-
-## Stage: Planning (2026-05-28T23:44:23Z)
-
-### Session summary
-
-Produced a numbered implementation plan for extracting a `WorktreeIsolation` collaborator (Phase 16, Step 1) that owns the worktree lifecycle (`setup`, `path`, `cleanup`) so `Agent` tells one collaborator instead of orchestrating `_worktrees` + `_isolation` + `worktreeState` itself.
-The plan covers the new module, `Agent`/`AgentManager`/`service-adapter` wiring, the `WorktreeState` deletion, doc updates, and a 4-cycle TDD order.
-
-### Observations
-
-- Decision: fold `WorktreeState` into `WorktreeIsolation` (delete `worktree-state.ts`) rather than wrap it.
-  The architecture target table already lists `WorktreeIsolation` as absorbing `worktrees` + `isolation` + `worktreeState`, and the user confirmed a fold preference when the doc had already decided it.
-- `WorktreeManager.cleanup(wt, ...)` mutates `wt.branch` in place; `WorktreeIsolation` must store a mutable `WorktreeInfo` (`_info`) to preserve that behavior — flagged as the top risk.
-- `AgentInit` net field change is −1 (removes `worktrees` + `isolation`, adds `worktree`), not −2 as the issue text loosely states; instance fields drop by 2 and `setupWorktree()` is removed.
-- The `missing worktrees dependency` defensive branch becomes structurally impossible (collaborator is only built with a manager) and is dropped.
-- Verified no consumer imports the `WorktreeCleanupResult`/`WorktreeInfo` re-exports from `worktree-state.ts` — they all import from `worktree.ts`, so deletion is safe.
-- Step 2 (the integration) is a single commit because the type checker forbids removing `AgentInit` fields while call sites still pass them; bulk of `agent.test.ts` is untouched, only worktree helpers/describe blocks change.
-- Doc updates needed: architecture class diagram + layout listing, and the package `SKILL.md` Lifecycle domain row (module count stays 9).
-- This step is independent of Step 2 (#257, `ChildSessionFactory`) per the architecture's Track A.
-
-## Stage: Implementation — TDD (2026-05-29T00:01:54Z)
-
-### Session summary
-
-Implemented all 4 planned TDD cycles: added `WorktreeIsolation` + unit tests, wired it into `Agent`/`AgentManager`/`service-adapter` (removing `_worktrees`/`_isolation`/`worktreeState`/`setupWorktree()`), deleted the folded `WorktreeState` class and its test, and updated the architecture doc + package skill.
-Full suite green at 1047 tests (baseline 1053; +7 new `worktree-isolation` tests, −4 removed `setupWorktree` tests, −9 removed `worktree-state` tests); `check`, `lint`, and `fallow dead-code` all clean.
-
-### Observations
-
-- One pre-existing baseline failure: `rumdl` flagged 5 orphaned issue link definitions (`[#227]`–`[#232]`, minus the still-used `[#231]`) in `architecture.md`, introduced by an earlier Phase 15 archive commit.
-  Fixed as a separate `docs:` cleanup commit before starting TDD to establish a green baseline.
-- Deviation from a literal 1:1 test mapping: `WorktreeIsolation` deliberately exposes `path` + `cleanupResult` but no `branch` getter (branch is an internal `_info` detail surfaced via `cleanupResult`).
-  The two `agent-manager.test.ts` tests that asserted `worktreeState.branch` now assert `record.worktree?.path` and `record.worktree?.cleanupResult`.
-  Noted in the Step 2 commit body.
-- `Agent.worktree` is `readonly` (set at construction), unlike the old mutable public `worktreeState` field.
-  Tests that previously mutated `record.worktreeState = new WorktreeState(...)` after construction were reworked to pass a pre-`setup()` `WorktreeIsolation` via the constructor (`createSetUpWorktree` helper in `agent.test.ts`; `setUpWorktree` helper in `service-adapter.test.ts`).
-- `createTestAgent` spreads `init` into the `Agent` constructor, so injecting `worktree` needed no helper change.
-- The Step 2 integration landed cleanly in a single commit as the plan predicted; the type checker pinpointed every stale call site.
-- Pre-completion reviewer: PASS (all deterministic checks, acceptance criteria, conventional commits, docs, code design, test artifacts, Mermaid, and dead-code gates green).
-
-## Stage: Final Retrospective (2026-05-29T00:18:13Z)
-
-### Session summary
-
-Shipped #256 end-to-end across one continuous session: planning → 4-cycle TDD → ship.
-The `WorktreeIsolation` collaborator landed, `WorktreeState` was folded in and deleted, the suite stayed green (1047 tests), the pre-completion reviewer returned PASS on first dispatch, CI passed, and `pi-subagents-v11.3.0` released cleanly.
-The session was notably low-friction; the only judgment calls were a pre-existing baseline lint failure and a fold-vs-wrap confirmation.
-
-### Observations
-
-#### What went well
-
-- The planning-stage lift-and-shift analysis precisely predicted the TDD shape: Step 2 was a single forced commit (the type checker rejects removing `AgentInit` fields while call sites still pass them), and `tsc` pinpointed every stale call site exactly as planned.
-  Zero TDD surprises followed from an accurate plan.
-- The fold decision (delete `WorktreeState`, store a mutable `WorktreeInfo` in `WorktreeIsolation`) preserved the in-place `branch` mutation that `WorktreeManager.cleanup` relies on — the top planning risk never materialized because it was designed around up front.
-- Pre-completion reviewer returned a clean PASS on first dispatch with no findings.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` (self-identified) — the `tdd-plan` "Verify green baseline" step says "stop and report" on any failed check, but the baseline `pnpm run lint` failed on 5 pre-existing orphaned issue-link definitions in `architecture.md` (from an earlier Phase 15 archive commit).
-  I fixed them as a separate `docs:` cleanup commit and proceeded rather than stopping.
-  This was the pragmatic call and matches the end-of-session rule ("Fix all failures — including pre-existing ones"), but the two prompt sections give opposite guidance for pre-existing failures.
-  Impact: no rework; one momentary judgment call against a contradictory prompt.
-- `missing-context` (user-caught) — in planning I posed the fold-vs-wrap choice to the user via `ask_user`, and the user responded by asking whether the architecture doc had already decided it.
-  The Phase 16 target table I had read already lists `WorktreeIsolation` as absorbing `worktreeState`, so the answer was partly in the doc.
-  Impact: one extra round-trip, no rework; confirming was still defensible since the issue body only mentioned losing 2 fields.
-
-#### What caused friction (user side)
-
-- None notable.
-  User involvement was a single low-cost confirmation; the rest was strategic delegation.
-
-### Diagnostic details
-
-- **Model-performance correlation** — the only subagent dispatch was the `pre-completion-reviewer`, running on `claude-sonnet-4-6-20260526` (declared in `.pi/agents/pre-completion-reviewer.md`).
-  Appropriate: judgment-heavy review work on a capable model, read-only tools.
-- **Escalation-delay tracking** — no `rabbit-hole` friction; the baseline lint was diagnosed and fixed in 3 tool calls (investigate refs → edit → re-lint).
-- **Feedback-loop gap analysis** — verification ran incrementally: `pnpm vitest run <file>` after each red and green phase, `pnpm run check` after the interface change, full suite + `fallow dead-code` from repo root before shipping.
-  No end-loaded verification gap.
-
-### Changes made
-
-1. `.pi/prompts/tdd-plan.md` — reconciled the "Verify green baseline" section with the end-of-session "fix pre-existing failures" rule: trivial pre-existing failures on untouched files may be fixed as a separate cleanup commit to establish a green baseline; non-trivial or unexplained failures still stop and report.

package/docs/retro/0257-extract-child-session-factory.md

@@ -1,33 +0,0 @@
----
-issue: 257
-issue_title: "Extract ChildSessionFactory from runner"
----
-
-# Retro: #257 — Extract ChildSessionFactory from runner
-
-> Superseded — #257 closed `not_planned`; the work was reframed as Phase 16 "invert dependencies" ([ADR-0002], issues #261–#265).
-
-## Stage: Planning (2026-05-29T00:32:12Z)
-
-### Session summary
-
-Produced the implementation plan for Phase 16, Step 2 — extracting session *creation* out of `runAgent()` into a `ChildSessionFactory` collaborator while leaving session *interaction* in the runner.
-The plan is a lift-and-shift: `runAgent()` keeps its `(snapshot, type, prompt, options, deps)` signature and delegates creation to a new `ConcreteChildSessionFactory`, so the existing 313-line runner test suite keeps passing through delegation.
-`#256` (`WorktreeIsolation`) is already merged; this step is independent of it and gates Steps 3-4.
-
-### Observations
-
-- Two deliberate refinements of the issue's interface sketch, both forced by the lift-and-shift and documented in the plan:
-  - `ChildSessionResult` adds `agentMaxTurns?: number` — the turn-limit resolution lives in the interaction half but `cfg.agentMaxTurns` is only known after `assembleSessionConfig`, which moves into the factory.
-    Carrying one field across the seam (not the whole `SessionConfig`) is the ISP-narrow choice.
-  - `ChildSessionConfig` is kept narrow (six creation inputs); the issue's target also lists `prompt`/`maxTurns`/`getRunConfig`, but those are interaction concerns that would violate ISP for a creation-only factory.
-- Deferred `ConcreteAgentRunner.createFactory()` to Step 3 (#258) even though the issue lists it as a Step 2 outcome.
-  Adding it now yields an unused class member (fallow flags it): `runAgent` builds the factory directly, and `AgentManager` — the eventual `createFactory` caller — is not wired until Step 3.
-  The factory still has a production consumer this step (`runAgent`), so it is not dead.
-- The permission-bridge `vi.mock()` is path-based, so moving the `registerChildSession`/`unregisterChildSession` import from `agent-runner.ts` into the factory does not break the existing mock — it intercepts the factory's import unchanged.
-- Type-only import of `RunnerDeps` (factory → runner) plus value import of the factory class (runner → factory) is a one-way runtime arrow; `import type` erasure means no real cycle.
-- `RunResult.sessionFile` shifts from a late `sessionManager.getSessionFile()` to the factory's `outputFile` — same value (stable after `newSession()`); the existing `/sessions/child.jsonl` assertion is the guard.
-- Did not invoke `ask_user`: the issue's "Proposed change" is prescriptive, and the two deviations are forced/justified rather than open-ended.
-- IO interfaces (`RunnerIO`, `RunnerDeps`, etc.) intentionally stay in `agent-runner.ts` for this step to minimize churn; their relocation to the factory module is flagged as an Open Question for Step 4 when the runner dissolves.
-
-[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/retro/0262-add-workspace-provider-seam.md

@@ -1,89 +0,0 @@
----
-issue: 262
-issue_title: "Add WorkspaceProvider extension seam"
----
-
-# Retro: #262 — Add WorkspaceProvider extension seam
-
-## Stage: Planning (2026-05-29T14:51:15Z)
-
-### Session summary
-
-Produced a numbered implementation plan for the Phase 16, Step 2 `WorkspaceProvider` seam ([ADR-0002]).
-The plan adds the seam additively — `WorkspaceProvider` / `Workspace` interfaces, `SubagentsService.registerWorkspaceProvider`, run-start consultation, and `dispose` with a verbatim `resultAddendum` — while leaving the existing `isolation: "worktree"` path untouched for #263 to evict.
-Three TDD steps (two `feat`, one `docs`).
-
-### Observations
-
-- Two ambiguous choices were surfaced via `ask_user` and resolved: **scope = additive seam only** (Option A — leave the legacy worktree path; #263 evicts it), and **duplicate registration = throw** (loud misconfiguration surface, disposer clears only the active provider).
-- The package's public surface is `./src/service.ts` (per `package.json` `exports`), so the seam types are defined in a new core `src/lifecycle/workspace.ts` and re-exported from `service.ts` — avoiding a `service ↔ lifecycle` import cycle while still exposing them to the worktrees consumer.
-- Diverged from the issue's literal `Disposable` return type: the repo convention for unsubscribe/unregister is a plain `() => void` (matching `SubscribableSession.subscribe` and `pi.events.on`); no `Symbol.dispose` usage exists anywhere in the codebase.
-- Provider-first precedence was chosen so the new seam and the legacy worktree collaborator never silently conflict during the transient dual-path window (#263 collapses the branch).
-- Headline risk is the ADR "no vacant hooks" rule: within #262 the seam is exercised only by test fakes, so it must land **alongside** #263 (`@gotgenes/pi-subagents-worktrees`) and not ship in a release on its own.
-- Step 1 bundles the entire registration surface (types, `SubagentsService` method, adapter impl, `AgentManagerLike`, required `baseCwd`) into one commit because the interface method forces the adapter and the required field forces both construction sites — splitting would not type-check.
-- Verified `test/service/service.test.ts` casts its mock `as unknown as SubagentsService`, so adding an interface method does not break it; flagged the `createManager` and `AgentManagerLike` mock updates for the `baseCwd` and registration additions.
-
-## Stage: Implementation — TDD (2026-05-29T15:09:49Z)
-
-### Session summary
-
-Implemented the `WorkspaceProvider` seam across three TDD cycles (two `feat`, one `docs`): the registration surface (`AgentManager.registerWorkspaceProvider` + service/adapter delegation + `workspace.ts` types), run-start consumption in `Agent.run()` with provider-first precedence and `dispose`/`resultAddendum`, and an architecture-doc update.
-Test count went from 1049 to 1061 (+12 new tests; +6 in `agent.test.ts`, +4 registration in `agent-manager.test.ts`, +1 adapter delegation, plus existing-helper additions).
-All deterministic gates green: `check`, `lint`, `test`, and `fallow dead-code` (run from repo root).
-
-### Observations
-
-- Deviation from plan (Module-Level Changes): the plan said `service.ts` would re-export "the five seam types and `AgentStatus`", but `fallow dead-code` flagged those five re-exports as unused (no consumer until #263), and AGENTS.md forbids speculative re-exports.
-  Resolved by re-exporting only `WorkspaceProvider` — a consumer assigning to it gets `Workspace` and the context types via inference; #263 adds named re-exports when it imports them.
-  This is the concrete manifestation of the plan's headline "vacant hook" risk surfacing in the dead-code gate.
-- Lint surprise: `WorkspaceDisposeResult | void` tripped eslint `no-invalid-void-type`.
-  Changed the `dispose` return type to `WorkspaceDisposeResult | undefined` (equivalent — a side-effecting `dispose` that falls off the end returns `undefined`); minor divergence from the issue's literal `| void`.
-- Three test mock factories implement `AgentManagerLike` in `service-adapter.test.ts` (`createMockManager`, `defaultManager`, `createTestManager`) — all three needed the new `registerWorkspaceProvider` stub; `tsc` caught the third after the first two were updated.
-- Used `git commit --fixup` + `--autosquash` rebase twice (unpushed history) to fold the fallow trim into the Step 1 `feat` commit and the reviewer's doc-wording fix into the Step 3 `docs` commit, keeping each commit self-consistent.
-- Pre-completion reviewer: WARN — all blocking checks pass; one non-blocking doc finding (architecture.md overstated that `Workspace` is re-exported).
-  Addressed before finishing.
-
-## Stage: Final Retrospective (2026-05-29T15:40:54Z)
-
-### Session summary
-
-Shipped #262: pushed, CI green, closed the issue, and merged release-please PR #269 → `pi-subagents-v11.5.0`.
-Mid-session the user asked what `model: claude-sonnet-4-6-20260526` in `.pi/agents/pre-completion-reviewer.md` resolved to; investigation found it had no entry in Pi's model registry and was silently falling back to the parent session model, and the fix (`anthropic/claude-sonnet-4-6`) landed in `1e46c5f4`.
-Across all stages the plan's risk predictions held and TDD verification was incremental.
-
-### Observations
-
-#### What went well
-
-- The planning-stage "vacant hook" risk prediction manifested exactly as predicted at the `fallow dead-code` gate: the plan named the failure (speculative re-exports flagged dead) before it happened, and the fix (re-export only `WorkspaceProvider`) was already reasoned out — a clean closed loop from planning risk to implementation gate.
-- Incremental verification during TDD: `check` / `test` / `lint` ran after each step plus per-file vitest red→green, not just at the end.
-- The model-spec question surfaced and fixed a latent silent bug — the reviewer's configured `model:` had no registry entry and was inheriting the parent model, so the misconfiguration produced no error.
-- Cost discipline: the session model was switched to `opencode-go/deepseek-v4-flash` for the mechanical shipping stage — appropriate model-to-task matching.
-
-#### What caused friction (agent side)
-
-- `rabbit-hole` — the model-resolution investigation (≈30 tool calls, turns 119–160) grepped the Pi core monorepo (`~/development/pi/pi/packages/coding-agent`) for `.pi/agents/` frontmatter handling that does not live there, before landing on `pi-prompt-template-model/model-selection.ts` (a `pi-packages` dependency) plus the `models.generated.ts` registry.
-  Impact: long detour on a user tangent; no rework, but the answer was reachable far sooner.
-- `other` (minor, recurring) — the pre-commit `trim trailing whitespace` hook reformatted files on the first `git commit`, failing it; the immediate retry succeeded (turns 55→56 and 95→96).
-  Impact: one wasted commit attempt per occurrence, no rework.
-
-#### What caused friction (user side)
-
-- The broken model spec was pre-existing config; because the failure mode is a silent fallback, such typos never surface on their own.
-  Opportunity (not criticism): a short convention note so future `.pi/agents/*.md` authoring uses the registry-resolvable `provider/id` form.
-
-### Diagnostic details
-
-- **Model-performance correlation** — the `pre-completion-reviewer` subagent was dispatched (turn 90) while the parent model was `anthropic/claude-opus-4-8`; because its `model:` frontmatter did not resolve, it ran on opus-4-8 (strong reasoning, appropriate for judgment-heavy review) rather than the configured Sonnet.
-  No quality mismatch in outcome, but the risk was latent: a weaker parent model would have silently degraded the reviewer.
-  The shipping stage ran on `deepseek-v4-flash` (mechanical git/CI/release ops) — appropriate.
-- **Escalation-delay tracking** — the model-resolution `rabbit-hole` ran ≈30 consecutive search calls on the same goal, far past the 5-call threshold; consulting the `prompt-template-authoring` skill or reading `model-selection.ts` first would have shortcut it.
-- **Unused-tool detection** — for that investigation the `prompt-template-authoring` skill (documents template/agent `model:` format) and `code_search` were available but not used; grep over two monorepos was used instead.
-- **Feedback-loop gap analysis** — none; verification ran incrementally after each TDD step, not only at the end.
-
-### Changes made
-
-1. `AGENTS.md` (Pre-completion reviewer subsection) — added a one-line guardrail: agent `model:` frontmatter must use the `provider/id` alias form the Pi CLI/UI accepts, because an ID absent from the model registry silently falls back to the parent session model.
-2. `packages/pi-subagents/docs/retro/0262-add-workspace-provider-seam.md` — this Final Retrospective stage entry.
-
-[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/retro/0264-remove-extension-lifecycle-control.md

@@ -1,91 +0,0 @@
----
-issue: 264
-issue_title: "Remove isolated / extensions:false / noSkills from core"
----
-
-# Retro: #264 — Remove isolated / extensions:false / noSkills from core
-
-## Stage: Planning (2026-05-30T00:09:21Z)
-
-### Session summary
-
-Planned Phase 16, Step 4: removing the extension-lifecycle-control axis (`isolated`, `extensions: false`, `noSkills`) from the pi-subagents core per [ADR-0002].
-Confirmed all three prerequisite Phase 16 steps (#261, #262, #263) are closed, so the explicit "deny-at-use" dependency is satisfied.
-Produced a four-cycle TDD plan (`isolated` → `extensions` → `skills`/`noSkills`/preload → docs) and committed it.
-
-### Observations
-
-- Scope expansion decided with the user: the issue names only `isolated` / `extensions: false` / `noSkills`, but `noSkills` is the single mechanism behind **both** skill-restriction modes (`skills: false` and `skills: string[]` preload).
-  Removing `noSkills` without also removing `AgentConfig.skills` would leave a field that silently stops restricting.
-  Chose the **collapse-skills-fully** option (symmetric with `extensions`): retire `AgentConfig.skills`, `skill-loader.ts`, `safe-fs.ts` (sole consumer was the skill loader), `preloadSkills`, `PromptExtras`, and `extras.skillBlocks`.
-  Children always inherit Pi's full skill system — the `skills: true` path.
-- The recursion guard's `if (cfg.extensions)` gate is removed in the `extensions` cycle (cycle 2), since `SessionConfig.extensions` disappears there.
-  A guard-always-runs assertion replaces the deleted "extensions: false skips the filter entirely" test.
-- This is a **breaking** change (`feat!:`): public `SpawnOptions.isolated` and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are removed.
-  Custom agents with legacy frontmatter will silently ignore those keys (matches the Phase 14 precedent for `disallowed_tools`).
-- Sequencing note surfaced to the user: some `isolated`-threading removed here (`RunOptions.isolated`, `Agent.run()` plumbing) is structure that Step 5 (#265, dissolve the runner) will delete anyway — small, unavoidable, and #265 depends on this step, so no reordering benefit.
-- Helper-file churn accepted: `test/helpers/runner-io.ts` is touched in all three removal cycles (one field per cycle); ordering is fixed (`isolated` → `extensions` → `skills`) so no cycle leaves a dangling reference.
-- Doc updates identified: `docs/architecture/architecture.md` (Mermaid session subgraph, directory tree, `SpawnOptions`/`RunOptions` field lists, roadmap status) and the `package-pi-subagents` SKILL.md session-domain row (8 → 6 modules).
-
-## Stage: Implementation — TDD (2026-05-30T00:38:00Z)
-
-### Session summary
-
-Executed all four plan cycles (`isolated` → `extensions` + unconditional guard → `skills`/`noSkills`/preload → docs) as three `feat!:` commits plus one `docs:` commit.
-The extension-lifecycle-control axis and the `skills` curation axis are gone; children always inherit the parent's extensions and full skill system, and the recursion guard is unconditional.
-Test count went 1016 → 951 (−65): deleted `skill-loader.test.ts` and `safe-fs.test.ts`, plus removed isolated/extensions/skills/preload-specific cases; `check`, `lint`, `fallow dead-code`, and `verify:public-types` all green.
-
-### Observations
-
-- The plan's cycle split held up cleanly.
-  The only interleaving friction was `test/config/custom-agents.test.ts`, where `extensions` and `skills` assertions shared the same `it` blocks.
-  Handled it by retitling the shared tests to skills-only in cycle 2 (keeping skills compiling/passing), then deleting them in cycle 3 — no dangling references between commits.
-- BSD `sed` (macOS) does not support `\|` alternation in basic regex; the standalone-fixture-line deletions needed `sed -E`.
-  Worth remembering for future bulk fixture removals.
-- Two in-scope judgment calls beyond the literal plan: (1) kept the generic tag-rendering test in `result-renderer.test.ts` by swapping the example tag `"isolated"` → `"inherit context"` rather than deleting coverage; (2) removed the now-unused `vi` import from `custom-agents.test.ts` after dropping the extensions-deprecation-warning test.
-- The `spawn-config.test.ts` `agentInvocation` snapshot carried a stale `isolation: undefined` leftover (from the #263 worktree eviction) that `toEqual` had been silently ignoring; removed it alongside `isolated: false` for a clean exact-match assertion.
-- `verify:public-types` confirmed the breaking `SpawnOptions.isolated` removal type-checks against an external consumer; no lockfile changes; `dist/` correctly gitignored after the type-bundle build.
-- Pre-completion reviewer: **PASS** — both acceptance criteria code-verified, all deterministic checks green, 6 Mermaid diagrams render, docs accurate, zero dead code.
-
-## Stage: Final Retrospective (2026-05-30T01:13:26Z)
-
-### Session summary
-
-Shipped #264 end-to-end across three stages (Planning → TDD → Ship) in one conversation: planned the four-cycle removal, implemented it as three `feat!:` commits plus docs, and released `pi-subagents-v13.0.0` via the release-please PR (#276).
-The run had zero rework and a PASS pre-completion review; test count moved 1016 → 951.
-
-### Observations
-
-#### What went well
-
-- The planning-stage `ask-user` gate caught a real scope trap before any code was written.
-  The issue named three fields (`isolated`, `extensions: false`, `noSkills`), but `noSkills` turned out to be the single mechanism behind **two** skill-restriction modes (skill-disable and `skills: string[]` preload).
-  Removing it while keeping `AgentConfig.skills` would have left a field that silently stops restricting — a mid-cycle-3 wall.
-  Catching it at planning time expanded the clean scope to four collapsing fields and produced a symmetric, reviewable plan.
-- The four-cycle split (`isolated` → `extensions` + unconditional guard → `skills`/`noSkills`/preload → docs) held with no cross-cycle dangling references, validating the lift-and-shift discipline for shared-interface removal.
-- Verification ran incrementally (`pnpm run check` + `pnpm run test` after every cycle), so each commit landed green; the only end-of-run surprise was a pre-commit `end-of-file-fixer` hook touching `custom-agents.ts` (handled with a re-add, no rework).
-
-#### What caused friction (agent side)
-
-- `other` (tooling) — BSD `sed` on macOS does not support `\|` alternation in basic regex; the first bulk fixture-deletion attempt silently matched nothing.
-  Impact: one wasted tool call, no rework; resolved by switching to `sed -E`.
-
-#### What caused friction (user side)
-
-- The opening sequencing question ("is there work that should precede this") was first read literally as a prerequisite check (#261/#262/#263), and the user had to rephrase to get at the within-issue sequencing point that surfaced the `noSkills`/`skills` coupling.
-  Opportunity, not criticism: offering both readings of an ambiguous "what comes first" question up front would have reached the valuable discovery one turn sooner.
-
-#### Diagnostic details
-
-- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`, 325s, 43 tool uses) on a judgment-heavy review task; appropriate assignment.
-  No Explore/Plan subagents were needed — planning-stage exploration was direct file reads and targeted greps, efficient for this removal's scope.
-- **Escalation-delay tracking** — no rabbit-holes; the `sed` issue resolved in one retry.
-- **Feedback-loop gap analysis** — no gap; `check`/`test`/`lint` ran after each cycle, with `fallow dead-code` and `verify:public-types` at the end.
-
-### Changes made
-
-1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0264-remove-extension-lifecycle-control.md`.
-2. Considered but **declined** (user: "too narrow") a removal-coupling detection rule for `.pi/prompts/plan-issue.md` — the heuristic that a field named for removal may be the mechanism behind a separate surviving feature.
-   No prompt or `AGENTS.md` changes were made this retro.
-
-[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md