[backnotprop]

What this does

Plannotator hands submitted feedback to the invoking agent and then forgets it. This adds a durable local archive of every review a user submits, on every surface, in both server runtimes.

The gaps this closes:

• Code review persisted nothing. POST /api/feedback deleted the draft, settled the decision promise, and wrote no record. If the invoking agent had already timed out, the review existed nowhere. That is exactly the failure Annotate feedback can be lost when submit auto-closes localhost session after CLI timeout on Windows/Codex #678 fixed for annotate.
• Plan decisions depended on a user setting. plans/ snapshots are written only while the client-sent planSave setting is on, and they are keyed by slug plus status, so approve then deny then approve on one plan keeps one file per status instead of a timeline.
• Annotate only covered single local files. URL, folder, live-app and annotate-last submissions wrote nothing.

Storage

${PLANNOTATOR_DATA_DIR}/feedback/{project}/
  index.jsonl                                            # append-only, authoritative, schema v1
  records/2026-08-31T14-22-07-511Z-review-feedback.md    # human-readable sidecar

The JSONL line is self-contained so an analyzer never has to open a sidecar (jq over index.jsonl); the markdown sidecar exists because the rest of the data dir is greppable markdown, and it is written only for records that carry content. Bare approvals, LGTMs and dismissals are decision-only lines.

Sample record (code review):

{"v":1,"ts":"2026-08-31T14:22:07.511Z","client":"plannotator","project":"plannotator","origin":"claude-code","surface":"review","decision":"feedback","target":{"review":{"diffType":"since-base","base":"origin/main","gitRef":"HEAD","snapshotId":"a1b2c3:since-base","cwd":"/abs/repo","vcsType":"git","changedFiles":14,"patchBytes":48211}},"feedback":"## Review\n\nparse() still drops the null case.","annotations":[{"id":"a1","type":"comment","text":"null case","originalText":"parse(input)","file":"src/parse.ts","lineStart":12,"lineEnd":12,"side":"new","author":"ramos"}],"counts":{"annotations":1,"external":0,"images":0},"recordFile":"records/2026-08-31T14-22-07-511Z-review-feedback.md"}

Records are cheap by design:

• Code review carries diff identity (vcsType, diffType, base, gitRef, snapshotId, cwd, PR metadata, changed-file count, patch byte count) and never the patch bytes. Guide history already showed what uncapped patch copies cost on disk.
• Plan records carry the decision text plus a reference to the exact history/{project}/{slug}/NNN.md version the decision was made on, so an analyzer joins the record to the plan content already on disk instead of storing a second copy.
• Annotation provenance (source, author) is preserved. External, review-agent and WebMCP annotations are included, because the submitted feedback text already embeds them, but they stay tagged, so source == null selects the reviewer's own comments. Agent job outputs (guides, tours) are not archived.

Where it is wired

One shared module, packages/shared/feedback-archive.ts, vendored to Pi through vendor.sh. It resolves the data dir per call (not at module load) so tests can redirect PLANNOTATOR_DATA_DIR inside the test body under Bun's one-process rule, and it never throws: a failure is logged, degrades silently for the user, and keeps the annotation draft as the recovery copy. The append happens before deleteDraft, generalizing the #678 ordering.

Surface	Bun	Pi
Plan approve / deny	packages/server/index.ts	serverPlan.ts
Review feedback / approve / LGTM / close	packages/server/review.ts	serverReview.ts
Annotate submit / approve / close	packages/server/annotate.ts	serverAnnotate.ts

Controls

• PLANNOTATOR_FEEDBACK_HISTORY env plus feedbackHistory config key, resolver beside resolveAnnotateHistory, default on.
• PLANNOTATOR_ANNOTATE_HISTORY=0 continues to suppress all annotate-surface writes including the new records, so the documented fully-stateless annotate session stays literally true.
• "feedback" is added to PURGE_OWNED_TOP_LEVEL, so uninstall purge removes it and dry-run does not report it as an unrecognized leftover.
• No retention or pruning, matching plans/, history/ and guides/. The privacy note (feedback text and quoted excerpts land on disk, kept indefinitely) is documented in the env table.

Behavior change worth release-noting

With defaults, URL, annotate-last, live-app and folder annotate submissions leave a durable record for the first time, and code review leaves one at all for the first time. Legacy stores are untouched: plans/ snapshots and the #678 history/.../submissions/ records behave exactly as before.

Deferred follow-ups (named, not in this PR)

1. Structured plan annotations. The plan client submits only rendered feedback text, so plan records are text plus the version-file reference. Capturing per-annotation structure needs a client payload addition that touches the UI and both built HTMLs; it is additive and can land later without changing the record schema.
2. POST /api/pr-action records (platform review submissions), an additive sixth severable increment from the design.
3. Read-path increments: a plannotator feedback list CLI reader, Archive-tab integration, image attachment copying, and opt-in full-patch retention.

Tests

New: packages/shared/feedback-archive.test.ts (record shape, append durability, sidecar collisions, torn-line tolerance, never-throws, project bucketing), packages/server/feedback-archive.test.ts (all three Bun surfaces end to end over HTTP), apps/pi-extension/server/feedback-archive.test.ts (Pi parity). packages/server/uninstall.test.ts gains the purge fixture. Each test names the regression it guards; all writes are sandboxed under a temp PLANNOTATOR_DATA_DIR set inside the test body.

No UI changes, no new endpoints, no client changes, no build-order implications.

AI-assisted (Claude) under maintainer direction.