@gotgenes/pi-autoformat 0.1.0 → 4.0.3

package/docs/plans/0012-remove-unused-formatter-extensions-field.md

@@ -0,0 +1,152 @@
+---
+issue: 12
+issue_title: "Remove unused `extensions` field from formatter definitions"
+---
+
+# Plan: Remove Unused `extensions` Field From Formatter Definitions (Issue #12)
+
+## Problem Statement
+
+`FormatterDefinition.extensions` is required by the type, populated in built-in defaults, validated by the config loader, declared in the JSON schema, and shown in docs — but no code in the dispatch path reads it.
+Dispatch is purely chain-driven (`config.chains?.[extension]`).
+The field is dead weight and a maintenance trap: users updating `chains` can leave per-formatter `extensions` metadata stale with no feedback.
+Removing it sharpens the conceptual model: `formatters` answers **how** to invoke a tool, `chains` answers **when** and **in what order**.
+
+This is a **breaking change** to the public config and TypeScript types.
+
+## Goals
+
+- Drop `extensions` from `FormatterDefinition` (TypeScript type, schema, defaults, docs, README).
+- Have the config loader silently drop a stray `extensions` key on a user-provided formatter, with one non-fatal config-issue notice per occurrence so stale metadata is visible without breaking existing configs.
+- Keep dispatch behavior unchanged — `chains` already drives everything.
+- Keep schema, loader, defaults, and docs aligned (per AGENTS.md).
+
+This is a **breaking change** for users who write code against the exported `FormatterDefinition` type.
+Runtime config files that still carry `extensions` continue to load.
+
+## Non-Goals
+
+- Adding per-formatter `when` predicates (referenced in the issue as future work — leave attachment point clean, do not implement).
+- Adding chain-level `fallback` steps (#13).
+- Auto-rewriting users' on-disk config files.
+- Changing dispatch, batching, or chain resolution.
+
+## Background
+
+Relevant modules:
+
+- `src/formatter-registry.ts` — declares `FormatterDefinition` (with required `extensions`); `groupFilesByChain` and `resolveChain` never read `extensions`.
+- `src/formatter-config.ts` — built-in defaults set `extensions` on `prettier` and `markdownlint-cli2`; the same extensions are also enumerated in `chains`, so `chains` is the single source of truth at runtime.
+- `src/config-loader.ts` — `validateFormatterDefinition` requires both `command` and `extensions`, calls `validateExtensionArray`, and returns the validated `extensions` on the resolved definition.
+- `schemas/pi-autoformat.schema.json` — `formatterDefinition.extensions` is declared (not in `required`, but documented).
+- `docs/configuration.md` and `README.md` — example configs and the formatter-definition reference both list `extensions`.
+- Tests across `test/config-loader.test.ts`, `test/formatter-registry.test.ts`, `test/formatter-config.test.ts` construct definitions with `extensions`.
+
+## Design Overview
+
+### Type shape
+
+```typescript
+// before
+export type FormatterDefinition = {
+  command: string[];
+  extensions: string[];
+  environment?: Record<string, string>;
+  disabled?: boolean;
+};
+
+// after
+export type FormatterDefinition = {
+  command: string[];
+  environment?: Record<string, string>;
+  disabled?: boolean;
+};
+```
+
+### Config-loader migration
+
+`validateFormatterDefinition` currently treats `extensions` as a required, validated property and rejects unknown keys.
+After the change:
+
+- `extensions` is **not** in `FormatterDefinition` and is **not** required.
+- If a user config still includes `extensions` on a formatter, the loader emits a single non-fatal config issue (`formatters.<name>.extensions` → "Deprecated. Remove this field; dispatch is driven by `chains`. The value is ignored.") and discards the value.
+  This is consistent with the existing config-issue plumbing — surfacing the trap without breaking startup.
+- Any other unknown formatter key continues to raise the existing "Unknown formatter property." issue.
+
+### Schema
+
+- Remove the `extensions` property from `$defs.formatterDefinition.properties`.
+- Schema stays `additionalProperties: false`.
+  Editor validators will flag stale `extensions` keys as unknown — that is the desired UX for editor users; the runtime loader still tolerates them with a deprecation notice for already-deployed configs.
+
+### Defaults
+
+`DEFAULT_FORMATTER_CONFIG.formatters.prettier` and `markdownlint-cli2` lose their `extensions` arrays.
+The `chains` map is unchanged and remains the single source of truth.
+
+### Docs
+
+- `docs/configuration.md` and `README.md`: drop `extensions` from JSON examples and from the `FormatterDefinition` reference.
+- Add a short note in `docs/configuration.md` explaining that legacy `extensions` keys are accepted but ignored, and recommending removal.
+
+### Edge cases
+
+- A formatter that currently has only `command` + `extensions` and no chain entry: previously already a no-op at dispatch (chain-driven); behavior unchanged.
+- An empty user-supplied `extensions: []`: previously failed validation (`minItems: 1`).
+  After: still surfaces the deprecation notice and is dropped — does not fail.
+
+## Module-Level Changes
+
+- `src/formatter-registry.ts`
+  - Remove `extensions: string[]` from `FormatterDefinition`.
+- `src/formatter-config.ts`
+  - Remove `extensions` arrays from the two built-in formatter defaults.
+- `src/config-loader.ts`
+  - Remove `validateExtensionArray` (no other callers) **only if unused** after the change; otherwise leave in place.
+  - In `validateFormatterDefinition`:
+    - Drop `extensions` from the required-fields gate.
+    - Replace the `key === "extensions"` branch with a single deprecation notice and skip storing the value.
+    - Stop returning `extensions` on the resolved definition.
+- `schemas/pi-autoformat.schema.json`
+  - Remove the `extensions` property from `$defs.formatterDefinition.properties`.
+- `docs/configuration.md`, `README.md`
+  - Strip `extensions` from examples and field reference; add deprecation note.
+- `test/config-loader.test.ts`, `test/formatter-registry.test.ts`, `test/formatter-config.test.ts`, and any other test that constructs a `FormatterDefinition`
+  - Drop `extensions` from constructed definitions.
+  - Add new coverage (see TDD Order).
+
+## TDD Order
+
+1. **red** — Add a `config-loader.test.ts` case: a user formatter with `extensions: [".ts"]` loads successfully, the resolved definition has no `extensions` key, and a single config issue is recorded for `formatters.<name>.extensions` describing the deprecation.
+   commit: `test: cover deprecated extensions field on formatter`
+2. **green** — Update `validateFormatterDefinition` to drop `extensions` from the required gate, emit the deprecation notice, and stop populating the field.
+   Remove `validateExtensionArray` if it has no remaining callers.
+   commit: `feat!: drop extensions field from formatter definitions`
+3. **red→green** — Update `formatter-registry.ts` type, `formatter-config.ts` defaults, and any existing tests that constructed `extensions`.
+   Tests should still pass (or be updated to no longer reference `extensions`).
+   Add a `formatter-config.test.ts` assertion that `DEFAULT_FORMATTER_CONFIG.formatters.prettier` has no `extensions` key.
+   commit: `feat!: remove extensions from FormatterDefinition type and defaults`
+4. **red→green** — Update `schemas/pi-autoformat.schema.json` to remove the `extensions` property and add a schema-shape test (or extend an existing one) that verifies the schema no longer declares it.
+   commit: `feat!: drop extensions from pi-autoformat JSON schema`
+5. **docs** — Update `docs/configuration.md` and `README.md`: strip `extensions` from examples and reference; add a deprecation note pointing users at `chains`.
+   commit: `docs: remove formatter extensions field and note deprecation`
+
+Each cycle leaves the repo in a green state.
+
+## Risks and Mitigations
+
+- **Risk:** Existing user configs on disk still contain `extensions`.
+  **Mitigation:** Loader accepts and ignores them with a single deprecation notice per formatter; no startup failure.
+- **Risk:** Editor validation flags `extensions` as an unknown property under `additionalProperties: false`.
+  **Mitigation:** This is the intended signal — the runtime tolerates it. Document the removal in `docs/configuration.md`.
+- **Risk:** Downstream code imports `FormatterDefinition` and constructs values with `extensions`.
+  **Mitigation:** Marked as breaking (`feat!:`). Release-please will bump major; CHANGELOG will call out the removal.
+- **Risk:** Tests across multiple files reference `extensions`.
+  **Mitigation:** TDD cycle 3 sweeps all tests in one commit; CI catches stragglers.
+
+## Open Questions
+
+- Should the deprecation notice be a one-time aggregate ("config still uses `extensions` on N formatters") instead of one-per-formatter?
+  Defer until we see real configs in the wild; per-formatter is more actionable.
+- Should we provide a one-shot codemod (`pi-autoformat migrate`) to strip `extensions` from on-disk configs?
+  Defer; the deprecation notice is sufficient for now.

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

@@ -0,0 +1,280 @@
+---
+issue: 13
+issue_title: "Add `fallback` step type to formatter chains"
+---
+
+# Plan: Add `fallback` Step Type to Formatter Chains (Issue #13)
+
+## Problem Statement
+
+Today, `chains` entries are flat lists of formatter names — every named formatter runs in order and is expected to apply.
+That works when each step does a distinct job (Prettier formats, then markdownlint-cli2 lints), but it does not handle the common case where a project standardizes on **one of several alternatives** (e.g. Biome *or* Prettier).
+Users either list both (the second undoes the first or fails noisily) or pick one globally (wrong half the time).
+A `fallback` step type lets a single global default chain adapt to whichever tool a given repo actually uses, with no per-project boilerplate.
+
+## Goals
+
+- Extend chain step shape: each step is either a string (single formatter, current behavior) or `{ "fallback": [name, ...] }`.
+- Implement `PATH`-only fallthrough semantics: skip when the command is not on `PATH`; stop on first formatter that runs (success **or** non-zero exit); group is a no-op if no formatter is on `PATH`.
+- Cache `PATH` probes per flush so a chain step does not re-probe the same command repeatedly.
+- Surface which fallback alternative actually ran when it was not the first listed (e.g. `prettier (fallback after biome unavailable)`).
+- Update schema, config loader, docs, and README in the same change (per AGENTS.md).
+- Stay **fully backward compatible** with existing string-only chains.
+
+This is a **non-breaking** change.
+Existing configs and types continue to work unchanged.
+
+## Non-Goals
+
+- A per-formatter `when: { configExists: [...] }` predicate — explicitly deferred per the issue.
+- Auto-detecting which formatter a repo "really" uses based on its config files.
+- Parallel probing of fallback alternatives — sequential is fine; the list is short and the probe is cached.
+- Cross-flush caching of `PATH` probes (a flush is short-lived; per-flush is enough).
+- Reworking `groupFilesByChain`'s grouping key beyond what the new shape requires.
+
+## Background
+
+Relevant modules:
+
+- `src/formatter-registry.ts` — declares `FormatterConfig` with `chains?: Record<string, string[]>` and exposes:
+  - `groupFilesByChain(files, config)` — keys files by chain identity (joined with `\u0000`).
+  - `resolveChain(chainNames, config)` — turns formatter names into `ResolvedFormatter[]`, dropping disabled / missing entries.
+- `src/formatter-executor.ts` — `executeChainGroup` runs a resolved chain once per group, appending the group's files as trailing args. Returns one `BatchRun` per chain step.
+- `src/prompt-autoformatter.ts` — orchestrates flush: queue → `groupFilesByChain` → `resolveChain` → `executeChainGroup`.
+- `src/config-loader.ts` — `validateChains` uses `validateStringArray`, so today every step must be a string.
+- `src/formatter-config.ts` — built-in defaults populate `chains` with string arrays only.
+- `schemas/pi-autoformat.schema.json` — `chains` items are `{ "type": "string" }`.
+- `src/extension.ts` — `summarizeFailures` reads `run.formatterName` / `run.files` from `BatchRun`s.
+
+The architecture is already chain-oriented and batch-based; the work is to extend the chain *step* type and have the executor decide, per fallback group, which single formatter actually runs.
+
+## Design Overview
+
+### Data shapes
+
+A chain becomes a list of *steps*.
+A step is either a formatter name (string) or a fallback group.
+
+```typescript
+export type FallbackChainStep = {
+  fallback: string[];
+};
+
+export type ChainStep = string | FallbackChainStep;
+
+export type FormatterConfig = {
+  formatters: Record<string, FormatterDefinition>;
+  chains?: Record<string, ChainStep[]>;
+};
+```
+
+Internally, after validation, we normalize every step to a discriminated form so downstream code does not branch on `typeof`:
+
+```typescript
+type NormalizedChainStep =
+  | { kind: "single"; formatter: string }
+  | { kind: "fallback"; formatters: string[] };
+```
+
+The string form is sugar for `{ kind: "single", formatter: name }`.
+A `{ fallback: [a] }` group with one entry is *not* rewritten into a single step — it stays a fallback group of one so reporting (and `PATH` probing) is consistent.
+
+### Grouping key
+
+`groupFilesByChain` currently keys on the chain-name list joined by `\u0000`.
+The key must remain stable and JSON-comparable for normalized steps.
+Use a canonical encoding:
+
+- single step → `"S:<name>"`
+- fallback group → `"F:<a>|<b>|<c>"`
+
+Then join steps with `\u0000`.
+This keeps grouping behavior identical for string-only chains (different prefix is fine — the encoding is internal) and gives fallback groups a unique, comparable identity.
+
+### Resolution and execution
+
+`resolveChain(steps, config)` returns a list of *resolved steps*, where each step carries either one resolved formatter or an ordered list of resolved-formatter alternatives:
+
+```typescript
+type ResolvedSingleStep = {
+  kind: "single";
+  formatter: ResolvedFormatter;
+};
+
+type ResolvedFallbackStep = {
+  kind: "fallback";
+  alternatives: ResolvedFormatter[]; // disabled/unknown formatters dropped
+};
+
+type ResolvedChainStep = ResolvedSingleStep | ResolvedFallbackStep;
+```
+
+A fallback step whose alternatives all reduce to disabled / unknown is dropped (same posture as a single step that names a missing formatter).
+
+`executeChainGroup` then, for each resolved step:
+
+- **single**: behaves exactly as today.
+- **fallback**: probes each alternative's `command[0]` against `PATH`, **in order**, using a cached probe.
+  The first alternative that is on `PATH` runs.
+  If it exits 0 → success, stop.
+  If it exits non-zero → failure, stop, report (do **not** mask by trying the next alternative).
+  If none of the alternatives are on `PATH` → no `BatchRun` is emitted (group is a no-op as specified).
+
+### `PATH` probing
+
+Implemented as a small helper that:
+
+- accepts an absolute path verbatim (returns true if the file exists and is executable).
+- otherwise walks `process.env.PATH`, checking each segment for an executable matching the command name (Windows handling is out of scope; this extension already assumes POSIX-style invocation).
+- caches results in a `Map<string, boolean>` injected per flush so a chain with the same fallback group across many file groups probes once.
+
+The probe is dependency-injectable so tests can stub it without touching the filesystem.
+
+### Reporting
+
+`BatchRun` gains an optional `fallbackContext` field used purely for human-readable reporting:
+
+```typescript
+export type BatchRun = {
+  formatterName: string;
+  command: string[];
+  files: string[];
+  success: boolean;
+  exitCode: number;
+  stdout?: string;
+  stderr?: string;
+  fallbackContext?: {
+    skipped: string[]; // formatter names skipped because not on PATH
+  };
+};
+```
+
+`extension.ts` `summarizeFailures` and the success summary path render this as `"<name> (fallback after <skipped...> unavailable)"` when `skipped` is non-empty.
+When the fallback group's first alternative wins, `fallbackContext` is omitted (quiet, same as a single-formatter step).
+
+A fallback group that ends in "all alternatives missing" emits **no** `BatchRun` — there is nothing to report at the chain-step level — but logs a single config-issue-style notice through the existing reporter so the user is not silently formatted-nothing.
+This is delivered via the standard reporter, not a new channel.
+
+### Config validation
+
+`validateChains` becomes:
+
+- accept either a string or a `{ fallback: string[] }` object per array entry.
+- reject any other shape with a clear path-aware message.
+- require `fallback` to be a non-empty array of non-empty strings.
+- reject unknown sibling keys on a fallback object (`additionalProperties: false`).
+- emit a non-fatal config-issue (and skip the offending step) when a fallback alternative names a formatter that is not present in `config.formatters` and is not a known built-in default.
+  This catches typos cheaply.
+- the same name-existence check is applied to single string steps for consistency (it is currently silently dropped at resolve time).
+
+### Edge cases
+
+- Empty `fallback: []` → validation error.
+- Fallback containing one entry → legal, treated as a fallback-of-one (still PATH-probed; a missing tool quietly no-ops instead of trying to run and failing).
+- A fallback alternative is `disabled: true` → treat as if absent (skip without probing).
+- A fallback step where every alternative is disabled or unknown → resolved-step is dropped; behaves like a no-op step.
+- Mixing fallback and single steps in one chain (e.g. `[{fallback: [...]}, "markdownlint-cli2"]`) → fully supported; second step always runs.
+- Same fallback group declared on multiple extensions → grouping key is identical, so files share the group and the `PATH` probe runs once.
+
+## Module-Level Changes
+
+- `src/formatter-registry.ts`
+  - Export `ChainStep`, `FallbackChainStep`, `NormalizedChainStep`, `ResolvedChainStep`, `ResolvedSingleStep`, `ResolvedFallbackStep`.
+  - Update `FormatterConfig.chains` to `Record<string, ChainStep[]>`.
+  - Add a `normalizeChainStep` helper used by both grouping and resolution.
+  - Update `groupFilesByChain` to use the new canonical encoding for the grouping key.
+  - Update `resolveChain` to return `ResolvedChainStep[]` and to drop fallback steps with no usable alternatives.
+- `src/formatter-executor.ts`
+  - Add `CommandProbe` type (`(command: string) => boolean | Promise<boolean>`) and a default `PATH`-walking implementation.
+  - Add a per-flush cache wrapper.
+  - Update `ChainGroupInput.chain` to `ResolvedChainStep[]`.
+  - Update `executeChainGroup` to dispatch by step kind, applying fallback semantics for fallback steps.
+  - Add `fallbackContext` to `BatchRun` (optional).
+- `src/prompt-autoformatter.ts`
+  - Construct one shared probe cache per `flushPrompt` call and pass it into `executeChainGroup`.
+  - No external API change.
+- `src/config-loader.ts`
+  - Replace the current `validateStringArray`-based chain validator with a per-step validator that accepts string or `{ fallback: string[] }`.
+  - Add formatter-name existence checks (non-fatal, single config-issue per offense).
+- `src/formatter-config.ts`
+  - Defaults stay string-only (no behavior change).
+- `schemas/pi-autoformat.schema.json`
+  - `chains.additionalProperties.items` becomes a `oneOf` of `string` and `{ fallback: string[] }`.
+  - Document fallback semantics inline.
+- `src/extension.ts`
+  - Render `fallbackContext.skipped` in success and failure summaries.
+  - Surface "all fallback alternatives missing" as a one-line notice.
+- `README.md`
+  - Add the **Choosing a chain strategy** section with the project-vs-global recommendation.
+  - Add the **Fallback caveat** block next to the new feature description.
+  - Update the chains example to show a fallback group.
+- `docs/configuration.md`
+  - Extend the `chains` section with the new step shape, semantics table, and fallback caveat.
+
+## TDD Order
+
+1. **Schema test for chain step shape.**
+   Extend `test/schema.test.ts` with valid string-and-fallback fixtures and invalid `{}` / `{ fallback: [] }` / extra-key fixtures.
+   Update `schemas/pi-autoformat.schema.json` to make them pass.
+   Commit: `test: cover fallback chain step shape in schema`, then `feat: allow fallback chain steps in schema`.
+2. **Config-loader: accept fallback steps.**
+   In `test/config-loader.test.ts`, cover string steps still loading, fallback objects loading, malformed fallback rejected, unknown sibling keys rejected, empty fallback rejected.
+   Implement in `src/config-loader.ts`.
+   Commit: `test: cover fallback step validation`, then `feat: validate fallback chain steps in config loader`.
+3. **Config-loader: formatter-name existence check.**
+   Tests for fallback referencing an unknown formatter (non-fatal config-issue, step dropped) and same for a single string step.
+   Implement.
+   Commit: `test: warn on chain steps referencing unknown formatters`, then `feat: surface unknown formatter names in chains as config issues`.
+4. **Registry: chain step types and grouping key.**
+   In `test/formatter-registry.test.ts`, cover normalized step shapes, grouping key stability for string-only chains, distinct grouping for differing fallback orderings, identical grouping for identical fallback orderings.
+   Implement type changes plus key encoding.
+   Commit: `test: extend chain grouping for fallback steps`, then `feat: support fallback steps in chain grouping`.
+5. **Registry: resolve chain returns resolved steps.**
+   Tests for resolving a single-only chain, a fallback with mixed disabled/unknown alternatives, dropping a fallback whose alternatives all reduce away.
+   Implement.
+   Commit: `test: resolve fallback steps to alternatives`, then `feat: resolve fallback chain steps`.
+6. **Executor: PATH probing helper.**
+   New tests for a probe helper covering absolute-path executables, `PATH`-walked executables, missing commands, and cache reuse.
+   Implement and inject.
+   Commit: `test: cover PATH-probe helper`, then `feat: add PATH probe with per-flush cache`.
+7. **Executor: fallback dispatch semantics.**
+   Tests for: first alternative present (runs, no `fallbackContext`), first missing / second present (runs, `fallbackContext.skipped` populated), first present and exits non-zero (failure surfaced, second NOT tried), all missing (no `BatchRun` emitted), single steps unchanged.
+   Implement in `executeChainGroup`.
+   Commit: `test: cover fallback dispatch semantics`, then `feat: dispatch fallback chain steps`.
+8. **Prompt autoformatter: shared probe cache.**
+   Test that two file groups whose chains share a fallback group probe each command at most once per flush.
+   Wire the cache through `flushPrompt`.
+   Commit: `test: share PATH probe cache across chain groups in a flush`, then `feat: share PATH probe cache across flush`.
+9. **Reporting: surface fallback context.**
+   Tests in `test/extension.test.ts` (or wherever `summarizeFailures` is exercised) covering success render with `fallbackContext`, failure render with `fallbackContext`, and the "all fallback alternatives missing" notice.
+   Implement in `src/extension.ts`.
+   Commit: `test: render fallback context in summaries`, then `feat: surface fallback context in flush reporting`.
+10. **Acceptance + smoke.**
+    End-to-end test in `test/acceptance.test.ts`: a `.ts` chain `[{ fallback: ["biome", "prettier"] }]` with biome absent and prettier present produces a single prettier batch run with `fallbackContext.skipped = ["biome"]`.
+    Commit: `test: end-to-end fallback chain run`.
+11. **Docs.**
+    Update `README.md` (Choosing-a-chain-strategy section + Fallback caveat + example) and `docs/configuration.md` (chain shape + semantics table).
+    Commit: `docs: document fallback chain steps and project-config recommendation`.
+
+## Risks and Mitigations
+
+- **Risk: silent fallback hides missing project config.**
+  A globally installed Biome will format with built-in defaults in a Prettier repo.
+  *Mitigation:* required README **Fallback caveat** block plus the **Choosing a chain strategy** recommendation; the docs explicitly point users at project-level chains. No runtime mechanism added (per AGENTS.md: "Mechanism is forever; docs are reversible.").
+- **Risk: PATH probing is platform-fragile.**
+  *Mitigation:* dependency-inject the probe so tests stub it; default implementation walks `process.env.PATH` and `fs.access(X_OK)`-style checks. Match the existing extension's POSIX assumption.
+- **Risk: probe overhead on every flush.**
+  *Mitigation:* per-flush cache; only probe a command once even across many fallback groups.
+- **Risk: grouping-key collision between old encoding and new.**
+  *Mitigation:* the encoding is internal — keys are computed fresh from the in-memory config every flush, never persisted. No migration needed.
+- **Risk: users typo a formatter name in a fallback group.**
+  *Mitigation:* config loader emits a non-fatal config-issue per occurrence and drops the offending entry.
+- **Risk: scope creep into a `when` predicate.**
+  *Mitigation:* explicitly out of scope per the issue and re-asserted in Non-Goals.
+
+## Open Questions
+
+- Should the "all fallback alternatives missing" notice be one-shot per flush, or one per group?
+  Tentatively: one per group, but quiet — defer until we see real noise.
+- Should the success summary always mention the fallback alternative that ran, or only when it was not the first listed?
+  Tentatively: only when it was not the first, matching the issue's reporting guidance.

package/docs/plans/0014-batch-by-default-formatter-dispatch.md

@@ -0,0 +1,195 @@
+---
+issue: 14
+issue_title: "Batch-by-default formatter dispatch"
+---
+
+# Plan: Batch-by-Default Formatter Dispatch (Issue #14)
+
+## Problem Statement
+
+The current executor invokes each formatter once per touched file, substituting `$FILE` per call.
+This pays N startup costs for N touched files, produces N noisy notifications, and is incompatible with batch-only tools like `treefmt`.
+Effectively every common formatter (prettier, biome, ruff, black, gofmt, rustfmt, shfmt, dprint, markdownlint-cli2, etc.) accepts multiple paths in a single invocation, so per-file dispatch is a self-imposed limitation.
+
+## Goals
+
+- Run each formatter step **once per chain group**, with all touched files in that group appended as trailing arguments.
+- Adopt a single "command + args, then file paths appended" convention that mirrors `pi-formatter`'s `appendFile` shape.
+- Make `tool`-mode formatting degenerate cleanly to a single-path batch.
+- Surface batch failures clearly: exit code + which files were in the batch.
+
+This is a **breaking change**.
+We are not maintaining `$FILE` substitution backcompat — see Compatibility below.
+
+## Non-Goals
+
+- Implementing the `fallback` step type (#13).
+  This plan only ensures the new batch executor is shaped so that #13 can plug in at the group level later.
+- Built-in `treefmt` support (separate issue).
+  This plan unblocks it but does not add it.
+- Parallel chain-group execution.
+  Groups still flush sequentially.
+- Reworking the touched-files queue, mutation detectors, or scope resolution.
+- Per-file outcome parsing from formatter stdout/stderr.
+  The result shape leaves room for it; v1 reports per-batch only.
+
+## Background
+
+Relevant existing pieces:
+
+- `src/formatter-registry.ts` — resolves a chain per file, substitutes `$FILE` in each formatter command.
+- `src/formatter-executor.ts` — runs a chain for a single file, command-by-command.
+- `src/prompt-autoformatter.ts` — loops over touched files, resolving and executing a chain per file.
+- `src/extension.ts` — `defaultReportFlushResult` summarizes per-file results from `PromptAutoformatterResult`.
+
+The architecture is already chain-oriented; the work is to lift the unit of execution from "one file" to "one group of files that share a chain."
+
+## Design Overview
+
+### Dispatch model
+
+1. After flushing the touched-files queue, group files by their chain identity (same ordered list of formatter names → same group).
+   Files with no chain are dropped as today.
+2. For each group, resolve the chain once (formatter name → command + env), then run each chain step once with the group's file paths appended as trailing arguments.
+3. Chain steps run sequentially within a group.
+   Groups themselves are processed sequentially (no concurrency change).
+4. A failing step does not abort later steps in the group — same policy as today's per-file chain.
+
+**Grouping key**: the chain's formatter-name list joined with a NUL separator (e.g. `"prettier\0markdownlint-cli2"`).
+Stable, comparable, independent of file paths.
+
+**Separation of concerns**: grouping is about files ("which files share a chain?"); resolution is about formatters ("what command does this chain expand to?").
+The two operations are split into distinct functions so neither has to know about the other's inputs.
+
+### Formatter command convention
+
+A formatter's `command` is **configured args only**.
+The executor appends the batch's file paths verbatim:
+
+```json
+"formatters": {
+  "prettier": { "command": ["prettier", "--write"] },
+  "markdownlint-cli2": { "command": ["markdownlint-cli2", "--fix"] }
+}
+```
+
+No substitution.
+No special tokens.
+The schema rejects `$FILE` as invalid.
+
+### Compatibility
+
+This is a breaking change.
+Configs containing `$FILE` are rejected at config-load time with a clear validation issue:
+
+> Formatter `prettier`: `$FILE` is no longer supported.
+> Remove it — file paths are appended automatically.
+> See `docs/configuration.md`.
+
+The formatter is treated as misconfigured (skipped) until the user updates the config.
+We do not silently strip the token, because silently changing the resolved command would mask real misconfiguration (e.g. `--stdin-filepath $FILE -` becoming `--stdin-filepath -`).
+
+Validation lives in the config loader alongside existing schema checks and surfaces through the established `reportConfigIssues` path.
+
+### Failure handling
+
+- Each chain-step invocation produces one `BatchRun` with: command, exit code, stdout, stderr, and the file paths it ran against.
+- v1 does not parse formatter output for per-file outcomes.
+  On non-zero exit, the entire batch is reported as failed and stderr is surfaced once.
+  This avoids per-formatter parsers and keeps the contract narrow.
+- Per-file output parsing is a follow-up; the result shape leaves room for it.
+
+### Result shape
+
+`PromptAutoformatterResult` becomes batch-first:
+
+```ts
+type BatchRun = {
+  formatterName: string;
+  command: string[];          // resolved command including appended files
+  files: string[];            // files in this batch
+  success: boolean;
+  exitCode: number;
+  stdout?: string;
+  stderr?: string;
+};
+
+type ChainGroupResult = {
+  chain: string[];            // formatter names, in order
+  files: string[];            // files in this group
+  runs: BatchRun[];           // one per chain step
+};
+
+type PromptAutoformatterResult = {
+  groups: ChainGroupResult[];
+};
+```
+
+The extension's reporter summarizes:
+
+- success: `Autoformatted N files across M batches` (file list when short).
+- failure: per-batch lines naming the formatter, exit code, and the files it touched.
+
+### Interaction with `tool` mode
+
+In `tool` mode the queue is flushed after every successful mutation, so a group is naturally size 1.
+The new executor still runs once, appending the single path — behavior is unchanged from the user's perspective.
+
+## Module-Level Changes
+
+- `src/formatter-registry.ts`
+  - Remove `$FILE` substitution entirely.
+  - Add `groupFilesByChain(files, config)` → `Array<{ chain: string[]; files: string[] }>`.
+    Pure grouping; no formatter resolution.
+  - Add `resolveChain(chainNames, config)` → `ResolvedFormatter[]`.
+    Pure resolution; no file-path involvement.
+    Skips disabled or missing formatters as today.
+  - The legacy per-file `resolveFormatterChainForFile` is removed.
+- `src/formatter-executor.ts`
+  - Replace `executeFormatterChain` with `executeChainGroup({ chain, files }, runner, options)` that runs each step once with appended file paths and returns `{ runs: BatchRun[] }`.
+- `src/prompt-autoformatter.ts`
+  - Drive the new grouping + group-execution path.
+    Return the new `groups`-based result shape.
+- `src/extension.ts`
+  - Update `defaultReportFlushResult` to read the new shape.
+- `src/config-loader.ts`
+  - Reject `$FILE` in any formatter command with a config-issue.
+- `src/formatter-config.ts`
+  - Drop `$FILE` from default formatter commands.
+- `schemas/pi-autoformat.schema.json`
+  - Update the `command` description to document "args + appended file paths."
+  - Add a pattern or `not` constraint that rejects `$FILE` in `command` items.
+- `docs/configuration.md`, `README.md`, `CHANGELOG.md`
+  - Document the new convention, the breaking change, and the per-batch reporting behavior.
+
+## TDD Order
+
+Each step is a small red→green→commit cycle.
+
+1. **Registry: chain resolution.** Tests for `resolveChain(names, config)` covering ordered resolution, disabled-formatter skip, missing-formatter skip, environment passthrough.
+2. **Registry: file grouping.** Tests for `groupFilesByChain(files, config)` covering: mixed extensions → distinct groups; same extension → one group; different extensions sharing a chain → one group; files with no chain dropped; deterministic group and file ordering.
+3. **Executor: batch dispatch.** Tests for `executeChainGroup` covering single-file batch, multi-file batch, multi-step chain (each step runs once with all files appended), step failure does not abort later steps, environment overrides propagate.
+4. **Executor: command shape.** Tests asserting configured args come first and file paths are appended verbatim.
+5. **Config loader: `$FILE` rejection.** Test that a formatter command containing `$FILE` produces a validation issue and the formatter is excluded from the active config.
+6. **PromptAutoformatter: end-to-end.** Tests for the new `groups`-based result shape: mixed-extension touched set produces one group per chain; tool-mode size-1 batch still works; empty touched set yields no groups; existing chain steps run once each.
+7. **Extension: reporting.** Tests for the updated `defaultReportFlushResult` covering success summary across multiple groups and per-batch failure lines.
+8. **Defaults + schema alignment.** Update built-in formatter defaults and schema; acceptance/smoke tests assert defaults contain no `$FILE` and the schema rejects it.
+9. **Docs + changelog.** Update `docs/configuration.md`, `README.md`, and `CHANGELOG.md`.
+
+Commit at each step using Conventional Commits, e.g. `test: cover chain grouping`, `feat: group touched files by chain`, `feat!: batch-dispatch chain steps`, `feat!: drop $FILE substitution`, `docs: document batch dispatch convention`.
+
+## Risks and Mitigations
+
+- **Risk:** A user upgrades and finds their `$FILE`-using config rejected. **Mitigation:** Validation message names the formatter, says exactly what to do, and points at `docs/configuration.md`.
+  CHANGELOG entry flags the breaking change.
+  Major version bump.
+- **Risk:** A formatter that genuinely needs one-file-per-invocation (e.g. a tool requiring `--stdin-filepath`) is now broken. **Mitigation:** Not present in any formatter listed in #14.
+  If a real case appears, add a `batch: false` per-formatter opt-out in a follow-up.
+- **Risk:** A formatter aborts on the first file with an error, silently skipping later files in the batch. **Mitigation:** Documented as a known limitation; per-file output parsing is a follow-up.
+  Exit code is still surfaced and stderr is preserved.
+
+## Open Questions
+
+- Per-formatter `batch: false` escape hatch — defer until a concrete case appears.
+- Whether to fail-loud (skip the formatter) or fail-fatal (refuse to load config) on `$FILE`.
+  Plan goes with fail-loud-skip; revisit if it turns out to be confusing in practice.