@gotgenes/pi-subagents 18.0.0 → 18.0.2

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,45 +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).

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/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.

package/docs/retro/0445-native-session-navigation.md

@@ -1,122 +0,0 @@
----
-issue: 445
-issue_title: "pi-subagents: implement native session navigation for any subagent (live or completed)"
----
-
-# Retro: #445 — pi-subagents: implement native session navigation for any subagent (live or completed)
-
-## Stage: Planning (2026-06-22T00:00:00Z)
-
-### Session summary
-
-Produced `docs/plans/0445-native-session-navigation.md`, a sliced plan for Phase 19 Step 4.
-The operator (issue author) chose Pi's per-entry TUI-component renderer as the eventual target but explicitly invited a Kent Beck "make the change easy, then make the easy change" breakdown into incremental, releasable additions, and chose `manager.listAgents()`-only as the candidate set.
-The plan scopes #445 to the first releasable vertical slice — full list → pick → read-only live transcript using `serializeConversation` text rendering behind a renderer-agnostic `TranscriptSource` seam — and names two follow-ups (TUI-component renderer; evicted-agent file source).
-
-### Observations
-
-- **Two `ask_user` rounds drove scope.**
-  Round 1: renderer choice (text vs TUI components) and candidate-set scope.
-  Round 2: decomposition strategy.
-  The operator's note on round 1 ("If this sounds large, it's probably because it is... what would Kent Beck do") reframed the whole plan from one big issue into a sliced first release.
-- **Key architectural finding — the file-snapshot branch is unreachable in #445.**
-  `SubagentManager.removeRecord` calls `record.disposeSession()` then `agents.delete(id)` atomically, and `disposeSession()` does not null `subagentSession`.
-  So no record in `listAgents()` is ever session-disposed; with the `listAgents()`-only candidate set, every listed session-ready record has a live session, and the dual-source "evicted/untracked → file" branch has no caller.
-  Implementing it now would be dead code that fails the `fallow dead-code` gate.
-  This sharpened the slice: #445 ships the **live source only** behind the seam.
-- **Type-boundary plan.** `AgentMessage` is not in the `@earendil-works/pi-coding-agent` barrel and `@earendil-works/pi-agent-core` is not a dependency, so the plan derives `SessionMessage = SessionContext["messages"][number]` from the barrel-exported `SessionContext` rather than adding a dep. `serializeConversation` takes a mutable `Message[]`, so the renderer spreads (`serializeConversation([...messages])`); `AgentMessage`→`Message` assignability is flagged as a TDD step-2 `pnpm run check` verification with a typed-adapter fallback.
-- **Seam justifies its weight via testability, not just the follow-up.** `TranscriptSource` + narrow `NavigableSubagent` interfaces let the pure module be unit-tested with light stubs (no full `Subagent`/`TUI`/`AgentSession`), and decouple the renderer (text→components) from sourcing (live→file) for the two named follow-ups.
-- **Doomed-code avoidance.**
-  The navigator must not import `message-formatters.ts` or `conversation-viewer.ts` (both deleted in Step 5, [#442]); the streaming indicator is a small local helper and the transcript text is Pi's `serializeConversation`.
-- **Open item for ship time:** the architecture roadmap's Step 4 description currently scopes full dual-source + components as one step and will need rescoping to match the slice, plus filing the two follow-up issues.
-  Command name `subagent-sessions` is proposed but flagged confirmable.
-- Release: ship independently (roadmap Step 4 is `Release: independent`, spike-gated; not part of the "dissolve-agents" batch).
-
-## Stage: Implementation — TDD (2026-06-22T18:03:26Z)
-
-### Session summary
-
-Implemented the sliced #445 in three TDD cycles: (1) the typed `agentMessages` accessor (`SessionMessage` on `SubagentSession`/`Subagent`); (2) the pure `session-navigation.ts` (selection, `liveSource`, `renderTranscriptLines`); (3) the `session-navigator.ts` overlay + `/subagent-sessions` command + `index.ts` wiring.
-Test count went 1064 → 1084 (+20).
-Pre-completion reviewer returned PASS.
-
-### Observations
-
-- **`AgentMessage` is NOT assignable to `serializeConversation`'s `Message[]`** (the plan's flagged risk materialized): `AgentMessage` is a superset adding session-display variants like `BashExecutionMessage`.
-  Applied the planned mitigation — a private `toMessages` adapter casting via `as unknown as Parameters<typeof serializeConversation>[0]` (`Message` is not re-exported from the `@earendil-works/pi-ai` barrel, so the type is referenced through the function signature rather than imported by name).
-- **`SessionContext` name collision:** `types.ts` already declares a local `SessionContext` interface, so the SDK import is aliased — `import type { SessionContext as SdkSessionContext }` — and `SessionMessage = SdkSessionContext["messages"][number]`.
-- **`describeActivity` survives in `display.ts`** (not the doomed `message-formatters.ts`), so the streaming indicator reuses it — the navigator imports neither doomed module, as planned.
-- **File-snapshot branch confirmed unreachable and omitted:** with the `listAgents()`-only candidate set, no listed record is ever session-disposed (dispose-and-delete are atomic), so the live source is always valid; implementing the file branch would have been dead code.
-  `fallow dead-code` is clean.
-- **Minor deviation:** `test/helpers/mock-session.ts` gained an `agentMessages` getter on the session stub (needed for the `Subagent.agentMessages` delegation test) — a small fixture addition not itemized in the plan's Module-Level Changes.
-- **Two lint nits caught by the pre-commit hook** (both per the testing skill): an unnecessary optional chain on a destructured array element, and an unnecessary `!` on `mock.calls[0][0]` — both fixed inline.
-- **Architecture doc:** added a "Landed ([#445], sliced)" note to Step 4; did **not** mark the step `✅` because the component renderer and evicted-agent file source are deferred follow-ups.
-  `SKILL.md` `ui/` module count (10 → 12) left for a later Phase 19 doc-sync, per the plan.
-- **Reviewer verdict: PASS.**
-  Two WARN notes, both intentional and plan-sanctioned: Step 4 heading unchecked (correct for a partial slice) and the deferred `SKILL.md` count.
-- **Open at ship time:** confirm command name `subagent-sessions`; file the two follow-up issues (component renderer; evicted-agent file source).
-
-## Stage: User Note (2026-06-22T18:26:37Z)
-
-When new issues are identified during planning, file them before leaving the planning stage rather than deferring to ship time.
-Two motivations: the planning session uses a very capable model, and it already has all the context needed to write the issues well.
-Applied here: the two follow-up issues (#462 renderer upgrade, #463 file-snapshot source) were identified during planning but filed only at ship time — they should have been created at the end of the planning commit instead.
-
-## Stage: Final Retrospective (2026-06-22T18:28:31Z)
-
-### Session summary
-
-One continuous session carried #445 from planning through TDD, ship, and a mid-session retro note.
-It delivered the sliced Phase 19 Step 4 — the `/subagent-sessions` command, the live `TranscriptSource`, and the typed `agentMessages` accessor — across three `feat:` commits plus docs, released as `pi-subagents` v17.3.0, with two follow-ups (#462, #463) filed at ship.
-Execution was notably clean: the plan anticipated both hard risks, and every implementation slip was absorbed by the feedback loops within its active TDD cycle.
-
-### Observations
-
-#### What went well
-
-1. **The plan pre-empted the two hardest risks.**
-   `AgentMessage`→`Message` non-assignability and the unreachable file-snapshot branch were both called out in planning and both materialized exactly as predicted; the planned mitigations (the `toMessages` adapter; shipping the live source only) applied with zero rework.
-2. **The `TranscriptSource` seam earned its keep.**
-   The pure `session-navigation.ts` was unit-tested with light stubs (no full `Subagent`/`TUI`/`AgentSession`), and the seam cleanly hosts both deferred follow-ups — testability justified it independent of the follow-ups.
-3. **Tight, incremental feedback loops.**
-   Per-cycle affected-file test runs, `pnpm run check` after every type-touching step, and full suite + lint + `fallow dead-code` after the last step caught every slip within seconds.
-4. **Two `ask_user` rounds during planning converted a large issue into a releasable slice** (the operator's Kent Beck nudge) — the central design win of the issue.
-
-#### What caused friction (agent side)
-
-1. `missing-context` — wrote test assertions before checking helper behavior: `formatMs` yields `3.0s` not `3s`, `getDisplayName` falls back to `Agent`, `TOOL_DISPLAY` keys are lowercase, and `AgentTypeRegistry` takes `() => new Map()` not `() => []`.
-   Impact: ~4 assertion fixes within one Green iteration; no rework beyond the cycle.
-2. `missing-context` — `SessionContext` name collision: imported the SDK type into `types.ts` without noticing a local `SessionContext` interface already existed.
-   Impact: one aliasing edit (`SdkSessionContext`), caught immediately by biome `noRedeclare`.
-3. `other` (mechanical) — a stray `}` when wrapping a new `describe` block (AGENTS.md already warns about brace-pair edits), and `SessionMessage` imported from the wrong module in the navigator test.
-   Impact: one fix each, caught by autoformat and `tsc`.
-4. `instruction-violation` (self-identified, hook-caught) — two lint nits the `testing` skill already documents: an unnecessary optional chain and an unnecessary `!` on `mock.calls[0][0]`.
-   Impact: two inline fixes; no rework.
-
-None of the agent-side slips caused rework beyond their active TDD cycle — the autoformat/biome/`tsc`/vitest/pre-commit loops absorbed all of them.
-
-#### What caused friction (user side)
-
-1. The dominant cross-session finding (recorded separately as the User Note stage): follow-up issues identified during planning (#462, #463) were filed only at ship time.
-   The workflow itself encodes the deferral — the plan said "file at ship time" and `/ship-issue` step 4c creates them.
-   The operator wants them filed during planning, while the capable planning model still holds full context.
-   Opportunity: move follow-up creation into `/plan-issue`.
-
-### Diagnostic details
-
-- **Model-performance correlation** — the only subagent dispatch was the `pre-completion-reviewer` on `anthropic/claude-sonnet-4-6`, a judgment-heavy review task; appropriate match.
-  Planning ran on a capable model, which the operator explicitly values.
-  No mismatch.
-- **Escalation-delay tracking** — no rabbit-holes; the longest same-area sequence was 4 assertion fixes inside one Green iteration (under the 5-call flag).
-- **Unused-tool detection** — the `missing-context` slips were caught trivially by running tests; reading `display.ts` helpers first would have pre-empted them, but the cost was negligible and no Explore/`colgrep` dispatch was warranted.
-- **Feedback-loop gap analysis** — verification ran incrementally and completely (per-cycle tests, `check` after type changes, full gate after the last step); no gap.
-  This is a win, not a gap.
-
-### Changes made
-
-Moved follow-up issue creation from ship time to planning time, with the backstop relocated to pre-completion (operator-directed):
-
-1. `.pi/prompts/plan-issue.md` — added a `## File follow-up issues` section before `## Commit`: file plan-named follow-ups during planning with `gh issue create` and record each number in the plan; nothing speculative.
-2. `.pi/agents/pre-completion-reviewer.md` — added checklist section `2i. Planned follow-up issues` and its report stanza: WARN when the plan names a follow-up but records no issue number; also added the case to the severity model's WARN list.
-3. `.pi/prompts/ship-issue.md` — removed step `4c. Create planned follow-up issues` (follow-ups are now filed during planning; the close comment in step 5 references the recorded numbers).
-4. `AGENTS.md` — extended the pre-completion-reviewer coverage enumeration to include planned follow-up filing.