feat(conversion): establish provider-neutral Office adapter contract

.github/workflows/ci.yml

@@ -3,8 +3,9 @@ name: CI
 on:
   push:
     branches: [main]
-  pull_request:
-    branches: [main]
+  # Every pull request target, including immutable stack branches, receives the
+  # same exact-head, synthetic-merge, and buyer-readiness acceptance evidence.
+  pull_request: {}
 
 permissions:
   contents: read
@@ -17,14 +18,87 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact checked-out revision
+        env:
+          EXPECTED_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
       - name: Use preinstalled Temurin JDK 21
         # Uses the runner image's bundled JDK instead of actions/setup-java to
         # keep every workflow dependency hash-pinned (Scorecard Pinned-Dependencies).
         run: |
           echo "JAVA_HOME=$JAVA_HOME_21_X64" >> "$GITHUB_ENV"
           echo "$JAVA_HOME_21_X64/bin" >> "$GITHUB_PATH"
-      - name: Run tests
-        run: mvn -B --no-transfer-progress test
+      - name: Run tests and coverage acceptance gates
+        shell: bash
+        run: |
+          if ! mvn -B --no-transfer-progress verify; then
+            if [[ -f target/site/jacoco/jacoco.csv ]]; then
+              echo "::group::JaCoCo CSV diagnostics"
+              cat target/site/jacoco/jacoco.csv
+              echo "::endgroup::"
+            fi
+            if [[ -f target/site/jacoco/jacoco.xml ]]; then
+              echo "::group::JaCoCo uncovered line diagnostics"
+              python3 - <<'PY'
+          import xml.etree.ElementTree as ET
+          from pathlib import Path
+
+          report = Path("target/site/jacoco/jacoco.xml")
+          root = ET.parse(report).getroot()
+          gaps = []
+          for package in root.findall("package"):
+              package_name = package.get("name", "")
+              for source_file in package.findall("sourcefile"):
+                  source_name = source_file.get("name", "")
+                  source_path = f"{package_name}/{source_name}" if package_name else source_name
+                  for line in source_file.findall("line"):
+                      missed_instructions = int(line.get("mi", "0"))
+                      missed_branches = int(line.get("mb", "0"))
+                      if missed_instructions or missed_branches:
+                          gaps.append(
+                              (
+                                  source_path,
+                                  int(line.get("nr", "0")),
+                                  missed_instructions,
+                                  missed_branches,
+                              )
+                          )
+
+          for source_path, line_number, missed_instructions, missed_branches in gaps:
+              print(
+                  f"{source_path}:{line_number}: "
+                  f"missed_instructions={missed_instructions} "
+                  f"missed_branches={missed_branches}"
+              )
+          PY
+              echo "::endgroup::"
+            fi
+            exit 1
+          fi
+          python3 scripts/verify_maven_test_reports.py
+
+  merge-compatibility:
+    name: Maven merge compatibility
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - name: Verify merge revision
+        env:
+          EXPECTED_SHA: ${{ github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
+      - name: Use preinstalled Temurin JDK 21
+        run: |
+          echo "JAVA_HOME=$JAVA_HOME_21_X64" >> "$GITHUB_ENV"
+          echo "$JAVA_HOME_21_X64/bin" >> "$GITHUB_PATH"
+      - name: Verify merged result
+        run: |
+          mvn -B --no-transfer-progress verify
+          python3 scripts/verify_maven_test_reports.py
 
   script-checks:
     name: Buyer-readiness script tests
@@ -33,6 +107,11 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Verify exact checked-out revision
+        env:
+          EXPECTED_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.12'

.github/workflows/fuzz.yml

@@ -45,6 +45,14 @@ jobs:
           - TenantClaimsFuzzTest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Verify exact checked-out revision
+        env:
+          EXPECTED_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$EXPECTED_SHA"
 
       - name: Set up JDK 21
         uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961

AGENTS.md

@@ -7,10 +7,19 @@ including mandatory quality and security merge gates.
 
 ## Mandatory merge gates
 
-- `mvn -DskipTests compile` must pass with warning/deprecated budget = 0.
-- `mvn test` must pass.
-- JaCoCo coverage for production package must remain 100% line/branch.
-- JavaDoc gate must pass (`mvn -q -DskipTests javadoc:javadoc`) with no warnings/errors.
+- `mvn -B --no-transfer-progress verify` is the authoritative local and CI
+  acceptance command. Do not substitute `compile`, `test`, or a predecessor
+  head result for this exact-head lifecycle.
+- Java 21 compilation must pass with warning and deprecation budget = 0.
+- Every test must pass with zero failures, errors, and skips.
+- JaCoCo coverage for the `com.clearfolio.viewer.*` production package must
+  remain 100% statement/line and branch coverage, expressed as zero missed
+  production lines and branches.
+- The verify lifecycle must generate public Javadocs with Maven Javadoc Plugin
+  3.12.0, `doclint=all`, `failOnError=true`, and `failOnWarnings=true`. Public
+  record components, constructors, methods, enum values, fields, parameters,
+  return values, and thrown failures must be understandable without reading the
+  implementation.
 - Markdown lint for changed docs must pass.
 - Security evidence must be attached on PR (SAST/code-scanning checks).
 - CodeQL Java/Kotlin analysis must remain enabled through repository default
@@ -31,10 +40,15 @@ including mandatory quality and security merge gates.
   `python3 scripts/summarize_buyer_readiness.py --manifest docs/diligence/2026-07-03-buyer-data-room-manifest.json --output docs/diligence/2026-07-03-buyer-readiness-scorecard.md --summary docs/qa/evidence/2026-07-02-krw2b-sale-readiness/buyer-readiness-scorecard-summary.json --check`.
 - Figma Slides generation payload check must pass:
   `python3 scripts/check_figma_deck_payload.py --payload docs/design/2026-07-03-buyer-diligence-slides-generation-payload.json --summary docs/qa/evidence/2026-07-02-krw2b-sale-readiness/figma-deck-payload-check.json`.
-- `mvn test` includes `DependencyPolicyTest`, which prevents reintroducing the
-  broad `tika-parsers-standard-package`, default Logback starter, or excluded
-  Jakarta annotation dependency unless a future PR updates the license policy,
-  SBOM evidence, attribution package, and buyer diligence docs together.
+- `mvn verify` includes `DependencyPolicyTest`, which prevents reintroducing the
+  broad `tika-parsers-standard-package`, default Logback starter, excluded
+  Jakarta annotation dependency, an unreviewed Netty version, or a weakened
+  public-Javadoc gate unless a future PR updates the corresponding security,
+  license, SBOM, attribution, acceptance, and buyer-diligence evidence together.
+- CI, Security Scan, SAST Semgrep, every fuzz target, required organization
+  reviews, and branch protection must all pass on the exact current PR head.
+  Queued, pending, cancelled, skipped-required, stale-head, or predecessor-head
+  evidence is not passing.
 
 ## Change management rule
 
@@ -58,7 +72,7 @@ Codex, Cursor, opencode, …) working in this repo.
   then **remediate**:
   - This is a Maven / Spring Boot app — findings are almost always vulnerable
     Java dependencies. Fix by bumping the offending artifact (or its managed
-    version) in `pom.xml`; re-run `mvn -DskipTests compile` and `mvn test`.
+    version) in `pom.xml`; re-run `mvn -B --no-transfer-progress verify`.
   - There is currently no `Dockerfile` or k8s manifest here; if one is added,
     trivy will also flag image/IaC misconfigs — fix those at the source.
   - For a genuine false positive only, add a narrow, **documented**
