donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
7c4e8df24826f637abe7bcbc3774d2c5afcf806f
llm-wiki/docs/superpowers/plans/2026-06-06-spec-a-deterministic-backbone-gate.md
T

683 lines
30 KiB
Markdown
Raw Blame History

# Spec A — Deterministic Backbone Gate Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
> **Commits excluded** per user instruction ("커밋은 제외") — no `git commit` steps. Each task ends with a test-green checkpoint instead.
**Goal:** Turn the existing (non-blocking) `wiki_structure_lint.py` into a real hybrid gate — PreToolUse blocks ghost-creating links, PostToolUse becomes an exit-2 fix-up gate for completeness findings on completion-declared docs — while deduping the claim-rule SSOT into a shared `wiki_rules.py` and adding the first tests for the blocking `wiki_claim_gate.py`.
**Architecture:** New `wiki_rules.py` holds shared event/IO mechanism + the claim-requirement SSOT data + severity-tier constants. `wiki_claim_gate.py` imports it and drives its table checks from the shared data (behavior-preserving refactor). `wiki_structure_lint.py` gains a `--pre` mode (PreToolUse, blocks `BROKEN_LINK`/`BROKEN_MD_LINK` on projected content) and a tiered `--hook` mode (PostToolUse exit-2 fix-up for `FIXUP_CODES` when the doc declares completion). Link logic stays in structure_lint; claim logic stays in claim_gate; only mechanism + reference data is shared.
**Tech Stack:** Python 3 stdlib only (`unittest`, `importlib`, `re`, `pathlib`, `json`). No third-party deps. Claude Code hooks (`settings.json`).
**Spec:** `docs/superpowers/specs/2026-06-06-spec-a-deterministic-backbone-gate-design.md`
---
## File Structure
- **Create** `.claude/hooks/wiki_rules.py` — shared mechanism (moved verbatim from claim_gate) + `CLAIM_REQUIREMENTS` SSOT data + `CRITICAL_CODES`/`FIXUP_CODES`.
- **Create** `.claude/hooks/test_wiki_rules.py` — unit tests for moved `projected_content` + data integrity.
- **Modify** `.claude/hooks/wiki_claim_gate.py` — `import wiki_rules`; drive `check_markdown_write` table checks from `CLAIM_REQUIREMENTS`; keep two semantic special-cases inline.
- **Create** `.claude/hooks/test_wiki_claim_gate.py` — regression-lock the 5-prefix block/pass behavior.
- **Modify** `.claude/hooks/wiki_structure_lint.py` — `import wiki_rules`; add `run_pre()` + `run_hook()` testable functions; wire `--pre`; tier `--hook`; add suppressed-count line.
- **Modify** `.claude/hooks/test_wiki_structure_lint.py` — add `--pre`/`--hook` fix-up cases.
- **Modify** `.claude/settings.json` — add `structure_lint.py --pre` to PreToolUse.
**Sibling-import rule (applies to both hooks):** the first executable lines (after `from __future__`) must be:
```python
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import wiki_rules
```
This makes `import wiki_rules` resolve whether the file is run as a script (hook) or loaded via `importlib.spec_from_file_location` (tests).
---
## Task 1: Create `wiki_rules.py` shared module
**Files:**
- Create: `.claude/hooks/wiki_rules.py`
- Test: `.claude/hooks/test_wiki_rules.py`
The moved helpers are **verbatim copies** of `wiki_claim_gate.py` current functions: `read_event` (42-47), `tool_name` (50-56), `tool_input` (59-76), `target_path` (79-85), `write_content` (88-94), `projected_content` (97-135), `command_string` (138-145), `rel_to_root` (148-154), `has_table` (157-163). `ROOT` is the same `Path(__file__).resolve().parents[2]`.
- [ ] **Step 1: Write the failing test**
Create `.claude/hooks/test_wiki_rules.py`:
```python
#!/usr/bin/env python3
"""wiki_rules.py 단위 테스트 (stdlib unittest)."""
import importlib.util
import sys
import tempfile
import unittest
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
_SPEC = importlib.util.spec_from_file_location(
"wiki_rules", str(Path(__file__).with_name("wiki_rules.py")))
wr = importlib.util.module_from_spec(_SPEC)
_SPEC.loader.exec_module(wr)
class TestProjectedContent(unittest.TestCase):
def test_write_full_content(self):
# Write 스타일: content 키가 있으면 그대로 반환
inp = {"content": "FULL BODY"}
self.assertEqual(wr.projected_content(None, inp), "FULL BODY")
def test_edit_applies_old_new(self):
with tempfile.TemporaryDirectory() as d:
p = Path(d) / "f.md"
p.write_text("alpha BETA gamma")
inp = {"old_string": "BETA", "new_string": "DELTA"}
self.assertEqual(wr.projected_content(p, inp), "alpha DELTA gamma")
class TestSeverityData(unittest.TestCase):
def test_critical_codes_are_links(self):
self.assertIn("BROKEN_LINK", wr.CRITICAL_CODES)
self.assertIn("BROKEN_MD_LINK", wr.CRITICAL_CODES)
self.assertNotIn("MISSING_SECTION", wr.CRITICAL_CODES)
def test_fixup_codes_are_completeness(self):
for c in ("MISSING_SECTION", "MISSING_FRONTMATTER",
"EMPTY_SELECTION_CRITERION", "DANGLING_ANCHOR",
"PROJECT_NO_DIAGRAM", "PROJECT_NO_BRANCH_TABLE",
"UNMAPPED_SOURCE_TYPE"):
self.assertIn(c, wr.FIXUP_CODES)
self.assertNotIn("BROKEN_LINK", wr.FIXUP_CODES)
def test_claim_requirements_cover_five_prefixes(self):
prefixes = {p for req in wr.CLAIM_REQUIREMENTS for p in req["prefix"]}
for p in ("raw/official-docs/", "raw/company-tech-blogs/",
"raw/branch-notes/", "wiki/concepts/"):
self.assertIn(p, prefixes)
if __name__ == "__main__":
unittest.main(verbosity=2)
```
- [ ] **Step 2: Run test to verify it fails**
Run: `python3 .claude/hooks/test_wiki_rules.py`
Expected: FAIL — `FileNotFoundError`/`ModuleNotFoundError` (wiki_rules.py does not exist yet).
- [ ] **Step 3: Write minimal implementation**
Create `.claude/hooks/wiki_rules.py`. Copy the 9 helper functions **verbatim** from `wiki_claim_gate.py` (current line ranges noted in the Task header), then append the SSOT data and severity constants:
```python
#!/usr/bin/env python3
"""wiki_rules.py — claim_gate / structure_lint 공유 기계장치 + SSOT 데이터 (stdlib only).
여기엔 *정책*이 아니라 *공유 메커니즘*과 *참조 데이터*만 둔다:
- 이벤트/IO 헬퍼 (claim_gate 에서 이관, 두 훅이 공유)
- CLAIM_REQUIREMENTS : claim 테이블/섹션 요구 SSOT (이전엔 claim_gate inline 하드코딩 — G5 dedup)
- 심각도 티어 상수 : structure_lint 의 게이트 결정(차단 vs fix-up vs warn)이 소비
정책(block/warn 적용)은 각 훅에 남는다.
"""
from __future__ import annotations
import json
import shlex
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
# ---------- 이벤트/IO 헬퍼 (claim_gate 에서 verbatim 이관) ----------
# read_event / tool_name / tool_input / target_path / write_content /
# projected_content / command_string / rel_to_root / has_table
# (wiki_claim_gate.py 의 동일 함수 본문을 그대로 복사. target_path/rel_to_root 는 ROOT 사용.)
# ... (verbatim copies here) ...
# ---------- claim 요구 SSOT (G5 dedup 대상) ----------
CLAIM_REQUIREMENTS = [
{"prefix": ("raw/official-docs/", "raw/company-tech-blogs/"),
"tables": [("## Claims Extracted",
["Claim ID", "Claim", "Evidence quote", "Strength", "Applies to", "Does not prove"])],
"sections": ["## Usage Boundaries"]},
{"prefix": ("raw/branch-notes/",),
"tables": [("## Decision Evidence Map",
["Decision ID", "Decision", "Supporting Claims", "Evidence Strength", "Open Risk"])],
"section_regex": [r"^## .*\bClaims To Verify\b"]},
{"prefix": ("wiki/concepts/",),
"tables": [("## Claim-backed Knowledge",
["Knowledge Point", "Supporting Claims", "Confidence", "Notes"])]},
]
# ---------- 심각도 티어 (structure_lint 소비) ----------
CRITICAL_CODES = frozenset({"BROKEN_LINK", "BROKEN_MD_LINK"}) # PreToolUse block
FIXUP_CODES = frozenset({
"MISSING_SECTION", "MISSING_FRONTMATTER", "EMPTY_SELECTION_CRITERION",
"DANGLING_ANCHOR", "PROJECT_NO_DIAGRAM", "PROJECT_NO_BRANCH_TABLE",
"UNMAPPED_SOURCE_TYPE",
}) # PostToolUse exit-2 (완성 선언 시)
```
Replace the `# ... (verbatim copies here) ...` comment with the 9 functions copied exactly from `wiki_claim_gate.py`. Keep their bodies unchanged except `target_path`/`rel_to_root`, which already reference module-level `ROOT` — that now resolves to `wiki_rules.ROOT` (same value).
- [ ] **Step 4: Run test to verify it passes**
Run: `python3 .claude/hooks/test_wiki_rules.py`
Expected: PASS (5 tests OK).
- [ ] **Step 5: Checkpoint (no commit)**
Run: `python3 .claude/hooks/test_wiki_rules.py` → all green. Do NOT commit.
---
## Task 2: Refactor `wiki_claim_gate.py` to consume `wiki_rules` (behavior-preserving)
**Files:**
- Modify: `.claude/hooks/wiki_claim_gate.py` (replace lines 42-163 helpers with import; rewrite `check_markdown_write` 166-220 to drive table/section checks from `wiki_rules.CLAIM_REQUIREMENTS`)
- Test: `.claude/hooks/test_wiki_claim_gate.py` (new — written FIRST to lock current behavior)
This is a refactor: tests are written against **current** behavior and must stay green through the change.
- [ ] **Step 1: Write the regression-lock test**
Create `.claude/hooks/test_wiki_claim_gate.py`:
```python
#!/usr/bin/env python3
"""wiki_claim_gate.py 회귀 고정 테스트 — check_markdown_write 행동 동치 (refactor 전후 동일)."""
import importlib.util
import sys
import unittest
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
_SPEC = importlib.util.spec_from_file_location(
"wcg", str(Path(__file__).with_name("wiki_claim_gate.py")))
wcg = importlib.util.module_from_spec(_SPEC)
_SPEC.loader.exec_module(wcg)
CLAIMS_TABLE = (
"## Claims Extracted\n"
"| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |\n"
"|---|---|---|---|---|---|\n"
"| C1 | x | q | company-case-study | a | b |\n"
)
USAGE = "## Usage Boundaries\n- x\n"
DEM = (
"## Decision Evidence Map\n"
"| Decision ID | Decision | Supporting Claims | Evidence Strength | Open Risk |\n"
"|---|---|---|---|---|\n"
"| D1 | x | C1 | company-case-study | none |\n"
)
CTV = "## 검증해야 할 주장 / Claims To Verify\n- v\n"
class TestSourceNote(unittest.TestCase):
def test_missing_claims_table_blocks(self):
f = wcg.check_markdown_write("raw/official-docs/x.md", "# t\n" + USAGE)
self.assertTrue(any("Claims Extracted" in m for m in f))
def test_complete_source_note_passes(self):
f = wcg.check_markdown_write("raw/official-docs/x.md", "# t\n" + CLAIMS_TABLE + USAGE)
self.assertEqual(f, [])
class TestBranchNote(unittest.TestCase):
def test_missing_dem_blocks(self):
f = wcg.check_markdown_write("raw/branch-notes/feature-x.md", "# t\n" + CTV)
self.assertTrue(any("Decision Evidence Map" in m for m in f))
def test_complete_branch_note_passes(self):
f = wcg.check_markdown_write("raw/branch-notes/feature-x.md", "# t\n" + DEM + CTV)
self.assertEqual(f, [])
def test_officially_supported_without_strength_blocks(self):
body = "# t\n" + DEM + CTV + "\n이 기능은 officially supported 된다.\n"
f = wcg.check_markdown_write("raw/branch-notes/feature-x.md", body)
self.assertTrue(any("official" in m.lower() for m in f))
class TestConceptNote(unittest.TestCase):
def test_missing_claim_backed_blocks(self):
f = wcg.check_markdown_write("wiki/concepts/x.md", "# t\n본문")
self.assertTrue(any("Claim-backed Knowledge" in m for m in f))
class TestUnrelatedPath(unittest.TestCase):
def test_non_gated_path_passes(self):
# 게이트 대상 아닌 경로 → 통과(빈 failures)
f = wcg.check_markdown_write("wiki/projects/x.md", "# anything\n")
self.assertEqual(f, [])
if __name__ == "__main__":
unittest.main(verbosity=2)
```
- [ ] **Step 2: Run test to verify it passes against CURRENT code**
Run: `python3 .claude/hooks/test_wiki_claim_gate.py`
Expected: PASS — this locks the current behavior as the regression baseline (claim_gate already implements all these checks). If any test fails now, the test encodes a wrong expectation — fix the test to match current behavior before refactoring.
- [ ] **Step 3: Refactor `wiki_claim_gate.py`**
(a) Replace the helper block (current lines ~12-163: the `from __future__` through `has_table`) so the top reads:
```python
from __future__ import annotations
import json
import re
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import wiki_rules
from wiki_rules import (
ROOT, read_event, tool_name, tool_input, target_path, write_content,
projected_content, command_string, rel_to_root, has_table,
)
```
Keep `emit_allow`, `emit_block` as they are (they `print`/`sys.exit`, hook-specific). Delete the now-moved 9 functions from claim_gate.
(b) Rewrite `check_markdown_write(rel, text)` so the official-docs / company-tech-blogs / branch-notes / concepts table+section checks are produced by iterating `wiki_rules.CLAIM_REQUIREMENTS`, while the two **semantic** special-cases stay inline:
```python
def check_markdown_write(rel: str, text: str) -> list[str]:
failures: list[str] = []
if not rel.endswith(".md") or not text:
return failures
for req in wiki_rules.CLAIM_REQUIREMENTS:
if not rel.startswith(req["prefix"]): # tuple-of-prefixes → str.startswith accepts tuple
continue
for section, cols in req.get("tables", []):
if not has_table(text, section, cols):
failures.append(
f"{req['prefix'][0]} 류 문서는 `{section}` 표(열: {' | '.join(cols)})를 가져야 한다."
)
for sec in req.get("sections", []):
if sec not in text:
failures.append(f"문서는 `{sec}` 섹션을 가져야 한다.")
for rx in req.get("section_regex", []):
if not re.search(rx, text, re.MULTILINE):
failures.append("branch-note must include `## Claims To Verify` "
"(bilingual `## 검증해야 할 주장 / Claims To Verify` 도 허용).")
# 의미 규칙 1: branch-note 의 'officially supported' 주장은 official 강도 필요 (정책 — 인라인 유지)
if rel.startswith("raw/branch-notes/"):
if re.search(r"(?i)\bofficial(?:ly)? supported\b|공식(?:적으로)?\s*지원", text):
if not re.search(r"official-(standard|vendor-doc|reference)", text):
failures.append(
"`officially supported` style claim requires an official claim strength "
"(`official-standard`, `official-vendor-doc`, or `official-reference`)."
)
# 의미 규칙 2: 감사 리포트가 COMPLETE 주장 시 traceability 검증 포함 (정책 — 인라인 유지)
if rel.startswith("docs/superpowers/specs/") and rel.endswith("-report.md"):
if re.search(r"Verdict:\s*COMPLETE|\*\*Verdict:?\*\*\s*COMPLETE", text):
required = ["Decision Evidence Map", "Claims Extracted", "UNSUPPORTED_DECISION"]
missing = [item for item in required if item not in text]
if missing:
failures.append(
"audit report cannot claim COMPLETE unless it verifies claim traceability. "
f"Missing references: {', '.join(missing)}."
)
return failures
```
Note: `str.startswith` accepts a tuple, so `rel.startswith(req["prefix"])` works directly with the `prefix` tuples. `main()` and the rest of the file (subagent gates, bash gate) are unchanged except they now reference the imported helpers.
- [ ] **Step 4: Run tests to verify they still pass**
Run: `python3 .claude/hooks/test_wiki_claim_gate.py`
Expected: PASS — behavior unchanged after refactor.
- [ ] **Step 5: Checkpoint (no commit)**
Run both: `python3 .claude/hooks/test_wiki_rules.py && python3 .claude/hooks/test_wiki_claim_gate.py` → green. No commit.
---
## Task 3: Add `--pre` mode to `wiki_structure_lint.py` (PreToolUse link block)
**Files:**
- Modify: `.claude/hooks/wiki_structure_lint.py` (add `import wiki_rules`; add `run_pre()`; wire `--pre` in `main`)
- Test: `.claude/hooks/test_wiki_structure_lint.py` (append `TestPreMode`)
- [ ] **Step 1: Write the failing test**
Append to `.claude/hooks/test_wiki_structure_lint.py` (the module is loaded as `wsl`; add a `sys.path` insert near the top of the file if not present, mirroring Task 1):
```python
class TestPreMode(unittest.TestCase):
def _event(self, root, rel, content):
return {"tool_name": "Write",
"tool_input": {"file_path": str(root / rel), "content": content}}
def test_ghost_wikilink_blocks(self):
with tempfile.TemporaryDirectory() as d:
root = Path(d)
(root / "raw" / "branch-notes").mkdir(parents=True)
ev = self._event(root, "raw/branch-notes/b.md", "# t\nsee [[raw/nonexistent/ghost]]\n")
self.assertEqual(wsl.run_pre(ev, root), 2)
def test_backtick_placeholder_passes(self):
with tempfile.TemporaryDirectory() as d:
root = Path(d)
(root / "raw" / "branch-notes").mkdir(parents=True)
ev = self._event(root, "raw/branch-notes/b.md", "# t\nfuture: `[[raw/nonexistent/ghost]]`\n")
self.assertEqual(wsl.run_pre(ev, root), 0)
def test_no_links_skips_and_passes(self):
with tempfile.TemporaryDirectory() as d:
root = Path(d)
(root / "raw" / "branch-notes").mkdir(parents=True)
ev = self._event(root, "raw/branch-notes/b.md", "# t\n링크 없는 본문\n")
self.assertEqual(wsl.run_pre(ev, root), 0)
def test_non_wiki_path_passes(self):
with tempfile.TemporaryDirectory() as d:
root = Path(d)
(root / "docs").mkdir()
ev = self._event(root, "docs/x.md", "see [[raw/nonexistent/ghost]]\n")
self.assertEqual(wsl.run_pre(ev, root), 0)
```
- [ ] **Step 2: Run test to verify it fails**
Run: `python3 .claude/hooks/test_wiki_structure_lint.py -k Pre`
Expected: FAIL — `AttributeError: module 'wsl' has no attribute 'run_pre'`.
- [ ] **Step 3: Implement `run_pre`**
In `wiki_structure_lint.py`, after the `from __future__ import annotations` line add the sibling import:
```python
import sys
sys.path.insert(0, str(Path(__file__).resolve().parent))
import wiki_rules
```
(Path is already imported below; move the `from pathlib import Path` above this insert, or use a local import — keep it stdlib-clean.) Then add, near `main()`:
```python
def run_pre(event, root):
"""PreToolUse: projected 본문의 C2 깨진링크(CRITICAL)만 차단. 반환 exit code."""
inp = wiki_rules.tool_input(event)
p = wiki_rules.target_path(inp)
if p is None or not str(p).endswith(".md"):
return 0
try:
rel = p.resolve().relative_to(root).as_posix()
except Exception:
return 0
if not (rel.startswith("raw/") or rel.startswith("wiki/")):
return 0
text = wiki_rules.projected_content(p, inp)
# 위키링크/마크다운링크가 전혀 없으면 vault 인덱스 빌드 스킵 (성능).
if "[[" not in text and "](" not in text:
return 0
vp, vb = build_vault_index(root)
doc = {"lines": text.splitlines()}
findings = check_c2(doc, vp, vb, root, {}, rel)
critical = [(c, ln, m) for (c, ln, m) in findings if c in wiki_rules.CRITICAL_CODES]
if critical:
print(f"✗ wiki-structure-lint (pre): {rel} — 깨진 링크 {len(critical)}건 → 쓰기 차단",
file=sys.stderr)
for code, ln, msg in critical[:10]:
loc = f":{ln}" if ln else ""
print(f" [{code}]{loc} {msg}", file=sys.stderr)
if len(critical) > 10:
print(f" … 외 {len(critical) - 10}건 (suppressed)", file=sys.stderr)
print(" 미존재 타깃은 백틱 코드(`[[slug]]`)로 표기하거나 타깃 파일을 먼저 생성하세요.",
file=sys.stderr)
return 2
return 0
```
Wire it in `main()` — add the arg and dispatch **before** the existing `--hook` block:
```python
ap.add_argument("--pre", action="store_true",
help="PreToolUse hook — projected 본문 C2 깨진링크 차단 (blocking)")
...
if args.pre:
import json as _json
try:
event = _json.loads(sys.stdin.read() or "{}")
except Exception:
sys.exit(0)
sys.exit(run_pre(event, root))
```
- [ ] **Step 4: Run test to verify it passes**
Run: `python3 .claude/hooks/test_wiki_structure_lint.py -k Pre`
Expected: PASS (4 tests).
- [ ] **Step 5: Checkpoint (no commit)**
Run: `python3 .claude/hooks/test_wiki_structure_lint.py` → all green (old + new).
---
## Task 4: Tier `--hook` into fix-up gate + suppressed-count line
**Files:**
- Modify: `.claude/hooks/wiki_structure_lint.py` (extract existing `--hook` body 486-531 into `run_hook(event, root)`; add exit-2 on `FIXUP_CODES` when `is_completeness_checkable`; add suppressed line)
- Test: `.claude/hooks/test_wiki_structure_lint.py` (append `TestHookTiering`)
- [ ] **Step 1: Write the failing test**
Append:
```python
class TestHookTiering(unittest.TestCase):
def _write(self, root, rel, fm, body):
p = root / rel
p.parent.mkdir(parents=True, exist_ok=True)
p.write_text("---\n" + fm + "\n---\n" + body)
return p
def _event(self, p):
return {"tool_name": "Edit", "tool_input": {"file_path": str(p)}}
def test_completed_missing_section_blocks(self):
with tempfile.TemporaryDirectory() as d:
root = Path(d)
# 완성 선언(status: verified) + 필수 섹션 누락 → fix-up exit 2
p = self._write(root, "wiki/concepts/x.md",
"title: x\nsource_type: concept\nstatus: verified\ntags: [a]", "본문만\n")
self.assertEqual(wsl.run_hook(self._event(p), root), 2)
def test_draft_missing_section_warns_only(self):
with tempfile.TemporaryDirectory() as d:
root = Path(d)
# draft → 완성 선언 아님 → exit 0 (WARN)
p = self._write(root, "wiki/concepts/x.md",
"title: x\nsource_type: concept\nstatus: draft\ntags: [a]", "본문만\n")
self.assertEqual(wsl.run_hook(self._event(p), root), 0)
def test_non_wiki_path_passes(self):
with tempfile.TemporaryDirectory() as d:
root = Path(d)
p = self._write(root, "docs/x.md", "title: x", "본문\n")
self.assertEqual(wsl.run_hook(self._event(p), root), 0)
```
- [ ] **Step 2: Run test to verify it fails**
Run: `python3 .claude/hooks/test_wiki_structure_lint.py -k HookTiering`
Expected: FAIL — `AttributeError: ... has no attribute 'run_hook'`.
- [ ] **Step 3: Refactor `--hook` into `run_hook`**
Extract the current `if args.hook:` body (lines ~486-531) into a function returning an exit code, adding the tier decision + suppressed line:
```python
def run_hook(event, root):
"""PostToolUse: 완성 선언 문서의 C1/C3/DANGLING(FIXUP) → exit 2 fix-up. 그 외 WARN(0)."""
inp = event.get("tool_input") or {}
fp = next((inp[k] for k in ("file_path", "path", "absolute_path", "TargetFile", "target_file")
if isinstance(inp.get(k), str)), None)
if not fp or not fp.endswith(".md"):
return 0
p = Path(fp)
if not p.is_absolute():
p = (root / fp)
try:
rel = p.resolve().relative_to(root).as_posix()
except Exception:
return 0
if not (rel.startswith("raw/") or rel.startswith("wiki/")) or not p.exists():
return 0
vp, vb = build_vault_index(root)
doc = parse_doc(p)
findings = check_c2(doc, vp, vb, root, {}, rel) # C2 항상
if is_completeness_checkable(doc):
by_st, by_file = build_template_index(root)
tmpl = resolve_template(doc["fm"], by_st, by_file)
if rel.startswith("raw/project-notes/"):
fm_findings = []
if tmpl is not None:
for k in tmpl["fm_keys"]:
if k not in doc["fm_keys"]:
fm_findings.append(("MISSING_FRONTMATTER", 0, f"frontmatter 키 누락: '{k}'"))
findings = fm_findings + check_project_proxies(doc) + findings
else:
findings = check_c1(doc, tmpl) + findings + check_c3(doc)
if not findings:
return 0
fixup = [f for f in findings if f[0] in wiki_rules.FIXUP_CODES]
block = bool(fixup) and is_completeness_checkable(doc)
sigil = "✗" if block else "⚠"
print(f"{sigil} wiki-structure-lint: {rel} — 구조/링크 이슈 {len(findings)}건"
+ (" → fix 필요" if block else ""), file=sys.stderr)
for code, ln, msg in findings[:10]:
loc = f":{ln}" if ln else ""
print(f" [{code}]{loc} {msg}", file=sys.stderr)
if len(findings) > 10:
print(f" … 외 {len(findings) - 10}건 (suppressed)", file=sys.stderr)
print(" 깨진 링크는 타깃 생성/수정(placeholder 는 `백틱 코드경로`). "
"섹션/선택조건은 완성 선언 문서에만 검사됨.", file=sys.stderr)
return 2 if block else 0
```
Replace the old `if args.hook:` block body with:
```python
if args.hook:
import json as _json
try:
event = _json.loads(sys.stdin.read() or "{}")
except Exception:
sys.exit(0)
sys.exit(run_hook(event, root))
```
Keep `build_vault_index`/`parse_doc`/`check_c1`/`check_c3`/`is_completeness_checkable`/`check_project_proxies`/`resolve_template`/`build_template_index` as-is (already module-level).
- [ ] **Step 4: Run test to verify it passes**
Run: `python3 .claude/hooks/test_wiki_structure_lint.py -k HookTiering`
Expected: PASS (3 tests).
- [ ] **Step 5: Checkpoint (no commit)**
Run: `python3 .claude/hooks/test_wiki_structure_lint.py` → all green.
---
## Task 5: Wire `--pre` into `settings.json`
**Files:**
- Modify: `.claude/settings.json` (add a second PreToolUse entry)
- [ ] **Step 1: Edit `settings.json`**
Change the `PreToolUse` array from one matcher to two (leave PostToolUse / Subagent blocks untouched):
```json
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{ "type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/wiki_claim_gate.py",
"timeout": 30 }
]
},
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{ "type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/wiki_structure_lint.py --pre",
"timeout": 30 }
]
}
],
```
- [ ] **Step 2: Validate JSON**
Run: `python3 -m json.tool .claude/settings.json > /dev/null && echo OK`
Expected: `OK`.
- [ ] **Step 3: Checkpoint (no commit)** — JSON valid.
---
## Task 6: Full regression + acceptance smoke (spec §6)
**Files:** none (verification only)
- [ ] **Step 1: Run the full hook test suite**
Run:
```bash
python3 .claude/hooks/test_wiki_rules.py && \
python3 .claude/hooks/test_wiki_claim_gate.py && \
python3 .claude/hooks/test_wiki_structure_lint.py
```
Expected: all suites OK, zero failures.
- [ ] **Step 2: `--all` regression (gate wiring must not change findings)**
Run: `python3 .claude/hooks/wiki_structure_lint.py --all`
Expected: a summary line `== 요약: N개 중 FAIL f / PASS p ==`. Compare `f` against a pre-change baseline (run the same on `git stash` of the hooks if unsure) — the FAIL set must be unchanged (the `--all` path is untouched by this spec).
- [ ] **Step 3: Acceptance criterion 1 — `--pre` blocks ghost, passes backtick (live stdin)**
Run:
```bash
echo '{"tool_name":"Write","tool_input":{"file_path":"raw/branch-notes/_smoke.md","content":"# t\nsee [[raw/nonexistent/ghost]]\n"}}' \
| python3 .claude/hooks/wiki_structure_lint.py --pre; echo "exit=$?"
echo '{"tool_name":"Write","tool_input":{"file_path":"raw/branch-notes/_smoke.md","content":"# t\nfuture: `[[raw/nonexistent/ghost]]`\n"}}' \
| python3 .claude/hooks/wiki_structure_lint.py --pre; echo "exit=$?"
```
Expected: first `exit=2` with a stderr `[BROKEN_LINK]` line; second `exit=0`.
- [ ] **Step 4: Acceptance criterion 3 — `--hook` fix-up only on completion**
Create a temp completed concept doc missing required sections, pipe an Edit event, expect exit 2; flip `status: verified` → `status: draft`, expect exit 0. (Use a path under `raw/` or `wiki/` in the real repo or a temp `--root`.)
```bash
python3 - <<'PY'
import json, subprocess, tempfile, os
from pathlib import Path
d = tempfile.mkdtemp()
root = Path(d); (root/"wiki"/"concepts").mkdir(parents=True)
# copy templates so resolve_template works
import shutil; shutil.copytree(".claude/hooks", root/".claude"/"hooks"); shutil.copytree("templates", root/"templates")
p = root/"wiki"/"concepts"/"x.md"
def run(status):
p.write_text(f"---\ntitle: x\nsource_type: concept\nstatus: {status}\ntags: [a]\n---\n본문만\n")
ev = json.dumps({"tool_name":"Edit","tool_input":{"file_path":str(p)}})
r = subprocess.run(["python3", str(root/".claude"/"hooks"/"wiki_structure_lint.py"),
"--hook", "--root", str(root)], input=ev, text=True, capture_output=True)
print(status, "exit", r.returncode)
run("verified"); run("draft")
PY
```
Expected: `verified exit 2`, `draft exit 0`.
- [ ] **Step 5: Acceptance criterion 8 — happy path passes both gates**
Take a real completed wiki doc with valid links; run it through `--pre` (Write event) and `--hook` (Edit event). Both must `exit=0`. Confirms the gate doesn't block legitimate writes.
- [ ] **Step 6: Final checkpoint (no commit)**
All §6 acceptance criteria (1, 3, 4, 7, 8) demonstrated green. Report results to the user. Do NOT commit (per user instruction) — leave changes staged in the working tree for the user to review.
---
## Self-Review (completed by plan author)
- **Spec coverage:** §3 DD1 hybrid gate → Tasks 3+4+5. §3 DD2 lean SSOT → Tasks 1+2. §4.1 wiki_rules → Task 1. §4.2 `--pre` → Task 3. §4.3 `--hook` tiering + suppressed → Task 4. §4.4 settings → Task 5. §6 acceptance 1-8 → Task 6. G6 (claim_gate tests) → Task 2. No spec requirement left unmapped.
- **Placeholder scan:** the only `...` is the explicit "copy these 9 functions verbatim from claim_gate lines X-Y" instruction with exact source line ranges — not a content gap. All test/impl steps carry runnable code.
- **Type/name consistency:** `run_pre(event, root)` / `run_hook(event, root)` signatures match between Tasks 3/4 impl and their tests; `CRITICAL_CODES`/`FIXUP_CODES`/`CLAIM_REQUIREMENTS` names match between Task 1 (def) and Tasks 2/3/4 (use); `check_markdown_write(rel, text)` signature unchanged (Task 2 tests call it as today).
Reference in New Issue View Git Blame Copy Permalink