@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/retro/0426-consolidate-residual-test-clone-families.md

@@ -1,100 +0,0 @@
----
-issue: 426
-issue_title: "pi-subagents: consolidate residual test clone families"
----
-
-# Retro: #426 — pi-subagents: consolidate residual test clone families
-
-## Stage: Planning (2026-06-18T17:48:42Z)
-
-### Session summary
-
-Produced a numbered plan (`docs/plans/0426-consolidate-residual-test-clone-families.md`) for consolidating the residual test clone families in four named `pi-subagents` test files.
-Ran `fallow dupes` to enumerate the live clone groups: 24 test clone groups package-wide, of which the four target files (`test/settings.test.ts` + `test/layered-settings.test.ts`, `test/lifecycle/create-subagent-session.test.ts`, `test/ui/agent-config-editor.test.ts`) contribute exactly 10 — consolidating them lands at 14, below the issue's `<15` target.
-The plan is a test-only refactor verified by the existing suite staying green plus a falling fallow clone count; the follow-up is `/build-plan` (no red→green behavior cycles).
-
-### Observations
-
-- Release: ship independently — the Phase 18 roadmap step 7 carries no `Release: batch` tag and is explicitly "independent of the disentanglement spine."
-- The `testing` skill's rule "do not wrap the system-under-test call in a helper to eliminate a duplication-metric clone" drove the design: consolidate *arrange* only, keep every `loadSettings`/`createSubagentSession`/`showAgentDetail` act written out.
-  For `agent-config-editor` menu cases, `it.each` is the right tool — it keeps the act visible in the table body rather than hiding it in a helper.
-- Three independent consolidations: (1) a new shared `test/helpers/tmp-settings-dirs.ts` fixture for the cross-file settings tmp-dir scaffolding (with paired self-test, per the `test/helpers/*.test.ts` convention); (2) file-local `arrangeFactory`/`defaultDeps` for the `create-subagent-session` post-bind-guard block; (3) `it.each` table + hoisted `filePath` for `agent-config-editor`.
-- Scope deliberately excludes: the production clone in `src/ui/agent-config-editor.ts` (test-only issue), the cross-package `vitest.config.ts` clone, the `5d8dbd48` group spanning `subagent-manager.test.ts` ↔ `subagent.test.ts` (neither is a target file), and all other non-target test clone families.
-- Key risk flagged for build: removing inline `writeGlobal`/`writeProject` may orphan fs imports (`mkdtempSync`/`rmSync`/`mkdirSync`/`writeFileSync`/`tmpdir`/`join`); Biome `noUnusedImports` is warning-level, so step 4 runs `pnpm fallow dead-code` as the backstop.
-- Markdown lint gotcha hit during planning: bare `#N` inline mentions are fine, but reference-style `[#N]` link defs trip `MD053` unless a matching bracket reference exists in the body — kept only the `[#427]` cross-link def.
-
-## Stage: Implementation — Build (2026-06-18T18:14:01Z)
-
-### Session summary
-
-Executed all four refactor steps plus the architecture doc-flip across four commits.
-Extracted two shared test fixtures (`test/helpers/tmp-settings-dirs.ts`, `test/helpers/capture-warn.ts`, each with a paired self-test) and table-drove the `create-subagent-session` post-bind and `agent-config-editor` menu/confirm-remove cases into `it.each`.
-Dropped pi-subagents test clone groups from 24 to 14 (below the `<15` target); full suite green at 1047 tests (was 1038), type check and lint clean, `fallow dead-code` clean.
-
-### Observations
-
-- Pre-completion reviewer: PASS (deterministic checks, assertion-strength preservation, act-visibility, and no-coverage-drop all verified).
-- Deviation 1 — the settings fixture exposes a `dispose()` method instead of the plan's separate `disposeSettingsDirs()` function (Tell-Don't-Ask; the fixture disposes itself).
-- Deviation 2 — added `test/helpers/capture-warn.ts` (`captureWarn`) beyond the plan's tmp-dir-only fixture.
-  The plan's Step 1 verify listed clone group `4003c0e7` (the `console.warn` spy try/finally boilerplate) as expected-gone, but the tmp-dir fixture alone did not address it; the warn-capture helper does, and migrating the spy tests in both files cleared it.
-  Squarely within the issue's "extract shared fixtures for the clone families" intent.
-- Deviation 3 — Step 2's first pass (arrange helpers only) left a transient arrange+assert clone (`62899223`) between the two adjacent post-bind membership tests; folding the three membership cases into one `it.each` with a strong `toEqual` (replacing the prior `toContain` checks) cleared it.
-- Used destructure-to-locals in `settings.test.ts`/`layered-settings.test.ts` (e.g. `({ globalDir: agentDir, projectDir: cwd, ... } = dirs)`) rather than the plan's `dirs.X` member-access sketch — keeps the existing terse test bodies unchanged and lowers edit risk.
-- Dropped one brittle `captureWarn` self-test ("suppresses real stderr") that was actually exercising `vi.spyOn`'s restore-to-original semantics with nested spies, not the helper's behavior.
-- The risk flagged at planning (orphaned `node:fs`/`node:os` imports after removing inline `writeGlobal`/`writeProject`) materialized only in `layered-settings.test.ts` (`mkdtempSync`/`rmSync`/`tmpdir`/`vi` became unused); removed them, and `fallow dead-code` confirmed clean.
-
-## Stage: Final Retrospective (2026-06-18T18:31:04Z)
-
-### Session summary
-
-Planned, built, and shipped #426 in one continuous session: extracted two shared test fixtures (`tmp-settings-dirs.ts`, `capture-warn.ts`) and table-drove four clone families into `it.each`, dropping pi-subagents test clone groups from 24 to 14.
-CI green, issue closed, no release cut (all `test:`/`docs:` commits batch until the next `feat`/`fix`).
-Execution was clean overall; the one recurring friction was the plan over-predicting which clone fingerprints each change would clear.
-
-### Observations
-
-#### What went well
-
-- **Metric-driven feedback loop.**
-  Each build step re-ran `pnpm fallow dupes` and checked the targeted fingerprints (`21d1fb01`, `4003c0e7`, `48ff1484`, …) disappeared before committing.
-  This caught the two prediction gaps (below) immediately rather than at pre-completion, and turned a fuzzy "reduce duplication" goal into a precise per-step pass/fail.
-- **`it.each` strengthened assertions while consolidating.**
-  Folding the `create-subagent-session` post-bind cases into a table let the merged test assert `toEqual(expected)` on the full post-bind set, replacing the prior weaker `toContain` checks — consolidation improved coverage rather than just moving lines.
-- **Pre-completion reviewer verified the real risk.**
-  For a test-refactor the central risk is silent coverage loss; the reviewer explicitly confirmed former-`it`-count equals row-count for every `it.each` and that each act stayed explicit.
-  PASS with nothing to fix.
-
-#### What caused friction (agent side)
-
-- `missing-context` (planning) — the plan's Step 1 *verify* listed clone group `4003c0e7` (the `console.warn` spy try/finally boilerplate) as expected-gone, but the Step 1 *design* only described the tmp-dir fixture, which does not touch that clone.
-  The build discovered the gap and added `capture-warn.ts` + migrated ~7 spy tests mid-step.
-  Impact: one unplanned helper (with self-test) folded into the same commit; no follow-up commit, but the plan-vs-build mismatch was real.
-- `wrong-abstraction` (build, self-corrected) — Step 2's first pass applied arrange helpers (`arrangeFactory`/`defaultDeps`) alone, which left a *new* transient clone (`62899223`) between the two adjacent post-bind tests.
-  Folding the three membership cases into one `it.each` cleared it.
-  Impact: one extra edit+verify iteration within the step; caught by the same-step `fallow dupes` run.
-- `other` (build, trivial) — wrote a brittle `captureWarn` self-test ("suppresses real stderr") that asserted `vi.spyOn` nested-restore semantics rather than the helper's behavior; the test failed immediately and was dropped.
-  Impact: ~2 tool calls, no rework downstream.
-- `other` (ship, trivial) — `git log | grep -P` failed on macOS BSD grep; retried with `grep -o`.
-  Impact: one retry.
-
-#### What caused friction (user side)
-
-- None.
-  The session ran end-to-end (plan → build → ship → retro) without a mid-course correction; the prompts carried enough structure that no strategic intervention was needed.
-
-### Diagnostic details
-
-- **Model-performance correlation** — the entire `/ship-issue` stage ran on `opencode-go/deepseek-v4-flash` (a reasoning-weak model), covering judgment-bearing steps: release-coordination decision, stacked-release detection, and close-comment synthesis.
-  It executed correctly because `/ship-issue` is heavily proceduralized (deterministic checks, explicit decision tree), so the weak model followed the rails without error.
-  Planning/build ran on stronger models (`opus-4-8`/`sonnet-4-6`); retro on `opus-4-8`.
-  No quality defect resulted, but ship-issue does carry real judgment — worth noting that its proceduralization is what absorbed the model mismatch.
-- **Escalation-delay tracking** — no `rabbit-hole`; the two prediction-gap fixes resolved in 1–2 tool calls each via the per-step `fallow dupes` check.
-  No sequence exceeded the 5-call flag.
-- **Unused-tool detection** — none needed; scope was small and fully understood from the planning-stage file reads. `fallow dupes` was the right and sufficient tool.
-- **Feedback-loop gap analysis** — verification ran *incrementally*: `pnpm run check` + `vitest run <file>` + `pnpm fallow dupes` after every step, full suite + `fallow dead-code` at the end.
-  No end-only verification gap.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added a cross-section consistency rule under **Module-Level Changes**: when a plan step's verify criterion names a static-analysis finding (clone fingerprint, dead-code symbol, complexity target) as resolved, the design or Module-Level Changes must map the change that clears it.
-   Motivated by the Step 1 `4003c0e7` prediction gap (the verify step listed it as expected-gone but the design did not address it, forcing the mid-build `capture-warn.ts` addition).

