notescraft/specs/plugins-parity/synced-blocks/tasks.md

Tasks: synced-blocks (roadmap 36)

Spec: spec.md. Ordered tasks depend on preceding tasks only; each finishes with independently runnable behavior tests.

First tool call rule: after at most three focused reads, write FIRST OWNS file in SECOND tool call: compiling stub plus one failing behavior test, then make it pass. New paths below are explicitly marked new; other paths verified in source on 2026-10-21. Standing VERIFY: export PATH="$HOME/.cargo/bin:$PATH"; cargo test -p <pkg>; cargo clippy -p <pkg> --all-targets -- -D warnings; rustfmt --edition 2024 <owned Rust files>; UI tasks also cargo xtask i18n and inspect snapshot PNG at 1440x900 Mocha/Latte. Final task: cargo xtask ci. These are FUTURE implementation checks; documentation author runs no cargo. Standing DO NOT: edit outside OWNS, mutate Git, add dependencies, blanket lint allows, panic/unchecked input indexing, IO during paint, overwrite malformed user data, bypass atomic vault writes, cargo fmt --all. No new crate planned: no root Cargo.toml or xtask/src/layers.rs edits required. If implementation introduces a crate, stop for scope approval then explicitly own root Cargo.toml and xtask/src/layers.rs registration before compiling.

Phase 1

• 1. Resolve stable block IDs and replace source content (brief briefs/23-synced-block-target.md).

  OWNS: crates/blocks/src/transclusion.rs (new, first write), crates/blocks/src/lib.rs (module, exports and error variants), unit tests in new module

  FILES TO OPEN: spec.md D1, crates/blocks/src/ids.rs, crates/blocks/src/parse.rs, crates/markdown/src/scanning/scan.rs, crates/blocks/src/lib.rs, crates/ui-egui/src/views/note_view/blocks/embed_data.rs

  GOAL: resolve_by_id(source,id) -> Result<BlockTarget> with block/content/marker ranges; replace_by_id(source,id,expected_block,replacement) -> Result<Edited>. Parse real markdown IDs and blocks, preserve ID/structure/CRLF, reject ambiguity and changed target, enforce 1 MiB replacement cap.

  TESTS: Paragraph Unicode/CRLF; list/quote and standalone table ID; ID-like code not target; duplicate/missing ID; unrelated offset shift; stale expected block; marker injection; unsupported structural replacement; over-cap refusal; unrelated bytes unchanged.

  VERIFY: standing, -p notescraft-blocks.

  DO NOT: Do IO, register commands or implement own wikilink path resolver.

Phase 2

• 2. Buffer-first transclusion commands.

  OWNS: crates/engine/src/block_edit/transclusion.rs (new), crates/engine/src/block_edit/mod.rs (module/spec registration), crates/engine/src/ai/assistant_gate.rs, crates/engine/tests/core_commands.rs (CORE_IDS), crates/engine/tests/transclusion.rs (new)

  FILES TO OPEN: spec.md D2, crates/engine/src/block_edit/mod.rs, crates/engine/src/vault/buffers.rs, crates/engine/src/lint/fixes.rs, crates/ui-egui/src/views/note_view/blocks/embed_data.rs

  GOAL: Implement read/replace contracts with shared index resolve, strict path validation, expected-block check at serial commit and source-owned undo through lint_commit. Classify read READ, replacement WRITE.

  TESTS: Two hosts one source; dirty source wins over disk; undo; stale/missing/ambiguous/read-only zero mutation; unrelated edits retained; closed source atomic persistence; host bytes unchanged.

  VERIFY: standing, -p notescraft-engine.

  DO NOT: Copy rendered host ranges into source or bypass session commit.

Phase 3

• 3. Editable embeds and cache invalidation.

  OWNS: crates/ui-egui/src/views/note_view/blocks/synced.rs (new), crates/ui-egui/src/views/note_view/blocks.rs (module), crates/ui-egui/src/views/note_view/blocks/embed.rs, crates/ui-egui/src/views/note_view/blocks/embed_data.rs, crates/ui-egui/src/shell/app/editor/blocks.rs, crates/ui-egui/src/shell/app/editor/blocks_tests.rs, crates/ui-egui/src/text/views/blocks.rs, crates/i18n/locales/en.toml (append synced-block keys)

  FILES TO OPEN: spec.md D3, crates/ui-egui/src/views/note_view/blocks/embed.rs, crates/ui-egui/src/views/note_view/blocks/embed_data.rs, crates/ui-egui/src/shell/app/editor/blocks.rs

  GOAL: Wire edit draft and Apply/Cancel to source command; queue after paint; deduplicate drafts per source; refresh embeds including closed-file watch changes and source undo; bounded cycle/oversize placeholders and conflict draft retention.

  TESTS: UI two embeds reflect edit; one draft per target; cancel; conflict keeps draft; source undo refresh; external closed-source write invalidation; self-cycle; same source in split panes; no IO during paint.

  VERIFY: standing, -p notescraft-ui-egui.

  DO NOT: Change existing note/heading embeds to editable targets without block identity.

Phase 4

• 4. Acceptance and status.

  OWNS: crates/engine/tests/transclusion.rs, ROADMAP.md, docs/ARCHITECTURE.md, docs/CODE-MAP.md, specs/plugins-parity/roadmap.md (rank36)

  FILES TO OPEN: spec.md acceptance criteria and prior tests

  GOAL: Complete source ownership, cycle and conflict regression corpus; document exact supported targets and undo semantics.

  TESTS: Host/source byte preservation with all supported block fixtures and readonly source.

  VERIFY: standing, -p notescraft-engine.

  DO NOT: Add detach/multi-block sync.