# 09 · 운영 지식 포착을 위한 개선안 (2026-08-11)

> **성격**: 제안. 확정 규약이 아니다. `05-final-spec.md` 는 정본이며 이 문서가 그것을 바꾸지 않는다.
> **선행**: 사실 대조 `07-domain-knowledge-gap.md` · 원인 `08-operational-blindspot-causes.md`.
> **제약 준수**: 우산 PRD §핵심 제약 6("배타 소유 경로 밖을 쓰지 않는다") 때문에 아래 제안은 전부
> **소유 PRD 를 명시**하고, 이 문서는 어떤 산출물도 직접 고치지 않는다.
> **사용자 결정 필요 항목은 `[사용자]` 로 표시**한다.

---

## 개선 1 · `planning/` 등급 재판정 — **확정 (2026-08-11)**

> **결정.** 등급 X → **L(legacy 참고)**. 사용자 확정: *"legacy 파일임을 인지하고 최소한의 규격만 판단"*.
> **아래 원 제안(A- · 코드 일치 시 본문 수록)보다 좁게 확정됐다** — L 은 **값 인용을 금지**하고
> 용어 존재·구조 축·질문 초안 입력에만 쓴다. 값은 전부 코드에서 재확인한다.
> 규약 정본: `05-final-spec.md` §6-4. `extraction-manifest.yaml` 의 제외 규칙은 **유지**
> (열람 권한만 바뀌었고 추출 대상은 그대로 → version 불변, 인덱스 재생성 없음).
> 원 제안은 판단 경위로 남긴다.

### 원 제안 (기록)

`05-final-spec.md` §2 등급표에서 `planning/` 을 **X(참조 금지)** 에서 **A-(기획 서술, 단독 근거 금지,
신선도 미검증)** 으로 재판정한다. 사용 방식은 **대조 전용**으로 한정한다.

```
planning/ 문서에서 발견한 진술 P 에 대해
  코드에 P 를 지지하는 근거가 있다        → 본문 수록. evidence: [A-planning, S-*]  (제약 #3 충족)
  코드에 P 를 반박하는 근거가 있다        → findings 에 갭으로 기록. 코드 쪽을 본문에 씀
  코드에 아무 근거도 없다                 → 본문 금지. term-requests 또는 90-history 후보로만
```

**planning 단독으로는 어떤 정책도 선언하지 않는다.** 제약 #3(근거 2중화)이 그대로 방어선이 된다.

### 근거

- 두 저장소 모두 HEAD 추적·clean. "의도 삭제"라는 배제 사유가 저장소 상태와 불일치(`08` 원인 1)
- `서비스정책_사용자.md` 310행 · `서비스정책_관리자.md` 278행이 사용자 제공 글의 상위집합
- 그 문서들이 이미 **기획 의도 vs 코드 구현 갭**을 명시한다(환불 수수료 예) — 우산 PRD 가 문제로
  삼은 "why 소실"의 직접 해답

### 반대 논거와 처리

| 반대 | 처리 |
|---|---|
| 낡았을 수 있다 | 그래서 A- 이고 대조 전용이다. `06-access-model-findings.md` §3-1 이 이미 "제공 덤프가 stg 보다 뒤처짐"을 겪었다. 같은 취급이면 된다 |
| 사용자가 배제를 지시했다 | **지시는 유효하다.** 다만 근거로 적힌 사실이 다르므로 재확인이 필요하다. 이 항목이 `[사용자]` 인 이유 |
| 문서화 작업 자체가 planning 대체가 목적이었다면 자기참조 | 대조 전용이면 자기참조가 아니다. 오히려 "planning 의 어느 진술이 지금도 참인가"를 판정하는 것이 대체의 실질이다 |

### 소유 · 비용

`00-protocol`(manifest `exclude_pathspec`/`exclude_glob` 에서 `planning/` 제거 또는 별도 축 신설) +
`05-final-spec.md` §0·§2 정정. **manifest 개정은 version 을 올리고 인덱스 재생성을 유발한다**
(우산 PRD Risk "manifest 동결 후 규약 변경"). 비용이 실재하므로 아래 개선 3과 **묶어서 한 번에** 올릴 것.

---

## 개선 2 · 소스 등급 신설 — **확정 (2026-08-11)**, 단 P 는 채택하지 않음

