9993a66fee
notescraft-bases (L2, no I/O): hand-written lossless YAML subset parser and emitter with limits (1 MiB, depth 12, 10000 nodes), value and date types with durations, month clamp and a total order across types (Bases tasks 1 and 4). Built by MiniMax M3.1 Flash (OpenCode Zen free route). Verified as part of the full cargo xtask ci run on the combined tree. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
13 KiB
13 KiB
Tasks: comments, suggestions, mentions, activity feed
One task = one agent's work. Each task names the files it owns, the files it must read and the
tests that prove it. [ ] open, phases run in order. Tasks 1 to 3 are ready for MiniMax M3.1
Flash (pure Rust, no I/O, no UI). The briefs live in scripts/mm/ once the owner writes them.
Tasks 1 to 6 and 8 are in notescraft-engine; task 7 is in notescraft-sync-server.
crates/engine/src/ already holds 12 loose .rs files, so every new module goes into the new
folder crates/engine/src/review/ (declared with one line in crates/engine/src/lib.rs). The
server side uses the new folder apps/notescraft-sync-server/src/activity/. No new crate, no new
dependency, no change to the root Cargo.toml.
Owner decisions (before phase 2)
- Comments in the sidecar file (spec D1) or inside the Markdown? The spec recommends the sidecar.
- The feed in a dedicated server table or derived from the audit log? The spec recommends a dedicated table with one row per (member, event).
- A mention of somebody who is not a member: refused or plain text? The spec recommends plain text.
Phase 1 - the pure model (no I/O)
- 1. The comment model and the sidecar codec.
OWNS:
crates/engine/src/review/mod.rs,crates/engine/src/review/model.rs,crates/engine/src/review/sidecar.rs, one line incrates/engine/src/lib.rs, the error variants incrates/engine/src/error.rs. READ FIRST:specs/comments-and-mentions/spec.md(D1, D2),crates/engine/src/error.rs,crates/engine/src/id.rs(the id rules),crates/engine/src/live/config.rs:54(the random bytes and the hex form the thread ids use),crates/engine/src/share/client.rs:82(theMembershape). Public API:Comment { id, author, created_ms, updated_ms, body, anchor: Anchor, thread: Vec<Reply>, resolved, resolved_by, mentions },Anchor { quote, context_before, context_after, start, end },Sidecar { version, note, comments },sidecar_path(note) -> String,parse_sidecar(bytes, note) -> Result<Sidecar>,sidecar_to_json(&Sidecar) -> Result<Vec<u8>>. Done when:cargo test -p notescraft-engine review::runs and passes; a sidecar round trips through JSON; a body over 4 KiB, a quote over 200 characters, 201 replies, 501 threads and a file over 1 MiB are refused with an error (never truncated); an unknownversionis refused;cargo clippy -p notescraft-engine --all-targets -- -D warningsis clean. - 2. The anchor resolution (drift).
OWNS:
crates/engine/src/review/anchor.rs. READ FIRST:crates/engine/src/review/model.rs,specs/comments-and-mentions/spec.md(D3),crates/markdown/src/lib.rs(how the ranges of a document are given). Public API:enum AnchorState { Exact, Reanchored, Fuzzy, Orphaned },resolve(anchor: &Anchor, text: &str) -> Resolvedwith the resolved range and the state. Done when: the unit tests show an unchanged range isExact; a quote that moved isReanchored; a quote with other spacing or case isReanchored; a reworded quote isFuzzy; a deleted quote isOrphaned; a quote that appears twice picks the occurrence nearest the old range; an empty quote is refused; the fuzzy ratio needs no new dependency. - 3. The CriticMarkup marks of the suggestion layer.
OWNS:
crates/engine/src/review/suggestion.rs. READ FIRST:specs/comments-and-mentions/spec.md(D4),crates/markdown/src/lib.rs:242(replace_range). Public API:enum SuggestionKind { Added, Removed, Substituted },scan(text: &str) -> Vec<Suggestion>(kind, byte range of the whole span, the text),accept(text: &str, span: Range<usize>) -> Result<String>,reject(text: &str, span: Range<usize>) -> Result<String>. Done when: the tests show the three rows of the table in D4 (accept and reject of{++…++},{--…--},{~~…~>…~~}); a range that holds no span is an error (stale_range); a mark inside a fenced code block is not a suggestion; two marks of the same kind do not nest; the text of a note without marks is returned unchanged.
Phase 2 - the commands
- 4. The comment commands and the sidecar on disk.
OWNS:
crates/engine/src/review/store.rs,crates/engine/src/review/commands.rs,crates/engine/src/commands.rs(the registration call, next tocrate::share::commands::register_share(reg)),crates/engine/src/ai/assistant_gate.rs(the id lists),crates/engine/src/lib.rs. READ FIRST:crates/engine/src/spec.rs,crates/engine/src/params.rs:88,crates/engine/src/commands.rs:156(the write gate),crates/engine/src/share/commands.rs(a command group to copy),crates/engine/src/vault/buffers.rs(the buffer API). Done when:comment.list,comment.add,comment.reply,comment.edit,comment.delete,comment.resolveandcomment.reanchorare registered and behave as the table in D8;comment.addwrites the sidecar throughVault::writeand leaves the note file byte-identical; the write commands are disabled in a read-only session; the new ids are in the right list ofcrates/engine/src/ai/assistant_gate.rs; the command tests drive the registry, not the internals. - 5. The suggestion commands and the role check.
OWNS:
crates/engine/src/review/commands.rs,crates/engine/src/review/role.rs,crates/engine/src/ai/assistant_gate.rs. READ FIRST:crates/engine/src/review/suggestion.rs,crates/engine/src/share/client.rs:244(the members list and the roles),crates/engine/src/vault/buffers.rs:92(Buffer::edit). Done when:suggestion.list,suggestion.acceptandsuggestion.rejectexist; accepting writes the new text through the ordinary buffer path (the live room sees it); a viewer is refused withforbiddenand an editor is not; a stale range answersstale_rangeand the note stays unchanged; a note without pending suggestions saves byte-identical to the same note edited without suggestions. - 6. The sidecar under rename and under conflict.
OWNS:
crates/engine/src/review/store.rs,crates/engine/src/review/merge.rs. READ FIRST:crates/sync/src/conflict.rs:12,crates/sync/src/merge.rs:30,crates/engine/src/sync/conflicts.rs(how the engine resolves a conflict today). Done when: renaming a note renames its sidecar; the merge of two sidecars unions the threads by id and never drops one; a sync conflict on a sidecar is merged instead of leaving two half-files; the tests cover two devices that commented while offline.
Phase 3 - the server and the feed
- 7. The activity table and the endpoints.
OWNS:
apps/notescraft-sync-server/src/activity/mod.rs,apps/notescraft-sync-server/src/activity/store.rs,apps/notescraft-sync-server/src/activity/routes.rs, the schema and the route registration inapps/notescraft-sync-server/src/store/mod.rsandapps/notescraft-sync-server/src/api/routes.rs. READ FIRST:apps/notescraft-sync-server/src/api/members.rs(a group to copy),apps/notescraft-sync-server/src/store/audit.rs,apps/notescraft-sync-server/src/roles.rs,apps/notescraft-sync-server/src/limits.rs. Done when:POST /v1/vaults/{v}/activitystores an event for the members it names (the actor must be the token's user, the mentions must be members, the note must exist in the vault);GET /v1/vaults/{v}/activity?since=&limit=answers the events of the caller and their unread count;POST /v1/vaults/{v}/activity/readmarks them read; a viewer token and a removed member get 403; the HTTP tests speak real HTTP against the test server; the server never writes a comment body to the log. - 8. The activity client, the commands and the outbox.
OWNS:
crates/engine/src/activity/mod.rs,crates/engine/src/activity/client.rs,crates/engine/src/activity/commands.rs,crates/engine/src/commands.rs(the registration call),crates/engine/src/lib.rs. READ FIRST:crates/engine/src/share/client.rs(the HTTP client to copy),crates/engine/src/sync/worker.rs:175(the poll loop),crates/engine/src/vault/buffers.rs(the private writes). Done when:activity.list,activity.unread,activity.readandmention.candidatesare registered; a comment that mentions a member posts the event when the server is reachable and keeps it in.notescraft/activity-outbox.jsonwhen it is not, and posts it with the next sync; the unread cursor is kept in.notescraft/activity.json; a vault without a server answersnot_boundinstead of failing.
Phase 4 - the UI
- 9. The comment panel and the margin gutter.
OWNS:
crates/ui-egui/src/panels/right/comment_panel.rs, the tab incrates/ui-egui/src/panels/right_view.rs, the gutter incrates/ui-egui/src/views/note_view/,crates/ui-egui/src/text/panels/review/mod.rsandcrates/ui-egui/src/text/panels/review/comment_panel.rs(the foldertext/andtext/panels/are full at 12 loose files, so the new tables go into a new folder), the tables incrates/i18n/locales/en.toml(new[ui.comment-panel]at the end of the[ui.*]tables). READ FIRST:crates/ui-egui/src/panels/right/backlinks_panel.rs(the shape of a right panel),crates/ui-egui/src/panels/right_view.rs:103(RightTab),crates/ui-egui/src/design/style/(the touch targets),.claude/skills/notescraft-egui-screen/SKILL.md. Done when: the panel lists the threads of the open note in document order with the filters All, Open, Resolved and Orphaned; a selection opens the composer and the new thread appears; a reply, a resolve and a re-anchor work; the gutter shows one marker per thread on the line of the anchor; the driven test incrates/ui-egui/tests/paints the panel and finds the thread text;cargo xtask i18nreports no hardcoded string. - 10. The suggestions in the Visual view and the review list.
OWNS:
crates/ui-egui/src/views/note_view/(the painting of the marks),crates/ui-egui/src/panels/right/suggestion_panel.rs,crates/ui-egui/src/text/panels/review/suggestion_panel.rs, the tables incrates/i18n/locales/en.toml. READ FIRST:crates/ui-egui/src/views/note_view/painting.rs, the task 3 API,crates/ui-egui/src/design/(the theme tokens). Done when: an addition is underlined and a deletion struck through in the Visual view; the Source view shows the raw marks; the review list offers accept, reject and accept all; a viewer sees the list without the buttons; the driven test finds the rendered marks. - 11. The activity feed, the badge and the phone pages.
OWNS:
crates/ui-egui/src/panels/right/activity_panel.rs,crates/ui-egui/src/panels/right_view.rs,crates/ui-egui/src/shell/compact/(the phone pages),crates/ui-egui/src/text/panels/review/activity_panel.rs, the tables incrates/i18n/locales/en.toml. READ FIRST:crates/ui-egui/src/panels/sync_sheet/(the phone sheet), the task 8 API,crates/ui-egui/src/shell/compact/mod.rs:29(CompactPage). Done when: the feed lists the events newest first with the unread ones marked; the tab shows the unread count; a click opens the note and the line; on the phone the feed and the comment panel are pages of the compact shell with 44 pt targets.
Phase 5 - the edges
- 12. The sidecars stay out of the way.
OWNS: the file tree in
crates/ui-egui/src/panels/tree.rs, the search index incrates/index/src/, the published listings inapps/notescraft-sync-server/src/publish/pages.rs:154(it keeps only the.mdfiles today). Done when: a*.comments.jsonfile never appears in the explorer, in the search results or in a published site; renaming a note keeps the sidecar with it; deleting a note removes the sidecar with it. - 13. The feed over Server-Sent Events (the optimisation of D7).
OWNS:
apps/notescraft-sync-server/src/activity/routes.rs,crates/engine/src/activity/client.rs,crates/engine/src/live/sse.rs(the parser is reusable). Done when:GET /v1/vaults/{vault}/activity/eventsstreams the events of the vault; the client updates the feed while it is open; the poll of task 8 stays the fallback and the two never deliver the same event twice. - 14. The end-to-end proof.
OWNS:
crates/engine/tests/comments_e2e.rs(or the folder of the crate). Done when: two clients on a stub server: Ana comments on a sentence of a note and mentions Bob; Bob's feed shows the mention and the comment; Ana's feed does not show her own comment; Bob resolves the thread and Ana gets thethread_resolvedevent; a second run of the sync changes nothing.