docs(agent-feedback): migrate to one item per file

AGENTS.md

@@ -4,4 +4,4 @@ A Prettier plugin for parsing and printing Marko files.
 
 ## Agent feedback
 
-Anything actionable but out of scope for the current task — a suspected bug, cleanup, a perf/size win, tooling friction, or code that was confusing — must be recorded in [`agent-feedback/`](agent-feedback/README.md) before finishing. Don't silently drop it, and don't fix it inside an unrelated diff.
+Anything actionable but out of scope for the current task (suspected bug, cleanup, perf or size win, tooling friction, confusing code) must be filed in [`agent-feedback/`](agent-feedback/README.md) before finishing. Never drop it silently. Never fix it inside an unrelated diff.

agent-feedback/README.md

@@ -1,39 +1,66 @@
 # Agent Feedback
 
-Actionable observations that were **out of scope for the task that surfaced them**. If something is in scope, fix it instead. Do not expand a task's diff to fix issues recorded here.
+Actionable observations that were out of scope for the task that surfaced them. In scope: fix it. Out of scope: file it here. Never expand a task's diff to fix an item recorded here.
 
-## When to add an entry
+One item per file in `items/`, named `YYYY-MM-DD-<slug>.md`.
 
-While working on any task, record anything a future contributor should act on:
+## When to file
 
-- a suspected bug you couldn't pursue → `bugs.md`
-- duplication, dead code, inconsistency, refactor opportunities → `cleanup.md`
-- runtime speed or bundle size opportunities → `perf.md`
-- friction in builds, tests, tooling, or repo workflows → `dx.md`
-- code or docs that were confusing, and what would have clarified them → `unclear.md`
+Anything a future contributor should act on:
 
-## Rules
+- `bug`: a suspected defect left unpursued
+- `cleanup`: duplication, dead code, inconsistency, refactor opportunity
+- `perf`: speed, memory, payload or bundle size, build time
+- `dx`: friction in builds, tests, tooling, or repo workflows
+- `unclear`: code or docs that were confusing, and what would have clarified them
 
-1. **Search the category file first.** If an entry already covers it, don't duplicate; append a corroborating sentence only if you have new information.
-2. **Be self-contained.** Include enough detail (paths, symbols, reasoning) that someone can act without re-discovering your analysis. Never reference "my earlier analysis" or conversation context.
-3. **Cite by stable symbol, not line number.** Line numbers rot with the next edit; anchor the primary citation to the nearest enclosing stable symbol (exported function, class, variable, or a heading for docs). A line number may appear in the body as a secondary hint.
-4. **Append to the end** of the category file.
-5. Entries are **removed when resolved** (delete, don't mark done; git history is the archive).
-6. **Verify before recording.** A guess is not feedback.
+## Rules
 
-## Resolving a "won't fix" item
+1. **Verify first.** A guess is not feedback. Every item ends with a check that reproduces the claim.
+2. **Dedupe first.** `grep -ril '<path or symbol>' agent-feedback/items`. If a file covers it, edit that file only when you add new information.
+3. **Check the code site.** An intent comment there means the behavior is deliberate. Do not file it.
+4. **Self-contained.** Paths, symbols, reasoning. Never reference conversation context or "earlier analysis".
+5. **Cite by stable symbol**, never line number.
+6. **State the defect and the check.** Never describe what works. Never narrate a landed fix.
+7. **Direction is preventive for `unclear` and `dx`.** Name what would have stopped the trip: a comment, a doc line, a lint rule, a compile error, a debug-only warning. The goal is that the next agent does not hit it.
+8. **Resolve by deleting the file in the same PR as the fix.** A partial fix rewrites the file to what remains.
+9. **Won't-fix is a maintainer's call, never an agent's.** Add a comment (two lines max) at the code site stating the behavior and why it is deliberate, then delete the file. The comment is what stops re-filing. Never consult git history to learn whether something was resolved; if it is not in `items/` and not commented at the site, it is unresolved.
 
-When a maintainer has explicitly deemed an item "won't fix" / "not worth it", resolve it by adding a brief inline comment at the code site that captures the decision (so it is not re-filed), then remove the entry. Only on such an explicit call — never on your own initiative.
+## Item format
 
-## Entry format
+`items/YYYY-MM-DD-<slug>.md`:
 
 ```md
-## <one-line imperative summary>
+---
+type: bug | cleanup | perf | dx | unclear
+impact: high | med | low
+effort: high | med | low
+site: <path/to/file.ts> › <nearestStableSymbol>
+---
 
-`<primary/file/path.ts>` › `<nearestStableSymbol>` | 2026-07-02 | impact:<low|med|high> | effort:<low|med|high>
+# <one-line imperative title>
 
-<2–6 sentences: the problem, why it matters, and a concrete suggested direction,
-ending with the check that re-verifies the claim (a command, input, or
-observation). Cut evidence beyond what a fixer needs to act; further detail is
-re-derived from the citation. Additional file paths inline as needed.>
+<2-6 sentences: the problem, why it matters, a concrete direction. Cut evidence a fixer can re-derive from the site.>
+
+Check: <command, input, or observation that reproduces the claim>
 ```
+
+`impact`: what breaks or is lost if ignored. `effort`: expected size of the fix. Both are the filer's estimate; triage re-judges.
+
+## Repo notes
+
+Single package, pnpm, vitest. Prints Marko files through prettier; parsing is delegated to `htmljs-parser`.
+
+**Reproduce a claim.** Format a snippet through the plugin:
+
+```sh
+pnpm exec prettier --plugin ./src/index.ts --parser marko <file.marko>
+```
+
+For a defect in the printed output, the smallest reproduction is the input template plus the expected output.
+
+**Guard tests.** `vitest run`. Fixtures live under `src/__tests__/`; snapshots are updated with `pnpm test:update`. Prefer adding a case to an existing fixture suite over a new file. Idempotence matters: formatting the output again must be a no-op, so assert that too when a change touches printing.
+
+**Pre-ship.** `pnpm run build` (tsc + rolldown), `pnpm run @ci:lint` (eslint + prettier check), `pnpm test`. Add a changeset with `pnpm run change`.
+
+**Gotchas.** Behavior is coupled to the installed `htmljs-parser` version; a parse-level defect is usually filed there, not here. Prettier's own AST invariants (comments must attach, every node must print) surface as runtime throws rather than wrong output.