---
title: "Spec A — 결정론 backbone을 진짜 게이트로 (하이브리드 PreToolUse/PostToolUse)"
source_type: llm-generated
status: draft
confidence: medium
tags: [harness, claude-code, hooks, design, automation]
last_reviewed: 2026-06-06
---

# Spec A — 결정론 backbone을 진짜 게이트로

> 상위 감사: [[2026-06-06-harness-audit-report]] §3 G1·G5·G6. 본 spec은 그 첫 슬라이스.
> 두 설계 결정 확정: **(1) 하이브리드 게이트**, **(2) Lean & safe 범위/SSOT**.

## 1. 문제 (감사에서)

- **G1**: `wiki_structure_lint.py`의 `--hook` 경로가 findings가 있어도 **항상 `sys.exit(0)`** (line 531) — 582행짜리 결정론 린터가 *경고 프린터*일 뿐 게이트가 아니다. 게다가 PostToolUse라 사후. 유일한 실제 차단(`wiki_claim_gate.py`)은 **5개 path-prefix만** 커버 → `wiki/projects`·`invest-*`·파생 산출물·`raw/errors`는 쓰기-시점 강제 0.
- **G5**: SSOT 분열 — `structure_lint`는 `templates/`에서 도출(좋음), 그러나 `claim_gate`는 섹션명·컬럼을 inline 하드코딩, `SKILL.md`는 source_type 재나열 → 택소노미 사본 3개, drift 위험.
- **G6**: 유일한 exit-2 차단 훅 `claim_gate.py`에 유닛 테스트 **0개**(비차단 린터는 잘 테스트됨 — 비대칭).

## 2. 비목표 (이 spec 범위 밖)

- judge 에이전트 return-schema / N-vote quorum → **Spec B**.
- funnel stats 계약 → **Spec C**.
- 누락 카테고리의 *새 의미 규칙*(invest source+timestamp, 파생물 canonical-source+status, wiki/projects claim-backed) → 후속(Spec B/C 또는 A.2). **단, 섹션/frontmatter 존재 검사는 C1이 template-derived이므로 게이트 배선만으로 전 카테고리 자동 확장됨.**
- Antigravity 훅 포팅 → 기존 follow-up(`docs/superpowers/notes/2026-06-04-phase2-antigravity-hook-coverage.md`).
- branch-spec/project-spec의 Workflow 변환 → **Spec D**(보류).

## 3. 핵심 설계 결정 (확정)

### DD1 — 하이브리드 게이트 지점·의미
PostToolUse exit-2는 쓰기를 되돌리지 못한다(파일은 이미 디스크, 모델에 "고쳐라"만 전달). 따라서:

- **항상-틀린 검사(C2 깨진 링크)** → **PreToolUse**로 옮겨 `projected_content`에 검사, exit 2로 **쓰기 자체 차단**(ghost가 디스크에 안 닿음).
- **완성성 검사(C1 섹션/frontmatter, C3 선택조건)** → 기존 `is_completeness_checkable` 철학 유지: '완성 선언' 문서에만 **PostToolUse exit-2 fix-up**.

기존 코드 철학(C2-항상 / C1·C3-완성시)과 정확히 일치한다.

### DD2 — Lean & safe 범위 + SSOT
- claim_gate의 *기존* 5-prefix 의미 규칙은 그대로. 새 의미 규칙 없음.
- SSOT: claim_gate의 하드코딩 prefix→요구 맵 + 공유 이벤트 파싱을 **새 `wiki_rules.py` 모듈**로 추출(두 훅이 import). 템플릿-테이블 파싱(Deep SSOT)은 채택 안 함 — fragile.

## 4. 아키텍처

```
.claude/hooks/
  wiki_rules.py            ← NEW. 공유 SSOT 모듈 (stdlib only)
  wiki_claim_gate.py       ← MOD. wiki_rules import (projected_content/파싱/PREFIX_REQUIREMENTS 이관)
  wiki_structure_lint.py   ← MOD. --pre 모드 신설 + --hook fix-up 티어링
  test_wiki_structure_lint.py  ← 기존
  test_wiki_claim_gate.py  ← NEW
```