@@ -108,11 +122,11 @@ Codex, Cursor, opencode, …) working in this repo.
   DOM-decomposes emails and files into a persisted knowledge graph. Each
   component is a standalone program that must ALSO work as a git submodule of
   the hub, grown separately and together.
-- Sibling components: **waf-ids-ai-soc** (WAF / IDS / AI SOC / LB / APIM),
+- Sibling components: **wardnet** (WAF / IDS / AI SOC / LB / APIM),
   **pg-erd-cloud** (ERD tool), **contextual-orchestrator** (LLM
   cost/perf/upstream-LB gateway, beyond LiteLLM), **codec-carver** (STT /
   omni-modal speech-video codec), **fast-mlsirm** (LLM-as-a-Judge calibration +
-  evaluation-item quality, using aFIPC FIPC + kaefa item-fit), **feelanet-adfs**
+  evaluation-item quality, using aFIPC FIPC + kaefa item-fit), **keyverse**
   (passwordless SSO — OIDC/SCIM/ADFS/LDAP/FIDO2/OAuth2.1, eliminate passwords),
   **newsdom-api** (PDF→DOM sidecar), and **semantic-data-portal** (upper
   ontology / catalog / governance plane with its own graph engine).

CHANGELOG.md

@@ -1,27 +1,47 @@
-## [Unreleased]
-### Added
-- **UI UX 개선**: 'Details' 버튼 클릭 시, 작업 상세 정보 로드 중에 사용자가 명시적인 로딩 상태를 확인할 수 있도록 'Loading...' 텍스트와 비활성화 상태를 표시하도록 추가했습니다.
-
-### Changed
-- PDF.js WebJar를 `6.1.200`으로 올리고, Clearfolio가 동일 버전의 `pdf.mjs`와 `pdf.worker.mjs`를 직접 사용해 서명된 same-origin artifact의 첫 페이지를 렌더링하도록 통합했습니다. 패키징·셸 경로·서명된 `artifactToken` 흐름을 회귀 테스트로 고정했습니다.
-
 # Changelog
 
 ## [Unreleased]
 
