Propose script-variant anchor matching

[kiki830621]

Summary

• add a Spectra/OpenSpec change proposal for P3 enhancement: H₀ Unicode subscript anchors don't match flatten output (post-#85 follow-up) che-word-mcp#90
• specify opt-in math-script-insensitive anchor matching in OOXMLSwift
• specify che-word-mcp match_options.math_script_insensitive for insertion text anchors

Validation

• spectra validate script-variant-anchor-matching

Refs PsychQuant/che-word-mcp#90

[kiki830621]

Verify Report — PR #97

Engine

6-AI ensemble: 5 general-purpose Agents (Claude reviewers) + Codex (gpt-5.5 xhigh). All 5/5 findings present + non-empty on first attempt. No Process Gaps.

Aggregate

NEEDS CHANGES (lighter) — Path B correctly chosen, dual-capability split clean, opt-in default-off well-locked. But 4 reviewer-converging blockers around contract gaps prevent archive. Verdict is materially better than #94/#95/#96 — this PR is closer to merge-ready.

Scope coverage

• Cross-repo: spec lives in macdoc, refs P3 enhancement: H₀ Unicode subscript anchors don't match flatten output (post-#85 follow-up) che-word-mcp#90 (P3 enhancement)
• Verified scope: che-word-mcp#90 + ooxml-swift dependency chain

---

Cross-repo che-word-mcp#90 — script-variant anchor matching

Requirements coverage (Requirements + Codex consensus):

• Path selection (B — lookup-time matcher option, opt-in flag): FULLY documented in proposal/design
• Cross-repo Spectra arrangement (spec in macdoc as umbrella): JUSTIFIED per .claude/rules/cross-repo-umbrella.md (but rationale not in proposal text)
• Subscript translation table: PARTIALLY — digits/signs pinned, Latin letters under-specified
• Backward compat (opt-in default false): FULLY locked (4 belt-and-suspenders layers)
• j corner case (no canonical Unicode subscript): NOT pinned with worked example
• test: strengthen Note→HTML smoke assertions (media/ dir + size floor) #86 dependency (anchor lookup public surface): NOT tracked in proposal artifacts

Findings (merged + deduplicated)

#	Severity	Finding	Source	Action
1	MEDIUM-BLOCKER	Direct Mode vs Session Mode contradiction: spec.md requires Direct Mode consistency with explicit source_path Scenario; tasks.md says this change has no source_path mutating Direct Mode surface. Internal artifact contradiction.	agents:codex	Reconcile — either drop Direct Mode requirement OR scope Direct Mode in for impl
2	MEDIUM-BLOCKER	che-word-mcp#86 dependency not tracked. Path B requires public anchor lookup surface from #86 (already MERGED per regression review, but PR artifacts don't reference it — no Refs #86, no version gate, no "OOXMLSwift release prerequisite" note). Cross-repo Spectra needs prerequisite chain documentation.	agents:codex+regression+devils-advocate	Add Refs ooxml-swift#38 (merged) + version threshold + dependency note in design.md
3	MEDIUM-BLOCKER	Unicode normalization form not pinned. spec mentions normalization but doesn't specify NFC/NFD/NFKC/NFKD. Implementer could pick NFKC fold and accidentally widen scope to homoglyphs/combining marks. Design Decision must lock the canonicalization model.	agents:security	Spec Decision: explicit Normalization Form choice + negative Scenarios (combining marks NOT folded)
4	MEDIUM	Homoglyph attack vector not considered. Cyrillic "а" (U+0430) vs Latin "a" (U+0061) — spec must declare these NOT considered equivalent. Otherwise anchor confusion attack: paper has Cyrillic "а" but anchor types Latin "a" finds it.	agents:security+devils-advocate	Spec Non-Goal entry + Scenario showing Cyrillic/Latin NOT cross-matched
5	MEDIUM	Tasks.md all marked [x] but proposal PR shouldn't have completed tasks. spectra analyze reports 12 warnings (requirement/design topic without corresponding task). If tasks were actually executed cross-repo, the spec should link PsychQuant/ooxml-swift#38 (MERGED) + che-word-mcp#115 (OPEN) + test commands.	agents:codex	Either reset to [ ] for proposal phase OR link the executing PRs/commits/tests
6	MEDIUM	Canonicalization table incomplete: digits (U+2080-U+2089, U+2070-U+2079) + signs are pinned; Latin letters described as "common Unicode subscript/superscript Latin letters with clear compatibility forms" — no codepoint range. Scenario xᵢ implicitly requires U+1D62 (IPA Modifier, outside U+2090-U+209C). Drift risk.	agents:requirements+logic+codex	Pin explicit codepoint table + non-supported list
7	MEDIUM	j corner case — no canonical Unicode subscript exists. Spec should explicitly enumerate "characters that DON'T have canonical Unicode form, preserved as-is".	agents:requirements+codex	Add j worked example + non-supported list section
8	MEDIUM	Mixed Unicode+ASCII needle scenario missing. Realistic reviewer workflow: anchor "H₀ 等於 H0" (paper has H₀ subscript notation AND ASCII "H0" mentioned later). Current spec scenarios don't cover this.	agents:logic	Add Scenario
9	MEDIUM	Math-context vs general-text scope not gated. Naming mathScriptInsensitive implies OMML zone gating, but spec applies normalization to entire flattenedDisplayText — including non-math paragraphs with subscript characters (e.g., chemistry "H₂O" in normal text). Either rename to remove "math" prefix OR add gating.	agents:devils-advocate	Resolve naming/scope mismatch
10	LOW-MEDIUM	Deprecation/Phase-2 plan for opt-in flag missing. Opt-in implies "default is broken". If math anchors are the dominant case (academic paper review), should default flip in Phase 2? Spec silent on lifecycle.	agents:devils-advocate	Add Future section
11	LOW	Mutating tool idempotency — calling insert_paragraph with script_insensitive=true twice → does it insert twice (default behavior) or 1 + idempotency check? Spec scenarios don't cover.	agents:logic	Add Scenario
12	LOW	match_options: {} empty object — equivalent to omitted? Spec silent.	agents:regression	Spec explicit
13	LOW	Translation table missing mathematical operators (− U+2212, · U+00B7, ′ U+2032). Issue body's H₀ + H₁ example uses + U+002B (covered) but − minus is not.	agents:security	Extend table OR document Non-Goal
14	LOW	Proposal omits Alternatives Considered section. Path A + Path C rationale exists in issue but not in proposal.md itself — reader must hunt across repos.	agents:requirements	Copy 3-path table into proposal.md
15	LOW	H_0 vs H₀ naming inconsistency in design.md narrative (uses both forms in different paragraphs).	agents:security	Pick one convention
16	LOW	cross-repo-umbrella.md rule mentions need for umbrella issue when changes span 2+ repos. Per gh issue list, no umbrella issue exists for this dual-capability spec.	agents:devils-advocate	Open umbrella OR document why this doesn't qualify
17	LOW-MEDIUM	P3-issue → 333-line dual-capability spec proportionality. Engineering justification (cross-repo API contract) is sound but not stated in proposal.	agents:devils-advocate+regression	One-sentence rationale in proposal
18	LOW	instance vs text_instance naming used in different places.	agents:requirements	Pick one
19	LOW	Spec narrative says "consistent with existing MCP validation" without citing where.	agents:requirements	Cite or remove