### 4.1 `wiki_rules.py` (NEW 공유 모듈)
- **이관(claim_gate→여기):** `tool_name()`, `tool_input()`, `target_path()`, `write_content()`, `projected_content()`, `command_string()`, `rel_to_root()`, `has_table()`.
- **추출(하드코딩→dict, SSOT):**
  ```python
  PREFIX_REQUIREMENTS = {
    "raw/official-docs/":       {"tables": [("## Claims Extracted", [...6 cols])], "sections": ["## Usage Boundaries"]},
    "raw/company-tech-blogs/":  {...동일...},
    "raw/branch-notes/":        {"tables": [("## Decision Evidence Map", [...5 cols])],
                                  "section_regex": [r"^## .*\bClaims To Verify\b"],
                                  "semantic": ["officially_supported_needs_strength"]},
    "wiki/concepts/":           {"tables": [("## Claim-backed Knowledge", [...4 cols])]},
    "docs/superpowers/specs/*-report.md": {"semantic": ["complete_needs_traceability"]},
  }
  ```
  (claim_gate의 `check_markdown_write` 로직이 이 dict를 순회하도록 리팩터 — 동작 동일, 출처가 dict로.)
- **상수:** `CRITICAL_CODES`, `FIXUP_CODES`, `WARN_CODES` (structure_lint이 import).
  ```python
  CRITICAL_CODES = {"BROKEN_LINK", "BROKEN_MD_LINK"}          # PreToolUse block
  FIXUP_CODES = {"MISSING_SECTION","MISSING_FRONTMATTER",
                 "EMPTY_SELECTION_CRITERION","DANGLING_ANCHOR",
                 "PROJECT_NO_DIAGRAM","PROJECT_NO_BRANCH_TABLE",
                 "UNMAPPED_SOURCE_TYPE"}                       # PostToolUse exit-2 (완성시)
  # 그 외(NO_FRONTMATTER 등) → WARN exit 0
  ```

### 4.2 `wiki_structure_lint.py --pre` (NEW 모드)
- stdin JSON 이벤트 → `wiki_rules.target_path()` + `projected_content()`로 *쓰기 후 예상 본문* 계산.
- `raw/` 또는 `wiki/`의 `.md`가 아니면 exit 0.
- `build_vault_index(root)` + `check_c2(projected_doc, ...)` 실행.
- **`code in CRITICAL_CODES`인 finding이 있으면 stderr로 사유 출력 + `sys.exit(2)`** (쓰기 차단).
  - 백틱 placeholder(`` `[[future]]` ``)는 `_code_spans`가 이미 면제 → forward-ref 정상.
  - 차단 메시지에 탈출구 명시: "미존재 타깃은 백틱 코드(`` `[[slug]]` ``)로 표기하거나 타깃을 먼저 생성."
- CRITICAL 없으면 exit 0(DANGLING_ANCHOR 등은 PostToolUse가 처리).
- **성능:** PreToolUse는 매 쓰기마다 발동 → `build_vault_index`(rglob) 비용. 30s timeout 내 여유지만, 캐시 불가(이벤트마다 새 프로세스). projected 본문에서 *추출된 위키링크가 0개면 인덱스 빌드 스킵*하는 early-exit 추가.

### 4.3 `wiki_structure_lint.py --hook` (MOD, fix-up 티어링)
현재: C2 항상 + (완성시) C1/C3 → 전부 stderr 출력 → 항상 exit 0.
변경:
- C2 **broken-link**는 이미 PreToolUse에서 차단됨 → `--hook`에서는 중복 차단 안 함(여전히 출력은 하되 exit 코드엔 미반영). DANGLING_ANCHOR(타깃 존재, 앵커만 부재)는 여기 fix-up 대상.
- `is_completeness_checkable(doc)` 이고 `findings` 중 `code in FIXUP_CODES`가 있으면 → stderr 사유 + **`sys.exit(2)`** (fix-up 루프; 파일은 디스크에 있으나 모델이 고침).
- 그 외 → 기존처럼 WARN 출력 + `sys.exit(0)`.
- **무삭제:** `findings[:10]` 잘림 시 `  … 외 {len-10}건 (suppressed)` 1줄 추가(`--hook`·`--pre` 양쪽).

