# 강제기 우선 MVP 설계 (.claude 슬라이스)

- 작성일: 2026-07-05
- 대상: `company-haness` / Org OS — 명세를 처음으로 **실행 시점에 강제**하는 층
- 범위: 강제기(hook/validator) 중심 + 최소 실제 구조. git 미사용.
- 뿌리 대응: 리뷰의 ①강제 공백 ②자기신고 — 명세로는 불가했던 부분을 코드로 강제.

## 1. 아키텍처
Claude Code hook은 stdin JSON + exit code로 동작한다. exit(2)는 툴콜/종료를 **하드 차단**하고 사유를 되먹인다(disler 패턴). 이 결정론 스크립트들은 이 세션에서 독립 테스트가 가능하다. 자동 라우팅·전체 오케스트레이션 루프는 런타임이 세션 로드시 구동하므로 MVP는 그 아래 **강제층을 완성·검증**한다.

## 2. 컴포넌트 (단일 책임)
| 파일 | 책임 | 입력 → 출력 |
|---|---|---|
| `.claude/hooks/gen_agents.py` | capability-families.yaml → `.claude/agents/*.md` 생성 | families → 26 agent .md |
| `.claude/hooks/validate_report.py` | 보고서가 org-os 계약 준수 검증 | report.yaml → exit 0/2 |
| `.claude/hooks/guard_tools.py` | tool-permission-matrix 강제 | PreToolUse JSON → exit 0/2 |
| `.claude/hooks/stop_validate.py` | SubagentStop시 보고서 찾아 validate 호출 | stdin JSON → exit 0/2 |
| `.claude/settings.hooks.json` | hook 배선 템플릿(활성화=다음 세션) | — |
| `.claude/commands/ceo-intake.md` | 진입 command(구조 시연) | — |
| `.claude/tests/test_enforcement.py` | good/bad 픽스처 + exit-code 단언 | → all green |

## 3. 강제 계약
### validate_report.py (자기신고 접지 + BLUF)
보고서 yaml에 대해:
- `report-header.bottom-line` 비면 차단(answer-first).
- `evidence[]` 비었거나 `source-uri`가 실존 파일이 아니면 차단(자기채점 차단). command+exit-code 형태도 허용.
- `confidence.value == High`인데 grade ≥ E3 증거 또는 성공 실행 아티팩트 0개면 차단(과잉확신 차단).
- 필수 필드(bottom-line, decision-needed, confidence, risks, evidence) 누락 차단.
- 통과 exit 0, 위반 stderr 사유 + exit 2.

### guard_tools.py (최소권한)
`tool-permission-matrix.yaml` default-deny(slack/github-pr-create/deploy/secret-read/db-write) 위반을 차단:
- Bash 명령의 위험 패턴(git push, gh pr create, deploy/kubectl, `.env`/secret 접근, rm -rf) → exit 2.
- 그 외 → exit 0. 사유는 stderr로 Claude에 되먹임.

## 4. gen_agents 생성 규칙
각 family → `.claude/agents/<family-id 소문자>.md`:
- frontmatter: `name`(소문자-하이픈), `description`(= capability + "Use PROACTIVELY when <triggers>. Do NOT use for <exclusions>."), `tools`(family유형별 최소권한), `model: inherit`.
- body: "When invoked" 넘버드 스텝 + **report-header(BLUF) 필수** + exclusions 준수 + tier=heavy는 plan-signoff 전 실행 금지.
- tools 매핑: 엔지니어링/실행 family=Read,Grep,Glob,Edit,Write,Bash; 감사(audit-capable)=Read,Grep,Glob,Bash; 임원/추천=Read,Grep,Glob,Write; orchestrator=Read,Grep,Glob,Write,Edit.

## 5. 테스트 (이 세션 검증)
- validate_report: 정상→0, BLUF누락/증거허위/과잉확신→각 2.
- guard_tools: 허용도구→0, deny(gh pr create/`.env`/rm -rf)→각 2.
- stop_validate: 픽스처 보고서(정상/불량)→0/2.
- gen_agents 실행 → 26 agent 생성 + frontmatter 파싱·description에 triggers/exclusions 포함 검증.
- `test_enforcement.py` 한 방 all green.

## 6. 범위 밖(다음)
전체 오케스트레이션 라이브, 7 command 전부, MCP, evidence 등급 CI 파생, settings.json 라이브 활성화(자기간섭 방지 위해 템플릿으로 제공).

## 7. 성공 기준
1. 4개 스크립트 모두 정상/위반 픽스처에서 기대 exit code.
2. gen_agents가 26개 agent .md 생성, 전부 유효 frontmatter.
3. test_enforcement.py exit 0(all pass).
4. 기존 org-os 정합성 게이트 무회귀.