353 lines
22 KiB
Markdown
353 lines
22 KiB
Markdown
---
|
|
title: 하네스 정합성 스위프 (Tier A) — 설계
|
|
date: 2026-07-14
|
|
status: draft
|
|
kind: design-spec
|
|
slice: 1-of-N (harness review 적용)
|
|
revision: 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 실측 스냅샷):**
|
|
```bash
|
|
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 (넓힘):**
|
|
```bash
|
|
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 통과 ≠ 유효 문법):**
|
|
```bash
|
|
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 회귀 (존재 확인됨):**
|
|
```bash
|
|
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` 통과.
|