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 가 판정한다.

9.7 KiB Raw Blame History