94 lines
13 KiB
Markdown
94 lines
13 KiB
Markdown
`/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 불일치면 완료 판정을 차단한다.
|