Scope Check

Spec scope is proportional to the cross-repo API contract complexity. No scope creep within the proposal. Cross-repo arrangement (umbrella spec in macdoc) is per project convention (per regression reviewer's check of cross-repo-umbrella.md).

Security

2 MEDIUM-BLOCKER security findings (#3 normalization form + #4 homoglyph). Both can be resolved with explicit Non-Goal + negative Scenario additions; no implementation rework needed.

Process Gaps

None — all 5/5 reviewers produced findings on first attempt.

---

Recommendation

NEEDS CHANGES but lighter than #94/#95/#96. The path-B decision is correct, the dual-capability split is clean, the opt-in safety mechanism is robust. The 4 BLOCKERs (#1-#4) are spec-text additions, not architectural rework.

Required Spec revisions:

1. Direct Mode contradiction — reconcile spec vs tasks (either drop or scope in)
2. test: strengthen Note→HTML smoke assertions (media/ dir + size floor) #86 dependency — add Refs ooxml-swift#38 (MERGED) + Refs che-word-mcp#115 (OPEN) + dependency chain note in design.md
3. Unicode normalization form — pin NFC (likely choice) explicitly + negative scenarios
4. Homoglyph Non-Goal — explicit declaration + Cyrillic/Latin cross-match negative Scenario

Recommended additionals (lift quality):
5. Reset tasks.md to [ ] OR link the executing PRs (ooxml-swift#38, che-word-mcp#115) + test commands
6. Pin explicit codepoint table for Latin letters + non-supported list (j/q/x + variants)
7. Add j worked example
8. Add mixed Unicode+ASCII needle Scenario
9. Resolve mathScript* naming vs flattenedDisplayText-wide scope

Path A (revise) preferred. If you prefer Path B (merge as Phase 1 + follow-ups), the 4 BLOCKERs would each need a dedicated follow-up issue.

[kiki830621]

Blocked pending lighter spec revision. 4 MEDIUM-BLOCKERs (#1 Direct Mode contradiction, #2 #86 dependency tracking, #3 Unicode normalization form, #4 homoglyph Non-Goal) + 15 other findings. Closer to merge-ready than #94-#96 — Path B decision is correct + opt-in default-off well-locked. Full revision list at #97 (comment).

[kiki830621]

Closing — Superseded by ooxml-edit-isomorphism-foundation (#99)

Per #99 ADR-009 + verify report (#97 (comment)), this cross-repo proposal's 4 MEDIUM-BLOCKERs (Direct Mode contradiction, #86 dependency tracking, Unicode normalization form pinning, homoglyph Non-Goal) intersect with the foundation's Edit-type contract.

When the architectural foundation's Edit type lands in #105, the script-variant anchor matching becomes a property of WordEdit's text-locating semantics rather than a parallel match_options surface on che-word-mcp tools.

The Codex work in this PR remains accessible (git show codex/script-variant-anchor-matching-spec) for reference when authoring the re-frame against ooxml-edit-algebra capability.

Refs #99 #105 PsychQuant/che-word-mcp#90