llm-wiki/rules/project-readiness-gate.md

# rules/project-readiness-gate — project-note 작성 완성도 게이트

> `rules/` 의 방법론 규칙. project-note(프로젝트 hub) 1개가 **다른 작업의 출발점이 될 만큼 깊고 근거 있는가**를 판정한다.
> 기준선은 `raw/project-notes/ca-skeleton-operational-contract.md` 의 *caliber*(엄격성 수준)이다 — 그 노트의 *내용·섹션 구성을 복제하라는 게 아니다*. 프로젝트마다 내용도 섹션 조직도 다르며, 게이트는 *깊이·근거·분해 수준*만 강제한다.
> `branch-depth-gate`(브랜치 1개 착수 깊이)와 다른 층: 본 게이트는 *프로젝트 hub* 미시 게이트.

## 적용

- 대상: `raw/project-notes/*.md`.
- 실행: `/project-spec <slug> <목표>` 의 **내부 마지막 단계** (독립 `/project-readiness` 커맨드 없음) →
  1. **1차 결정론 검사** `.claude/hooks/wiki_structure_lint.py` (project 모드 — proxy + 링크)
  2. **2차 의미 판정** `project-readiness-auditor` (아래 4축 — 노트와 링크된 소스를 읽고 의미로 판정)
- 본 게이트는 **read-only**. 노트를 편집하지 않으며 판정을 노트에 박지 않는다.

## 왜 결정론 계층이 *섹션명 매칭*이 아닌가

exemplar `ca-skeleton-operational-contract.md` 는 project-template §1~14 가 아니라 계약 특화 자기 구조(§1 목표 … §30 아키텍처 … §33 checklist)를 쓴다. "project-template 섹션 존재"를 강제하면 *exemplar 자신이 탈락*한다. 따라서 1차는 **구조-불가지 proxy**(섹션명 무관, 존재만)만 본다. *깊이/caliber* 는 전적으로 2차 auditor.

## 역할 분담 (결정론 proxy vs 의미)

| | 1차 린터(proxy, 존재) | 2차 감사기(LLM 의미, 깊이) |
|---|---|---|
| R1 문제·성공 구체성 | (해당 proxy 없음) | 측정가능 기준인가, 추상 표현("잘 동작")인가 |
| R2 아키텍처·시퀀스 | `PROJECT_NO_DIAGRAM` (임베디드 다이어그램 0개) | 다이어그램 *존재/placeholder* 여부 + 시퀀스 error path 유무 (컨퍼런스급 ≥95 는 판정 안 함 — `wiki-diagram-reviewer` 권고만) |
| R3 결정 근거성 | 링크 깨짐만 | 기술결정이 대안+외부근거로 뒷받침되나, 맨주장인가 |
| R4 Work Item 분해 | `PROJECT_NO_BRANCH_TABLE` (legacy 명칭; Work Item 표 부재) | 각 Work Item 이 stable ID + valid slug + 측정가능 완료조건 + pinned decision refs 를 가지는가 |

→ 2차 감사기는 **의미만** 본다(존재는 1차가 확인).

## 4축 (R1~R4)

> 축 라벨은 `R1~R4`. branch-depth-gate 와 동일 라벨 체계지만 *대상이 다르다*(branch 1개가 아니라 프로젝트 hub).

