Noema document multimodal envelope + proofreading checklist (#2280)

.github/workflows/agent-review-runtime-quality-ci.yml

@@ -16,7 +16,10 @@ on:
       - "scripts/ci/noema-document-reader/package.json"
       - "scripts/ci/noema-document-reader/package-lock.json"
       - "tests/test_noema_document_review_context.py"
+      - "tests/test_noema_review_document_multimodal.py"
+      - "docs/doctoring/noema-document-multimodal-proofreading.md"
       - "docs/doctoring/noema-review-token-lifetime.md"
+      - "scripts/ci/noema_review_gate.py"
       - "docs/product-technical-gap-baseline.md"
       - ".github/workflows/opencode-review-dispatch.yml"
       - "scripts/ci/ensure_rust_llvm19.sh"
@@ -198,6 +201,9 @@ jobs:
               scripts/ci/noema-document-reader/package.json|\
               scripts/ci/noema-document-reader/package-lock.json|\
               tests/test_noema_document_review_context.py|\
+              tests/test_noema_review_document_multimodal.py|\
+              docs/doctoring/noema-document-multimodal-proofreading.md|\
+              scripts/ci/noema_review_gate.py|\
               docs/doctoring/noema-review-token-lifetime.md)
                 noema_suite=true
                 ;;
@@ -366,14 +372,16 @@ jobs:
             tests/test_noema_two_phase_handoff.py \
             tests/test_noema_refreshed_app_identity.py \
             tests/test_noema_token_lifetime_stale_run_contract.py \
-            tests/test_noema_document_review_context.py
+            tests/test_noema_document_review_context.py \
+            tests/test_noema_review_document_multimodal.py
           python -m compileall -q \
             .github/actions/noema-review/two_phase.py \
             tests/test_noema_reviewer_token_lifetime.py \
             tests/test_noema_two_phase_handoff.py \
             tests/test_noema_refreshed_app_identity.py \
             tests/test_noema_token_lifetime_stale_run_contract.py \
-            tests/test_noema_document_review_context.py
+            tests/test_noema_document_review_context.py \
+            tests/test_noema_review_document_multimodal.py
 
       - name: Verify OpenCode Rust coverage toolchain contract
         if: steps.affected_suites.outputs.opencode == 'true'

.github/workflows/trusted-uv-materializer-quality-ci.yml

@@ -12,6 +12,7 @@ on:
       - "tests/test_uv*.py"
       - "tests/test_repository_branch_coverage_*.py"
       - "requirements-opencode-review-ci-hashes.txt"
+      - "requirements-noema-document-ci-hashes.txt"
       - "pyproject.toml"
   push:
     branches: [main]
@@ -24,6 +25,7 @@ on:
       - "tests/test_uv*.py"
       - "tests/test_repository_branch_coverage_*.py"
       - "requirements-opencode-review-ci-hashes.txt"
+      - "requirements-noema-document-ci-hashes.txt"
       - "pyproject.toml"
 
 concurrency:
@@ -104,10 +106,12 @@ jobs:
         with:
           python-version: "3.14"
           cache: pip
-          cache-dependency-path: requirements-opencode-review-ci-hashes.txt
+          cache-dependency-path: |
+            requirements-opencode-review-ci-hashes.txt
+            requirements-noema-document-ci-hashes.txt
 
       - name: Install hash-locked quality tooling
-        run: python -m pip install --disable-pip-version-check --require-hashes -r requirements-opencode-review-ci-hashes.txt
+        run: python -m pip install --disable-pip-version-check --require-hashes -r requirements-opencode-review-ci-hashes.txt -r requirements-noema-document-ci-hashes.txt
 
       - name: Run trusted uv tests with complete branch coverage
         run: |

CHANGELOG.md

