outl architecture.instructions.md

Reuse-first violations — no parallel implementations

Duplication here is a real hazard: two implementations of the same logic drift apart over time, and the user is the one who hits the divergence.

Past incidents to anchor severity:

• outl_md::index::Backlink and outl_actions::Backlink were two parallel "backlinks" pipelines that started identical and ended up disagreeing on self-references — caught by the user, not the reviewer. Collapsed into outl_actions::backlinks_for_page in 0.5.3.
• PR #47 (Logseq import) opened with crates/outl-cli/src/cmd/import/normalize.rs reimplementing \r\n handling, id:: stripping, and long-form date rewriting — every one of which outl_actions::paste::normalize_external_syntax already owned. (That directory has since been replaced by the adapter-based crates/outl-import; the lesson carries over.) Caught in review after a Claude-assisted PR shipped without the catalog being visible. That is why the shared primitives catalog exists (see shared-primitives.instructions.md).

The rule the PR author was expected to follow:

1. Grep before writing. rg "fn foo" / rg "struct Foo" across crates/. Look in upstream crates first, in this order: outl-core → outl-md → outl-actions. These are where shared primitives live. The catalog above is your starting point.
2. Prefer evolving the existing API over duplicating, even if that means a small refactor (rename, generalize a parameter, move into a sibling module). One owner per concept; many callers.
3. Refactor into the shared crate, not around it. If a TUI helper feels like it could live in outl-actions, the PR should move it there now — the mobile client will need it soon. The flatten_subtree_paths migration is the canonical pattern.
4. Duplication is OK only when the platforms are genuinely different. outl-tui::EditBuffer and the mobile <textarea> are both "cursor + text", but one is a terminal widget Rust has to render itself and the other is a browser primitive. Same role, different runtime — not duplication. Recalculating (line, col) from cursor in both places, though, would be — extract to outl_md::view::char_to_line_col and wrap.

When you spot a duplicate, point at the existing function with file:line and ask: "can you call this instead, or extend it if it doesn't quite fit? The fix is to wrap or evolve the upstream API, never to write a parallel one. If the author argues for duplication, they have to fit it into case 4 above — same role, genuinely different runtime. Anything else is a blocker.

• Layering violations. UI imports in outl-core. Client crates building op trees instead of calling outl-actions. Workspace mutations done outside Workspace::apply.
• New Op variant without the full checklist. Adding a variant touches apply_op, undo_op (the inverse must be exact), the sidecar serializer, the markdown projection, the replay tests, and the per-crate docs. Check the diff against /new-op expectations and call out anything missing.
• Trait surface that locks out a future backend. Storage must stay implementable by ChronDB later. If a new method assumes file semantics (paths, flock), question it.
• Sidecar / op-log format changes without a migration story. Existing workspaces on disk must still load. Either the change is backward-compatible (new optional field) or there is a versioned migration path described in the PR.
• File size growth past 600 lines. Note it, suggest a split by responsibility, point at refactor-architect agent. Past 900 lines, request a refactor before merge.
• Premature abstraction. A new trait or generic with one impl and no second use case in sight. The Rule of Three applies — concrete first, abstract on the third caller.