@gotgenes/pi-autoformat 0.1.0 → 4.0.3

package/docs/plans/0031-turn-end-flush-with-change-detection.md

@@ -0,0 +1,365 @@
+---
+issue: 31
+issue_title: "Pre-commit flush: format touched files before agent-initiated git commits"
+---
+
+# Turn-end flush with change detection
+
+## Problem Statement
+
+pi-autoformat runs its formatter flush at `agent_end`, which fires after the agent's full turn loop completes.
+In TDD and commit-heavy workflows, the agent writes files in one turn and commits them in a later turn.
+Because formatting has not yet run, pre-commit hooks (e.g. Biome via prek) reject the commit.
+The agent then has to run the formatter manually, re-stage, and retry — wasting tokens and time.
+
+Observed in `pi-permission-system`: 3 of ~10 commits required retry after Biome rejection.
+
+The typical pattern across 4,925 analysed turns:
+
+```text
+Turn N:   edit src/foo.ts        (single tool call)
+Turn N+1: edit src/bar.ts        (single tool call)
+Turn N+2: bash("git add ... \n git commit -m '...'")
+```
+
+93.4% of turns contain exactly one tool call.
+Writes and commits always occur in separate turns.
+Zero instances of same-file edits within a single turn were found across all session data.
+
+## Goals
+
+1. Move the primary formatter flush from `agent_end` to `turn_end` so files are formatted between turns — before any subsequent commit.
+2. Detect whether formatting actually changed file content (content hashing before/after) and only notify the agent when changes occurred or the formatter failed.
+3. Notify the agent inline via a steering message (`pi.sendMessage` during streaming) so it sees the notification before its next LLM call.
+4. Remove the `notifyAgent` config field; turn-end steering replaces the `agent_end` follow-up turn mechanism.
+5. Keep `agent_end` as a safety-net flush for any files not yet formatted (e.g. files added via EventBus without a turn loop).
+
+## Non-Goals
+
+1. Re-staging formatted files in the git index — session data shows `git add` and `git commit` always share the same bash command, run in a turn after formatting has already occurred.
+2. Command detection for `git commit` at `tool_call` — the turn-end flush makes this unnecessary; the intra-turn write+commit pattern has never occurred in session data.
+3. Exposing an explicit flush tool or slash command for agents.
+4. Byte-level diffs or line-change summaries in the notification — file names and failure details are sufficient.
+
+## Background
+
+### Session data analysis
+
+| Metric | Count | % |
+| --- | --- | --- |
+| Total turns with tools | 4,925 | 100% |
+| Single-tool turns | 4,515 | 91.7% |
+| Multi-tool turns | 410 | 8.3% |
+| Same-file edits in same turn | 0 | 0% |
+| Read-after-write to same file in same turn | 0 | 0% |
+| Write + git commit in same turn | 0 | 0% |
+
+The original argument against per-turn formatting was that it could corrupt `Edit` tool `oldText` matching or `Read` tool `offset`/`limit` when a formatter changes a file between two tool calls targeting the same file within a turn.
+The session data shows this scenario has never occurred.
+
+### Pi agent loop lifecycle (from source)
+
+```text
+OUTER LOOP:
+  INNER LOOP (while hasMoreToolCalls || pendingMessages):
+    turn_start
+      process pendingMessages (steering messages from previous turn)
+      LLM generates response
+      execute tool calls sequentially:
+        beforeToolCall → tool runs → afterToolCall (tool_result)
+    turn_end  ← FLUSH HERE, send steering message if changes
+      shouldStopAfterTurn? (not used by coding-agent)
+      pendingMessages = getSteeringMessages()  ← PICKS UP OUR MESSAGE
+  END INNER LOOP
+  
+  followUpMessages = getFollowUpMessages()
+  if followUp → continue outer loop
+  else → break
+agent_end  ← SAFETY-NET FLUSH
+```
+
+Key properties:
+
+- `turn_end` is fully `await`ed before the next `turn_start`.
+- During the turn loop, `isStreaming` is `true`; `pi.sendMessage()` defaults to `agent.steer()`.
+- Steering messages are consumed as `pendingMessages` at the start of the next turn, injected before the LLM call.
+- When the agent's final turn has no tool calls (text-only), the queue is empty, so the turn-end flush is a no-op and no steering message is sent.
+
+### Relevant modules
+
+| Module | Role |
+| --- | --- |
+| `src/extension.ts` | Extension entrypoint. Lifecycle handlers for `session_start`, `tool_call`, `tool_result`, `agent_end`, `session_shutdown`. Owns `queueFlush()` and reporting. |
+| `src/prompt-autoformatter.ts` | `PromptAutoformatter` class. `flushPrompt()` drains the touched-file queue and runs formatter chains. |
+| `src/formatter-executor.ts` | `BatchRun` type with `stdout`, `stderr`, `exitCode`. Runs formatter commands. |
+| `src/formatter-config.ts` | `AutoformatConfig` with `notifyAgent` boolean (to be removed). `UserFormatterConfig`. |
+| `src/config-loader.ts` | Loads/merges config, validates fields. |
+| `schemas/pi-autoformat.schema.json` | JSON Schema for config validation. |
+| `docs/configuration.md` | User-facing config documentation. |
+| `test/extension.test.ts` | Extension lifecycle tests with `TestPi` harness. |
+
+### Relationship to plan 0027
+
+Plan 0027 introduced `notifyAgent` (default `false`), which sends a follow-up turn at `agent_end` via `pi.sendMessage({ triggerTurn: true })`.
+This plan replaces that mechanism: formatting moves to `turn_end` with inline steering, making the `agent_end` follow-up unnecessary.
+The `notifyAgent` field is removed per the deprecation policy in AGENTS.md.
+
+## Design Overview
+
+### Flush at `turn_end`
+
+Register a new `turn_end` handler in `src/extension.ts`.
+On each `turn_end` event, call `queueFlush(ctx)`.
+The queue contains files recorded during the turn's `tool_result` events.
+After the flush, the queue is empty; the next turn starts with clean files on disk.
+
+### Content-change detection
+
+Wrap the formatter execution with before/after content hashing to determine which files were actually changed.
+
+Add a `changedFiles` field to `ChainGroupResult`:
+
+```typescript
+export type ChainGroupResult = {
+  chain: ChainStep[];
+  files: string[];
+  runs: BatchRun[];
+  changedFiles: string[];  // files whose content changed after formatting
+};
+```
+
+In `flushPrompt()`, before running each chain group's formatter:
+
+1. Read and hash (SHA-256) each input file.
+2. Run the formatter.
+3. Re-read and hash each file.
+4. Populate `changedFiles` with files whose hash differs.
+
+Files that no longer exist after formatting (deleted by the formatter — unusual but possible) are excluded from `changedFiles`.
+
+The hashing cost is 2× reads per formatted file.
+These files are small source files already in the OS page cache (just written by the agent moments ago), so the overhead is negligible.
+
+### Steering notification
+
+After the flush, if any files changed or any run failed, compose a steering message and call `pi.sendMessage()`.
+During the turn loop, `isStreaming` is `true`, so `sendMessage` defaults to `agent.steer()`.
+The message is consumed as `pendingMessages` at the start of the next turn.
+
+Message format:
+
+```text
+[autoformat] Formatted 2 file(s): src/foo.ts, src/bar.ts
+```
+
+When there are failures:
+
+```text
+[autoformat] Formatted 1 file(s): src/foo.ts
+
+Failures:
+  biome (exit 1) on src/broken.ts:
+    SyntaxError: Unexpected token at line 42
+```
+
+When only failures (no successful changes):
+
+```text
+[autoformat] Failures:
+  biome (exit 1) on src/broken.ts:
+    SyntaxError: Unexpected token at line 42
+```
+
+File list truncated at 10 with "… and N more" suffix.
+Failure details use the existing `formatterOutput` config limits.
+
+No message is sent when:
+
+- The flush processed no files (empty queue).
+- The formatter ran but no files changed and no runs failed.
+
+### Removing `notifyAgent`
+
+Per AGENTS.md deprecation policy:
+
+- Remove `notifyAgent` from `AutoformatConfig`, `UserFormatterConfig`, `createFormatterConfig()`.
+- Remove from `schemas/pi-autoformat.schema.json` and `docs/configuration.md`.
+- In `src/config-loader.ts`: when `notifyAgent` key is present, emit a config issue (`notifyAgent has been removed; the extension now notifies via steering messages at turn end.`) and discard.
+- Remove the `agent_end` follow-up turn logic (`followUpPending`, `buildNotifyMessageContent`, `pi.sendMessage({ triggerTurn: true })`).
+- Remove `followUpPending` from `SessionState`.
+
+### `agent_end` safety net
+
+The `agent_end` handler still calls `queueFlush(ctx)` as a safety net for files added via EventBus or other non-turn paths.
+It no longer sends follow-up turns.
+In the normal case, `turn_end` has already drained the queue, so the `agent_end` flush is a no-op.
+
+### `TestPi` harness changes
+
+Add `turn_end` to the `EventName` type.
+Keep `sendMessage` capture for steering-message assertions.
+
+## Module-Level Changes
+
+### `src/prompt-autoformatter.ts`
+
+1. Add `changedFiles: string[]` to `ChainGroupResult`.
+2. In `flushPrompt()`, hash file contents before and after each chain group execution.
+3. Populate `changedFiles` by comparing hashes.
+
+### `src/formatter-config.ts`
+
+1. Remove `notifyAgent` from `UserFormatterConfig` and `AutoformatConfig`.
+2. Remove from `DEFAULT_FORMATTER_CONFIG`.
+3. Remove from `createFormatterConfig()`.
+
+### `src/config-loader.ts`
+
+1. When `notifyAgent` key is present in user config, emit a config issue and discard.
+2. Remove `notifyAgent` validation logic.
+
+### `schemas/pi-autoformat.schema.json`
+
+1. Remove `notifyAgent` property.
+
+### `src/extension.ts`
+
+1. Add a `turn_end` handler that calls `queueFlush(ctx)` and, if the result has changes or failures, sends a steering message via `pi.sendMessage()`.
+2. Extract `buildSteeringMessageContent(result): string | undefined` helper (replaces `buildNotifyMessageContent`).
+3. Simplify `agent_end` handler: remove `followUpPending` logic, keep safety-net flush only.
+4. Remove `followUpPending` from `SessionState`.
+5. Remove `buildNotifyMessageContent` (replaced by `buildSteeringMessageContent`).
+6. Update `queueFlush` return type if needed to propagate the result for steering decisions.
+
+### `docs/configuration.md`
+
+1. Remove `notifyAgent` section.
+2. Add a section explaining turn-end formatting and steering notifications.
+
+### `README.md`
+
+1. Remove `notifyAgent` references.
+2. Update description of formatting timing.
+
+### `test/extension.test.ts`
+
+1. Add `turn_end` to `EventName` type in `TestPi`.
+2. Add tests for turn-end flush behavior.
+3. Add tests for steering message on file changes.
+4. Add tests for no steering message when no changes.
+5. Add tests for steering message on formatter failure.
+6. Remove `notifyAgent`-specific tests (follow-up turn, loop guard, etc.).
+7. Update `createLoadResult` helper to drop `notifyAgent`.
+
+### `test/prompt-autoformatter.test.ts`
+
+1. Add tests for `changedFiles` population in `ChainGroupResult`.
+2. Test that unchanged files are not in `changedFiles`.
+3. Test that failed runs do not populate `changedFiles` (or populate correctly depending on behavior).
+
+### `test/config-loader.test.ts`
+
+1. Add test for legacy `notifyAgent` key producing a config issue.
+2. Remove `notifyAgent` validation tests.
+
+## TDD Order
+
+### 1. Content-change detection in `flushPrompt`
+
+- **Test surface:** `test/prompt-autoformatter.test.ts`.
+- **Covers:** `changedFiles` populated when formatter changes file content. Empty when formatter is a no-op. Files that don't exist after formatting are excluded.
+- **Commit:** `feat: detect content changes in flushPrompt (#31)`
+
+### 2. Remove `notifyAgent` from config types and defaults
+
+- **Test surface:** `test/formatter-config.test.ts`, `test/config-loader.test.ts`.
+- **Covers:** `notifyAgent` removed from types; `createFormatterConfig()` no longer accepts it. Legacy key in config emits a config issue and is discarded.
+- **Commit:** `feat!: remove notifyAgent config field (#31)`
+
+### 3. Remove `notifyAgent` from JSON schema and docs
+
+- **Test surface:** `test/schema.test.ts`, manual review.
+- **Covers:** Schema no longer includes `notifyAgent`. Docs updated.
+- **Commit:** `feat!: remove notifyAgent from schema and docs (#31)`
+
+### 4. Steering message builder
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** Message with 1 changed file, 3 changed files, 11 files (truncation). Message with failures. Message with mixed changes + failures. Returns `undefined` when no changes and no failures.
+- **Commit:** `feat: add buildSteeringMessageContent helper (#31)`
+
+### 5. Turn-end flush handler
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** `turn_end` event triggers flush. Files recorded in `tool_result` are formatted at `turn_end`. Queue is empty after flush.
+- **Commit:** `feat: flush formatters at turn_end (#31)`
+
+### 6. Steering notification on change
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** When flush changes files, `pi.sendMessage` is called with steering content. When flush is a no-op (no changes, no failures), no message is sent.
+- **Commit:** `feat: send steering notification after turn-end formatting (#31)`
+
+### 7. Steering notification on failure
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** When a formatter run fails, steering message includes failure details (stderr, exit code).
+- **Commit:** `feat: include failure details in steering notification (#31)`
+
+### 8. Remove `agent_end` follow-up turn logic
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** `agent_end` handler no longer calls `pi.sendMessage`. `followUpPending` removed from `SessionState`. `agent_end` still calls safety-net `queueFlush`.
+- **Commit:** `feat!: replace agent_end follow-up with turn-end steering (#31)`
+
+### 9. Agent-end safety-net flush
+
+- **Test surface:** `test/extension.test.ts`.
+- **Covers:** Files added via EventBus (no turn loop) are formatted at `agent_end`. Files already flushed at `turn_end` are not re-formatted at `agent_end`.
+- **Commit:** `test: agent_end safety-net flush (#31)`
+
+### 10. Documentation
+
+- **Test surface:** Manual review.
+- **Covers:** `docs/configuration.md` updated. `README.md` updated.
+- **Commit:** `docs: document turn-end formatting and steering notifications (#31)`
+
+## Risks and Mitigations
+
+### Formatter latency between turns
+
+Formatting at `turn_end` adds latency between turns — the agent waits for the formatter before its next LLM call.
+Mitigation: most turns have 1-3 touched files; formatter runs are typically sub-second.
+The existing `commandTimeoutMs` config prevents hangs.
+
+### Steering message noise
+
+Even with change detection, active editing sessions may produce frequent "Formatted X" messages.
+Mitigation: messages are only sent when content actually changed or a formatter failed.
+During long edit streaks where the agent writes already-formatted code, no messages are sent.
+
+### File I/O from content hashing
+
+Reading files before and after formatting doubles the I/O per formatted file.
+Mitigation: files are small source files already in the OS page cache.
+The hash computation (SHA-256) is negligible for typical file sizes.
+
+### Breaking change: `notifyAgent` removal
+
+Users who set `notifyAgent: true` will see a config issue.
+Mitigation: the replacement (turn-end steering) provides strictly better behavior — inline notification during the turn rather than a follow-up turn after the agent finishes.
+The deprecation policy (accept, warn, discard) ensures no hard failure.
+
+### `turn_end` not firing for non-turn paths
+
+Files added via EventBus or `session_shutdown` never pass through `turn_end`.
+Mitigation: `agent_end` and `session_shutdown` safety-net flushes handle these paths.
+
+## Open Questions
+
+1. Should the steering message include which formatter ran (e.g. "biome formatted src/foo.ts") or just the file list?
+   Start with the file list; add formatter names if users find it useful.
+
+2. Should there be a config to disable turn-end formatting entirely (revert to agent-end-only)?
+   Defer until someone needs it.
+   If needed, the implementation can gate the `turn_end` flush behind a boolean.

