llm-wiki/.agents/workflows/branch-spec.md

description

description
빈 브랜치 노트를 source claim 기반으로 채우고(필요시 자동조사) 끝에 /depth로 검증

사용자가 /branch-spec <브랜치 이름> [추가 source URL ...] 를 입력하면 아래 절차를 수행한다.

/branch 로 만든 빈 브랜치 노트를 되묻지 않을 수준으로 채우는 오케스트레이터입니다. source claim 에서 결정 후보·대안 비교를 도출하고, 근거 없는 결정은 먼저 자동조사한 뒤 그래도 없으면 UNSUPPORTED_DECISION 으로 라벨링하고, 끝에 /depth 로 깊이를 검증합니다.

브랜치 이름: <브랜치 이름> [추가 source URL ...]

참조 (작업 시 정독)

• rules/subagent-input-contracts.md — 본 명령 + dispatch 할 agent 들의 입력 계약
• rules/branch-depth-gate.md — 끝에 적용할 깊이 판정 4축(R1~R4)
• rules/coverage-gate.md — 끝에 적용할 완전성 판정(빠진 관심사 3단계). depth 의 짝
• templates/branch-note-template.md — 채울 대상 구조(특히 ## Decision Evidence Map, ## 구현 가이드)
• 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.

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 수집

   • 노트의 ## 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 …)로 부여.

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. 노트 채움 (기존 표 포맷 유지)

   • ## Decision Evidence Map 표를 채운다: 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)은 삭제 금지 — 가장 관련된 템플릿 섹션 바로 옆에 슬롯한다(검증성 섹션 → ## Claims To Verify 앞, 결정 테이블 → ## Decision Evidence Map 앞, Sources 보강 → ## Sources 뒤).
   • 파일 편집은 직접 Edit 하거나 대규모(전면 재배치 포함)면 wiki-doc-author(mode=migrate)에 위임. 기존 사용자 작성 본문 verbatim 보존.

8. 자동 게이트 — 깊이 + 완전성 (맨 끝, 나란히)

   • (8a) /depth (깊이) — python3 .claude/hooks/wiki_structure_lint.py --file raw/branch-notes/<slug>.md (1차 구조) → 통과 시 branch-depth-auditor dispatch (2차 R1~R4). 판정 Ready(Blocking 0) / Not ready.
   • (8b) /coverage (완전성) — /coverage <slug> 흐름: 1차 python3 .claude/hooks/wiki_structure_lint.py --coverage-pre raw/branch-notes/<slug>.md (0 PASS / 1 FAIL / 3 EXEMPT) → PASS 시 coverage-auditor dispatch (governing 문서·선례 브랜치·ca-tmpl 코드 대조). 판정 Covered(missing 0) / Not-covered.
   • (8c) 루프백 — 천장 2회 (project-spec §9 와 동일 규율) — depth Not ready 또는 coverage Not-covered(🔴 missing) 이면 → §3~§7 로 되돌아가 빠진 관심사를 결정으로 채우거나 깊이를 보강 → 8a·8b 재실행. 루프는 최대 2회 — 2회 초과에도 미통과면 무한 재조사로 컨텍스트를 태우지 말고 Not ready/Not-covered 로 깨끗이 종료하고 잔여 finding 을 사용자에게 보고(다음 세션 재개).
   • 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 — 게이트/컨트롤러가 균형 검증): 요약 끝에 기계 파싱용 블록을 방출한다. found = processed + dropped 균형 필수:

     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 에만. 사용자가 쓴 결정·메모를 덮어쓰지 않는다.
• 템플릿 순서·중복은 린터가 안 잡는다 — 채움 후 ## 헤더 순서를 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 를 만들지 않는다 — 기존 서브에이전트(wiki-source-summarizer / wiki-decision-researcher / wiki-doc-author)만 dispatch.
• 검증은 /depth + /coverage 에 위임 — 본 명령은 채움에 집중. 깊이(/depth)·완전성(/coverage) 판정 로직을 중복 구현하지 않는다. 두 게이트가 모두 통과해야 완성.
• wiki/log.md 기록 안 함(브랜치 작업은 빈번, 로그 노이즈) — /branch·/depth 와 동일 정책.