| 축 | Pass 조건 | Blocking(Not-ready) 트리거 |
|---|---|---|
| **R1. 문제·성공 구체성** | §문제정의가 구체 시나리오/수치, 성공기준이 측정가능 | 성공기준이 "잘 동작한다" 류 추상 표현뿐 |
| **R2. 아키텍처·시퀀스 깊이** | 아키텍처 다이어그램 **존재**(게이트가 확인하는 것은 *존재*만) + 핵심 시퀀스가 happy+error path | 다이어그램 *완전 부재* / 시퀀스가 happy path 만. ※ `needs-diagram` placeholder(사용자가 작성 예정)는 **Blocking 아님 → Should-fix(`DIAGRAM_PENDING_USER`)**. ※ 컨퍼런스급 `≥95` 는 게이트가 강제 못 함 — 사용자가 `wiki-diagram-reviewer` 별도 실행(아래 R2 ≥95 주) |
| **R3. 결정 근거성** | 각 주요 기술결정이 검토 대안 + 외부근거 wikilink(official/회사블로그) 보유 | 기술결정이 근거 없는 맨주장. ※ `deferred` 표시된 결정(자동조사 6개 bound 초과분)은 **R3 Blocking 면제 → Advisory** (현재 pass 에서 근거 미보유 허용, branch 단계에서 종결) |
| **R4. Work Item 분해 실행가능성** | 각 자식 작업이 `WI-<PROJECT>-NNN` stable ID + naming-conventions 준수 slug + 측정가능 완료조건 + `DEC-...@revision` pinned refs + 유효한 dependency 를 가짐. 결정 *내용*은 Work Item 표에 적지 않음. 표에 **실데이터 row ≥1**(placeholder 만 있으면 미충족) | Work Item Registry 부재 / 실 row 0 / ID·slug·완료조건·decision pin 누락 / 존재하지 않는 dependency |

> **R2 ≥95 주**: 게이트(린터 proxy·auditor)는 다이어그램의 *존재*만 확인하고 *품질 점수(≥95)는 확인하지 못한다* (auditor 는 `Read/Grep/Glob` 만 가져 `wiki-diagram-reviewer` 를 dispatch 못 함). 따라서 "다이어그램이 컨퍼런스급인가"는 **게이트의 Ready 조건이 아니라** 사용자가 `wiki-diagram-reviewer` 를 별도 실행해 확인하는 *권고 단계*다. Ready 판정은 *존재 + error-path 시퀀스*까지만 보장한다.

## 깊이 사다리 (R1~R4 공통)

| 레벨 | 항목이 답하는 것 | 판정 |
|---|---|---|
| **L0 존재** | "섹션이 있다 / 항목이 적혀 있다" | 단독 불충분 |
| **L1 메커니즘** | 어떻게/왜 — 구체 시나리오·메커니즘·근거 링크 | 최소선 |
| **L2 조건·경계** | 언제 적용/제외, 실패/대안, 측정 기준 | Ready 최소선 |
| **L3 검증** | 측정값·다이어그램 점수·검증 등급 근거 | 가산점 |

## 판정 규칙

- 심각도 3단계: `Blocking`(Not-ready) · `Should-fix`(권고) · `Advisory`(참고).
- **Ready = 4축 모두 L2+ (Blocking 0).** 이것이 "ca-skeleton caliber" 의 조작적 정의. Should-fix 가 남아도 사용자 "감수" 선언 시 진행 가능(리포트에 기록).
- 모든 finding 은 4종 세트로 근거화: `심각도 · 위치(섹션/행) · 예상 문제("이 hub 를 출발점 삼는 다음 작업자가 여기서 ___를 되묻게 됨") · 채울 방법`. 근거 없는 지적 금지.
- **세션 내 해소 불가 Blocking 의 탈출 (무한루프 방지)**: 일부 Blocking 은 *사용자 행동*으로만 해소된다(아키텍처 `.drawio` 작성, 사용자 소유 결정 입력). 이런 항목은 게이트·오케스트레이터가 **무한 재시도하지 않는다**. 판정을 `Ready-pending-user` 로 내고, *정확히 어떤 사용자 행동이 무엇을 unblock 하는지* 한 줄로 보고한 뒤 **깨끗이 종료**한다. 자동 루프백은 *자동으로 채울 수 있는* Blocking(근거 보강·시퀀스 error path 추가 등)에만 적용하며, **루프 천장 = 2회**(2회 후에도 동일 Blocking 잔존 시 종료+보고). `DIAGRAM_PENDING_USER`·사용자 소유 결정 미입력은 자동 루프 대상이 아니다.

## 명명된 실패 모드

