# insuniverse-temp 작업 규약

## 0. 경계 규약 — 이 규약 계층이 mccp 와 동화되지 않기 위한 조건

이 문서와 `.claude/templates/plan-kit/` 은 mccp 본체 결함([#127](https://github.com/idenn207/mccp/issues/127) · [#128](https://github.com/idenn207/mccp/issues/128))에 대한 **로컬 임시 방편**이다. 상류가 수용하면 철거한다.

| ID | 경계 | 검사 |
|---|---|---|
| **B1** | mccp 플러그인 파일을 수정하지 않는다. 캐시(`~/.claude/plugins/cache/mccp/`) 수정은 업데이트 시 원복되며, 그 상태에서 본체 개선을 판단하면 틀린다 | `(미검증)` — 저장소 밖이라 `git diff` 사정거리 밖 |
| **B2** | 변경 범위는 `CLAUDE.md` · `.claude/templates/plan-kit/` · `.claude/meta/` · `.claude/PRPs/plans/` 4곳뿐 | 계획서 Validation 블록 |
| **B3** | 계획서 형식은 mccp 템플릿의 **상위집합**이다. mccp 필수 절을 하나도 제거하지 않는다 — 이 계층을 삭제해도 receipt 체인·`plan_hash`·L1 게이트가 그대로 돈다 | 계획서 Validation 블록 |
| **B4** | 철거 조건을 문서에 박는다. 상류 #127·#128 수용 시 이 계층 삭제 | `.claude/templates/plan-kit/README.md` · `.claude/meta/11-review-round-remediation.md` |
| **B5** | 이 계층은 mccp 개선의 **대체재가 아니라 증거**다. 로컬에서 잡히는 결함은 상류 이슈에 실측으로 환류한다 | `(미검증)` — 네트워크 작업 |

**B1 은 이 저장소의 어떤 게이트로도 못 잡는다.** 플러그인 캐시는 저장소 밖이라 `git diff` 에 나타나지 않는다. B1 은 규범이고 위반은 리뷰에서만 잡힌다.

### 리뷰 수용 규약

이 계층을 건드리는 계획은 **의도적으로 mccp 표준을 이탈**한다. mccp loop review(santa-loop · L1/L2 패널 · Codex)가 그런 계획을 칠 때:

- **전제**: 이 계층의 방향은 이미 판정됐다. 리뷰는 방향이 아니라 **구현의 정확성**만 본다.
- **`out_of_scope_observations` 로 분리할 지적** — "mccp 템플릿과 형식이 다르다" · "mccp 가 이미 제공하는 기능이다" · "본체에 제기하라" · "로컬 규약을 늘리지 마라". 전부 전제 부정형이며 blocker 가 아니다.
- **수용할 지적** — 검사가 실제로 안 도는가 · 규칙이 겨냥한 층위를 못 잡는가 · 경계 B1~B4 를 깨는가.

## 1. plan 저작 계약 (`/mccp:plan` 산출물)

mccp 기본 템플릿(`commands/plan.md` §PRD Artifact Output)보다 강한 기준을 쓴다. 이 절이 없으면 santa-loop 라운드가 아래 항목을 대신 저작한다 (실측: 마일스톤당 11~16라운드).

### Task 표

```markdown
### Task 1: {name}
- **Action**: {무엇을 한다}
- **Mirror**: {따를 패턴}
- **Validate**: {정확성을 증명하는 명령}
- **Gate**: `#N` — Validation 블록의 검사 번호
```

- `Gate:` 는 **검사 번호만** 적는다. 산문 서술 금지.
- 대응 검사가 없으면 Task 를 쪼개거나 검사를 먼저 쓴다. `Gate: (없음)` 은 허용하되 그 사실이 Acceptance 에 그대로 실려야 한다.
- **`- **Validate**:` 행을 유지한다.** mccp L1(`l1-check.js` `C4_MISSING_VALIDATE`)이 이 행을 요구하고, 빠지면 계획서당 수 건씩 떨어진다(실측). `Gate:` 는 mccp `Validate:` 의 **대체가 아니라 추가**다 — 이것이 B3 상위집합의 정의다.
- **Files to Change 표 헤더는 `File`, Action 열은 `CREATE`/`UPDATE`/`DELETE` 정확 일치.** L1 은 헤더를 `cells[0] === 'File'` 로만 건너뛰고 Action 도 정확 일치일 때만 존재/부재를 검사한다 — `UPDATE + git add` 처럼 꾸미면 **검사가 조용히 꺼진다**(층위 3). 부연은 Action 열이 아니라 Why 열이나 Task 본문에. 근거 `l1-check.js` `parseFileRows`·`C3`·`C4`.

### Validation 블록

- 블록 머리에 `set -euo pipefail` **필수**. 없으면 `false || { echo x; false; }` 가 메시지만 찍고 스크립트가 계속 간다 — 이 블록의 실패 규약 전체가 무력해진다.
- `grep -c` 는 0건에 exit 1 이다. "0건이 정상" 인 검사는 카운트를 캡처해 비교한다.
- 검사마다 **음성 케이스 1건**을 주석으로 병기한다: 깨진 입력에서 exit 1 임을 실행해 확인한 출력.
- **출력을 보지 않고 종료코드만 보는 명령은 게이트가 아니다.** 파싱하거나 지운다. (`git check-attr` · `git submodule status` 는 문제 상황에서도 exit 0 이다.)
- 블록이 200행을 넘으면 계획서 밖 스크립트 파일로 빼고 계획은 그 출력만 인용한다.

#### 검사 번호 마커

각 검사는 `# 검사 #N: <제목>` 주석행으로 시작하고, 그 블록 안에 `# 기대:` 와 `# 음성:` 을 각 1개 갖는다.

```bash
# 검사 #1: <제목>
# 기대: 이 명령의 정상 출력이 무엇인가 — 층위 3(명령 ≠ 게이트)의 직접 항체
# 음성: 깨진 입력에서 exit 1 임을 실행해 확인한 관찰 — 층위 5 항체
```

`# 음성:` 은 저자가 한 번 돌려본 관찰의 **기록**이지 블록이 매번 재현하는 검사가 아니다. 기록이 사실인지는 리뷰 몫이다.

### NOT Building

계획서에 **명시적 범위 밖** 절을 둔다. 근거 `.claude/meta/12-ecc-upstream-delta.md` A3 — 상류 `prp-plan.md` 에는 있고 mccp `commands/plan.md` 에는 0건이다. 경계 없는 완료 조건은 Goodhart 로 간다(층위 6).

### Acceptance

```markdown
- [ ] {검증 가능한 서술} — 게이트 `#N`
```

- `All tasks complete` 류의 계획 무관 상수 문장 금지.
- 기계 검증 불가한 항목은 `(미검증)` 을 명시한다. 숨기지 않는다.
- **완전성 주장은 그것을 검사하는 코드 없이 쓰지 않는다.** "전부 덮었다" · "모든 Task 가 게이트를 갖는다" 는 실측으로 두 번 거짓이었다.
- **가능한 한 자기 단언이 아니라 외부 기준 대조로 쓴다** (golden 동결 · 정본 digest · upstream total). 근거 `.claude/meta/12-ecc-upstream-delta.md` C2. 층위 2·7 이 정의상 줄어든다.

### 리뷰 진입 전 lint

```bash
node .claude/templates/plan-kit/lint-plan.mjs <plan>
```

통과 필수. 실패한 계획서는 santa-loop 에 넣지 않는다. 규칙 PL1~PL10 과 겨냥 층위는 `.claude/templates/plan-kit/README.md` 에.

## 2. 리뷰 진입 전 자가 1패스 — 결함 층위 체크리스트

santa 라운드가 매번 이 순서로 한 겹씩 올라간다. 리뷰 전에 한 번에 훑으면 라운드가 그만큼 줄어든다.

```
1) 사실 오류 · 설계 결함 — 실측 없이 적은 인과가 있는가
2) 주장 ≠ 검사      산문이 주장하는데 대응 게이트가 없는 자리
3) 명령 ≠ 게이트    검사 자리에 명령이 있는데 출력을 안 보는 자리
4) 셸 실패 규약     set -euo pipefail · grep -c 종료코드 · 파이프 앞단 실패
5) 게이트 실행 불가  이 검사가 통과할 수 있는 대상을 보고 있는가 (실제로 돌려본다)
6) 게이트가 보는 대상  표본 ≠ 범위 · 값 검사로 계약을 잡으려는 자리
7) 검사 자신에 대한 주장에 검사가 있는가
8) 그 검사 자신의 사각지대 (자기 제외 구간을 출력에 드러낸다)
```

**notes 라운드 표에 `층위` 열을 추가한다.** 값은 위 체크리스트의 층 번호. 문서 11 §3 이 정한 세 측정 지표 중 유일하게 인프라가 없던 것이다 — 층위 열 없이는 "층위 2~6 이 저작 시점으로 옮겨갔는가" 를 잴 수 없다.

| 라운드 | A | B | 층위 | 흡수 | 기각 |
|---|---|---|---|---|---|

## 3. 저장소 상시 불변식 — 리뷰 루브릭에 원문 그대로 주입

이미 내려진 결정이다. **이 항목을 깨야만 해소되는 지적은 blocker 가 아니다.** 리뷰어 프롬프트에 이 절을 붙이고 `out_of_scope_observations` 로 분리하도록 지시한다. (실측: 이 지시를 넣자 무한 반복되던 항목 하나가 한 라운드에서 out-of-scope 로 닫혔다.)

| ID | 불변식 | 근거 |
|---|---|---|
| INV1 | **신규 의존 0.** 서브모듈 `node_modules` 가 gitignore 라 파서·라이브러리 도입 불가 | `.claude/plans/codex-findings-backlog.md` TS 파서 항목 |
| INV2 | **main 의 서브모듈 포인터는 동결값.** manifest `repos[].head` 와 일치해야 하며 stg bump 를 main 에 밀지 않는다 | `extraction-manifest.yaml` · m1-r2 Validation `#0c`·`#7` |
| INV3 | **PRD §배타 소유 경로는 `docs/` 산출물 충돌 방지용.** mccp 워크플로 산출물(`.claude/PRPs·notes·plans·receipts`)은 그 대상이 아니다 | backlog `REJECTED(PR-Codex F3)` — `origin/main` 선례 77건 |
| INV4 | **검사 없는 규범을 문서에 리터럴로 박지 않는다.** 기대 총수·행수 등은 golden 동결이나 기계 산출로만 | backlog selftest 건수 항목 — 세 번 기각된 축 |
| INV5 | **`planning/` 은 등급 L.** 값 인용 금지, 구조·용어만 참조 | `.claude/PRDs` 우산 제약 |
| INV6 | **로컬 계층은 mccp 대체가 아니다.** mccp 파일 미수정(B1) · 철거 조건 명시(B4) · 형식은 mccp 상위집합(B3) | `.claude/meta/12-ecc-upstream-delta.md` |

