init: llm-wiki-haness 하네스 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,49 @@
|
||||
wiki 내용을 블로그 글감과 초안 구조로 변환합니다.
|
||||
|
||||
**대상:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **소스 식별 (canonical만)**
|
||||
- 인자가 경로면 **`wiki/concepts/` 또는 `wiki/projects/`만** 허용. 다른 경로 입력 시 **중단**.
|
||||
- 인자가 주제면 `/query`로 canonical 문서 수집. raw 직접 참조 금지.
|
||||
- `raw/blog-topics/`나 `raw/job-postings/`가 출발점이면 먼저 `/ingest` 또는 수동 정제로 canonical 문서를 만든 뒤 진행.
|
||||
|
||||
2. **상태 게이트 (차단)**
|
||||
- 소스 문서 status가 `reviewed | verified | published-ready` 중 하나가 **아니면 중단**.
|
||||
- 사용자에게 안내: "원천 문서를 `reviewed` 이상으로 승급한 후 다시 실행하세요."
|
||||
|
||||
3. **`/lint` 사전 검증**
|
||||
- 출처 없는 단정, 공식/사례 혼동, 과장 표현 사전 점검
|
||||
- 발견되면 변환 전에 보고
|
||||
|
||||
4. **blog 문서 생성** — `templates/blog-template.md` 적용 (자체 inline template 금지)
|
||||
- 대상 경로: `wiki/blog/<제목-slug>-YYYY-MM-DD.md` (날짜 suffix 권장 — drafts vs published 구분)
|
||||
- **`templates/blog-template.md` 를 Read 후 그대로 사용.** placeholder (`<title>`, `<...>`) 만 사용자 입력으로 치환.
|
||||
- frontmatter 필수 필드 (template 명세 그대로):
|
||||
- `source_type: blog` (NOT `llm-generated` — blog 는 derived canonical 의 status_label 로 outline → drafting → review → ready → published 로 진화)
|
||||
- `status: draft` (시작값)
|
||||
- `status_label: outline` (시작값)
|
||||
- `audience: backend-engineer | senior-engineer | tech-lead | general` (사용자 입력 또는 default `backend-engineer`)
|
||||
- `canonical_sources: []` — 게시 전 채워야 함 (Step 5 게시 체크리스트)
|
||||
- `tags: [blog, ...]` — L1 tag 로 `blog` 명시, 그 외는 taxonomy 따름
|
||||
- `target_publish:` (선택, 게시 예정일)
|
||||
- 본문 섹션 구성은 `templates/blog-template.md` 를 **Read 한 결과가 SSOT** — 인라인 목록을 두지 않는다(이미 한 번 drift 됨). 명령 고유 규칙(아래 ## 규칙)만 여기 유지.
|
||||
|
||||
5. **초안은 사람이 작성**
|
||||
- 이 명령은 **template scaffold + canonical Sources 채움** 만. 본문 초안 자동 생성 X.
|
||||
- Parent/부모 섹션의 canonical wikilink 는 자동 채움 (Step 1 에서 식별된 소스, 헤더는 template Read 결과를 따름).
|
||||
- 본문은 사람이 쓰고, 필요 시 다시 `/lint`로 검증.
|
||||
- 본문은 한국어로 쓰고 개발 용어만 원문(영어)을 유지한다. 문장 단위 윤문은 여기서 하지 않고, 작성이 끝난 뒤 im-not-ai(`/humanize-korean`)로 묶어서 처리한다(`rules/prose-style.md` §3).
|
||||
|
||||
6. **로그 기록**
|
||||
- `wiki/log.md`: `YYYY-MM-DD HH:mm /blogify — <소스> → <blog 경로>`
|
||||
|
||||
## 규칙
|
||||
|
||||
- **template 파일 그대로 사용.** inline template 작성 금지 (`templates/blog-template.md` 와 drift 발생 위험).
|
||||
- **프로젝트 사실은 `actually-implemented` / `locally-verified` / `prod-verified`만 사용.**
|
||||
- 공식 개념과 내 해석을 분리해서 글 구조에 반영 (template 의 "사실 vs 의견 구분" 섹션 활용 — 정확한 헤더는 template Read 결과를 따름).
|
||||
- 글 제목 후보는 과장 표현(`완벽한`, `궁극의`, `X배 빠른`) 사용 금지.
|
||||
- 새 blog 문서의 Parent/부모 와 Sources/근거 섹션(정확한 헤더는 template Read 결과)에 **반드시** `[[wiki/concepts/...]]` 또는 `[[wiki/projects/...]]` canonical 링크 포함. `/lint`가 이를 검사.
|
||||
- frontmatter `canonical_sources` 배열은 사용자가 `status_label: ready` 직전 채워야 함 (게시 전).
|
||||
@@ -0,0 +1,48 @@
|
||||
project 실행계획의 Work Item을 결정론 runtime으로 branch-note에 적용합니다.
|
||||
|
||||
**입력:** {{arguments}}
|
||||
|
||||
## 실행 계약
|
||||
|
||||
- 이 workflow는 `harness/runtime/branch_from_project.py`의 얇은 wrapper다.
|
||||
- project 표나 decision registry를 직접 파싱하지 않는다.
|
||||
- branch 문서, Work Item 상태, parent MOC를 직접 작성하거나 수정하지 않는다.
|
||||
- runtime 실패를 임의 보정하거나 같은 로직을 자연어로 재구현하지 않는다.
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. 인자가 project slug와 `WI-<PROJECT>-NNN` 두 값인지 확인한다. 값이 없거나 두 개가 아니면 사용법만 보고하고 종료한다.
|
||||
2. runtime이 선택한 parent project의 **current hub semantic certificate**를 status와 무관하게 검사한다. 직접 우회하지 않는다. 독립 재현 명령은 다음과 같다.
|
||||
|
||||
```bash
|
||||
python3 harness/runtime/semantic_certificate.py --root . --check --mode hub --path raw/project-notes/<project>.md
|
||||
```
|
||||
|
||||
`SEMANTIC_CERTIFICATE_MISSING`, `SEMANTIC_CERTIFICATE_STALE`, semantic blocking verdict, certificate에 bind된 typed graph drift 중 하나라도 있으면 branch 생성을 중단한다.
|
||||
3. 다음 dry-run을 실행한다. `branch_from_project.py`도 같은 parent certificate 검사를 내부에서 수행하므로 wrapper 문구만으로 통과시킬 수 없다.
|
||||
|
||||
```bash
|
||||
python3 harness/runtime/branch_from_project.py <project> <WI-ID> --dry-run
|
||||
```
|
||||
|
||||
4. exit code가 0이고 JSON의 `schema_version`이 `branch-from-project-result/v1`, `status`가 `DRY_RUN`인지 확인한다. `plan_sha256`이 64자리 소문자 SHA-256이 아니면 쓰지 않고 종료한다.
|
||||
5. dry-run이 반환한 `plan_sha256`을 그대로 사용해 다음 apply를 한 번 실행한다.
|
||||
|
||||
```bash
|
||||
python3 harness/runtime/branch_from_project.py <project> <WI-ID> --apply --expected-plan-sha256 <plan_sha256>
|
||||
```
|
||||
|
||||
6. exit code가 0이고 JSON의 `schema_version`이 `branch-from-project-result/v1`, `status`가 `APPLIED`이며 `plan_sha256`이 dry-run 값과 같은지 확인한다. generated-only scaffold의 local semantic audit는 이 단계에서 꾸며내지 않고 `/branch-spec`까지 명시적으로 유예한다.
|
||||
7. 성공 시 **APPLIED JSON에 존재하는 필드만** 짧게 요약하고 `/branch-spec <branch>`를 다음 단계로 안내한다. 실패 시 runtime 오류를 그대로 보고하고 추가 쓰기나 보정을 수행하지 않는다.
|
||||
|
||||
## 금지 사항
|
||||
|
||||
- project 또는 Work Item Markdown 직접 해석
|
||||
- template 복사나 placeholder 치환
|
||||
- branch 파일 직접 생성·수정
|
||||
- Work Item status 또는 generated MOC 직접 수정
|
||||
- dry-run 없이 apply 실행
|
||||
- `--expected-plan-sha256` 생략 또는 임의 값 사용
|
||||
- 실패 후 partial write 정리나 수동 재시도
|
||||
- parent hub certificate 검사 생략 또는 stale certificate로 branch 파생
|
||||
- `wiki/log.md` 기록
|
||||
@@ -0,0 +1,120 @@
|
||||
`/branch` 로 만든 빈 브랜치 노트를 **되묻지 않을 수준으로 채우는** 오케스트레이터입니다.
|
||||
source claim 에서 결정 후보·대안 비교를 도출하고, 근거 없는 결정은 **먼저 자동조사**한 뒤 그래도 없으면 `UNSUPPORTED_DECISION` 으로 라벨링하고, 끝에 `/depth` 로 깊이를 검증합니다.
|
||||
|
||||
**브랜치 이름:** {{arguments}}
|
||||
|
||||
## 참조 (작업 시 정독)
|
||||
|
||||
- `rules/subagent-input-contracts.md` — 본 명령 + dispatch 할 agent 들의 입력 계약
|
||||
- `rules/branch-depth-gate.md` — 끝에 적용할 깊이 판정 4축(R1~R4)
|
||||
- `rules/coverage-gate.md` — 끝에 적용할 완전성 판정(빠진 관심사 3단계). depth 의 짝
|
||||
- `rules/consistency-contract.md` — project decision 상속, revision pin, override 선언 규칙
|
||||
- `templates/branch-note-template.md` — 채울 대상 구조(특히 `## 결정-근거 매핑`, `## 구현 가이드`)
|
||||
- `CLAUDE.md` §11, §15 — 근거 없는 결정 금지, 근거 기반 구현 명세
|
||||
|
||||
### ca-tmpl 구현·계약 ground truth (필수 — §2 에서 읽음, 읽기 전용)
|
||||
|
||||
이 wiki 의 branch-note 는 별도 레포 **`/home/donghyeon/workspace/ca-tmpl`** 의 *설계·계약 rationale 층*이다 (ca-tmpl `CLAUDE.md` HARD-STOP #8: 구현 종료 시 이 wiki 의 branch-note 갱신 의무 — 코드↔노트 양방향 결합). 명세를 추측이 아니라 **실제 구현·계약에 정합**시키려면 다음을 본다:
|
||||
|
||||
- `/home/donghyeon/workspace/ca-tmpl/CLAUDE.md` + `AGENTS.md` + 해당 `src/<module>/CLAUDE.md` — 아키텍처 HARD-STOP, module map, 레이어 규칙.
|
||||
- `/home/donghyeon/workspace/ca-tmpl/docs/registries/*.yaml` — **계약 값의 SSOT**: `error-codes.yaml`(category enum·code·owner_branch·owner_layer·client_safe), `env-keys.yaml`, `headers.yaml`, `metrics.yaml`, `mdc-keys.yaml`, `capabilities.yaml`, `secrets-classification.yaml`. 각 row 의 `owner_branch:` 가 그 계약을 정한 branch-note 를 가리킨다.
|
||||
- `/home/donghyeon/workspace/ca-tmpl/docs/runbooks/*.md` — 운영 시나리오(장애 대응). retryable/category 정책의 운영측 근거.
|
||||
- `/home/donghyeon/workspace/ca-tmpl/src/<module>/` — **무엇이 실제 구현됐는지의 최종 SSOT.** registry 주석조차 drift 가능(예: `error-codes.yaml` L580 의 stale `PERSISTENCE`) → enum/클래스 실체는 `src/shared-contract/src/main/java/dev/caskeleton/shared/error/Category.java` 같은 코드가 authoritative. module: `domain-core`·`application-core`·`adapter-web`·`adapter-persistence`·`adapter-outbound`·`shared-contract`·`sample-portfolio`·`app-bootstrap`.
|
||||
- **완수한 sibling branch-notes** (`raw/branch-notes/feature-*.md` 중 구현 완료분) — registry `owner_branch` 로 발견. 앞선 결정·구조·계약을 알아야 일관성을 깨지 않는다.
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **전제 확인**
|
||||
- 인자 비면 브랜치 이름 요청(종료). `.md`·prefix 누락은 관대히 보정(`rules/naming-conventions.md` §2.1).
|
||||
- `raw/branch-notes/<slug>.md` 가 **없으면** 생성하지 말고 `/branch <slug>` 먼저 실행하도록 안내(종료). 채움은 본 명령, 생성은 `/branch`.
|
||||
- 노트의 `## Parent` 가 비어 있으면 `NEEDS_CONTEXT`.
|
||||
- **결정론 contract preflight (필수)**: 편집 전에 다음 명령을 실행한다.
|
||||
|
||||
```bash
|
||||
python3 harness/runtime/branch_contract_check.py --preflight --root . raw/branch-notes/<slug>.md
|
||||
```
|
||||
|
||||
- exit code가 0이고 JSON의 `schema_version`이 `branch-contract-check-result/v1`, `status`가 `PASS`일 때만 계속한다. `MISSING_PROJECT_BINDING`, `MISSING_INHERITED_DECISION`, `STALE_INHERITANCE_REVISION`, `UNDECLARED_OVERRIDE`, `CONFLICTS_WITH_PROJECT_DECISION`, `GENERATED_REGION_DRIFT` 등 실패는 그대로 보고하고 직접 보정하지 않는다.
|
||||
- preflight가 확인하는 project/Work Item/decision/dependency/revision/packet hash를 LLM이 다시 파싱하거나 독자 판정하지 않는다.
|
||||
|
||||
2. **구현·계약 현황 확인 (ca-tmpl ground truth — 필수, 추측 방지)**
|
||||
- 위 §참조의 ca-tmpl 자료를 **읽기 전용**으로 확인. 순서: 아키텍처 진입점(`CLAUDE.md`/`AGENTS.md` + 건드리는 레이어의 `src/<module>/CLAUDE.md`) → 결정이 건드리는 `docs/registries/*.yaml` → 관련 `docs/runbooks/` → `src/<module>/` grep.
|
||||
- **계약 값은 invent 금지** — 결정이 error code / category / env key / header / metric / capability / secret 을 건드리면 registry 의 *기존 값*을 재사용. 없으면 "신규 제안"임을 명시. registry row 의 `owner_branch` 로 그 계약을 정한 sibling branch-note 를 찾아 정합 확인.
|
||||
- **`actually-implemented` 주장은 코드로 확인** — 클래스/메커니즘이 "구현됐다"고 적기 전 `src/` 를 grep. *노트의 자기 보고만으로 FACT 화 금지.* 코드에 없으면 `documented-only`/`planned` 로 표기.
|
||||
- **drift 발견 시 surface** — branch-note 의 명칭/매핑이 registry 또는 코드 enum 과 어긋나면(예: stale category 명) `## Audit & Findings` 에 `CATEGORY_DRIFT` 등으로 기록. 사용자 작성 결정 영역이면 자동 rewrite 말고 *정합 권고만*.
|
||||
- ca-tmpl 경로 부재 시 `NO_GROUND_TRUTH` 라벨 + registry/노트 근거로만 진행하고 그 한계를 §8 에서 보고.
|
||||
|
||||
3. **Sources 수집**
|
||||
- 노트의 `## 근거` 표 + 인자로 받은 추가 URL 을 합친다.
|
||||
- URL 이면 `wiki-source-summarizer` dispatch (source_type + parent + 정당화 결정 한 줄 전달 — 입력 계약 §wiki-source-summarizer). 결과 raw 의 Claim ID 를 수집.
|
||||
|
||||
4. **결정 후보 추출**
|
||||
- 수집한 source Claim 과 노트의 `## TODO`·`## 결정 사항`, 그리고 §2 에서 본 ca-tmpl 구현·계약 현황에서 *내려야 할 결정*과 *각 결정의 대안*을 도출.
|
||||
- 각 후보를 `Decision ID`(D1, D2 …)로 부여.
|
||||
- project decision 상세를 branch 에 복제하지 않는다. 브랜치 계약 패킷은 pinned pointer + project 1줄 요약 + branch application 만 유지하고, 새 상세는 branch-local D-row 가 소유한다.
|
||||
|
||||
5. **자동조사 (bounded — DD4)**
|
||||
- Supporting Claim 이 없는 결정마다 `wiki-decision-researcher` dispatch (decision_topic + parent_branch + constraints + N — 입력 계약 §wiki-decision-researcher). 공식문서 + 대기업 블로그를 webfetch 로 조사해 대안 비교 + Claim 생성.
|
||||
- **bound: 회당 최대 6개 결정.** 초과분은 채우지 말고 `deferred` 목록으로 보고(절대 silent 절단 금지). 사용자가 재실행하거나 수동 조사.
|
||||
- 조사는 **개수가 아니라 근거** — 회사 블로그 1개로 "공식" 승격 금지(`rules/branch-depth-gate.md` 출처 타입 적정성).
|
||||
|
||||
6. **라벨링**
|
||||
- 조사 후에도 근거가 없는 결정은 **추측 금지**. `Decision Evidence Map` 에 `UNSUPPORTED_DECISION` + trade-off 한 줄로 남긴다.
|
||||
- 구현 가이드의 근거 없는 detail 은 `UNSUPPORTED_IMPL_DECISION` 라벨(CLAUDE.md §15.5 R2).
|
||||
|
||||
7. **격리 candidate 채움 (기존 표 포맷 유지)**
|
||||
- 실제 target bytes는 유지하고 repo와 같은 layout의 `<run-root>`에 candidate를 작성한다. 이 단계의 Edit와 agent 입력은 staged candidate만 대상으로 한다.
|
||||
- `<!-- GENERATED: branch-contract:start -->`와 `<!-- GENERATED: branch-contract:end -->` 사이 전체는 runtime 소유다. marker 자체와 내부 bytes를 수정하지 않는다. 편집은 marker 밖의 editable section으로 한정한다.
|
||||
- `## 결정-근거 매핑` 표를 채운다: Decision / 선택 조건(언제 이 결정/언제 대안) / Supporting Claims(`raw/<slug>.md#C1`) / Evidence Strength / Open Risk.
|
||||
- `## 구현 가이드` 는 in-scope 항목을 명명·경로·메커니즘으로 구체화하거나 `UNSUPPORTED_IMPL_DECISION` 라벨(CLAUDE.md §15.5 3-rule). §2 에서 확인한 *실제 클래스/패키지/registry 값*을 anchor 로 쓰되, 코드로 확인 안 된 것은 `planned` 로 표기.
|
||||
- **템플릿 섹션 순서 정합 (린터 미검사 — 필수 수기 확인)**: `wiki_structure_lint.py` 는 섹션 *존재*만 검사하고 *순서·중복*은 검사하지 않는다(린트 PASS ≠ 템플릿 정합). pre-template 노트(템플릿 도입 전 작성분)는 섹션 순서가 템플릿과 다를 수 있으므로, 채운 뒤 `grep '^## ' <노트>` 와 `templates/branch-note-template.md` 의 `## ` 순서를 대조해 **템플릿 순서로 재배치**한다. 템플릿에 없는 *노트 고유 섹션*(예: `## 테스트 계약`, `## Secret Source Defaults`, `## Work Item Contract`)은 **삭제 금지** — *가장 관련된 템플릿 섹션 바로 옆*에 슬롯한다(검증성 섹션 → `## 검증해야 할 주장` 앞, 결정 테이블 → `## 결정-근거 매핑` 앞, 근거 보강 → `## 근거` 뒤).
|
||||
- 파일 편집은 직접 Edit 하거나 대규모(전면 재배치 포함)면 `wiki-doc-author`(mode=migrate)에 위임. **기존 사용자 작성 본문 verbatim 보존.**
|
||||
|
||||
8. **결정론 postflight + semantic certificate + 깊이·완전성 + 원자 commit (맨 끝)**
|
||||
- **(8a) contract postflight** — 다음 명령을 실행하고 exit code 0, schema `branch-contract-check-result/v1`, status `PASS`를 요구한다.
|
||||
|
||||
```bash
|
||||
python3 harness/runtime/branch_contract_check.py --postflight --root . raw/branch-notes/<slug>.md --candidate <run-root>/raw/branch-notes/<slug>.md
|
||||
```
|
||||
|
||||
`GENERATED_REGION_DRIFT`를 포함한 실패가 하나라도 있으면 즉시 중단한다. generated 영역을 수동 복구하거나 다시 쓰지 않는다.
|
||||
- **(8b) typed + local/direct-impact semantic audit** — parent project의 current hub certificate를 먼저 확인한다. staged root에서 `typed_contract_check.py` → `semantic_surface_extractor.py` → `wiki-semantic-coherence-auditor` assertion phase → `semantic_candidate_builder.py` → verdict phase → proof manifest → `semantic_audit.py validate` 순서로 실행한다. impact set은 typed graph가 계산한 imported owner/consumer, 직접 dependency branch, delegation 상대만 포함하며 sibling 전수 비교는 금지한다.
|
||||
- **(8c) semantic certificate** — 모든 `CONTRADICTION`, hub `AMBIGUOUS_AUTHORITY`, `RESTATEMENT_DRIFT`, explicit blocking이 0이고 pair coverage가 완전해야 한다. 미검증 negative finding은 dropped로 분류하며 hub dropped는 PASS 불가다.
|
||||
- **(8d) /depth + /coverage** — staged candidate에 대해 structure/depth와 coverage를 실행한다. depth `Ready`와 coverage `Covered`를 모두 요구한다.
|
||||
- **(8e) 공통 quality gate** — staged candidate와 generated projection/MOC/current semantic certificate를 `quality_gate.py`로 검사한다. semantic 의미 판단은 quality gate가 재현하지 않고 certificate hash·coverage·verdict만 검증한다.
|
||||
- **(8f) 원자 commit** — `document-commit/v1`에 candidate/proof와 semantic audit request/result의 run-namespace hash를 넣는다. `document_commit.py --dry-run --semantic-run-root <run-root>`의 `plan_sha256`을 그대로 `--apply --expected-plan-sha256`에 전달해 target·projection·MOC·certificate를 한 번에 반영한다.
|
||||
- **(8g) 루프백 — 천장 2회 (project-spec §10 과 동일 규율)** — depth `Not ready`, coverage `Not-covered`, semantic/quality FAIL이면 §3~§7의 staged candidate만 보강하고 8a~8f를 다시 실행한다. 실제 target에는 실패 bytes를 남기지 않는다.
|
||||
- coverage 가 찾은 missing 관심사는 §3 결정 후보로 편입 → §5 자동조사 대상이 됨(깊이·완전성이 한 루프에서 수렴).
|
||||
|
||||
9. **요약 보고 (DD5 — 짧게, 상세는 노트에)**
|
||||
- 사람이 5초에 읽을 요약만: `채운 결정 N / UNSUPPORTED K / 조사한 결정 M / deferred D / drift D' / depth: Ready|Not ready / coverage: Covered|Not-covered (missing X)`.
|
||||
- 통과 못하면 *무엇을 더 채워야 하는지* 한 줄씩(depth·coverage finding 인용). 상세는 노트 본문에.
|
||||
- **funnel 계측 (no-silent-truncation — Stop 훅이 균형 검증)**: 요약 끝에 기계 파싱용 블록을 방출한다. `found = processed + dropped` 균형 필수:
|
||||
|
||||
```wiki-stats
|
||||
agent: branch-spec
|
||||
found: <대상 결정 총수 = 채움 + UNSUPPORTED + deferred>
|
||||
processed: <채운 결정 + UNSUPPORTED_DECISION 라벨 수>
|
||||
dropped: <deferred 수>
|
||||
dropped_reason: <deferred 사유 (bound 6 초과 등), 0 이면 행 생략 가능>
|
||||
```
|
||||
|
||||
## 규칙
|
||||
|
||||
- **추측해서 FACT 로 채우지 않는다.** 근거 없으면 자동조사 → 실패 시 `UNSUPPORTED_*` 라벨(CLAUDE.md §11).
|
||||
- **계약 값을 지어내지 않는다.** error code / category enum / env key / header / metric 등은 `ca-tmpl/docs/registries/*.yaml` + 코드 enum(예: `shared/error/Category.java`)이 SSOT. registry 에 없으면 "신규 제안"으로만 표기, 기존 값처럼 단정 금지.
|
||||
- **`actually-implemented` 는 `src/` grep 으로만 확정.** 다른 노트의 자기 보고(note→note 전이)는 근거가 아니다. 코드 미확인 항목은 `documented-only`/`planned`.
|
||||
- **기존 본문 보존** — 채움은 빈 셀/skeleton 에만. 사용자가 쓴 결정·메모를 덮어쓰지 않는다.
|
||||
- **generated 계약 영역은 수정 금지** — `<!-- GENERATED: branch-contract:start/end -->` 내부는 runtime만 쓴다. `GENERATED_REGION_DRIFT`는 자동 수정 대상이 아니라 즉시 중단 조건이다.
|
||||
- **템플릿 순서·중복은 린터가 안 잡는다** — 채움 후 `## ` 헤더 순서를 `templates/branch-note-template.md` 와 대조해 템플릿 순서로 정렬(§7). 노트 고유 섹션은 관련 템플릿 섹션 옆에 보존(삭제 금지). pre-template 노트일수록 이 단계가 필수다.
|
||||
- **자동조사는 bounded** — §4 의 6개 한도. 초과는 `deferred` 명시(`UNBOUNDED_RESEARCH` 실패 모드 방지). deferred 는 §9 의 `wiki-stats` funnel 에 계측된다(silent 절단 불가).
|
||||
- **루프 천장 2회** — §8c. 2회 초과 미통과는 실패가 아니라 *정상 종료 경로* (잔여 finding 보고 후 다음 세션 재개).
|
||||
- **agent 경계 고정** — source 조사/작성 agent에 더해 `wiki-semantic-coherence-auditor`는 assertion·verdict 의미 판단에만 dispatch한다. Python validator나 certificate 발급을 agent가 흉내내지 않는다.
|
||||
- **검증은 /depth + /coverage 에 위임** — 본 명령은 *채움*에 집중. 깊이(`/depth`)·완전성(`/coverage`) 판정 로직을 중복 구현하지 않는다. 두 게이트가 모두 통과해야 완성.
|
||||
- `wiki/log.md` 기록 안 함(브랜치 작업은 빈번, 로그 노이즈) — `/branch`·`/depth` 와 동일 정책.
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,41 @@
|
||||
브랜치 1개 단위의 작업 노트를 생성합니다.
|
||||
|
||||
**브랜치 이름:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **인자 검증**
|
||||
- 인자가 비어 있으면 사용자에게 브랜치 이름 요청
|
||||
- **prefix 4종 (`feature-` / `fix-` / `chore-` / `experiment-`)** + 구현 내용 4~8단어 kebab-case 슬러그
|
||||
- 상세는 `rules/naming-conventions.md` §2.1 — 위반은 린터가 생성 시점 차단 (`wiki_structure_lint.py` NAMING_VIOLATION)
|
||||
- **project 의 직접 자식이면 본 명령으로 생성하지 않는다.** project Work Item Registry 에서 온 작업은 `/branch-from-project <project> <WI-ID>` 를 안내하고 종료한다. 본 명령은 standalone 또는 다른 branch 의 자식 스캐폴딩에만 사용한다.
|
||||
|
||||
2. **파일 존재 확인**
|
||||
- `raw/branch-notes/<branch-name>.md`가 이미 있으면 **덮어쓰지 말 것**. 기존 경로만 안내하고 종료.
|
||||
|
||||
3. **스캐폴딩**
|
||||
- `templates/branch-note-template.md` 복사 → `raw/branch-notes/<branch-name>.md`
|
||||
- 템플릿의 `## Decision Evidence Map` 과 `## Claims To Verify` 섹션을 보존
|
||||
- 사용자가 Sources/Claim ID 를 제공했다면 Decision ID 와 Supporting Claims 를 즉시 연결
|
||||
- 근거가 아직 없으면 중요한 결정은 `UNSUPPORTED_DECISION` 으로 남기고 추측해서 채우지 않음
|
||||
- frontmatter `title`, `branch`, `created`(오늘 날짜) 치환
|
||||
- 본문 `# branch: <branch-name>` 헤더 치환
|
||||
- `status_label`은 `in-progress`로 기본
|
||||
- v2 frontmatter 는 용도에 맞게 `id=<branch-name>`, `kind=branch-child|standalone`, `contract_packet=1` 을 채운다. project Work Item 상속값을 추측해 넣지 않는다.
|
||||
|
||||
4. **오늘 daily 노트 연결 (있다면)**
|
||||
- `raw/daily-notes/YYYY-MM-DD.md` 파일이 존재하면, "활성 브랜치" 섹션에 이 브랜치 항목을 추가
|
||||
- daily 파일이 없으면 건드리지 않음 (사용자가 `/daily` 실행할 때 자동 반영하지 않음)
|
||||
|
||||
5. **사용자 안내**
|
||||
- 파일 경로 출력
|
||||
- "목표/범위/TODO부터 채워주세요" 안내
|
||||
- "`/branch-spec <slug>` 로 채우세요 (끝에 depth+coverage 자동)" 안내
|
||||
|
||||
## 규칙
|
||||
|
||||
- **스캐폴딩만**. 내용을 추측해서 채우지 말 것.
|
||||
- `Decision Evidence Map` 을 삭제하지 말 것. 비어 있더라도 나중에 Claim ID 를 연결할 구조로 유지.
|
||||
- 브랜치 머지/종료 후 `/ingest raw/branch-notes/<branch-name>.md`로 verified 결과를 `wiki/projects/`에 추출.
|
||||
- 머지 후에도 branch-note는 raw에 **영구 보관** (삭제 X). 면접/회고 시 결정 사항 근거가 됨.
|
||||
- `wiki/log.md`는 기록하지 않음 (브랜치 생성은 빈번, 로그가 노이즈).
|
||||
@@ -0,0 +1,51 @@
|
||||
브랜치 노트 1개가 **기준 문서가 요구하는 관심사를 빠짐없이 덮는지** 점검합니다(완전성).
|
||||
`/depth`(깊이)의 짝 — 이쪽은 *적어야 할 게 다 적혔나*를 봅니다.
|
||||
(기준: `rules/coverage-gate.md` / 판정 위계: governing 문서 → 선례 브랜치 → ca-tmpl 코드)
|
||||
|
||||
**인자:** {{arguments}}
|
||||
|
||||
## 작업 절차 (브랜치 모드)
|
||||
|
||||
1. **인자 검증** — 비어 있으면 브랜치 이름 요청. `--project` 면 프로젝트 모드(아래)로. `raw/branch-notes/<name>.md` 로 해석(`.md`·`feature-` 누락은 관대히 보정).
|
||||
|
||||
2. **파일 존재 확인** — 없으면 경로만 안내하고 종료(생성은 `/branch`).
|
||||
|
||||
3. **1차 결정론 사전 검사 + 면제 판정 (스크립트 — LLM 인라인 grep 금지)**:
|
||||
|
||||
```bash
|
||||
python3 .claude/hooks/wiki_structure_lint.py --coverage-pre raw/branch-notes/<name>.md
|
||||
```
|
||||
|
||||
exit code 로 분기 — **0 PASS**(WARN 포함 가능, 2차 진행) / **1 FAIL**(`NO_GOVERNING_DOC`·`GOVERNING_DOC_MISSING` — 먼저 고치도록 안내하고 2차 보류) / **3 EXEMPT**(coverage 면제, 예: keycloak 학습 노트 — 면제 사유만 보고하고 종료). `NO_COVERAGE_SECTION` 은 WARN(2차가 채울 칸).
|
||||
|
||||
4. **2차 의미 판정 (coverage-auditor 디스패치)** — 1차 PASS(또는 WARN 사용자 인지)하면 `coverage-auditor` 서브에이전트에 브랜치 노트 경로 전달.
|
||||
- 감사기는 governing 문서·선례 브랜치·ca-tmpl 코드를 실제로 읽어 각 관심사를 covered-here / delegated / missing 으로 *의미* 판정.
|
||||
- 감사기 리포트(Verdict + Coverage 표 + 다음 행동)를 그대로 출력.
|
||||
|
||||
5. **§Coverage 반영 (사용자 확인 후)** — 감사기가 돌려준 Coverage 표를 노트의 `## Coverage` 섹션에 기록할지 사용자에게 제안. **표는 생성물** — 손으로 유지하지 않음, coverage 실행 시마다 갱신.
|
||||
|
||||
6. **종합 판정** — 1차 exit code(0) + 2차 `wiki-verdict` 블록(`blocking: 0`)을 기계 합산해 `Covered` / `Not-covered`. missing(🔴) 0건이어야 Covered.
|
||||
|
||||
7. **루프** — missing 을 `/branch-spec <name>` 으로 되돌아가 결정으로 채운 뒤 `/coverage <name>` 재실행 → Covered 까지. (`/branch-spec` 이 끝에서 depth·coverage 를 자동 실행하므로 보통 그 흐름 안에서 닫힘.)
|
||||
|
||||
## 작업 절차 (프로젝트 모드 — `/coverage --project`)
|
||||
|
||||
1. `coverage-auditor` 를 `--project` 입력으로 디스패치.
|
||||
2. 감사기가 전체 canonical 문서에서 관심사를 열거하고 각 브랜치 `## Coverage` 와 cross-ref 해 **owner-less 관심사**(아무 브랜치도 안 맡음)를 Blocking 으로 식별.
|
||||
3. 감사기가 돌려준 매트릭스를 `wiki/projects/ca-tmpl/coverage-matrix.md` 로 **생성/덮어쓰기**(생성물 — 손유지 금지). 사용자 확인 후 기록.
|
||||
4. owner-less 관심사 목록을 요약 보고 — 각각 어느 브랜치(신규/기존)가 맡아야 하는지 한 줄씩.
|
||||
|
||||
## 규칙
|
||||
|
||||
- 검출·판정만(read-only). 1차 인라인 검사도 2차 감사기도 노트를 **편집하지 않는다**. §Coverage/matrix 기록은 사용자 확인 후 명령이 수행(생성물).
|
||||
- 멱등: 같은 노트에 몇 번 돌려도 안전. §Coverage 는 매번 재생성.
|
||||
- **추측 금지** — governing 문서·코드를 실제로 읽고 판정. owner 위임은 Blocking 아님(Should-fix).
|
||||
- **depth 와 분업** — 깊이는 `/depth`, 완전성은 `/coverage`. 서로의 영역을 중복 판정하지 않는다.
|
||||
- 자동 채움 금지 — missing 갭은 `/branch-spec` 으로 채운다(본 명령은 *검출*만).
|
||||
- `wiki/log.md` 기록 안 함(`/depth`·`/branch-spec` 와 동일 정책).
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,27 @@
|
||||
오늘(또는 지정 날짜)의 일일 노트를 생성합니다.
|
||||
|
||||
**대상 날짜:** {{arguments}} (비어 있으면 오늘 날짜)
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **날짜 결정**
|
||||
- 인자가 있으면 `YYYY-MM-DD` 포맷 검증 후 사용
|
||||
- 비어 있으면 시스템 오늘 날짜 사용
|
||||
|
||||
2. **파일 존재 확인**
|
||||
- `raw/daily-notes/YYYY-MM-DD.md`가 이미 있으면 **덮어쓰지 말 것**. 기존 파일 경로만 안내하고 종료.
|
||||
|
||||
3. **스캐폴딩**
|
||||
- `templates/daily-note-template.md`를 복사해 `raw/daily-notes/YYYY-MM-DD.md` 생성
|
||||
- frontmatter의 `title`, `date`를 실제 날짜로 치환
|
||||
- 본문의 `# YYYY-MM-DD` 헤더도 실제 날짜로 치환
|
||||
|
||||
4. **사용자 안내**
|
||||
- 파일 경로 출력
|
||||
- "오늘 작업 시작/종료 시 채워주세요" 한 줄
|
||||
|
||||
## 규칙
|
||||
|
||||
- 이 명령은 **스캐폴딩만** 합니다. 내용을 추측해서 채우지 마세요.
|
||||
- 일일 노트의 **promotable 추출**은 별도 작업 (`/ingest raw/daily-notes/YYYY-MM-DD.md`)으로 진행.
|
||||
- 로그(`wiki/log.md`)는 기록하지 않습니다 (매일 생성되므로 로그가 노이즈가 됨). `/ingest`가 실행될 때만 로그.
|
||||
@@ -0,0 +1,38 @@
|
||||
브랜치 노트 1개가 **코딩 착수해도 되묻지 않을 만큼 깊은지** 점검합니다.
|
||||
(기준: `rules/branch-depth-gate.md` / 결정론 검사: `.claude/hooks/wiki_structure_lint.py`)
|
||||
|
||||
**브랜치 이름:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **인자 검증** — 비어 있으면 브랜치 이름 요청. `raw/branch-notes/<name>.md` 로 해석(`.md`·`feature-` 누락은 관대히 보정).
|
||||
|
||||
2. **파일 존재 확인** — 없으면 경로만 안내하고 종료(생성은 `/branch` 의 일).
|
||||
|
||||
3. **결정론 구조 검사 (1차 — 싸고 빠른 게이트)** — 다음을 실행하고 결과(PASS/FAIL + 사유)를 그대로 보고:
|
||||
```
|
||||
python3 .claude/hooks/wiki_structure_lint.py --file raw/branch-notes/<name>.md
|
||||
```
|
||||
- 구조 FAIL(템플릿 누락 섹션 / 백틱 링크 / 깨진 링크 / 빈 선택조건 셀 등)이면 **그것부터** 고치도록 안내. (본 명령은 read-only — 수정은 사용자 또는 `/branch-spec` 의 몫.)
|
||||
|
||||
4. **의미 깊이 판정 (2차 — R1~R4)** — 1차가 통과(또는 구조 이슈를 사용자가 인지)하면 `branch-depth-auditor` 서브에이전트를 디스패치하고 입력으로 브랜치 노트 경로를 전달.
|
||||
- 감사기는 소스를 실제로 읽어 조사 깊이(L0/L1), 결정 조건의 진위, 구현 detail 충분성, 암시된 의존을 *의미*로 판정한다.
|
||||
- 감사기 리포트(Verdict + Findings 표 + 다음 행동)를 그대로 출력.
|
||||
- **1차가 구조 FAIL 인데도 2차를 돌릴지**: 구조가 심하게 깨졌으면(섹션 다수 누락 등) 먼저 구조부터 고치도록 권하고 2차는 보류. 경미하면 1차 보고 + 2차 동시 진행.
|
||||
|
||||
5. **종합 판정** — 1차(구조) + 2차(의미) 를 합쳐 `Ready` / `Not ready`. 둘 다 Blocking 0 이어야 Ready.
|
||||
|
||||
6. **루프** — 사유를 고친 뒤 `/depth <name>` 재실행 → Ready 까지.
|
||||
|
||||
## 규칙
|
||||
|
||||
- 검출·판정만(read-only — frontmatter `disallowed-tools` 로 강제). 1차 린터도 2차 감사기도 노트를 편집하지 않는다.
|
||||
- 멱등: 같은 노트에 몇 번 돌려도 안전.
|
||||
- 자동 조사·자동 수정 금지 — R1 조사 얕음 갭은 `wiki-decision-researcher` 권고만(사용자 옵트인).
|
||||
- `wiki/log.md` 기록 안 함.
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,34 @@
|
||||
canonical 문서를 "나의 진짜 이해" 를 위한 1타강사 설명 문서로 변환합니다. **외부 공개물이 아니라 개인 학습 산출물**입니다 (CLAUDE.md §5·§15 explainer 특수 지위).
|
||||
|
||||
**대상:** {{arguments}} (concept/project 문서 경로 또는 설명받고 싶은 주제)
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **소스 식별 (canonical만)**
|
||||
- 인자가 경로면 **`wiki/concepts/` 또는 `wiki/projects/`만** 허용. 다른 경로(`raw/`, `wiki/interview/` 등) 입력 시 **중단**.
|
||||
- 인자가 주제면 `/query`로 관련 canonical 문서(개념 + 내 프로젝트 적용)를 모은다. raw 직접 참조 금지.
|
||||
- 대안 비교가 핵심이므로, 개념 문서의 **대안/선택지 목록 전체**와 프로젝트 문서의 **결정 이유·검증 범위**를 함께 확보한다.
|
||||
|
||||
2. **상태 게이트 — 없음 (단, 두 불변식은 강제)**
|
||||
- explainer 는 외부 공개물이 아니므로 status `reviewed` 이상 게이트를 적용하지 **않는다**. `draft` canonical 에서도 생성 가능.
|
||||
- 대신: (1) **canonical 경유 필수** (raw/daily/branch 직접 변환 금지), (2) **새 claim 생성 금지** — canonical 에 없는 사실을 만들지 않는다. 모든 사실은 canonical 링크로 근거.
|
||||
|
||||
3. **explainer 문서 생성**
|
||||
- `wiki/explainer/<주제>.md`에 `templates/explainer-template.md` 적용. slug 는 가능하면 원천 concept slug 와 맞춘다.
|
||||
- 골격(0~4단 + 대안별 5단 a~e)은 `templates/explainer-template.md` 를 **Read 한 결과가 SSOT** — 인라인 섹션 목록을 두지 않는다(drift 방지). template 의 모든 단을 **빠짐없이** 채운다 (틀은 강제, 산문은 자유).
|
||||
- 명령 고유 규칙: §2 에서 canonical 의 대안을 **빠짐없이** 다루고, 각 대안의 근거 단(e)에는 canonical 링크 + claim ID 를 단다. §3 은 검증된 사실만(project 문서 등급) + 말하면 안 되는 범위 명시.
|
||||
|
||||
4. **양방향 링크**
|
||||
- explainer → canonical(concepts/projects) 링크는 Sources 와 각 (e)·§3 에 필수. (canonical → explainer 는 Obsidian backlink 가 자동 발견하므로 별도 편집 불필요.)
|
||||
|
||||
5. **로그 기록**
|
||||
- `wiki/log.md`: `YYYY-MM-DD HH:mm /explain — <소스> → <explainer 경로>`
|
||||
|
||||
## 규칙
|
||||
|
||||
- **새 claim 금지.** canonical 에 없는 사실·수치·주장을 만들지 않는다. explainer 는 canonical 의 교육적 재구성일 뿐이다.
|
||||
- **비유는 의도적 단순화**임을 문서에 명시하고, 사실로 인용하지 않는다. 비유가 왜곡할 수 있는 지점은 "강사의 한마디" 로 보정한다.
|
||||
- **과장 금지**(canonical 의 Do Not Overclaim / 과장 금지 지점을 그대로 승계). "무조건 우월", "항상", 단정형 주의.
|
||||
- **대안은 패배자 목록이 아니다.** 각 대안을 "문제를 다르게 정의한 정당한 답" 으로 다룬다. 내 선택은 "우월해서" 가 아니라 "내 문제 정의가 그래서" 로 설명한다.
|
||||
- **톤**: 크리스프 평서문 + 직접 호명("너의 메서드"). explainer 는 개인 이해용이라 윤문 대상이 아니다 — im-not-ai 를 돌리지 않는다.
|
||||
- explainer 는 외부 공개(이력서/면접/블로그)에 직접 쓰지 않는다. 외부용은 canonical 에서 `/interviewize`·`/blogify`·portfolio 로.
|
||||
@@ -0,0 +1,106 @@
|
||||
다음 raw 자료를 wiki 문서로 변환합니다.
|
||||
|
||||
**대상:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **source_type 분류** (CLAUDE.md §5 와 일치, templates 와 1:1)
|
||||
- `official-doc` / `company-tech-blog` / `personal-blog` / `lecture` / `project-note` / `error-note` / `job-posting` / `blog-topic` / `interview-prep` / `daily-note` / `branch-note` / `concept` / `interview` / `portfolio` / `blog` / `llm-generated`
|
||||
- **deprecated 표기 거부**: `error-log` → `error-note`, `interview-note` → `interview-prep`, `lecture-note` → `lecture`. 입력이 deprecated 면 정정 후 진행.
|
||||
- `daily-note`, `branch-note`는 "특수" 처리 절차(아래)로 분기됨.
|
||||
|
||||
2. **핵심 개념 추출**
|
||||
- 자료가 다루는 주요 개념 1–5개 식별
|
||||
- raw source 의 `Claims Extracted` 와 branch-note 의 `Decision Evidence Map` 을 먼저 확인
|
||||
- 근거 Claim 이 없는 단정은 wiki FACT 로 승격하지 않음 (`INFERENCE` 또는 `needs-confirmation`)
|
||||
|
||||
3. **wiki 위치 결정 (canonical만)**
|
||||
- 일반 개념 → `wiki/concepts/<concept-slug>.md` (평면)
|
||||
- 내 프로젝트 사실 → `wiki/projects/<project-slug>/<topic>.md` (**nested** — `rules/naming-conventions.md` §2.11). 새 프로젝트면 sibling **named hub** `wiki/projects/<project-slug>.md` (MOC) 도 함께 생성 (folder-note 패턴, `index.md` 사용 금지 — `rules/linking-rules.md` §12).
|
||||
- **금지:** `wiki/interview/`, `wiki/portfolio/`, `wiki/blog/`. `/ingest`는 canonical만 생성.
|
||||
- 자료 안에 면접·포트폴리오·블로그로 옮길 만한 부분이 있어도 **먼저 canonical로 변환**한 뒤, 별도로 `/interviewize` / `/blogify` 또는 수동 작성 단계로 진행.
|
||||
- `raw/blog-topics/`는 블로그 글감 원석이며, `/ingest`는 여기서 바로 `wiki/blog/`를 만들지 않는다. promotable claim만 canonical 후보로 정제한다.
|
||||
|
||||
4. **템플릿 적용** (canonical 출력 + raw 보관용만)
|
||||
- 개념 (`wiki/concepts/`): `templates/concept-template.md`
|
||||
- 프로젝트 (`wiki/projects/`): `templates/wiki-project-template.md`
|
||||
- 외부 자료 **원본 발췌** (`raw/`): `templates/raw-source-template.md`
|
||||
- 외부 자료 **검증된 요약** (`wiki/concepts/`): `templates/source-summary-template.md`
|
||||
- `templates/interview-template.md`은 `/interviewize` 전용. `/ingest`는 사용하지 않음.
|
||||
|
||||
5. **YAML frontmatter 작성**
|
||||
- `CLAUDE.md` 메타데이터 표준 준수 (title, source_type, status, confidence, tags, related_projects, last_reviewed)
|
||||
- `last_reviewed`는 오늘 날짜로
|
||||
|
||||
6. **링크 연결**
|
||||
- 관련 문서는 `[[wikilink]]`로 양방향 연결
|
||||
- 원본 raw 문서를 Sources에 명시
|
||||
|
||||
7. **원본 보존 확인**
|
||||
- 외부 URL이 있으면 raw 문서에 핵심 인용 3–5문장이 발췌되어 있는지 확인
|
||||
- 누락이면 발췌 후 raw에 추가
|
||||
- 가능하면 `archive_url` 병기
|
||||
|
||||
8. **Hub 및 log 갱신**
|
||||
- `wiki/llm-wiki.md` (vault MOC) 에 새 카테고리 / 허브 문서가 추가되었으면 업데이트 (개별 문서 일일이 나열 X)
|
||||
- `wiki/log.md`에 한 줄 기록: `YYYY-MM-DD HH:mm /ingest — <raw 경로> → <wiki 경로>`
|
||||
|
||||
## 규칙
|
||||
|
||||
- **프로젝트 관련 진술**은 반드시 증거 등급(actually-implemented / locally-verified / prod-verified / documented-only / planned / needs-confirmation) 명시.
|
||||
- **공식 문서와 기술블로그 혼동 금지.** 기술블로그는 사례, 공식 best practice가 아님.
|
||||
- **Claim ID 없는 결정 승격 금지.** branch-note 의 결정은 Supporting Claims 가 있거나 `UNSUPPORTED_DECISION` 으로 명시된 상태여야 한다.
|
||||
- **LLM 생성 내용**은 `confidence: high`로 두지 말 것. 최대 `medium`.
|
||||
- **원본을 임의로 의역하지 말 것.** 인용은 인용 표시(`>`)로 분리.
|
||||
- 모호하면 `status: needs-confirmation`으로 두고 사람 검토 대기.
|
||||
|
||||
## 특수: daily-note 처리
|
||||
|
||||
`source_type: daily-note` 또는 `raw/daily-notes/` 하위 파일을 ingest할 때:
|
||||
|
||||
- **원본 daily 파일을 wiki로 통째 옮기지 않음.** raw에 영구 보관.
|
||||
- 파일 내 섹션별로 promotable 항목만 추출. **canonical(`wiki/concepts/`, `wiki/projects/`)으로만 추출.** 파생 산출물 직접 생성 금지.
|
||||
- **한 일** / **트러블슈팅** → 관련 `wiki/projects/`에 추가 또는 신규 생성 (증거 등급 표기 필수). `[branch-name]` 프리픽스가 있으면 해당 브랜치 노트의 "마주친 문제"·"진행 중 메모"에도 cross-link.
|
||||
- **배운 점** → `wiki/concepts/`에 신규/추가
|
||||
- **트러블슈팅** 중 재발 가능한 패턴 → `wiki/concepts/`로 (`raw/errors/`는 원본 보관 위치, 변환 X)
|
||||
- **면접·포트폴리오 옮길 만한 것** → **후보 표기만**. 관련 `wiki/projects/` 문서의 "면접 후보" 메모 또는 frontmatter 태그로 표시. **`wiki/interview/`·`wiki/portfolio/` 문서를 직접 만들지 않음** — 후속 `/interviewize` 또는 수동 작성 단계로 위임.
|
||||
- **잡담 / 회의 / 기타** → 추출하지 않음 (raw에만 남김)
|
||||
- 추출 시 daily 파일 경로를 새 wiki 문서의 Sources에 `[[raw/daily-notes/YYYY-MM-DD]]` 형식으로 링크.
|
||||
- 추출하지 않은 항목은 daily 파일에 그대로 둠 (수정·삭제 금지).
|
||||
|
||||
## 특수: branch-note 처리
|
||||
|
||||
`source_type: branch-note` 또는 `raw/branch-notes/` 하위 파일을 ingest할 때:
|
||||
|
||||
- **원본 branch 파일을 wiki로 통째 옮기지 않음.** raw에 영구 보관 (머지 후에도).
|
||||
- 추출 트리거: `status_label`이 `merged` 또는 `abandoned` 또는 `완료 후 정리` 섹션이 채워졌을 때.
|
||||
- 섹션별 처리 (**canonical로만 추출, 파생 산출물 직접 생성 금지**):
|
||||
- **완료 후 정리 → wiki 추출 대상** 의 `actually-implemented` / `locally-verified` / `prod-verified` 항목만 `wiki/projects/`로 추출 (신규 또는 기존 project 문서에 추가). 다른 등급은 추출 금지.
|
||||
- **결정 사항 (decisions)** → 추출된 `wiki/projects/` 문서의 "결정 이유" 섹션에 통합. 면접 후보면 frontmatter 태그(`interview-candidate`)만 표시. **`wiki/interview/` 직접 생성 금지** — 후속 `/interviewize` 단계로 위임.
|
||||
- 단, `Decision Evidence Map` 에서 Claim ID 로 뒷받침되는 결정만 FACT 로 통합. `UNSUPPORTED_DECISION` 은 추출하지 않고 검증 필요로 남김.
|
||||
- **마주친 문제** 중 해결된 패턴 → `wiki/concepts/` 후보로 보고. 사용자 확인 후 변환.
|
||||
- **TODO 중 abandoned/planned** → 추출하지 않음. branch-note에만 기록 남김.
|
||||
- **목표 / 범위 / 진행 중 메모 / 잡담** → 추출하지 않음.
|
||||
- 추출한 wiki 문서의 Sources에 `[[raw/branch-notes/<branch-name>]]` cross-link.
|
||||
- 추출 후 branch-note의 `status_label`을 `merged`로 갱신 가능 (사용자 확인 후).
|
||||
- `abandoned` 브랜치는 추출 없이 raw에만 보관. 단, 결정 사항/마주친 문제는 회고·면접에서 "왜 폐기됐나" 근거가 되므로 삭제 금지.
|
||||
|
||||
## 출력: Stats funnel (no-silent-truncation)
|
||||
|
||||
작업 종료 시 `## Stats` 절을 보고한다 (`rules/reporting-standards.md` No silent truncation 계약):
|
||||
|
||||
```
|
||||
## Stats
|
||||
found: <식별한 promotable 항목 수>
|
||||
processed: <canonical 로 promote 한 수>
|
||||
dropped: <추출 안 한 수>
|
||||
dropped_reason: <항목별 제외 사유 (raw 보존 / 잡담 / abandoned / planned 등)>
|
||||
```
|
||||
|
||||
`found = processed + dropped` 균형 필수. daily/branch 특수처리에서 "추출 안 함" 으로 raw 에 남긴 항목도 `dropped` 에 카운트하고 사유를 적는다 — 무엇을 안 옮겼는지 보이게. 침묵 누락 금지.
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,38 @@
|
||||
wiki 내용을 면접 답변용 문서로 변환합니다.
|
||||
|
||||
**대상:** {{arguments}} (concept/project 문서 경로 또는 면접 질문)
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **소스 식별 (canonical만)**
|
||||
- 인자가 경로면 **`wiki/concepts/` 또는 `wiki/projects/`만** 허용. 다른 경로(`raw/`, `wiki/interview/` 등) 입력 시 **중단**.
|
||||
- 인자가 질문이면 `/query`로 canonical 문서 수집. raw 직접 참조 금지.
|
||||
|
||||
2. **상태 게이트 (차단)**
|
||||
- 소스 문서 status가 `reviewed | verified | published-ready` 중 하나가 **아니면 중단** (경고 X).
|
||||
- 사용자에게 안내: "원천 문서를 `reviewed` 이상으로 승급(사람 검토 → §15 단계) 후 다시 실행하세요."
|
||||
- 위 조건 통과 후 과장 표현 사전 검사 — 발견 시 변환 전에 보고.
|
||||
|
||||
3. **interview 문서 생성**
|
||||
- `wiki/interview/<주제>.md`에 `templates/interview-template.md` 적용
|
||||
- 섹션 구성은 `templates/interview-template.md` 를 **Read 한 결과가 SSOT** — 인라인 섹션 목록을 두지 않는다(이미 한 번 drift 됨: `## 관련 문서` 누락). template 의 모든 섹션을 **빠짐없이** 채움 (Sources/사실 분류 누락 금지).
|
||||
- "면접에서 말해도 되는 범위" 판정: **CLAUDE.md §6 허용 등급표가 SSOT (외부 공개 3등급만)** — 허용 외 등급은 본문 진술 대신 "모른다 / 확인 필요" 로 답하는 방향 제시.
|
||||
|
||||
4. **사실 vs 일반론 분리**
|
||||
- 답변 본문에 "내가 프로젝트에서 한 일"과 "일반 개념 설명"을 **분명히 구분**
|
||||
- 일반론은 짧게, 프로젝트 적용은 구체적으로
|
||||
|
||||
5. **양방향 링크**
|
||||
- 원본 concept/project 문서에 새 interview 문서 링크 추가
|
||||
|
||||
6. **로그 기록**
|
||||
- `wiki/log.md`: `YYYY-MM-DD HH:mm /interviewize — <소스> → <interview 경로>`
|
||||
|
||||
## 규칙
|
||||
|
||||
- **상세 답변에 들어가는 프로젝트 사실은 CLAUDE.md §6 허용 등급표의 외부 공개 3등급만.** 허용 외 등급은 본문 진술 금지.
|
||||
- "운영 중" / "프로덕션" / "성능 X배" 같은 표현은 **`prod-verified` 등급**이고 근거(로그/측정/릴리즈)가 있을 때만.
|
||||
- 새 interview 문서의 Sources에 **반드시** `[[wiki/concepts/...]]` 또는 `[[wiki/projects/...]]` 링크 포함. `/lint`가 이를 검사.
|
||||
- 모르는 부분에 대한 모범 답변도 같이 제시 ("이 부분은 확인이 필요합니다" 형태).
|
||||
- **본문은 한국어로 쓰고, 개발 용어만 원문(영어)을 유지한다.** 문장 단위 윤문은 여기서 하지 않는다 — 작성이 끝난 뒤 im-not-ai(`/humanize-korean`)로 묶어서 처리한다(`rules/prose-style.md` §3). 표현이 다소 어색해도 작성 단계에서는 넘어간다.
|
||||
- **윤문은 사실 등급을 바꾸지 않는다** (`rules/prose-style.md` §2) — 이 경계만 여기서 검사한다.
|
||||
@@ -0,0 +1,38 @@
|
||||
오늘(또는 지정 날짜)의 투자 일일 조사 노트를 생성합니다.
|
||||
|
||||
**대상 날짜:** {{arguments}} (비면 오늘)
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **날짜 결정** — 인자 있으면 `YYYY-MM-DD` 검증, 없으면 오늘.
|
||||
2. **파일 존재 확인** — `raw/invest-daily/YYYY-MM-DD.md` 있으면 덮어쓰지 말고 경로 안내 후 종료.
|
||||
3. **스캐폴딩** — `templates/invest-daily-template.md` 복사, frontmatter `title`/`date`/`last_reviewed`와 본문 헤더의 날짜 치환.
|
||||
4. **`deep-research` 스킬 호출 (명시 — Spec F V3)** — `deep-research` 스킬로 고정 체크리스트(미 10Y·한 기준금리·USD/KRW·WTI·금·S&P500·KOSPI·나스닥·BTC·ETH)의 현재 값/방향과 그날 주요 이슈를 조사. **각 수치에 출처 링크 + 조사시점**을 붙여 표/이슈 섹션을 채움.
|
||||
|
||||
5. **수치 3표 quorum 검증 (기본값 — P2-17 반전, opt-out 명시제)** — 미래시점 수치(지수·환율)는 환각 위험이 가장 큰 지점이므로 **기본으로** 검증한다. 3표는 **cross-vendor 1+1+1** (`rules/extraction-tiering.md` T1 — codex/agy 모두 web 검증 가능, 검증된 사실):
|
||||
- **Claude 1표**: read-only 검증 subagent 1개 dispatch (WebSearch 가능). 고정 체크리스트의 수치를 권위 출처에서 독립 재확인하고, 행마다 `finding: <행ID> action: KEEP|DOWNGRADE|REJECT` (KEEP=일치 확인 / DOWNGRADE=단일출처·근사치 / REJECT=불일치·확인불가) 형식의 ```wiki-verdict``` 블록(`agent:` 라인 포함)을 출력 → `/tmp/invest-vote-claude.md`.
|
||||
- **외부 2표**: 체크리스트 수치 행(행ID 포함)을 findings 파일로 저장 후 — 외부 엔진은 web 재확인이 가능하므로 노트 전체를 `--context-files` 로 전달:
|
||||
|
||||
```bash
|
||||
cd scripts/deep-research && python3 -m deep_research.vote --backend codex \
|
||||
--findings /tmp/invest-findings.md --context-files raw/invest-daily/YYYY-MM-DD.md --out /tmp/invest-vote-codex.md
|
||||
cd scripts/deep-research && python3 -m deep_research.vote --backend antigravity \
|
||||
--findings /tmp/invest-findings.md --context-files raw/invest-daily/YYYY-MM-DD.md --out /tmp/invest-vote-agy.md
|
||||
```
|
||||
|
||||
- `python3 .claude/hooks/wiki_quorum.py /tmp/invest-vote-claude.md /tmp/invest-vote-codex.md /tmp/invest-vote-agy.md` 로 결정론 합산 — **KILL** → 해당 수치를 비우고 "검증 실패" 표기, **DOWNGRADE** → "단일출처/근사" 표기, **UNVERIFIED** → 비움(추측 금지).
|
||||
- **외부 표 생성 실패 시** (vote.py exit 1) 해당 표만 Claude read-only 검증 subagent 추가 dispatch 로 대체 (fallback) — 표별 엔진 출처를 `## 출처 / Sources` 에 funnel 로 기록 (no silent engine swap).
|
||||
- **opt-out**: 사용자가 명시적으로 빠른 모드를 요청한 경우에만 생략하고, 생략 사실을 노문 `## 출처 / Sources` 에 한 줄 기록. 더 강한 검증이 필요하면 deep-research **Workflow(3표 quorum)** = `Workflow` opt-in("ultracode", Spec D).
|
||||
6. **분야 관찰 채우기 (field-map 루프 엔진)** — `[[wiki/invest-concepts/field-map]]` 허브의 분야 카드를 읽고, **오늘 유의미하게 움직인 카드**(달러·금리·원유·금·미국주식·BTC·반도체·빅테크AI)마다 한 행씩:
|
||||
- `오늘 움직인 카드` = `[[wiki/invest-concepts/field-...]]`, `방향` = 그날 변화(↑/↓ %),
|
||||
- `그 카드 예측 연결이 맞았나?` = 그 카드의 **연결(Linkages)표 예측**과 오늘 실측을 대조(예: 달러↑면 카드가 예측한 "금↓·원유↓"이 실제로 맞았는지 *확인/반증* 표기),
|
||||
- `새 가설/메모` = 어긋났으면 왜인지 한 줄.
|
||||
- ⚠️ 여기서 **새 사실을 단정하지 말 것** — 관찰은 미검증(가설). 반복 확인된 패턴만 나중에 `/invest-research`로 검증해 카드의 `[가설]`→`[검증]` 승격(`/invest-ingest`).
|
||||
7. **출처 기록 (추적성 — 필수)** — deep-research 가 조사한 **전(全) 출처**를 `## 출처 / Sources` 섹션에 등급(`[primary/secondary/blog/unreliable]`) + URL 로 나열한다. **교차검증 실패(claims:0)·`[unreliable]` 출처도 *조사했으나 미채택* 으로 남겨 투명성 확보** — "어디서 뭘 봤나"를 사용자가 추적/교차검증할 수 있어야 함. 조사 통계(N각도·M출처 fetch·confirmed/killed) 1줄 포함.
|
||||
8. **사용자 안내** — 경로 출력 + "관찰·분야관찰은 미검증이니 반복 패턴은 `/invest-research`로 확인 → `/invest-ingest`로 카드에 반영하세요. 출처 섹션에서 직접 교차검증 권장."
|
||||
|
||||
## 규칙
|
||||
|
||||
- **수치마다 출처 + 조사시점 필수.** 출처 없는 단정 금지(환각 위험). 모르면 비움.
|
||||
- "관찰·가설" 섹션은 미검증 표시 유지. canonical로 직접 가지 않음.
|
||||
- `wiki/log.md` 기록 안 함(매일 생성, 노이즈).
|
||||
@@ -0,0 +1,24 @@
|
||||
**결정:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **인자 파싱** — 매수/매도, 종목, 수량, 단가, (선택)계좌. 불명확하면 되물음.
|
||||
2. **선근거 확인** — 이 매매의 근거 문서(`raw/invest-research/` 또는 `wiki/invest-plan/`) 링크를 요구. **근거 없으면 기록 거부**(전략 ③ 선근거 원칙).
|
||||
3. **규칙 강제 체크 — 임계값은 strategy.md 가 SSOT (인라인 수치 금지)** — `wiki/invest-strategy/strategy.md` 의 ①~⑤ 규칙을 **읽어서** 대조한다. 본 명령에 임계값을 복붙하지 않는다(strategy 개정 시 drift 방지 — 실제로 MDD -20%→-40% 개정 이력 있음):
|
||||
- **① 포지션 크기**: 이 매매 후 한 종목 비중이 현재 자본 구간 규칙 초과?
|
||||
- **② 손절/익절**: 매도가 코어 ETF 손절이면 경고("코어는 손절 안 함"). 개별 베팅 기계적 익절은 strategy 의 `UNSUPPORTED_DECISION` 표기 환기.
|
||||
- **③ 행동 가드레일**: 패닉셀 쿨다운(급락 보고 후 매도 — 최근 invest-daily 와 대조) + 주간 거래상한.
|
||||
- **④ 절세계좌**: 일반계좌 매수인데 더 유리한 계좌 조건 충족 시 권고(strategy ④ 의 사전 체크 순서대로).
|
||||
4. **기록** — `raw/invest-ledger/ledger.md`의 "거래 내역" 행 추가, "현재 포지션" 갱신. 플래그가 있었으면 "규칙 위반 이력"에도 기록(사용자 처리 포함).
|
||||
5. **결정론 검증 (기록 직후 필수 — P2-17)**:
|
||||
```bash
|
||||
python3 .claude/hooks/invest_ledger_check.py --check --weekly-cap <strategy ③의 N>
|
||||
```
|
||||
행 스키마(11열)·근거 링크 실존·근거 staleness(일일노트 >24h / 조사노트 >90d, Spec F C4 — 플래그로 조정 가능 = 위험감내 재량)·주간 거래 수를 기계 검사. **FLAG 가 나오면 "규칙 위반 이력"에 추가**하고 사용자에게 보고.
|
||||
6. **결과 리포트** — 위반 0건이면 ✅, 있으면 ⚠️ 목록 + 그래도 진행할지 사용자 확인.
|
||||
|
||||
## 규칙
|
||||
|
||||
- **규칙 위반을 사용자가 무시할 수 있으나, 무시 사실을 원장에 기록**(나중 회고용).
|
||||
- 근거 링크 없는 매매는 기록하지 않음.
|
||||
- 면허 자문 아님 — 체크는 사용자가 정한 규칙의 기계적 대조일 뿐.
|
||||
@@ -0,0 +1,15 @@
|
||||
**원본:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **입력 검증** — 경로가 `raw/invest-daily/` 또는 `raw/invest-research/` 인지 확인. 아니면 거부.
|
||||
2. **추출 대상 판정** — 일반 개념이면 `wiki/invest-concepts/`(`invest-concept-template`), 전략 규칙이면 `wiki/invest-strategy/strategy.md`에 규칙 추가.
|
||||
3. **Claim 연결** — canonical의 모든 Knowledge Point/규칙은 raw의 `#C<n>` claim을 Supporting Claim으로 링크. 근거 없으면 `UNSUPPORTED_DECISION` 라벨.
|
||||
4. **양방향 링크** — concept↔strategy, invest-hub upward link 추가.
|
||||
5. **로그** — `wiki/log.md`에 한 줄: `YYYY-MM-DD HH:mm /invest-ingest — <입력> → <출력>`.
|
||||
|
||||
## 규칙
|
||||
|
||||
- **출력은 wiki/invest-concepts/ 또는 invest-strategy/ 로만.** invest-plan은 `/invest-plan`이 생성.
|
||||
- 검증 안 된(판정 REJECT/needs-confirmation) claim은 canonical로 올리지 않음.
|
||||
- 환각 금지 — raw에 없는 사실 생성 금지.
|
||||
@@ -0,0 +1,15 @@
|
||||
**메모:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **전제 확인** — `wiki/invest-strategy/strategy.md` 존재 + `status ≥ draft`. 없으면 "먼저 전략을 seed 하세요" 안내.
|
||||
2. **프로필 게이트 (실행 전 필수값 — Spec F C1)** — strategy 프로필의 핵심값(**목표금액·기간·최대감내손실 MDD**)이 비어 있으면 **AskUserQuestion 으로 묻어 채운다**(이 값들이 ①~⑤ 규칙·리밸런싱 밴드의 기준점). 사용자가 거부/미정이면 그 항목만 `NEEDS_CONTEXT` 로 두고 *가능한 범위만* 계획(되묻고 종료가 아니라 묻고 이어감). **과세소득(민감정보)은 강제하지 않고 권고만** — 무소득/미확인이면 절세계좌 보류 유지(전략 ④). 채운 값은 strategy 프로필에 반영.
|
||||
3. **입력 수집** — strategy의 프로필·규칙 + 최근 `raw/invest-daily/` 스냅샷 + `raw/invest-ledger/ledger.md` 현재 포지션.
|
||||
4. **계획 산출** — 없으면 `templates/invest-plan-template.md`로 `wiki/invest-plan/active-plan.md` 생성, 있으면 갱신. 목표 배분·워치리스트·실행계획을 채움. **모든 항목에 근거 링크**.
|
||||
5. **규칙 사전 점검** — 계획이 전략 규칙(포지션 크기·리밸런싱 밴드·절세계좌 조건)을 위반하지 않는지 확인. 위반 시 플래그.
|
||||
6. **로그** — `wiki/log.md` 한 줄.
|
||||
|
||||
## 규칙
|
||||
|
||||
- 모든 배분·종목은 canonical/증거 링크 필수. 근거 없는 종목 금지.
|
||||
- 60만원 구간 기본값: 광범위 ETF 1~2개(전략 ① 규칙). 임의 집중 베팅은 `UNSUPPORTED_DECISION` 라벨.
|
||||
@@ -0,0 +1,35 @@
|
||||
**조사 주제:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **인자 검증** — 비면 주제 요청. 파일 슬러그는 `YYYY-MM-DD-<kebab-주제>.md` (naming-conventions).
|
||||
2. **파일 존재 확인** — 있으면 덮어쓰지 말고 안내 후 종료.
|
||||
3. **스캐폴딩** — `templates/invest-research-template.md` 복사, frontmatter 치환.
|
||||
4. **`deep-research` 스킬 호출 (명시 — Spec F V3)** — `deep-research` 스킬로 다출처 조사. 권위 출처(학술·공식·vendor-research) 우선, 블로그는 약함 표기. 각 출처에서 **verbatim 인용(byte-for-byte)** 추출 후 proof manifest로 원문 일치 확인(evidence-first-research). Claim 분리 + KEEP/CORRECT/REJECT 판정 채움.
|
||||
5. **고위험 claim 3표 quorum 검증 (기본값 — P2-17 반전, opt-out 명시제)** — 매매 결정에 직결되는 수치/주장(가격·수익률·MDD·세율 등)은 단일 패스 KEEP/CORRECT/REJECT 로 끝내지 않는다. 3표는 **cross-vendor 1+1+1** (`rules/extraction-tiering.md` T1 — codex/agy 모두 web 검증 가능, 검증된 사실):
|
||||
- **Claude 1표**: read-only 검증 subagent 1개 dispatch (WebSearch 가능). 해당 claim 을 **refute 시도**(권위 출처 재확인)하고 `finding: <ClaimID> action: KEEP|DOWNGRADE|REJECT` 형식의 ```wiki-verdict``` 블록을 출력 → `/tmp/invest-research-vote-claude.md`.
|
||||
- **외부 2표**: 고위험 claim 행(ClaimID 포함)을 findings 파일로 저장 후 — 외부 엔진은 web 재확인이 가능하므로 조사 노트를 `--context-files` 로 전달:
|
||||
|
||||
```bash
|
||||
cd scripts/deep-research && python3 -m deep_research.vote --backend codex \
|
||||
--findings /tmp/invest-research-findings.md --context-files raw/invest-research/<노트>.md --out /tmp/invest-research-vote-codex.md
|
||||
cd scripts/deep-research && python3 -m deep_research.vote --backend antigravity \
|
||||
--findings /tmp/invest-research-findings.md --context-files raw/invest-research/<노트>.md --out /tmp/invest-research-vote-agy.md
|
||||
```
|
||||
|
||||
- `python3 .claude/hooks/wiki_quorum.py /tmp/invest-research-vote-claude.md /tmp/invest-research-vote-codex.md /tmp/invest-research-vote-agy.md` 합산 — **KILL** → 해당 claim 판정을 REJECT 로 기록, **UNVERIFIED** → `needs-confirmation` 표기(매매 근거로 사용 금지), **DOWNGRADE** → Strength 하향.
|
||||
- **외부 표 생성 실패 시** (vote.py exit 1) 해당 표만 Claude read-only 검증 subagent 추가 dispatch 로 대체 (fallback) — 표별 엔진 출처를 노트에 funnel 로 기록 (no silent engine swap).
|
||||
- **opt-out**: 사용자가 명시적으로 빠른 모드를 요청한 경우에만 생략 + 노트에 "단일 패스 한계" 명시. 더 강하게는 deep-research **Workflow(3표 quorum)** = `Workflow` opt-in("ultracode", Spec D).
|
||||
6. **사용자 안내** — 경로 + "검증된 결론은 `/invest-ingest`로 canonical 추출."
|
||||
|
||||
## 규칙
|
||||
|
||||
- verbatim 인용은 의역 금지. proof manifest 미통과 인용은 삭제.
|
||||
- 출처 등급 명시(공식 vs 블로그). 회사/블로그 사례를 일반 법칙으로 격상 금지.
|
||||
- 내 적용 결론은 raw에 쓰지 않음(canonical에서).
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,23 @@
|
||||
**범위:** {{arguments}} (비면 전체)
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **입력** — `raw/invest-ledger/ledger.md`(포지션·손익) + `wiki/invest-plan/active-plan.md`(목표) + `wiki/invest-strategy/strategy.md`(규칙).
|
||||
2. **점검 항목**:
|
||||
- 목표 배분 대비 현재 비중 이탈(리밸런싱 필요?)
|
||||
- 손익 vs 목표 진척
|
||||
- 패닉셀/과다거래 이력(원장 규칙 위반 누적)
|
||||
- stale: 워치리스트 종목 근거(`raw/invest-research/`)가 오래됨(>90일)?
|
||||
- 절세계좌 활용도
|
||||
3. **원장 손익 요약 갱신 — 산술은 스크립트가 (LLM 암산 금지, P2-17)**:
|
||||
```bash
|
||||
python3 .claude/hooks/invest_ledger_check.py --report
|
||||
```
|
||||
출력(매수/매도 합·누적 수수료·종목별 순수량·매수가중 평균단가·주간 거래 수)을 그대로 ledger "손익 요약" 섹션에 반영. 평가금액·환차손익·세후 추정만 출처 있는 현재가/환율로 별도 계산(출처 링크 필수).
|
||||
4. **리포트** — 발견 + 권고(리밸런싱/추가조사). 권고도 근거 링크.
|
||||
5. **로그** — `wiki/log.md` 한 줄.
|
||||
|
||||
## 규칙
|
||||
|
||||
- 권고는 강제가 아님. 사용자 결정 보조.
|
||||
- 새 사실 생성 금지 — 기존 ledger/plan/strategy/raw 기반 재구성만.
|
||||
@@ -0,0 +1,168 @@
|
||||
wiki 품질을 검사합니다.
|
||||
|
||||
**대상:** {{arguments}} (지정 안 하면 `wiki/` 전체)
|
||||
|
||||
## 작업 절차 — 결정론 선행 (LLM 수기 재연 금지)
|
||||
|
||||
1. **구조 린터 전수 실행 (필수 1단계)**: `python3 .claude/hooks/wiki_structure_lint.py --all`
|
||||
- 깨진 링크(`BROKEN_LINK`/`BROKEN_MD_LINK`) → **CRITICAL**, 섹션·frontmatter 누락(`MISSING_SECTION`/`MISSING_FRONTMATTER`)·`UNMAPPED_SOURCE_TYPE`·`NAMING_VIOLATION` → **WARN** 으로 그대로 흡수.
|
||||
- 이 검사들을 LLM 이 수백 파일에서 수기로 재연하지 않는다 — D군의 해당 항목은 린터 출력이 SSOT.
|
||||
2. **stale 결정론 집계**: `python3 .claude/hooks/wiki_structure_lint.py --stale`
|
||||
- 90/30/14일 임계(C군)를 기계가 계산 — LLM 날짜 암산 금지. 출력(`STALE_90`/`RECHECK_30`/`NEEDS_CONFIRMATION_14`)을 WARN 으로 흡수.
|
||||
3. **의미 검사** — 아래 체크리스트(A0/A/B/D 잔여/E/F + 투자 트리)에서 결정론 린터가 못 보는 *의미* 판정만 수행. 대상이 넓으면 `wiki-research-lane` 슬라이스 병렬 위임.
|
||||
|
||||
## 검사 항목
|
||||
|
||||
### A0. Claim Traceability
|
||||
|
||||
- [ ] `raw/official-docs/` 또는 `raw/company-tech-blogs/` 문서에 `## Claims Extracted` 가 없음
|
||||
- [ ] Claim row 의 `Evidence quote` 가 `## 핵심 인용` 또는 PASS proof manifest 와 연결되지 않음
|
||||
- [ ] `raw/branch-notes/` 문서에 `## Decision Evidence Map` 이 없음
|
||||
- [ ] Decision row 의 `Supporting Claims` 가 비어 있는데 `UNSUPPORTED_DECISION` 도 아님
|
||||
- [ ] 존재하지 않는 Claim ID 를 참조함 (`BROKEN_CLAIM_REFERENCE` — 형식: `<SOURCE-SLUG-UPPER>-C<n>`, `/migrate-claims` §Claim ID 규약)
|
||||
- [ ] 회사 기술 블로그 Claim 만으로 공식 best practice / 표준 / 공식 지원이라고 서술함
|
||||
- [ ] `wiki/concepts/` 문서에 `## Claim-backed Knowledge` 가 없거나 FACT/INFERENCE 구분이 없음
|
||||
|
||||
### A1. 구현 가이드 추적성 (CLAUDE.md §15.5 — 3-rule)
|
||||
|
||||
branch-note 의 `## 구현 가이드 / Implementation Specification` 섹션에 대해:
|
||||
|
||||
- [ ] sub-section / row 에 Trace 표시(`D<n>` Decision ID + Claim ID reference) 누락 (R1 위반)
|
||||
- [ ] 근거 raw 가 *원칙*만 권고하고 *detail*(메커니즘/명명/glob/algorithm)은 권고하지 않는 cell 에 `UNSUPPORTED_IMPL_DECISION` 라벨 + trade-off 한 줄 누락 (R2 위반)
|
||||
- [ ] 본 branch 결정 범위 밖 cell 잔존 — 도메인 특화 또는 타 branch 결정 영역(security/persistence/HTTP-standard 등)이 이관 없이 남음 (R3 위반, `OUT_OF_BRANCH_SCOPE`)
|
||||
|
||||
### A. 출처 / 신뢰도
|
||||
|
||||
- [ ] 단정적 진술인데 Sources가 비어 있는 문장
|
||||
- [ ] `source_type: company-tech-blog` 문서를 "공식 best practice"처럼 서술
|
||||
- [ ] `source_type: llm-generated` 문서가 `confidence: high`로 설정됨
|
||||
- [ ] 외부 URL이 raw에 발췌 보존 없이 링크만 있음
|
||||
|
||||
### B. 프로젝트 증거
|
||||
|
||||
- [ ] 프로젝트 관련 진술에 증거 등급 누락
|
||||
- [ ] `documented-only` / `planned` 항목이 "구현했다"는 표현으로 작성됨
|
||||
- [ ] `wiki/portfolio/` · `wiki/interview/` · `wiki/blog/` 문서에 `actually-implemented` / `locally-verified` / `prod-verified` **이외** 등급이 섞임
|
||||
- [ ] 이력서/README용 문장에 `prod-verified` 또는 `locally-verified` 표기 없이 "운영", "프로덕션", "최적화" 같은 표현 사용
|
||||
|
||||
### C. Stale (→ 절차 2단계 `--stale` 출력이 SSOT — LLM 재계산 금지)
|
||||
|
||||
- [ ] `STALE_90` / `RECHECK_30` / `NEEDS_CONFIRMATION_14` 출력을 WARN 으로 보고
|
||||
|
||||
### D. 구조
|
||||
|
||||
- [ ] `wiki/llm-wiki.md` (vault MOC) 에 누락된 주요 허브 문서
|
||||
- [ ] `index.md` 파일 존재 (named hub 룰 위반 — `rules/linking-rules.md` §12)
|
||||
- [ ] `raw/`에만 존재하고 `wiki/`로 변환되지 않은 자료 (특히 `project-notes`, `errors`, `official-docs`, `company-tech-blogs`, `lectures`, `interviews`, `job-postings`, `blog-topics`)
|
||||
- **예외 — 영구 보관 정책:** `raw/daily-notes/`, `raw/branch-notes/`는 그 자체가 wiki로 옮겨지지 않는 것이 정상. 두 경로는 "**promotable 항목이 적절히 추출되었는지**"만 검사:
|
||||
- daily-note: `한 일` / `배운 점` / `트러블슈팅` / `면접·포트폴리오 옮길 만한 것`에 항목이 있지만 wiki에 대응 추출이 없는 경우 → WARN
|
||||
- branch-note: `status_label`이 `merged`인데 `완료 후 정리 → wiki 추출 대상`의 `actually-implemented` / `locally-verified` 항목이 `wiki/projects/`에 없는 경우 → WARN
|
||||
- `status_label`이 `abandoned`인 branch-note는 추출 누락 검사 제외 (의도된 미추출)
|
||||
- blog-topic: `wiki/blog/` 직접 변환 여부가 아니라 canonical 후보(`wiki/concepts/` 또는 `wiki/projects/`)와 상태(`captured`/`triaged`/`promoted`/`discarded`)가 명확한지 검사
|
||||
- [ ] ~~깨진 `[[wikilink]]`~~ → 절차 1단계 `--all` 출력(`BROKEN_LINK`/`BROKEN_MD_LINK`)이 SSOT
|
||||
- [ ] ~~frontmatter 필수 필드 누락~~ → 절차 1단계 `--all` 출력(`MISSING_FRONTMATTER`)이 SSOT
|
||||
|
||||
### E. Canonical 우회 검사 (§15 위반)
|
||||
|
||||
> 참고: 2026-06-10 부터 **쓰기 시점** 결정론 backstop 존재 — claim gate 가 파생 4종의 `## Sources` canonical 링크 + 원천 status 를 Write/Edit 시 차단한다. 본 검사는 *전수 retro* (훅 도입 전 문서·우회 경로 탐지) 용도로 유지.
|
||||
>
|
||||
> 경계: cross-doc 모순·위임 동기화(STALE_SUMMARY / CONTRADICTION / RESTATED / DANGLING·BARE 참조)는 `/sync` 의 영역 — 본 검사에서 중복 검사하지 않는다 (`rules/consistency-contract.md`).
|
||||
|
||||
파생 산출물(`wiki/interview/`, `wiki/portfolio/`, `wiki/blog/`)에 대해:
|
||||
|
||||
- [ ] 문서 Sources에 `[[wiki/concepts/...]]` 또는 `[[wiki/projects/...]]` 링크가 **하나도 없음** → CRITICAL (canonical 우회)
|
||||
- [ ] `wiki/portfolio/` 문서가 `wiki/projects/`를 Sources에 두지 않음 (concepts 단독 출처) → CRITICAL
|
||||
- [ ] 파생 문서의 원천 canonical 문서가 `status: reviewed | verified | published-ready`가 아님 → CRITICAL (status 미달 파생)
|
||||
- [ ] Sources가 `[[raw/...]]` 또는 `[[raw/daily-notes/...]]` 또는 `[[raw/branch-notes/...]]`만 가리킴 (canonical 미경유) → CRITICAL
|
||||
- [ ] 파생 문서가 원천에 없는 사실을 추가 진술 → WARN (`사실/추론/확인 필요` 분류 누락)
|
||||
|
||||
### F. 과장 표현
|
||||
|
||||
다음과 같은 표현이 있는지 grep:
|
||||
- "최적화했다" / "성능을 X배 개선했다" → 측정값과 검증 방법이 같이 있는지 확인
|
||||
- "운영 중" / "프로덕션에서" → `prod-verified` 등급이고 근거(로그/측정/릴리즈)가 있는지 확인. 없으면 CRITICAL.
|
||||
- "설계했다" → 실제 구현 여부와 별개임을 명확히 했는지
|
||||
- "도입했다" / "적용했다" → `actually-implemented` 이상 등급인지
|
||||
|
||||
## 출력 형식
|
||||
|
||||
검사 결과를 다음 4그룹으로 분류해 보고:
|
||||
|
||||
```
|
||||
[CRITICAL] — 즉시 수정 필요 (과장, 출처 위반, 증거 등급 오류)
|
||||
[WARN] — 검토 필요 (stale, 누락)
|
||||
[INFO] — 참고 사항 (포맷, 링크 일관성)
|
||||
[OK] — 통과
|
||||
```
|
||||
|
||||
각 항목은 파일 경로와 라인 번호(가능하면)로.
|
||||
|
||||
Claim traceability 위반은 가능한 경우 `UNSUPPORTED_DECISION`, `BROKEN_CLAIM_REFERENCE`, `MISSING_CLAIMS_EXTRACTED` 같은 명명된 실패 모드로 보고.
|
||||
|
||||
## `--fix-plan` 모드 (선택)
|
||||
|
||||
`/lint --fix-plan [대상]` 으로 실행하면 위 검사 결과에 더해 **구조화된 수정 계획**을 만든다. 여전히 *무단 자동 수정은 하지 않는다* — 계획을 표로 제시하고 **사용자 승인 후에만** 적용한다. 보고→수동 판단→수정 요청→재검사의 왕복을 줄이는 것이 목적(자동수정 금지 원칙은 유지).
|
||||
|
||||
각 CRITICAL / WARN finding 을 다음 행으로 구조화:
|
||||
|
||||
| Finding | 필요한 수정 | 대상 파일:line | 위험 | 승인 필요? | 패치 범위 |
|
||||
|---|---|---|---|---|---|
|
||||
| `<실패 모드 + 한 줄>` | `<무엇을 어떻게 바꾸는가>` | `path:line` | low / med / high | yes / no | `<몇 줄 / 어느 섹션>` |
|
||||
|
||||
위험도·승인 기준:
|
||||
|
||||
- **high (승인 필요)**: 본문 의미 변경·삭제·문장 rewrite·파일 rename(wikilink 영향). 개별 승인.
|
||||
- **med**: frontmatter 값 변경, 섹션 구조 추가. 묶음 승인 가능.
|
||||
- **low (`승인 필요? = no`)**: 누락 frontmatter 키 추가, placeholder 보강, 깨진 링크 경로 수정. low 항목만 한꺼번에 적용 제안 가능.
|
||||
- INFO 는 fix-plan 에 넣지 않는다(참고용).
|
||||
- 적용 후에는 PostToolUse 구조 린터(`wiki_structure_lint.py`)가 자동 재검증한다.
|
||||
|
||||
제시 순서: ① fix-plan 표 출력 → ② "low 항목 N개 일괄 적용할까요? high 항목은 개별 확인" 질의 → ③ 승인된 항목만 Edit.
|
||||
|
||||
### CRITICAL ≥5건 → 적대 quorum 검증 (락인 전 필수)
|
||||
|
||||
CRITICAL finding 이 **5건 이상**이면 fix-plan 을 락인하기 전에 자기확증을 깬다. N=3 은 **cross-vendor 1+1+1** 로 구성한다 (`rules/extraction-tiering.md` T1 — 독립 실패 모드로 falsification 강화 + Claude 토큰 절감):
|
||||
|
||||
1. **Claude 1표**: `wiki-adversarial-reviewer` dispatch (findings 목록 + source corpus 경로 + workspace 컨텍스트) → ```wiki-verdict``` 블록을 `/tmp/lint-vote-claude.md` 로 저장.
|
||||
2. **외부 2표**: findings 목록을 파일로 저장 후 (각 finding 에 ID 포함):
|
||||
|
||||
```bash
|
||||
cd scripts/deep-research && python3 -m deep_research.vote --backend codex \
|
||||
--findings /tmp/lint-findings.md --context-files <corpus 경로...> --out /tmp/lint-vote-codex.md
|
||||
cd scripts/deep-research && python3 -m deep_research.vote --backend antigravity \
|
||||
--findings /tmp/lint-findings.md --context-files <corpus 경로...> --out /tmp/lint-vote-agy.md
|
||||
```
|
||||
|
||||
3. 결정론 합산:
|
||||
|
||||
```bash
|
||||
python3 .claude/hooks/wiki_quorum.py /tmp/lint-vote-claude.md /tmp/lint-vote-codex.md /tmp/lint-vote-agy.md
|
||||
```
|
||||
|
||||
4. per-finding 판정을 fix-plan 에 기계 반영 — **KILL** → fix-plan 에서 제외(오탐), **UNVERIFIED**(정족수 미달) → 적용 보류 + 사용자 보고, **DOWNGRADE** → 위험도 한 단계 하향, **KEEP** → 그대로. 임계값(≥2 REJECT=KILL)은 변경 금지 — `wiki_quorum.py` 가 SSOT.
|
||||
5. **외부 표 생성 실패 시** (vote.py exit 1) 해당 표만 `wiki-adversarial-reviewer` 추가 dispatch 로 대체 (fallback 사다리) — 어느 표가 어느 엔진인지 funnel 로 보고 (no silent engine swap).
|
||||
6. CRITICAL <5건이면 기본 N=1 (단일 패스) 유지.
|
||||
|
||||
## 투자 트리(invest-*) 추가 검사
|
||||
|
||||
- `raw/invest-daily/`·`raw/invest-research/` 의 수치/주장에 **출처 링크 누락** → 플래그.
|
||||
- `wiki/invest-strategy/` 규칙 중 Supporting Claim 도 `UNSUPPORTED_DECISION` 라벨도 없는 행 → 플래그.
|
||||
- `wiki/invest-strategy/` 에 ⚠️ 고지 섹션 누락 → 플래그.
|
||||
- `wiki/invest-plan/` 항목 중 근거 링크 없는 종목/배분 → 플래그.
|
||||
- 2026 ISA 확대안 등 **미확정 수치를 확정처럼 단정** → 플래그.
|
||||
|
||||
## 로그 기록
|
||||
|
||||
`wiki/log.md`에 한 줄: `YYYY-MM-DD HH:mm /lint — <대상> → CRITICAL n, WARN n, INFO n` (`--fix-plan` 이면 `→ fix-plan: 적용 a / 보류 b` 추가)
|
||||
|
||||
## 규칙
|
||||
|
||||
- **무단 자동 수정 금지.** 기본은 보고만. `--fix-plan` 도 *승인된 항목만* 적용하며 사용자 확인 없이 본문을 바꾸지 않는다.
|
||||
- CRITICAL이 있으면 수정 제안을 같이 제시(`--fix-plan` 없이도).
|
||||
- `--fix-plan` 의 high 위험 항목은 절대 묶음 적용하지 않는다 — 개별 승인.
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,119 @@
|
||||
기존 문서를 Claim Traceability 구조로 마이그레이션합니다.
|
||||
|
||||
**대상:** {{arguments}}
|
||||
|
||||
## 원칙
|
||||
|
||||
이 명령은 좋은 마이그레이션 순서를 강제합니다. branch-note를 먼저 고치지 않습니다. 먼저 source claim을 만들고, 그 다음 branch decision을 연결하고, 마지막에 wiki FACT를 승격합니다.
|
||||
|
||||
## Phase 0 — Scope Inventory
|
||||
|
||||
1. 대상 scope를 확정합니다.
|
||||
- `all`: `raw/official-docs/`, `raw/company-tech-blogs/`, `raw/branch-notes/`, `wiki/concepts/`
|
||||
- `raw-sources`: `raw/official-docs/`, `raw/company-tech-blogs/`
|
||||
- `branch-notes`: `raw/branch-notes/`
|
||||
- `wiki-concepts`: `wiki/concepts/`
|
||||
- 특정 path: 해당 파일 또는 디렉터리
|
||||
2. 파일 목록을 정렬합니다.
|
||||
3. Evidence Matrix를 먼저 만듭니다.
|
||||
4. 10개 초과 파일이면 `wiki-research-lane` 또는 병렬 subagent slice로 나눕니다.
|
||||
|
||||
## Phase 1 — Raw Source Claim Migration
|
||||
|
||||
대상: `raw/official-docs/`, `raw/company-tech-blogs/`
|
||||
|
||||
각 파일에 대해:
|
||||
|
||||
1. 기존 본문을 삭제하지 않습니다.
|
||||
2. `templates/raw-source-template.md`를 기준으로 누락 섹션만 보강합니다.
|
||||
3. `## 핵심 인용` 또는 기존 quote/summary를 읽고 `## Claims Extracted`를 작성합니다.
|
||||
4. Claim ID를 안정적으로 부여합니다.
|
||||
- 형식: `<SOURCE-SLUG-UPPER>-C<number>`
|
||||
- 예: `KEYCLOAK-OIDC-C1`, `STRIPE-IDEMP-C2`
|
||||
5. `Strength`를 보수적으로 지정합니다.
|
||||
- official docs: `official-standard`, `official-vendor-doc`, `official-reference`
|
||||
- company blog: 기본 `company-case-study`
|
||||
- 불확실하면 `needs-confirmation`
|
||||
6. `Does not prove`와 `Usage Boundaries`를 반드시 채웁니다.
|
||||
7. 원문 quote가 있으면 `grep -nF` 또는 `sed -n` proof를 남깁니다.
|
||||
|
||||
완료 조건:
|
||||
|
||||
- 모든 source 문서에 `## Claims Extracted` 존재
|
||||
- 모든 Claim row에 `Claim ID`, `Claim`, `Evidence quote`, `Strength`, `Applies to`, `Does not prove` 존재
|
||||
- 회사 블로그 Claim을 공식 best practice로 승격하지 않음
|
||||
|
||||
## Phase 2 — Branch Decision Mapping
|
||||
|
||||
대상: `raw/branch-notes/`
|
||||
|
||||
Phase 1이 끝나지 않았으면 BLOCKED입니다. branch-note는 source Claim ID 없이는 정상 마이그레이션할 수 없습니다.
|
||||
|
||||
각 파일에 대해:
|
||||
|
||||
1. 기존 `## 결정 사항`, `## Sources / 근거`, `완료 후 정리`를 읽습니다.
|
||||
2. 중요한 구현 결정을 `Decision ID`로 분리합니다.
|
||||
- 형식: `D<number>` 또는 `<BRANCH-SLUG-UPPER>-D<number>`
|
||||
3. `## Decision Evidence Map`에 결정별 Supporting Claims를 연결합니다.
|
||||
4. 연결 가능한 Claim이 없으면 추측하지 않고 `UNSUPPORTED_DECISION`으로 둡니다.
|
||||
5. 확인해야 할 내용은 `## Claims To Verify`에 남깁니다.
|
||||
|
||||
완료 조건:
|
||||
|
||||
- 모든 branch-note에 `## Decision Evidence Map` 존재
|
||||
- 모든 중요한 decision은 Claim ID 또는 `UNSUPPORTED_DECISION`으로 분류
|
||||
- 존재하지 않는 Claim ID 참조 없음 (`BROKEN_CLAIM_REFERENCE` 0)
|
||||
|
||||
## Phase 3 — Wiki Concept / Project Promotion Check
|
||||
|
||||
대상: `wiki/concepts/`, 필요 시 `wiki/projects/`
|
||||
|
||||
1. `## Claim-backed Knowledge`를 추가합니다.
|
||||
2. source Claim 또는 branch Decision으로 뒷받침되는 내용만 `FACT`로 둡니다.
|
||||
3. 근거가 약한 설명은 `INFERENCE`, `needs-confirmation`으로 낮춥니다.
|
||||
4. 회사 기술 블로그 단독 근거는 case-study로 표현합니다.
|
||||
|
||||
완료 조건:
|
||||
|
||||
- wiki FACT는 Supporting Claims를 가짐
|
||||
- unsupported decision이 wiki FACT로 승격되지 않음
|
||||
|
||||
## Phase 4 — Controller Verification
|
||||
|
||||
최종 보고 전 다음을 기계적으로 계측합니다.
|
||||
|
||||
```bash
|
||||
find raw/official-docs raw/company-tech-blogs -maxdepth 1 -type f -name '*.md' | sort
|
||||
# 미마이그레이션 파일 목록 (주의: rg 의 -L 은 --follow 다 — files-without-match 는 긴 플래그만 존재)
|
||||
rg --files-without-match '^## Claims Extracted' raw/official-docs raw/company-tech-blogs
|
||||
rg --files-without-match '^## Decision Evidence Map' raw/branch-notes
|
||||
rg -n 'UNSUPPORTED_DECISION|BROKEN_CLAIM_REFERENCE|MISSING_CLAIMS_EXTRACTED' raw wiki docs
|
||||
```
|
||||
|
||||
보고서에는 반드시 다음을 포함합니다.
|
||||
|
||||
| Metric | Expected | Actual | Status |
|
||||
|---|---:|---:|---|
|
||||
| Raw source files with Claims Extracted | N | M | PASS/FAIL |
|
||||
| Branch notes with Decision Evidence Map | N | M | PASS/FAIL |
|
||||
| Broken Claim references | 0 | B | PASS/FAIL |
|
||||
| Unsupported decisions | report count | U | INFO |
|
||||
|
||||
## Verdict Rules
|
||||
|
||||
- `COMPLETE`: Phase 1~4 완료, missing required sections 0, broken references 0
|
||||
- `PARTIAL`: 지정 scope 내부는 완료했지만 전체 corpus가 아님
|
||||
- `BLOCKED`: source Claim migration 없이 branch-note mapping을 시도했거나, unread files가 있음
|
||||
|
||||
## 금지
|
||||
|
||||
- source Claim 없이 branch decision을 임의로 official-supported 처리 금지
|
||||
- 회사 기술 블로그만 보고 universal best practice라고 작성 금지
|
||||
- 기존 본문 삭제/요약으로 손실 발생 금지
|
||||
- 여러 파일을 처리하면서 Evidence Matrix 없이 완료 보고 금지
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,93 @@
|
||||
`/project` 로 만든 빈 project-note(hub)를 **다음 작업의 출발점이 될 만큼 깊게 채우는** 오케스트레이터입니다.
|
||||
기준선은 `raw/project-notes/ca-skeleton-operational-contract.md` 의 *caliber*(엄격성)이며, 내용·섹션 구성은 프로젝트마다 다릅니다. 목표 prose 에서 문제·아키텍처·기술결정·branch 분해를 도출하고, 근거 없는 결정은 자동조사하되 **사용자 소유 결정(범위/우선순위/목표)은 직접 질문**으로 채우고, 끝에 readiness 게이트로 검증합니다.
|
||||
|
||||
**프로젝트 slug + 목표:** {{arguments}}
|
||||
|
||||
## 참조 (작업 시 정독)
|
||||
|
||||
- `rules/project-readiness-gate.md` — 끝에 적용할 4축(R1~R4) + v2 project contract + legacy 정책 + 실패 모드.
|
||||
- `rules/consistency-contract.md` — stable decision owner, pinned revision, Reference-Only 규칙.
|
||||
- `rules/naming-conventions.md` §2.1 — Branch 분해표 slug 규칙.
|
||||
- `rules/diagram-standards.md` — 아키텍처 .drawio / 시퀀스 Mermaid 컨퍼런스급 기준.
|
||||
- `templates/project-template.md` — 채울 대상 구조(특히 §3 아키텍처, §4 시퀀스, §6.1 Project Decision Registry, §8.0 Work Item Registry).
|
||||
- `CLAUDE.md` §11, §15 — 근거 없는 결정 금지, 파생 규칙.
|
||||
|
||||
### 프로젝트 ground truth (필수 — 추측 방지, 읽기 전용)
|
||||
|
||||
대상 프로젝트에 코드 레포가 있으면 그 레포가 SSOT. 예: ca-tmpl 류는 `/home/donghyeon/workspace/ca-tmpl` 의 `CLAUDE.md`/`AGENTS.md`/`src/<module>`/`docs/registries/*.yaml` 를 읽어 명세를 실제 구현·계약에 정합시킨다(ground-truth repo 기억 참조). `actually-implemented` 주장은 `src/` grep 으로만 확정.
|
||||
|
||||
## 작업 절차
|
||||
|
||||
아래의 본문 변경은 실제 target에 즉시 쓰지 않는다. repo와 같은 layout의 격리된 `<run-root>`에 candidate hub를 만들고, 모든 검증이 끝난 뒤 `document_commit.py`의 한 transaction으로만 target·projection·MOC·semantic certificate를 반영한다.
|
||||
|
||||
1. **전제 확인**
|
||||
- slug 가 비면 slug 를 요청(종료 — 대상 파일을 모름). 목표 prose 가 비면 **종료하지 말고 AskUserQuestion 으로 목표를 물어 답을 받아 진행**(되묻고 종료가 아니라 묻고 이어감).
|
||||
- slug 노트가 **없으면** 채우지 말고 `/project <slug>` 먼저 실행하도록 안내(종료). 채움은 본 명령, 생성은 `/project`.
|
||||
- 노트의 §1 개요가 비고 목표도 못 받으면 `NEEDS_CONTEXT` 로 표기하고 그 부분만 보류한 채 가능한 범위 진행.
|
||||
- **v2 preflight**: 신규 작성·본 명령으로 갱신하는 project-note 는 `project_revision` 양의 정수 + §6.1 Project Decision Registry + §8.0 Work Item Registry 가 필수다. 없는 기존 문서는 `LEGACY_PROJECT_CONTRACT` warning 을 보고한 뒤 skeleton 을 추가하되, 기존 결정에 stable ID 를 임의 부여하지 않는다. 귀속이 모호하면 사용자에게 묻는다.
|
||||
|
||||
2. **프로젝트 ground truth 확인 (읽기 전용)** — 대상 repo 코드/기존 raw/관련 노트를 읽어 현황 파악. 코드 미확인 항목은 `documented-only`/`planned` 로 표기. 레포 부재 시 `NO_GROUND_TRUTH` 라벨 + 한계 보고.
|
||||
|
||||
3. **문제정의·성공기준 구체화 (R1)**
|
||||
- 추상 표현 거부. 구체 시나리오·수치로.
|
||||
- ★ **명확화 질문** — 정해야 하는데 근거·기본값이 없는 *사용자 소유 결정*(프로젝트 범위/우선순위/성공기준 임계)은 추측·UNSUPPORTED 라벨 대신 **AskUserQuestion 으로 직접 묻는다**. (branch-spec 과의 차이: hub 는 사용자 in-the-loop.)
|
||||
|
||||
4. **아키텍처 + 시퀀스 (R2)**
|
||||
- 핵심 user flow 의 Mermaid 시퀀스를 자동 작성(happy + error path, autonumber).
|
||||
- 아키텍처 `.drawio` 는 자동생성 불가 → §3.1 에 **`needs-diagram` 표시**를 남기고 사용자가 작성/요청하도록 안내. **임베드 경로는 백틱 코드로 표기**(예: `` `![[raw/diagrams/<slug>/architecture-overview-YYYY-MM-DD.drawio.svg]]` ``) — 미작성 파일을 활성 임베드로 두면 9a 린터가 `BROKEN_LINK` 로 잡으므로, 백틱 코드 placeholder 로 비활성화(린터의 inline code-span 면제 활용). 사용자가 실제 파일 작성 후 백틱을 풀어 활성 임베드로 바꾼다.
|
||||
- 다이어그램 **품질(≥95)은 게이트가 판정하지 못한다** — 사용자가 `wiki-diagram-reviewer` 를 *별도로* 실행해 확인(R2 ≥95 는 권고 단계, Ready 조건 아님). 게이트는 *존재 + error-path 시퀀스*만 본다.
|
||||
|
||||
5. **기술결정 소싱 (R3) — hub 레벨**
|
||||
- 주요 기술결정마다 §6 표에 `검토한 대안` 을 적고, 채택 근거를 **`wiki-source-summarizer` dispatch** 로 외부자료(official/대기업 블로그) raw 화 → `근거 자료` 칸에 `[[raw/...]]` 링크. (`parent` = `[[raw/project-notes/<slug>]]` — summarizer 는 project parent 를 받는다.)
|
||||
- **`wiki-decision-researcher` 는 여기서 dispatch 하지 않는다** — 그 agent 의 입력 계약은 `parent_branch`(branch-note) 필수다. *결정별 깊은 대안 비교/조사*는 hub 가 아니라 **branch 단계(`/branch-spec`)로 미룬다**(hub→branch 핸드오프). hub 는 *프로젝트 차원 stack 결정*의 근거 소싱까지만.
|
||||
- **덮어쓰기 가드**: §6 행의 `근거 자료` 칸이 *이미 채워져 있으면* 그 행은 소싱 dispatch 하지 않고 기존 링크 보존(C#6).
|
||||
- **bound: 회당 최대 6개 결정.** 초과분은 채우지 말고 `deferred` 로 *§6 행에 명시 표기*(silent 절단 금지). `deferred` 행은 R3 Blocking 면제(Advisory) — auditor 가 인식하도록 행에 `deferred` 토큰을 남긴다.
|
||||
- 조사 후에도 근거 없으면 `UNSUPPORTED_DECISION` 라벨 + trade-off 한 줄.
|
||||
|
||||
6. **Stable Project Decision Registry (R3 — owner)**
|
||||
- project-wide 결정마다 `DEC-<PROJECT>-<DOMAIN>-NNN` ID 와 양의 정수 revision 을 부여한다. `<PROJECT>`·`<DOMAIN>` 은 uppercase kebab-case.
|
||||
- 의미가 같은 결정은 기존 ID 를 유지한다. 의미·경계가 바뀌면 decision revision 과 `project_revision` 을 증가시킨다. 단순 오탈자·링크 보정은 증가시키지 않는다.
|
||||
- 표에는 결정의 1줄 요약·상태·owner·근거를 기록하고 상세 대안/트레이드오프는 §6 의 owner 내용으로 연결한다.
|
||||
|
||||
7. **Work Item Registry (R4 — 핸드오프)**
|
||||
- §8.0 표에 `{WI-<PROJECT>-NNN | branch slug | 측정가능 완료조건 | DEC-...@revision | 선행 WI ID | status}` 를 채운다.
|
||||
- `Applies Decisions` 는 §6.1 에 실재하는 pinned ref 만, `Dependencies` 는 §8.0 에 실재하는 `WI-...` 만 허용한다. 결정 상세·메커니즘은 적지 않는다.
|
||||
- project 직접 자식 branch 생성 surface 는 `/branch-from-project <project> <WI-ID>` 다. `/branch` 를 handoff 로 사용하지 않는다.
|
||||
|
||||
8. **검증등급 + 면접·외부공개 경계** — project-template §9·§10 채움. 코드 확인 기준 등급(actually-implemented/locally-verified/...).
|
||||
|
||||
9. **필수 hub semantic audit + 원자 commit**
|
||||
- staged candidate에 `semantic_gate: required`를 선언하고 다음 순서를 고정한다: typed contract → semantic surface → assertion audit → deterministic candidate → verdict audit → exact quote proof → validated audit → certificate → quality → atomic commit.
|
||||
- `python3 harness/runtime/typed_contract_check.py --root <run-root>`와 `python3 harness/runtime/semantic_surface_extractor.py --root <run-root> --check --path raw/project-notes/<slug>.md`가 먼저 PASS해야 한다.
|
||||
- extractor JSON으로 `semantic_audit.py assertion-request`를 만들고 `wiki-semantic-coherence-auditor`를 assertion phase로 dispatch한다. 결과는 `semantic_candidate_builder.py --root <run-root> --document raw/project-notes/<slug>.md --assertions <assertions.json>`로 검증한다.
|
||||
- candidate JSON으로 `semantic_audit.py verdict-request`를 만든 뒤 같은 auditor를 `hub` verdict phase로 dispatch한다. `AMBIGUOUS_AUTHORITY`, 모든 `CONTRADICTION`, `RESTATEMENT_DRIFT`, dropped candidate는 완료를 차단한다.
|
||||
- negative verdict의 양쪽 quote는 `proof_runner.py ... --repo-root . --run-root <run-root>`로 검증하고, `semantic_audit.py validate ... --root <run-root> --run-root <run-root>`가 PASS여야 한다.
|
||||
- audit request/result의 `namespace: run` hash reference를 `document-commit/v1`에 넣고 `document_commit.py --dry-run --semantic-run-root <run-root>` → 동일 `plan_sha256`의 `--apply`를 한 번 실행한다. `semantic-certificate` quality extension과 certificate write는 같은 transaction 안에서 수행된다.
|
||||
|
||||
10. **자동 게이트 — readiness (맨 끝, 내부 단계)**
|
||||
- **(9-contract) v2 계약 점검** — `project_revision > 0`; 모든 Decision ID/revision 유효·owner 중복 없음; 모든 WI ID/branch slug 유일; Applies Decisions/Dependencies resolve; unpinned ref 없음. 실패 코드는 `rules/project-readiness-gate.md` 명칭을 사용한다.
|
||||
- **(9-coverage) 관심사 누락 점검 (depth 의 짝, 경량)** — §2 ground truth 에서 식별한 프로젝트 관심사 목록(예: security / async / multi-tenancy / data-retention)과 §6·§7·§8.0 의 커버리지를 대조. 빠진 domain 은 §8.0 Work Item Registry 의 deferred item 또는 §7 에 *명시적으로 표기*(silent 누락 금지). (full `coverage-auditor` 포트는 v2 — 여기선 수동 대조.)
|
||||
- **(9a) 1차 결정론** — `python3 .claude/hooks/wiki_structure_lint.py --file raw/project-notes/<slug>.md` (repo-루트 상대경로로 호출). proxy(PROJECT_NO_DIAGRAM/PROJECT_NO_BRANCH_TABLE)·frontmatter·링크 확인.
|
||||
- **(9b) 2차 의미** — 통과 시 `project-readiness-auditor` dispatch(노트 경로 전달). R1~R4 판정.
|
||||
- **(9c) 루프백 (천장 2회 + 사용자행동 탈출)** — Not-ready(Blocking)면 → §3~§8 로 되돌아가 *자동으로 채울 수 있는* Blocking(근거 보강·시퀀스 error path 등)을 보강 → 9a·9b 재실행. **루프 천장 2회.** 단 *사용자 행동으로만 해소되는* Blocking(`DIAGRAM_PENDING_USER` 아키텍처 작성 / 사용자 소유 결정 미입력)은 **자동 루프 대상 아님** — 판정을 `Ready-pending-user` 로 내고 *어떤 사용자 행동이 무엇을 unblock 하는지* 보고한 뒤 step 11 으로 **깨끗이 종료**(무한루프 금지, `rules/project-readiness-gate.md` 판정 규칙 참조).
|
||||
|
||||
11. **요약 보고 (짧게, 상세는 노트에)**
|
||||
- 사람이 5초에 읽을 요약만: `project revision R / stable decisions N / UNSUPPORTED K / 조사 M / deferred D' / work items B / needs-diagram D / 누락 domain X / readiness: Ready|Ready-pending-user|Not-ready (Blocking 축 인용)`.
|
||||
- `Ready-pending-user` 면 *사용자가 할 행동*을 한 줄씩(예: "① <slug> 아키텍처 .drawio 작성 후 백틱 해제 → wiki-diagram-reviewer ≥95").
|
||||
- 통과 못하면 *무엇을 더 채워야 하는지* 한 줄씩(축·finding 인용).
|
||||
|
||||
## 규칙
|
||||
|
||||
- **추측해서 FACT 로 채우지 않는다.** 근거 없으면 자동조사 → 실패 시 `UNSUPPORTED_*` 라벨. 단 *사용자 소유 결정*은 라벨 대신 **AskUserQuestion**.
|
||||
- **`actually-implemented` 는 `src/` grep 으로만 확정.** note→note 자기보고 전이 금지.
|
||||
- **기존 사용자 작성 본문 보존** — 채움은 빈 셀/skeleton 에만.
|
||||
- **자동조사 bounded** — §5 의 6개 한도. 초과는 `deferred` 명시(R3 면제).
|
||||
- **정의된 agent 외 임의 agent를 만들지 않는다.** 본 명령이 직접 dispatch 하는 것은 `wiki-source-summarizer`(§5 hub 소싱), `wiki-semantic-coherence-auditor`(§9 assertion/verdict), `project-readiness-auditor`(§10 readiness)다. `wiki-diagram-reviewer`(≥95)는 *사용자가 별도 실행*하고 본 명령은 안 부른다. `wiki-decision-researcher`(결정별 깊은 대안조사)는 `parent_branch` 계약상 **branch 단계로 이관**(여기서 안 부름). `wiki-doc-author`(노트 생성/마이그레이션)는 `/project` 의 일.
|
||||
- **검증은 readiness 게이트에 위임** — 본 명령은 *채움*에 집중. 4축 판정 로직을 중복 구현하지 않는다.
|
||||
- `wiki/log.md` 기록 안 함 (`/branch`·`/depth` 와 동일).
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,32 @@
|
||||
프로젝트 1개의 최상위 hub 노트를 생성합니다. (채움은 `/project-spec`, 생성은 본 명령.)
|
||||
|
||||
**프로젝트 slug:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **인자 검증** (`rules/naming-conventions.md` 준수)
|
||||
- 인자가 비어 있으면 사용자에게 프로젝트 slug 요청.
|
||||
- kebab-case 권장 (`ca-skeleton-operational-contract`, `keycloak-patterns-overview`).
|
||||
- branch prefix 4종 규칙은 **비적용** (그건 branch 전용). slug 는 프로젝트 이름.
|
||||
|
||||
2. **파일 존재 확인**
|
||||
- `raw/project-notes/<slug>.md` 가 이미 있으면 **덮어쓰지 말 것**. 기존 경로만 안내하고 종료.
|
||||
|
||||
3. **스캐폴딩**
|
||||
- `wiki-doc-author`(mode=create, category=project-note)에 위임이 **기본**(upward-link/tag 정규화 수행). 그게 불가할 때만 `templates/project-template.md` 직접 복사 → `raw/project-notes/<slug>.md`.
|
||||
- frontmatter `title`(slug 를 사람이 읽는 형태로), `status: draft`, `status_label: active`, `last_reviewed`(오늘) 치환.
|
||||
- **v2 필수**: `project_revision: 1` 을 유지하고 `## 6.1 Project Decision Registry`, `## 8.0 Work Item Registry` skeleton 을 삭제하지 않는다.
|
||||
- 본문 `# <title>` 헤더 치환. 나머지 placeholder·섹션은 **보존** — 추측해서 채우지 말 것.
|
||||
- **단, §8.0 Work Item Registry 의 예시 데이터 행은 제거**하고 헤더+구분선만 남긴 뒤 그 아래 `<!-- /project-spec 가 채움: WI-<PROJECT>-NNN | feature-<slug> | 측정가능 완료조건 | DEC-...@revision | WI dependency | planned -->` 주석으로 대체. 예시 행을 실제 row 로 오인하지 않게 한다.
|
||||
- project-note 는 cluster 의 root 이므로 Parent upward link 불요(자기 자신이 hub).
|
||||
|
||||
4. **사용자 안내**
|
||||
- 파일 경로 출력.
|
||||
- "이제 `/project-spec <slug> <프로젝트 목표>` 로 깊은 조사를 채우세요." 안내.
|
||||
|
||||
## 규칙
|
||||
|
||||
- **스캐폴딩만**. 내용을 추측해서 채우지 말 것 (채움은 `/project-spec`).
|
||||
- Project Decision Registry 와 Work Item Registry skeleton 을 삭제하지 말 것 — `/project-spec` 가 v2 handoff 로 채운다.
|
||||
- project-note 는 머지/완료 후에도 raw 에 **영구 보관**. verified 사실만 `/ingest` 로 `wiki/projects/` 에 추출.
|
||||
- `wiki/log.md` 는 기록하지 않음 (`/branch` 와 동일 정책).
|
||||
@@ -0,0 +1,39 @@
|
||||
`wiki/concepts/`의 일반 개념 문서를 **내 프로젝트 적용 문서**로 변환합니다.
|
||||
|
||||
**대상:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **개념 문서 읽기**
|
||||
- `wiki/concepts/<...>.md`의 Summary / Standard / Sources 파악
|
||||
|
||||
2. **관련 프로젝트 식별**
|
||||
- 내 프로젝트 자료(`wiki/projects/`, `raw/project-notes/`)에서 이 개념이 등장하는 곳 검색
|
||||
- 관련 프로젝트가 없으면 사용자에게 어느 프로젝트와 연결할지 물어봄
|
||||
|
||||
3. **증거 등급 판정**
|
||||
- 관련 프로젝트에서 이 개념이 어떤 등급으로 존재하는지 판정. **등급 어휘는 CLAUDE.md §6 프로젝트 증거 등급표가 SSOT** — 인라인 재나열 금지.
|
||||
- 모든 진술에 §6 등급 라벨을 붙인다.
|
||||
|
||||
4. **project 문서 생성** (`rules/naming-conventions.md` §2.11 nested 구조)
|
||||
- 대상 경로: `wiki/projects/<project-slug>/<concept-topic>.md` — **nested**, hyphenated flat (`<project>-<concept>.md`) 금지
|
||||
- `<project-slug>` 는 `raw/project-notes/<project-slug>.md` 의 슬러그와 일치 (cluster 정합성)
|
||||
- `<concept-topic>` 은 그 프로젝트 안에서 이 concept 의 적용 측면을 표현 (kebab-case, 4~6 단어)
|
||||
- 예: `wiki/projects/keycloak-patterns/oidc-handshake-application.md` (NOT `wiki/projects/keycloak-patterns-oidc-handshake.md`)
|
||||
- 프로젝트의 wiki sub-hub: sibling **named hub** `wiki/projects/<project-slug>.md` (folder-note 패턴, MOC) — 새 토픽 생성 시 hub 의 sub-doc 목록에도 등재. `index.md` 사용 금지 (`rules/linking-rules.md` §12).
|
||||
- `templates/wiki-project-template.md` 적용
|
||||
- "실제 구현 / 로컬 검증 / 문서·계획 / 면접 가능 범위 / 과장 금지" 섹션을 사실 기반으로 채움
|
||||
- 추측이나 일반화는 적지 않음
|
||||
|
||||
5. **양방향 링크**
|
||||
- 원본 concept 문서의 "Project Application" 섹션에 새 project 문서를 `[[...]]`로 연결
|
||||
- 새 project 문서의 "관련 개념"에 원본 concept를 `[[...]]`로 연결
|
||||
|
||||
6. **로그 기록**
|
||||
- `wiki/log.md`: `YYYY-MM-DD HH:mm /projectize — <concept> → <project>`
|
||||
|
||||
## 규칙
|
||||
|
||||
- **개념 문서의 일반론을 내가 한 것처럼 옮기지 말 것.**
|
||||
- 사실 확인이 안 되는 부분은 `needs-confirmation`으로 두고 사용자에게 질문.
|
||||
- 면접에서 말할 수 있는 범위와 말하면 안 되는 부분을 **반드시** 분리.
|
||||
@@ -0,0 +1,34 @@
|
||||
wiki를 기반으로 질문에 답합니다.
|
||||
|
||||
**질문:** {{arguments}}
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **wiki/ 우선 검색**
|
||||
- 관련 키워드로 `wiki/` 전체 grep
|
||||
- frontmatter `tags`, `related_projects` 매칭
|
||||
- 관련 문서 2–5개 식별
|
||||
|
||||
2. **필요 시 raw 확인**
|
||||
- wiki에 정리된 내용이 부족하거나 출처 검증이 필요하면 `raw/` 추가 확인
|
||||
|
||||
3. **답변 구성**
|
||||
- 항상 **canonical(`wiki/concepts/`, `wiki/projects/`)을 우선** 검색. raw는 검증 보조로만 사용.
|
||||
- 다음 3구분을 **명확히 분리**:
|
||||
- **사실 (verified)**: canonical 문서에 `status: reviewed | verified | published-ready`이고 Sources가 있는 내용
|
||||
- **추론 (inferred)**: canonical 내용을 조합한 결론
|
||||
- **확인 필요 (needs-confirmation)**: wiki에 없거나 stale, 또는 원천 status가 `draft` 이하인 부분
|
||||
|
||||
4. **출처 명시**
|
||||
- 답변 끝에 참고한 wiki 문서를 `[[wikilink]]`로 나열
|
||||
|
||||
5. **문서화 제안**
|
||||
- 답변 과정에서 wiki에 없거나 stale한 내용이 있었다면
|
||||
- "다음 자료를 raw로 추가하고 `/ingest`하시는 것을 추천합니다" 형태로 제안
|
||||
|
||||
## 규칙
|
||||
|
||||
- **wiki에 없는 내용을 wiki 출처처럼 답하지 말 것.** 모르면 모른다고.
|
||||
- 프로젝트 관련 답변은 반드시 증거 등급을 함께 표시.
|
||||
- 면접/이력서 직결 답변은 `/lint` 통과한 문서만 사실로 인용.
|
||||
- 답변 길이는 질문 규모에 비례. 짧은 질문에 긴 답 X.
|
||||
@@ -0,0 +1,117 @@
|
||||
문서 간 모순·위임 동기화를 검사하고 수거합니다. (계약: `rules/consistency-contract.md` — Single-Owner + Reference-Only)
|
||||
|
||||
**대상:** {{arguments}} (지정 안 하면 `raw/branch-notes/` + `raw/project-notes/` 전수)
|
||||
|
||||
## 작업 절차 — 결정론 선행 (LLM 수기 재연 금지)
|
||||
|
||||
1. **결정론 검사기 (필수 1단계)**
|
||||
|
||||
```
|
||||
python3 .claude/hooks/wiki_consistency_check.py --all
|
||||
```
|
||||
|
||||
`--impact <slug>` 가 주어지면 대신 `python3 .claude/hooks/wiki_consistency_check.py --impact <slug>` (해당 노트의 결정을 참조하는 문서 역추적).
|
||||
- `--all`은 `.claude/hooks/wiki_graph_contract_check.py`의 v2 structured graph 검사를 이미 병합한다. 디버깅은 독립 CLI `python3 .claude/hooks/wiki_graph_contract_check.py --all`로 재현한다.
|
||||
- 신규 validation output 8종: `AMBIGUOUS_WIKILINK`(동명 basename은 full path 필수) + graph `MISSING_PROJECT_BINDING` / `MISSING_INHERITED_DECISION` / `STALE_INHERITANCE_REVISION` / `CONFLICTS_WITH_PROJECT_DECISION` / `UNDECLARED_OVERRIDE` / `MISSING_EXPECTED_EDGE` / `DUPLICATE_DECISION_OWNER`. Link ambiguity는 structure lint, graph 7종은 consistency `--all`이 각각 수거한다.
|
||||
- Parent edge는 child의 structured `project` / `parent_branch` 또는 `Branch Contract Packet`이 canonical이다. Hub의 `<!-- GENERATED: children:start -->`…`<!-- GENERATED: children:end -->` 블록은 reverse view로만 대조하며, `MISSING_EXPECTED_EDGE`는 batch/post-sync에서만 판정한다.
|
||||
- marker/table 없는 legacy 문서는 strict failure가 아닌 `LEGACY_GRAPH_CONTRACT` migration warning + skip으로 보존한다.
|
||||
- findings 를 그대로 흡수: `DANGLING_DECISION_REF` / `DANGLING_SECTION_REF` / `DUAL_OWNERSHIP` → **CRITICAL**, `BARE_DECISION_REF` / `BARE_OWNER_REF` → **WARN**.
|
||||
- 이 검사들을 LLM 이 수기로 재연하지 않는다 — 검사기 출력이 결정론 SSOT.
|
||||
|
||||
2. **typed contract 검사**
|
||||
|
||||
```
|
||||
python3 harness/runtime/typed_contract_check.py --root .
|
||||
```
|
||||
|
||||
owner/revision/import/delegation/projection findings를 별도 `typed findings`로 수거한다. 실패해도 의미 결과로 덮어쓰지 않으며 explicit blocking으로 통합한다.
|
||||
|
||||
2-b. **투영 drift · 레이아웃 · MOC · branch postflight (필수 — 위 두 검사가 보지 못하는 축)**
|
||||
|
||||
```
|
||||
python3 harness/runtime/contract_projection.py --check --root .
|
||||
python3 harness/runtime/layout_check.py --root .
|
||||
python3 harness/runtime/moc_indexer.py --check
|
||||
for f in raw/branch-notes/*.md; do
|
||||
python3 harness/runtime/branch_contract_check.py "$f" --postflight --root .
|
||||
done
|
||||
```
|
||||
|
||||
> **이 검사들이 `/sync` 에 없던 동안 무슨 일이 있었나** (2026-07-21~22 실측):
|
||||
> `branch_contract_check` 는 vault cutover 이후 심링크를 resolve 한 경로로 위치를 판정해
|
||||
> **모든 branch 를 거부**했고(status=ERROR), 아무도 그것을 돌리지 않아 `contract_packet_sha256`
|
||||
> drift 가 두 프로젝트 **82건** 쌓이는 동안 sweep 은 계속 `findings 0` 을 반환했다.
|
||||
> `contract_projection --check` 는 셀 정규화 버그로 깨진 코드스팬 15곳을 들고 있었고,
|
||||
> `moc_indexer --check` 는 hub reverse-view 3건이 낡은 상태였다.
|
||||
> 즉 "consistency + typed 통과 = 깨끗하다"는 성립하지 않는다 — 축들이 서로를 못 본다.
|
||||
>
|
||||
> 비용은 전부 합쳐 ~6.5초다(2026-07-22 실측: consistency 0.56s · typed 0.29s ·
|
||||
> projection 0.40s · layout 1.41s · structure lint 2.32s). 느려서 뺄 이유가 없다.
|
||||
|
||||
- `contract_projection` / `moc_indexer` 가 `DRIFT` 면 **수기로 고치지 말고** `--write` 로 재생성한다. 생성기가 SSOT 이므로 수기 수정은 다음 재생성에서 되돌아온다.
|
||||
- `layout_check` 의 `MIGRATION_LEGACY_EXTRA` / `INVALID_COMPATIBILITY_SYMLINK` 는 호환 심링크가 실파일로 대체됐다는 신호다(writer 가 정본 대신 링크를 덮어쓴 경우). 정본과 링크가 갈라진 split-brain 이므로 CRITICAL.
|
||||
- postflight 는 `GENERATED_REGION_DRIFT` / `CONFLICTS_WITH_PROJECT_DECISION` / `STALE_INHERITANCE_REVISION` / `INHERITED_DECISION_MISMATCH` 를 branch 단위로 판정한다. `status: ERROR` 는 "통과"가 아니라 **검사가 실행조차 못 했다**는 뜻이니 findings 0 으로 세지 말 것.
|
||||
|
||||
3. **팩킷 준비 (T0 결정론 발췌 — 0토큰, `rules/extraction-tiering.md`)**
|
||||
|
||||
```
|
||||
python3 .claude/hooks/wiki_consistency_check.py --packets [slug] > /tmp/sync-packets.md
|
||||
```
|
||||
|
||||
참조 엣지 양쪽(citing ±2줄 / owner D-row)의 맥락을 결정론 추출. auditor 는 corpus 대신 이 팩킷 파일을 **1차 입력**으로 소비한다 — 판결이 모호한 엣지만 원문 해당 라인을 Read.
|
||||
|
||||
4. **명시 참조 엣지 의미 대조 — `wiki-consistency-auditor` dispatch**
|
||||
|
||||
- 입력: 1단계 검사기 출력 + **팩킷 파일 경로**(`/tmp/sync-packets.md`) + **대조할 참조 엣지 목록** (엣지 = citing 문서 / owner 문서 / D-id·§-id + 양 노트 경로).
|
||||
- 기본 슬라이스: DANGLING / DUAL_OWNERSHIP 관련 엣지 + 사용자가 지정한 대상 경로의 엣지. **전수 대조는 엣지 수를 먼저 보고하고 사용자 확인 후에만.**
|
||||
- 엣지 **>20개면 슬라이스로 분할해 병렬 dispatch**.
|
||||
- 출력: 엣지별 `CONSISTENT` / `STALE_SUMMARY` / `CONTRADICTION` / `RESTATED_FOREIGN_DECISION` verdict (+ wiki-verdict/wiki-stats 블록).
|
||||
|
||||
5. **local/hub semantic certificate 수거 + impact audit**
|
||||
|
||||
- `semantic_certificate.py --root . --check`로 stale/missing certificate를 수거한다.
|
||||
- project 변경은 full `hub`, branch 변경은 `local + typed graph direct impact`로 `wiki-semantic-coherence-auditor`를 실행한다. direct impact는 imported owner/consumer, 직접 dependency, delegation 상대이며 sibling 전체는 포함하지 않는다.
|
||||
- `semantic_surface_extractor.py` → assertion → `semantic_candidate_builder.py` → verdict → proof → `semantic_audit.py validate` 순서를 지키고, `typed findings`, `edge-semantic findings`, `local-semantic findings`, `hub-semantic findings`를 서로 섞지 않고 집계한다.
|
||||
- hub `AMBIGUOUS_AUTHORITY`, 모든 `CONTRADICTION`, `RESTATEMENT_DRIFT`, hub dropped candidate는 fix 전까지 blocking이다.
|
||||
|
||||
6. **fix-plan 표** — `/lint --fix-plan` 과 동일 규율 (위험도·승인 필요·패치 범위):
|
||||
|
||||
| Finding | 필요한 수정 | 대상 파일:line | 위험 | 승인 필요? | 패치 범위 |
|
||||
|---|---|---|---|---|---|
|
||||
| `<실패 모드 + 한 줄>` | `<무엇을 어떻게 바꾸는가>` | `path:line` | low / med / high | yes / no | `<몇 줄 / 어느 섹션>` |
|
||||
|
||||
- **owner-우선 해소 원칙** (`rules/consistency-contract.md` §충돌 해소): 위임한 쪽(참조자)이 요약을 갱신한다. owner 본문을 참조자에 맞춰 고치지 않는다.
|
||||
- `RESTATED_FOREIGN_DECISION` → **"참조 + 1줄 요약으로 교체" 제안** (세부 내용은 owner 로 이관 또는 삭제를 명시).
|
||||
- **hub(project-note) vs branch 충돌은 항상 개별 승인** — 자동 적용 금지. 보통 branch 가 더 최신·구체 → "project-note 갱신 제안" 형태가 기본이나, 판정은 사용자 몫.
|
||||
- `BARE_DECISION_REF` / `BARE_OWNER_REF` 수정(wikilink 화)은 low 위험 — 묶음 승인 제안 가능.
|
||||
|
||||
7. **승인된 항목만 Edit**
|
||||
|
||||
- 재진술 수거 시 **기존 본문 의미 보존** — 세부 내용을 owner 로 이관했는지, 중복이라 삭제했는지 fix-plan 에 명시한 대로만.
|
||||
- high 위험(본문 의미 변경·hub 갱신)은 절대 묶음 적용 금지 — 개별 승인.
|
||||
- 적용 중 owner D-row 를 건드리면 PostToolUse 훅(`wiki_consistency_check.py --post`)이 역참조 충격을 비차단 알림 — 같은 세션에서 반영.
|
||||
|
||||
8. **재검사 + 로그 + 요약**
|
||||
|
||||
- 적용 후 `python3 .claude/hooks/wiki_consistency_check.py --all` 재실행. **루프 천장 2회** — 2회 후 잔여 findings 는 보고 후 종료 (다음 `/sync` 로 이월).
|
||||
- `wiki/log.md` 한 줄: `YYYY-MM-DD HH:mm /sync — <대상> → findings n (CRITICAL c / WARN w), 적용 a / 보류 b`
|
||||
- 최종 요약 funnel:
|
||||
|
||||
```wiki-stats
|
||||
agent: sync
|
||||
found: <검출 findings 수>
|
||||
processed: <적용 + 보류 수>
|
||||
dropped: <제외 수 + 사유>
|
||||
```
|
||||
|
||||
## 규칙
|
||||
|
||||
- **무단 자동 수정 금지.** fix-plan 의 *승인된 항목만* 적용하며 사용자 확인 없이 본문을 바꾸지 않는다.
|
||||
- `/lint` 와의 경계: 단일 문서 품질(과장/stale/canonical 우회)은 `/lint`, **cross-doc 모순·위임 동기화는 `/sync`** — 서로 중복 검사하지 않는다.
|
||||
- 검사기가 침묵하는 귀속 모호 케이스(인용자 자신의 DEM 에 있는 D-id)는 Layer 2 의미 대조가 판정한다 — 결정론 출력만으로 "깨끗하다" 단정 금지.
|
||||
|
||||
## Proof Artifact Contract (HARD)
|
||||
|
||||
finding/인용 draft는 exact UTF-8 quote 전부를 포함한 `proof-request/v1` JSON으로 조립한다. controller는 `python3 harness/runtime/proof_runner.py <proof-request.json> --repo-root . --output <report-dir>/proof-manifest.json`을 실행한다. exit 0, `schema_version: proof-runner-result/v1`, `status: PASS`, manifest `schema_version: proof-manifest/v1` 확인 전에는 workflow 완료를 선언하지 않는다.
|
||||
|
||||
보고서에는 `manifest_path`, `manifest_sha256`, `proof_count`, `pass_count`, `fail_count`를 기록한다. 실패 proof와 라인 정정은 전부, PASS proof는 대표 1~3개만 펼치고 나머지는 manifest를 참조한다. `fail_count != 0` 또는 count 불일치면 완료 판정을 차단한다.
|
||||
@@ -0,0 +1,36 @@
|
||||
기존 wiki 문서의 **메타데이터를 보정**합니다. 신규 변환은 `/ingest`를 사용하세요.
|
||||
|
||||
**대상:** {{arguments}} (지정 안 하면 `wiki/` 전체)
|
||||
|
||||
## 작업 절차
|
||||
|
||||
1. **대상 문서 수집**
|
||||
- 인자가 경로면 해당 문서들
|
||||
- 인자가 없으면 `wiki/` 전체 스캔
|
||||
|
||||
2. **frontmatter 검사 및 보정**
|
||||
- `title` 누락 → 본문 H1에서 추출
|
||||
- `source_type` 누락 또는 잘못된 값 → 본문/Sources 기반으로 재분류
|
||||
- `status` 누락 → `draft`로 기본 설정
|
||||
- `confidence` 누락 → `unknown`
|
||||
- `tags` 빈 배열 → 본문 키워드와 도메인(backend, db, infra 등)에서 추출
|
||||
- `related_projects` 빈 배열 → 본문/링크에서 프로젝트명 추출
|
||||
- `last_reviewed` 누락 → 오늘 날짜로
|
||||
|
||||
3. **태그 정규화**
|
||||
- 동의어 통일 (예: `db` / `database` → `db`)
|
||||
- 너무 일반적인 태그(`기타`, `미분류` 등) 제거
|
||||
- 도메인 태그 우선 (backend, db, infra, network, auth, ...)
|
||||
|
||||
4. **링크 일관성 검사**
|
||||
- 상대경로 링크가 있으면 `[[wikilink]]`로 변환
|
||||
- 깨진 wikilink 보고
|
||||
|
||||
5. **로그 기록**
|
||||
- `wiki/log.md`에 한 줄: `YYYY-MM-DD HH:mm /tag — <대상> → 변경 요약`
|
||||
|
||||
## 규칙
|
||||
|
||||
- **본문 내용은 건드리지 않는다.** frontmatter와 링크 형식만 조정.
|
||||
- 자동 분류가 애매하면 `status: needs-confirmation`으로 두고 사람 검토 요청.
|
||||
- 대량 처리 시에는 dry-run 결과를 먼저 보여주고 사용자 확인 후 적용.
|
||||
Reference in New Issue
Block a user