init: readme 작성 하네스 설계

runs/company-haness/20260720-rewrite/readme-brief.yaml

@@ -0,0 +1,80 @@
+schema-version: 1
+project-profile:
+  primary: generic
+  secondary:
+    - agent-operations-harness
+    - workflow-contract-repository
+audiences:
+  primary:
+    - 저장소를 처음 사용하는 운영자와 개발자
+    - 하네스에 기여하려는 개발자
+  secondary:
+    - 에이전트 워크플로와 산출물 계약을 검토하는 기술 리더
+reader-outcomes:
+  - 이 저장소가 무엇을 운영하는 물건인지, 자신의 상황에 맞는지를 첫 화면에서 판단한다.
+  - Python·PyYAML 설치, workspace 지정, doctor 확인까지 최소 사용 절차를 끝낸다.
+  - 5개 workflow plan 가운데 작업 성격에 맞는 경로와 첫 명령을 고른다.
+  - 실행 결과·증거·상태가 어느 workspace 경로에 어떤 불변성으로 남는지 찾는다.
+  - 저장소가 제공하는 검증 명령과 그 검증 수준의 차이를 구분한다.
+  - 벤치마크가 아직 품질 우위를 입증하지 않았고 문서화된 검증 결과가 워킹 트리 기준이라는 근거 한계를 확인한다.
+project-story:
+  value-proposition: 역할 라우팅·단계 전이·산출물 계약·증거 등급을 파일로 고정하고 Claude Code 훅으로 강제해, 여러 에이전트가 나눠 수행한 긴 작업의 결정과 실행 증거를 재현 가능한 파일로 남긴다.
+  problem: 여러 에이전트가 긴 작업을 분담하면 역할 경계, 선행 산출물, 승인 주체, 실행 증거가 대화 로그 안에 흩어져 사후에 재현하거나 검증하기 어렵다.
+  target-reader: Claude Code에서 제품·개발·비즈니스 작업을 다역할 계약으로 운용하려는 운영자와 기여자
+  notable-traits:
+    - text: 5개 workflow plan과 18개 slash command가 workflow-contracts.yaml 한 그래프의 단계·산출물·exit gate로 묶여 있다.
+      fact-ids: [F-WORKFLOW-PLAN-INVENTORY, F-WORKFLOW-COMMAND-INVENTORY, F-WORKFLOW-CASCADE]
+    - text: 역할 75개를 28개 family로 라우팅하고, 생성기가 101개 agent card의 구성 계약을 검사한다. 카드는 생성물이라 수기 편집을 금지한다.
+      fact-ids: [F-ARCH-ROLE-MODEL, F-ARCH-AGENT-CARD-COMPOSITION]
+    - text: 상태·산출물 런타임은 caller가 제출한 gate fact를 신뢰하지 않고 불변 바이트에서 파생하며, 186개 artifact kind를 컴파일된 registry로 관리한다.
+      fact-ids: [F-ARCH-STATE-ARTIFACT, F-ARCH-ARTIFACT-REGISTRY]
+    - text: E4/E5 등급 주장은 evidence ledger의 실제 receipt와 대조되고 receipt가 없으면 차단되며, report는 발급 후 덮어쓸 수 없다.
+      fact-ids: [F-ARCH-EVIDENCE-GRADING, F-ARTIFACT-PROVENANCE]
+    - text: 도구 경계는 Claude Code 네이티브 permission이 1차이고 guard_tools regex는 스스로 우회 가능성을 선언한 2차 방어선이다.
+      fact-ids: [F-ARCH-HOOKS, F-LIMIT-GUARD-REGEX]
+    - text: design-direction이 cascade에 종속된 다섯 번째 first-class workflow로 존재하며 부모 결정과 입력 brief SHA-256으로 결속된다.
+      fact-ids: [F-WORKFLOW-DESIGN-DIRECTION, F-WORKFLOW-SPECIALIZED]
+    - text: 역할별 method skill 75개와 v2 계약 75개가 활성화 기록으로 관리되고 migration-debt가 0으로 집계된다.
+      fact-ids: [F-ARCH-METHOD-CONTRACT]
+    - text: P4 cascade 벤치마크는 계획·예산 게이트·공정성 통제까지 구현되고 테스트되어 있으나 8개 서브커맨드 중 6개가 stub이고 파일럿 실행 결과가 없다.
+      fact-ids: [F-LIMIT-P4-PILOT-UNRUN, F-VERIFY-CASCADE-CLI-EXECUTED, F-LIMIT-BENCHMARK-CONTROLS]
+  maturity: 계약·훅·테스트는 구현되어 워킹 트리에서 전체 스위트가 green이지만, 회사 컨텍스트는 provisional이고 하네스의 품질 우위를 뒷받침할 실증 결과는 아직 없는 상태
+  limitations:
+    - 문서화된 모든 검증 결과는 커밋된 HEAD가 아니라 현재 워킹 트리 기준이며 두 상태가 실제로 다르다.
+    - agent card가 추적본 72개와 워킹 트리 101개로 벌어져 있어 저장소를 clone한 상태와 검증된 상태가 일치하지 않는다.
+    - golden task 벤치마크는 13개 과제 중 저난도 bugfix 2개만 plain·harness 각 2표본으로 실행됐고 측정된 3개 지표가 모두 동률이라 하네스 우위를 입증하지 않는다.
+    - P4 cascade 벤치마크는 plan과 approve-budget만 배선돼 있고 나머지 6개 서브커맨드는 exit 3 stub이며 파일럿 실행 산출물이 저장소에 없다.
+    - company-context가 provisional이고 창업자 확인값 5개가 미해결이라 회사 관련 인용은 증거 등급 상한에 묶인다.
+    - org-os의 컨텍스트 폴더 5개가 README stub만 담고 있어 회사·제품 문맥 레이어가 비어 있다.
+    - 강제 훅은 Claude Code가 이 저장소의 settings.json을 로드한 세션에서만 동작하고 다른 실행 환경에서는 같은 강제를 보장하지 않는다.
+    - guard_tools의 regex denylist는 저장소 스스로 우회 가능하다고 선언한 2차 방어선이라 보안 경계로 신뢰할 수 없다.
+    - CLAUDE.md가 역할 수를 73으로 적고 있어 registry 정본 75와 어긋난다. 저장소 내부 문서도 완전히 동기화돼 있지 않다.
+    - workspace 포인터 파일이 현재 값으로 채워져 있어, 환경변수 미설정 상태가 로컬에서 더 이상 fail-closed로 이어지지 않는다.
+    - UI 검증은 render health만 판정하고 미학 품질은 판정하지 않으며 일부 경로는 Node·Chrome·D2·Marp 같은 외부 도구에 의존한다.
+    - 저장소 루트에 LICENSE 파일이 없어 사용·재배포 조건이 명시돼 있지 않다.
+narrative-variant: custom
+reader-journey:
+  - reader-question: 이 저장소는 무엇을 운영하는 물건이고 나에게 맞는가?
+    section-id: overview
+  - reader-question: 프롬프트 모음이 아니라고 말할 근거가 되는 운영 원리는 무엇인가?
+    section-id: operating-model
+  - reader-question: 내 환경에서 최소한으로 돌려보려면 무엇을 설치하고 무엇을 지정해야 하는가?
+    section-id: quick-start
+  - reader-question: 지금 하려는 작업에는 어떤 workflow를 골라야 하는가?
+    section-id: workflows
+  - reader-question: 규칙과 실행 코드는 어디에 나뉘어 있고 무엇을 고쳐야 하는가?
+    section-id: repo-map
+  - reader-question: 실행하면 결과와 증거가 어디에 어떤 형태로 남는가?
+    section-id: artifacts
+  - reader-question: 저장소가 정상인지 어떤 명령으로 확인하고 그 결과는 어디까지 믿을 수 있는가?
+    section-id: verification
+  - reader-question: 이 하네스가 실제로 더 나은 산출물을 낸다는 근거는 어디까지 있는가?
+    section-id: evidence-status
+  - reader-question: 도입 전에 받아들여야 할 현재 한계는 무엇인가?
+    section-id: limitations
+  - reader-question: 기여하려면 어디를 고치고 무엇을 재생성해야 하는가?
+    section-id: contributing
+  - reader-question: 계약 원본과 상세 설계를 직접 읽으려면 어디로 가야 하는가?
+    section-id: reference
+  - reader-question: 이 코드를 사용하거나 재배포해도 되는가?
+    section-id: license