# Semantic Editorial Pass — 진행 기록

**현재 상태: COMPLETE**

:::warning

이 문서는 작업 로그다. 아래 여러 절은 **작업 당시의 incremental progress snapshot** 이다.
`진행 중` 표기, 중간 count, 이전 audit 결과는 historical record 이며 현재 상태를 뜻하지 않는다.
예를 들어 `state-machines-and-ownership — 78/119 (진행 중)` 은 그 시점의 값이고, 그 topic 은
CONCEPT 386건 완료 시점에 끝났다.

정본은 두 곳이다.

- 이 문서 하단의 `Correction pass` 절
- `_meta/editorial/final-editorial-validation-2026-09-01.md` — 최종 검증 수치

:::

시작 2026-09-01. 대상 949 records. 우선순위 CONCEPT -> CASE -> REFERENCE/QUESTION/DECISION.

## Historical progress snapshot — 이번 pass 에서 함께 고친 것

- 생성 과정에서 문장이 절 경계에서 잘려 나간 body 를 원본 source anchor 로 복원한다. 말줄임(…)으로 끝난 문장, 목록이 한 줄로 뭉개진 문단, 코드 스팬 중간에서 끊긴 문장이 대상이다.
- 절 제목을 그 문서가 실제로 설명하는 메커니즘·사건·경계 이름으로 바꾼다. 고정 목차를 새로 만들지 않는다.
- 제목이 SSOT 절 머리글(모듈의 정체와 경계, 실패 경로와 복구/번역 등)이거나 분석 번호((8.2) 등)이거나 분석 과정형(Confirmed —)이면 그 문서의 메커니즘 이름으로 바꾼다.
- 그림은 논지에 맞는 visual grammar 로 다시 그리거나, 논지와 무관하면 제거한다.

## Historical progress snapshot — 완료 topic (CONCEPT)

- result-and-failure-algebra — 10/10
- query-and-pagination-models — 6/6
- observability-models — 7/7
- identity-and-value-contracts — 8/8
- capability-and-disclosure-models — 11/11
- security-and-trust-boundaries — 20/20

## Historical progress snapshot — 그림 처리 기록

- 재설계: adapter-inbound-graphql-c10, adapter-outbound-cache-redis-c03, adapter-outbound-support-c02, application-core-c01, messaging-testkit-c04, adapter-inbound-web-c01, adapter-outbound-objectstorage-c01, adapter-outbound-persistence-jpa-c24, grpc-advanced-diagnostics-c02, adapter-inbound-web-c03, adapter-inbound-web-c04, application-core-c02, grpc-advanced-diagnostics-c01, grpc-observability-c01, grpc-spring-boot-starter-c01
- 제거: grpc-core-api-c01(기록의 논지와 다른 그림), app-bootstrap-c01(표로 읽는 것이 명확), adapter-outbound-notification-c04(같음), grpc-advanced-bootstrap-c03(같음)
- admission-budget-and-backpressure — 21/21
- composition-and-lifecycle-models — 26/26
- transaction-and-consistency-models — 27/27
- state-machines-and-ownership — 78/119 (진행 중)

## CONCEPT 386건 완료 (2026-09-01)

- 일반 heading(구조 / 명령이 보여 주는 것 / 어떻게 움직이는가 / 무엇이 불변식인가 / 어디까지가 경계인가 / 왜 그렇게 되나 / 무엇이 남는가 / 실패하면 어떤 상태가 되는가 / 근거 절 원문)을 남긴 CONCEPT body 0건.
- audit_corpus_structure.py concept: bodies=386 findings=0.
- state.json 과 frontmatter/H1 사이 title 불일치 132건을 state.json 쪽(보호 대상 식별자가 살아 있는 쪽)으로 정본화. 단 test-names-that-assert-what-their-bodies-do-not 은 본문이 네 사례를 열거하므로 "테스트 넷" 으로 확정하고 state.json 을 고쳤다.
- diagram 217 → 181. 제거 36건은 (a) 내용이 목록/표라서 그림이 정보를 더하지 않는 경우, (b) alt 가 다른 기록의 주장을 그리고 있던 경우다.
- CASE 402건은 ca0..ca30 청크로 진행한다.

## CASE 402건 완료 (2026-09-01)
- ca0..ca30 청크 전량 편집. 일반 heading 잔존 0건.
- audit_corpus_structure.py case: bodies=402 findings=0.
- CASE 구간에서 diagram 재설계 다수, 제거 다수. 최종 diagram 수는 pass 종료 시 재보고.
- 다음: REFERENCE 105 / OPEN QUESTION 31 / DECISION 25 (본문 파일 없음, record .md 만 편집).

