notescraft/specs/plugins-parity/citations/tasks.md

Tasks: Zotero/BibTeX citations (roadmap 39)

Spec: spec.md. One task = one agent. No new crate; no Cargo/layer registration. New dependencies require owner response to Q2. First tool call rule: first call batches required reads; write first OWNS file in SECOND tool call, compiling stub plus one failing test, then make it pass. First OWNS is always a source file, not a directory. Module wiring listed explicitly below. Standing VERIFY: export PATH="$HOME/.cargo/bin:$PATH"; cargo test -p <owned package>; cargo clippy -p <owned package> --all-targets -- -D warnings; rustfmt --edition 2024 <owned Rust files>; UI adds cargo xtask i18n; final phase cargo xtask layers and cargo xtask tree. These are future implementation checks; specification author does not run Cargo. Standing DO NOT: edit outside OWNS; git mutations; dependencies/Cargo changes; shared craft API changes; panics, unchecked input slices, blanket allows; per-frame IO; cargo fmt --all; rewrite bibliography exports.

Phase 1 — pure input model

• 1. CSL JSON normalization and limits. OWNS: crates/engine/src/citations/model.rs (new, FIRST), crates/engine/src/citations/mod.rs (new), one mod citations; declaration in crates/engine/src/lib.rs, narrowly scoped error variant in crates/engine/src/error.rs if existing error cannot express invalid bibliography. FILES TO OPEN: spec.md D1, crates/engine/src/lib.rs, crates/engine/src/error.rs, crates/engine/src/activity/outbox.rs (versioned structured data pattern). GOAL: pure Entry, Creator, Library, parse_csl_json(&str) -> Result<Library>, validate_key(&str) -> Result<()>; bounded deterministic normalization, preserve literal names/date precision; no source writes. TESTS: two items, Unicode, institutional author, partial date, absent optional fields; invalid JSON, duplicates, invalid/oversize key, 20,001 items, nesting/field/author caps; invalid inputs return Err. VERIFY: standing -p notescraft-engine with citations filter, confirm tests run through module declaration. DO NOT: IO, commands, BibTeX parser, CSL formatting or dependencies.
• 2. Explicit BibTeX subset adapter. OWNS: crates/engine/src/citations/bibtex.rs (new, FIRST), crates/engine/src/citations/mod.rs (module declaration), fixtures/tests inside bibtex.rs. FILES TO OPEN: D1 and task 1 model, crates/engine/src/error.rs. GOAL: parse_bibtex(&str) -> Result<Library> maps supported records, balanced nested values and creators, reports unsupported constructs with location. Keep bounded parser under 400 lines/file; no TeX execution. TESTS: article/book/misc/inproceedings, nested braces, escaped quotes, % comments, and authors, institutional braces, Unicode; duplicate, malformed/unclosed entry, macros/concatenation/crossref/unsupported TeX, depth/byte caps; equivalent CSL fixture normalization. VERIFY: standing -p notescraft-engine, filter citations. DO NOT: silently discard unsupported semantics, download parser or claim complete BibLaTeX support. If Q2 requires a new parser, stop dependency work until approved.

Phase 2 — engine surface

• 3. Refresh/search/resolve/insert with guarded sources. OWNS: crates/engine/src/citations/commands.rs (new, FIRST), crates/engine/src/citations/source.rs (new), crates/engine/src/citations/mod.rs, crates/engine/src/vault/session.rs (bounded cache field and constructor initialization), crates/engine/src/commands.rs (one register call), crates/engine/src/ai/assistant_gate.rs, crates/engine/tests/core_commands.rs, crates/engine/tests/citations.rs (new). FILES TO OPEN: D2, crates/engine/src/capture/mod.rs, crates/engine/src/vault/buffers.rs, crates/engine/tests/common/mod.rs, crates/markdown/src/frontmatter/mod.rs. GOAL: D2 command table, bounded cache and atomic snapshot replacement, note-relative guarded bibliography path, stable search, compare-before-edit insertion into open buffer. TESTS: TempVault sources in two folders, relative path resolution, read-only reads/insert refusal, stale buffer/invalid UTF-8 offset, undo, duplicate source refresh keeps previous snapshot, recovery after failed refresh, traversal/reserved/absolute/URL source rejection; command ids/gate classification; ignored warm-search fixture. VERIFY: standing -p notescraft-engine, --test citations --test core_commands. DO NOT: read Zotero SQLite, write source, perform network calls, save unrelated dirty edits.

Phase 3 — export and native UI

• 4. Explicit citation-enabled Pandoc export (Q1 backend decision first). OWNS: crates/engine/src/pandoc/run.rs (FIRST), crates/engine/src/pandoc/commands.rs, crates/engine/src/pandoc/mod.rs, crates/engine/tests/pandoc.rs. FILES TO OPEN: D4, current Pandoc request/reader/timeout and engine source guard from task 3. GOAL: opt-in citations:true, citation-capable reader, --citeproc, guarded controlled bibliography/style snapshots; default export behavior stays intact. No shell, remote references or arbitrary metadata paths. TESTS: stub executable captures argv/input; citation mode vs default; missing executable, bad style, source path traversal, timeout, malformed source, failed run never creates final output; optional ignored real-Pandoc bibliography assertion. VERIFY: standing -p notescraft-engine, --test pandoc --test citations. DO NOT: bundle/install Pandoc, add CSL dependency, call this native CSL rendering, enable unvalidated remote resource fetches.
• 5. Citation picker, inline metadata and release checks. OWNS: crates/ui-egui/src/views/citation_picker/mod.rs (new, FIRST), crates/ui-egui/src/views/mod.rs, crates/ui-egui/src/views/note_view/inlines/scan.rs, crates/ui-egui/src/views/note_view/inlines.rs, crates/ui-egui/src/views/note_view/inlines/scan_tests.rs, crates/ui-egui/src/views/note_view/painting.rs (citation span/tooltip arm only), crates/ui-egui/src/shell/app/window/commands.rs, crates/ui-egui/src/shell/app/window/views.rs, crates/ui-egui/src/text/views/citations.rs (new), crates/ui-egui/src/text/views/mod.rs, [ui.citations] at END of crates/i18n/locales/en.toml, crates/ui-egui/tests/citations.rs (new), ROADMAP.md, docs/ARCHITECTURE.md, docs/CODE-MAP.md, rank 39 status in specs/plugins-parity/roadmap.md. FILES TO OPEN: D3, crates/ui-egui/src/views/note_view.rs, existing inline scanner/tests, crates/ui-egui/src/widgets/palette.rs, crates/ui-egui/src/shell/hotkeys/defaults.rs, crates/ui-egui/src/views/share_dialog/mod.rs worker pattern. GOAL: keyboard-search picker and insert through engine, one source snapshot per note/version, known/missing/grouped citation display and refresh diagnostics. Wire actual handlers in owned shell files; no unowned “lead wiring” remains. Update documentation only after actual checks. TESTS: kittest search and select inserts once, cancel no write, undo, missing key and malformed refresh, no code/comment/email recognition, unsupported locators literal, no per-span engine calls. VERIFY: standing engine/UI; i18n, Mocha/Latte snapshot PNGs read, cargo xtask ci. Record optional real-Pandoc check skipped if unavailable. DO NOT: invent shortcut conflicts, style key text as a real CSL bibliography, silently alter note source.