init: llm-wiki-haness 하네스 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: Phase 1 — 경험적 포맷·충돌 확인 (codex skills / antigravity workflows)
|
||||
date: 2026-06-04
|
||||
---
|
||||
|
||||
# Phase 1 경험적 확인 결과
|
||||
|
||||
## CLI 설치 상태 (실측)
|
||||
|
||||
- **codex-cli 0.136.0** 설치됨 (`~/.nvm/.../bin/codex`).
|
||||
- **agy (Antigravity CLI)** 설치됨 (`~/.local/bin/agy`), home `~/.gemini/antigravity-cli/`.
|
||||
|
||||
## codex skills
|
||||
|
||||
- codex 0.136.0 에는 `skills` 전용 subcommand 가 **없음** (subcommands: exec/review/login/logout/mcp/plugin/mcp-server). skill 은 **자동 디스커버리 + TUI `/skills`·`$name`** 로 surface 되는 대화형 기능이라 비대화형 목록 확인 불가.
|
||||
- 공식 디스커버리 경로(`developers.openai.com/codex/skills`): `$REPO_ROOT/.agents/skills/<name>/SKILL.md`. → **타깃 경로 확정: `.agents/skills/<cmd>/SKILL.md`.**
|
||||
- `codex plugin` 은 marketplace 기반의 **별개 메커니즘**(skill 과 무관).
|
||||
|
||||
## antigravity workflows / skills
|
||||
|
||||
- **로딩 모델 = `agy plugin` import.** `agy plugin list` 출력:
|
||||
```json
|
||||
{ "imports": [ { "name": "wiki-superpowers", "source": "local-install", "importedAt": "2026-05-26T12:39:39Z", "components": ["installed"] } ] }
|
||||
```
|
||||
→ `.agents/plugins/wiki-superpowers/` 가 import 되어 있음. 즉 antigravity 는 workspace `.agents/` 를 (프로젝트 열림 시 native 인식 + plugin import) 로 적재.
|
||||
- 공식(Google Codelab) 기준 workflow 경로 = workspace `.agents/workflows/<name>.md`, frontmatter `description` 만, `/name <args>` 호출.
|
||||
- → **타깃 경로 확정: `.agents/workflows/<cmd>.md`** (repo `.agents/` 복수 규약 일치).
|
||||
- **운영 주의**: 생성/수정 후 antigravity 가 변경을 반영하려면 `agy plugin` 재import 또는 프로젝트 재오픈이 필요할 수 있음(plugin-import 모델). workspace 직접 native 인식 여부는 build/version 의존.
|
||||
|
||||
## `$ARGUMENTS` 매핑
|
||||
|
||||
- codex skills·antigravity workflows **둘 다 인자 placeholder 미지원** → argument-hint 의 각괄호 prose 로 치환 확정.
|
||||
|
||||
## 충돌(`.agents/skills/` 이중 로드) 확인
|
||||
|
||||
| 항목 | 결과 |
|
||||
|---|---|
|
||||
| codex 가 `.agents/skills/` 읽음 | YES (공식 디스커버리 경로) |
|
||||
| antigravity 가 `.agents/skills/` 도 skill 로 읽는지 | **UNVERIFIED (비대화형 확인 불가).** antigravity 는 `.agents/plugins/.../skills/` 를 plugin 으로 적재 중 — workspace `.agents/skills/`(plugin 밖) 직접 적재 여부는 build 의존. |
|
||||
| 위험도 | **낮음.** 설령 antigravity 가 codex command-skill 을 semantic skill 로 이중 인지해도, 같은 command 의 workflow(`/cmd`)와 기능 중복일 뿐 충돌 아님. 실사용에서 문제되면 codex skill 을 plugin 밖 `.agents/skills/` 에만 두고 antigravity 는 workflow 만 쓰도록 build 설정으로 분리. |
|
||||
|
||||
## 결정 (잠금)
|
||||
|
||||
| 항목 | 결정 |
|
||||
|---|---|
|
||||
| codex skill 경로 | `.agents/skills/<cmd>/SKILL.md` |
|
||||
| antigravity workflow 경로 | `.agents/workflows/<cmd>.md` |
|
||||
| `$ARGUMENTS` | argument-hint 각괄호 prose 치환 |
|
||||
| 이중 로드 | UNVERIFIED·저위험 — 생성 후 Task 5 에서 실호출로 재확인, 문제 시 에스컬레이션 |
|
||||
|
||||
## Task 5 — 실호출 스모크 결과
|
||||
|
||||
- skill(`/skills`·`$name`)·workflow(`/name`) 등록은 **두 CLI 모두 대화형(TUI) 기능**이라 헤드리스(비대화형) 완전 검증 불가. codex 0.136.0 에 skills 목록 subcommand 없음, agy 도 마찬가지.
|
||||
- 대신 **포맷 정합성**을 결정론적으로 검증 완료: 13개 skill 전부 frontmatter `name`(=폴더명)+`description`, body 에 `$ARGUMENTS` 0개; 13개 workflow 전부 frontmatter `description` + 본문 `/<cmd> <hint>` 호출 안내, `$ARGUMENTS` 0개. `sync_automation.py commands --check` exit 0.
|
||||
- **workflow 적재**: workspace `.agents/workflows/` 는 Codelab 기준 antigravity 가 프로젝트 열림 시 native 인식(plugin import 와 별개). plugin(`agy plugin`)은 `.agents/plugins/wiki-superpowers/`(agents/skills/hooks) 적재용이며 workspace `.agents/workflows/` 와 무관.
|
||||
- **라이브 TUI 호출 검증은 사용자 대화형 사용으로 위임** — codex TUI 에서 `$depth`/`/skills`, antigravity TUI 에서 `/depth` 가 뜨는지 실사용 시 확인. 안 뜨면 본 노트의 경로/frontmatter 와 대조.
|
||||
- 이중 로드(`.agents/skills/` 를 antigravity 도 읽는지)는 여전히 UNVERIFIED·저위험 — 실사용에서 `/skills` 목록에 codex command-skill 이 함께 뜨면 그때 분리 결정.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Phase 2 — antigravity 훅 커버리지 점검
|
||||
date: 2026-06-04
|
||||
---
|
||||
|
||||
# antigravity 훅 커버리지 (실측)
|
||||
|
||||
## 현재 antigravity 훅: `wiki_hard_gate.py`
|
||||
|
||||
- 위치: `~/.gemini/antigravity-cli/hooks/wiki_hard_gate.py` (global), `.agents/hooks.json` 이 PreToolUse matcher `*` 로 가리킴.
|
||||
- **강제 대상**: `docs/superpowers/specs/*.md` 리포트 출력 품질 (SKILL.md Output-Format Hard Gate subset):
|
||||
- G1 §7.1 self-grep proof (V/N 비율 + 실제 grep 명령)
|
||||
- G2 Contract 7 금지 마케팅어 ("100%/완벽/극한/절대로/최강/..." )
|
||||
- G3 `Verdict: COMPLETE` 시 §3-1 공식 유도
|
||||
- G4 findings ≥5 시 `## 4-1 Adversarial Review` 필수
|
||||
- 입력/출력 어댑터 보유: Antigravity protobuf(`tool_call.{name,input}`, `write_to_file`/`edit_file`/`run_command`/`bash`) + Gemini CLI(`tool_name`/`tool_input`, `{decision}`) 양쪽 처리. 미인식 → fail-open.
|
||||
|
||||
## 갭 (Claude / codex 와 비교)
|
||||
|
||||
| 검사 | Claude (`.claude/`) | codex (`.codex/hooks.json`) | antigravity |
|
||||
|---|---|---|---|
|
||||
| report 품질 게이트 | (SKILL.md) | (skill 본문) | 있음 (`wiki_hard_gate.py`) |
|
||||
| claim 추적성 (raw source claims / branch decision→claim / wiki FACT 분리) | 있음 (`wiki_claim_gate.py` PreToolUse) | wired (trust 시) | **없음** |
|
||||
| 구조 린트 (template 섹션·frontmatter·Parent·broken link, C2) | 있음 (`wiki_structure_lint.py` PostToolUse) | wired (trust 시) | **없음** |
|
||||
|
||||
→ antigravity 는 리포트 품질은 강제하지만 **claim_gate·structure_lint 의 강제가 없다.**
|
||||
|
||||
## 권고 (별도 follow-up — 본 세션에서 미실행 이유)
|
||||
|
||||
> **Update (2026-07-14):** 아래 1~3 항(출력 어댑터 · payload 어댑터 · `.agents/hooks.json` 배선)은 **이후 구현·활성 완료**됐다. 현재 `.claude/hooks/wiki_claim_gate.py`(`--antigravity` → stdout `{decision:"deny", reason}`, exit 0)와 `.claude/hooks/wiki_structure_lint.py`(`--antigravity` `_dispatch_hook` 동일 어댑터)가 antigravity 출력 규약을 지원하고, `.agents/hooks.json` 에 `wiki-claim-gate`(PreToolUse+Stop)·`wiki-structure-gate`(PreToolUse+PostToolUse) 가 `enabled: true` 로 배선돼 있다. **남은 것은 4항(fail-open 검증)을 포함한 실제 Antigravity 런타임 hook E2E 검증** 뿐이며, 그때까지 상태는 *experimental* 이다. 아래 원문은 2026-06-04 시점 실측 기록으로 보존한다.
|
||||
|
||||
claim_gate / structure_lint 를 antigravity 로 포팅하려면:
|
||||
|
||||
1. **출력 어댑터**: Claude 규약(exit 2 + stderr) → antigravity `{decision:"deny", reason}` JSON. 단일 SSOT 유지하려면 두 스크립트에 `--emit antigravity` 모드 추가.
|
||||
2. **payload/content 어댑터**: antigravity `tool_call.input.content`/`arguments` 에서 쓰기 내용 추출 (`wiki_hard_gate.py` 의 `get_write_content` / `get_target_path` 패턴 차용).
|
||||
3. `.agents/hooks.json` 에 PreToolUse 항목 추가 (claim_gate = blocking, structure_lint = advisory always-allow).
|
||||
4. **fail-open 철저 검증** — matcher `*` 전역 훅이라 버그 시 antigravity 쓰기 전체 차단(blast radius 큼). 미인식·에러 시 반드시 allow.
|
||||
|
||||
**미실행 이유**: 전역 high-blast-radius 훅을 "인라인 빠른" 패스에서 성급히 추가하면 사용자의 antigravity 작업을 막을 위험. 별도의 신중한 패스(어댑터 + 충분한 fail-open 테스트)로 권고. 그동안 antigravity 에서도 agents/skills/workflows 의 Mandatory First Reads 가 rules 정독을 지시하므로 soft 강제는 존재.
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Phase 2 — codex 훅 payload·차단 규약 경험적 캡처
|
||||
date: 2026-06-04
|
||||
---
|
||||
|
||||
# codex 0.136.0 훅 실측 결과
|
||||
|
||||
## 훅 지원 여부
|
||||
|
||||
- codex 0.136.0 은 **훅 기능 보유**. 근거: `codex exec --help` 에 `--dangerously-bypass-hook-trust` ("Run enabled hooks without requiring persisted hook trust for this invocation. DANGEROUS.") 플래그 존재.
|
||||
- 즉 훅은 **trust(신뢰) 게이트** 가 있다 — repo 의 `.codex/hooks.json` 은 신뢰 등록 전엔 실행되지 않음(임의 명령 실행 방지 보안).
|
||||
|
||||
## 실측 (probe 캡처 시도 3회)
|
||||
|
||||
- `.codex/hooks.json` 에 PreToolUse/PostToolUse(matcher `*`) → stdin 덤프 probe 를 걸고 `codex exec` 로 shell tool(`ls`) 실행.
|
||||
- 결과: **shell tool 은 실행됐으나(출력 정상) probe 훅은 한 번도 안 뜸** — `--dangerously-bypass-approvals-and-sandbox` + `--dangerously-bypass-hook-trust` 동시 적용에도 미발화.
|
||||
- `codex doctor` 출력에 hooks 섹션 없음(config/auth/mcp/updates/reachability 만 보고).
|
||||
|
||||
## 해석
|
||||
|
||||
- **`codex exec`(비대화형/automation) 모드는 project-local 훅을 로드하지 않는 것으로 보임** — exec 는 자동화용이라 신뢰 안 된 repo 훅을 건너뛰는 보안 설계로 추정. 훅은 **대화형 `codex` TUI 에서 repo 진입 시 trust 프롬프트로 활성화**되는 구조로 판단(공식 hooks 문서의 project-local 지원과 일치하되, exec 경로에선 비활성).
|
||||
- 환경 제약도 있었음: 이 샌드박스가 bubblewrap user namespace 를 못 만들어 `-s read-only` 에선 shell 자체가 실패(별도 우회 필요).
|
||||
|
||||
## 결정 (Task 3 반영)
|
||||
|
||||
- `.codex/hooks.json` 을 **공식 문서 포맷**으로 작성(forward-compatible). PreToolUse(claim_gate) + PostToolUse(structure_lint --hook), matcher 는 Edit/Write 계열.
|
||||
- **활성화는 대화형 codex 에서 hook trust 승인 필요** — 본 repo 첫 진입 시 codex 가 신뢰를 물음. `codex exec` 자동화에선 미발화 가능(문서에 명시).
|
||||
- 차단 규약/payload 필드는 미캡처 → claim_gate 는 이미 멀티-variant 리더(`tool_name`/`tool_call.name`/`hook_event_name`)라 Claude/codex 공통 필드면 동작. 첫 신뢰 실행에서 실거동 확인 권장.
|
||||
- 구조/claim 강제는 훅 외에도 `/depth`(skill·workflow)·`/lint` 가 동일 스크립트를 직접 호출하므로 훅 미발화 상황에서도 우회 수단 존재.
|
||||
Reference in New Issue
Block a user