llm-wiki/docs/superpowers/specs/2026-07-14-harness-correctness-sweep-design.md

title, date, status, kind, slice, revision

title	date	status	kind	slice	revision
하네스 정합성 스위프 (Tier A) — 설계	2026-07-14	draft	design-spec	1-of-N (harness review 적용)	3 (spec 리뷰 2차 반영 — A1 portable-only 경로 + A3 BLOCKED 고정 + A1 hook별 E2E 표)

하네스 정합성 스위프 (Tier A)

0. 한 줄 목표

문서·설정이 실제 repo 상태와 어긋난 곳을 바로잡는다. 아키텍처는 건드리지 않는다.

1. 배경

외부에서 받은 "LLM Wiki 하네스 구조·효율성 리뷰"를 적용하기로 했다. 리뷰는 partial Repomix 스냅샷(raw/·wiki/ 본문 미포함) 기반이라, 적용 전 각 주장을 실제 repo 근거로 선별(triage) 했다. 선별 결과 ~8개 semi-independent 프로젝트가 6 phase 로 나온다 — 단일 spec 으로 다룰 수 없다.

이 문서는 그중 첫 슬라이스 = Tier A(정합성 스위프) 만 다룬다. 나머지(B/C 티어)는 §7 백로그에 기록만 한다.

Tier A 선택 이유: 근거 확실, 소규모, 아키텍처 lock-in 0, live bug 포함, 빠름.

rev.2 노트: 이 spec 자체를 리뷰받아 반영했다. 주요 변경 — (1) A1 완료 기준을 "직접 실행"이 아닌 "실제 Hook E2E 관측"으로 격상, (2) A3 를 모호한 "트랜잭션"이 아닌 명시적 허용 write set 으로 고정 + agent runtime contract 변경으로 재분류, (3) A4 범위를 live 문서 전체로 확대(historical 기록 제외), (4) JSON/TOML 구문 검증·기존 hook test·의미 패리티 표·git-diff allowlist 추가.

2. 선별 근거 (verified)

주장	판정	근거
Antigravity 훅 command 대상 절대경로가 부재	CONFIRMED	.agents/hooks.json → /home/donghyeon/dev/llm-wiki-private/...; /home/donghyeon/dev 자체가 부재(ls 실패).
해당 claim/structure Python 검사가 정상 실행 불가	CONFIRMED	경로 부재로 python3 <경로> 실패.
Hook 실패 시 Antigravity 가 작업을 완전 허용(fail-open)한다 / "강제 0"	UNVERIFIED	Antigravity 의 command-실패 처리(fail-open vs fail-closed)를 실행 로그로 확인 안 함. 단정 금지. global wiki-hard-gate 만 생존은 LIKELY(로그 확인 필요).
Codex 가 CLAUDE.md fallback 로드 (문서 서술)	CONFIRMED (문서 오류)	루트에 AGENTS.md 존재 → .codex/config.toml:2-3 주석대로 fallback 은 "AGENTS.md 없을 때만" 발동. CLAUDE.md:82(Hooks bullet) "codex 가 본 CLAUDE.md 를 읽음(AGENTS.md 중복 불필요)" 은 거꾸로.
wiki-doc-author "1 file" vs Parent 갱신 모순	CONFIRMED	STOP #5 / "What NOT" 이 "2개 이상 파일 수정 금지"인데 정상 create/migrate 는 target + Parent hub 2개 Edit.
doc-author 카테고리 "7 vs 8"	CONFIRMED (SSOT·agent.json 만)	SSOT .agents/plugins/.../wiki-doc-author.md:73 "Category ∉ 7 허용"·agent.json STOP #2/table — 8개 나열하며 7. Claude 사본은 "8종"(드리프트).
doc-author validator "8개 모두" vs grep 그룹 7개	CONFIRMED (agent.json 만)	agent.json output schema Post-Write Validator ... (8개 모두) 인데 validator 블록 grep 그룹 7개.
doc-author migrate "본문 보존 vs 정규화 모순"	REJECTED (오독)	body 보존 + frontmatter/Parent/Sources placeholder 추가만 분리(L144·L156-157 line-count BLOCKED). 결함 아님.
인벤토리 숫자 stale	CONFIRMED	실측(§4 A4 명령): templates 27, rules 14, Claude agents 12, Antigravity executable agents 10, agent-prompt SSOT 10, commands 23.
scripts/ 디렉터리 자체 부재	CONFIRMED (stale)	scripts/ 는 존재(scripts/deep-research/). sync_automation.py 만 부재.

