[lukasoppermann]

Why

Prototype authors need to retain Pick & polish requests and Copilot answers without turning private improvement work into team review conversations. This is the server foundation of the Pick & polish stack, extracted from #13; local synchronization and the canvas interface follow separately.

What changes

Hub stores each request or agent response in a separate ImprovementComment row, not in ReviewComment. Foreign keys connect replies to their original request, and ImprovementCommentReply links an agent response to the requests it answers. The API returns one current thread shape, assembled from these records rather than stored as a JSON conversation or lists of IDs. Synchronization validates and saves the conversation in one transaction.

Initial uploads require a successful Build. Unpublished notes remain on the author's device until the client verifies that their captured source was published; later changes retain the original Build. The paired API checks repository access, saves only the authenticated creator's notes, and rejects stale or conflicting revisions. Notes remain outside ordinary review interfaces, summaries, unread state, notifications, analytics and learning. Paired comment lists must explicitly request them.

Conversations preserve the original request, follow-ups, answers and immutable owner snapshots without legacy conversions, version negotiation or speculative collection limits. Creator and raw comment feeds return complete collections; existing browser and agent readers use that contract. Compact agent output retains its separate pagination. Deletion clears message text and author snapshots while retaining tombstones. The unshipped relational migration and API guide are updated together; development databases that ran an earlier copy need a fresh database or a deliberate rollback and reapply after preserving needed data. Local synchronization and the canvas interface remain in #41 and #42.

[Copilot]

🟡 Changes recommended

The new persistence API has unresolved correctness and memory-use issues.

5 open issues

• Bound capture payloads across all note-bearing collections · New
• Reject non-string scalar note fields before lookup or save · New
• Require repository write access for note edit and delete flags · New
• Allow underscores in Enterprise Managed User author logins · New
• Allow identical retries of version-2 deletions after owner renames · New

What changed in this PR

Adds Hub persistence for creator-owned Pick & polish notes, preparing for later local synchronization and canvas UI work.

Changes:

• Adds revision-guarded note APIs, versioned threads and permanent deletion tombstones.
• Separates improvement notes from ordinary reviews and learning.
• Adds migrations, regression coverage and API documentation.

File	Description
hub/​test/​models/​review_comment_note_thread_test.rb	Tests thread validation, immutable history and deletion.
hub/​test/​models/​learning/​run_test.rb	Tests exclusion from learning scheduling.
hub/​test/​integration/​canvas_repository_comments_test.rb	Covers synchronization, visibility and request limits.
hub/​test/​integration/​canvas_improvement_note_threads_test.rb	Covers thread revisions, compatibility and ownership.
hub/​docs/​review-collaboration.md	Explains separation from review conversations.
hub/​docs/​prototype-canvas.md	Documents note persistence contracts.
hub/​db/​schema.rb	Records note fields, indexes and constraints.
hub/​db/​migrate/​20261019140000_add_note_thread_to_review_comments.rb	Adds constrained thread storage.
hub/​db/​migrate/​20261013080000_add_improvement_notes_to_review_comments.rb	Adds note identity and persistence fields.
hub/​config/​routes.rb	Adds note read and save routes.
hub/​app/​models/​review_comment/​note_thread_contract.rb	Validates thread formats, snapshots and history.
hub/​app/​models/​review_comment.rb	Adds note validation, scopes and lifecycle handling.
hub/​app/​models/​prototype.rb	Separates review and note associations.
hub/​app/​models/​learning/​run.rb	Excludes notes from learning eligibility.
hub/​app/​models/​learning/​overview.rb	Excludes notes from learning evidence.
hub/​app/​models/​learning/​collection.rb	Excludes notes from learning imports.
hub/​app/​controllers/​concerns/​review_comment_pages.rb	Adds note filtering and serialization.
hub/​app/​controllers/​concerns/​review_comment_actions.rb	Rejects threads through ordinary comment writes.
hub/​app/​controllers/​concerns/​has_review_comment_context.rb	Shares filtering, payload guards and request limits.
hub/​app/​controllers/​canvas_api/​repository_review_comments_controller.rb	Supports explicit note inclusion.
hub/​app/​controllers/​canvas_api/​prototypes_controller.rb	Exposes the authenticated viewer ID.
hub/​app/​controllers/​canvas_api/​improvement_notes_controller.rb	Implements creator-scoped reads and guarded saves.

_{Review effort: Max}