### 4.4 `settings.json` 배선
```jsonc
"PreToolUse": [
  { "matcher": "*", "hooks": [ /* wiki_claim_gate.py (기존) */ ] },
  { "matcher": "Write|Edit|MultiEdit", "hooks": [
      { "type": "command",
        "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/wiki_structure_lint.py --pre",
        "timeout": 30 } ] }
],
"PostToolUse": [
  { "matcher": "Write|Edit|MultiEdit", "hooks": [ /* wiki_structure_lint.py --hook (기존, 동작 변경) */ ] }
]
```
SubagentStart/SubagentStop(claim_gate)는 불변.

## 5. 영향 분석 / 위험

| 위험 | 완화 |
|---|---|
| PreToolUse C2-block이 클러스터 작성 중 형제 forward-ref를 막음 | 백틱 placeholder(코드가 이미 면제). 차단 메시지에 탈출구 명시. C1/C3는 PreToolUse 차단 안 함(완성시 PostToolUse fix-up). |
| 매 쓰기 `build_vault_index` 비용 | projected 본문에 위키링크 0개면 인덱스 빌드 스킵. 30s timeout. |
| PostToolUse exit-2가 무한 fix-up 루프 | claim_gate가 쓰는 `stop_hook_active` 가드 패턴 동일 적용 — 재진입 시 통과. |
| `wiki_rules.py` import가 Codex에서 깨짐 | 같은 디렉터리 stdlib import → Codex 동일 스크립트 실행이라 동작. `--check`(sync_automation)와 무관(훅은 SSOT 1벌). |
| claim_gate 리팩터가 기존 동작 변경 | dict-주도로 바꾸되 *동작 동치*. 신규 `test_wiki_claim_gate.py`가 5-prefix 케이스 회귀 고정. |

## 6. 수용 기준 (검증 가능)

1. `--pre`: 미존재 타깃 `[[ghost]]`를 본문에 포함한 Write 이벤트(stdin JSON) → exit 2 + stderr에 사유. **백틱** `` `[[ghost]]` ``은 exit 0.
2. `--pre`: 위키링크 0개 본문 → `build_vault_index` 미호출(스킵) + exit 0.
3. `--hook`: `status: verified` 문서가 필수 섹션 누락 → exit 2. `status: draft` 동일 문서 → exit 0(WARN만).
4. `--hook`/`--pre`: findings 11건 → 10건 출력 + `… 외 1건 (suppressed)`.
5. `claim_gate`: 리팩터 후 기존 5-prefix 차단 케이스 5종 + 통과 케이스가 `test_wiki_claim_gate.py`에서 green.
6. `python3 .claude/hooks/test_wiki_structure_lint.py` + `test_wiki_claim_gate.py` 전부 통과.
7. `wiki_structure_lint.py --all` 회귀: 본 변경 전후 FAIL 집합 동일(게이트 배선은 `--all`에 영향 없음).
8. 실제 wiki 문서 1개 정상 작성(완성 frontmatter + 유효 링크) → Pre/Post 훅 모두 통과(exit 0), 정상 저장.

## 7. 구현 순서 (writing-plans에서 단계화)

1. `wiki_rules.py` 생성 — claim_gate에서 공유 헬퍼 이관 + `PREFIX_REQUIREMENTS` dict + severity 상수.
2. `wiki_claim_gate.py` — `wiki_rules` import, `check_markdown_write`를 dict-주도로 리팩터(동작 동치).
3. `test_wiki_claim_gate.py` — 5-prefix 차단/통과 회귀 고정(2 전에 작성 = TDD).
4. `wiki_structure_lint.py` — `--pre` 모드 + `--hook` fix-up 티어링 + 무삭제 1줄.
5. `test_wiki_structure_lint.py` — `--pre`/fix-up 케이스 추가.
6. `settings.json` — PreToolUse에 `--pre` 배선.
7. 수동 스모크: §6 수용 기준 1-8 실행.

## 8. 메모

- 본 spec은 *기존 메커니즘 강화*(저위험)이며 새 아키텍처를 도입하지 않는다. Workflow/quorum 같은 고위험 변경은 Spec B/D로 분리.
- `claim_gate`와 `structure_lint`의 책임 분리 유지: claim_gate=claim 의미, structure_lint=구조/링크. `wiki_rules.py`는 *공유 기계장치*만(정책 아님).