3. 범위

In scope

• A1: Antigravity 훅 경로 복구 (Hook runtime configuration 변경)
• A2: Codex 문서 오류 정정 (운영 문서 정정)
• A3: wiki-doc-author 계약 결함 3종 정정 (agent runtime contract 변경)
• A4: 인벤토리 숫자 정정 (운영 문서 정정)

Explicitly out of scope (→ §7 백로그)

harness/ 재구조화 · rules→skills 이관 · template-v2 · SSOT 생성기(B1) · 3-채널 출력(B2) · deep-research 런타임 하드닝(B3) · 훅 증분화+wiki-index(B4) · 훅 matcher 과범위(*) 최적화 · AGENTS.md source_type 목록 완전성 · historical 기록(docs/superpowers/plans/*, notes/*)의 stale 숫자. 이번 슬라이스에서 절대 손대지 않는다.

4. 항목별 설계

A1 — Antigravity 훅 부활 (Hook runtime configuration)

대상: .agents/hooks.json 의 다음 4개 command entry (전부 절대경로 /home/donghyeon/dev/... 사용):

1. wiki-claim-gate.PreToolUse
2. wiki-claim-gate.Stop
3. wiki-structure-gate.PreToolUse
4. wiki-structure-gate.PostToolUse

wiki-hard-gate(global ~/.gemini/antigravity-cli/hooks/...)는 정상 — 건드리지 않음.

핵심 미확정: Antigravity 가 hook command 를 어느 cwd 에서 실행하는지 불명(hook input payload 의 cwd 필드 ≠ command 실행 cwd). 따라서 단순 상대경로가 repo 루트로 resolve 된다고 가정 금지.

구현 전략 (진단 우선):

1. CWD 진단 — 임시 진단 command(예: pwd, git rev-parse --show-toplevel, env 를 파일에 기록)로 Antigravity hook 의 실제 실행 cwd·환경변수를 관측한다.
2. 경로 형태 확정 (portable-only 우선순위 사다리). 절대경로를 "올바른 현재 경로"로 교체하는 것은 같은 버그를 다른 절대경로로 연장할 뿐(이동·clone 시 재사망) → 임시 진단 외 최종안으로 채택 금지. 다음 우선순위로 확정한다:
   • 1순위: Antigravity 가 제공하는 workspace/repository 환경변수(있다면). 진단 §5-A1 로 존재 확인.
   • 2순위: git rev-parse --show-toplevel 로 repo root 도출.
   • 3순위: launcher 파일(.agents/hooks/run-wiki-hook.py)이 자기 파일 위치 기준으로 repo root 탐색 후 .claude/hooks/<script>.py 실행. shell expansion 미지원/불확실 시 이 방식.
   • 분기 규칙(구현 전 확정): 진단상 cwd == repo root 면 .agents/hooks.json 만 상대경로로 수정하고 launcher 불필요. cwd ≠ repo root 면 launcher 파일 추가를 허용하고 §5 allowlist 에 조건부 포함.
3. E2E 검증 — §5 A1 참조. 실제 Hook 실행 관측 전에는 구현 verdict = PARTIAL(DONE 금지).

되돌리기: git revert (config 1파일).

A2 — Codex 문서 오류 정정 (운영 문서)

대상: CLAUDE.md:82 (§2 Hooks bullet) 의 codex fallback 서술 — 현행 "project_doc_fallback_filenames 로 codex 가 본 CLAUDE.md 를 프로젝트 지침으로 읽음(AGENTS.md 중복 불필요)".

증거 경계 (중요): 이 정정의 증거는 Codex 의 project_doc_fallback_filenames 동작뿐이다. Codex 에 대해서만 단정하고, Antigravity 로딩 메커니즘을 이 증거로 확장하지 않는다.

변경 문구(취지):

Codex 는 루트 AGENTS.md 를 프로젝트 지침으로 로드한다. .codex/config.toml 의 project_doc_fallback_filenames = ["CLAUDE.md"] 는 해당 디렉터리에 AGENTS.md 가 없을 때만 쓰이는 fallback 이다. 루트 AGENTS.md 가 존재하는 현재 구조에서 Codex 가 CLAUDE.md 를 자동 프로젝트 지침으로 직접 선택한다고 가정해서는 안 된다. CLAUDE.md 는 Claude Code 용 전체 운영 지침이자 모든 모델 공통 운영-규칙 SSOT 로 유지되며, AGENTS.md(≤150줄 요약)가 이를 가리킨다.

Antigravity 진입점은 AGENTS.md:3 의 기존 self-claim("Antigravity CLI / Codex CLI ... 가 자동 로드")을 참조하되, 그 로딩 동작을 이 슬라이스에서 새로 certify 하지는 않는다(백로그: 3-플랫폼 로딩 검증).

범위 밖: 리뷰의 "AGENTS.md 를 단일 공통 진입점으로 만들고 core-invariants 분리" 는 아키텍처 → 백로그.

용어 주의: CLAUDE.md 를 무자격 "full SSOT" 로 부르지 않는다. 이 repo 엔 복수 SSOT 존재 — 운영 규칙=CLAUDE.md, agent system prompt SSOT=.agents/plugins/.../agents/*.md, rules=rules/*.md. 따라서 "운영-규칙 SSOT" 로 한정 표기한다.

A3 — wiki-doc-author 계약 결함 3종 (agent runtime contract)

세 결함이 3개 플랫폼 계열의 5개 수기-동기화 표현 파일에 불균등 분포. 사본마다 표현이 달라 개별 편집.

결함 D1 — 파일수 vs Parent 갱신 모순. "1 dispatch = 1 file" / "2개 이상 파일 수정 금지" 를 아래 명시적 허용 write set 으로 대체("트랜잭션" 추상어 대신 열거로 고정):

1 dispatch 는 정확히 하나의 target raw document 를 생성 또는 마이그레이트한다. 허용되는 write set 은 다음으로 제한한다:

• daily-note · project-note: target document 1개.
• 그 외 child category: target document 1개 + 그 문서가 직접 가리키는 Parent hub 1개 (## Cluster 링크 유지 목적에 한함).

다른 raw 문서 / rule / template / derived wiki 문서는 수정하지 않는다.

description 의 "Writes exactly 1 file" → "creates/migrates one target document (maintaining its Parent hub link)".

원자성 오해 방지(ACID 아님). 위 write set 은 논리적 change set 이며 기술적 atomic rollback 을 보장하지 않는다. target 또는 Parent 중 일부만 변경된 경우 — 단일 상태로 고정(실행 계약에서 "또는" 금지, 플랫폼별 상이 해석 차단):

• DONE 반환 금지 → Status = BLOCKED. (PARTIAL 은 현행 doc-author output schema 에 미정의 — DONE | NEEDS_CONTEXT | BLOCKED 뿐. PARTIAL 정식 도입은 B2 command-result-v1 로 이연.)
• 변경에 성공한 파일 + 실패한 단계를 모두 보고.
• 자동 rollback 은 구현된 경우에만 수행(현재 미구현 — 부분변경은 BLOCKED + 정직 보고).

(이는 기존 계약과 일관 — 본문 손실 시 BLOCKED 규칙이 이미 존재.)

결함 D2 — 카테고리 "7" 오기. SSOT·agent.json 의 "Category ∉ 7 허용" / "Category in 7 allowed" → 8. 허용 8종: branch-note, error-note, interview-prep, job-posting, blog-topic, lecture-note, project-note, daily-note.

결함 D3 — validator 개수 하드코딩 제거(8→7 금지). agent.json 의 ... (8개 모두) 를 숫자 7로 바꾸지 않는다 — 검증 "그룹" 수와 실제 shell command 수가 달라 재-stale 위험. 대신 숫자를 제거:

Post-Write Validator: 아래 정의된 모든 적용 가능 항목을 실행하고 실제 결과를 첨부한다.

출력 schema 도 {{위 Validator 의 모든 적용 가능 항목 실행 결과}} 로.

플랫폼 팬아웃 (수기 — 생성기 부재):

표현 파일	계열	D1	D2	D3
.claude/agents/wiki-doc-author.md	Claude(md)	有	無(이미 8)	無
.agents/plugins/wiki-superpowers/agents/wiki-doc-author.md	plugin SSOT(md)	有	有	편집 시 확인
.codex/agents/wiki-doc-author.md	Codex(md)	有	無(이미 8)	편집 시 확인
.codex/agents/wiki-doc-author.toml	Codex(toml)	有	無(이미 8)	편집 시 확인
.agents/agents/wiki-doc-author/agent.json	Antigravity(json)	有	有	有

각 사본 개별 Read → 해당 결함만 정밀 편집. 의미(계약)만 바꾸고 나머지 프롬프트 구조 보존. migrate 본문-보존 계약은 변경하지 않음(정상).

범위 밖: doc-author 를 중립 정의+생성기로 만드는 것(B1). 이번엔 기존 5표현 수기 정합화.

A4 — 인벤토리 숫자 정정 (운영 문서)

권위값 산출 명령(고정, 2026-07-14 실측 스냅샷):

find templates -maxdepth 1 -type f -name '*.md' | wc -l                              # 27
find rules -maxdepth 1 -type f -name '*.md' | wc -l                                  # 14
find .claude/agents -maxdepth 1 -type f -name '*.md' | wc -l                         # 12
find .agents/agents -mindepth 2 -maxdepth 2 -type f -name 'agent.json' | wc -l       # 10 (Antigravity executable)
find .agents/plugins/wiki-superpowers/agents -maxdepth 1 -type f -name '*.md' | wc -l # 10 (agent-prompt SSOT)
find .claude/commands -maxdepth 1 -type f -name '*.md' | wc -l                       # 23

주의: .agents/agents(=10, executable registry)와 .agents/plugins/.../agents(=10, prompt SSOT)는 물리적으로 별개인 두 디렉터리이며 각각 10개다. "10 공유" 로 합쳐 쓰지 않는다.

live 문서 정정 대상 (repo-wide grep 으로 확정, historical 제외):

대상	현재(stale)	정정
AGENTS.md:23	templates "14개"	27개
AGENTS.md:24	rules "7개 rule"	14개 rule
AGENTS.md:50	"7 agents ... 정의"	10 agents (7 core + branch-depth-auditor·coverage-auditor·wiki-consistency-auditor)
CLAUDE.md:79	"동일 9개 agent" / "(위 7개 + branch-depth-auditor·coverage-auditor)"	10개 / "(위 7개 + branch-depth-auditor·coverage-auditor·wiki-consistency-auditor)"
CLAUDE.md:79	"scripts/ 디렉터리 자체 부재"	"scripts/ 존재(deep-research), sync_automation.py 만 부재"
.codex/agents/README.md:9	"scripts/ 디렉터리 자체 부재"	동상 정정
.agents/plugins/wiki-superpowers/README.md:11	"the scripts/ directory itself is absent"	"scripts/ exists (deep-research); only sync_automation.py is absent"
.agents/plugins/wiki-superpowers/README.md:46	"동일한 7개 rule 파일"	14개 rule 파일

CLAUDE.md:81 은 "생성기 부재(2026-06-06 확인)"만 서술 — 여전히 참이므로 변경하지 않음. docs/superpowers/plans/*·notes/* 의 동일 문구는 dated 기록이라 정정 대상 아님(역사 보존).

자동 치환 금지: "14개"/"7개" 는 다른 의미로도 쓰이므로, repo-wide grep 후보는 수동 판정해 inventory 문맥만 편집.

스냅샷 명시: 정정 위치(또는 인접)에 "2026-07-14 실측 수기 스냅샷, B1 생성기 도입 전까지 수기 관리" 취지 1줄 병기.

트레이드오프(인지): B1 이 훗날 자동 생성 시 A4 는 버려질 작업. 현재 오독 유발 중이라 지금 정정.

5. 검증 계획

항목별:

항목	검증
A1	(1) python3 -m json.tool .agents/hooks.json 통과. (2) Antigravity 실제 Tool 이벤트에서 4개 hook 실행 관측 + 의도한 PASS/BLOCK 이 Antigravity 에 전달됨을 로그로 확인. (3) 직접 스크립트 실행만 통과했으면 DONE 아닌 PARTIAL.
A2	grep -n "AGENTS.md 중복 불필요" CLAUDE.md → 0. 새 문구 존재. Antigravity 단정 없음 확인.
A3	아래 grep 으로 5표현 잔존 0 + 의미 패리티 표(아래) 전 PASS. python3 -m json.tool .agents/agents/wiki-doc-author/agent.json 및 tomllib 로 .codex/agents/wiki-doc-author.toml 구문 통과.
A4	위 find 명령 재실행값 == 문서값. repo-wide stale grep(§4 A4) 에서 live 문서 잔존 0(historical 제외).

A1 Hook별 E2E 트리거 표 (구현자가 각 hook 을 어떤 이벤트로 발생시킬지 명시):

Hook	발생시킬 이벤트	기대 결과
claim gate PreToolUse	Write 또는 Edit 실행	hook process 실행 로그 확인
claim gate Stop	Agent 실행 정상 종료	종료 hook 실행 로그 확인
structure gate PreToolUse	Markdown 대상 Write/Edit 실행	pre 검사 실행 확인
structure gate PostToolUse	Markdown 쓰기 완료	post 검사 실행 확인
차단 검증	의도적으로 규칙 위반한 임시 입력	비정상 종료코드 또는 BLOCK 전달
정상 검증	규칙 만족하는 임시 입력	PASS 후 작업 계속

검증용 임시 파일을 repo 내부에 생성했다면 테스트 후 삭제 — 최종 git diff 에 남지 않아야 함.

A3 잔존-문구 grep (넓힘):

grep -RInE '1 dispatch = 1 file|Writes exactly 1 file|Write 1 file|write the file once|2개 이상 파일|여러 파일을 한 번에 생성.?수정 금지|여러 파일 동시 생성.?수정 금지|Category ∉ 7|Category in 7 allowed|8개 모두' \
  .claude/agents/wiki-doc-author.md \
  .codex/agents/wiki-doc-author.md \
  .codex/agents/wiki-doc-author.toml \
  .agents/plugins/wiki-superpowers/agents/wiki-doc-author.md \
  .agents/agents/wiki-doc-author/agent.json
# 기대: 0 hit. 이후 새 write-set 계약 문구 존재도 각 파일에서 확인.

A3 의미 패리티 표 (grep 만으로 불충분 — 계약 동등성 확인):

Contract	Claude md	plugin SSOT md	Codex md	Codex toml	agent.json
target document 1개
Parent hub edit 허용
unrelated 문서 edit 금지
허용 category = 8
validator 개수 비고정
migrate 본문 보존 유지

(각 셀 PASS 확인. 문장은 달라도 계약값은 동일해야 함.)

구문 검증 (grep 통과 ≠ 유효 문법):

python3 -m json.tool .agents/hooks.json >/dev/null
python3 -m json.tool .agents/agents/wiki-doc-author/agent.json >/dev/null
python3 -c 'import tomllib; tomllib.load(open(".codex/agents/wiki-doc-author.toml","rb")); print("toml OK")'

기존 hook test 회귀 (존재 확인됨):

python3 -m pytest .claude/hooks -q   # test_wiki_structure_lint / _consistency_check / _claim_gate 등

git-diff allowlist (범위 이탈 감시): 아래 10개 파일(+ 본 spec) 외 변경 시 중단·사유 확인.

.agents/hooks.json
CLAUDE.md
AGENTS.md
.codex/agents/README.md
.agents/plugins/wiki-superpowers/README.md
.claude/agents/wiki-doc-author.md
.agents/plugins/wiki-superpowers/agents/wiki-doc-author.md
.codex/agents/wiki-doc-author.md
.codex/agents/wiki-doc-author.toml
.agents/agents/wiki-doc-author/agent.json
# 조건부(A1 launcher 경로 채택 시에만):
.agents/hooks/run-wiki-hook.py

검증: git diff --name-only 가 위 집합에 한정(launcher 미채택 시 11번째 파일은 나오면 안 됨). 검증용 임시 진단/테스트 파일은 최종 diff 에 잔존 0.

전역 주의: 편집 대상이 config/문서/프롬프트라 기존 hook(claim gate·structure lint)이 편집 자체를 차단할 수 있음 — 차단 시 사유 확인 후 우회 아닌 정합 편집으로 해결.

6. 리스크 & 롤백

변경 종류 분류:

항목	변경 종류
A1	Hook runtime configuration 변경
A2	운영 문서 사실 정정
A3	agent runtime contract 변경(Parent edit 이 STOP 위반→허용)
A4	운영 문서 인벤토리 정정

• A1·A3 는 런타임 계약을 바꾼다. A1 은 hook 실행 경로, A3 는 doc-author 의 허용 write set. 순수 문서 변경은 A2·A4 뿐.
• A1 불확실성: 대상 Python 경로가 무효인 것은 CONFIRMED 이나, Antigravity 의 command-실패 처리 (fail-open/closed)는 미확인 — "현재도 dead 라 악화 없음" 으로 단정하지 않는다. 변경 전후 실제 hook 이벤트/오류 동작을 비교해 판단.
• A2·A4 는 문서 텍스트 — git revert 즉시 롤백.
• 3-플랫폼 패리티: A3 은 5표현을 손으로 맞춰야 함. 하나라도 누락 시 새 드리프트 — §5 grep·패리티 표를 5표현 전부에 실행해 방지.

7. 백로그 (이번 슬라이스 밖 — 기록만)

Tier B (근거 있음, 각자 프로젝트, 별도 spec):

• B1: SSOT 생성기 복원(generate_harness.py + drift check). 최고 레버리지·최대 빌드. A4 흡수. 기존 드리프트 선(先) 정합 필요.
• B2: 3-채널 출력(command-result-v1 + run ledger + 사용자 응답 15줄화). 모든 명령/에이전트 접촉.
• B3: deep-research 런타임 하드닝(subprocess timeout[현재 부재 확인] + retry + resume + cache + stderr 보존).
• B4: 훅 증분화 + wiki-index.json. 현재 rglob("*.md") 전체 순회 확인됨.
• (신규) 3-플랫폼 project-지침 로딩 검증 — Codex/Antigravity 가 실제로 어느 파일을 로드하는지 E2E 확인.

Tier C (opinionated/위험/저ROI — wholesale 비권장):

• harness/ 메가 재구조화 — 동작하는 3-플랫폼 레이아웃 폐기. 아이디어만 선별 채택.
• rules→skills wholesale + template-v2(27개 전부). "컨텍스트 과다" 전제는 사실이나 fix 침습적. B1 이후 점진.

8. 완료 기준

A1

• .agents/hooks.json 대상 command 4개 전부 수정 + JSON 구문 통과.
• 최종 경로 방식이 portable(env var / git rev-parse / launcher self-locate) — 새 하드코딩 절대경로 0.
• launcher 채택 시 .agents/hooks/run-wiki-hook.py 만 추가되고 allowlist 에 포함(그 외 신규 파일 0).
• Antigravity 실제 Tool 이벤트에서 각 hook 실행 관측(§5 A1 표 6행) + 의도한 PASS/BLOCK 전달 확인.
• 직접 Python 실행만 성공 시 구현 verdict = PARTIAL(DONE 아님).

A2

• Codex fallback 설명이 실제 동작과 일치.
• 검증 안 된 Antigravity 자동로딩 단정 없음.
• "AGENTS.md 중복 불필요" 기존 문구 0건.
• CLAUDE.md 를 "운영-규칙 SSOT" 로 한정 표기(무자격 "full SSOT" 아님).

A3

• 5표현 전부 "target 1개 + Parent link 유지" 계약으로 정합, 허용 write set 명시.
• 부분 실패 시 DONE 금지 규칙 존재.
• 허용 category 8 통일, validator 개수 하드코딩 제거.
• JSON·TOML 구문 통과.
• migrate 본문-보존 계약 불변.
• 의미 패리티 표 전 셀 PASS.

A4

• 모든 숫자를 고정 find 명령으로 재산출.
• repo-wide stale 검색 수행, live 문서 잔존 0(historical 제외).
• .agents/agents(10)와 .agents/plugins/.../agents(10)를 별개 디렉터리로 구분 표기.
• 2026-07-14 수기 스냅샷·B1 자동화 예정 명시.

전역

• git diff --name-only 가 §5 allowlist 10파일(+spec)에 한정.
• 범위 밖 구조 변경 없음.
• python3 -m pytest .claude/hooks -q 통과.