package/docs/retro/0002-richer-tui-formatter-summaries.md

@@ -0,0 +1,47 @@
+---
+issue: 1
+issue_title: "Add richer TUI formatter summaries"
+---
+
+# Retro: #1 — Add richer TUI formatter summaries
+
+## Final Retrospective (2026-05-02T01:09:19Z)
+
+### Session summary
+
+Planned, implemented, shipped, and released `2.2.0` for issue #1.
+Replaced transient success toasts with a persistent themed `setStatus("autoformat", ...)` footer line; failures keep the warning toast and additionally leave an error-styled status that survives until the next flush.
+Seven TDD commits plus a docs commit landed cleanly; CI green; release-please PR `#19` merged.
+
+### Observations
+
+#### What went well
+
+- TDD execution was unusually clean — seven cycles (`4d4fb8c` → `9a10d59`), every commit green, the one minor deviation (folding step 1's minimal impl into its own test commit so `main` never carried a failing test) was noted and within the slash-command's deviation guidance.
+- The lint-fixup split worked correctly: `pnpm run lint:fix` touched both source and docs files; `src/extension.ts` + `test/extension.test.ts` fixups were amended into the most recent `test:` commit and the `docs:` commit stayed docs-only, per the slash-command rule.
+- `/plan-issue`'s "Decide" step did its job — first `ask_user` surfaced that the issue was exploratory, second `ask_user` (after researching the actual Pi UI surface) converged on a concrete, shippable direction in one round.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (user-caught) — Wrote prose paragraphs in `README.md` and `docs/configuration.md` with hard wraps inside multi-sentence paragraphs.
+  `AGENTS.md` § Markdown already says "Use one sentence per line (unbroken) for better diffs."
+  Required an `--amend` of the docs commit (`1df2550`) after the user pointed it out.
+  Impact: one rework cycle, no commit churn beyond the amend, but the rule was visible in `AGENTS.md` and I had read it that session.
+- `premature-convergence` / `missing-context` — In the first `/plan-issue` `ask_user`, I assumed `ctx.ui.notify` was the only Pi UI primitive available and offered four options all routed through notifications.
+  The user redirected with "let's explore our options before we converge.
+  The Pi codebase is at `~/development/pi/pi-mono`."
+  Reading `pi-mono/packages/coding-agent/src/core/extensions/types.ts` revealed `setStatus`, `setWidget`, `custom`, and `theme.fg` — substantively richer surface area.
+  The second `ask_user` led to the actually-shipped design.
+  Impact: one extra `ask_user` round; would have produced a weaker plan if the user had not redirected.
+
+#### What caused friction (user side)
+
+- The pi-extension project depends on the Pi runtime API surface, but nothing in `AGENTS.md` or the project context points an agent at `pi-mono` for that surface.
+  The user supplied the path mid-session as a redirection.
+  Earlier mention (or a hint in `AGENTS.md`) would have eliminated the first round of shallow options.
+  Framed as opportunity, not criticism: this is the kind of context that lives in one head and can be cheaply written down once.
+
+### Changes made
+
+1. Added this retro file at `docs/retro/0002-richer-tui-formatter-summaries.md`.
+   No `AGENTS.md` or prompt changes were landed; both candidate proposals (Pi-runtime API pointer in `AGENTS.md` § Notes for Agents, and a sentence-per-line scan note in `/tdd-plan` step 3) were declined this round.

package/docs/retro/0013-fallback-chain-step-type.md

@@ -0,0 +1,67 @@
+---
+issue: 13
+issue_title: "Add `fallback` step type to formatter chains"
+---
+
+# Retro: #13 — Add `fallback` step type to formatter chains
+
+## Final Retrospective (2026-05-02T00:22:50Z)
+
+### Session summary
+
+Took issue #13 from `/plan-issue` through `/tdd-plan` and `/ship-issue` end-to-end.
+Added a `fallback` chain step type with `PATH`-only fallthrough, per-flush probe caching, and reporting that names which alternative actually ran.
+Eleven TDD commits landed cleanly into release `v2.1.0` via release-please.
+Mid-session the user introduced a new "sync with remote first" rule for all flow prompts; that work was committed independently and the TDD flow resumed without rework.
+
+### Observations
+
+#### What went well
+
+- The plan/TDD/ship flow worked end-to-end against a non-trivial change with no human-in-the-loop debugging. Eleven feat commits + acceptance test + docs landed in a single sitting and release-please picked them all up into `v2.1.0` automatically.
+- TDD discipline caught a real bug at step 10 of the plan: the acceptance test surfaced that `flushPrompt` was emitting groups with empty `runs[]` when all fallback alternatives were missing, contradicting the plan's "group is a no-op" wording.
+  Fixed in the same commit.
+- Running `pnpm exec tsc --noEmit` mid-flow caught a vacuous test in step 8 — `commandProbe` was passed via the constructor's options but TS flagged it as an unknown property. Without the typecheck the test would have passed for the wrong reason.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (self-identified, end-of-flow) — `pnpm run lint:fix` reformatted some test files; that cleanup landed inside the `docs:` commit instead of being amended onto the most recent feat commit.
+  The existing rule in `.pi/prompts/tdd-plan.md` says to amend onto the prior feat commit when not yet pushed; I had not pushed.
+  Impact: noisier final commit (`docs: document fallback chain steps...` touches 9 files instead of 2), but no rework.
+- `rabbit-hole` — markdown table column alignment with em-dashes (`—`) failed `MD060` repeatedly because em-dash width-vs-byte math was off.
+  Took three table-edit attempts to land a passing layout.
+  Should have switched to ASCII hyphen on the first failure.
+  Impact: ~1 minute, no rework.
+- `missing-context` (self-identified, step 8) — wrote a `commandProbe` test against `PromptAutoformatter` constructor options before extending `PromptAutoformatterOptions` to declare the field.
+  Test passed vacuously (unknown property silently ignored at runtime).
+  Caught by `pnpm exec tsc --noEmit`, fixed in same commit.
+  Impact: ~5 minutes to wire the option through, same commit.
+- `missing-context` (self-identified, plan-author side) — plan TDD step 10 said put the e2e test in `test/acceptance.test.ts`, but that file is gated on the real `pi` CLI.
+  Created `test/fallback-acceptance.test.ts` instead and noted the deviation in the commit body.
+  Impact: marginal — correct outcome, ~30 seconds of judgment to deviate.
+- `wrong-abstraction` — when changing `executeChainGroup`'s input shape in step 7, I rewrote `test/formatter-executor.test.ts` wholesale via `Write` instead of surgical edits.
+  All tests still covered the same surface but the diff is harder to review.
+  Impact: cosmetic.
+
+#### What caused friction (user side)
+
+- The "sync with remote first" rule (`git pull --ff-only` at the top of every flow prompt) was retrofitted mid-TDD.
+  Catching it then was good — the user noticed before I'd made anything irreversible — but had the rule existed before this session it would have eliminated one full conversational interruption.
+  Treat as a "rule earned through observation, not friction" rather than user-side friction.
+
+### Novel wins
+
+- The `/plan-issue` → `/tdd-plan` → `/ship-issue` chain produced a clean `v2.1.0` release with no manual intervention beyond the TDD execution itself.
+  This is the first session where release-please's commit grouping handled a 9-feat-commit feature cleanly into one minor bump.
+- Mid-flow prompt evolution worked: the user paused execution to update flow templates, I committed those updates as their own change, and TDD resumed without state corruption.
+
+### Insight from retro discussion
+
+Proposal B (a human-readable "use ASCII `-` in markdown tables" rule for `AGENTS.md`) was rejected with the observation: markdownlint already caught the violation — that's *why* the build failed three times — so the right behavioral lesson is "linter says column width is wrong → stop iterating on whitespace, switch to ASCII," not "add a project rule papering over a tool that already works."
+Adding rules for things the existing toolchain already detects is redundant when the project's premise is auto-formatting.
+Kept the retro file's record of the rabbit-hole as the lesson; no `AGENTS.md` change.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` — appended one clause to the lint-fixup rule: "The fixup must NOT land in a `docs:` commit." Closes the gap that produced this session's noisy `3bbc846` docs commit.
+2. `docs/retro/0013-fallback-chain-step-type.md` — this file.

package/docs/retro/0015-builtin-treefmt-and-treefmt-nix-support.md

@@ -0,0 +1,56 @@
+---
+issue: 15
+issue_title: "Built-in `treefmt` and `treefmt-nix` project formatter support"
+---
+
+# Retro: #15 — Built-in `treefmt` and `treefmt-nix` project formatter support
+
+## Final Retrospective (2026-05-02T03:50:00Z)
+
+### Session summary
+
+Took issue #15 from `/plan-issue` through `/tdd-plan` and `/ship-issue` end-to-end.
+Added two opt-in built-in formatters (`treefmt`, `treefmt-nix`), a wildcard `"*"` chain key, per-session config-root discovery cache, skip-pattern parsing, and a `treefmt-nix`-over-`treefmt` precedence rule inside `fallback` groups.
+Eleven `feat:` commits plus a `docs:` commit landed cleanly; release-please rolled them into `v2.4.0` with no human-in-the-loop debugging.
+
+### Observations
+
+#### What went well
+
+- The plan/TDD/ship flow ran end-to-end with zero rework or user intervention.
+  271 tests passed; type-check clean; release-please picked everything up.
+- Refactoring `executeChainGroup` into `executeChainGroupWithPartition` and delegating preserved the existing `BatchRun[]` API, so all 16 prior executor tests stayed green while new partition-aware behavior was added.
+  Existing tests stayed unchanged.
+- The async `discoverRoot` precedence check inside the `fallback` resolver — `treefmt-nix` wins over `treefmt` only when both PATH-probe true **and** resolve to the same root — landed first try with two focused tests (same-root override; different-root preserves user order).
+- `walkUp` + `DiscoveryCache` design (per-session memoization, sentinel for "no match") landed first try and the cache reuse test exercises it cleanly.
+
+#### What caused friction (agent side)
+
+- `other` (self-identified, post-hoc) — Two `void 0;` lines were inserted into tests (`test/builtin-formatters.test.ts:74`, `test/formatter-executor.test.ts:299`) as an `Edit`-tool workaround: when inserting tests near visually similar text, I padded `oldText` with a fake marker line instead of widening `oldText` with more surrounding context.
+  Impact: 2 lines of dead code shipped to `main`; cleanup deferred to this retro commit.
+- `other` (lint-caught at end of TDD) — `wildcardConfig` const left over in `test/prompt-autoformatter.test.ts` after I switched the wildcard test from a fake-formatter-shadow approach to monkey-patching the real built-in registry mid-edit.
+  Biome flagged the unused-binding warning during `pnpm run lint`; removed during the lint-fixup amend.
+  Impact: one extra edit cycle, amended into the most recent feat commit per the prompt's rule.
+- `missing-context` (step 5) — `treefmtConfigPath` initially used `existsSync` to choose between `treefmt.toml` and `.treefmt.toml`, which broke a unit test that passed `/repo` as the root without creating any files on disk.
+  Adjusted to default to the canonical `treefmt.toml` when neither file exists.
+  Impact: one extra red→green cycle within step 5, no rework.
+- `instruction-violation` (self-identified, mild) — Plan suggested separate `test:` then `feat:` commits per TDD step.
+  I bundled each step's test + implementation into one `feat:` commit, citing AGENTS.md's "small reviewable commits" preference.
+  Noted as a deviation in the summary; not flagged by the user.
+  Impact: none; arguably the right call given AGENTS.md, but the prompt itself already says "`test:` for test-only commits (rare; usually folded into the feat)" — so this matches the prompt's own hint.
+
+#### What caused friction (user side)
+
+- None worth flagging — the user ran the three slash-command prompts and let them complete.
+  This is a sign the prompts are doing the right thing, not a friction point.
+
+### Changes made
+
+1. Removed leftover `void 0;` cruft from `test/builtin-formatters.test.ts` (line 74) and `test/formatter-executor.test.ts` (line 299).
+2. Added a one-line rule to the `## Testing` section of `AGENTS.md`: "Do not insert no-op statements (`void 0;`, unused locals) in tests just to make an `Edit` tool's `oldText` unique — widen `oldText` with surrounding context instead."
+3. Wrote this retro file at `docs/retro/0015-builtin-treefmt-and-treefmt-nix-support.md`.
+
+### Cross-session pattern
+
+The pattern from #13 holds: when the plan is detailed enough to enumerate types, edge cases, and TDD ordering, the TDD execution is essentially mechanical and lands without rework.
+The friction sources are now small enough to be agent-tooling artifacts (`Edit` no-op markers, in-flight refactor cruft) rather than design or strategy gaps.

package/docs/retro/0016-detailed-formatter-output-on-failure.md

@@ -0,0 +1,60 @@
+---
+issue: 2
+issue_title: "Support optional detailed formatter output in reports"
+---
+
+# Retro: #2 — Support optional detailed formatter output in reports
+
+## Final Retrospective (2026-05-02T02:15:00Z)
+
+### Session summary
+
+Triaged the open backlog, picked issue #2, planned (`docs/plans/0016-detailed-formatter-output-on-failure.md`), implemented across ten TDD cycles, and shipped `2.3.0`.
+Added an opt-in `formatterOutput` config object that surfaces a failed formatter run's `stderr` (or `stdout + stderr`) with tail-preserving byte/line truncation; defaults preserve prior concise reporting.
+While testing, the user reported an "Unexpected runtime error: ... `fgColors`" warning above the editor that traced to a latent `this`-binding bug in `themed()` from the plan-0002 work; landed a regression test plus fix (`6ba7576`, `6a6ec16`) in the same release.
+
+### Observations
+
+#### What went well
+
+- Backlog triage at the start was useful as a standalone workflow — `gh issue list` → ranked recommendation → user pick.
+  The format ("top picks / defer / recommendation") gave the user a real choice without forcing a single answer.
+- Plan-number selection caught a small alignment hazard preemptively: `0002` was taken (mismatched with issue #2), `0005` was the next free slot, but I picked `0016` to keep `0015` reserved for issue #15.
+  Tiny detail; the kind of thing only worth noting because it would have been irritating to fix later.
+- TDD execution was clean — ten cycles, every commit landed green.
+  Step 9's truncation e2e test was already green when written, which surfaced as evidence the helper-module boundary (`src/formatter-output-report.ts`) was at the right level: unit tests had already covered the corners.
+- The mid-session `fgColors` bug investigation was textbook: read the user's symptom, traced through our `themed()` helper, opened `pi-mono`'s `Theme` class, identified the destructured-method `this`-loss pattern, then took the user's correction ("Other way around, I want to put the test in that should fail") and ran proper red→green TDD on the fix.
+- The "outstanding changes" moment after committing the plan was a nice meta-confirmation: the autoformat extension itself reformatted the plan file we'd just written, exactly as advertised.
+  Folded as a single `docs: apply autoformat to plan 0016` follow-up.
+
+#### What caused friction (agent side)
+
+- `missing-context` (user-caught, latent) — The test stubs throughout `test/extension.test.ts` use `theme: { fg: (_name, text) => text }`, a plain function that doesn't depend on `this`.
+  Pi's real `Theme.fg` is an instance method that reads `this.fgColors`.
+  The shape mismatch hid a `this`-binding bug from plan-0002's `themed()` helper for a full release cycle until the user surfaced it from running against their custom catppuccin theme.
+  Impact: one user-reported warning in production, one regression test (`6ba7576`), one fix commit (`6a6ec16`).
+  Diagnosis required reading `pi-mono/packages/coding-agent/src/modes/interactive/theme/theme.ts` — the same external repo flagged in the #1 retro as missing from the agent's onboarding context.
+- `premature-convergence` (self-identified, low-impact) — On the `formatterOutput` config shape (single boolean vs object with knobs), I judged the issue's "Follow-up ideas" unambiguous and skipped the `ask_user` gate.
+  The shape landed fine, but a 30-second sanity check would have been cheap insurance for a permanent config surface.
+  No rework, no change of direction.
+  Impact: added confidence cost; no commit churn.
+- `scope-drift` (sanctioned, worth noting) — The `themed()` `this`-binding fix is unrelated to issue #2.
+  The user explicitly directed the fix during the session, and the close comment flagged it as out-of-scope-but-found-while-testing.
+  Combining the fix into release `2.3.0` was kinder to the user (one push, one release) but slightly conflates the release notes.
+  No rework; flagged here so the pattern is visible.
+
+#### What caused friction (user side)
+
+- The `pi-mono` repo at `~/development/pi/pi-mono` is the canonical reference for Pi's runtime API surface (`ExtensionApi`, `Theme`, etc.).
+  This is the second consecutive retro where reading `pi-mono` was decisive — first to discover `setStatus`/`theme.fg` (#1 retro), now to diagnose a `this`-binding bug rooted in that same surface.
+  The path lives in one head; surfacing it once in `AGENTS.md` would have eliminated a redirection in #1 and accelerated diagnosis in #2.
+  Framed as opportunity, not criticism: low-cost, high-payoff context to write down.
+
+### Changes made
+
+1. Added this retro file at `docs/retro/0016-detailed-formatter-output-on-failure.md`.
+2. Added a one-line `pi-mono` pointer at the end of `AGENTS.md` § Notes for Agents — then **reverted it** in the same retro commit after a follow-up question surfaced that Pi publishes `@mariozechner/pi-coding-agent` to npm.
+   The right fix is to depend on the published types package, not to point agents at a sibling git checkout.
+3. Opened issue #22 ("Depend on `@mariozechner/pi-coding-agent` for runtime types instead of duck-typing") to track the typing refactor.
+   The duck-typed `*Like` aliases in `src/extension.ts` are what let the `theme.fg` `this`-binding bug ship; switching to real types from the published Pi package would have caught it at compile time.
+   Tracked as a follow-up rather than implemented inline because the change touches `package.json`, `src/extension.ts`, and several test files — over the retro's scope budget.