-### 추가된 기능 (Added)
+### Added
+
+- **UI UX 개선**: 'Details' 버튼 클릭 시, 작업 상세 정보 로드 중에 사용자가 명시적인 로딩 상태를 확인할 수 있도록 'Loading...' 텍스트와 비활성화 상태를 표시하도록 추가했습니다.
 - **관리자용 단건 작업 삭제 및 재시도 API 추가**
   - 특정 변환 작업을 삭제할 수 있는 `DELETE /api/v1/admin/convert/jobs/{jobId}` 엔드포인트를 추가했습니다.
   - 실패(dead-lettered) 상태인 작업을 관리자가 재시도 큐에 등록할 수 있는 `POST /api/v1/admin/convert/jobs/{jobId}/retry` 엔드포인트를 추가했습니다.
-
 - **비동기 버튼 로딩 피드백 및 상태 복원 개선**
-  - KPI 스냅샷 증거를 다시 불러오는 `refreshKpiEvidence` 동작 중에 "Refresh evidence" 버튼을 비활성화하고 "Refreshing..." 이라는 피드백을 제공하여 사용자의 중복 클릭을 방지했습니다.
+  - KPI 스냅샷 증거를 다시 불러오는 `refreshKpiEvidence` 동작 중에 "Refresh evidence" 버튼을 비활성화하고 "Refreshing..."이라는 피드백을 제공하여 사용자의 중복 클릭을 방지했습니다.
   - 버튼 상태 변경 시 내부 DOM 구조를 보존하기 위해 `Array.from(button.childNodes)`로 원래 노드를 저장하고, 성공 및 실패 후 `finally` 블록에서 `replaceChildren(...)`으로 안전하게 복원하도록 구현했습니다.
 