package/docs/retro/0427-reconsider-ui-direction.md

@@ -1,102 +0,0 @@
----
-issue: 427
-issue_title: "pi-subagents: reconsider the UI direction from first principles (ADR)"
----
-
-# Retro: #427 — pi-subagents: reconsider the UI direction from first principles (ADR)
-
-## Stage: Planning (2026-06-18T00:00:00Z)
-
-### Session summary
-
-Planned the Phase 18 Step 8 decision-only ADR for the pi-subagents UI direction.
-Two `ask_user` rounds with the operator (their own issue) settled a per-component decision and surfaced a key SDK finding — Pi's `switchSession(sessionPath)` — that reshapes the conversation-viewer direction.
-The plan writes `docs/decisions/0004-reconsider-ui-direction.md` plus an architecture-doc update; no `src/`/`test/` changes (implementation deferred to a separately-planned Phase 19).
-
-### Observations
-
-- **Decision-only ADR → `/build-plan`, not `/tdd-plan`.**
-  The operator chose to record decisions and defer all code to Phase 19, so the plan has a docs-only Build Order, no test cycles.
-- **Per-component decisions recorded:**
-  (A) foreground widget shrinks to background-agents-only;
-  (B) conversation viewer replaced by native session navigation (remove the bespoke `ConversationViewer`);
-  (C) `/agents` menu dissolved — **remove** both agent-management surfaces outright (creation wizard and agent-types config editor; managing definitions belongs in an editor/IDE or a Pi agent, not the menu), re-home running-agent visibility onto the widget + session navigation, extract settings to a focused `/subagents:settings` command;
-  (D) distribution = keep surviving UI in-core (substitutable, _not_ extracted to `@gotgenes/pi-subagents-ui`).
-- **Key SDK finding — `switchSession`.**
-  `@earendil-works/pi-coding-agent@0.79.1` exposes `ExtensionActions.switchSession(sessionPath, { withSession })`.
-  It is a _full active-session takeover_ (fires `session_before_switch`/`session_shutdown`, invalidates the current context), and the switched-to session is interactive (`ReplacedSessionContext.sendUserMessage`).
-  A read-only alternative exists: `loadEntriesFromFile`/`parseSessionEntries` render a transcript without switching.
-  These tensions are recorded as Phase 19 spike gates rather than pretend-resolved — the ADR commits to the _direction_ (native session machinery over a bespoke renderer), not the _mechanism_.
-- **Operator-raised open questions (now Phase 19 entry criteria):** root-continuity during a session switch, view-only vs interactive, parallel-agent navigation gesture, settings command namespace, and confirming the creation-wizard's value is covered by "generate via a Pi agent" before deleting it.
-- **Release:** ship independently — Phase 18 carries no `Release:` batch tag; this issue completes the phase.
-- **Numbering:** plan `0427`, ADR `0004` (next free in `docs/decisions/`).
-
-## Stage: Implementation — Build (2026-06-18T20:05:00Z)
-
-### Session summary
-
-Executed the decision-only ADR plan in two docs steps: wrote `docs/decisions/0004-reconsider-ui-direction.md` (per-component decisions A–D plus Phase 19 entry criteria) and updated `docs/architecture/architecture.md` (Step 8 + phase row marked `✅` complete, `S8` Mermaid node `✅`, ADR-0004 Landed line gateway-ing Phase 19).
-No `src/`/`test/`/`.ts` files were touched, so the type-check and suite were correctly skipped; `pnpm run lint` is green.
-
-### Observations
-
-- **Decision-only ADR held to scope:** four docs files total (ADR, arch doc, plan, retro); zero runtime change, matching the plan's Non-Goals.
-- **Pre-completion reviewer: PASS.**
-  One non-blocking WARN — architecture design-principle #5 still read "UI extraction is deferred … first candidate for extraction," which ADR-0004's Decision D now contradicts.
-- **Reviewer warning addressed in-session:** rewrote principle #5 to "UI is an in-core, substitutable consumer" pointing at ADR-0004 (commit `1c445ed4`), rather than deferring it to Phase 19 — it lived in the same doc and directly conflicted with the just-landed ADR.
-- **Lint gotcha:** the relative ADR link from `docs/architecture/` needs `../decisions/…` (the Step 8 Landed line already had it); an initial `decisions/…` tripped `MD057` and was fixed by amend.
-  Also note `pnpm … lint | tail -N` masks the pipeline exit status — check `PIPESTATUS`/run lint unpiped to gate `&&` chains.
-- **Commit count:** 4 build/doc commits for this stage (`17b0546a`, `7b1d9316`, `1c445ed4` for the ADR + arch doc; planning commits `12e7814a`/`e4895548`/`f1e65a14` predate this stage).
-
-## Stage: Final Retrospective (2026-06-18T21:00:00Z)
-
-### Session summary
-
-Shipped issue #427 — a decision-only ADR (`docs/decisions/0004-reconsider-ui-direction.md`) completing Phase 18 of the `pi-subagents` roadmap — across planning, build, and ship stages in one session.
-The whole arc held to docs-only scope: four docs files, zero runtime change, all `docs:` commits, so release-please correctly batched (no version cut).
-CI passed; #427 closed with a per-component decision summary; siblings #425/#426/#434 were already closed.
-
-### Observations
-
-#### What went well
-
-- **Verified the SDK surface before recording it (novel).**
-  Rather than build the ADR on an assumed `switchSession` API, I read `@earendil-works/pi-coding-agent@0.79.1` `.d.ts` files directly in `node_modules` and confirmed the real contract — full active-session takeover, interactive `ReplacedSessionContext`, plus the `loadEntriesFromFile` read-only alternative.
-  This generalizes the AGENTS.md "verify the remediation exists in the real surface" rule (written for breaking-change migration notes) to an ADR's SDK claims, and it directly shaped Decision B's "direction not mechanism" framing.
-- **Decision-only scope discipline.**
-  Held to four docs files matching the plan's Non-Goals; no `src/`/`test/` drift despite the ADR describing future code.
-- **Pre-completion reviewer earned its keep on a docs-only change.**
-  It caught a stale design-principle (#5) that directly contradicted the just-landed ADR — a real inconsistency, not a code defect — showing the reviewer adds value beyond test/lint gates.
-- **`ask_user` used well for a decision-heavy issue.**
-  Two structured rounds (per-component fates, then the `switchSession`-informed follow-up) let the operator drive the ADR's content; the second round was correctly gated on the first's SDK finding.
-
-#### What caused friction (agent side)
-
-- `other` (shell footgun) — gated a commit on a lint check piped through `tail`: `pnpm … lint 2>&1 | tail -3 && git add … && git commit`.
-  A pipeline's exit status is the last command (`tail`), so the lint failure was masked and a broken-link commit (`89ad57a3`, `MD057`) landed before I noticed.
-  Impact: one extra fix + `git commit --amend`; self-caught on the next unpiped lint run.
-  No bad push (the amend preceded `/ship-issue`).
-- `other` (doc-link slip) — wrote a relative ADR link as `decisions/0004-…` from `docs/architecture/`, when the same session's earlier Step 8 Landed line already used the correct `../decisions/…`.
-  Impact: the `MD057` failure above; had the correct pattern in hand and didn't reuse it.
-- `other` (malformed tool call) — one `Edit` call included a stray `newText_unused` property and was rejected; retried cleanly.
-  Impact: one wasted call, self-caught.
-
-#### What caused friction (user side)
-
-- None blocking.
-  The operator firmed the `/agents` decision (remove create+edit surfaces) one turn after the plan was first committed, costing a small follow-up commit (`f1e65a14`).
-  Opportunity, not criticism: the `ask_user` `/agents` option labeled "shrink — keep config management" may have under-signaled that outright removal was on the table; a crisper "remove agent-management surfaces" option could have surfaced the firm decision in the first round.
-
-### Diagnostic details
-
-- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`) for judgment-heavy review; appropriate (per AGENTS.md its `model:` frontmatter must be a `provider/id` alias to actually run).
-  The main session's `model_change` log shows frequent toggling (`glm-5.2`, `opus-4-8`, `sonnet-4-6`, `deepseek-v4-flash`) but turns can't be cleanly attributed and nothing looks mismatched — not actionable.
-- **Feedback-loop gap analysis** — `pnpm run lint` ran incrementally after each build step (good), not just at the end; baseline `check`+`lint` ran before any change.
-  The one gap was process, not timing: the `tail`-masked lint let a failure slip a commit (above).
-- **Escalation-delay / unused-tool** — no rabbit-holes; longest same-error streak was 1–2 calls (the `MD057` fix).
-  Direct `node_modules` `.d.ts` inspection substituted well for `web_search`/`code_search` on the SDK contract — no missing-context gap.
-
-### Changes made
-
-1. `AGENTS.md` § Commits — added a two-line rule: don't gate a commit (or any `&&` step) on a check piped through `tail`/`head`, since the pipeline's exit status is the filter's and a failed `pnpm run lint`/`check` is masked; run the check unpiped or test `${PIPESTATUS[0]}`.
-2. `packages/pi-subagents/docs/retro/0427-reconsider-ui-direction.md` — appended this Final Retrospective stage entry.

package/docs/retro/0441-remove-agent-definition-management-subtree.md

@@ -1,97 +0,0 @@
----
-issue: 441
-issue_title: "pi-subagents: remove the orphaned agent-definition management subtree"
----
-
-# Retro: #441 — pi-subagents: remove the orphaned agent-definition management subtree
-
-## Stage: Planning (2026-06-23T00:00:00Z)
-
-### Session summary
-
-Produced a deletion-only plan for Phase 19 Step 6: `git rm` the orphaned creation wizard, config editor, and their two file-ops helpers (plus tests), prune `test/helpers/ui-stubs.ts` to just `makeMenuUI`, and update the two current-state docs.
-Verified against `main` that the five modules are pure orphans (no `src/` importer, `index.ts` clean) and that this is the unreleased tail of release batch "dissolve-agents".
-The plan routes to `/build-plan` (no test cycles) with two commits.
-
-### Observations
-
-- Two deviations from the issue body, both forced by the codebase + the authoritative architecture doc rather than by preference, so no `ask_user` gate was used:
-  1. `menu-ui.ts` (the `MenuUI` interface) must also be deleted — it is orphaned by the same cut, and `architecture.md` lines 346/1076 explicitly schedule its removal under #441.
-     The issue body omits it.
-  2. `makeMenuManager` is removed whole, not just its `spawnAndWait` field — after the four test files go, its only consumer is its own self-test, so it is residual clutter.
-     The architecture doc's "if no surviving consumer remains" phrasing licenses this.
-- `ui-stubs.ts` survives because `makeMenuUI` still has a real consumer (`subagents-settings.test.ts`); only the three other helpers (and the private `DEFAULT_TEST_AGENT_CONFIG` + the `AgentConfig` import) are pruned.
-- Commit type is `refactor(pi-subagents):`, not `feat!:` — deleting already-unreachable code changes no observable behavior at this step.
-  The release is driven by Step 5's unreleased breaking `feat!:` (`cb813f2c`, after tag `pi-subagents-v17.5.0`); landing this tail lets release-please cut the major bump.
-- Production duplication goes to zero when `agent-config-editor.ts` is deleted (the 11-line `disableAgent`/`ejectAgent` clone); pin with `pnpm fallow dupes`.
-- Historical docs under `docs/plans/`, `docs/retro/`, and `docs/architecture/history/` mention the deleted modules only as records of completed phases — left untouched per convention; only `architecture.md` current-state and `SKILL.md` are updated.
-
-## Stage: Implementation — Build (2026-06-23T17:00:00Z)
-
-### Session summary
-
-Executed the two-commit plan: `git rm` the five orphaned `src/ui/` modules and four test files in one atomic commit; pruned `test/helpers/ui-stubs.ts` and `ui-stubs.test.ts` to `makeMenuUI` only in the same commit.
-Second commit updated `architecture.md` (directory tree, Step 6 ✅ and Landed note, Mermaid node) and `SKILL.md` (UI domain row 11→6).
-Three additional doc-fixup commits addressed stale `architecture.md` prose (domain flowchart, cross-extension diagram, "What the core owns," "Composition model") deferred from #442.
-All checks green: 62 test files / 950 tests, `fallow dead-code` clean, `fallow dupes` shows 0 production clone groups.
-
-### Observations
-
-- The pre-completion reviewer surfaced five stale `architecture.md` sections not covered by the plan's declared doc scope — all carried over from #442's retro note "Deferred the holistic architecture-doc refresh … to the batch tail [#441]."
-  Required three extra doc-fixup commits (`e440d0d1`, `04b13812`, and the SKILL.md file-count fix) beyond the plan's two.
-  **Lesson:** when a retro note explicitly defers a doc refresh to the batch tail, include it in the batch-tail plan's "Module-Level Changes" doc section so it isn't discovered only by the reviewer.
-- `makeMenuManager` was removed whole (not just its `spawnAndWait` relay) because its only post-cut consumer was its own self-test — exactly the right call, consistent with the planning decision.
-- Final file count in `src/`: 57 (was 58 in SKILL.md header; now corrected).
-- Pre-completion reviewer: **PASS** (third dispatch, after two WARN rounds on the stale doc sections).
-
-## Stage: Final Retrospective (2026-06-23T18:30:00Z)
-
-### Session summary
-
-Shipped #441 as the tail of release batch "dissolve-agents": pushed, CI green, closed both #441 and the stacked #442, merged release-please PR #469, and cut `pi-subagents-v18.0.0`.
-The whole arc (plan → build → ship) executed in one session with no rework to the deletion itself — the only friction was doc staleness inherited from #442, caught by the pre-completion reviewer across two WARN rounds.
-
-### Observations
-
-#### What went well
-
-- The fresh-context `pre-completion-reviewer` earned its keep on a deletion task: it caught five stale `architecture.md` sections (a domain Mermaid diagram, a cross-extension diagram label, and three prose passages) that referenced modules deleted in #442, none of which the plan or the implementation agent flagged.
-  Doc staleness is exactly the category a focused deletion misses, and the reviewer is the safety net that held.
-- Batch-tail release mechanics worked exactly as planned: a `refactor(pi-subagents):` tail commit carried no version weight itself, the unreleased `feat(pi-subagents)!:` from #442 (`cb813f2c`) drove the major bump, and `release-please` cut `v18.0.0` cleanly while both issues closed with curated comments.
-
-#### What caused friction (agent side)
-
-1. `missing-context` (cross-session) — `#442`'s retro explicitly deferred a "holistic architecture-doc refresh" to the batch tail (#441), but #441's planning stage never pulled that deferred work into the plan's `Module-Level Changes` doc scope.
-   The `/plan-issue` "Check for prior session context" step reads only the **current** issue's retro (`NNNN` matching the issue number), so a predecessor batch member's deferred work is invisible to it.
-   Impact: three extra doc-fixup commits (`e440d0d1`, `04b13812`, and the `SKILL.md` file-count fix) and three pre-completion reviewer dispatches (two WARN, then PASS) during the build stage.
-2. `wrong-abstraction` (fix scope) — after the first reviewer WARN named three stale sections, the fix addressed exactly those three rather than grepping `architecture.md` exhaustively for every reference to the deleted modules (`conversation-viewer`, `agent-menu`, `/agents`).
-   Impact: the second review round found two more stale sections, forcing another fix → commit → re-review cycle that one exhaustive grep would have collapsed into the first round.
-
-#### What caused friction (user side)
-
-- None substantive.
-  The user's two `Continue.` prompts during the build stage were mechanical resumptions (after an autoformat tool message and a context boundary), not redirections — the work was well-specified by the plan throughout.
-
-### Diagnostic details
-
-- **Model-performance correlation** — the `pre-completion-reviewer` ran on `anthropic/claude-sonnet-4-6` (per its agent frontmatter), an appropriate match for judgment-heavy doc-staleness and design review; no high-cost-model-on-mechanical-work or weak-model-on-judgment mismatch.
-  No other subagents were dispatched.
-- **Unused-tool detection** — friction point 2 was a `grep`/`colgrep` gap: an exhaustive search for the deleted-module names across `architecture.md` after the first WARN would have surfaced all five stale references in one pass instead of two.
-- **Feedback-loop gap analysis** — no gap; verification ran incrementally (baseline `check`/`lint` before edits, then `check`/`test`/`lint`/`fallow dead-code`/`fallow dupes` after each step, then the reviewer), not bunched at the end.
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added step 5 to "Check for prior session context": a release-batch tail plan must read earlier batch members' retros for deferred work and fold it into `Module-Level Changes`.
-2. `.pi/skills/pre-completion/SKILL.md` — added a line under "Overall: WARN": when a WARN names stale references to a deleted symbol, grep the file exhaustively for every instance before fixing, to avoid a second WARN round.
-
-### Post-commit follow-up — stale `README.md`
-
-After the retro commit, the user caught that `packages/pi-subagents/README.md` still documents the removed `/agents` command and conversation viewer and omits `/subagents:settings` and `/subagents:sessions` — a published, user-facing miss that shipped in `pi-subagents-v18.0.0`.
-
-- `missing-context` (cross-session, user-caught) — the README was stale from #442's deletions (it documents `/agents`, not the module `agent-menu.ts`) and was never folded into #442's or #441's plan.
-  The pre-completion reviewer's README check keyed on module names, not the command names a README actually documents, so a module-name match missed it.
-  Impact: a user-facing doc defect shipped to npm; tracked as a follow-up in #470 (recommend `/plan-issue`).
-
-3. Filed #470 to rewrite the stale `README.md` (removed `/agents` surface, missing `/subagents:` commands, eject UI gone).
-4. `.pi/prompts/plan-issue.md` — `Module-Level Changes`: when a change adds, removes, or renames a slash command or user-facing feature, grep `packages/<PKG>/README.md` for the command/feature name (the `src/`-symbol grep misses command names).
-5. `.pi/agents/pre-completion-reviewer.md` — broadened the forward-doc README check: when a change removes or renames a slash command or user-facing feature, grep the package `README.md` for the command/feature name, not just module names.

package/docs/retro/0442-dissolve-agents-conversation-viewer.md

@@ -1,108 +0,0 @@
----
-issue: 442
-issue_title: "pi-subagents: dissolve /agents and remove the conversation-viewer subtree"
----
-
-# Retro: #442 — pi-subagents: dissolve /agents and remove the conversation-viewer subtree
-
-## Stage: Planning (2026-06-23T18:06:31Z)
-
-### Session summary
-
-Planned Phase 19 Step 5: dissolve the `/agents` command and delete the conversation-viewer subtree (`agent-menu.ts`, `conversation-viewer.ts`, `message-formatters.ts`, plus their three tests), dewire `index.ts`.
-Investigation surfaced a blocker the issue overlooked — a bidirectional type cycle between the hub and its leaves — and the operator chose a tidy-first resolution.
-Plan committed at `packages/pi-subagents/docs/plans/0442-dissolve-agents-conversation-viewer.md`; this is a `/build-plan` (no red→green cycles), batched for release with the tail [#441].
-
-### Observations
-
-- Key finding: `agent-creation-wizard.ts` and `agent-config-editor.ts` (which survive until [#441]) both `import type { MenuUI } from "#src/ui/agent-menu"` and use it throughout, while the hub value-imports the wizard/editor classes — a bidirectional cycle.
-  Deleting either subtree first breaks `tsc --noEmit` (type-checks `src` + `test`).
-  The issue's "pure orphans" premise holds for runtime reachability but not at the type level.
-- Flipping the [#442]/[#441] order does **not** fix it (cycle is bidirectional) — surfaced this directly when the operator asked about step ordering.
-- Operator decision via `ask_user`: keep two commits, relocate `MenuUI` to a surviving `src/ui/menu-ui.ts` first (tidy-first).
-  Rejected alternatives: merge [#441] into [#442] (one deletion commit), or inline a throwaway `MenuUI` into the doomed leaves.
-- Operator confirmed release timing: do not release until both [#442] and [#441] land — marker is `mid-batch — defer (batch "dissolve-agents")`, tail is [#441].
-- `menu-ui.ts` is intentionally transient (one issue's lifespan); it keeps two live consumers (wizard/editor) immediately, so no fallow dead-code flag; [#441] deletes it with its consumers.
-- Verified no collateral: `FsAgentFileOps` stays off the dead-code list because its own test still imports it; `subagents-settings.ts` defines its own `SubagentsSettingsUI` (no `MenuUI` coupling); `ui-stubs.ts`'s `makeMenuUI` is structurally typed; `join`/`buildParentSnapshot` become dead `index.ts` imports and are removed; deleting the consumers orphans no `display.ts` export.
-- Change is breaking (the `/agents` command disappears) → deletion commit is `feat(pi-subagents)!:` with a `BREAKING CHANGE:` footer naming `/subagents:settings`, `/subagents:sessions`, and the background widget (verified the real registered command names, not the architecture's proposed `/subagents-settings`).
-- Deferred the holistic architecture-doc refresh (Mermaid domain diagram, complexity/health tables, Phase-19-to-history migration) to the batch tail [#441] to avoid double-editing tables that [#441] also touches; [#442] keeps only the current-state file tree, the Step 5 `Outcome:` annotation, and the SKILL.md UI count accurate.
-
-[#441]: https://github.com/gotgenes/pi-packages/issues/441
-[#442]: https://github.com/gotgenes/pi-packages/issues/442
-
-## Stage: Implementation — Build (2026-06-23T19:30:00Z)
-
-### Session summary
-
-Executed both plan commits (Step 1: extract `MenuUI`; Step 2: delete hub+viewer+formatters and dewire `index.ts`).
-A mid-session diversion investigated the commitlint `#N`-in-body false positive (issue [#4099]), determined it is still present in v21.0.2 despite the issue being closed, and removed the `--strict` flag from `prek.toml` so the warning no longer blocks commits.
-Pre-completion reviewer returned PASS.
-
-### Observations
-
-- **Unplanned fallow finding:** after deleting `agent-menu.ts`, `showAgentDetail` (`agent-config-editor.ts`) and `showCreateWizard` (`agent-creation-wizard.ts`) lost their only external callers and became unused class members.
-  The plan's risk analysis covered unused *files* (`FsAgentFileOps`) but not unused class *methods*.
-  Added `// fallow-ignore-next-line unused-class-member` suppressions with a comment pointing to [#441] as the removal commit.
-  Future plans for hub-deletion steps should explicitly check whether public methods on surviving leaf classes lose their only caller.
-- **Unplanned commitlint diversion:** bodies with `#N` mid-sentence in multi-paragraph messages are still misidentified as footer tokens by commitlint v21.0.2 despite issue [#4099] being closed COMPLETED on 2026-06-02 with no linked PR.
-  Removed `--strict` from the `commit-msg` hook in `prek.toml` so the false-positive is a non-blocking warning; updated `AGENTS.md` accordingly.
-  This also required untangling a bad commit (the `git rm`'d pi-subagents files were swept into the commitlint fix commit) via `git reset HEAD~1` + selective re-staging.
-- **Commit message refinement:** learned empirically that `#N` appearing in a wrapped body line (near end of line) triggers the false positive even in a single-paragraph body; a two-paragraph body with `#N` in the second paragraph was the original failure mode.
-  Workaround before the `--strict` removal: keep `#N` out of body prose; use `Refs #N` as a true footer with a blank-line separator.
-- Pre-completion reviewer: PASS — all deterministic checks green; doc-staleness WARNs (Mermaid domain diagram, structural tables, Phase 19 history) are intentional mid-batch deferred work per the plan's Non-Goals, to be resolved at the batch tail [#441].
-
-[#4099]: https://github.com/conventional-changelog/commitlint/issues/4099
-
-## Stage: Final Retrospective (2026-06-23T20:05:13Z)
-
-### Session summary
-
-Shipped Phase 19 Step 5 across plan → build → ship: extracted `MenuUI` to break a bidirectional type cycle, deleted the `/agents` hub plus the conversation-viewer subtree, and dewired `index.ts`.
-The release was correctly deferred at ship time per the `mid-batch — defer` marker (batch tail is [#441]).
-The session's dominant friction was an unplanned commitlint diversion that produced a blunt fix, then a superseding surgical fix, a bad-commit untangle, and a new tracking issue ([#468]).
-
-### Observations
-
-#### What went well
-
-1. The Planning `ask_user` gate caught the hub↔leaf bidirectional type cycle before any code was written and produced a clean tidy-first plan (relocate `MenuUI` first), so the two implementation commits were each green — no broken-commit sequence.
-2. The commitlint claim was verified empirically by running `commitlint` against crafted test messages, not by trusting the closed-issue status — this confirmed [#4099] was closed `COMPLETED` without a shipped fix and that the false positive still fired in `v21.0.2`.
-3. Incremental verification: `pnpm run check`/`lint`/`test`/`fallow dead-code` ran after each implementation step, so the unused-class-member finding surfaced at the right step rather than at the end.
-
-#### What caused friction (agent side)
-
-1. `premature-convergence` — the first commitlint fix (`9b60c943`, remove `--strict`) was blunt: dropping `--strict` silences every warning-level rule, including the load-bearing malformed-`!`-header rejection (Refs #457).
-   The surgical fix (`40189cc4`, disable only `footer-leading-blank`, keep `--strict`) only emerged from a separate branch reconsideration.
-   Impact: one superseded `fix(commitlint):` commit now permanent in pushed history; a #457 regression was avoided only because the blunt fix was reconsidered before the batch released.
-2. `other` (git workflow) — `git rm` pre-stages its deletions, so a later `git add prek.toml AGENTS.md && git commit` for the commitlint fix swept the already-staged `/agents` deletions into the wrong commit.
-   Required `git reset HEAD~1` plus selective re-staging to untangle.
-   Impact: ~4 extra tool calls; caught immediately, no lasting damage.
-3. `missing-context` / unused-tool — determining the upstream commitlint issue state took several rounds of `web_search` + `fetch_content` until the user said "Remember you have access to the `gh` CLI, too"; `gh issue view 4099 --repo conventional-changelog/commitlint` then returned the authoritative state (`CLOSED`/`COMPLETED`, no linked PR) in one call.
-   Impact: several wasted research rounds; user-caught.
-4. `missing-context` (minor) — the plan's risk analysis covered unused *files* (`FsAgentFileOps`, kept live by its test import) but not unused class *methods*; deleting the hub orphaned `showAgentDetail` and `showCreateWizard`, tripping `fallow dead-code`.
-   Impact: low — caught by the gate, resolved with two `fallow-ignore-next-line unused-class-member` suppressions pointing at [#441].
-
-#### What caused friction (user side)
-
-1. The agent reached for `web_search`/`fetch_content` to check a GitHub issue's state instead of `gh`; the user had to point at an available tool.
-   Opportunity: reach for `gh issue view`/`gh pr view` first for GitHub issue/PR state, including upstream repos.
-2. The user supplied the steer toward a surgical fix ("prefer surgical fixes over blunt ones").
-   Opportunity: a standing rule about disabling the single offending rule rather than the enforcement mode could have produced the surgical fix on the first pass.
-
-### Diagnostic details
-
-- **Model-performance correlation** — the `pre-completion-reviewer` subagent ran on `anthropic/claude-sonnet-4-6` (per its agent frontmatter), appropriate for judgment-heavy review; the implementation ran on `claude-opus-4-8`.
-  No quality mismatch.
-  The many `model_change` entries are transient UI cycling (no assistant turn under most), not real reassignments.
-- **Escalation-delay tracking** — the upstream-issue-state investigation ran ~6 consecutive `web_search`/`fetch_content` calls before the `gh` reminder; one `gh issue view` would have resolved it immediately.
-- **Unused-tool detection** — `gh` was available throughout but not used for upstream issue state until prompted.
-- **Feedback-loop gap analysis** — no gap; verification ran incrementally after each step.
-
-[#468]: https://github.com/gotgenes/pi-packages/issues/468
-
-### Changes made
-
-1. `AGENTS.md` (`## Commits`) — tightened the `footer-leading-blank` note from ~62 words to rule + `Refs #468`, dropping the parser-variant list and the two upstream issue numbers (now here and in [#468]).
-2. `AGENTS.md` (`## Commits`) — added a single-rule-vs-mode principle: disable the single offending lint rule (`[0]`), not the `--strict` enforcement mode that gates the others.
-3. `AGENTS.md` (`## Workflow`) — added a bullet to use `gh issue view N --repo owner/repo` for GitHub issue/PR state instead of web search.
-4. `AGENTS.md` (`## Commits`, git mechanics) — added a note that staged `git rm` deletions ride along with the next `git commit` even when only unrelated paths are `git add`ed; commit with an explicit pathspec or check `git status` first.

package/docs/retro/0443-consolidate-remaining-test-clone-families.md

@@ -1,28 +0,0 @@
----
-issue: 443
-issue_title: "pi-subagents: consolidate remaining test clone families"
----
-
-# Retro: #443 — pi-subagents: consolidate remaining test clone families
-
-## Stage: Planning (2026-06-23T00:00:00Z)
-
-### Session summary
-
-Planned Phase 19 Step 7 (test-clone consolidation) for `pi-subagents`.
-Re-ran `fallow dupes` against current `main` and found the live state diverged from the issue's Phase-18-era snapshot: line numbers shifted after the terminal cut ([#441]/[#442]) and new Phase-19 UI test files added clones the issue never named.
-Wrote `packages/pi-subagents/docs/plans/0443-consolidate-remaining-test-clone-families.md` and committed it.
-
-### Observations
-
-- The issue is the operator's own, but the proposed "extract a shared fixture" list was substantially invalidated by live evidence: several named targets (`resolveSpawnConfig`, `assembleSessionConfig`, `schedule`) are the repeated *system-under-test act*, which the `testing` skill says not to wrap to clear a clone metric.
-- `ask_user` gate settled two decisions: **guardrail-first** (leave act-clones, extract only genuine fixtures) and **full live set** (include the new Phase-19 UI clones, notably the byte-identical `makeNavigable` factory duplicated across `session-navigation.test.ts` and `session-navigator.test.ts`).
-- Eight genuine extraction targets identified; clearing them drops the count from 16 to 8 — below the issue's `≤ 10` target — without wrapping any act.
-  The four primary UI/lifecycle extractions alone reach 10.
-- Six residual families are documented as intentional act-clones in Non-Goals so a future fallow pass reads them as deliberate, not oversight.
-- Convention confirmed: cross-file helpers go in `test/helpers/<name>.ts` (imported via `#test/helpers/<name>`) with a companion `<name>.test.ts`; single-file helpers stay local.
-- Invariants at risk flagged: the `#423` reactive-consumer assertion in `session-navigator.test.ts` must stay in the test body (not absorbed by the `renderCapturedOverlay` helper), and the resume-events emitter must preserve exact usage/compaction payloads.
-- `Release: independent` — ships on its own; no batch coupling.
-
-[#441]: https://github.com/gotgenes/pi-packages/issues/441
-[#442]: https://github.com/gotgenes/pi-packages/issues/442

package/docs/retro/0444-shrink-widget-to-background-agents.md

@@ -1,81 +0,0 @@
----
-issue: 444
-issue_title: "pi-subagents: shrink the agent widget to background runs only"
----
-
-# Retro: #444 — pi-subagents: shrink the agent widget to background runs only
-
-## Stage: Planning (2026-06-20T18:47:05Z)
-
-### Session summary
-
-Produced a numbered implementation plan for Phase 19 Step 3: shrink `AgentWidget` to background agents only by funneling both `manager.listAgents()` call sites (`update()` and `renderWidget()`) through a single private `listBackgroundAgents()` accessor that applies `record.invocation?.runInBackground === true` once at the source.
-Confirmed the change is single-package (`pi-subagents`), non-breaking, and `Release: independent` per the architecture roadmap.
-
-### Observations
-
-- Issue author is the operator (`gotgenes`) and the proposed change is unambiguous, so the `ask-user` gate was skipped.
-  The design is a legitimate improvement (removes the two-site duplication and fixes the latent inconsistency), not procedure-splitting.
-- `widget-renderer.ts` needs **no** code change — it has no foreground-specific path; filtering at the data source in `agent-widget.ts` is sufficient.
-  Listed in Module-Level Changes only to record the verification.
-- Key risk is mass test breakage: the existing `update()`-driven fixtures (two `makeWidget` helpers + the projection test's `createTestSubagent`) would all be filtered out once the predicate lands.
-  Mitigated with a tidy-first TDD step 1 that adds `invocation: { runInBackground: true }` to fixtures while the filter does not yet exist (inert), so step 2 only adds new tests.
-- `assembleWidgetState` pure-function tests are unaffected — they call the function directly with `AgentSummary[]`, bypassing the accessor.
-- Verified `clearWidget`'s stale-purge has no regression: foreground agents are never seeded into `finishedTurnAge`, so purging against the background-only list is correct.
-- Doc grep surfaced one stale prose line (`README.md:64` "showing all active agents"); SKILL.md and `comparison-with-upstream.md` references remain accurate.
-- Deferred (Open Question): relabeling the widget heading `Agents` → `Background agents` — out of scope for this issue.
-
-## Stage: Implementation — TDD (2026-06-20T19:47:34Z)
-
-### Session summary
-
-Executed all three planned TDD cycles plus one reviewer-driven cleanup: (1) `test:` migrated the `agent-widget.test.ts` fixtures to a background invocation, (2) `feat:` added the private `listBackgroundAgents()` accessor and routed both `update()` and `renderWidget()` through it, (3) `docs:` updated `README.md` and marked roadmap Step 3 ✅.
-Test count went from 24 to 26 in `agent-widget.test.ts` (two new background-only filtering tests); full pi-subagents suite is 1064 passing.
-
-### Observations
-
-- The tidy-first fixture migration worked exactly as planned — adding `invocation: { runInBackground: true }` was inert (suite stayed green) until the filter landed, so step 2 was a pure addition with no fixture churn.
-- New-test fixtures default the shared `makeWidget` helper to background invocation via `{ invocation: { runInBackground: true }, ...a }`, letting per-agent `invocation` override for the mixed/foreground cases in the new `describe` block.
-- `widget-renderer.ts` needed no change, as the plan predicted — the filter at the single `listBackgroundAgents()` funnel is sufficient.
-- Pre-completion reviewer: PASS.
-  One non-blocking naming WARN — `clearWidget`'s `allAgents` parameter and JSDoc were stale after the refactor (it now receives only background agents); fixed in a follow-up `refactor:` commit (`backgroundAgents`).
-  Landed as a separate commit rather than amending the feat commit because HEAD was already the `docs:` commit and the fix must not land in a `docs:` commit.
-- All gates green: `pnpm run check`, root `pnpm run lint`, full vitest (1064), `pnpm fallow dead-code`.
-
-## Stage: Final Retrospective (2026-06-20T22:41:58Z)
-
-### Session summary
-
-Shipped Phase 19 Step 3 end-to-end across three stages (plan → TDD → ship) in one continuous session, releasing `@gotgenes/pi-subagents` v17.2.0.
-The change funnels both `manager.listAgents()` call sites through a single `listBackgroundAgents()` accessor so the above-editor widget shows only background agents.
-Execution was unusually clean: no rabbit holes, no user corrections, one reviewer-caught naming miss resolved in a single follow-up commit.
-
-### Observations
-
-#### What went well
-
-- Tidy-first preparatory step paid off as designed.
-  TDD step 1 (`test:` migrate fixtures to background invocation) was inert until the filter landed, turning the behavior change in step 2 into a pure addition with zero fixture churn mid-cycle.
-  This is the `code-design` skill's "make the change easy, then make the easy change" applied to a test suite — worth reusing whenever a new predicate will retroactively exclude existing fixtures.
-- The pre-completion reviewer caught semantic drift that all four deterministic gates missed.
-  `tsc`, `pnpm run lint`, vitest (1064), and `pnpm fallow dead-code` all passed the stale `clearWidget(allAgents)` parameter — a name whose meaning narrowed to background-only but which no tool flags, because a misleading-but-valid identifier is neither a type nor a lint error.
-  This is the reviewer's distinct value: naming/comment staleness after a rename.
-
-#### What caused friction (agent side)
-
-- `other` (incomplete rename) — during the `feat:` step I renamed the local `allAgents` → `backgroundAgents` in `update()` but left the `clearWidget` parameter (a separate scope receiving the same value) named `allAgents`, along with its JSDoc.
-  Impact: one extra `refactor:` commit (`319e7df3`); ~2 minutes.
-  No rework to logic.
-  Reviewer-caught, not self-caught.
-
-#### What caused friction (user side)
-
-- None.
-  The operator delegated the full plan/TDD/ship/retro workflow and it ran without correction or mid-course steering.
-  No earlier-context opportunity identified.
-
-### Changes made
-
-1. Added this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0444-shrink-widget-to-background-agents.md`.
-
-No `AGENTS.md` or prompt changes: the one friction point (an incomplete rename) was reviewer-caught with trivial cost, and the wins (tidy-first fixture migration, pre-completion reviewer value) are already covered by the `code-design` and `testing` skills — nothing actionable to encode.