## Semantic editorial pass — 1차 (2026-09-01, 이후 정정됨)

:::warning

아래는 1차 pass 당시의 스냅숏이다. 두 수치가 틀렸고 correction pass 에서 정정했다 —
`20개 이상 문서에서 동일한 문단 = 0` 은 body 만 센 것이고 main record 를 세지 않았으며,
테스트 수는 `test_verify_pipeline` 한 파일만 돈 결과다. 최신 상태는 이 문서 끝의
"Correction pass" 절을 본다.

:::

전체 949건 편집을 마쳤다. `lastEditorialAt` / `lastValidationAt` = `2026-09-01T10:39:26Z`.

### 구조 다양성

| 지표 | 이전 | 이후 |
|---|---|---|
| CONCEPT heading signature | 18 / 386 (4.7%) | 382 / 386 (99.0%) |
| CASE heading signature | 12 / 402 (3.0%) | 400 / 402 (99.5%) |
| CASE 서로 다른 `##` heading | — | 1,191 |
| CONCEPT 서로 다른 `##` heading | — | 1,054 |
| 20개 이상 body 에서 동일한 문단 | 다수 | 0 |
| 20개 이상 main record 에서 동일한 문장 | 측정하지 않음 | 측정하지 않음 — correction pass 가 163건을 찾았다 |

`## 출처` 는 provenance 절이므로 전 기록이 공유한다. 그 다음으로 빈도가 높은 것은
CASE `## 수정` 37건(9.2%), CONCEPT `## 이 기록이 다루는 파일 범위` 34건(8.8%) 이다.
`audit_corpus_structure.py` 의 FIRST_HEADING_DOMINANCE(80%) · LOW_HEADING_SIGNATURE_DIVERSITY(15%)
· REPEATED_BOILERPLATE(20) 세 규칙 모두 findings=0.

### 이번 회차에 마지막으로 처리한 것

- CASE ca29 · ca30 청크 25건. CASE 402건 전량 완료.
- REFERENCE 40건: `목적`/`규칙`/`적용 조건`/`예외`/`근거` 가 전부 boilerplate 였던 기록을
  각 source anchor 의 SSOT finding(사실·근거·왜 문제인가·확인 방법)으로 다시 썼다.
- QUESTION 13건: `미지수`("현재 근거로는 답이 닫히지 않는다")와 `다음 검증` boilerplate 를
  각 기록의 실제 미지수와 확인 방법으로 바꾸고, SSOT 의 후보를 `선택지` 절로 옮겼다.
- `## 원본 판정이 무엇을 적었나` 206건(CASE 186 · CONCEPT 20)을 각 기록이 인용하는
  근거가 무엇을 보여 주는지로 개별 명명했다. 편집 과정에서 이 heading 자체가
  두 번째 template 이 된 것을 계측으로 발견해 되돌린 것이다.
- 제목: LONG_TITLE 후보를 전수 검토했다. 9건을 줄였고 60건은 유지했다.

### 제목 판정

줄인 것 9건.

- `analysis-finding-a03-f003` → `legacy compatibility surface의 제거 조건을 세 가지로 고정한다`
  (다른 두 기록의 `## 관계` 가 이미 이 이름으로 이 규칙을 가리키고 있었다. 끊긴 링크가 붙었다)
- `a05-f003-capabilitysupport-constraints` → `CapabilitySupport.constraints 의 경계가 타입에 없다`
- `analysis-finding-a04-f006` → `cache-redis 와 httpclient 의 support 간선이 죽었는지 확정되지 않았다`
- `a06-f003-change-streams-true`(88자) → 두 절 중 중복(`거부되지 않고`/`조용히 버려지며`)을 뺐다
- `a13-f002-authentication-failed-resumehealthy`(77자) → 한 절로 줄였다
- `analysis-finding-a19-f013`(75자) → 인용 문장을 본문에 남기고 제목은 사건 이름으로 바꿨다
- `a14-f005-publicpaths-restrictedpathrule`(73자) → 뒤 절이 앞 절을 일반어로 반복하고 있었다
- `messaging-nats-experimental-f03`(72자) → 제목에 두 문장이 들어 있었다
- `messaging-kafka-f01`(69자) → 세 절 중 사건을 이루는 두 절만 남겼다