@@ -1,3 +1,7 @@
+### Noema DOCX and HWPX figures preserve document relationship order
+
+- `scripts/ci/noema_review_document.py` resolves embedded DOCX figures through `word/_rels/document.xml.rels` and HWPX figures through `Contents/content.hpf` plus each spine-ordered section's `binaryItemIDRef`. Both paths preserve semantic source order, ignore orphaned archive media, bind stable relationship/media locators, and fail closed on duplicate, unresolved, external, traversal, malformed, or unreadable relationships. The immutable contextual-orchestrator multimodal release/pin and protected merge remain Proposed dependencies of `.github#2281`; this entry does not claim release completion.
+
 ### Noema transport capacity schedules a bounded continuation re-dispatch
 
 - After gateway failover, HTTP 429/5xx no longer end only as a permanent required-check failure with `caller attempts=1`. ADR-0031 classifies that class as `provider_capacity_unavailable`, keeps the single gateway request per job, surfaces `provider_attempt_count` from the orchestrator error envelope, and authorizes at most two same-head `repository_dispatch` retries after a capped `Retry-After` or deterministic 60–180 s jitter. Review is never skipped. Refs #2165.

docs/doctoring/noema-document-multimodal-proofreading.md

@@ -0,0 +1,83 @@
+# Noema document multimodal envelope and proofreading checklist
+
+Issue: ContextualWisdomLab/.github#2280
+
+## Problem
+
+Noema's document reader extracted bounded text from `.docx`, `.hwp`, and `.hwpx`
+files, but embedded figures never reached the model. A text-only success path
+could omit images silently. Document PRs also lacked an explicit proofreading
+contract tied to the organization's existing skills.
+
+## Contract
+
+1. **Extraction** — `scripts/ci/noema_review_document.py`
+   - `extract_review_document_bundle()` returns `DocumentExtraction` with text,
+     declared media count, and OpenAI-style multimodal parts (`text` locator +
+     `image_url` data-URL per figure).
+   - `extract_review_document()` remains text-only and **fails closed** when
+     figures are present.
+   - `ensure_figures_attached()` rejects partial or missing figure coverage.
+   - Provisional leaf budget: at most eight figures, each at most 1.5 MiB.
+   - DOCX figures are resolved only from internal image relationships in
+     `word/_rels/document.xml.rels` and attached in the source order of
+     `a:blip` elements in `word/document.xml`. Orphan ZIP media is not source
+     evidence; missing, external, or out-of-bound relationship targets fail
+     closed.
+   - HWPX figures are resolved from the `Contents/content.hpf` manifest and
+     spine-ordered section XML `binaryItemIDRef` references. Locators preserve
+     section, paragraph/run/table-cell position, manifest ID, and exact
+     `BinData` path. Orphans are ignored; duplicate IDs/entries, unresolved or
+     external references, traversal, malformed XML, and unreadable targets
+     fail closed.
+
+2. **Review gate** — `scripts/ci/noema_review_gate.py`
+   - `fetch_file_review_bundle()` fetches office documents as text + parts.
+   - `ReviewContext` carries bounded text and flattened multimodal parts from
+     changed/removed files.
+   - `call_llm()` emits a multimodal user message when parts exist; otherwise
+     the legacy string envelope is preserved.
+   - `document_proofreading_prompt_lines()` encodes the reused skills:
+     `~/.claude/skills/humanize-korean/SKILL.md` (KO/EN style and terminology
+     consistency without rewriting substance) and
+     `~/.agents/skills/source-check/SKILL.md` (citation/page verification;
+     no arbitrary number or citation edits).
+
+3. **Fixtures** — synthetic archives only in `tests/test_noema_document_review_context.py`.
+   Research originals and participant materials are never used.
+
+## Ownership and delivery state
+
+- `.github#2281` DOCX implementation evidence is functional commit
+  `4513708f47ee44b51d431272f91af753dda8a882` (tree
+  `b3deea106a94799f324cee385f9246db6b443548`). HWPX RED
+  `21eae9d5e9ce4ee43ee692776a1062c13c9f1a98` precedes GREEN
+  `768860076068384552c9dfdb02bec1d8996962be` (tree
+  `3b8b28e6b815ec7b635458c456f0deb921a49ec8`). The branch remains Draft and
+  Proposed until fresh exact-head Checks and an independent approval exist.
+- Multimodal route discovery and fail-closed capability selection belong to
+  `ContextualWisdomLab/contextual-orchestrator#1203`, current head
+  `37435b5e82e9fe53abc67b032c67df83425c0250` (tree
+  `e7bf07b644af5b3ed7b1117b0baeab14767f4ad8`). It ordinarily preserves source
+  repair `738ab3689d110685ca07f09b7c51031f11d3f07f`, the prior exact evidence, and
+  RED `7f69bacb0d35f00e6902df8e440efeafbe08dbe3` before its latest judge-failover
+  GREEN. Its four exact-head workflows are queued and no independent approval
+  exists. The leaf must consume a protected immutable release/pin; an open
+  owner PR is not released API authority.
+
+## Verification
+
+```bash
+PYTHONWARNINGS=error python3 -m pytest -q \
+  tests/test_noema_review_document_multimodal.py \
+  tests/test_noema_document_review_context.py \
+  tests/test_noema_removed_file_context.py
+coverage run -m pytest tests && coverage report --show-missing
+interrogate
+```
+
+Multimodal e2e tests assert `image_url` data-URLs in the captured LLM payload
+and fail-closed behavior when figures are omitted or media types are unsupported.
+The current focused evidence is `79 passed, 2 skipped`; the owned document
+reader is `381/381` statements and `134/134` branches (100%). Hosted exact-head
+evidence remains required after the branch is published.