> **결정.** 원안의 **P(기획 서술, 코드 일치 시 본문 수록)는 채택하지 않는다** — 개선 1 이 값 인용을
> 금지하는 방향으로 좁게 확정됐으므로 "본문 수록 가능한 기획 등급"은 성립하지 않는다.
> 대신 `05-final-spec.md` §2 에 **L · U 2행만** 추가했다.

| 등급 | 소스 | 신뢰 조건 |
|---|---|---|
| **L** | `planning/**` (legacy) | 본문 인용 금지 · **값 인용 금지.** 용어 존재·구조 축·질문 초안 입력 전용. §6-4 |
| **U** | 유지보수자 구술 (`10-user-oral-source.md`) | **정책 본문 금지.** `90-history/00-origin.md` · glossary `출처: 구술` 항목 전용 |

L·U 는 근거 2중화(제약 #3)의 **근거 수에 들어가지 않는다.** 값을 못 쓰므로 애초에 근거가 되지 못한다.
기존 S~X 가 **매체**로 나뉘는 반면 L·U 는 **검증 가능성**으로 나뉜다 — 축이 섞이지만 실제 구분선이
거기이므로 억지로 맞추지 않았다.

### 소유

`00-protocol`(spec §2 는 `05-final-spec.md` 소유이나 실사용 규약은 `template-config.yaml` 이 참조).
`evidence:` 프론트매터 허용값 목록에 **`U-oral` 만** 추가 → `lint-docs.mjs` 검증 목록 갱신
(`doc-template-kit` 소관). **`L-planning` 은 만들지 않는다** — L 은 값을 못 쓰므로 근거로 표기될 일이
없고, 표기 가능하게 만들면 곧바로 근거로 세게 된다.

---

## 개선 3 · 주석 분류에 정의 축 추가 — 비용 대비 효과 최대

### 제안

`comment_rules.classification` 에 6번째 클래스와 **별도 플래그**를 신설한다.

```yaml
comment_rules:
  classification:
    1_policy:     [...]                 # 기존
    2_rationale:  [...]                 # 기존
    6_definition:                       # 신설 — 정의·관계·목적 서술
      # 정의문 신호
      - ["란", "이란", "라 함은", "일명", "약칭", "즉", "개념", "정의"]
      # 관계문 신호
      - ["단위", "소속", "상위", "하위", "귀속", "매핑", "대응", "별", "당"]
      # 목적문 신호
      - ["위해", "위한", "용도", "목적", "역할", "담당", "책임"]
    3_impl:  null
  flags:
    policy_candidate:   [1_policy, 2_rationale]           # 기존 동작 유지
    glossary_candidate: [6_definition, 1_policy]          # 신설 — 용어 문서 입력
```

**`policy_candidate` 의 정의는 건드리지 않는다.** 기존 산출물(1,370건)의 재현성이 깨지지 않는다 —
`glossary_candidate` 는 새 열이고, 재실행 시 기존 열은 같은 값이 나온다.

### 기대 효과 (실측 근거)

현재 `3_impl` 로 버려지는 10,927 블록 안에 다음이 들어 있다:

```
configuration.ts:21   "심평원 '내가 먹는약 한눈에' API URL"        → 6_definition
configuration.ts:77   "자체 스크래퍼 엔진(scraper-engine) 베이스 URL. 미설정/풀 미등록 시
                       'inhouse' 공급자는 비활성"                  → 6_definition + 1_policy
treat-queue:161       "공급자 풀 전체 여유 슬롯 수 = Σ max(0, maxFlows − inflight)"  → 6_definition
```

용어별 현재 유실률 75~93%(`08` 원인 3)의 상당 부분이 정의문이다.

### 검증 방법

키워드 목록은 **책상에서 확정하지 않는다** — `06-access-model-findings.md` §3-1 이 메뉴 정규식에서
같은 실수를 했다. 절차:

1. `3_impl` 10,927 블록에서 무작위 200 블록 표본 추출(seed 고정)
2. 사람이 `6_definition` 여부를 라벨링
3. 위 키워드 목록의 precision/recall 측정 → 목록 조정
4. 확정 후 전수 재분류. `verify/` 의 golden 갱신

### 소유 · 비용

`00-protocol`(manifest) + `10-index-git`(comments 추출기 `extract-comments.mjs`).
**개선 1 과 같은 manifest 개정 사이클에 묶는다.**

---

## 개선 4 · `docs/00-service-overview.md` 신설

### 제안

`05-final-spec.md` §4 docs 트리 최상단에 문서 1개 추가. **`00-protocol` 배타 소유**
(이미 `docs/00-index.md` 를 소유하므로 경로표 변경 없이 확장 가능).

```
docs/
  00-index.md                 (기존) 읽는 순서 · 상태 범례
  00-service-overview.md      (신설)
```

내용 골격 — **전부 `## 정책 (기획)` 성격이므로 `policy-doc@1` 을 씌우지 않는다.**
`90-history/**` · `99-deprecated/**` 와 같은 lint 예외로 둔다(우산 PRD 제약 #7 예외 조항 확장).

```
1. 서비스 정의        무엇을 수집해 무엇으로 가공해 누구에게 제공하는가
2. 가치 사슬          심평원/벤더 → 수집 → 정규화 → 제공. 각 단계의 코드 소재 링크
3. 제공 단위 3종      채널 / 기업 / 고객사 — 각각의 계약·과금·데이터 범위 (개선 5 와 연결)
4. 참여자 지도        FC · GA · 영업대리점 · 기업 · 조직 · 회원고객 · B2C 고객
5. 이 문서가 답하지 않는 것   권한 판정 → 02-access, 한도 → 04-limits ...
```

### 왜 glossary 로 대신할 수 없는가

`01-glossary.md` 는 **용어 → 정의** 사전이다. "채널·기업·고객사가 하나의 축을 이룬다"는 것은 항목이
아니라 **구조**이므로 사전에 담기지 않는다. 그리고 `20-foundation-access` 는 문서 8종 상한을 지키고
있어 여기에 6번째 문서를 밀어 넣으면 그 PRD 의 MVP 경계가 흔들린다.

---

## 개선 5 · glossary 를 2축으로 구성

### 제안

`01-glossary.md` 의 Open Question("코드 심볼 전부인가 기획 용어만인가")에 대한 답:
**둘 다이되 표를 나눈다.**

```markdown
## A. actor 축 — 시스템에 로그인하는 주체
| 용어 | 코드 심볼 | 로그인 표면 | 관련 문서 |
| admin / sales / corp | @Roles 대상 | 관리자 콘솔 3분할 | 02-access/02 |
| 일반회원(MEM001) / 기업회원(MEM002) | ... | site | 20-site/04 |

## B. 제공 단위 축 — 계약·수익이 귀속되는 주체
| 용어 | 코드 표면 | 계약 소재 | 데이터 범위 | 관련 문서 |
| 영업대리점 / 채널 | modules/sales-agency/** | ... | ... | 30-admin/03 |
| 기업 / 조직 | modules/agency + corp | ... | ... | 30-admin/02 |
| 고객사 | modules/client/** (독립 에러 NS) | client_contract | 분석옵션 + 월 쿼터 | (문서 없음 — 개선 6) |

## C. 코드 심볼 — 02-identifier-namespaces.md 로 링크만
```

A 와 B 가 **교차하지 포함하지 않는다**는 것을 표 2개로 드러내는 것이 이 문서의 핵심 정보다
(`06-access-model-findings.md` 가 actor 3종의 메뉴 모델 차이를 한 문서 3절로 드러낸 것과 같은 방식).

### 소유

`20-foundation-access`(glossary 유일 소유자). Open Question 해소 항목.

---

## 개선 6 · 고객사(client) 축 문서 자리 확보 `[사용자]`

### 사실

`modules/client/{analyze,client,contract,order-detail,settlement}` 5개 하위 모듈 + 내부와 다른
대외 에러 네임스페이스(`resultCode`/`resultMsg`, `S0000`, 기능별 앞 2자리 규약)를 갖는 **대외 API
계약 표면**인데, `05-final-spec.md` §4 의 50문서 어디에도 없다(`10-server/` 8문서 목록 확인).

### 선택지

| 안 | 내용 | 비용 |
|---|---|---|
| A | `10-server/09-client-api.md` 신설 | `50-domain` MVP 18 → 19종. 그 PRD Risk "18개 규모로 완주 실패"(확률 높음)를 악화 |
| B | `03-contracts/05-external-client-api.md` 신설 | `30-contracts-limits` 소관. 대외 계약이라는 성격에 더 맞음 |
| C | 이번 범위에서 제외하고 findings 로만 기록 | 비용 0. 누락은 남음 |

**권고: B.** 고객사 축은 도메인 각론이 아니라 **계약**이다. 내부 E코드와 층이 다르다는 사실
(`07` §4-1)이 그 문서의 첫 절이 된다.

---

## 개선 7 · `onboarding-questions.yaml` 을 코드에서 역산하지 않는다 `[사용자]`

### 제안

`00-protocol` 마일스톤 6 착수 시 **입력 순서를 고정**한다:

```
1) 사용자 구술 (이번 제공 글이 1차 입력)         ← 먼저
2) planning/ 서비스정책 2종의 목차                ← 개선 1 통과 시
3) 코드 인덱스에서 역산한 질문                    ← 마지막
```

3 을 먼저 하면 `08` 원인 6 의 순환이 그대로 재발한다. 1·2 에서 나왔는데 3 에서 답이 안 나오는 질문이
**가장 가치 있는 질문**이다 — 그것이 문서가 존재해야 하는 이유다.

### 질문 집합에 신설할 카테고리

| 카테고리 | 예시 | 왜 필요한가 |
|---|---|---|
| 구조 질문 | "진료정보는 어떤 단위로 제공되는가" | 항목이 아니라 축을 묻는다. 현행 질문 초안 성격상 안 나온다 |
| 역방향 질문 | "대상선정기준은 무엇인가" | `07` §2-3 — **사용자도 모르는데 코드에는 있는** 항목. 문서의 산출 가치를 직접 증명 |
| 부재 확인 질문 | "고객사는 분석을 받는가" | `07` §2-4 — 사용자 인식과 코드가 갈리는 지점 |

---

## 개선 8 · `90-history/00-origin.md` — 구술 전용 문서

### 제안

`60-history-deprecated` 소유. `90-history/` 는 이미 lint 예외이므로 형식 부담이 없다.

```markdown
> 이 문서의 모든 진술은 유지보수자 구술이며 저장소 근거가 없다(등급 U).
> 코드로 검증되지 않는다. 반증이 나오면 이 문서를 고친다.

- 창업 경위 (대표 3인)
- 영업대리점이 추가된 이유 — 수익 분배 / 수익 구조 증설 / 서비스 독점
- 머니(포인트)의 기원 — FAX 호출 과금
- 사용처 확대 지연 — 법적 사유. 타 프로젝트 쿠폰 서비스 연동 예정이었음
```

`10-server/04-settlement-money.md` 와 `30-admin/03-sales-console.md` 의 `## 연혁` 절이 여기로 링크한다.
**정책 본문에는 U등급을 쓰지 않는다** — 왜 있는지를 설명하는 자리에만 쓴다.

---

## 개선 9 · 부수 결함 2건 처리

| 결함 | 근거 | 조치 | 소유 |
|---|---|---|---|
| `E0001` 3중 충돌, 그중 하나는 대외 계약 | `07` §4-1 | `code_namespaces` 에 `client_result_codes` 분리 — `^(S0000\|E[0-9]{4})$` 이되 **소속은 출처(`client.constant.ts`)로 판정**. `findings/11-index-code.md` 발견 9 가 세운 `membership: pattern \| source` 규약을 그대로 적용 | `00-protocol` |
| FAX 머니 차감 경로 이원화 (실동작 + TODO 주석 공존) | `07` §2-2 | `docs/_meta/findings/50-domain.md` 기록. 코드 수정은 우산 PRD Out of scope | `50-domain` |

---

## 실행 상태 (2026-08-11 갱신)

```
[완료 — 이 세션]
  개선 1  planning 등급 X → L                spec §0 · §2 · §6-4 · manifest 주석 · 우산 PRD
  개선 2  등급 U 신설 (P 는 미채택)           spec §2
  개선 6  고객사 문서 위치 = 안 B              30-contracts-limits PRD
  개선 7  질문 입력 순서 고정                  00-protocol PRD M6
  개선 4  00-service-overview.md 소유 확정     00-protocol PRD
  개선 5  glossary 2축                        20-foundation-access PRD Open Question 해소
  개선 8  90-history/00-origin.md             60-history-deprecated PRD
          구술 원본 보존                       10-user-oral-source.md (등급 U)

[backlog — 실행 주체가 해당 PRD 착수 시]
  개선 3  주석 6_definition 축 + glossary_candidate 열   10-index-git + 00-protocol
  개선 9  client_result_codes namespace 분리             00-protocol
  (신규)  verify.sh --check 가 현재 exit 1               00-protocol  ← 아래 참조
```

**manifest `version` 은 올리지 않았다.** 재판정이 바꾼 것은 열람 권한이고 `exclude_*` 규칙은
그대로이므로 산출 수치가 불변이다. 인덱스 재생성·golden 갱신 불필요. 실측 확인:

```
verify.sh --check  →  HEAD 원본 manifest 와 편집본이 출력 바이트 일치 (diff 빈 출력)
```

**단 그 출력은 exit 1 이다 — 편집 전부터.** 증상은 `verify.sh` 가 `repos:` 블록 밖의 `path:` 까지
집계해 `extraction-manifest.yaml:320`(`reproduce.runtime_scale_oracle.path`)을 4번째 저장소로 잡는
것이다(정상은 `:54,59,64` 3행).

> **원인 정정 (2026-08-11, 최초 진단 철회).** 이것은 고쳐야 할 코드 결함이 **아니다. 머지 비대칭**이다.
>
> | | main | `feat/insuniverse-docs-00-protocol-m3-recheck` |
> |---|---|---|
> | `extraction-manifest.yaml` | **v8** (runtime 축 `bdd05bc` 로 `path:` 4번째 도입) | 구버전 (`path:` 3행) |
> | `verify.sh` | **605행** — 미스코프 파서 `:204` | **2,764행** — `:206` 섹션 절단 + `:2687` selftest 불변식 6 |
>
> 두 축이 각자 정상인데 **main 이 신 manifest + 구 파서라는 조합을 들고 있다.** 파서 수정은 이미
> 프로토콜 브랜치에 있고 selftest 가 그 불변식을 지키고 있다("repos 섹션 밖의 name/path/head
> 3행은 저장소가 아니다").
>
> **사용자 지시 (2026-08-11): `00-protocol` 의 main 머지가 완료되면 검토한다. 그 전에는 손대지
> 않는다.** 머지가 파서를 가져오므로 별도 수정이 불필요할 가능성이 높고, 지금 main 에서 고치면
> 머지 시 충돌하거나 프로토콜 축의 selftest 와 어긋난 두 번째 구현이 된다.
>
> 머지 후 남는 것은 `lint.files 0 — 검사 대상 없음`(문서 산출 0건)뿐이며, 이는 스크립트가 스스로
> 안내하는 정상 상태다 — 마일스톤 3~6 동안 `--bootstrap` 으로 한시 통과시킨다.

**그동안 제약 #7 은 강제되지 않는다.** 문서 PRD 착수 전에 머지가 선행돼야 하는 실질적 이유다.

**개선 3 이 남은 것 중 실익이 가장 크다.** manifest 개정 없이 추출기 열 추가만으로 검증 가능하고,
기존 `policy_candidate` 1,370 의 재현성을 깨지 않는다.

---

## 이 분석 자체의 한계

- `planning/` 문서는 **목차와 3개 절만** 열람했다. 전문 대조는 하지 않았다 — 참조 금지 규약이
  아직 유효하므로 진단에 필요한 최소한만 확인했다. 등급 재판정이 승인되면 전문 대조가 별도로 필요하다.
- "기업구독 변경 불가" 등 사용자 진술 일부는 **금지를 강제하는 코드 지점을 찾지 못했다**(`07` §1-2).
  부재 증명이 아니라 미탐색이다.
- 주석 분류 개선(개선 3)의 기대 효과는 **표본 라벨링 전 추정**이다. 검증 절차를 같이 적은 이유다.
- `docs/` 산출이 0건이므로 "문서가 이 내용을 담지 못한다"는 판정은 **계획서 기준**이다. 실제 문서가
  나오면 작성자가 계획 밖의 서술을 넣을 수도 있다 — 다만 그것은 규약이 보장하는 바가 아니다.