유지한 60건은 길이가 (a) `MessagingPublicSurfaceContractTest` · `GrpcSerializedStreamWriter` 같은
보호 대상 식별자, (b) 사건 자체가 두 사실의 대조인 경우(문서 X · 코드 Y), (c) 열거가 실질인 경우
(`연결 티켓·origin 정책·메시지 권한·연결 예산`)에서 온다. 줄이면 사실이 빠진다.

### 시각 자료

- diagram 217 → 181. 제거 36건은 내용이 목록/표라 그림이 정보를 더하지 않거나,
  alt 가 다른 기록의 주장을 그리고 있던 경우다.
- terminal SVG 788건은 손대지 않았다.
- `validate_svg.py assets/svg --kind diagram` PASS, `assets/terminal --kind terminal` PASS.

### 최종 검증

| 명령 | 결과 |
|---|---|
| `PYTHONPATH=tools python3 -m unittest tools.tests.test_verify_pipeline` | OK (38 tests — 한 파일만. 전체 discover 아님) |
| `python3 tools/verify_pipeline.py /shared` | PASS |
| `audit_korean_tech_writing.py concept` | scanned=772 findings=0 |
| `audit_korean_tech_writing.py case` | scanned=804 findings=60 (LONG_TITLE, 전건 검토 후 유지) |
| `audit_korean_tech_writing.py reference` | scanned=105 findings=0 |
| `audit_korean_tech_writing.py openquestion` | scanned=31 findings=0 |
| `audit_korean_tech_writing.py decision` | scanned=25 findings=0 |
| `audit_corpus_structure.py concept` | bodies=386 findings=0 |
| `audit_corpus_structure.py case` | bodies=402 findings=0 |
| `validate_svg.py assets/svg --kind diagram` | PASS |
| `validate_svg.py assets/terminal --kind terminal` | PASS |
| record/body SHA ↔ `_meta/state.json` | 949건 전건 일치 |

### 남은 editorial warning

CASE LONG_TITLE 60건뿐이다. 위 판정대로 유지 결정이며, 규칙을 다시 적용할 때는
길이가 아니라 "제목이 사건을 이름 짓는가"로 판정한다.

### 편집 중 발견해 고친 사실 오류 하나

`case-an-unselectable-broker-listed-with-features` 의 `## 출처` 가 존재하지 않는 절
`analysis/messaging/messaging-rabbit.md §17` 을 가리키고 있었다. SSOT 를 grep 해
`analysis/19-messaging-platform.md` §6.2 가 그 finding 의 실제 소유자임을 확인하고 고쳤다.

---

# Correction pass (2026-09-01)

독립 재검증에서 나온 결함만 고치고, 같은 형태가 다시 완료 판정을 통과하지 못하도록 validation
contract 를 보강한 회차다. 949건을 다시 쓰지 않았다. `lastEditorialAt` · `lastValidationAt` =
`2026-09-01T11:32:12Z`.

## 1. main record boilerplate 163건

1차 pass 의 audit 은 `*.body.md` 만 glob 했다. main record 는 대상 밖이었고, 그래서 다음 두 문장이
CASE 163건과 158건에 그대로 남아 있었다.

```
확인 방식 : 원본 분석 절의 판정을 옮겼고, 이 기록에 붙은 자산의 명령만 이번 회차에 실행했다
이 노드는 canonical SSOT 의 판정을 그대로 옮긴 것이다. 그 SSOT 의 §16 이 해당 finding 에 대해 실행하지 못한 검증을 소유한다.
```

둘 다 기록이 아니라 생성 파이프라인을 설명하는 문장이다. 163건 전부를 owning SSOT 43개의 §16
(확인하지 못한 것)과 각 기록에 붙은 자산으로 다시 썼다.

- `확인 방식` — 그 기록을 실제로 무엇이 확정했는지. 예: `GrpcAdmissionController 참조 16건 전수
  검색과 두 클래스의 공개 표면 대조`, `HeaderValue 참조 26건 검색과 파서의 종료 지점 탐색 코드
  확인. jshell 리플렉션으로 왕복 손상을 런타임 재현`.
- `확인하지 못한 것` — owning SSOT §16 이 그 finding 에 대해 소유한 실제 미검증 범위. SSOT 가
  그 finding 을 닫아 둔 한 건(`messaging-outbox-jdbc-postgresql-f03`)만 `없음 — …` 으로 적었고,
  읽지 않고 `없음` 을 쓴 기록은 없다.

