@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/retro/0265-born-complete-subagent-session.md

@@ -1,97 +0,0 @@
----
-issue: 265
-issue_title: "Born-complete child execution; dissolve the runner"
----
-
-# Retro: #265 — Born-complete child execution; dissolve the runner
-
-## Stage: Planning (2026-05-30T02:30:00Z)
-
-### Session summary
-
-Produced the implementation plan for dissolving the `agent-runner` and introducing a born-complete `SubagentSession`.
-Most of the session was a design dialogue that resolved naming, the turn-loop home, a discovered Law-of-Demeter cluster, and the workspace-ownership fork before any plan text was written.
-Plan committed as `0265-born-complete-subagent-session.md`; a side-quest filed #277 and added an architecture-doc breadcrumb for discovered debt.
-
-### Observations
-
-- Vocabulary was pinned down explicitly because "execution" is overloaded: granular execution = one turn loop (one `session.prompt()`, run or resume); the born-complete object spans the whole session lifetime (run + resumes).
-  The object is named `SubagentSession` (matches the existing `SubagentType` / `SubagentSessionDir` / `SubagentSessionRegistry` family; cohesive with the deferred `Agent` → `Subagent` rename).
-  Turn driving is `runTurnLoop` / `resumeTurnLoop`; resume is *not* an SDK `session.resume()` — it is `session.prompt()` again on the retained session.
-- The turn-loop home is **on `SubagentSession`** (methods), not inline on `Agent` and not a free function.
-  The user caught that `subagent.driveTurnLoop(subagentSession.session, …)` is a Law-of-Demeter reach-through; putting the behavior on the object that owns the `AgentSession` is both LoD-correct and more testable (satisfying the user's conditional "inline only if straightforward to test").
-- Workspace ownership locked to **Option A** (session-only `SubagentSession`; `Agent` keeps workspace prepare/dispose).
-  Decisive reasoning: the workspace and the session have genuinely different lifetimes (workspace dies at run-completion to fold its `resultAddendum` into the result; session survives to cleanup for resume + the new registry boundary), so they are different resources.
-  Option B would fuse them into one object needing two teardown methods, and would thread the `WorkspaceProvider` + prepare-context through the factory just to call `prepare()` — a parameter-relay smell the user flagged.
-  The factory takes a resolved `cwd` value (used directly), never the provider.
-- Worktrees are already out of the core (#263) — confirmed zero git code in `pi-subagents/src/` (only doc comments).
-  The A/B fork is purely about how the core sequences its abstract `WorkspaceProvider` seam; `@gotgenes/pi-subagents-worktrees` is untouched.
-- Registry semantics: moving `disposed` from run-completion to true session disposal makes resume executions registry-detected (closes the gap deferred from #261).
-  The permission system's subscription code does not change; only *when* `disposed` fires moves.
-  Edge case planned: `createSubagentSession` must dispose on a post-`session-created` failure to avoid a registry leak.
-- Discovered debt captured (the user's "it is in doing the work that we discover the work to be done"): filed #277 for the remaining `agent.session` reach-throughs (steer buffer-or-deliver duplicated across `steer-tool` + `service-adapter`, conversation viewing, resume-readiness guards) and added a "Session encapsulation debt (Law of Demeter)" subsection to `architecture.md` (commit `038a1283`).
-  `SubagentSession` exposes a `.session` accessor in #265 so observer wiring + consumers keep working; #277 retires those.
-- Two follow-ups deliberately deferred and noted in the plan's Non-Goals / Open Questions: the `Agent` → `Subagent` class rename (mechanical, ~19 files — separate issue) and resume-aware workspaces (a worktree's lifetime is one turn loop; worktree + resume is degenerate today).
-- The change is non-breaking (no `feat!:`): the dissolved types (`RunOptions`, `RunResult`, `AgentRunner`) are internal, so `public.d.ts` is unaffected.
-  TDD order uses lift-and-shift across 7 steps to keep each commit compiling; transient duplication of the turn-loop helpers/assembly exists between steps 3–5 and is deleted in step 6.
-
-## Stage: Implementation — TDD (2026-05-29T22:18:00Z)
-
-### Session summary
-
-Executed all 7 TDD steps from the plan via lift-and-shift, one commit per step, each leaving the suite green.
-Introduced `SubagentSession` (`runTurnLoop`/`resumeTurnLoop`/`steer`/`dispose`) and the `createSubagentSession()` assembly factory, swapped `Agent`/`AgentManager`/`index.ts` onto them, then deleted `agent-runner.ts` + `execution-state.ts` and the three runner test files.
-Package test count went 951 → 960 (net +9: new `subagent-session`/`create-subagent-session`/`turn-limits` suites added, the redundant runner suites deleted).
-Pre-completion reviewer: initial FAIL (MD060 table alignment in SKILL.md, auto-fixed by `rumdl fmt`), PASS on re-check after fix + stale doc cleanup.
-
-### Observations
-
-- The plan sketch's `TurnLoopOptions` listed only `maxTurns`/`graceTurns`/`signal`, but preserving the old `runAgent` precedence `per-call ?? agentMaxTurns ?? defaultMaxTurns` required threading `defaultMaxTurns` through `TurnLoopOptions` and storing `agentMaxTurns` + `parentContext` in `SubagentSession` meta (both are session-level facts known at creation).
-  This is a correctness-preserving deviation, well covered by three precedence tests plus a parent-context-prepend test in `subagent-session.test.ts`.
-- The atomic call-site swap (step 5) touched more test files than the plan's step-5 list anticipated: every tool/service test that set `record.execution = { session, outputFile }` (`steer-tool`, `agent-tool`, `background-spawner`, `foreground-runner`, `get-result-tool`, `service-adapter`) had to migrate to `record.subagentSession = toSubagentSession(createSubagentSessionStub(...))`.
-  Added `createSubagentSessionStub`/`toSubagentSession` to `mock-session.ts` so the migration was a one-line change per call site; the stub's `steer`/`dispose` delegate to the underlying `MockSession` so existing session-spy assertions kept working unchanged.
-- `disposed` moved from `runAgent`'s `finally` (run-completion) to `SubagentSession.dispose()`, invoked by `AgentManager` via the new `Agent.disposeSession()` (routing both `record.session?.dispose?.()` call sites at `agent-manager.ts:235,309`).
-  The full cross-package suite confirms the permission system (1504 tests) is unaffected — its subscription code did not change, only *when* `disposed` fires.
-- Test-helper gotcha: `makeSubagentSession`'s `outputFile` default initially swallowed an explicit `undefined` via `?? default`; fixed with an `"outputFile" in metaOverrides` presence check (the testing-skill "Partial spread erases explicit undefined" family).
-- `print-mode.test.ts` now mocks `#src/lifecycle/create-subagent-session` (was `#src/lifecycle/agent-runner`); `index.ts` wraps the factory as `(params) => createSubagentSession(params, deps)`, so the module mock still intercepts it.
-- fallow stayed clean throughout — the transient duplication of IO interfaces + turn-loop helpers between `agent-runner.ts` and the new modules (steps 3–5) was removed in step 6 before the pre-completion gate ran.
-- Reviewer's two minor non-blocking notes: SKILL.md Session-domain count now lists `conversation.ts` but still omits the pre-existing `content-items.ts` (drift predates this issue); `create-subagent-session.ts` keeps an accurate "old runner's runAgent()" provenance comment.
-
-## Stage: Final Retrospective (2026-05-30T13:37:00Z)
-
-### Session summary
-
-Shipped issue #265 (`pi-subagents-v13.1.0`) and ran the retrospective across all three stages (planning, TDD implementation, ship).
-The implementation landed cleanly in 7 TDD commits + 1 docs commit; test count 951 → 960.
-
-### Observations
-
-#### What went well
-
-- The lift-and-shift strategy (new modules alongside old, swap consumers, delete old) kept every intermediate commit compiling and the suite green — zero broken-baseline moments across 7 steps.
-- The `createSubagentSessionStub` pattern (steer/dispose delegate to the wrapped `MockSession`) let 6 tool/service test files migrate with a one-line change each, preserving all existing session-spy assertions.
-- Verification ran incrementally: `pnpm vitest run <file>` after every Red/Green, `pnpm run check` after every interface change, and `pnpm -r run test` (full cross-package) after step 6's deletion to confirm the permission system (1504 tests) was unaffected.
-
-#### What caused friction (agent side)
-
-1. `missing-context` — The plan's step-5 file list omitted 6 tool/service test files (`steer-tool`, `agent-tool`, `background-spawner`, `foreground-runner`, `get-result-tool`, `service-adapter`) that directly set `record.execution = { session, outputFile }`.
-   The existing planning rule ("grep all test files for every removed symbol") was present but was not applied to the renamed `.execution` property — only to removed type imports.
-   Impact: step 5 took ~2× expected time; each file was discovered reactively via `tsc --noEmit` errors.
-2. `rabbit-hole` — Step 6's `sed` invocation for import-path renames failed silently on macOS BSD `sed` because the `#` delimiter clashed with `#test/helpers/...` paths. 3 consecutive tool calls were spent diagnosing and retrying before switching to per-file `sed` with `@` delimiters.
-   Impact: added ~3 minutes of friction; the `edit` tool would have been safer for targeted, known-file replacements.
-3. `other` (autoformat race) — The `pi-autoformat` extension ran concurrently with `git commit` twice during the docs phase, causing `.git/index.lock` conflicts.
-   Recovery was mechanical (remove lock, retry) but required user intervention once.
-   Impact: one user prompt to retry; no rework.
-4. `other` (markdown table alignment) — Replacing short table cells with long module lists in SKILL.md broke MD060's compact-table rule.
-   The pre-completion reviewer caught it (initial FAIL); `rumdl fmt` auto-fixed it.
-   Impact: one amend + re-lint cycle; self-identified after reviewer report.
-
-#### What caused friction (user side)
-
-- No user-side friction observed.
-  The user's only intervention was a retry prompt after the autoformat/git-lock race — a timing issue, not a judgment or context gap.
-
-### Changes made
-
-1. `.pi/skills/testing/SKILL.md` — added rule about `??` swallowing explicit `undefined` in factory overrides (under "Vitest mock patterns").
-2. `packages/pi-subagents/docs/retro/0265-born-complete-subagent-session.md` — appended Final Retrospective stage entry.

package/docs/retro/0270-type-consumable-public-surface.md

@@ -1,108 +0,0 @@
----
-issue: 270
-issue_title: "Make @gotgenes/pi-subagents type-consumable by sibling workspace packages"
----
-
-# Retro: #270 — Make @gotgenes/pi-subagents type-consumable by sibling workspace packages
-
-## Stage: Planning (2026-05-29T00:00:00Z)
-
-### Session summary
-
-Diagnosed the consumability failure empirically with `tsc --traceResolution` and planned a `.d.ts`-emit fix.
-The plan adds a `rollup-plugin-dts` build that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`, wires conditional `exports` (`types` → the bundle, `default` → the real source), generates the artifact at `prepack` time, ships it via a `files` allowlist, and proves external consumability with a `pnpm pack` → throwaway-consumer → `tsc` harness.
-
-### Observations
-
-- Root cause is two compounding failures: the stale `exports["."]` path (`./src/service.ts` does not exist) and, once fixed, an unresolvable `#src/*` cascade.
-  The trace showed the consumer's own `paths` (`#src/*` → `./src/*`) intercept first (both packages define `#src/*`), and the publisher's `imports`-field fallback cannot resolve the extensionless `.ts` target.
-- The public type closure is entangled: `WorkspaceProvider` → `AgentStatus` (in the 510-LOC `agent.ts`) → `types.ts` (which re-exports the `Agent` class).
-  This made the alias-free-entry alternative (Option 2) a substantial source restructure, so it was rejected.
-- Decisions taken via `ask_user`:
-  1. Approach — emit a bundled `.d.ts` (the repo's first build step), over alias-free restructure or type re-declaration.
-  2. Bundler — `rollup-plugin-dts` (purpose-built for flattening declarations; no JS bundle, which suits ship-source), over `tsdown`/`api-extractor`.
-  3. Artifact — not committed; generated at `prepack` and shipped in the tarball, consumed via the package interface.
-  4. Scope — tight: packaging + a `pnpm pack`-based verification harness in #270; defer the `pi-subagents-worktrees` registry-consumption flip (drop `workspace:*`, `link-workspace-packages: false`, wire the real import) to #263.
-- Scope was deliberately narrowed after a chicken-and-egg surfaced: the registry version carrying the fix does not exist until #270 publishes, so the meaningful consumer flip belongs to #263.
-- Sequencing constraint for #263 (captured in the plan): publish #270 first — merge its release-please PR so `pi-subagents` publishes — *before* resuming #263, otherwise #263's `pi-subagents` core edits batch into the same release.
-  The current `#263` scaffold commits on `main` touch only the unregistered `pi-subagents-worktrees` component, so they do not batch into `pi-subagents` and #270 ships cleanly.
-- Primary feasibility risk flagged: whether `rollup-plugin-dts` resolves `#src/*` while rolling up the type graph.
-  Build Step 1 is the explicit checkpoint (emit + assert the output is alias-free and exports the expected symbols).
-- `dist/` is gitignored and already excluded by eslint/biome; the new wrinkle is that a `files` allowlist is required so the gitignored `dist/public.d.ts` is included in the npm tarball — validate `pnpm pack --dry-run` parity so no currently-shipped file is dropped.
-
-## Stage: Implementation — Build (2026-05-29T00:00:00Z)
-
-### Session summary
-
-Executed all four build-order steps: added `rollup` + `rollup-plugin-dts` and a `build:types` script that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`; wired conditional `exports` (`types` + `default`, fixing the stale path) with a `prepack` hook and a `files` allowlist; added a `pnpm pack` → throwaway-consumer → `tsc` verification harness (`scripts/verify-public-types.sh`) plus a CI step; and recorded [ADR-0003].
-A fifth commit documented the new build step in the `package-pi-subagents` skill (reviewer WARN).
-Root `pnpm run check`, root `pnpm run lint`, and `verify:public-types` all pass.
-
-### Observations
-
-- The primary feasibility risk (`rollup-plugin-dts` resolving `#src/*`) resolved cleanly out of the box: driving it with the package `tsconfig` (which carries the `#src/*` paths) produced a 178-line `dist/public.d.ts` with zero `#src/` residue and only `ThinkingLevel` kept external from `@earendil-works/pi-ai`.
-  No alias/path resolver plugin was needed.
-- Harness deviation (fixed in the same step): `pnpm add` in the isolated (`--ignore-workspace`) throwaway consumer exited non-zero with `ERR_PNPM_IGNORED_BUILDS` because it does not inherit the workspace `allowBuilds` approvals (`@google/genai`, `protobufjs`).
-  Fixed by adding `--ignore-scripts` — a type-check needs no dependency build scripts.
-  Worth remembering for any future packaged-consumer harness.
-- A subtle gotcha while debugging: `pnpm ... | tail; echo $?` reports `tail`'s exit, not pnpm's, which masked the real failure.
-  Use `set -o pipefail` or check the command directly.
-- `files` allowlist parity was validated with a before/after `pnpm pack --dry-run` diff: nothing dropped, only `dist/public.d.ts` added.
-  The allowlist reproduces the current contents (`src`, `docs`, `vitest.config.ts`, `AGENTS.md`, `CHANGELOG.md`, `.prettierignore`) plus `dist`.
-  Did not take the opportunity to slim the tarball (docs/test-config still ship) — that would be a separate deliberate change.
-- Runtime `default` → `./src/service/service.ts` is safe because that module's only internal imports are `import type`, which erase; no runtime `#src/*` resolution occurs.
-- No `src/`/`test/` `.ts` files were touched, so the vitest suite and `tsc` were unaffected (confirmed via root check).
-- Pre-completion reviewer: WARN — no findings attributable to this session.
-  Reviewer warnings: (1) the `package-pi-subagents` skill lacked a build-step note — addressed in commit `2ff5a375`; (2) `pnpm fallow dead-code` exits non-zero on a pre-existing finding in `packages/pi-subagents-worktrees/package.json` from the #263 scaffold (commit `9a7dcfc5`), out of scope for #270 and left for #263.
-
-## Stage: Final Retrospective (2026-05-29T21:00:00Z)
-
-### Session summary
-
-Shipped #270 end-to-end across planning, build, and ship stages: diagnosed the cross-package type-resolution failure empirically, built a `rollup-plugin-dts` declaration bundle plus a pack-based verification harness, and published `@gotgenes/pi-subagents@11.6.0` (tag `pi-subagents-v11.6.0`).
-Two CI failures during the ship stage — a pre-existing `pnpm fallow dead-code` gate and lockfile drift — required two extra fix commits before CI went green.
-
-### Observations
-
-#### What went well
-
-- Empirical-first diagnosis: `tsc --traceResolution` in planning pinned the exact two-part failure (consumer `paths` collision + the publisher's `imports`-field extensionless-`.ts` miss) and directly justified the chosen `.d.ts`-emit approach over the alias-free restructure.
-- The flagged primary risk evaporated: `rollup-plugin-dts` resolved `#src/*` out of the box via the package `tsconfig` paths, producing a clean 178-line `dist/public.d.ts` with no resolver plugin.
-- Novel, reusable pattern: `scripts/verify-public-types.sh` proves a ship-source package is externally type-consumable via `pnpm pack` → throwaway-consumer → `tsc`, with no publish round-trip.
-  Worth promoting if other packages grow public surfaces.
-- Disciplined `ask_user` use on the genuinely ambiguous decisions (approach, bundler, artifact handling, scope), with strong user steering — the `tsup`-is-unmaintained redirect to `rollup-plugin-dts`, the "no workspace trickery / use released versions" directive, and the #263 chicken-and-egg catch that correctly narrowed scope.
-
-#### What caused friction (agent side)
-
-- `missing-context` — Pushed to `main` with a pre-existing `pnpm fallow dead-code` failure (unused `@earendil-works/pi-coding-agent` devDependency in `packages/pi-subagents-worktrees/package.json`, from the #263 scaffold).
-  The pre-completion reviewer reported it as `FAIL` but labelled it out-of-scope, and I accepted that framing and pushed.
-  The CI `Fallow dead-code gate` runs `if: github.ref == 'refs/heads/main'` — a hard gate that fires on every `main` push regardless of who introduced the failure — so CI failed (run `26659647270`).
-  Impact: 2 fix commits (`7e7afadd`, `10e74f2f`) and 2 extra CI cycles (~10 min).
-  The ship pre-push step runs only `pnpm run lint`, never `pnpm fallow dead-code`.
-- `missing-context` — Removed the devDependency and committed/pushed `package.json` (`7e7afadd`) without the updated `pnpm-lock.yaml`.
-  CI's `pnpm install --frozen-lockfile` failed with `ERR_PNPM_OUTDATED_LOCKFILE` (run `26659851716`).
-  Impact: 1 extra commit (`10e74f2f`) and 1 extra CI cycle.
-  Self-identified from the CI log.
-- `rabbit-hole` (minor) — While debugging the harness's `ERR_PNPM_IGNORED_BUILDS`, the `pnpm ... | tail; echo $?` idiom reported `tail`'s exit code, masking pnpm's real failure; took ~4 tool calls before tracing with `bash -x`.
-  Impact: added friction, no rework.
-
-#### What caused friction (user side)
-
-- The "pi-subagents-* extensions should use the released, npm-installed version, no workspace trickery" directive arrived mid-planning, after initial exploration.
-  Surfacing the consumption-model constraint at kickoff would have framed the scope question earlier.
-  Opportunity, not criticism — the same exchange produced the high-value chicken-and-egg catch (the registry version with the fix cannot exist until #270 publishes) that correctly deferred the worktrees flip to #263.
-- A brief "there is no [ADR-0003]" → "My mistake" exchange; no rework.
-
-### Diagnostic details
-
-- Model-performance correlation — the lone subagent dispatch (`pre-completion-reviewer`) ran on `anthropic/claude-sonnet-4-6`, appropriate for judgment-heavy review.
-  The dead-code-gate framing miss was a protocol-scope issue (pre-existing vs blocking), not a model-capability mismatch.
-- Escalation-delay — no error sequence exceeded 5 consecutive tool calls; the harness `ERR_PNPM_IGNORED_BUILDS` resolved in ~4.
-- Feedback-loop gap — build-stage verification ran incrementally after each step (good); the gap was at ship: the pre-push check omits the `main`-only gates (`pnpm fallow dead-code`) and lockfile validation that CI enforces, so a locally-clean `pnpm run lint` still failed CI twice.
-
-### Changes made
-
-1. `.pi/prompts/ship-issue.md` — renamed Step 2 to "Pre-push checks" and added `pnpm fallow dead-code` alongside `pnpm run lint`, with a one-line note that the gate is `main`-only and blocks pushes regardless of who introduced the failure.
-2. `AGENTS.md` (§ Code Style pnpm rules) — added a rule to run `pnpm install` and commit the updated `pnpm-lock.yaml` in the same commit when a `package.json` dependency changes, since CI installs with `--frozen-lockfile`.
-
-[ADR-0003]: ../decisions/0003-publish-bundled-type-declarations.md

package/docs/retro/0272-export-workspace-collaborator-types.md

@@ -1,38 +0,0 @@
----
-issue: 272
-issue_title: "Export WorkspaceProvider collaborator types by name from the public surface"
----
-
-# Retro: #272 — Export `WorkspaceProvider` collaborator types by name from the public surface
-
-## Stage: Planning (2026-05-29T23:23:37Z)
-
-### Session summary
-
-Planned a purely additive, type-only change to `@gotgenes/pi-subagents`'s public surface: re-export `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, and `WorkspaceDisposeResult` by name from `src/service/service.ts`, alongside the already-exported `WorkspaceProvider`.
-The plan bundles the source change with extending the `verify:public-types` harness (symbol guard + probe consumer) into a single `feat:` commit, since a packaged-tarball probe cannot import names the entry does not yet export.
-
-### Observations
-
-- The issue's "Proposed change" was unambiguous, so the `ask-user` design gate was skipped.
-
-## Stage: Implementation — Build (2026-05-29T23:30:13Z)
-
-### Session summary
-
-Implemented the single plan step: widened the `#src/lifecycle/workspace` import in `src/service/service.ts` to include all four collaborator types and added them to the `export type { … }` block, updating the standing comment from a future-tracking reference to a present-tense description.
-Extended `scripts/verify-public-types.sh` — the symbol guard loop and inline `probe.ts` — to assert all four new names, confirmed the harness fails (red) before the source change and passes (green) after.
-Also updated two stale forward-references to #272 in `docs/architecture/architecture.md` (flagged by the pre-completion reviewer).
-
-### Observations
-
-- Red→green cycle through the type-level harness (`verify:public-types`) rather than vitest, exactly as planned.
-- No rollup config change was needed — `rollup-plugin-dts` carries through whatever the entry exports; the symbol guard and `#src` self-containment guard both stayed green.
-- The symbol guard already found the names present in the bundle (declared but not exported); the probe's type-check was the real red signal.
-- Pre-completion reviewer: WARN — two stale forward-references to #272 in `docs/architecture/architecture.md`; both fixed in a follow-up `docs:` commit before shipping.
-- No new vitest cycle: the re-exports are type-only and erase at runtime.
-  The red→green loop lives in the type-level `verify:public-types` harness, not the runtime suite — this is closer to a `/build-plan` shape than a code TDD cycle, but it still has a clean red→green via the probe consumer.
-- The four interfaces already exist in `src/lifecycle/workspace.ts` with correct shapes; only re-exporting is in scope.
-- `rollup.dts.config.mjs` needs no change — `WorkspaceProvider` already pulls the four collaborator declarations into the bundle by reference, so adding named exports keeps the `grep '#src'` self-containment guard green.
-- A standing comment in `service.ts` ("Named re-exports … tracked in #272") goes stale on landing — the plan updates it in the same step.
-- The downstream simplification in `@gotgenes/pi-subagents-worktrees` (swap indexed-access aliases for named imports, bump the dependency) is deferred until a `pi-subagents` release carries these exports — consistent with the registry-consumption model settled in #270.

package/docs/retro/0277-encapsulate-agent-session.md

@@ -1,80 +0,0 @@
----
-issue: 277
-issue_title: "Encapsulate AgentSession behind SubagentSession; retire the remaining agent.session reach-throughs"
----
-
-# Retro: #277 — Encapsulate AgentSession behind SubagentSession
-
-## Stage: Planning (2026-05-30T12:00:00Z)
-
-### Session summary
-
-Produced an 8-step TDD plan covering delegate methods on `SubagentSession`, intent-revealing methods on `Agent`, caller migration across tools/service/UI/observation, observer callback narrowing, and `Agent.session` getter removal.
-The plan extends the issue's three proposed methods with `getContextPercent()`, `subscribeToUpdates()`, and `messages` to fully satisfy the acceptance criterion that no production module outside `lifecycle/` references the raw `AgentSession`.
-
-### Observations
-
-- `subscribeAgentObserver` already accepts `SubscribableSession` (not `AgentSession`), so adding `subscribe()` to `SubagentSession` enables passing it directly — no `session` getter needed for observer wiring.
-- The `onSessionCreated` observer callback delivers raw `AgentSession` to spawners in `tools/`.
-  The plan narrows it to `(agent: Agent)` and has spawners use `agent.subagentSession!` which structurally satisfies both `SubscribableSession` and `SessionLike` via the new delegate methods.
-- The conversation viewer uses `session.messages` for rendering and `session.subscribe()` for live updates — both require delegate methods beyond the issue's three proposed methods.
-- `queueSteer()` and `flushPendingSteers()` become private after migration, which requires migrating existing tests that call them directly.
-- The public API surface (`SubagentsService` + `SubagentRecord`) is unaffected — `Agent` is internal.
-
-## Stage: Implementation — TDD (2026-05-30T15:10:00Z)
-
-### Session summary
-
-All 8 TDD steps completed in one session. 13 commits landed: 2 `feat:`, 5 `refactor:`, 2 `docs:`, 1 `style:`, plus the earlier plan and retro commits.
-Test count went from 960 → 973 (+13 net: +18 new tests, −5 removed tests for the retired `session` getter and `queueSteer`/`flushPendingSteers` private methods).
-
-### Observations
-
-- `subscribeAgentObserver` already accepted `SubscribableSession`, so `SubagentSession` (once it grew a `subscribe()` delegate) could be passed directly in `Agent.run()` and `Agent.resume()` — no cast needed.
-- Adding `messages` to `MockSession` interface was a minor unplanned step: the field existed at runtime (via `createMockSession`'s spread) but the interface didn't declare it, causing a type error when `createSubagentSessionStub` tried to forward it.
-- `onSessionCreated` tests in `foreground-runner.test.ts` called the callback with 2 args `(record, mockSess)`.
-  After narrowing, the first test case was missing a `subagentSession` setup; fixed by setting `record.subagentSession` before invoking the callback.
-- The `get-result-tool.test.ts` verbose conversation test needed updating: previously built a mock session with messages and passed it directly; now the stub's `getConversation` must return the expected text via `mockReturnValue`.
-- Pre-completion reviewer returned **WARN** for two stale `architecture.md` passages: (1) conversation-viewer description still said "subscribes directly to `AgentSession`"; (2) `Agent` classDiagram still listed `queueSteer`/`flushPendingSteers` as public and omitted the 6 new public members.
-  Both fixed in a `docs:` commit before closing.
-
-## Stage: Final Retrospective (2026-05-30T16:00:00Z)
-
-### Session summary
-
-Issue #277 shipped across three sessions (planning, TDD, ship) in a single day.
-All 8 TDD steps completed cleanly, 13 implementation commits landed, and `pi-subagents-v13.2.0` released.
-
-### Observations
-
-#### What went well
-
-- Planning correctly identified scope beyond the issue's three proposed methods: `getContextPercent()`, `subscribeToUpdates()`, and `messages` were needed to satisfy the "no production module outside `lifecycle/` references `AgentSession`" acceptance criterion.
-  This prevented mid-TDD design revisions.
-- The discovery that `subscribeAgentObserver` already accepted `SubscribableSession` meant adding `subscribe()` to `SubagentSession` was sufficient for observer wiring — no type cast or adapter needed.
-- Lift-and-shift execution was precise: new methods added first (steps 1-2), callers migrated by concern (steps 3-6), old getter removed last (step 7).
-  No step broke any other step's tests.
-- Pre-completion reviewer caught two stale `architecture.md` passages (classDiagram with removed public methods, conversation-viewer description) that the implementation steps missed.
-  Both fixed in a `docs:` commit before closing.
-
-#### What caused friction (agent side)
-
-1. `missing-context` — `MockSession` interface lacked `messages`.
-   The field existed at runtime (via `createMockSession`'s spread + `Record<string, unknown>` return type) but the `MockSession` interface didn't declare it.
-   Adding `messages` to `createSubagentSessionStub` triggered a type error.
-   Impact: 2 extra edits to `mock-session.ts` (add field to interface, add to `base` object), no rework.
-2. `missing-context` — `get-result-tool.test.ts` conversation test relied on raw mock session messages.
-   After migrating to `record.getConversation()`, the stub's `getConversation` returned `""` by default.
-   The test needed `stub.getConversation.mockReturnValue("...")` instead.
-   Impact: 1 test update, caught immediately by `pnpm vitest run`.
-3. `missing-context` — `foreground-runner.test.ts` called `onSessionCreated(record, mockSess)` with 2 args.
-   After narrowing the callback to `(agent: Agent)`, the first test lacked `record.subagentSession` setup.
-   Impact: 2 test blocks updated, caught by `pnpm vitest run`.
-4. `missing-context` — First `get-result-tool.ts` edit left a double-nested `if (conversation)` block.
-   The multi-edit replaced the outer `if (params.verbose && record.session)` but preserved the inner guard, creating `if (conversation) { if (conversation) { ... } }`.
-   Impact: Self-caught on immediate read-back; fixed in the same commit, no rework.
-
-#### What caused friction (user side)
-
-- None observed.
-  The user's involvement was limited to the `/plan-issue`, `/tdd-plan`, `/ship-issue`, and `/retro` prompts — no mid-session corrections or redirections were needed.

package/docs/retro/0280-rename-agent-to-subagent.md

@@ -1,96 +0,0 @@
----
-issue: 280
-issue_title: "Rename the internal Agent class to Subagent"
----
-
-# Retro: #280 — Rename the internal `Agent` class to `Subagent`
-
-## Stage: Planning (2026-05-31T00:09:51Z)
-
-### Session summary
-
-Produced a numbered implementation plan to rename the subagent-instance cluster in `src/lifecycle/` from the bare `Agent*` family to `Subagent*`, consolidate the duplicate `AgentStatus` union into the public `SubagentStatus`, and update the architecture doc.
-The plan is a 7-step refactor (no behavior change), each step an atomic language-service rename that leaves the tree green.
-
-### Observations
-
-- Scope decisions confirmed with the user via `ask_user`: (1) rename the module files too (`agent.ts` → `subagent.ts`, `agent-manager.ts` → `subagent-manager.ts`, plus test/helper files), and (2) full-consistency rename of adjacent identifiers — `subscribeAgentObserver`, the `SubagentManagerObserver` `onAgent*` methods, and the `createTestAgent` helper.
-- Layering catch: pointing `WorkspaceDisposeOutcome.status` directly at `service.ts`'s `SubagentStatus` would create a `lifecycle → service` cycle (`service.ts` already imports the workspace collaborator types).
-  Resolution: keep the union's single home in the lifecycle layer (`subagent.ts`) and have `service.ts` re-export it, mirroring the existing `LifetimeUsage` / workspace re-export pattern.
-- Acceptance-grep catch: the issue's `grep src/lifecycle/` for bare `Agent` matches comments and string literals (e.g. the two `"Agent not configured …"` error messages), not just symbols.
-  The language-service rename does not touch those, so each step must sweep residual comment/string occurrences; step 7 has a final grep gate.
-- Compound names (`AgentSession`, `AgentInvocation`, `AgentTypeRegistry`, `AgentTool`, `AgentSpawnConfig`) are not bare-word matches and are explicitly out of scope.
-- Non-breaking — `refactor:` commits throughout; `verify:public-types` runs after the status consolidation and the final step since the public bundle (`dist/public.d.ts`) is rolled from `src/service/service.ts`.
-- Also flagged the `package-pi-subagents` SKILL.md for an internals-naming update (it references `AgentManager`, `Agent`, `make-agent`).
-
-## Stage: Implementation — TDD (2026-05-31T00:38:55Z)
-
-### Session summary
-
-Completed 6 refactor commits (steps 1–6 from the plan, with step 5 folded into step 3) plus a `test:` commit for the helper rename and a `docs:` commit for the architecture doc update.
-All 973 tests pass across 59 test files with no test count delta.
-Pre-completion reviewer returned PASS with all 5 acceptance criteria verified.
-
-### Observations
-
-- Step 5 (`AgentManagerLike` → `SubagentManagerLike`) was automatically folded into step 3 because the bulk-rename Python script replaced all `AgentManager*` compounds at once — no separate commit was needed or appropriate.
-- The acceptance grep (`grep -rnE '\bAgent(Manager|Init)?\b' src/lifecycle/`) also flags bare `Agent` in comments and error strings; each rename step swept those manually since the language-service rename does not touch non-symbol text.
-- `sed` with negative lookaheads failed on macOS for the `notification.ts` file; fell back to a two-pass approach (sed for the import, then `perl -i -0pe` with negative lookahead for the body).
-- `describe("Agent — ...)` test block names used em-dashes (Unicode U+2014); `sed` with `\u2014` escape did not match on macOS — required Python `re.sub` with the literal character.
-- The `SubagentStatus` type definition was kept in `src/lifecycle/subagent.ts` (single home) and re-exported from `src/service/service.ts`, matching the existing `LifetimeUsage` / workspace re-export pattern and avoiding a `lifecycle → service` cycle.
-- Docs: the architecture doc's session-encapsulation table had misaligned Markdown table columns after the rename (cell widths changed); `rumdl fmt` auto-fixed them.
-- Pre-completion reviewer: PASS — all deterministic checks, all 5 acceptance criteria, conventional commits, docs, Mermaid diagrams, and dead-code gate confirmed clean.
-
-## Stage: Final Retrospective (2026-05-31T01:05:57Z)
-
-### Session summary
-
-Shipped the full Planning → TDD → Ship lifecycle for the internal `Agent` → `Subagent` rename across `@gotgenes/pi-subagents`: 7 implementation commits (6 `refactor:`/`test:` + 1 `docs:`), 973 tests green throughout, CI passed on `27abb5aa`, and issue #280 closed.
-No release was triggered (all `refactor:`/`test:`/`docs:` commits), so no release-please PR appeared — expected.
-
-### Observations
-
-#### What went well
-
-- Two planning-stage catches prevented downstream rework: the `lifecycle → service` import cycle (resolved by keeping `SubagentStatus`'s single home in `subagent.ts` and re-exporting from `service.ts`) and the acceptance grep matching bare `Agent` in comments/strings (so each step swept non-symbol text).
-  Both were anticipated in the plan and held during execution.
-- Incremental verification carried the rename safely: `pnpm run check` plus the affected test files ran after every step, so the text-based substitution mistakes were caught instantly and never reached a commit.
-  The pre-completion reviewer then returned a clean PASS with nothing to fix.
-- The status re-export needed a follow-up `import type { SubagentStatus }` because `export type { … } from` does not create a local binding for `SubagentRecord` to reference — `pnpm run check` flagged it immediately, a one-edit fix.
-
-#### What caused friction (agent side)
-
-- `wrong-abstraction` — The plan specified each rename as a "scope-aware language-service pass" (`findRenameLocations`), but the execution toolkit has no LSP-rename tool — only `Edit`, `Bash` (`sed`/`perl`/`python`), and `grep`.
-  Execution fell back to text substitution, which is exactly why the comment/string sweep was needed and why the regex gymnastics below happened.
-  Impact: added friction but no rework — `tsc` + tests caught every gap; no incorrect commit landed.
-- `other` (cross-platform tooling) — Repeated silent failures from BSD `sed` / `perl` one-liners: BSD `sed` lacks `\b` and lookahead; `perl -i ''` is malformed (the `-i ''` form is a `sed`-ism); neither interprets `\uXXXX` escapes, so em-dash `describe("Agent — …")` blocks and `notification.ts` body renames did not match.
-  Each failure forced a grep-verify-redo loop, ultimately resolved by switching to Python `re.sub`.
-  Impact: roughly 5–8 extra tool calls across the TDD stage; no rework beyond the redo cycles.
-
-#### What caused friction (user side)
-
-- None.
-  The user's two `ask_user` answers at planning time (file renames + full-consistency adjacent identifiers) front-loaded every scope decision, so the TDD and Ship stages ran without a single mid-course correction.
-
-### Diagnostic details
-
-- **Model-performance correlation** — One subagent dispatched (`pre-completion-reviewer`) on judgment-heavy review work (acceptance verification, Mermaid validation via `mmdc`, dead-code gate); appropriate match, no mismatch.
-- **Escalation-delay tracking** — The `notification.ts` body rename cycled ~4–5 consecutive `sed`/`perl`/`grep` calls on the same substitution before switching to `perl -i -0pe`; under the 5-call threshold but the closest the session came.
-  The general lesson (prefer Python `re.sub`) generalizes the fix.
-- **Unused-tool detection** — No Explore/`colgrep` gap: the codebase was already understood from planning, and an exact symbol rename is not a semantic-search task.
-  The only "missing capability" is a language-service rename tool, which is not in the toolkit — a genuine gap, not an unused option.
-- **Feedback-loop gap analysis** — No gap: `pnpm run check` and affected tests ran after each step (incremental); `pnpm run lint`, `pnpm fallow dead-code`, and `verify:public-types` ran as the final batch.
-  Verification cadence was correct.
-
-### Changes made
-
-1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0280-rename-agent-to-subagent.md`.
-2. Strengthened the global `APPEND_SYSTEM.md` "Shell Commands" rule to name the literal absolute-path `cd` form (e.g. `cd /Users/you/project &&`), not just `cd $CWD &&` — the existing rule failed to catch the literal-path form that agents actually emit.
-   This file is global (`~/.pi/agent/APPEND_SYSTEM.md`), outside the repo, so it is not committed here.
-3. Added a monorepo-specific line to `AGENTS.md` § Monorepo Structure: prefer `pnpm --filter @gotgenes/<pkg> run <script>` (or `pnpm -C packages/<pkg> run <script>`) from the root over `cd packages/<pkg> && pnpm run <script>`.
-   Prompted by excessive `cd` chaining observed across this session's Ship and Retro stages.
-
-### Follow-ups considered (not applied)
-
-1. Proposed adding a bulk-substitution tooling rule (prefer Python `re.sub` over `sed`/`perl` one-liners, since BSD `sed` lacks `\b`/lookahead and `\uXXXX` is uninterpreted) to the `code-design` skill's Tooling section.
-   The user opted to record the observation here only and skip the skill change.

package/docs/retro/0360-custom-agents-default-append.md

@@ -1,81 +0,0 @@
----
-issue: 360
-issue_title: "fix(pi-subagents): custom agents default to replace mode instead of append"
----
-
-# Retro: #360 — fix(pi-subagents): custom agents default to replace mode instead of append
-
-## Stage: Planning (2026-06-09T02:42:19Z)
-
-### Session summary
-
-Planned the one-line fix flipping the `promptMode` ternary in `custom-agents.ts` so custom agents without an explicit `prompt_mode` default to `append` (matching the built-in default) instead of `replace`.
-Enumerated the full change surface: the source line, two existing tests in `test/config/custom-agents.test.ts`, the wizard frontmatter doc comment, and the `README.md` defaults table.
-
-### Observations
-
-- The issue's proposed fix is unambiguous, so no `ask_user` round was needed.
-- `grep` confirmed the only default-asserting tests live in `test/config/custom-agents.test.ts`; the broader upstream regression suite uses explicit `promptMode` values and is unaffected.
-- Unknown `prompt_mode` values (e.g. `merge`) now resolve to `append` rather than `replace` — flagged as the safer fallback (inheriting a superset of context rather than silently dropping project context).
-- Source fix and test updates are coupled into one TDD cycle because the assertions and the changed line move together; docs split into a separate `docs:` commit.
-- **Breaking change**: flipping the default alters the runtime behavior of existing `.pi/agents/*.md` files that omit `prompt_mode` (they switch from `replace` to `append` on upgrade with no config edit).
-  The plan was corrected mid-session to use `fix!:` with a `BREAKING CHANGE:` footer so release-please cuts a major — the initial draft incorrectly used a plain `fix:`.
-- No `docs/architecture/` references to the default value exist; `CHANGELOG.md` is release-please-owned and untouched.
-
-## Stage: Implementation — TDD (2026-06-09T02:48:38Z)
-
-### Session summary
-
-Completed both TDD cycles from the plan in a single session.
-Step 1 flipped the ternary in `src/config/custom-agents.ts` and updated three assertions in `test/config/custom-agents.test.ts` (empty-frontmatter default, no-frontmatter assertion added, unknown-mode renamed and flipped).
-Step 2 updated the inline doc comment in `src/ui/agent-creation-wizard.ts` and the `README.md` defaults table.
-Test count: 973 (unchanged — no new tests added, three assertions updated in-place).
-
-### Observations
-
-- No deviations from the plan; all three test mutations landed exactly as specified.
-- Full suite (59 test files, 973 tests) stayed green after the source change — the planning analysis that the broader upstream regression suite uses explicit `promptMode` values was confirmed correct.
-- `pnpm fallow dead-code` and `pnpm run check` both passed with no findings.
-- Pre-completion reviewer verdict: **PASS** — no warnings or findings raised.
-
-## Stage: Final Retrospective (2026-06-09T03:04:21Z)
-
-### Session summary
-
-Shipped the breaking-default fix end to end across four staged sessions (plan → TDD → ship → retro), cutting `pi-subagents@15.0.0`.
-The change flips the `promptMode` default for custom agents that omit `prompt_mode` from `replace` to `append`.
-Execution was clean except for one significant miss in planning: the change was initially classified as a non-breaking `fix:` and corrected only after the user intervened.
-
-### Observations
-
-#### What went well
-
-- The multi-model pipeline matched models to stage complexity: planning and retro on `claude-opus-4-8`, TDD on `claude-sonnet-4-6`, and the mechanical ship stage (push, CI watch, close, merge) on a cheaper `deepseek-v4-flash` — all stages completed their work correctly.
-- The breaking-change correction propagated cleanly across the stage boundary: once the plan was fixed to `fix!:` with a `BREAKING CHANGE:` footer, the TDD stage (different model, different session) picked it up from the plan and committed the footer verbatim without re-deciding.
-- TDD verification was incremental, not end-loaded: green baseline (`check`/`lint`/test) before any edit, red confirmation after the test edit, green after the source edit, then full suite + `check` + `lint` + `fallow` before the reviewer dispatch.
-
-#### What caused friction (agent side)
-
-- `instruction-violation` (user-caught) — the planning stage classified a changed-default bug fix as a non-breaking `fix:`, producing a plan with `fix:` commit messages.
-  The plan template line "If the change is breaking, say so explicitly in Goals and use `feat!:`" was available but never triggered, because the agent conflated "the fix is unambiguous" (turn 8) with "the change is non-breaking" and skipped the breaking determination entirely.
-  Impact: the user had to intervene ("This is a breaking change, right?"); three corrective edits (plan Goals, plan TDD commit block, retro Planning notes) plus one extra commit (`docs: mark issue #360 change as breaking`).
-  Caught before TDD, so no code rework — but a wrong `fix:` that reached `/ship-issue` would have cut a patch release for a breaking change.
-
-#### What caused friction (user side)
-
-- None on the #360 work.
-  The single redirecting question ("This is a breaking change, right?") was a near-optimal intervention: minimal, Socratic, and it let the agent reason to the correct classification itself rather than dictating the fix.
-- Environment note (not #360-specific): the retro session opened with local `main` detached onto a stale `#332` side-branch after an aborted rebase (2 duplicate commits, 36 behind `origin/main`).
-  `origin/main` was intact; recovery was a verified `git reset --hard origin/main` after confirming the 2 local commits were byte-identical duplicates of work already on origin.
-
-### Diagnostic details
-
-- **Model-performance correlation** — the breaking-change miss happened on the *strongest* model in the pipeline (`claude-opus-4-8`) during the judgment-heaviest stage (planning).
-  This rules out model capability as the cause and points to a salience gap in the plan-issue prompt: the breaking determination is framed only as an `ask-user` ambiguity, conditional on the change being "ambiguous," with no unconditional classification step.
-- **Feedback-loop gap analysis** — no gap; the TDD stage ran `check`/`lint`/test/`fallow` incrementally rather than only at the end.
-- Escalation-delay and unused-tool lenses found nothing notable (no rabbit-holes or tool-availability misses).
-
-### Changes made
-
-1. `.pi/prompts/plan-issue.md` — added an unconditional breaking-change classification step to the `## Decide` section (before the ambiguity paragraph), so the breaking determination no longer hides behind the `ask-user` ambiguity gate.
-   Names the non-obvious case explicitly: a bug fix that changes a default is breaking.

package/docs/retro/0373-extract-subagent-state.md

@@ -1,94 +0,0 @@
----
-issue: 373
-issue_title: "Extract SubagentState; make Subagent execution deps mandatory"
----
-
-# Retro: #373 — Extract SubagentState; make Subagent execution deps mandatory
-
-## Stage: Planning (2026-06-14T03:34:51Z)
-
-### Session summary
-
-Produced the implementation plan at `packages/pi-subagents/docs/plans/0373-extract-subagent-state.md`.
-The architecture doc (Phase 17 Step 2 + "First-principles refinement") already specified the design precisely and the issue body matched it, so planning was confirmation-and-detailing rather than discovery.
-Issue is first-party (`gotgenes`) and unambiguous — skipped the `ask_user` gate.
-
-### Observations
-
-- **Not breaking** for the published surface: `src/service/service.ts` exposes `SubagentRecord`/`SubagentStatus`/spawn-config, never `SubagentInit` or the `Subagent` constructor.
-  Only the internal constructor signature changes.
-- **Single production construction site** confirmed: `SubagentManager.spawn` (~line 139) is the only `new Subagent(...)` outside tests — this is what makes mandatory execution deps viable.
-- **Observer retarget is required**, not optional: making execution mandatory would otherwise force `record-observer.test.ts` to stub execution.
-  Pointing `subscribeSubagentObserver` at `SubagentState` (and dropping the record from `onCompact`, closing over `this` in `subagent.ts`) is the move that lets observer tests target `SubagentState` directly.
-- **`resume()`'s missing-session throw stays** — it guards a genuine runtime state, not a construction concern.
-  Only the two `run()` "not configured for execution" throws are deleted.
-- **`SubagentStatus` home**: moved to `subagent-state.ts` but re-exported from `subagent.ts` to keep `service.ts`'s import path (and the public type bundle path) unchanged, and to avoid a circular import.
-- **Lift-and-shift for the large test file**: `test/lifecycle/subagent.test.ts` (~700 LOC).
-  Step 1 funnels constructions through a local helper and moves the state-machine `describe` blocks to the new `subagent-state.test.ts`, so Step 3's mandatory-execution flip is bounded to the helper + two run/resume factories.
-  Step 3 is unavoidably one atomic commit (removing optional fields breaks every construction at the type level at once).
-- **Doc updates identified**: `architecture.md` (lifecycle file listing, `Subagent` class diagram, mark Step 2 ✅ Complete, Phase 17 prose ~line 879, type-complexity table ~line 649) and `SKILL.md` (Lifecycle 10→11 modules, total 56→57 files).
-- Deferred per scope boundary: metrics-as-projection and result-delivery domain extraction (the other two of the four conflated domains).
-
-## Stage: Implementation — TDD (2026-06-14T09:23:00Z)
-
-### Session summary
-
-Executed all four planned steps as separate commits: (1) extract `SubagentState` value object + new `subagent-state.test.ts`, (2) retarget `subscribeSubagentObserver` at `SubagentState`, (3) the atomic flip making `SubagentExecution` a mandatory collaborator and deleting the two `run()` throws, (4) docs.
-Test count moved 966 → 967 (net): +26 new `SubagentState` tests, minus the migrated state-machine duplicates and the obsolete missing-factory test.
-Pre-completion reviewer returned **PASS**; `check`/`lint`/`test`/`fallow` all clean.
-
-### Observations
-
-- The plan held exactly — every file in Module-Level Changes was touched and nothing else.
-  The `createTestSubagent` consumers (`conversation-viewer`, `notification`, `get-result-tool`, `make-subagent.test`) stayed untouched as predicted; the helper absorbed the construction change via a `TestSubagentOptions` shape that splits passive-state shorthands from identity/execution.
-- **Explicit-`undefined` preservation** (testing-skill warning) mattered: `createTestSubagent` and the local `makeSubagent` build their `SubagentState` via spread of the rest-captured state overrides (`{ defaults, ...stateOverrides }`) so callers passing `completedAt: undefined` (running-status records in `get-result-tool.test`) still get `undefined`, not the `2000` default.
-- The lift-and-shift prep in Step 1 (local `makeSubagent` helper + perl-routing the single-line constructions) paid off: Step 3's breaking flip only had to edit the helper, `createRunnableAgent`, `createResumableAgent`, `createCompletionAgent`, and the constructor describe — not the whole file.
-- Removed the obsolete "throws when the session factory is missing" test (the guard is gone by construction); the construct-complete invariant is now type-level, not runtime-testable.
-  An initial replacement comment was dropped per reviewer/operator feedback as unhelpful.
-- `SubagentExecution` carries 12 fields (4 mandatory).
-  Reviewer flagged it as wide but accepted per the plan's recorded decision to keep it concrete rather than split further.
-- Pre-completion reviewer: **PASS** (no WARN findings).
-
-## Stage: Final Retrospective (2026-06-14T17:20:00Z)
-
-### Session summary
-
-Shipped #373 end-to-end across one conversation spanning Planning → TDD → Ship → Retro: four implementation commits, CI green, issue closed, no release-please PR (a `refactor:`-only change does not trigger a release).
-The plan held exactly — zero rework, and the pre-completion reviewer returned PASS with nothing to fix.
-The single user intervention was a one-line comment removal during TDD Step 3.
-
-### Observations
-
-#### What went well
-
-- **Plan-to-ship with zero rework.**
-  Every file in the plan's Module-Level Changes was touched and nothing else; the `createTestSubagent` consumers stayed untouched exactly as predicted.
-  The lift-and-shift prep (Step 1 funneling constructions through a local `makeSubagent` helper) bounded the breaking Step 3 flip to the helper plus three factories — the atomic-construction-change concern from the plan never materialized as churn.
-- **Clean model allocation across stages.**
-  Planning ran on `claude-opus-4-8`, TDD on `claude-sonnet-4-6`, Ship on `opencode-go/deepseek-v4-flash` (mechanical git/CI/close work), the pre-completion reviewer subagent on `claude-sonnet-4-6`, and Retro on `claude-opus-4-8`.
-  Judgment-heavy work landed on reasoning-strong models; the cheap model handled only the mechanical ship sequence.
-- **Incremental verification.** `pnpm run check` ran after every TDD step (not just at the end), catching the shared-type breakage at the right boundary; the affected test files were run per-step before the full suite.
-
-#### What caused friction (agent side)
-
-- `other` (tombstone comment) — after removing the obsolete "throws when the session factory is missing" test in TDD Step 3, left a comment narrating the *absence* of the guard (`// No "missing session factory" guard: execution is a mandatory constructor collaborator …`).
-  The user flagged it as unhelpful and asked for removal.
-  Impact: one extra `Edit` + a blank-line cleanup + a `--amend` of the Step 3 commit.
-  No behavioral rework; user-caught.
-
-#### What caused friction (user side)
-
-- None of consequence.
-  The single intervention (comment removal) was light mechanical oversight on an otherwise self-driving session; no earlier context would have changed the outcome.
-
-### Diagnostic details
-
-- **Model-performance correlation** — no mismatch.
-  The only subagent dispatch (pre-completion-reviewer) ran on `claude-sonnet-4-6`, appropriate for judgment-heavy review; it returned PASS.
-  The Ship stage on `deepseek-v4-flash` was purely mechanical (git push, `ci_find`/`ci_watch`, `issue_close`, `release_pr_find`) and the one judgment point (the batch-vs-release `ask_user`) was handled correctly.
-- **Escalation-delay / unused-tool / feedback-loop** — nothing notable: no rabbit-holes, no error-chasing sequences, and verification ran incrementally throughout.
-  Lenses skipped.
-
-### Changes made
-
-1. `.pi/skills/code-design/SKILL.md` (§ Names over comments) — added a line forbidding tombstone comments that narrate removed code or the absence of a guard/test/branch, prompted by the user-caught over-comment in TDD Step 3.