feat(office): add bounded DOCX page layout contract

[seonghobae]

Purpose

Implement the bounded DOCX page-layout slice as next-release Inkspan work while protected main remains the release authority tracked by #118.

Current source identity

• Live protected base: main@3b38ead2d00f44eb578d0689087b9293b3dabe1e.
• Current exact Draft head: ad497ed4150d4648206afd65487bf0a8b3d14a40 on feat/docx-page-layout.
• The branch already contains the non-destructive synchronization with protected main; predecessor identities dd73df7..., d715efb..., d1148b4..., and earlier base e8109ec... are historical only. Their checks/reviews do not pass the current head.

Test-first lineage

• Original RED 634d1ed1a7f7a29cd6681872a42ac49d330717d6 reached the Office product boundary and failed because the renderer rejected page_layout.
• Preflight-order RED ce809c3485e92729a9115c5d685fe187b313f7d3 / CI 31567029574 proved invalid layout was rejected only after content rendering; the repair validates layout first.
• Diagnostic-privacy RED 05475267ee3eb0d535af07ac828998611c8b89bb / CI 31587583073 proved caller-controlled unknown member names leaked into ordinary errors; the repair retains only structural path/category diagnostics.
• 4bd144047b9e573859097e29c17ae569b34a1817 bounded unknown-key scanning; d1148b4980c689e1a1a0fb6e7dc092f17ac60225 added the repeated-iterator-key regression so exotic mappings cannot evade progress indefinitely.
• Current ad497ed4150d4648206afd65487bf0a8b3d14a40 additionally contains the payload-redaction repair for hostile page-layout mapping failures: unknown mapping/access failures are normalized to stable OfficeDocumentError('page_layout is invalid') instead of leaking caller-controlled exception material.

Implemented boundary

The branch provides a bounded machine-readable DOCX page-layout contract: A4/Letter, portrait/landscape, integer 0–100 mm margins, fail-fast validation, bounded hostile-mapping handling, deterministic single-section OOXML application/canonicalization, payload-redacted diagnostics, no partial publication on failure, real round-trip matrix coverage, structural-fidelity regressions, and explicit DOCX-only format enforcement. It does not add arbitrary page dimensions, multiple-section authority, headers/footers, durable print/PDF authority, network, persistence, credentials, tenancy, model, transport, authorization, or durable-audit authority.

Exact-current-head evidence

For unchanged exact head ad497ed4150d4648206afd65487bf0a8b3d14a40 against live base main@3b38ead2d00f44eb578d0689087b9293b3dabe1e:

• repository CI 32004457407: completed / success;
• Security Scan 32004457376: completed / success;
• SAST Semgrep 32004457423: completed / success;
• build-and-test 95311092050: completed / success;
• Office Python 3.11 95311092059, 3.12 95311091957, 3.13 95311092032, and 3.14 95311091966: completed / success;
• cross-engine Clipboard / Playwright 1.62.0 95311092125: completed / success;
• required central OpenCode 95311094275, Strix 95311088624, Noema 95311026363, close-empty 95311026207, required-workflow bootstrap 95311026423, and scheduler queue scan 95311026138: completed / success;
• coverage-source-tree 95311045810 and coverage-evidence 95311069576: completed / success;
• OSV 95311034907, Trivy 95311034895, dependency review 95311035064, and Scorecard 95311034787: completed / success;
• formal reviews: one Cursor COMMENTED review, explicitly non-approving;
• qualifying approving reviews: 0;
• unresolved inline review threads: 0.

Skipped auxiliary cancellation/manual-evidence jobs are not treated as required passing evidence. Any head/base movement invalidates this exact generation.

Governance and integration boundary

Live organization ruleset 18156473 currently requires one qualifying approving review, dismisses stale approvals after a push, requires approval of the latest push by someone other than the pusher, requires review-thread resolution, requires the central workflows, allows merge/squash only, forbids deletion/non-fast-forward updates, exposes no bypass actor, and the current user cannot bypass.

The product/source lane is exact-head green, but this is not merge-ready: the independent approval is absent and #118 still freezes protected v0.6.0 publication identity. Keep this PR Draft and unmerged. Refetch live rules, head/base, review/thread state, and exact checks before any future lifecycle transition; never transfer predecessor evidence or synthesize tag/release identity from a branch ref.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 122a1949-9cbb-42b9-9e89-b3e8033e42c4

📥 Commits

Reviewing files that changed from the base of the PR and between af14e5c and aa98785.

📒 Files selected for processing (18)