- `ABSTRACT_SUCCESS_CRITERION` (R1): 성공기준이 측정 불가 추상 표현.
- `DIAGRAM_MISSING_OR_WEAK` (R2, **Blocking**): 아키텍처 다이어그램 *완전 부재*. (※ ≥95 품질 미달은 게이트가 판정 안 함 — R2 ≥95 주 참조.)
- `DIAGRAM_PENDING_USER` (R2, **Should-fix**): `needs-diagram` placeholder 존재(사용자 작성 예정). 자동 루프 대상 아님 → `Ready-pending-user`.
- `HAPPY_PATH_ONLY_SEQUENCE` (R2): 시퀀스에 error path 없음.
- `UNSOURCED_TECH_DECISION` (R3): 기술결정에 대안·외부근거 없음. (※ `deferred` 표시 결정은 면제 → Advisory.)
- `BRANCH_DECOMP_INCOMPLETE` (R4): 분해표 부재 / 실 row 0(placeholder 만) / slug·목표조건 누락.

### v2 project contract 실패 모드

- `MISSING_PROJECT_BINDING` (R4, Blocking): project 직접 자식 branch 의 `project` 또는 `work_item` binding 이 없거나, Work Item Registry 의 project/branch row 와 일치하지 않음.
- `MISSING_INHERITED_DECISION` (R4, Blocking): Work Item 의 `Applies Decisions` 에 있는 pinned ref 가 branch frontmatter `inherits` 또는 Branch Contract Packet 에 없음.
- `STALE_INHERITANCE_REVISION` (R4, Blocking): branch 가 pin 한 `DEC-...@revision` 이 project registry 의 현재 revision 보다 오래되었고 명시적 migration/override 상태도 없음.
- `CONFLICTS_WITH_PROJECT_DECISION` (R4, Blocking): branch-local 결정 또는 구현 계약이 inherited project decision 과 양립하지 않는데 승인된 override 가 없음.
- `UNDECLARED_OVERRIDE` (R4, Blocking): branch 가 project 결정을 다르게 적용하면서 frontmatter `overrides` 와 `Declared Overrides` 표에 같은 pinned ref·이유·승인을 선언하지 않음.
- `MISSING_EXPECTED_EDGE` (R4, Blocking): Work Item 이 요구하는 project→branch, WI dependency, decision inheritance edge 중 하나가 실제 branch packet 에 없음.
- `DUPLICATE_DECISION_OWNER` (R3, Blocking): 같은 stable project Decision ID 또는 동일 계약 관심사를 둘 이상의 owner row/document 가 소유함.

## v1 legacy 호환 정책

- active `raw/project-notes/*.md`와 `raw/branch-notes/*.md`는 2026-07-20 migration 이후 v2 graph contract를 필수로 가진다.
- marker/table이 없는 문서는 `raw/archive/` 또는 `vault/90-archive/`에서만 보존하며 graph·structure 전수 검사 대상에서 제외한다.
- 외부 저장소에서 legacy 문서를 다시 가져오면 `LEGACY_PROJECT_CONTRACT` warning으로 식별하되, active 경로로 승격하기 전에 stable Decision/Work Item/Branch ID와 계약 패킷을 부여한다.
- `/project-spec`는 본문 결정을 추측해 변환하지 않고, stable ID 부여가 모호하면 사용자 결정을 요청한다.

## proxy(1차 결정론) — `wiki_structure_lint.py` project 모드

- `PROJECT_NO_DIAGRAM` — 임베디드 다이어그램 0개(`![[....drawio` 임베드도 ```mermaid 블록도 없음). R2 존재 proxy.
- `PROJECT_NO_BRANCH_TABLE` — legacy 코드명. Work Item Registry(또는 legacy Branch 분해표) 부재. R4 존재 proxy.
- `MISSING_FRONTMATTER` — project-template frontmatter 필수 키 누락(기존 검사 재사용).
- C2 링크(BROKEN_LINK 등) — 그대로.

proxy 는 *존재* 만 본다. 임베디드 다이어그램이 컨퍼런스급인지, 분해표 row 가 측정가능한지는 2차 auditor 가 판정한다.