> 새 불변식을 추가할 때는 근거 파일을 함께 적는다. 근거 없는 행은 리뷰어가 정당하게 반박한다.

## 4. santa-loop 운용

- **판정 원장을 쓴다** — `.claude/state/santa-ledger.md` 에 `round | issue | ABSORBED(proof) | REJECTED(reason)` 한 줄씩. 매 라운드 통째로 주입하고 "판정 끝난 항목 재보고 금지" 로 지시. mccp 1.23.7 기능인데 이 저장소는 아직 미사용이다.
  - **생성 시점**: 루프 R1 진입 **전**. 첫 라운드가 돌기 전에 빈 표라도 만든다.
  - **경로**: `.claude/state/santa-ledger.md`.
  - **양식**: `round | issue | ABSORBED(proof) | REJECTED(reason)` 한 줄씩.
  - **`.claude/state/` 는 gitignore 대상이다.** 원장은 워크트리 안에서만 유효하고 이력에 남지 않는다 — 판정 근거의 **정본은 notes**다. 원장은 루프 재시작 시 정리된 땅을 다시 파지 않기 위한 작업 사본이다. 이력에 남겨야 하는 판정은 계획서 본문이나 notes 로 옮긴다.
- **Reviewer A 를 매 라운드 갈아 끼운다** — 범용 `code-reviewer` 는 승인으로 수렴한다(실측: 11라운드 중 9라운드 PASS, 6라운드 연속 PASS). `silent-failure-hunter` · `type-design-analyzer` · `comment-analyzer` 로 로테이션.
- **흡수는 매 건 반사실 검증한다** — 수정 전/후로 검사를 돌려 결과가 뒤집히는지 확인. 주장으로만 남긴 흡수는 다음 라운드의 지적이 된다.
- **커밋한 뒤 리뷰어를 돌린다** — 워킹트리를 읽은 리뷰는 편집 중인 행을 지적해 무효가 된다.
- **NICE 판정의 `git push` 는 보고로 내리고 사람이 마지막 스위치를 잡는다.** 근거 `.claude/meta/12-ecc-upstream-delta.md` C3 · 상류 #130. 이 저장소는 이미 실질적으로 그렇게 운용해 왔고 문서만 어긋나 있었다. mccp 파일은 고치지 않는다 — 운용 규약으로만 둔다(B1).

## 5. 상류 이슈

이 규약의 1·3절은 mccp 본체에 제기돼 있다 — [idenn207/mccp#127](https://github.com/idenn207/mccp/issues/127) (plan 생성 계약) · [#128](https://github.com/idenn207/mccp/issues/128) (루브릭 불변식 주입). 본체가 수용하면 이 절은 축소한다. 철거 조건은 §0 B4.