• docs/TRACEABILITY.md
• docs/adr/0027-bounded-docx-page-layout.md
• docs/adr/README.md
• docs/doctoring/docx-page-layout.md
• docs/docx-page-layout.md
• office/src/inkspan_office/page_layout.py
• office/src/inkspan_office/safe_renderer.py
• office/src/inkspan_office/schema.json
• office/tests/test_page_layout.py
• office/tests/test_page_layout_content_fidelity.py
• office/tests/test_page_layout_error_privacy.py
• office/tests/test_page_layout_format_boundary.py
• office/tests/test_page_layout_matrix.py
• office/tests/test_page_layout_omission.py
• office/tests/test_page_layout_ooxml.py
• office/tests/test_page_layout_preflight.py
• office/tests/test_page_layout_structural_fidelity.py
• src/docxPageLayoutDocumentation.test.ts

---

📝 Walkthrough

Walkthrough

선택적 page_layout 계약을 DOCX 요청에 추가했습니다. 런타임은 입력을 검증하고 단일 섹션 DOCX에 레이아웃을 적용합니다. 스키마, 출력 충실도, 오류 처리, 문서 상태와 롤백 절차를 테스트하고 문서화했습니다.

Changes

DOCX 페이지 레이아웃

Layer / File(s)	Summary
계약과 상태 문서 docs/TRACEABILITY.md, docs/adr/..., docs/doctoring/..., docs/docx-page-layout.md, src/docxPageLayoutDocumentation.test.ts	A4 또는 Letter 용지, 세로 또는 가로 방향, 0~100mm 정수 여백을 사용하는 단일 섹션 DOCX 계약을 문서화했습니다. 기능 상태를 Proposed 및 implemented_on_active_pr로 유지합니다.
검증과 DOCX 적용 office/src/inkspan_office/page_layout.py, office/src/inkspan_office/safe_renderer.py, office/src/inkspan_office/schema.json	page_layout을 정규화하고 잘못된 입력과 다중 섹션 문서를 거부합니다. 검증된 레이아웃을 콘텐츠 렌더링 후 DOCX에 적용합니다.
계약 및 경계 검증 office/tests/test_page_layout.py, office/tests/test_page_layout_matrix.py, office/tests/test_page_layout_omission.py, office/tests/test_page_layout_preflight.py, office/tests/test_page_layout_format_boundary.py, office/tests/test_page_layout_error_privacy.py	용지와 방향 조합, 레이아웃 생략, 사전 검증, XLSX/PPTX 거부, 오류 메시지 비공개, 결정성을 검증합니다.
DOCX 출력 충실도 office/tests/test_page_layout_ooxml.py, office/tests/test_page_layout_content_fidelity.py, office/tests/test_page_layout_structural_fidelity.py	OOXML 페이지 속성과 여백을 확인합니다. 페이지 나누기, 메타데이터, 목록, 표, 외부 링크 및 이미지를 검증합니다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• ContextualWisdomLab/inkspan 이슈 140 — 이 PR의 스키마, 렌더러, 검증, 문서 및 테스트 변경이 해당 bounded DOCX page_layout 계약을 구현합니다.

Possibly related PRs

• ContextualWisdomLab/inkspan#75 — 이 PR은 기존 문서 및 추적성 체계에 DOCX 페이지 레이아웃 ADR, 계약 문서 및 상태 추적을 추가합니다.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 64.52% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 제한된 DOCX 페이지 레이아웃 계약을 추가하는 PR의 주요 변경 사항을 정확하고 간결하게 설명합니다.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docx-page-layout

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

@coderabbitai review

Please review the exact current head aa987858e115340ccacf87eac299a386d0796e51. This remains Draft only because protected main is frozen for the 0.6.0 registry operational-acceptance boundary; review findings should still be evaluated against this exact head.

[coderabbitai]

@seonghobae I will review pull request #141 at exact head aa987858e115340ccacf87eac299a386d0796e51. I will evaluate findings against that commit, independent of the frozen protected main boundary.

---

🧠 Learnings used

Learnt from: CR
Repo: ContextualWisdomLab/inkspan PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-08-12T02:31:03.922Z
Learning: Do not infer shipped behavior from conversation history, PR bodies, model output, or predecessor-head evidence. Keep Proposed/Active-PR behavior distinct from implementation on Protected `main`, preserve fail-closed security and deterministic conversion boundaries, and update the smallest affected canonical documents plus tests when a durable contract changes.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cursor]

Review

This is the earliest open ADR 0027 claimant (0027-bounded-docx-page-layout, 2026-08-10). Later lanes #248/#249/#285, #320, and #360 reused 0027 for unrelated decisions.

Keep 0027 here. Do not renumber this record to make room for later collisions. Keep Draft while #118 owns v0.6.0. This comment is not a qualifying independent approval of the page-layout product slice.

  

_{Sent by Cursor Automation: Fix Issues}