refactor(cli): centralize annotation state and preserve diagnostic order

[johnny4young]

Finding

Annotation parsing carried twenty-two loose fields, while the compatibility pass and option construction repeated the same position/style and geometry decisions. This made per-kind final-style application and error precedence depend on several separate mappings.

Refactor

• Introduce one invocation-local CLIAnnotationArguments value for callout/counter position/style and the five geometric groups.
• Keep token consumption and syntax validators in CLIArgumentParser.
• Centralize modifier compatibility at the same point in the broader semantic pass, preserving the exact kind order and diagnostics.
• Share geometry-to-option projection so each group's final style travels with its own ordered points.
• Keep the existing CLIOptions result, flags, defaults, recipes, entitlement boundaries and canonical model order unchanged.
• Document these contracts in English architecture documentation.

Regression coverage

Five new native tests cover interleaved repeated marks and final per-kind styles, last assignment of point fields, semantic diagnostic precedence independent of argv order, syntax/cross-feature precedence, and isolation between invocations. Existing per-kind annotation parsing/model tests remain intact. Visual blur stays visual only and does not sanitize sidecars.

Verification

Published source head: 82fc47e
Uploaded tree: f9852179b729792a4fd0bb0953934220236b993d
Explicit base: main at bb8fea0

• Local git diff --check and make hygiene changelog-check passed.
• Platform-independent prerequisites in make lint passed.
• Native swift-format, build and tests were attempted but blocked by missing xcrun/Xcode/XcodeGen on this Linux executor; they are not reported as passed.
• Exact-head native CI 37400428192 completed successfully: all five required jobs pass. Existing coverage, rendering, visual, UI and performance gates are unchanged.

Scope and integration

Independent main-based PR, separate from open app-review, file-reload/read, CLI batch-preflight and GUI export-publication changes. No public API break, overwrite policy, merge, release, deployment or credential access.

Exact-head hosted evidence

Source head: 82fc47e
Verified remote/local tree: f9852179b729792a4fd0bb0953934220236b993d
Verified synthetic PR merge checkout: ef6211b

• Strict formatting, warning checks, Debug and universal arm64/x86_64 Release builds pass on both SDKs.
• All five new annotation compatibility regressions pass natively on Sequoia and Tahoe.
• The disjoint coverage lane reports 2,397 passing tests per SDK: 244 CLI, 143 Domain, 51 Rendering, 133 Repository and 1,826 app tests.
• Changed critical executable lines are 94/94 covered (100%). Production coverage is 58.28% on Sequoia against the unchanged 47.87% floor, and 58.32% on Tahoe against the unchanged 47.93% floor.
• Frozen performance gates pass; this refactor makes no measured performance-improvement claim.
• Tahoe's pinned strict golden lane compares all seven baseline images with zero differing pixels. Sequoia's explicit golden smoke lane is render-only.
• Each ordinary UI run reports 108 cases, with the 26 tour cases deliberately deferred. The separate strict tour executes all 26 successfully, then exports and validates all 53 required screenshots through xcresult attachments.
• Both UI/tour jobs and Linux static checks pass. Direct screenshot-file writes encounter the existing test-host sandbox boundary; the supported xcresult attachment exporter completes and validates delivery.
• Open and mergeable. Main remains bb8fea0. Pairwise source merges are conflict-free with the recorded open app-review/CLI batch and file/export repair heads; that is not a combined native-integration qualification.

No gates, baselines or expected skips were relaxed. No merge, release or deployment.

Human-review readiness

Scoped implementation and regressions are complete at unchanged head 82fc47e. Fresh exact-head checks confirm all five required CI jobs plus GitGuardian successful. No submitted reviews, discussion comments or unresolved inline review threads are pending. Human-review readiness does not qualify an untested combined integration or authorize merge, release or deployment.

Review follow-ups (2026-10-06)

• Code changes: none needed.
• Verified:
  • validate() reproduces the old checks one-for-one, with the same messages and kind order.
  • hasContent matches the old --edit disjunction.
  • materialized attaches the final per-kind style to every point, and highlighter size and blur style stay nil.
  • Annotation state is fresh per invocation.
• Possible follow-up (docs only): document in --help/README that a later --<kind>-color/--<kind>-size applies to every mark of that kind, including earlier ones. That is long-standing behavior, unchanged by this PR.

---

Generated by Claude Code

[johnny4young]

Review: centralize CLI annotation state

What it does: replaces 22 loose annotation fields on CLIArgumentParser with one invocation-local CLIAnnotationArguments value. Two position/style groups (callout, counter) and five geometry groups (arrow, line, rectangle, highlighter, blur) each own their own validation and projection into CLIOptions.

Verdict: ready. Nothing blocking found.

What I checked

• Diagnostics: validate() reproduces the old checks one-for-one, with the same messages in the same kind order (callout → counter → arrow → line → rectangle → highlighter), and runs at the same point in the compatibility pass. The precedence tests cover argv-order independence.
• hasContent: matches the old styleOptionsRequested disjunction for --edit exactly.
• Projection: materialized attaches each group's final color and size to every point, as before. highlighters.size and the blur group's style are never set by any flag, so they stay nil, matching the old hard-coded size: nil / color: nil.
• Positions: callout.position and counter.position keep the "both or neither" semantics.
• Isolation: the parser builds a fresh value per invocation (var annotations = CLIAnnotationArguments()), so no state leaks between runs.
• CI was green on 82fc47e (all 5 required jobs).

🟡 Nit: the ARCHITECTURE.md section says "a later style flag applies to every mark of that kind, including earlier marks". That's accurate and long-standing, but it may surprise CLI users. A one-line note in --help or the README for --arrow-color and friends would make it discoverable.

---

Generated by Claude Code