docs/product-technical-gap-baseline.md

@@ -7,6 +7,17 @@
 
 이 문서는 제품·기술·운영 Gap을 현재 문서와 현재 GitHub 상태에 묶어 두는 기준선이다. 새 작업은 먼저 이 문서의 Gap ID를 PR 설명과 테스트 증거에 연결하고, PR의 정확한 exact HEAD·Checks·리뷰를 다시 수집한 뒤 구현한다. 표의 상태는 작성 시점의 관측값이므로, 병합 판단에는 재사용하지 않는다. 이 인벤토리는 스냅샷이며 merge authorization이 아니다.
 
+### 2026-09-20 Noema document multimodal delta
+
+| Gap ID | 상태 | exact evidence | causal owner / next gate |
+|---|---|---|---|
+| CONTROL-NOEMA-DOCX-SOURCE-ORDER-01 | **Proposed; DOCX source-order repair implemented on `.github#2281`, not merged** | Functional commit `4513708f47ee44b51d431272f91af753dda8a882`, tree `b3deea106a94799f324cee385f9246db6b443548`; relationship order, orphan exclusion, unresolved relationship and path-escape fixtures; focused evidence is included in the combined `79 passed / 2 skipped` warnings-as-errors lane below. | `.github` owns document extraction. Fresh exact-head hosted Checks and independent approval remain required before ordinary merge. |
+| CONTROL-NOEMA-HWPX-SOURCE-ORDER-04 | **Proposed; HWPX source-order repair implemented on `.github#2281`, not merged** | RED `21eae9d5e9ce4ee43ee692776a1062c13c9f1a98` exposed filename-order inference, orphan admission, and missing manifest validation. GREEN `768860076068384552c9dfdb02bec1d8996962be`, tree `3b8b28e6b815ec7b635458c456f0deb921a49ec8`, binds `content.hpf` manifest IDs to spine/section `binaryItemIDRef` order and stable paragraph/run/table-cell locators; duplicate reuse preserves distinct positions. Duplicate IDs/entries, external/traversal/unresolved relationships, malformed XML, missing sections, unreadable/empty media, and unsupported media fail closed. Focused warnings-as-errors: `79 passed / 2 skipped`; owned reader: `381/381` statements and `134/134` branches (100%); compileall and diff check pass. | `.github` owns document extraction. Exact-head hosted protection and independent review remain open; release completion is not claimed. |
+| CONTROL-NOEMA-MULTIMODAL-OWNER-02 | **Canonical owner repaired but open/unreleased** | `ContextualWisdomLab/contextual-orchestrator#1203` historical exact `5fa1c8b8f19353d712d6578c4af4c75e96f6988b`, tree `027ee33be749e702290e24ae663879d523974455`, preserves the earlier owner lineage. Judge-failover RED `7f69bacb0d35f00e6902df8e440efeafbe08dbe3` proved a selected free image judge could escape to an ineligible text-only or paid sibling; GREEN `37435b5e82e9fe53abc67b032c67df83425c0250` persists the exact outer free/image-qualified ID set into adapter failover. Later source GREEN `b7440092d1cda47008271ed658fe372f536dd58f` repairs role-ineligible worker preflight, restores complete source blob `1dd97e36fe1579c434413317a5366f9f27d6e766` after the reviewed truncation incident, contains no truncation marker, passes `py_compile`, and completes the three affected warnings-as-errors suites at `91 passed`. Owner-lineage RED `a952041f26ed258c8668fffff3f28e1fe5121355` and GREEN `acb31d0e8929438bf6f46ec12422ad4cc78b91f2` preserve those functional milestones in the canonical owner baseline; formatting-only `5fa1c8b8f19353d712d6578c4af4c75e96f6988b` preserves that earlier evidence. Durable-modality exact `e4846673c110ceaace5cfe300081f02521b4429b` adds case-normalized `input:*` admission after restart while retaining explicit-modality precedence. Current owner exact `ad45a74f0acdddcd023646661413e76a120b88e3` additionally carries mode-alias RED `10f96453a6050ab47575e4975aa068cb4f899e23` and GREEN `c3e4e94cf6566f6a0187c502d279dccc6989d4a1`, so explicit falsey aliases fail closed instead of becoming omitted-mode `auto`; it remains open, Ready/Proposed, unreleased, with fresh hosted acceptance and independent approval pending. | contextual-orchestrator owns modality-aware discovery/routing. Merge under protection, make an immutable release, then advance the `.github` consumer pin and run contract/E2E evidence. No mutable branch/source copy, paid fallback, or Python leaf workaround is authorized. |
+| CONTROL-NOEMA-DOC-QUALITY-DEPS-05 | **Proposed repair on `.github#2281`; hosted exact-head acceptance pending** | [Trusted uv run `35459690722`](https://github.com/ContextualWisdomLab/.github/actions/runs/35459690722), job `105941203532`, passed 108 focused tests at 100% coverage and then failed complete-suite collection in 11 document tests because `defusedxml` was absent. RED `4614971896dac7f52871eec4501f32338cca0375` requires the Noema document hash lock in path, cache, and install authority; GREEN `5521b8128c90d374eb05533aa00da31cc619eaa7` installs both immutable locks before the full suite. | `.github` owns the central quality workflow and its complete dependency closure. Fresh exact-head hosted execution and independent review remain required; focused success does not supersede the failed full-suite oracle. |
+| CONTROL-STRIX-FIXTURE-BINDER-06 | **Proposed fixture repair on `.github#2281`; hosted exact-head acceptance pending** | [Runtime Quality run `35459690876`](https://github.com/ContextualWisdomLab/.github/actions/runs/35459690876), job `105941203883`, showed the production gate correctly failing closed because synthetic repositories copied `strix_quick_gate.sh` and `strix_model_utils.sh` but omitted required `strix_evidence_binding.py`. GREEN `346e1160174926c59995e748f4d9ecb0652c1f41` materializes the production binder in all 25 model-utils fixture roots; the 24 direct gate roots are covered without weakening production admission. | `.github` owns the Strix gate fixture contract. Fresh exact-head Runtime Quality must prove every scenario; the repair does not bypass or relax the production binder requirement. |
+| CONTROL-GAP-BASELINE-PRESERVATION-03 | **Proposed repair on `.github#2281`** | Predecessor `dc47aa82faf4a838b96b63a84a459efea7e91c84` changed this baseline by +11/-1,897 and dropped 28 of 59 protected level-two sections. RED `9ba78fe89f2d2dd19477650c5a26d42df5e4bd24` requires representative protected security, runtime, compliance, APA, and credential-lifetime authorities. The selected repair restores protected `main` and keeps this four-row delta additive. | `.github` owns the central baseline. Exact-head hosted checks and independent review must confirm the restored tree before Ready/merge; future baseline updates must preserve or explicitly supersede protected authority rather than replace the file from a stale branch snapshot. |
+
 ### 2026-09-13 current-head incident delta
 
 | Gap ID | 상태 | exact-head evidence | causal owner / next gate |