feat: detect and retain DOCX text boxes / callout shapes; surface them for review

[thewrz]

Why

Sometimes text boxes, callouts and inserted comments are included in a master spec and exist in draft form, but must be deleted before Final — with routing semantics (a text box addressed to a reviewer is deleted by that reviewer; one addressed to editors by editors). SpecR covers the comments third of this item well; text boxes and callout shapes are entirely unmodeled — the parser never extracts them, so their content is invisible to review and silently absent from round-trip output.

Verified current state (2026-07-07):

• Word comments: fully covered — captured as permanent source facts (comments.xml extraction, feat(parser): extract DOCX margin comments (comments.xml) as paragraph-anchored facts #128), open-comments report per spec/project (src/db/queries/open-comments.ts), closure detection (src/ast/comment-closure.ts), accept_comment_as_note (src/db/queries/reclassify.ts:357).
• Text boxes (w:txbxContent inside mc:AlternateContent/VML shapes) and callouts: zero handling anywhere in src/parser/ — verified absent in the audit. Never filed as an issue.
• The retain-don't-discard precedent is established: hidden text (feat(parser): exclude hidden OOXML text from 5-signal inference (retain, don't discard) #291, ADR-038) and hidden tables are retained in sidecars rather than dropped; visible tables detect-and-warn (feat(parser): parse DOCX tables — retain hidden, warn on visible #293/feat(parser/generator): represent + round-trip visible tables in specs (AST model, inference exclusion, render) #300 open).

Proposed scope

1. Detect text-box/callout content at parse time (drawing + VML paths in the OOXML body) and retain it — per ADR-038, as source facts or a raw sidecar anchored to the nearest paragraph, never silently dropped.
2. Surface a per-spec/per-project report of text boxes with their text (so a reviewer can route each one to whoever owns its removal), either extending the open-comments report shape or as a coordination finding — decide in impl.
3. Feed the issuance-readiness gate (companion issue): text boxes present → Final blocker/warning.

Non-goals

• Round-trip regeneration of text boxes into output DOCX (fidelity is a separate, later concern — same split as hidden tables feat(parser): parse DOCX tables — retain hidden, warn on visible #293 vs feat(parser/generator): represent + round-trip visible tables in specs (AST model, inference exclusion, render) #300).
• Images/logos inside shapes (H/F program feat(generator): render header/footer image and logo content #308 territory).

Pointers

ADR-038 (hidden OOXML retained), #291/#293/#300 (the retain-and-warn family this extends), src/parser/docx/comments.ts + open-comments.ts (report shape to mirror).

[thewrz]

Prior-art validation during sprint pickup (2026-07-27): the body-objects program has shipped the core of this issue since it was filed —

• Detect + retain: text boxes / callout shapes (w:txbxContent, incl. mc:AlternateContent fallbacks) are captured as first-class body objects with retained blobs and anchored interiors — src/parser/docx/body-objects.ts, body-drawings.ts, body-object-attach.ts (ADR-072; feat(parser): capture body objects (tables, text boxes) from DOCX body content #513/feat(generator): round-trip body objects via ImportedXmlComponent (#300 WS2) #518).
• Surface + edit: objectText is exposed through the read model, with an interior-text edit API and read-only object display in the demo (feat(api/generator): interior-text edit API for body-object objectText + demo read-only object display (#300 WS3a) #519).
• Round-trip: blobs re-emit on generate, incl. the mc:Fallback dedup fix (fix(parser): captured text-box blob keeps mc:Fallback, duplicating objectText (ADR-072 decision 7 not applied on the capture path) #517).

Rescoped rather than closed. What remains here:

1. A dedicated per-spec/per-project text-box/callout report mirroring the open-comments report shape (routing: who owns each box's removal) — the 'surface for review' half of the original ask. ← this issue's remaining scope
2. Feeding the issuance-readiness gate → now in flight as feat: issuance-readiness gate — validate brackets/notes/comments/highlight before "Final" (ADR required) #406 (text-box presence as a Final blocker).
3. Mixed visible/hidden box visibility → tracked as fix(parser): body text-box visibility is decided per host-paragraph, not per text box (mixed visible/hidden boxes leak or suppress objectText) #515.

🤖 Prior-art audit by Claude Fable 5