llm-wiki/harness/source/skills/project-spec.md

/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 면 사용자가 할 행동을 한 줄씩(예: "① 아키텍처 .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 불일치면 완료 판정을 차단한다.