+### Changed
+
+- PDF.js WebJar를 `6.1.200`으로 올리고, Clearfolio가 동일 버전의 `pdf.mjs`와 `pdf.worker.mjs`를 직접 사용해 서명된 same-origin artifact의 첫 페이지를 렌더링하도록 통합했습니다. 패키징·셸 경로·서명된 `artifactToken` 흐름을 회귀 테스트로 고정했습니다.
+- CI가 pull request의 정확한 head SHA를 명시적으로 체크아웃하고 검증하며, 합성 merge revision은 별도 호환성 작업에서 검증하도록 분리했습니다.
+- Maven `verify` 단계에서 JaCoCo production line 및 branch missed count가 각각 0인지 강제하고, 실패 시 누락 위치 진단을 출력하도록 했습니다.
+- Maven `verify` 이후 Surefire 보고서가 존재하고 실행 테스트 수가 1개 이상이며 skipped·failure·error 수가 모두 0인지 검증합니다. Failsafe 보고서가 생성된 경우 동일한 규칙을 적용하며, 보고서 누락·손상·음수 카운트·전체 skip·실패 결과는 exact-head CI와 merge-compatibility 모두에서 fail closed 처리합니다.
+- Maven `verify` 단계에서 Java 21 public Javadocs를 `doclint=all`로 생성하고 warning 또는 error가 하나라도 발생하면 실패하도록 했습니다. 공개 record 구성요소, 생성자, enum 값, 필드와 매개변수 문서를 초보자도 코드 분석 없이 이해할 수 있는 수준으로 보완했습니다.
+- Jazzer fuzzing도 pull request의 정확한 head SHA를 명시적으로 체크아웃하고 검증하도록 강화했습니다.
+- CycloneDX Maven Plugin 2.9.1의 정확한 `outputFormat`/`outputName` 사용자 속성으로 생성한 61개 구성요소 SBOM과 제3자 고지문을 buyer evidence에 반영했습니다. 생성 source head, UTC 시각, artifact/archive/SBOM/attribution 해시, 17개 Netty 구성요소의 purl·bom-ref·dependency-edge 정합성, 로컬 생성 증거와 공유 가능한 데이터룸 증거의 경계를 ADR 및 실행 가능한 drift test로 고정했습니다.
+
+### Security
+
+- `GET /api/v1/convert/jobs/{jobId}/download`가 리소스 조회 전에 전용 `artifact:read` 권한을 검증하고, PDF 저장소 접근 전에 작업의 tenant 소유권을 확인하도록 강화했습니다. `job:read`만으로는 문서 바이트를 읽을 수 없으며, 인증 누락·권한 누락·교차 tenant UUID 접근은 각각 fail closed 처리되고 교차 tenant 요청은 리소스 존재를 숨기는 `404`를 반환합니다.
+- Maven XML 테스트 보고서 검증기는 각 `testsuite`의 `tests`, `skipped`, `failures`, `errors` 속성을 모두 필수 증거로 요구합니다. 누락된 결과 수를 암묵적으로 0으로 간주하지 않고 fail closed 처리하며, 각 속성 누락 회귀 테스트를 추가했습니다.
+- Maven XML 테스트 보고서 검증기는 UTF-8만 허용하고 UTF-8 BOM은 수용하며, NUL 바이트·DTD·엔터티 선언을 파싱 전에 거부합니다. UTF-16 같은 대체 인코딩으로 위험 선언을 바이트 검사에서 숨기는 우회와 외부 엔터티 읽기·엔터티 확장형 서비스 거부를 회귀 테스트로 차단했습니다.
+- Maven XML 테스트 보고서 검증기는 파일당 16 MiB 상한을 적용하고 한 번의 제한된 읽기로 실제 입력 크기를 검증합니다. 테스트 코드가 보고서 파일을 교체하거나 확장해도 크기 사전검사와 파싱 사이의 경쟁 조건을 이용할 수 없습니다.
+- Spring Boot 3.5.16이 관리하던 Netty `4.1.135.Final` 전이 의존성 전체를 Spring Boot의 공식 `netty.version` 속성을 통해 `4.1.136.Final`로 정렬했습니다. 실제 POM을 읽는 회귀 테스트와 보안 ADR을 추가해 개별 Netty 모듈의 혼합 버전 및 향후 무의식적 downgrade를 차단했습니다.
+- 정책 재정의 승인자의 원문 식별자를 감사 로그에서 제거하고, 전용 회전형 키와 도메인 분리를 사용하는 HMAC 기반 `approverFingerprint`로 대체했습니다. 정책 재정의 서명이 비활성화된 경우에만 전용 키 부재를 비상관 `unavailable` 표식으로 표현하며, 원문이나 비키 해시로 폴백하지 않습니다.
+- 정책 재정의 서명 키를 활성화하면서 전용 감사 가명화 키를 누락하면 Spring 시작과 `DefaultDocumentValidationService`의 독립·모듈식 직접 생성을 모두 거부하도록 강화했습니다. 관리자 예외를 승인하면서 승인자별 상관 가능한 감사 증거를 남기지 못하는 구성을 모든 실행 모드에서 fail closed로 차단하고, 두 키의 최소 강도와 용도 분리를 유지합니다.
+- 감사 가명화 키의 소유권, 회전, 보존, 사고 대응 및 GDPR상 가명정보의 개인정보 지위를 문서화하고, 원문 승인자 식별자와 승인 토큰이 로그에 남지 않는 회귀 테스트를 추가했습니다.
+- 경로·쿼리 파라미터 타입 변환 실패 응답에서 사용자가 제출한 거부 값을 고정된 `[redacted]` 표식으로 대체해 오류 응답을 통한 개인정보·비밀값 반사를 차단했습니다. 값이 실제로 없었던 경우에만 `null` 진단을 유지합니다.
+
+### Fixed
+
+- 뷰어 UI의 재시도 버튼 로딩 상태가 내부 DOM을 손상시키지 않고 안전하게 복원되도록 수정했습니다.
 
 ## [0.1.0] - 2026-06-25
 
 ### 추가된 기능 (Added)