고정 필드(`## 요약` · `## 문제` · `## 결론` · `## 검증 환경` · `## 재현 조건` ·
`## 확인하지 못한 것`)는 record contract 이므로 건드리지 않았다. 공통 환경값
(`OpenJDK : 21.0.12` · `Gradle : 9.0.0` · `소스 수정 : x`)도 그대로 두었다.

덤으로 같은 형태 하나를 더 찾아 고쳤다 — CASE 5건과 그 body 5건이
`가족 문서의 판정을 옮긴 것이다. 실행 확인은 그 문서의 §확인하지 못한 것이 소유한다.` 를 갖고
있었는데, `analysis/19-messaging-platform.md` 에는 그런 절이 없다. 끊긴 포인터였다.

## 2. corpus audit 의 근본 원인

`audit_corpus_structure.py` 를 두 층으로 나눴다.

| 층 | 대상 | 검사 |
|---|---|---|
| rich body | `*.body.md` | heading signature · 첫 heading 편중 · 반복 문단 |
| main record | `*.md` (body 제외) | **section 내부 설명형 prose 반복만** |

main record 층은 고정 schema heading 을 검사하지 않는다. CASE 의 여섯 절이 100% 같은 것은 계약이
동작하는 것이지 결함이 아니다. 대신 `키 : 값` 줄의 **값이 값인지 설명인지**를 가른다 —
한국어 종결형이 붙거나 문장이 둘 이상이면 설명으로 본다. `21.0.12   java -version 으로 확인` 은
값이고, `원본 분석 절의 판정을 옮겼고 …` 는 설명이다.

`## 관계` · `## 근거 기록` · `## 출처` 아래의 `-` 링크 줄은 대상에서 뺐다. 그 줄은 다른 기록의
제목을 그대로 반복해야 링크가 성립한다 — 참조이지 설명이 아니다. 링크 아래의 설명 줄은 그대로
검사한다.

regression test: `tools/tests/test_main_record_boilerplate.py` 8건.

- 고정 CASE heading 이 100% 같아도 fail 하지 않는다
- 공통 Java/Gradle 값만 같아도 fail 하지 않는다
- 같은 설명 문장이 20개 이상 main record 에 반복되면 fail 한다
- 19건이면 fail 하지 않는다 (threshold 경계)
- 관계 링크 줄은 반복해도 fail 하지 않는다

## 3. 잘못된 evidence reference 4건

owning SSOT 를 다시 읽고 정본으로 고쳤다. 없는 파일을 새로 만들지 않았다.

| 기록 | 잘못된 참조 | 정본 |
|---|---|---|
| `a-resumed-redrive-skips-what-it-could-not-move` | `306-redrive-resume-skips-failed-items.txt` | `306-redrive-resume-skips-unmoved.txt` (EVD-306) |
| `an-authorization-denial-recorded-as-a-configuration-error` | `287-messaging-security-access-path.txt` | `287-messaging-security-duplicate-checks.txt` §C (EVD-287) |
| `blocking-means-startup-fails-and-nothing-runs-it` | `302-messaging-admin-service-unwired.txt` | `302-admin-api-topology-guarantee-unwired.txt` (EVD-302) |
| `the-forgeable-approval-survived-on-the-irreversible-half` | `307-destructive-approval-not-verified.txt` | `308-admin-runtime-api-and-dependency-defects.txt` (EVD-308) |

넷째는 접두사 정정이 아니다. `Approved` 가 `VerifiedApproval` 이 아니라 `AdminApproval` 을 담는다는
사실은 `analysis/messaging/messaging-admin-runtime.md` 의 §14 표에서 EVD-**308** 에 귀속돼 있다
(EVD-307 이 소유하는 것은 구현 0건 쪽이다).

## 4. source/evidence reference validator

`tools/validate_source_references.py` 를 추가하고 `verify_pipeline.py` 의 REQUIRED_PATHS 에 등록했다.

| 참조 형태 | 규칙 |
|---|---|
| `analysis/foo.md` | 파일 존재 |
| `analysis/foo.md#L123` | 파일 존재 + line 범위 유효 |
| `evidence/raw/<full-name>.txt` | **정확히 그 파일** 존재. 접두사가 같은 이웃으로 대체하지 않는다 |
| `evidence/raw/287` | unique prefix 로 정확히 하나에 해석 |

두 evidence 형태를 비대칭으로 둔 것이 이 도구의 요점이다. 전체 파일명을 적은 것은 그 파일에 대한
단언이므로, 없으면 FAIL 이어야 한다. 번호만 적은 shorthand 는 evidence id 를 가리키므로 접두사
해석을 허용한다.

