docs: refresh local agent guidance (#71)

Author: benvinegar

AGENTS.md

@@ -24,6 +24,9 @@ CLI input
 - `hunk mcp serve` runs one loopback daemon that brokers agent commands to many live Hunk sessions. Normal Hunk sessions should auto-start and register with that daemon when MCP is enabled. Keep it local-only and session-brokered rather than opening per-TUI ports.
 - Agent rationale is optional sidecar JSON matched onto files/hunks.
 - The order of `files` in the sidecar is intentional. Hunk uses that order for the sidebar and main review stream.
+- Prefer one source of truth for each user-visible behavior. When rendering, navigation, scrolling, or note placement share the same model, derive them from the same planning layer rather than maintaining parallel implementations.
+- When UI behavior depends on derived structure or metrics, make that structure explicit in helper modules and reuse it across rendering and interaction code instead of re-deriving it ad hoc in multiple places.
+- If a new implementation makes an older path obsolete, remove the dead path instead of keeping two overlapping systems around.
 
 ## architectural rules
 
@@ -40,6 +43,8 @@ CLI input
 - Pane rendering should live in dedicated components.
 - New UI work should extend existing components or add new ones, not grow `App` back into a monolith.
 - Shared formatting, ids, and small derivations belong in helper modules, not repeated inline.
+- Prefer one implementation path per feature instead of separate "old" and "new" codepaths that duplicate behavior.
+- When refactoring logic that spans helpers and UI components, add tests at the level where the user-visible behavior actually lives, not only at the lowest helper layer.
 
 ## review behavior
 
@@ -50,7 +55,8 @@ CLI input
 - `[` and `]` navigate hunks across the full review stream. Do not reintroduce `j`/`k` hunk navigation unless the user asks.
 - Agent context belongs beside the code, not hidden in a separate mode or workflow.
 - Agent notes are hunk-specific: show notes for the selected hunk, render them in the diff flow near the annotated row, and keep a clear spatial relationship to the code they explain.
-- If you choose to use a local sidecar such as `.hunk/latest.json`, keep it concise and review-oriented: one changeset summary, file summaries in narrative order, and a few hunk-level annotations with real rationale.
+- Keep note behavior explicit. If the UI intentionally prioritizes one note, one selection, or one active target, encode that as a named policy rather than scattering array-index assumptions through the codebase.
+- If you choose to use a local sidecar for temporary review context, keep it concise and review-oriented: one changeset summary, file summaries in narrative order, and a few hunk-level annotations with real rationale.
 - If a local sidecar is present, its file order is intentional, but the visible note UI should stay hunk-note driven rather than showing generic file or changeset explainer cards.
 - If newly created files should appear in `hunk diff` before commit, use `git add -N <paths>` so they show up in the review stream without staging content.
 
@@ -75,11 +81,12 @@ CLI input
 ## verification
 
 - For rendering changes: run `bun run typecheck`, `bun test`, `bun run test:tty-smoke`, and do one real TTY smoke run on an actual diff.
+- For interaction, layout, scrolling, navigation, or windowing changes: also add or update integration tests that exercise the user-visible behavior at the pane/app level.
 - For CLI, config, or pager work: make sure the relevant source invocation still works (`diff`, `show`, `patch`, or `pager`).
 - Preserve current interaction model unless the user asks to change it explicitly.
 
 ## repo notes
 
-- `.hunk/latest.json` is ignored on purpose. Use it only if you want temporary local review context, and do not commit it.
+- Local review artifacts are ignored on purpose. Leave them alone unless the user explicitly wants them updated, and do not commit them.
 - Do not auto-commit after making changes. Leave edits uncommitted so the user can review them in `hunk`, and only commit when the user explicitly asks.
 - Keep this doc short and architectural. Fresh-context agents can discover file paths themselves.