+
 - **비동기 버튼 로딩 상태 UX 개선 (Async Button Loading States)**
   - 문서 제출(`submitDocument`), 데모 데이터 로드(`loadDemoData`), 실패 작업 재시도(`retryActiveJob`) 등 비동기 요청을 수행하는 버튼들에 대해 처리 중 명시적인 로딩 상태(Loading, Submitting, Retrying 등)를 추가했습니다.
   - 사용자의 중복 클릭을 방지하기 위해 작업 중에는 버튼이 비활성화되도록 수정했습니다.
@@ -37,9 +57,11 @@
   - 관련 `AdminJobListResponse` DTO 모델과 이를 처리하는 Repository 및 Service 계층의 `findAll`/`getAllJobs` 메서드를 추가했습니다.
 
 ### 테스트 커버리지 (Tests)
+
 - 신규 구현된 Repository, Service, Controller 계층에 대한 유닛 테스트(Unit Tests)를 작성하여 JaCoCo 기준 라인 및 브랜치 커버리지 100%를 달성했습니다.
 
 ### 보안 (Security)
+
 - **의존성 취약점 일괄 정리 (trivy-fs / osv-scan 대응)**: Spring Boot 부모 POM을 `3.5.0`에서 `3.5.16`으로 올려 Spring Framework, Netty, Reactor Netty, logback 관련 다수의 HIGH/MEDIUM 권고를 해소했습니다.
 - Jackson 계열을 `jackson-bom` import로 `2.22.1`에 고정하여 jackson-databind case-insensitive deserialization bypass 권고(GHSA-5jmj-h7xm-6q6v / CVE-2026-54515)를 제거했습니다.
 - Apache Tika 표준 파서를 통해 유입되던 전이 의존성을 `dependencyManagement`로 고정했습니다: junrar `7.6.0`(경로 순회 RCE/파일 쓰기), commons-io `2.20.0`(XmlStreamReader DoS), commons-lang3 `3.18.0`, BouncyCastle `bcprov-jdk18on 1.84` 및 `bcpkix-jdk18on 1.84`(CRITICAL/Medium). 전체 347개 테스트 통과를 확인했습니다.
@@ -48,6 +70,3 @@
 - 루트 `LICENSE`와 Maven license metadata를 추가해 Scorecard License alert가 표준 Apache-2.0 파일을 확인할 수 있게 했습니다.
 - logback-core 신규 권고(GHSA-jhq6-gfmj-v8fx) 대응을 위해 Logback 관리 버전을 `1.5.35`로 고정했습니다.
 - 저장소 보안 정책, Maven/GitHub Actions Dependabot 설정, 기본 CodeQL/중앙 SAST 운영 지침, 다운로드 파일명 정규화 Jazzer fuzz target을 추가해 Scorecard 보안 거버넌스 신호를 보강했습니다.
-
-### Fixed
-- 뷰어 UI의 재시도 버튼 로딩 상태가 내부 DOM을 손상시키지 않고 안전하게 복원되도록 수정