regression test: `tools/tests/test_source_reference_validation.py` 8건 — 이번 네 오류의 형태가
전부 포함돼 있다.

## 5. SVG semantic defect

정상 방향 화살표는 실재하는 관계를 뜻하고, 도착 상자를 빗금 치는 것으로 그 뜻이 뒤집히지 않는다.
33개 후보를 전수 검토해 3건을 재설계하고 30건을 유지했다. 상세는
`_meta/editorial/svg-semantic-review-2026-09-01.md`.

| 판정 | 수 |
|---|---:|
| 재설계 | 3 |
| 유지 — 들어오는 전이는 실재하고 부재는 나가는 쪽 | 3 |
| 유지 — 빗금 상자에 화살표가 닿지 않음 | 2 |
| 유지 — 빗금 상자 없음, 화살표가 전부 실재 흐름 | 25 |

규칙을 `designing-tech-log-visuals` 의 SKILL hard gate · editorial rules · review checklist 세 곳에
명문화하고, 그 셋이 존재하는지 검사하는 테스트를 붙였다.

layout signature 수는 목표로 삼지 않았다. 재설계 3건은 화살표가 기록과 반대를 말했기 때문에
고친 것이고, 나머지 30건은 grammar 가 generic 하다는 이유로 건드리지 않았다.

## 6. SVG 좌표 직렬화

설명용 SVG 40개의 좌표 340개가 소수점 둘 이상을 갖고 있었다. 소수점 한 자리로 정규화했고
(기하 변화 최대 0.05px), 생성기와 `validate_svg.py`(`COORDINATE_PRECISION`) 양쪽에 규칙을 넣었다.
터미널 SVG 는 대상이 아니다 — 원래 정수 좌표만 쓴다.

## 7. cross-scope metadata

`document-detail/.../state.json` 의 `crossScopeAnalysis` 가 재생성 이전 값을 들고 있었다.

```
sha256  481b3728…  →  538e4e72…
lines   428        →  552
```

이것을 놓친 이유는 어떤 verifier 도 기록된 수치를 파일과 대조하지 않았기 때문이다.
`verify_pipeline.py` 에 `_verify_upstream_document_metadata` 를 추가했다 — state.json 안에서 `path`
와 `sha256` 을 함께 가진 모든 블록(crossScopeAnalysis · finalDocument · rootTree · candidateLedger ·
sourceManifest)을 실제 파일과 대조한다. regression test 5건.

## 8. LONG_TITLE 60건

길이만 보고 줄이지 않았다. 네 조건(독립 사건 둘 혼재 · 본문에 내려도 되는 설명 · 같은 뜻 반복 ·
분석 과정 문장)으로 60건을 다시 훑었고 해당하는 것이 없었다. 남은 길이는 보호 대상 식별자
(`MessagingPublicSurfaceContractTest` · `GrpcSerializedStreamWriter`), 사건 자체가 두 사실의 대조인
경우(문서 X · 코드 Y), 열거가 실질인 경우에서 온다.

## 9. 최종 검증 (fresh)

| 항목 | 결과 |
|---|---|
| records 총수 | 949 (CASE 402 · CONCEPT 386 · REFERENCE 105 · QUESTION 31 · DECISION 25) |
| record hash mismatch | 0 |
| body hash mismatch | 0 |
| diagram svg hash mismatch | 0 |
| raw evidence hash mismatch | 0 |
| line count mismatch | 0 |
| invalid source reference | 0 |
| repeated main-record prose | 0 |
| `unittest discover -s tools/tests` | **Ran 80 tests — OK** |
| `verify_pipeline.py /shared` | PASS (required paths 67 · upstream document metadata matches files) |
| `audit_korean_tech_writing.py` (5개 디렉터리 1,737 파일) | findings 60 — 전부 LONG_TITLE |
| `audit_corpus_structure.py concept` | bodies 386 · records 386 · findings 0 |
| `audit_corpus_structure.py case` | bodies 402 · records 402 · findings 0 |
| `audit_corpus_structure.py reference / openquestion / decision` | records 105 / 31 / 25 · findings 0 |
| `validate_svg.py assets/svg --kind diagram` | PASS (181개) |
| `validate_svg.py assets/terminal --kind terminal` | PASS (788개) |
| `validate_source_references.py` (신규) | findings 0 |
| crossScope metadata | 실제 파일과 일치 |

남은 editorial warning 은 CASE LONG_TITLE 60건뿐이며, §8 의 판정대로 유지한다.