init: readme 작성 하네스 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,46 @@
|
||||
schema-version: 1
|
||||
target:
|
||||
repository: /home/donghyeon/workspace/ai-tool/company-haness
|
||||
readme-path: README.md
|
||||
mode: refresh
|
||||
profile-override: generic
|
||||
project-intent:
|
||||
purpose: 대상 저장소의 핵심 운영 흐름, 구조, 검증 방법을 실제 파일 근거에 맞춰 설명한다.
|
||||
positioning: AI 에이전트 기반 회사 운영 하네스를 처음 접하는 사용자와 기여자를 위한 저장소 진입 문서다.
|
||||
maturity: 현재 저장소에서 확인되는 구현과 한계를 과장 없이 문서화한다.
|
||||
audience:
|
||||
primary:
|
||||
- 저장소를 처음 사용하는 운영자와 개발자
|
||||
- 하네스에 기여하려는 개발자
|
||||
secondary:
|
||||
- 에이전트 워크플로와 산출물 계약을 검토하는 기술 리더
|
||||
reader-actions:
|
||||
- 프로젝트의 목적과 적용 범위를 빠르게 파악한다.
|
||||
- 대표 진입점과 최소 사용 흐름을 선택한다.
|
||||
- 주요 디렉터리와 산출물 위치를 찾는다.
|
||||
- 저장소가 정의한 검증 명령과 현재 한계를 확인한다.
|
||||
content-policy:
|
||||
language: ko-KR
|
||||
tone: 간결하고 기술적이며 검증 수준을 명시하는 설명체
|
||||
target-length: long
|
||||
preserve-existing-copy: false
|
||||
detail-docs-policy: summary-and-link
|
||||
visual-policy:
|
||||
mode: when-useful
|
||||
max-visuals: 1
|
||||
preferred-formats:
|
||||
- mermaid
|
||||
placeholder-format: HTML 주석 기반 제작 사양
|
||||
must-include:
|
||||
- 프로젝트 개요와 대상 독자
|
||||
- 대표 워크플로 진입점과 선택 기준
|
||||
- 저장소 구조와 주요 책임
|
||||
- 최소 사용 절차
|
||||
- 검증 명령과 검증 수준
|
||||
- 산출물 위치
|
||||
- 현재 한계
|
||||
must-exclude:
|
||||
- 저장소 근거가 없는 기능·버전·성능 우위 주장
|
||||
- 비밀 값 또는 개인 환경의 절대 경로
|
||||
- 상세 설계 이력의 장문 복제
|
||||
protected-sections: []
|
||||
@@ -0,0 +1,28 @@
|
||||
{
|
||||
"build-files": [
|
||||
"hyeonworks/design-direction/hyeonworks-reset-v1-direction-v2/directions/direction-1/package.json",
|
||||
"hyeonworks/design-direction/hyeonworks-reset-v1-direction-v2/directions/direction-2/package.json",
|
||||
"hyeonworks/design-direction/hyeonworks-reset-v1-direction-v2/directions/direction-3/package.json",
|
||||
"hyeonworks/design-direction/hyeonworks-reset-v1-direction/gallery/package.json",
|
||||
"hyeonworks/design-direction/hyeonworks-reset-v1-direction/prototype/package.json",
|
||||
"hyeonworks/design-system/package.json"
|
||||
],
|
||||
"languages": [
|
||||
"JavaScript",
|
||||
"Python",
|
||||
"TypeScript"
|
||||
],
|
||||
"top-level-dirs": [
|
||||
".agents",
|
||||
".claude",
|
||||
".codex",
|
||||
".github",
|
||||
".superpowers",
|
||||
"_sandbox",
|
||||
"benchmark",
|
||||
"docs",
|
||||
"hyeonworks",
|
||||
"org-os"
|
||||
],
|
||||
"multi-module": true
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"git-sha": "00db337cfb3a22feb0b4d8529f23d72067f9ce16",
|
||||
"dirty": true,
|
||||
"diff-hash": "sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64",
|
||||
"scanned-at": null,
|
||||
"file-count": 893
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"run-id": "20260717-refresh",
|
||||
"repo-id": "company-haness",
|
||||
"mode": "refresh",
|
||||
"target-repository": "/home/donghyeon/workspace/ai-tool/company-haness",
|
||||
"harness-version": "0.1.0",
|
||||
"started-at": null,
|
||||
"tool-adapter": "codex",
|
||||
"input-hashes": {}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"mode": "refresh",
|
||||
"current": "REPOSITORY_SNAPSHOTTED",
|
||||
"history": [
|
||||
{
|
||||
"state": "INITIALIZED"
|
||||
},
|
||||
{
|
||||
"state": "INPUT_CAPTURED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "request",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "REPOSITORY_SNAPSHOTTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "snapshot",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"diff-hash": "sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"rework": {
|
||||
"iterations": 0,
|
||||
"findings": {}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,171 @@
|
||||
# Org OS 하네스 — Claude Code용 에이전트 운영체계
|
||||
|
||||
Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다. <!-- claim-id: C-IDENTITY -->
|
||||
|
||||
이 저장소의 핵심은 역할 프롬프트의 개수가 아니라 **누가 무엇을 만들고, 어떤 근거로 검토하며, 어느 조건에서 다음 단계로 갈 수 있는지**를 명시하는 데 있습니다. 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다. <!-- claim-id: C-VALUE -->
|
||||
|
||||
<!-- section-id: overview -->
|
||||
## 무엇을 제공하나요?
|
||||
|
||||
일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다. 짧은 작업은 light 경로로 줄이고, 회사 수립이나 디자인 방향처럼 별도 수명주기가 필요한 일은 전용 workflow로 분리합니다. <!-- claim-id: C-ENTRY-MODEL -->
|
||||
|
||||
이 하네스가 연결하는 범위는 다음과 같습니다.
|
||||
|
||||
- 역할과 family를 이용한 작업 라우팅
|
||||
- 단계별 입력·출력 artifact와 검토 권한
|
||||
- 상태 전이 전 exit gate와 사람 승인
|
||||
- subagent 실행, 도구 사용, 증거 기록, 종료 검증 hook
|
||||
- 프로젝트별 report·evidence·state 저장소
|
||||
|
||||
<!-- section-id: operating-model -->
|
||||
## 핵심 운영 모델
|
||||
|
||||
1. **계약이 실행보다 먼저입니다.** `workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다. <!-- claim-id: C-CONTRACT-MODEL -->
|
||||
2. **판단과 구현의 협업 방식이 다릅니다.** 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다. <!-- claim-id: C-COLLAB-MODEL -->
|
||||
3. **중요 결정은 자동 완주하지 않습니다.** 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다. <!-- claim-id: C-HUMAN-BOUNDARY -->
|
||||
4. **결과보다 provenance를 함께 남깁니다.** workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다. <!-- claim-id: C-PROVENANCE-MODEL -->
|
||||
|
||||
Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다. <!-- claim-id: C-HOOK-MODEL -->
|
||||
|
||||
<!-- section-id: quick-start -->
|
||||
## 시작하기
|
||||
|
||||
### 1. 필수 도구 확인
|
||||
|
||||
핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다. <!-- claim-id: C-PREREQUISITES -->
|
||||
|
||||
저장소 루트에서 의존성을 설치합니다.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
<!-- claim-id: C-INSTALL-COMMAND -->
|
||||
|
||||
### 2. 워크스페이스 지정
|
||||
|
||||
산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다. <!-- claim-id: C-WORKSPACE-RESOLUTION -->
|
||||
|
||||
저장소 자체를 점검할 때는 테스트용 `_sandbox`를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.
|
||||
|
||||
```bash
|
||||
export ORGOS_WORKSPACE=_sandbox
|
||||
python3 .claude/hooks/doctor.py
|
||||
```
|
||||
<!-- claim-id: C-DOCTOR-COMMAND -->
|
||||
|
||||
`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다. <!-- claim-id: C-DOCTOR-SCOPE -->
|
||||
|
||||
### 3. 첫 워크플로 시작
|
||||
|
||||
Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다. 이 단계가 `decision-brief`와 `workload-profile`을 만들고 다음 plan의 입구를 정합니다. `/doctor`, `/consult`, 독립 `/design-system`처럼 자체 목적이 있는 command는 예외입니다. <!-- claim-id: C-FIRST-COMMAND -->
|
||||
|
||||
<!-- section-id: workflows -->
|
||||
## 작업에 맞는 워크플로 선택
|
||||
|
||||
| 경로 | 적합한 작업 | 공식 흐름과 종단 |
|
||||
|---|---|---|
|
||||
| **cascade** | 근거 탐색, 방향 결정, 설계, 명세, 구현, 검증, release를 모두 거치는 작업 | `/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-CASCADE --> |
|
||||
| **wave** | 계획한 여러 작업을 wave로 실행하고 검증·수용하는 작업 | `/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-WAVE --> |
|
||||
| **light** | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `/ceo-intake` → `/run-wave` → `/review-output` → `acceptance` <!-- claim-id: C-WORKFLOW-LIGHT --> |
|
||||
| **venture-bootstrap** | company context가 아직 template인 새 회사·제품의 수립 | founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete` <!-- claim-id: C-WORKFLOW-VENTURE --> |
|
||||
|
||||
`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다. <!-- claim-id: C-SPECIALIZED-WORKFLOWS -->
|
||||
|
||||
다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다. <!-- claim-id: C-CASCADE-VISUAL -->
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["intake<br/>/ceo-intake"] --> B["discovery<br/>/ground"]
|
||||
B --> C["decide<br/>/decide"]
|
||||
C --> D{"사람 방향 수용"}
|
||||
D --> E["design<br/>/design"]
|
||||
E --> F["spec<br/>/spec"]
|
||||
F --> G["build<br/>/build"]
|
||||
G --> H["verification<br/>/review-output"]
|
||||
H --> I["acceptance<br/>/release-check"]
|
||||
I --> J{"사람 release 승인"}
|
||||
J --> K["released"]
|
||||
```
|
||||
|
||||
<!-- visual-id: cascade-flow -->
|
||||
|
||||
<!-- section-id: architecture -->
|
||||
## 저장소 구조와 책임
|
||||
|
||||
실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다. <!-- claim-id: C-ARCH-SOURCE -->
|
||||
|
||||
| 경로 | 책임 |
|
||||
|---|---|
|
||||
| `org-os/00-role-registry/` | 역할, capability family, lens, 권한과 라우팅 정책 |
|
||||
| `org-os/06-agent-work/` | workflow graph, artifact vocabulary, 협업·실행 정책 |
|
||||
| `.claude/commands/` | 사용자가 호출하는 slash command 정의 |
|
||||
| `.claude/agents/` | registry에서 생성되는 worker·lead·router·resolver 카드 |
|
||||
| `.claude/skills/` | concrete role별 작업 방법과 자기검증 절차 |
|
||||
| `.claude/hooks/` | 상태 엔진, 도구 경계, report·evidence 검증, 생성기와 렌더러 |
|
||||
| `.claude/schemas/` | workflow artifact와 report의 typed schema |
|
||||
| `.claude/tests/` | hook 강제기와 workflow 계약 테스트 |
|
||||
| `benchmark/` | golden task, 실행 ledger, plain 대 harness 비교 |
|
||||
| `docs/` | 설계·계획·감사 이력 |
|
||||
|
||||
<!-- claim-id: C-DIRECTORY-MAP -->
|
||||
|
||||
현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다. <!-- claim-id: C-ROLE-MODEL -->
|
||||
|
||||
기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오. <!-- claim-id: C-GENERATED-AGENTS -->
|
||||
|
||||
<!-- section-id: artifacts -->
|
||||
## 워크스페이스와 산출물
|
||||
|
||||
`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다. workspace 아래에는 실행 결과와 상태가 다음처럼 분리됩니다. <!-- claim-id: C-WORKSPACE-LAYOUT -->
|
||||
|
||||
```text
|
||||
<workspace>/
|
||||
├── completion-records/<workflow>/ # 불변 .report.yaml과 사람용 .md
|
||||
├── evidence/ # 실행·파일 receipt와 근거
|
||||
├── reports/ # INDEX와 사람이 읽는 집계 뷰
|
||||
├── state/ # workflow·artifact·acceptance event
|
||||
├── slack-inbox/ · slack-outbox/ # 승인 정책을 따르는 알림 큐
|
||||
└── design-system/ # 해당 프로젝트에 UI 산출물이 있을 때
|
||||
```
|
||||
|
||||
report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다. <!-- claim-id: C-REPORT-RECEIPTS -->
|
||||
|
||||
<!-- section-id: verification -->
|
||||
## 검증 방법과 증거 수준
|
||||
|
||||
다음 명령은 README 작성 과정에서 대상 스크립트와 경로를 **정적으로 확인**했습니다. 이 작업트리에서는 의존성 설치나 대상 테스트 suite를 실행하지 않았으므로, 정적 통과를 실제 실행 성공으로 해석하면 안 됩니다.
|
||||
|
||||
| 목적 | 명령 | 성공 신호와 현재 확인 수준 |
|
||||
|---|---|---|
|
||||
| hook·workspace preflight | `python3 .claude/hooks/doctor.py` | hard failure가 없고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-DOCTOR --> |
|
||||
| agent card 정합 | `python3 .claude/hooks/gen_agents.py --check` | 101개 카드 계약과 생성 내용 정합. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-AGENTS --> |
|
||||
| 전체 저장소 suite | `python3 .claude/tests/run_all.py` | preflight 뒤 모든 `test_*.py`가 green이고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-TESTS --> |
|
||||
| golden task 목록 | `python3 .claude/hooks/benchmark.py list` | 정의된 13개 task를 출력. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-BENCHMARK --> |
|
||||
|
||||
`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다. <!-- claim-id: C-TEST-RUNNER -->
|
||||
|
||||
GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다. <!-- claim-id: C-CI -->
|
||||
|
||||
벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다. <!-- claim-id: C-BENCHMARK-STATUS -->
|
||||
|
||||
<!-- section-id: limitations -->
|
||||
## 현재 상태와 한계
|
||||
|
||||
- `company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다. <!-- claim-id: C-LIMIT-CONTEXT -->
|
||||
- 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다. <!-- claim-id: C-LIMIT-HOOKS -->
|
||||
- UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다. <!-- claim-id: C-LIMIT-UI -->
|
||||
- Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다. <!-- claim-id: C-LIMIT-TOOLS -->
|
||||
- plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다. <!-- claim-id: C-LIMIT-EVIDENCE -->
|
||||
|
||||
<!-- section-id: reference -->
|
||||
## 정본 파일 지도
|
||||
|
||||
- Workflow와 artifact: [workflow-contracts.yaml](org-os/06-agent-work/workflow-contracts.yaml) · [artifact vocabulary](org-os/06-agent-work/artifact-type-vocabulary.yaml)
|
||||
- 역할과 라우팅: [roles.yaml](org-os/00-role-registry/roles.yaml) · [capability-families.yaml](org-os/00-role-registry/capability-families.yaml)
|
||||
- 권한과 실행: [tool-permission-matrix.yaml](org-os/00-role-registry/tool-permission-matrix.yaml) · [execution-policy.yaml](org-os/06-agent-work/execution-policy.yaml)
|
||||
- 런타임 요구사항: [tool-versions.yaml](.claude/tool-versions.yaml) · [requirements.txt](requirements.txt)
|
||||
- Claude Code 어댑터: [commands](.claude/commands/) · [hooks](.claude/hooks/) · [schemas](.claude/schemas/) · [tests](.claude/tests/)
|
||||
- 실증 자료: [golden tasks](benchmark/golden-tasks.yaml) · [benchmark report](benchmark/BENCHMARK.md)
|
||||
- 설계와 변경 이력: [docs](docs/)
|
||||
|
||||
README는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.
|
||||
@@ -0,0 +1,171 @@
|
||||
# Org OS 하네스 — Claude Code용 에이전트 운영체계
|
||||
|
||||
Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다. <!-- claim-id: C-IDENTITY -->
|
||||
|
||||
이 저장소의 핵심은 역할 프롬프트의 개수가 아니라 **누가 무엇을 만들고, 어떤 근거로 검토하며, 어느 조건에서 다음 단계로 갈 수 있는지**를 명시하는 데 있습니다. 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다. <!-- claim-id: C-VALUE -->
|
||||
|
||||
<!-- section-id: overview -->
|
||||
## 무엇을 제공하나요?
|
||||
|
||||
일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다. 짧은 작업은 light 경로로 줄이고, 회사 수립이나 디자인 방향처럼 별도 수명주기가 필요한 일은 전용 workflow로 분리합니다. <!-- claim-id: C-ENTRY-MODEL -->
|
||||
|
||||
이 하네스가 연결하는 범위는 다음과 같습니다.
|
||||
|
||||
- 역할과 family를 이용한 작업 라우팅
|
||||
- 단계별 입력·출력 artifact와 검토 권한
|
||||
- 상태 전이 전 exit gate와 사람 승인
|
||||
- subagent 실행, 도구 사용, 증거 기록, 종료 검증 hook
|
||||
- 프로젝트별 report·evidence·state 저장소
|
||||
|
||||
<!-- section-id: operating-model -->
|
||||
## 핵심 운영 모델
|
||||
|
||||
1. **계약이 실행보다 먼저입니다.** `workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다. <!-- claim-id: C-CONTRACT-MODEL -->
|
||||
2. **판단과 구현의 협업 방식이 다릅니다.** 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다. <!-- claim-id: C-COLLAB-MODEL -->
|
||||
3. **중요 결정은 자동 완주하지 않습니다.** 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다. <!-- claim-id: C-HUMAN-BOUNDARY -->
|
||||
4. **결과보다 provenance를 함께 남깁니다.** workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다. <!-- claim-id: C-PROVENANCE-MODEL -->
|
||||
|
||||
Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다. <!-- claim-id: C-HOOK-MODEL -->
|
||||
|
||||
<!-- section-id: quick-start -->
|
||||
## 시작하기
|
||||
|
||||
### 1. 필수 도구 확인
|
||||
|
||||
핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다. <!-- claim-id: C-PREREQUISITES -->
|
||||
|
||||
저장소 루트에서 의존성을 설치합니다.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
<!-- claim-id: C-INSTALL-COMMAND -->
|
||||
|
||||
### 2. 워크스페이스 지정
|
||||
|
||||
산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다. <!-- claim-id: C-WORKSPACE-RESOLUTION -->
|
||||
|
||||
저장소 자체를 점검할 때는 테스트용 `_sandbox`를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.
|
||||
|
||||
```bash
|
||||
export ORGOS_WORKSPACE=_sandbox
|
||||
python3 .claude/hooks/doctor.py
|
||||
```
|
||||
<!-- claim-id: C-DOCTOR-COMMAND -->
|
||||
|
||||
`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다. <!-- claim-id: C-DOCTOR-SCOPE -->
|
||||
|
||||
### 3. 첫 워크플로 시작
|
||||
|
||||
Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다. 이 단계가 `decision-brief`와 `workload-profile`을 만들고 다음 plan의 입구를 정합니다. `/doctor`, `/consult`, 독립 `/design-system`처럼 자체 목적이 있는 command는 예외입니다. <!-- claim-id: C-FIRST-COMMAND -->
|
||||
|
||||
<!-- section-id: workflows -->
|
||||
## 작업에 맞는 워크플로 선택
|
||||
|
||||
| 경로 | 적합한 작업 | 공식 흐름과 종단 |
|
||||
|---|---|---|
|
||||
| **cascade** | 근거 탐색, 방향 결정, 설계, 명세, 구현, 검증, release를 모두 거치는 작업 | `/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-CASCADE --> |
|
||||
| **wave** | 계획한 여러 작업을 wave로 실행하고 검증·수용하는 작업 | `/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-WAVE --> |
|
||||
| **light** | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `/ceo-intake` → `/run-wave` → `/review-output` → `acceptance` <!-- claim-id: C-WORKFLOW-LIGHT --> |
|
||||
| **venture-bootstrap** | company context가 아직 template인 새 회사·제품의 수립 | founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete` <!-- claim-id: C-WORKFLOW-VENTURE --> |
|
||||
|
||||
`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다. <!-- claim-id: C-SPECIALIZED-WORKFLOWS -->
|
||||
|
||||
다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다. <!-- claim-id: C-CASCADE-VISUAL -->
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["intake<br/>/ceo-intake"] --> B["discovery<br/>/ground"]
|
||||
B --> C["decide<br/>/decide"]
|
||||
C --> D{"사람 방향 수용"}
|
||||
D --> E["design<br/>/design"]
|
||||
E --> F["spec<br/>/spec"]
|
||||
F --> G["build<br/>/build"]
|
||||
G --> H["verification<br/>/review-output"]
|
||||
H --> I["acceptance<br/>/release-check"]
|
||||
I --> J{"사람 release 승인"}
|
||||
J --> K["released"]
|
||||
```
|
||||
|
||||
<!-- visual-id: cascade-flow -->
|
||||
|
||||
<!-- section-id: architecture -->
|
||||
## 저장소 구조와 책임
|
||||
|
||||
실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다. <!-- claim-id: C-ARCH-SOURCE -->
|
||||
|
||||
| 경로 | 책임 |
|
||||
|---|---|
|
||||
| `org-os/00-role-registry/` | 역할, capability family, lens, 권한과 라우팅 정책 |
|
||||
| `org-os/06-agent-work/` | workflow graph, artifact vocabulary, 협업·실행 정책 |
|
||||
| `.claude/commands/` | 사용자가 호출하는 slash command 정의 |
|
||||
| `.claude/agents/` | registry에서 생성되는 worker·lead·router·resolver 카드 |
|
||||
| `.claude/skills/` | concrete role별 작업 방법과 자기검증 절차 |
|
||||
| `.claude/hooks/` | 상태 엔진, 도구 경계, report·evidence 검증, 생성기와 렌더러 |
|
||||
| `.claude/schemas/` | workflow artifact와 report의 typed schema |
|
||||
| `.claude/tests/` | hook 강제기와 workflow 계약 테스트 |
|
||||
| `benchmark/` | golden task, 실행 ledger, plain 대 harness 비교 |
|
||||
| `docs/` | 설계·계획·감사 이력 |
|
||||
|
||||
<!-- claim-id: C-DIRECTORY-MAP -->
|
||||
|
||||
현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다. <!-- claim-id: C-ROLE-MODEL -->
|
||||
|
||||
기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오. <!-- claim-id: C-GENERATED-AGENTS -->
|
||||
|
||||
<!-- section-id: artifacts -->
|
||||
## 워크스페이스와 산출물
|
||||
|
||||
`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다. workspace 아래에는 실행 결과와 상태가 다음처럼 분리됩니다. <!-- claim-id: C-WORKSPACE-LAYOUT -->
|
||||
|
||||
```text
|
||||
<workspace>/
|
||||
├── completion-records/<workflow>/ # 불변 .report.yaml과 사람용 .md
|
||||
├── evidence/ # 실행·파일 receipt와 근거
|
||||
├── reports/ # INDEX와 사람이 읽는 집계 뷰
|
||||
├── state/ # workflow·artifact·acceptance event
|
||||
├── slack-inbox/ · slack-outbox/ # 승인 정책을 따르는 알림 큐
|
||||
└── design-system/ # 해당 프로젝트에 UI 산출물이 있을 때
|
||||
```
|
||||
|
||||
report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다. <!-- claim-id: C-REPORT-RECEIPTS -->
|
||||
|
||||
<!-- section-id: verification -->
|
||||
## 검증 방법과 증거 수준
|
||||
|
||||
다음 명령은 README 작성 과정에서 대상 스크립트와 경로를 **정적으로 확인**했습니다. 이 작업트리에서는 의존성 설치나 대상 테스트 suite를 실행하지 않았으므로, 정적 통과를 실제 실행 성공으로 해석하면 안 됩니다.
|
||||
|
||||
| 목적 | 명령 | 성공 신호와 현재 확인 수준 |
|
||||
|---|---|---|
|
||||
| hook·workspace preflight | `python3 .claude/hooks/doctor.py` | hard failure가 없고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-DOCTOR --> |
|
||||
| agent card 정합 | `python3 .claude/hooks/gen_agents.py --check` | 101개 카드 계약과 생성 내용 정합. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-AGENTS --> |
|
||||
| 전체 저장소 suite | `python3 .claude/tests/run_all.py` | preflight 뒤 모든 `test_*.py`가 green이고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-TESTS --> |
|
||||
| golden task 목록 | `python3 .claude/hooks/benchmark.py list` | 정의된 13개 task를 출력. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-BENCHMARK --> |
|
||||
|
||||
`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다. <!-- claim-id: C-TEST-RUNNER -->
|
||||
|
||||
GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다. <!-- claim-id: C-CI -->
|
||||
|
||||
벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다. <!-- claim-id: C-BENCHMARK-STATUS -->
|
||||
|
||||
<!-- section-id: limitations -->
|
||||
## 현재 상태와 한계
|
||||
|
||||
- `company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다. <!-- claim-id: C-LIMIT-CONTEXT -->
|
||||
- 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다. <!-- claim-id: C-LIMIT-HOOKS -->
|
||||
- UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다. <!-- claim-id: C-LIMIT-UI -->
|
||||
- Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다. <!-- claim-id: C-LIMIT-TOOLS -->
|
||||
- plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다. <!-- claim-id: C-LIMIT-EVIDENCE -->
|
||||
|
||||
<!-- section-id: reference -->
|
||||
## 정본 파일 지도
|
||||
|
||||
- Workflow와 artifact: [workflow-contracts.yaml](org-os/06-agent-work/workflow-contracts.yaml) · [artifact vocabulary](org-os/06-agent-work/artifact-type-vocabulary.yaml)
|
||||
- 역할과 라우팅: [roles.yaml](org-os/00-role-registry/roles.yaml) · [capability-families.yaml](org-os/00-role-registry/capability-families.yaml)
|
||||
- 권한과 실행: [tool-permission-matrix.yaml](org-os/00-role-registry/tool-permission-matrix.yaml) · [execution-policy.yaml](org-os/06-agent-work/execution-policy.yaml)
|
||||
- 런타임 요구사항: [tool-versions.yaml](.claude/tool-versions.yaml) · [requirements.txt](requirements.txt)
|
||||
- Claude Code 어댑터: [commands](.claude/commands/) · [hooks](.claude/hooks/) · [schemas](.claude/schemas/) · [tests](.claude/tests/)
|
||||
- 실증 자료: [golden tasks](benchmark/golden-tasks.yaml) · [benchmark report](benchmark/BENCHMARK.md)
|
||||
- 설계와 변경 이력: [docs](docs/)
|
||||
|
||||
README는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.
|
||||
@@ -0,0 +1,271 @@
|
||||
--- README.md (current)
|
||||
+++ README.md (candidate)
|
||||
@@ -1,120 +1,171 @@
|
||||
-# Org OS 하네스 — 실행 안내
|
||||
+# Org OS 하네스 — Claude Code용 에이전트 운영체계
|
||||
|
||||
-회사를 AI 에이전트로 운영하는 파일 기반 운영체계. 개발 + 비즈니스(수익)를 함께 다룬다.
|
||||
-규칙·구조는 [CLAUDE.md](CLAUDE.md), 상태/기록 구분은 [org-os/06-agent-work/README.md](org-os/06-agent-work/README.md).
|
||||
+Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다. <!-- claim-id: C-IDENTITY -->
|
||||
|
||||
-## 🚀 어떤 커맨드부터? — 항상 `/ceo-intake`
|
||||
+이 저장소의 핵심은 역할 프롬프트의 개수가 아니라 **누가 무엇을 만들고, 어떤 근거로 검토하며, 어느 조건에서 다음 단계로 갈 수 있는지**를 명시하는 데 있습니다. 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다. <!-- claim-id: C-VALUE -->
|
||||
|
||||
-**새 워크플로**는 **`/ceo-intake`**로 시작한다 — 사용자 요청을 Decision Brief(mode·tier·후보 직무)로 정리한다. (모순 아님: **기존 wf-id**는 선행 gating 산출물이 있으면 중간 stage에서 재개 가능 — B. 참조. `state_engine`이 전이 선행조건을 검증한다.)
|
||||
-그다음은 **상황(tier·명확도)에 따라** 갈린다:
|
||||
+<!-- section-id: overview -->
|
||||
+## 무엇을 제공하나요?
|
||||
|
||||
-### 새 회사/제품을 처음 세울 때(venture-bootstrap)
|
||||
+일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다. 짧은 작업은 light 경로로 줄이고, 회사 수립이나 디자인 방향처럼 별도 수명주기가 필요한 일은 전용 workflow로 분리합니다. <!-- claim-id: C-ENTRY-MODEL -->
|
||||
|
||||
-company-context가 아직 `template`이면 제품 cascade 전에 회사부터 세운다:
|
||||
+이 하네스가 연결하는 범위는 다음과 같습니다.
|
||||
|
||||
-1. `org-os/01-company/founder-context.yaml`을 채운다(status: filled).
|
||||
-2. `/ceo-intake --plan venture-bootstrap` → `/venture-validate`(기회탐색+9-gate 검증) → `/company-bootstrap`(C-Level 수렴 + 사람 승인 + company-context 원자 commit).
|
||||
-3. 완료되면 공식 company-context.status = `provisional`. 이제 `/ground`부터 제품 cascade를 탄다.
|
||||
+- 역할과 family를 이용한 작업 라우팅
|
||||
+- 단계별 입력·출력 artifact와 검토 권한
|
||||
+- 상태 전이 전 exit gate와 사람 승인
|
||||
+- subagent 실행, 도구 사용, 증거 기록, 종료 검증 hook
|
||||
+- 프로젝트별 report·evidence·state 저장소
|
||||
|
||||
-기존 회사(status ∈ {provisional, operating})면 곧장 `/ceo-intake` → `/ground`.
|
||||
+<!-- section-id: operating-model -->
|
||||
+## 핵심 운영 모델
|
||||
|
||||
-### A. 새 전략 결정 (신규 제품·수익·방향, 아이디어 불명확) — 전체 cascade
|
||||
+1. **계약이 실행보다 먼저입니다.** `workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다. <!-- claim-id: C-CONTRACT-MODEL -->
|
||||
+2. **판단과 구현의 협업 방식이 다릅니다.** 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다. <!-- claim-id: C-COLLAB-MODEL -->
|
||||
+3. **중요 결정은 자동 완주하지 않습니다.** 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다. <!-- claim-id: C-HUMAN-BOUNDARY -->
|
||||
+4. **결과보다 provenance를 함께 남깁니다.** workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다. <!-- claim-id: C-PROVENANCE-MODEL -->
|
||||
+
|
||||
+Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다. <!-- claim-id: C-HOOK-MODEL -->
|
||||
+
|
||||
+<!-- section-id: quick-start -->
|
||||
+## 시작하기
|
||||
+
|
||||
+### 1. 필수 도구 확인
|
||||
+
|
||||
+핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다. <!-- claim-id: C-PREREQUISITES -->
|
||||
+
|
||||
+저장소 루트에서 의존성을 설치합니다.
|
||||
+
|
||||
+```bash
|
||||
+pip install -r requirements.txt
|
||||
```
|
||||
-/ceo-intake 의도 → Decision Brief(tier=heavy, divergent→converge)
|
||||
- ↓
|
||||
-/ground discovery: 시장·사용자·경쟁·재무 근거 접지 + option-set(≥2) 발산 (결정 전, anchoring 방지)
|
||||
- ↓
|
||||
-/decide converge: C-Level(CPO·CFO·CTO·COO)이 근거·옵션을 하나로 수렴 → CEO ExecutiveDecisionPacket
|
||||
- ↓ ← 사용자(HUMAN-001) 승인 게이트 (go/no-go)
|
||||
-/design 아키텍트·데이터·디자인·보안 설계 fan-out → 큰 설계문서
|
||||
- ↓ (UI-bearing이면 design-system 서브파이프라인 포함 → 실제 preview_ui 렌더 게이트가 프론트 BUILD 선행조건)
|
||||
-/spec PM·아키텍트 → 기능명세(PRD·api-contract·수용기준)
|
||||
- ↓
|
||||
-/build 구현 family(collapse) + QA/보안 감사 → completion-record
|
||||
- ↓
|
||||
-/review-output Parent 수용 검토(Accepted/Changes-Requested/Blocked)
|
||||
- ↓
|
||||
-/release-check Release Acceptance(DRAI + 인간 게이트)
|
||||
+<!-- claim-id: C-INSTALL-COMMAND -->
|
||||
+
|
||||
+### 2. 워크스페이스 지정
|
||||
+
|
||||
+산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다. <!-- claim-id: C-WORKSPACE-RESOLUTION -->
|
||||
+
|
||||
+저장소 자체를 점검할 때는 테스트용 `_sandbox`를 명시할 수 있습니다. 실제 작업에서는 별도의 프로젝트 디렉터리를 지정하십시오.
|
||||
+
|
||||
+```bash
|
||||
+export ORGOS_WORKSPACE=_sandbox
|
||||
+python3 .claude/hooks/doctor.py
|
||||
+```
|
||||
+<!-- claim-id: C-DOCTOR-COMMAND -->
|
||||
+
|
||||
+`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다. <!-- claim-id: C-DOCTOR-SCOPE -->
|
||||
+
|
||||
+### 3. 첫 워크플로 시작
|
||||
+
|
||||
+Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다. 이 단계가 `decision-brief`와 `workload-profile`을 만들고 다음 plan의 입구를 정합니다. `/doctor`, `/consult`, 독립 `/design-system`처럼 자체 목적이 있는 command는 예외입니다. <!-- claim-id: C-FIRST-COMMAND -->
|
||||
+
|
||||
+<!-- section-id: workflows -->
|
||||
+## 작업에 맞는 워크플로 선택
|
||||
+
|
||||
+| 경로 | 적합한 작업 | 공식 흐름과 종단 |
|
||||
+|---|---|---|
|
||||
+| **cascade** | 근거 탐색, 방향 결정, 설계, 명세, 구현, 검증, release를 모두 거치는 작업 | `/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-CASCADE --> |
|
||||
+| **wave** | 계획한 여러 작업을 wave로 실행하고 검증·수용하는 작업 | `/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released` <!-- claim-id: C-WORKFLOW-WAVE --> |
|
||||
+| **light** | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `/ceo-intake` → `/run-wave` → `/review-output` → `acceptance` <!-- claim-id: C-WORKFLOW-LIGHT --> |
|
||||
+| **venture-bootstrap** | company context가 아직 template인 새 회사·제품의 수립 | founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete` <!-- claim-id: C-WORKFLOW-VENTURE --> |
|
||||
+
|
||||
+`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다. <!-- claim-id: C-SPECIALIZED-WORKFLOWS -->
|
||||
+
|
||||
+다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다. <!-- claim-id: C-CASCADE-VISUAL -->
|
||||
+
|
||||
+```mermaid
|
||||
+flowchart LR
|
||||
+ A["intake<br/>/ceo-intake"] --> B["discovery<br/>/ground"]
|
||||
+ B --> C["decide<br/>/decide"]
|
||||
+ C --> D{"사람 방향 수용"}
|
||||
+ D --> E["design<br/>/design"]
|
||||
+ E --> F["spec<br/>/spec"]
|
||||
+ F --> G["build<br/>/build"]
|
||||
+ G --> H["verification<br/>/review-output"]
|
||||
+ H --> I["acceptance<br/>/release-check"]
|
||||
+ I --> J{"사람 release 승인"}
|
||||
+ J --> K["released"]
|
||||
```
|
||||
|
||||
-> **한 번에 걷고 싶으면 — `/run-cascade`** (상위 오케스트레이터). 위 A를 개별 커맨드로 일일이 부르는 대신, `/run-cascade`가 `state_engine`을 재사용해 현재 stage를 확인 → 필요한 stage만 실행 → 산출물 검증 → **사람 결정 지점(DECIDE go/no-go·RELEASE 수용)에서 정지**한다. 사용자는 처음에 문제·목표만 주고 중요한 결정에서만 개입한다. 자동 승인·자동 완주는 하지 않으며(사람 게이트가 존재 이유), 각 stage의 강제(spawn 게이트·validator·전이)는 그대로 작동한다. 사람이 승인하면 `/run-cascade --workflow <wf>`로 재개.
|
||||
+<!-- visual-id: cascade-flow -->
|
||||
|
||||
-### B. 방향이 이미 명확하면 — **중간부터 시작**
|
||||
-- 결정은 섰고 설계부터 → `/design` → `/spec` → `/build`
|
||||
-- 설계도 섰고 명세부터 → `/spec` → `/build`
|
||||
-- 명세·디자인도 있고 바로 개발 → `/build`
|
||||
+<!-- section-id: architecture -->
|
||||
+## 저장소 구조와 책임
|
||||
|
||||
-### C. 단순·저위험 작업 — 경량 경로 (cascade 생략)
|
||||
-```
|
||||
-/ceo-intake (tier=light) → /run-wave (family collapse 실행) → /review-output
|
||||
+실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다. <!-- claim-id: C-ARCH-SOURCE -->
|
||||
+
|
||||
+| 경로 | 책임 |
|
||||
+|---|---|
|
||||
+| `org-os/00-role-registry/` | 역할, capability family, lens, 권한과 라우팅 정책 |
|
||||
+| `org-os/06-agent-work/` | workflow graph, artifact vocabulary, 협업·실행 정책 |
|
||||
+| `.claude/commands/` | 사용자가 호출하는 slash command 정의 |
|
||||
+| `.claude/agents/` | registry에서 생성되는 worker·lead·router·resolver 카드 |
|
||||
+| `.claude/skills/` | concrete role별 작업 방법과 자기검증 절차 |
|
||||
+| `.claude/hooks/` | 상태 엔진, 도구 경계, report·evidence 검증, 생성기와 렌더러 |
|
||||
+| `.claude/schemas/` | workflow artifact와 report의 typed schema |
|
||||
+| `.claude/tests/` | hook 강제기와 workflow 계약 테스트 |
|
||||
+| `benchmark/` | golden task, 실행 ledger, plain 대 harness 비교 |
|
||||
+| `docs/` | 설계·계획·감사 이력 |
|
||||
+
|
||||
+<!-- claim-id: C-DIRECTORY-MAP -->
|
||||
+
|
||||
+현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다. <!-- claim-id: C-ROLE-MODEL -->
|
||||
+
|
||||
+기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오. <!-- claim-id: C-GENERATED-AGENTS -->
|
||||
+
|
||||
+<!-- section-id: artifacts -->
|
||||
+## 워크스페이스와 산출물
|
||||
+
|
||||
+`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다. workspace 아래에는 실행 결과와 상태가 다음처럼 분리됩니다. <!-- claim-id: C-WORKSPACE-LAYOUT -->
|
||||
+
|
||||
+```text
|
||||
+<workspace>/
|
||||
+├── completion-records/<workflow>/ # 불변 .report.yaml과 사람용 .md
|
||||
+├── evidence/ # 실행·파일 receipt와 근거
|
||||
+├── reports/ # INDEX와 사람이 읽는 집계 뷰
|
||||
+├── state/ # workflow·artifact·acceptance event
|
||||
+├── slack-inbox/ · slack-outbox/ # 승인 정책을 따르는 알림 큐
|
||||
+└── design-system/ # 해당 프로젝트에 UI 산출물이 있을 때
|
||||
```
|
||||
|
||||
-### D. 외부·독립 컨설팅 문서·덱이 필요하면 — `/consult`
|
||||
-```
|
||||
-/consult 주제 · 자료=<문서> · 대상=<repo>
|
||||
- → 엔게이지먼트 유형으로 family 선택:
|
||||
- • 비즈니스 자문 → FAM-CONSULTING (EM + 전략/운영/조직·변화/디지털/재무·리스크)
|
||||
- • 문서·콘텐츠 설계 → FAM-DOC-CONSULT (DOC-LEAD + 라이터/정보아키텍트/비주얼/개발자교육)
|
||||
- → 진단→권고 storyline → 문서(.md) + 덱(.pptx/.pdf/.html, 시그니처 도해 SVG)
|
||||
-```
|
||||
-컨설팅은 LENS-ADVISORY(외부·제3자 관점) — 사내 결정(`/decide`)·전략분석(`FAM-STRATEGY`)과 별개의 독립 자문 산출물. 제안까지(최종 결정은 사람).
|
||||
+report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다. <!-- claim-id: C-REPORT-RECEIPTS -->
|
||||
|
||||
-### E. 실제 UI·디자인 시스템을 코드로 만들고 보고 싶으면 — `/design-system`
|
||||
-```
|
||||
-/design-system 주제 · dir=<프로젝트>/design-system
|
||||
- ① design-brief(제약층: brief→references→tokens→decisions→donts, skill=design-craft)
|
||||
- ② DES-PLATFORM → tokens.css(CSS변수 SoT) + components/*.jsx (var(--*)만 소비)
|
||||
- ③ ENG-FE → screens/*.jsx (컴포넌트 조립만) + preview.jsx
|
||||
- ④ preview_ui.py → 패키지매니저 자동감지(pnpm/yarn/npm)→build→headless chrome 렌더검증+반응형 스크린샷+정적 CSS 품질(대비·포커스)
|
||||
- ⑤ 스크린샷 육안검증 → 고치고 preview 재실행(무제한 반복 루프). 스크린샷 존재 ≠ 품질(빈 #root·대비 실패면 게이트 실패)
|
||||
-```
|
||||
-Figma 없이 **코드로** 실제 UI를 만들고 headless chrome으로 확인한다(무료 Figma의 read rate-limit 회피). 산출: `<프로젝트>/design-system/`(tokens·components·screens·preview.png).
|
||||
+<!-- section-id: verification -->
|
||||
+## 검증 방법과 증거 수준
|
||||
|
||||
-> **`/design` ⊃ `/design-system`(UI-bearing이면 통합)** — `/design`은 cascade의 **설계 판단** 단계(아키텍트·데이터·디자인·보안이 *무엇을 만들지* fan-out으로 결정). 이 워크플로가 **사용자 대면 UI를 만들면**(BUILD에 `FAM-ENG-FRONTEND` 포함) `/design`의 fam-design 분기가 **`/design-system` 서브파이프라인을 그대로 돈다** — 산출 `design-type: design-system`은 **실제 `preview_ui` 렌더 게이트(receipt)를 통과해야** 프론트 BUILD가 열린다(`state_engine`이 강제; 산문만으론 안 됨). non-UI 워크플로(백엔드·인프라·의사결정)는 design-system을 요구하지 않는다. `/design-system`은 **독립 실행**(디자인만 반복)도 가능. 디자인·비주얼 직무는 *프레임워크 서술*이 아니라 **제약층(design-brief) + skill**(`design-craft`·`diagram-craft`)로 일한다 — 다이어그램은 **D2 우선**(Mermaid는 폴백).
|
||||
+다음 명령은 README 작성 과정에서 대상 스크립트와 경로를 **정적으로 확인**했습니다. 이 작업트리에서는 의존성 설치나 대상 테스트 suite를 실행하지 않았으므로, 정적 통과를 실제 실행 성공으로 해석하면 안 됩니다.
|
||||
|
||||
-## 커맨드 = 계층, 이전 산출물을 읽는다
|
||||
+| 목적 | 명령 | 성공 신호와 현재 확인 수준 |
|
||||
+|---|---|---|
|
||||
+| hook·workspace preflight | `python3 .claude/hooks/doctor.py` | hard failure가 없고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-DOCTOR --> |
|
||||
+| agent card 정합 | `python3 .claude/hooks/gen_agents.py --check` | 101개 카드 계약과 생성 내용 정합. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-AGENTS --> |
|
||||
+| 전체 저장소 suite | `python3 .claude/tests/run_all.py` | preflight 뒤 모든 `test_*.py`가 green이고 exit 0. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-TESTS --> |
|
||||
+| golden task 목록 | `python3 .claude/hooks/benchmark.py list` | 정의된 13개 task를 출력. 스크립트 실존을 정적 확인 <!-- claim-id: C-CMD-BENCHMARK --> |
|
||||
|
||||
-| 커맨드 | phase | 호출 계층 | 입력(must-read) | 산출/handoff |
|
||||
-|---|---|---|---|---|
|
||||
-| `/run-cascade` | **전 cascade 오케스트레이터** | Orchestrator(`state_engine`) | 아이디어/문제 또는 `--workflow <wf>` | GROUND→…→BUILD 순차 진행, **사람 게이트서 정지**(자동 완주 X) |
|
||||
-| `/ceo-intake` | intake | CEO | 사용자 요청 | Decision Brief → /ground 또는 /run-wave |
|
||||
-| `/ground` | GROUND/discovery | strategy·PM·UX·CI·pricing | Decision Brief | 근거+option-set(≥2) → /decide |
|
||||
-| `/decide` | DECIDE/converge | C-Level → CEO | discovery 근거+옵션 | ExecutiveDecisionPacket → /design (사람 go/no-go) |
|
||||
-| `/design` | DESIGN | 아키텍트·데이터·디자인·보안 | 승인 결정+verdict | 큰 설계문서(+UI면 design-system·preview 렌더 게이트) → /spec |
|
||||
-| `/spec` | DETAIL | PM·아키텍트 | 설계문서 | 기능명세 → /build |
|
||||
-| `/build` | BUILD | ENG(collapse)+QA | 설계+명세(+UI면 렌더된 design-system) | completion-record → /review-output |
|
||||
-| `/review-output` | review | Parent | completion-record | 수용/반려 |
|
||||
-| `/release-check` | release | DRAI+HUMAN | 수용 결과 | 릴리스 승인(인간 게이트) |
|
||||
-| `/consult` | CONSULT | FAM-CONSULTING(EM+5분과) | 주제+자료+대상repo | 컨설팅 문서(.md)+덱(.pptx/.pdf/.html) |
|
||||
-| `/design-system` | DESIGN-SYSTEM | DES-PLATFORM+ENG-FE | design-brief(제약) | 코드 디자인시스템(tokens·components·screens)+preview.png |
|
||||
+`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다. <!-- claim-id: C-TEST-RUNNER -->
|
||||
|
||||
-- **fan-out**(판단·설계·수익): 역할별 격리 subagent → 각자 보고서 → 상위가 원본 읽고 종합.
|
||||
-- **collapse**(코드·실행): family 1에이전트 단일 보고서(효율).
|
||||
-- 전 단계 공통: 불변보고서(`new_report.py`)·토큰게이트(`token_ledger.py`)·dissent게이트(`validate_report.py`)·태그(`report_tags.py`)·작업전 Slack(`slack_inbox.py`).
|
||||
+GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다. <!-- claim-id: C-CI -->
|
||||
|
||||
-## 결과는 어디에
|
||||
-산출물·상태는 **프로젝트별 root 폴더**로 나간다(`<project>/`, 현재 워크스페이스=`.orgos-workspace` 또는 env `ORGOS_WORKSPACE`, 미설정 시 중단 — 조용한 test 기본값 없음(WorkspaceNotSetError)). org-os는 SSOT(정의·계약)만 남긴다 — 훅은 [.claude/hooks/_workspace.py](.claude/hooks/_workspace.py)로 경로를 해석한다.
|
||||
-- **불변 보고서(SoT, 에이전트끼리)**: `<project>/completion-records/<workflow>/*.report.yaml`
|
||||
-- **대표용 MD**: 같은 이름 `.md` + 목차 `<project>/reports/INDEX.md` + 토큰 `<project>/reports/TOKENS.md`
|
||||
-- **디자인 시스템**: `<project>/design-system/`(tokens·components·screens·preview.png)
|
||||
-- **워크스페이스**: 산출물은 `ORGOS_WORKSPACE`가 가리키는 프로젝트 폴더로 나간다. 하네스 자기검증용 `_sandbox/`가 기본 데모 워크스페이스.
|
||||
-- **Slack 보고**: 부모=종합 결정 + 스레드 답글=역할별 개별 판정(`#clean-architecture-전체`)
|
||||
+벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다. <!-- claim-id: C-BENCHMARK-STATUS -->
|
||||
|
||||
-## 검증
|
||||
-```bash
|
||||
-ORGOS_WORKSPACE=<프로젝트> python3 .claude/hooks/doctor.py # 실행 무결성 preflight(설정·hook·의존성·workspace·참조). workspace 미설정이면 FAIL(P0-1 fail-closed 설계)
|
||||
-CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/tests/run_all.py # 전체(doctor+lint_refs+모든 test_*) — CI 진입점
|
||||
-CLAUDE_PROJECT_DIR="$PWD" python3 .claude/hooks/gen_agents.py --check # 101 에이전트 정합
|
||||
-```
|
||||
+<!-- section-id: limitations -->
|
||||
+## 현재 상태와 한계
|
||||
|
||||
-## 품질 검증 상태 (정직 — 과대주장 금지)
|
||||
-이 하네스는 **절차·신뢰경계는 강제되지만, "plain Claude보다 결과가 낫다"는 아직 증명되지 않았다.**
|
||||
-- **측정 인프라는 실재**: `benchmark.py run --execute`가 골든태스크를 plain vs 하네스로 실제 실행(nested claude CLI)하고 pytest·git diff로 객관 채점한다(위조 점수 없음).
|
||||
-- **지금까지 실증**: 단순 버그픽스(GT-01·GT-R2)는 **plain==harness**(둘 다 만점). 하네스가 과차단·과설계를 하지 않음(해 없음)은 확인됐으나 **lift(우위)는 없음** — 단순 과제는 하네스를 exercise하지 않기 때문.
|
||||
-- **미증명**: 하네스의 가치가설(다관점 fan-out·근거접지·사람게이트)이 발휘되는 **모호·설계·의사결정 과제(GT-09~12)는 자동채점 fixture가 없어 아직 측정 못 함**. head-to-head rubric 채점을 붙여야 "품질이 높다"를 말할 수 있다.
|
||||
-```bash
|
||||
-python3 .claude/hooks/benchmark.py list # 골든태스크 목록
|
||||
-python3 .claude/hooks/benchmark.py run --task GT-01 --arm plain --execute # 실제 실행·객관채점(예산 소비)
|
||||
-python3 .claude/hooks/benchmark.py compare # → benchmark/BENCHMARK.md (plain vs 하네스 delta)
|
||||
-```
|
||||
-> 판정 규칙: 어떤 role/fan-out/framework가 이 비교에서 delta≤0이면 비용만 늘리는 것 → 제거/경량화 후보. **증명 안 된 것을 증명된 척하지 않는다.**
|
||||
+- `company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다. <!-- claim-id: C-LIMIT-CONTEXT -->
|
||||
+- 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다. <!-- claim-id: C-LIMIT-HOOKS -->
|
||||
+- UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다. <!-- claim-id: C-LIMIT-UI -->
|
||||
+- Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다. <!-- claim-id: C-LIMIT-TOOLS -->
|
||||
+- plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다. <!-- claim-id: C-LIMIT-EVIDENCE -->
|
||||
+
|
||||
+<!-- section-id: reference -->
|
||||
+## 정본 파일 지도
|
||||
+
|
||||
+- Workflow와 artifact: [workflow-contracts.yaml](org-os/06-agent-work/workflow-contracts.yaml) · [artifact vocabulary](org-os/06-agent-work/artifact-type-vocabulary.yaml)
|
||||
+- 역할과 라우팅: [roles.yaml](org-os/00-role-registry/roles.yaml) · [capability-families.yaml](org-os/00-role-registry/capability-families.yaml)
|
||||
+- 권한과 실행: [tool-permission-matrix.yaml](org-os/00-role-registry/tool-permission-matrix.yaml) · [execution-policy.yaml](org-os/06-agent-work/execution-policy.yaml)
|
||||
+- 런타임 요구사항: [tool-versions.yaml](.claude/tool-versions.yaml) · [requirements.txt](requirements.txt)
|
||||
+- Claude Code 어댑터: [commands](.claude/commands/) · [hooks](.claude/hooks/) · [schemas](.claude/schemas/) · [tests](.claude/tests/)
|
||||
+- 실증 자료: [golden tasks](benchmark/golden-tasks.yaml) · [benchmark report](benchmark/BENCHMARK.md)
|
||||
+- 설계와 변경 이력: [docs](docs/)
|
||||
+
|
||||
+README는 첫 판단과 운영 진입에 필요한 정보만 유지합니다. 세부 규칙을 바꿀 때는 위 정본을 수정하고 관련 생성·검증 경로를 함께 확인하십시오.
|
||||
@@ -0,0 +1,7 @@
|
||||
schema-version: 1
|
||||
mode: bootstrap
|
||||
target-rel: README.md
|
||||
generated-hash: sha256:2e57d3f0e5477bf5f091501e436554860125857e560c9119993d7d5eb262ad93
|
||||
target-before-hash: sha256:0686e6df63886ee361c919fc27c39ceb6925cd7b7994fce402b82e356cfca7c7
|
||||
repository-snapshot-hash: sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64
|
||||
review-score: 93
|
||||
@@ -0,0 +1,230 @@
|
||||
schema-version: 1
|
||||
claims:
|
||||
- id: C-IDENTITY
|
||||
type: factual
|
||||
statement: Org OS 하네스는 제품·개발·운영·GTM 업무를 여러 AI 역할에 배분하고, 단계별 산출물과 사람 승인을 파일 계약으로 연결하는 Claude Code 프로젝트 하네스입니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-IDENTITY-CORE}, {fact-id: F-WORKFLOW-CASCADE}]
|
||||
status: supported
|
||||
- id: C-VALUE
|
||||
type: factual
|
||||
statement: 워크플로 그래프, 역할·권한, typed artifact, 실행 증거를 각각 정본 파일과 hook으로 연결합니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-ARCH-STATE-ARTIFACT}, {fact-id: F-ARCH-HOOKS}, {fact-id: F-ARTIFACT-PROVENANCE}]
|
||||
status: supported
|
||||
- id: C-ENTRY-MODEL
|
||||
type: factual
|
||||
statement: 일반적인 새 작업은 `/ceo-intake`에서 의도와 작업 규모를 구조화한 뒤, 선택된 plan에 따라 discovery·decision·design·build·verification·acceptance로 진행됩니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-WORKFLOW-ENTRY}, {fact-id: F-WORKFLOW-CASCADE}, {fact-id: F-WORKFLOW-WAVE-LIGHT}]
|
||||
status: supported
|
||||
- id: C-CONTRACT-MODEL
|
||||
type: factual
|
||||
statement: "`workflow-contracts.yaml`이 stage, command, artifact bundle, reviewer capability, exit gate를 정의하고 `state_engine.py`가 그 그래프를 읽습니다."
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-ARCH-STATE-ARTIFACT}]
|
||||
status: supported
|
||||
- id: C-COLLAB-MODEL
|
||||
type: factual
|
||||
statement: 현재 family 정책은 판단·설계·분석을 멤버별로 격리하는 fan-out과 코드·실행을 한 concrete worker로 모으는 collapse를 구분합니다.
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-ARCH-COLLABORATION}]
|
||||
status: supported
|
||||
- id: C-HUMAN-BOUNDARY
|
||||
type: factual
|
||||
statement: 전체 cascade는 방향 수용과 release 승인 같은 사람 결정 지점에서 멈추도록 정의되어 있습니다.
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-WORKFLOW-CASCADE}, {fact-id: F-WORKFLOW-SPECIALIZED}]
|
||||
status: supported
|
||||
- id: C-PROVENANCE-MODEL
|
||||
type: factual
|
||||
statement: workflow와 artifact는 append-only event 및 id+SHA-256 snapshot으로 연결되고, report는 새 시도마다 새 파일로 발급됩니다.
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-ARCH-STATE-ARTIFACT}, {fact-id: F-ARTIFACT-PROVENANCE}]
|
||||
status: supported
|
||||
- id: C-HOOK-MODEL
|
||||
type: factual
|
||||
statement: Claude Code가 이 프로젝트의 `.claude/settings.json`을 로드하면 PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop 이벤트가 각각 도구 경계·증거 원장·subagent 등록·종료 검증에 연결됩니다.
|
||||
section: operating-model
|
||||
sources: [{fact-id: F-ARCH-HOOKS}]
|
||||
status: supported
|
||||
- id: C-PREREQUISITES
|
||||
type: factual
|
||||
statement: 핵심 hook과 테스트에는 Python 3.10 이상과 PyYAML 6.0 이상이 필요합니다. `requirements.txt`는 PyYAML 6.0.1과 jsonschema 4.10.3을 고정합니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-PREREQ-TOOLS}]
|
||||
status: supported
|
||||
- id: C-INSTALL-COMMAND
|
||||
type: factual
|
||||
statement: pip install -r requirements.txt
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-PREREQ-TOOLS}]
|
||||
status: supported
|
||||
- id: C-WORKSPACE-RESOLUTION
|
||||
type: factual
|
||||
statement: 산출물 경로는 `ORGOS_WORKSPACE` 환경변수를 먼저 사용하고, 없으면 `.orgos-workspace`의 첫 유효 줄을 사용합니다. 둘 다 없으면 strict 운영 hook은 exit 2로 중단합니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-ARTIFACT-LAYOUT}]
|
||||
status: supported
|
||||
- id: C-DOCTOR-COMMAND
|
||||
type: factual
|
||||
statement: python3 .claude/hooks/doctor.py
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-CI-WORKFLOW}, {fact-id: F-ARTIFACT-LAYOUT}]
|
||||
status: supported
|
||||
- id: C-DOCTOR-SCOPE
|
||||
type: factual
|
||||
statement: "`doctor.py`는 hook 배선, 참조 스크립트, Python 의존성, workspace, 참조 무결성을 점검하고 hard failure가 있으면 비영점으로 종료합니다."
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-VERIFY-SUITE}, {fact-id: F-CI-WORKFLOW}]
|
||||
status: supported
|
||||
- id: C-FIRST-COMMAND
|
||||
type: factual
|
||||
statement: Claude Code에서 일반적인 새 제품·개발·운영 요청은 `/ceo-intake`로 시작합니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-WORKFLOW-ENTRY}, {fact-id: F-WORKFLOW-SPECIALIZED}]
|
||||
status: supported
|
||||
- id: C-WORKFLOW-CASCADE
|
||||
type: factual
|
||||
statement: "`/ceo-intake` → `/ground` → `/decide` → `/design` → `/spec` → `/build` → `/review-output` → `/release-check` → `released`"
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-CASCADE}]
|
||||
status: supported
|
||||
- id: C-WORKFLOW-WAVE
|
||||
type: factual
|
||||
statement: "`/ceo-intake` → `/plan-wave` → `/run-wave` → `/review-output` → `/release-check` → `released`"
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-WAVE-LIGHT}]
|
||||
status: supported
|
||||
- id: C-WORKFLOW-LIGHT
|
||||
type: factual
|
||||
statement: "`/ceo-intake` → `/run-wave` → `/review-output` → `acceptance`"
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-WAVE-LIGHT}]
|
||||
status: supported
|
||||
- id: C-WORKFLOW-VENTURE
|
||||
type: factual
|
||||
statement: founder context를 채운 뒤 `/ceo-intake --plan venture-bootstrap` → `/venture-validate` → `/company-bootstrap` → `bootstrap-complete`
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-VENTURE}]
|
||||
status: supported
|
||||
- id: C-SPECIALIZED-WORKFLOWS
|
||||
type: factual
|
||||
statement: "`/run-cascade`는 cascade의 현재 stage와 다음 command를 계산하는 상위 드라이버입니다. `/design-direction`은 제품 cascade에 종속된 방향 탐색 child workflow이고, `/design-system`과 `/consult`는 각각 코드 UI 검증과 독립 자문 산출물에 초점을 둡니다."
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-SPECIALIZED}]
|
||||
status: supported
|
||||
- id: C-CASCADE-VISUAL
|
||||
type: factual
|
||||
statement: 다음 흐름은 `workflow-contracts.yaml`에 정의된 cascade stage와 사람 결정 경계를 요약합니다.
|
||||
section: workflows
|
||||
sources: [{fact-id: F-WORKFLOW-CASCADE}, {fact-id: F-WORKFLOW-SPECIALIZED}]
|
||||
status: supported
|
||||
- id: C-ARCH-SOURCE
|
||||
type: factual
|
||||
statement: 실행 그래프의 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 역할·권한 정책은 `org-os/00-role-registry/`에 있고, Claude Code용 command·agent·skill·hook은 `.claude/` 아래에서 이 계약을 소비하거나 검증합니다.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-ARCH-STATE-ARTIFACT}, {fact-id: F-ARCH-DIRECTORIES}]
|
||||
status: supported
|
||||
- id: C-DIRECTORY-MAP
|
||||
type: factual
|
||||
statement: 저장소 구조와 책임
|
||||
section: architecture
|
||||
sources: [{fact-id: F-ARCH-DIRECTORIES}]
|
||||
status: supported
|
||||
- id: C-ROLE-MODEL
|
||||
type: factual
|
||||
statement: 현재 registry는 75개 AI 역할과 최종 사람 소유자 `HUMAN-001`, 28개 routing family, 12개 평가 lens를 정의합니다. agent generator의 현재 정합 계약은 101개 agent card입니다.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-ARCH-ROLE-MODEL}]
|
||||
status: supported
|
||||
- id: C-GENERATED-AGENTS
|
||||
type: factual
|
||||
statement: 기여할 때는 산출된 `.claude/agents/*.md`만 직접 고치기보다 역할·family·method·tool 정본을 먼저 수정하고 생성기 정합 검사를 통과시키는 구조를 따르십시오.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-ARCH-DIRECTORIES}, {fact-id: F-ARCH-ROLE-MODEL}]
|
||||
status: supported
|
||||
- id: C-WORKSPACE-LAYOUT
|
||||
type: factual
|
||||
statement: "`ORGOS_WORKSPACE`가 상대 경로이면 저장소 루트 아래 프로젝트 디렉터리로 해석되고, 절대 경로이면 그대로 사용됩니다."
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-ARTIFACT-LAYOUT}]
|
||||
status: supported
|
||||
- id: C-REPORT-RECEIPTS
|
||||
type: factual
|
||||
statement: report는 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml` 형식으로 새로 발급됩니다. 실행 command와 exit code, 작성 파일 경로와 SHA-256은 evidence ledger의 receipt로 남길 수 있지만, workspace를 해석하지 못한 계측 hook은 기록을 생략할 수 있습니다.
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-ARTIFACT-PROVENANCE}]
|
||||
status: supported
|
||||
- id: C-CMD-DOCTOR
|
||||
type: factual
|
||||
statement: python3 .claude/hooks/doctor.py
|
||||
section: verification
|
||||
sources: [{fact-id: F-CI-WORKFLOW}]
|
||||
status: supported
|
||||
- id: C-CMD-AGENTS
|
||||
type: factual
|
||||
statement: python3 .claude/hooks/gen_agents.py --check
|
||||
section: verification
|
||||
sources: [{fact-id: F-ARCH-ROLE-MODEL}, {fact-id: F-CI-WORKFLOW}]
|
||||
status: supported
|
||||
- id: C-CMD-TESTS
|
||||
type: factual
|
||||
statement: python3 .claude/tests/run_all.py
|
||||
section: verification
|
||||
sources: [{fact-id: F-VERIFY-SUITE}]
|
||||
status: supported
|
||||
- id: C-CMD-BENCHMARK
|
||||
type: factual
|
||||
statement: python3 .claude/hooks/benchmark.py list
|
||||
section: verification
|
||||
sources: [{fact-id: F-MATURITY-BENCHMARK}]
|
||||
status: supported
|
||||
- id: C-TEST-RUNNER
|
||||
type: factual
|
||||
statement: "`run_all.py`는 artifact registry check, doctor, reference lint를 거친 뒤 `.claude/tests/test_*.py`를 suite별 제한시간과 함께 순차 실행합니다. 하나라도 실패하거나 timeout이면 exit 1입니다."
|
||||
section: verification
|
||||
sources: [{fact-id: F-VERIFY-SUITE}]
|
||||
status: supported
|
||||
- id: C-CI
|
||||
type: factual
|
||||
statement: GitHub Actions는 Python 3.12와 Node 20, `_sandbox` workspace에서 의존성을 설치하고 doctor, reference lint, agent generation check, 전체 test suite를 분리해 실행하도록 정의돼 있습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-CI-WORKFLOW}]
|
||||
status: supported
|
||||
- id: C-BENCHMARK-STATUS
|
||||
type: factual
|
||||
statement: 벤치마크에는 13개 golden task가 정의돼 있지만 현재 실행 ledger에는 GT-01과 GT-R2의 plain·harness 표본만 있습니다. 두 과제는 first-pass acceptance, test pass rate, unnecessary change lines에서 모두 동률이므로 현재 데이터는 하네스의 품질 우위를 입증하지 않습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-MATURITY-BENCHMARK}]
|
||||
status: supported
|
||||
- id: C-LIMIT-CONTEXT
|
||||
type: factual
|
||||
statement: "`company-context.yaml`과 `founder-context.yaml`은 현재 `template` 상태입니다. 회사 수립 경로를 사용하려면 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 합니다."
|
||||
section: limitations
|
||||
sources: [{fact-id: F-MATURITY-CONTEXT}, {fact-id: F-WORKFLOW-VENTURE}]
|
||||
status: supported
|
||||
- id: C-LIMIT-HOOKS
|
||||
type: factual
|
||||
statement: 강제 hook은 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션 경계 안에서 동작합니다. 다른 실행 환경에서 같은 강제를 자동으로 보장하지 않습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-ARCH-HOOKS}]
|
||||
status: supported
|
||||
- id: C-LIMIT-UI
|
||||
type: factual
|
||||
statement: UI preview는 DOM mount, bundle, 대비, focus, 반응형 screenshot 같은 render health를 검사하지만 시각적 차별성·타이포그래피·비례·spacing의 미학 품질을 판정하지 않습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-PREREQ-UI}]
|
||||
status: supported
|
||||
- id: C-LIMIT-TOOLS
|
||||
type: factual
|
||||
statement: Node 18 이상과 D2 0.6 이상은 관련 기능의 권장 도구이고, Marp 3 이상은 선택 사항입니다. 전체 UI render에는 Chrome 또는 Chromium 계열 실행 파일도 필요합니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-PREREQ-TOOLS}, {fact-id: F-PREREQ-UI}]
|
||||
status: supported
|
||||
- id: C-LIMIT-EVIDENCE
|
||||
type: factual
|
||||
statement: plain 대 harness의 현재 실행 표본은 저난도 bugfix 두 과제뿐이며 결과는 동률입니다. 설계·문서·의사결정 과제에 대한 품질 향상은 아직 실증되지 않았습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-MATURITY-BENCHMARK}]
|
||||
status: supported
|
||||
@@ -0,0 +1,13 @@
|
||||
schema-version: 1
|
||||
mode: bootstrap
|
||||
profile: generic
|
||||
repository-snapshot-hash: sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64
|
||||
artifacts:
|
||||
readme-request.yaml: sha256:1b836226cd3aff5eb108ebafe053d5f4ca7b1376a93d19a9bd47d3aaa6b9dcac
|
||||
repository-facts.yaml: sha256:93020532ad2cd0fc40b55d299acfeebf33ba3ac76bcceb1133ec7696d9ba5a3f
|
||||
readme-brief.yaml: sha256:d1d9c930dc36800f4d8bf00c8b5bc51f57e107a19c735d2b4b006cbfed87f663
|
||||
readme-outline.yaml: sha256:a2f39fcc3988f1c2b04e47ca07ec68ca547aecbf698ca63341f9337a994cfe06
|
||||
README.candidate.md: sha256:2e57d3f0e5477bf5f091501e436554860125857e560c9119993d7d5eb262ad93
|
||||
claim-map.yaml: sha256:5404d520fdf3dd92d2787310f1f31b6710620a0d00412319da7fa0a622eaf67c
|
||||
visual-plan.yaml: sha256:870e85cb973b0ee2b3ecf139e0ad6d06f203ed3340cf26d2e3c649f41ff1e5ad
|
||||
review-findings.yaml: sha256:1ef3f845fa9a6457188aba426ea6723a9d645ccc64a6803d304a76bfde750995
|
||||
@@ -0,0 +1,59 @@
|
||||
schema-version: 1
|
||||
project-profile:
|
||||
primary: generic
|
||||
secondary:
|
||||
- workflow-harness
|
||||
- configuration-repository
|
||||
audiences:
|
||||
primary:
|
||||
- 저장소를 처음 사용하는 운영자와 개발자
|
||||
- 하네스의 역할·워크플로·검증 계약을 변경하는 기여자
|
||||
secondary:
|
||||
- 에이전트 운영 모델과 증거 체계를 평가하는 기술 리더
|
||||
reader-outcomes:
|
||||
- 이 저장소가 해결하는 운영 문제와 적용 범위를 30초 안에 설명한다.
|
||||
- 필수 도구와 워크스페이스를 설정하고 preflight 진입점을 찾는다.
|
||||
- cascade·wave·light·venture 경로 가운데 작업에 맞는 흐름을 고른다.
|
||||
- 역할·워크플로·훅·산출물의 정본과 변경 위치를 구분한다.
|
||||
- 정적 검증과 실제 실행 증거의 차이 및 현재 실증 한계를 확인한다.
|
||||
project-story:
|
||||
value-proposition: 역할 선택부터 사람 승인, 산출물 검증, 증거 기록까지를 Claude Code 명령·계약·훅으로 연결하는 파일 기반 에이전트 운영 하네스다.
|
||||
problem: 여러 에이전트가 긴 작업을 수행하면 역할 경계, 선행 산출물, 승인 주체, 실행 증거가 산문과 대화 안에서 쉽게 분리된다.
|
||||
target-reader: Claude Code에서 복수 역할의 제품·개발·운영 워크플로를 일관된 계약으로 운용하려는 사용자와 기여자
|
||||
notable-traits:
|
||||
- text: workflow-contracts가 단계, 산출물 bundle, 검토 권한, exit gate를 한 그래프로 정의한다.
|
||||
fact-ids: [F-WORKFLOW-CASCADE, F-ARCH-STATE-ARTIFACT]
|
||||
- text: 역할 75개를 28개 family로 라우팅하고 현재 생성기 계약은 101개 agent card의 정합을 검사한다.
|
||||
fact-ids: [F-ARCH-ROLE-MODEL, F-ARCH-COLLABORATION]
|
||||
- text: Claude Code hook이 도구 사용, 증거 기록, subagent 수명주기, 종료 검증을 연결한다.
|
||||
fact-ids: [F-ARCH-HOOKS, F-ARTIFACT-PROVENANCE]
|
||||
- text: 프로젝트별 workspace에 불변 report와 append-only 상태·증거 기록을 분리한다.
|
||||
fact-ids: [F-ARTIFACT-LAYOUT, F-ARTIFACT-PROVENANCE]
|
||||
- text: 전체 테스트 진입점과 plain 대 harness 벤치마크는 존재하지만 현재 품질 우위 표본은 제한적이다.
|
||||
fact-ids: [F-VERIFY-SUITE, F-MATURITY-BENCHMARK]
|
||||
maturity: 실행 계약과 검증 코드는 구현되어 있으나 회사 컨텍스트는 template이고 품질 우위 실증은 초기 표본에 머문 상태
|
||||
limitations:
|
||||
- 강제 hook은 Claude Code가 이 프로젝트의 .claude/settings.json을 로드한 세션에서 적용된다.
|
||||
- 현재 company-context와 founder-context는 template 상태라 회사 수립 경로에 사람 입력이 필요하다.
|
||||
- 기록된 plain 대 harness 실행 표본은 두 저난도 과제뿐이며 모두 동률이다.
|
||||
- UI 렌더와 덱 출력 같은 일부 경로는 Node, 브라우저, D2 또는 Marp 같은 추가 도구에 의존한다.
|
||||
narrative-variant: custom
|
||||
reader-journey:
|
||||
- reader-question: 이 저장소는 무엇을 어떤 방식으로 운영하는가?
|
||||
section-id: overview
|
||||
- reader-question: 대화형 프롬프트와 다른 핵심 운영 원칙은 무엇인가?
|
||||
section-id: operating-model
|
||||
- reader-question: 사용 전에 무엇을 설치하고 어떤 workspace를 지정해야 하는가?
|
||||
section-id: quick-start
|
||||
- reader-question: 작업 크기와 목적에 맞는 workflow는 무엇인가?
|
||||
section-id: workflows
|
||||
- reader-question: 규칙과 실행 코드는 어디에 있고 서로 어떻게 연결되는가?
|
||||
section-id: architecture
|
||||
- reader-question: 실행 결과와 증거는 어디에 어떤 형태로 남는가?
|
||||
section-id: artifacts
|
||||
- reader-question: 저장소 정합과 품질 주장을 어떻게 검증하는가?
|
||||
section-id: verification
|
||||
- reader-question: 도입 전에 받아들여야 할 현재 한계는 무엇인가?
|
||||
section-id: limitations
|
||||
- reader-question: 세부 계약을 직접 확인하거나 변경하려면 어디를 읽는가?
|
||||
section-id: reference
|
||||
@@ -0,0 +1,142 @@
|
||||
schema-version: 1
|
||||
sections:
|
||||
- id: overview
|
||||
title-guidance: Org OS 하네스 개요
|
||||
level: 2
|
||||
purpose: 프로젝트의 정체성, 대상 독자, 해결하려는 운영 문제를 빠르게 판단시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- Claude Code 기반 파일형 운영 하네스라는 구체적 정의
|
||||
- 개발과 비즈니스 workflow를 함께 다루는 범위
|
||||
- 대화 프롬프트 모음이 아니라 계약과 검증을 연결한다는 가치
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 프로젝트 정체성을 이해하는 데 별도 그림이 필요한가?
|
||||
rationale: 제목과 두 문단의 구체적인 정의가 그림보다 빠르게 전달된다.
|
||||
|
||||
- id: operating-model
|
||||
title-guidance: 핵심 운영 모델
|
||||
level: 2
|
||||
purpose: 역할 라우팅, 상태 전이, 사람 게이트, 증거 기록이 어떤 원칙으로 결합되는지 설명한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- workflow-contracts 중심의 상태·산출물 계약
|
||||
- fan-out과 collapse의 구분
|
||||
- immutable artifact와 사람 승인 경계
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 핵심 원칙을 이해하는 데 관계도가 필요한가?
|
||||
rationale: 세 가지 원칙을 짧은 목록으로 분리하는 편이 더 명확하다.
|
||||
|
||||
- id: quick-start
|
||||
title-guidance: 시작하기
|
||||
level: 2
|
||||
purpose: 필수 도구, 의존성, workspace, preflight, 첫 slash command까지의 최소 경로를 제공한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- Python과 PyYAML 최소 버전
|
||||
- requirements 설치 명령과 수동 검증 한계
|
||||
- ORGOS_WORKSPACE 우선순위와 유효한 디렉터리 조건
|
||||
- doctor 성공 신호
|
||||
- 일반 workflow의 첫 명령 /ceo-intake
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 설치와 첫 실행 순서를 이해하는 데 그림이 필요한가?
|
||||
rationale: 복사 가능한 명령 블록과 예상 결과가 가장 직접적이다.
|
||||
|
||||
- id: workflows
|
||||
title-guidance: 작업에 맞는 워크플로 선택
|
||||
level: 2
|
||||
purpose: cascade, wave, light, venture-bootstrap, 전문 진입점을 입력·단계·종단 기준으로 구분한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- cascade 전체 흐름과 사람 결정 지점
|
||||
- wave와 light의 차이
|
||||
- venture-bootstrap의 사람 입력과 결과
|
||||
- run-cascade, design-direction, design-system, consult의 범위
|
||||
visual-slot:
|
||||
decision: include
|
||||
reader-question: cascade의 여덟 단계와 사람 승인 지점은 어떤 순서인가?
|
||||
rationale: 단계와 gate가 연속되는 관계는 표보다 흐름도가 더 빠르게 전달한다.
|
||||
purpose: intake부터 release까지의 공식 cascade와 사람 승인 경계를 한 화면에 보여준다.
|
||||
|
||||
- id: architecture
|
||||
title-guidance: 저장소 구조와 책임
|
||||
level: 2
|
||||
purpose: 정본 계약, Claude Code 어댑터, 생성 카드, 테스트와 벤치마크의 책임을 구분한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- org-os와 .claude 하위 디렉터리의 책임 표
|
||||
- workflow-contracts에서 state_engine과 agent generator로 이어지는 관계
|
||||
- 기여자가 규칙별로 수정할 위치
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 디렉터리별 변경 위치를 찾는 데 두 번째 그림이 필요한가?
|
||||
rationale: 경로와 책임을 직접 짝지은 표가 탐색에 더 적합하고 시각물 한도도 지킨다.
|
||||
|
||||
- id: artifacts
|
||||
title-guidance: 워크스페이스와 산출물
|
||||
level: 2
|
||||
purpose: workspace 선택 규칙과 report, evidence, state, human view의 저장 위치·불변성을 설명한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- ORGOS_WORKSPACE와 pointer의 우선순위
|
||||
- completion-records, evidence, reports, state 경로
|
||||
- report 새 파일 발급과 receipt의 실행 증거
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 산출물 경로를 찾는 데 그림이 필요한가?
|
||||
rationale: 작은 디렉터리 tree와 책임 설명이면 충분하다.
|
||||
|
||||
- id: verification
|
||||
title-guidance: 검증 방법과 증거 수준
|
||||
level: 2
|
||||
purpose: preflight, agent generation, 전체 suite, CI, benchmark를 목적과 검증 수준별로 제공한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- doctor, gen_agents --check, run_all 명령
|
||||
- 정적 확인과 실제 실행의 차이
|
||||
- CI의 분리 실행 경로
|
||||
- benchmark list와 현재 표본의 해석
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 검증 명령 선택에 그림이 필요한가?
|
||||
rationale: 목적·명령·성공 신호·수준을 짝지은 표가 더 정확하다.
|
||||
|
||||
- id: limitations
|
||||
title-guidance: 현재 상태와 한계
|
||||
level: 2
|
||||
purpose: template context, 제한된 benchmark, 선택 도구와 hook 경계를 과장 없이 밝힌다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- company와 founder context의 template 상태
|
||||
- 두 저난도 benchmark만 실행됐고 동률이라는 결과
|
||||
- UI 미학은 자동 판정하지 않는다는 한계
|
||||
- 일부 기능의 추가 도구 의존성과 Claude Code session 경계
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 현재 한계를 이해하는 데 시각화가 필요한가?
|
||||
rationale: 근거와 영향을 한 줄씩 연결한 목록이 더 정직하고 명료하다.
|
||||
|
||||
- id: reference
|
||||
title-guidance: 정본 파일 지도
|
||||
level: 2
|
||||
purpose: 세부 workflow, 역할, 권한, 실행 정책, 도구 버전, command 정의로 직접 이동시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- workflow-contracts, roles, families, permissions, execution policy 링크
|
||||
- command, hook, schema, test 디렉터리 링크
|
||||
- 상세 설계 이력은 docs로 분리
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 세부 정본을 찾는 데 그림이 필요한가?
|
||||
rationale: 목적별 상대 링크 목록이 탐색과 유지보수에 가장 적합하다.
|
||||
@@ -0,0 +1,46 @@
|
||||
schema-version: 1
|
||||
target:
|
||||
repository: /home/donghyeon/workspace/ai-tool/company-haness
|
||||
readme-path: README.md
|
||||
mode: bootstrap
|
||||
profile-override: generic
|
||||
project-intent:
|
||||
purpose: 대상 저장소의 핵심 운영 흐름, 구조, 검증 방법을 실제 파일 근거에 맞춰 설명한다.
|
||||
positioning: AI 에이전트 기반 회사 운영 하네스를 처음 접하는 사용자와 기여자를 위한 저장소 진입 문서다.
|
||||
maturity: 현재 저장소에서 확인되는 구현과 한계를 과장 없이 문서화한다.
|
||||
audience:
|
||||
primary:
|
||||
- 저장소를 처음 사용하는 운영자와 개발자
|
||||
- 하네스에 기여하려는 개발자
|
||||
secondary:
|
||||
- 에이전트 워크플로와 산출물 계약을 검토하는 기술 리더
|
||||
reader-actions:
|
||||
- 프로젝트의 목적과 적용 범위를 빠르게 파악한다.
|
||||
- 대표 진입점과 최소 사용 흐름을 선택한다.
|
||||
- 주요 디렉터리와 산출물 위치를 찾는다.
|
||||
- 저장소가 정의한 검증 명령과 현재 한계를 확인한다.
|
||||
content-policy:
|
||||
language: ko-KR
|
||||
tone: 간결하고 기술적이며 검증 수준을 명시하는 설명체
|
||||
target-length: long
|
||||
preserve-existing-copy: false
|
||||
detail-docs-policy: summary-and-link
|
||||
visual-policy:
|
||||
mode: when-useful
|
||||
max-visuals: 1
|
||||
preferred-formats:
|
||||
- mermaid
|
||||
placeholder-format: HTML 주석 기반 제작 사양
|
||||
must-include:
|
||||
- 프로젝트 개요와 대상 독자
|
||||
- 대표 워크플로 진입점과 선택 기준
|
||||
- 저장소 구조와 주요 책임
|
||||
- 최소 사용 절차
|
||||
- 검증 명령과 검증 수준
|
||||
- 산출물 위치
|
||||
- 현재 한계
|
||||
must-exclude:
|
||||
- 저장소 근거가 없는 기능·버전·성능 우위 주장
|
||||
- 비밀 값 또는 개인 환경의 절대 경로
|
||||
- 상세 설계 이력의 장문 복제
|
||||
protected-sections: []
|
||||
@@ -0,0 +1,547 @@
|
||||
schema-version: 1
|
||||
repository-snapshot-hash: sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64
|
||||
project-name: Org OS 하네스
|
||||
languages: [Python, YAML, Markdown]
|
||||
frameworks: [Claude Code]
|
||||
facts:
|
||||
- id: F-IDENTITY-CORE
|
||||
category: identity
|
||||
key: project-identity-and-purpose
|
||||
value:
|
||||
name: Org OS 하네스
|
||||
purpose: 회사 전체를 AI 에이전트로 운영하는 파일 기반 운영체계로, 개발과 비즈니스 업무를 함께 다룬다.
|
||||
runtime: Claude Code의 subagent, project command, hook
|
||||
assertion-type: declared
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: CLAUDE.md
|
||||
line-start: 1
|
||||
line-end: 3
|
||||
source-kind: project-documentation
|
||||
|
||||
- id: F-WORKFLOW-ENTRY
|
||||
category: workflow
|
||||
key: new-workflow-entrypoint
|
||||
value:
|
||||
command: /ceo-intake
|
||||
applies-to: [cascade, wave, light, venture-bootstrap]
|
||||
normal-outputs: [decision-brief, workload-profile]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 46
|
||||
line-end: 54
|
||||
source-kind: workflow-contract
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 103
|
||||
line-end: 124
|
||||
source-kind: workflow-contract
|
||||
|
||||
- id: F-WORKFLOW-CASCADE
|
||||
category: workflow
|
||||
key: cascade-stage-map
|
||||
value:
|
||||
terminal-stage: released
|
||||
stages:
|
||||
- {stage: intake, command: /ceo-intake, output: [decision-brief, workload-profile]}
|
||||
- {stage: discovery, command: /ground, output: [grounding-package]}
|
||||
- {stage: decide, command: /decide, output: [executive-decision-packet]}
|
||||
- {stage: design, command: /design, output: conditional-design-bundle}
|
||||
- {stage: spec, command: /spec, output: conditional-spec-bundle}
|
||||
- {stage: build, command: /build, output: [completion-record]}
|
||||
- {stage: verification, command: /review-output, output: [quality-gate-review]}
|
||||
- {stage: acceptance, command: /release-check, output: [release-decision]}
|
||||
release-exit-gates: [release-approved, no-unresolved-critical-risks, human-gate]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 46
|
||||
line-end: 101
|
||||
source-kind: workflow-contract
|
||||
|
||||
- id: F-WORKFLOW-WAVE-LIGHT
|
||||
category: workflow
|
||||
key: wave-and-light-selection
|
||||
value:
|
||||
wave:
|
||||
commands: [/ceo-intake, /plan-wave, /run-wave, /review-output, /release-check]
|
||||
terminal-stage: released
|
||||
light:
|
||||
commands: [/ceo-intake, /run-wave, /review-output]
|
||||
terminal-stage: acceptance
|
||||
omitted-stage: plan
|
||||
intended-for: 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 103
|
||||
line-end: 119
|
||||
source-kind: workflow-contract
|
||||
- path: org-os/06-agent-work/execution-plans.yaml
|
||||
line-start: 23
|
||||
line-end: 37
|
||||
source-kind: execution-plan
|
||||
|
||||
- id: F-WORKFLOW-VENTURE
|
||||
category: workflow
|
||||
key: venture-bootstrap
|
||||
value:
|
||||
entry: /ceo-intake --plan venture-bootstrap
|
||||
subsequent-commands: [/venture-validate, /company-bootstrap]
|
||||
founder-input: org-os/01-company/founder-context.yaml
|
||||
required-founder-status: filled
|
||||
output: org-os/01-company/company-context.yaml
|
||||
output-status: provisional
|
||||
terminal-stage: bootstrap-complete
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/06-agent-work/workflow-contracts.yaml
|
||||
line-start: 121
|
||||
line-end: 130
|
||||
source-kind: workflow-contract
|
||||
- path: org-os/06-agent-work/execution-plans.yaml
|
||||
line-start: 38
|
||||
line-end: 47
|
||||
source-kind: execution-plan
|
||||
- path: org-os/01-company/founder-context.yaml
|
||||
line-start: 1
|
||||
line-end: 5
|
||||
source-kind: company-context-input
|
||||
|
||||
- id: F-WORKFLOW-SPECIALIZED
|
||||
category: workflow
|
||||
key: specialized-entrypoints
|
||||
value:
|
||||
/run-cascade: 전체 cascade를 state_engine으로 순회하고 사람 결정 게이트에서 중단·재개하는 상위 드라이버
|
||||
/design-direction: 제품 cascade의 child workflow로 발산·선택·prototype·비평을 거쳐 approved-direction을 산출
|
||||
/design-system: 기존 스택을 조사해 reuse/adapt/create를 선택하고 코드 UI와 렌더 미리보기를 검증
|
||||
/consult: 비즈니스 자문 또는 문서 자문 family를 선택해 문서와 덱을 산출
|
||||
assertion-type: declared
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/commands/run-cascade.md
|
||||
line-start: 1
|
||||
line-end: 24
|
||||
source-kind: command-definition
|
||||
- path: .claude/commands/design-direction.md
|
||||
line-start: 1
|
||||
line-end: 25
|
||||
source-kind: command-definition
|
||||
- path: .claude/commands/design-system.md
|
||||
line-start: 1
|
||||
line-end: 10
|
||||
source-kind: command-definition
|
||||
- path: .claude/commands/consult.md
|
||||
line-start: 1
|
||||
line-end: 12
|
||||
source-kind: command-definition
|
||||
|
||||
- id: F-ARCH-DIRECTORIES
|
||||
category: architecture
|
||||
key: repository-directory-responsibilities
|
||||
value:
|
||||
org-os/00-role-registry: 역할·family·lens·상태 전이·권한 정책의 원천
|
||||
org-os/06-agent-work: workflow·artifact·협업·실행 계약
|
||||
.claude/commands: 사용자 workflow 진입점
|
||||
.claude/agents: registry에서 생성되는 실행 역할·resolver·router 카드
|
||||
.claude/skills: 역할별 작업 방법
|
||||
.claude/hooks: 상태 엔진·검증·증거 원장·렌더러·생성기
|
||||
.claude/schemas: report와 typed artifact 스키마
|
||||
.claude/tests: 하네스 강제기와 workflow 계약 테스트
|
||||
benchmark: golden task와 plain-vs-harness 비교 자료
|
||||
project-workspace: completion record·evidence·report·state·UI 산출물
|
||||
assertion-type: derived
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: CLAUDE.md
|
||||
line-start: 5
|
||||
line-end: 43
|
||||
source-kind: architecture-documentation
|
||||
- path: .claude/hooks/_workspace.py
|
||||
line-start: 1
|
||||
line-end: 15
|
||||
source-kind: runtime-path-implementation
|
||||
|
||||
- id: F-ARCH-ROLE-MODEL
|
||||
category: architecture
|
||||
key: role-family-lens-model
|
||||
value:
|
||||
reference-ai-roles: 75
|
||||
final-human-owner: HUMAN-001
|
||||
routing-families: 28
|
||||
evaluation-lenses: 12
|
||||
generated-agent-cards-contract: 101
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/00-role-registry/roles.yaml
|
||||
line-start: 1
|
||||
line-end: 20
|
||||
source-kind: role-registry
|
||||
- path: org-os/00-role-registry/capability-families.yaml
|
||||
line-start: 1
|
||||
line-end: 13
|
||||
source-kind: family-registry
|
||||
- path: org-os/00-role-registry/lens-registry.yaml
|
||||
line-start: 1
|
||||
line-end: 25
|
||||
source-kind: lens-registry
|
||||
- path: .claude/hooks/gen_agents.py
|
||||
line-start: 814
|
||||
line-end: 836
|
||||
source-kind: generator-contract
|
||||
|
||||
- id: F-ARCH-COLLABORATION
|
||||
category: architecture
|
||||
key: fan-out-collapse-policy
|
||||
value:
|
||||
family-defaults: {fan-out: 21, collapse: 6, coordination-only: 1}
|
||||
fan-out: 판단·설계·분석 family의 멤버를 격리 실행하고 상위가 원본 보고서를 읽어 종합
|
||||
collapse: 코드·실행 family를 하나의 concrete worker 실행으로 축소
|
||||
wave-max-concurrency: 5
|
||||
heavy-tier-min-independent-verifiers: 3
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/00-role-registry/capability-families.yaml
|
||||
line-start: 14
|
||||
line-end: 34
|
||||
source-kind: family-registry
|
||||
- path: org-os/06-agent-work/execution-policy.yaml
|
||||
line-start: 10
|
||||
line-end: 57
|
||||
source-kind: execution-policy
|
||||
|
||||
- id: F-ARCH-STATE-ARTIFACT
|
||||
category: architecture
|
||||
key: trusted-state-and-artifact-runtime
|
||||
value:
|
||||
workflow-contract-source: org-os/06-agent-work/workflow-contracts.yaml
|
||||
workflow-contract-responsibility: stage graph·role capability·artifact kind·bundle·exit gate
|
||||
canonical-runtime-events: [workflow-events.jsonl, artifact-events.jsonl, acceptance-events.jsonl, human-signoff.jsonl]
|
||||
materialized-view: workflow.yaml
|
||||
artifact-identity: immutable artifact id plus SHA-256 snapshot
|
||||
generated-registry: org-os/06-agent-work/generated/artifact-registry.yaml
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/hooks/state_engine.py
|
||||
line-start: 2
|
||||
line-end: 11
|
||||
source-kind: runtime-implementation
|
||||
- path: .claude/hooks/state_engine.py
|
||||
line-start: 32
|
||||
line-end: 38
|
||||
source-kind: runtime-implementation
|
||||
- path: .claude/hooks/artifact_contract.py
|
||||
line-start: 2
|
||||
line-end: 39
|
||||
source-kind: artifact-validation-implementation
|
||||
- path: .claude/hooks/compile_artifact_registry.py
|
||||
line-start: 2
|
||||
line-end: 7
|
||||
source-kind: artifact-registry-compiler
|
||||
|
||||
- id: F-ARCH-HOOKS
|
||||
category: architecture
|
||||
key: claude-code-hook-wiring
|
||||
value:
|
||||
PreToolUse: guard_tools.py
|
||||
PostToolUse: evidence_ledger.py
|
||||
SubagentStart: subagent_register.py
|
||||
SubagentStop: stop_validate.py
|
||||
Stop: stop_validate.py --main
|
||||
limitation: 강제 동작은 Claude Code가 프로젝트의 .claude/settings.json을 로드할 때 적용된다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/settings.json
|
||||
line-start: 3
|
||||
line-end: 66
|
||||
source-kind: claude-code-configuration
|
||||
- path: CLAUDE.md
|
||||
line-start: 58
|
||||
line-end: 68
|
||||
source-kind: runtime-limit-documentation
|
||||
|
||||
- id: F-ARTIFACT-LAYOUT
|
||||
category: artifacts
|
||||
key: workspace-resolution-and-layout
|
||||
value:
|
||||
resolution-order: [ORGOS_WORKSPACE environment variable, .orgos-workspace pointer]
|
||||
unresolved-behavior: strict operational hooks fail closed with exit 2
|
||||
directories:
|
||||
completion-records: <workspace>/completion-records/<workflow>/
|
||||
evidence: <workspace>/evidence/
|
||||
reports: <workspace>/reports/
|
||||
state: <workspace>/state/
|
||||
slack-inbox: <workspace>/slack-inbox/
|
||||
slack-outbox: <workspace>/slack-outbox/
|
||||
design-system: <workspace>/design-system/
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/hooks/_workspace.py
|
||||
line-start: 1
|
||||
line-end: 15
|
||||
source-kind: runtime-path-implementation
|
||||
- path: .claude/hooks/_workspace.py
|
||||
line-start: 44
|
||||
line-end: 94
|
||||
source-kind: runtime-path-implementation
|
||||
- path: .claude/hooks/_workspace.py
|
||||
line-start: 97
|
||||
line-end: 118
|
||||
source-kind: runtime-path-implementation
|
||||
|
||||
- id: F-ARTIFACT-PROVENANCE
|
||||
category: artifacts
|
||||
key: immutable-reports-and-receipts
|
||||
value:
|
||||
report-path: <workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml
|
||||
report-policy: 새 시도마다 새 파일을 발급하며 기존 report를 덮어쓰지 않는다.
|
||||
acceptance-history: 별도 append-only acceptance event로 관리
|
||||
receipt-ledger: <workspace>/evidence/ledger.jsonl
|
||||
receipt-records: [executed command and exit code, written artifact path and SHA-256]
|
||||
receipt-hook-limitation: workspace를 해석하지 못하면 계측을 생략하고 도구 실행 자체는 막지 않는다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/hooks/new_report.py
|
||||
line-start: 2
|
||||
line-end: 48
|
||||
source-kind: report-path-implementation
|
||||
- path: .claude/hooks/evidence_ledger.py
|
||||
line-start: 2
|
||||
line-end: 22
|
||||
source-kind: evidence-ledger-implementation
|
||||
|
||||
- id: F-PREREQ-TOOLS
|
||||
category: prerequisites
|
||||
key: runtime-tool-versions
|
||||
value:
|
||||
required:
|
||||
python: {minimum: '3.10', tested: '3.12.3'}
|
||||
PyYAML: {minimum: '6.0', tested: '6.0.1', pinned: '6.0.1'}
|
||||
recommended:
|
||||
jsonschema: {minimum: '4.0', tested: '4.10.3', pinned: '4.10.3'}
|
||||
node: {minimum: '18.0', tested: '24.14.0'}
|
||||
d2: {minimum: '0.6', tested: '0.7.1'}
|
||||
optional:
|
||||
marp: {minimum: '3.0', fallback: HTML deck}
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/tool-versions.yaml
|
||||
line-start: 1
|
||||
line-end: 16
|
||||
source-kind: tool-version-configuration
|
||||
- path: requirements.txt
|
||||
line-start: 1
|
||||
line-end: 7
|
||||
source-kind: dependency-manifest
|
||||
|
||||
- id: F-PREREQ-UI
|
||||
category: prerequisites
|
||||
key: design-system-preview-tools
|
||||
value:
|
||||
required-for-full-render-check: [detected package manager and project build command, Google Chrome or Chromium-compatible executable]
|
||||
checked-properties: [non-empty mounted DOM, generated JavaScript bundle, CSS contrast, keyboard focus visibility, responsive viewport screenshots]
|
||||
limitation: render health를 검사하지만 시각적 차별성·타이포·비례·spacing의 미학 품질은 판정하지 않는다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/hooks/preview_ui.py
|
||||
line-start: 2
|
||||
line-end: 41
|
||||
source-kind: UI-verification-implementation
|
||||
- path: .claude/hooks/preview_ui.py
|
||||
line-start: 54
|
||||
line-end: 79
|
||||
source-kind: UI-verification-implementation
|
||||
- path: .claude/hooks/preview_ui.py
|
||||
line-start: 541
|
||||
line-end: 541
|
||||
source-kind: UI-verification-limitation
|
||||
|
||||
- id: F-VERIFY-SUITE
|
||||
category: verification
|
||||
key: full-test-runner
|
||||
value:
|
||||
entrypoint: .claude/tests/run_all.py
|
||||
preflight: [compile_artifact_registry.py --check, doctor.py, lint_refs.py]
|
||||
test-discovery: .claude/tests/test_*.py
|
||||
execution: suites run sequentially with a per-suite timeout
|
||||
failure-contract: any failed or timed-out suite produces exit 1
|
||||
no-preflight-option: --no-preflight
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .claude/tests/run_all.py
|
||||
line-start: 2
|
||||
line-end: 11
|
||||
source-kind: test-runner
|
||||
- path: .claude/tests/run_all.py
|
||||
line-start: 23
|
||||
line-end: 30
|
||||
source-kind: test-runner
|
||||
- path: .claude/tests/run_all.py
|
||||
line-start: 53
|
||||
line-end: 80
|
||||
source-kind: test-runner
|
||||
|
||||
- id: F-CI-WORKFLOW
|
||||
category: verification
|
||||
key: github-actions-ci
|
||||
value:
|
||||
triggers: {push: [main, fix/**, feat/**], pull-request: [main]}
|
||||
environment: {python: '3.12', node: '20', workspace: _sandbox}
|
||||
steps: [install pinned Python dependencies, attempt D2 0.7.1 installation, run doctor, run lint_refs, run gen_agents --check, run all tests with --no-preflight]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .github/workflows/ci.yml
|
||||
line-start: 1
|
||||
line-end: 46
|
||||
source-kind: CI-workflow
|
||||
|
||||
- id: F-MATURITY-CONTEXT
|
||||
category: limitation
|
||||
key: current-company-context-state
|
||||
value:
|
||||
company-context-status: template
|
||||
founder-context-status: template
|
||||
validation-stage: pre-traction
|
||||
implication: 회사 수립 경로는 사람이 founder context를 채우고 venture-bootstrap을 거쳐야 한다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: org-os/01-company/company-context.yaml
|
||||
line-start: 13
|
||||
line-end: 51
|
||||
source-kind: company-context
|
||||
- path: org-os/01-company/founder-context.yaml
|
||||
line-start: 1
|
||||
line-end: 17
|
||||
source-kind: company-context-input
|
||||
|
||||
- id: F-MATURITY-BENCHMARK
|
||||
category: limitation
|
||||
key: benchmark-evidence-status
|
||||
value:
|
||||
golden-tasks: 13
|
||||
executed-samples: {plain: 2, harness: 2}
|
||||
measured-dimensions: 3
|
||||
unexecuted-dimensions: 8
|
||||
observed-result:
|
||||
first-pass-acceptance: tie
|
||||
tests-pass-rate: tie
|
||||
unnecessary-change-lines: tie
|
||||
weighted-composite-delta: 0
|
||||
conclusion: 현재 표본은 하네스의 품질 우위를 입증하지 않는다.
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: benchmark/BENCHMARK.md
|
||||
line-start: 1
|
||||
line-end: 20
|
||||
source-kind: generated-benchmark-report
|
||||
- path: benchmark/runs.jsonl
|
||||
line-start: 1
|
||||
line-end: 4
|
||||
source-kind: benchmark-run-ledger
|
||||
|
||||
commands:
|
||||
- id: CMD-1
|
||||
command: pip install -r requirements.txt
|
||||
cwd: .
|
||||
source: {path: .github/workflows/ci.yml, line-start: 30, line-end: 31, source-kind: CI-workflow}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-2
|
||||
command: python3 .claude/tests/run_all.py
|
||||
cwd: .
|
||||
source: {path: .claude/tests/run_all.py, line-start: 7, line-end: 9, source-kind: test-runner-usage}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-3
|
||||
command: python3 .claude/hooks/doctor.py
|
||||
cwd: .
|
||||
source: {path: .github/workflows/ci.yml, line-start: 36, line-end: 37, source-kind: CI-workflow}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [유효한 ORGOS_WORKSPACE 또는 .orgos-workspace 포인터가 필요함., Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-4
|
||||
command: python3 .claude/hooks/lint_refs.py
|
||||
cwd: .
|
||||
source: {path: .github/workflows/ci.yml, line-start: 39, line-end: 40, source-kind: CI-workflow}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-5
|
||||
command: python3 .claude/hooks/compile_artifact_registry.py --check
|
||||
cwd: .
|
||||
source: {path: .claude/tests/run_all.py, line-start: 57, line-end: 60, source-kind: test-runner-preflight}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-observed-invocation
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-6
|
||||
command: python3 .claude/hooks/gen_agents.py --check
|
||||
cwd: .
|
||||
source: {path: .github/workflows/ci.yml, line-start: 42, line-end: 43, source-kind: CI-workflow}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-declared
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-7
|
||||
command: python3 .claude/hooks/benchmark.py list
|
||||
cwd: .
|
||||
source: {path: .claude/hooks/benchmark.py, line-start: 11, line-end: 15, source-kind: benchmark-implementation}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-observed-invocation
|
||||
limitations: [Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-8
|
||||
command: python3 .claude/hooks/benchmark.py compare
|
||||
cwd: .
|
||||
source: {path: .claude/hooks/benchmark.py, line-start: 16, line-end: 19, source-kind: benchmark-implementation}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-observed-invocation
|
||||
limitations: [기존 benchmark run ledger를 비교하며 새 표본을 생성하지 않음., Repository Evidence Analyst가 실행하지 않음.]
|
||||
|
||||
- id: CMD-9
|
||||
command: python3 .claude/hooks/benchmark.py run --task GT-01 --arm plain --execute
|
||||
cwd: .
|
||||
source: {path: .claude/hooks/benchmark.py, line-start: 11, line-end: 15, source-kind: benchmark-implementation}
|
||||
verification:
|
||||
status: discovered
|
||||
method: static extraction
|
||||
level: repository-observed-invocation
|
||||
limitations: [Claude CLI와 외부 실행 예산이 필요할 수 있음., Repository Evidence Analyst가 실행하지 않음.]
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"git-sha": "00db337cfb3a22feb0b4d8529f23d72067f9ce16",
|
||||
"dirty": true,
|
||||
"diff-hash": "sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64",
|
||||
"scanned-at": null,
|
||||
"file-count": 893
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
schema-version: 1
|
||||
verdict: PASS
|
||||
score: 93
|
||||
scores:
|
||||
project-specificity:
|
||||
score: 5
|
||||
evidence:
|
||||
- overview·operating-model·architecture가 workflow contract, hook, 역할 registry, workspace 산출물 체계를 구체적으로 설명한다.
|
||||
- F-IDENTITY-CORE, F-ARCH-STATE-ARTIFACT, F-ARCH-HOOKS, F-ARCH-ROLE-MODEL
|
||||
reader-journey:
|
||||
score: 4
|
||||
evidence:
|
||||
- 개요 → 운영 모델 → 시작하기 → workflow 선택 → 구조 → 검증 → 한계 → 정본 링크 순서가 brief의 reader journey와 일치한다.
|
||||
- 30초 독자에게 대상 독자는 다소 암시적이지만 프로젝트 정체성과 용도는 첫 두 문단에서 파악된다.
|
||||
technical-explanation:
|
||||
score: 5
|
||||
evidence:
|
||||
- workflow-contracts, state_engine, 사람 gate, hook event, append-only event와 SHA-256 provenance의 관계가 사실 범위 안에서 설명된다.
|
||||
- F-WORKFLOW-CASCADE, F-ARCH-STATE-ARTIFACT, F-ARTIFACT-PROVENANCE
|
||||
task-usability:
|
||||
score: 4
|
||||
evidence:
|
||||
- 의존성 설치, ORGOS_WORKSPACE 지정, doctor, 첫 slash command와 목적별 검증 명령이 복사 가능한 형태로 제공된다.
|
||||
- verification.json은 명령 5개 중 4개를 정적 확인하고 pip 설치 1개를 manual-required로 명시한다.
|
||||
prose-clarity:
|
||||
score: 5
|
||||
evidence:
|
||||
- ko-KR 기술 문체가 일관되고 표·목록·짧은 문단으로 긴 문서의 탐색성이 유지된다.
|
||||
- 정적 확인과 실제 실행 성공을 명시적으로 구분해 과장된 성공 표현을 피한다.
|
||||
visual-judgment:
|
||||
score: 5
|
||||
evidence:
|
||||
- 유일한 Mermaid 흐름도가 cascade stage와 두 사람 결정 경계를 직접 설명하며 장식적 시각물을 추가하지 않는다.
|
||||
- visual-plan의 must-show, relationships, emphasize, avoid 요구를 충족한다.
|
||||
hard-gates:
|
||||
passed: true
|
||||
failures: []
|
||||
reader-simulations:
|
||||
30-seconds:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- 제목과 첫 두 문단에서 Claude Code용 파일 기반 에이전트 운영 하네스라는 정체성, 존재 이유, 적용 업무를 파악할 수 있다.
|
||||
5-minutes:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- 시작하기, workflow 선택표, 저장소 구조, 검증 수준, 현재 한계를 통해 가치·실행·구조·제약을 모두 확인할 수 있다.
|
||||
contributor:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- architecture 표가 정본과 생성물을 구분하고, verification 표가 검사 명령을 제공하며, reference가 상세 계약과 docs로 연결한다.
|
||||
findings: []
|
||||
@@ -0,0 +1,10 @@
|
||||
# README 품질 검토
|
||||
|
||||
- 판정: **PASS**
|
||||
- 가중 점수: **93/100**
|
||||
- Hard gate: 모두 통과
|
||||
- 독자 시뮬레이션: 30초·5분·기여자 모두 통과
|
||||
|
||||
후보 문서는 Org OS의 workflow 계약, 사람 승인 경계, hook, workspace 산출물과 검증 체계를 저장소 고유 정보로 설명합니다. 정보 흐름과 한국어 가독성이 좋고, 기여자가 정본·생성물·검증 경로를 구분할 수 있습니다.
|
||||
|
||||
검증 수준도 정직합니다. 현재 증거는 정적 검증이며 대상 테스트 suite를 실행한 결과가 아닙니다. `pip install -r requirements.txt`는 manual-required이고, 나머지 문서 명령은 스크립트와 경로의 정적 존재만 확인됐다는 제한을 README가 명시합니다.
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"run-id": "20260717-rewrite",
|
||||
"repo-id": "company-haness",
|
||||
"mode": "bootstrap",
|
||||
"target-repository": "/home/donghyeon/workspace/ai-tool/company-haness",
|
||||
"harness-version": "0.1.0",
|
||||
"started-at": null,
|
||||
"tool-adapter": "codex",
|
||||
"input-hashes": {}
|
||||
}
|
||||
@@ -0,0 +1,283 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"mode": "bootstrap",
|
||||
"current": "APPLIED",
|
||||
"history": [
|
||||
{
|
||||
"state": "INITIALIZED"
|
||||
},
|
||||
{
|
||||
"state": "INPUT_CAPTURED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "request",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "REPOSITORY_SNAPSHOTTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "snapshot",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"diff-hash": "sha256:1eaa580e67e33d16a6115eb8f66fd034446436fb8f3bf70842ee9fd91b60ca64"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "FACTS_EXTRACTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "facts",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"fact_ids": [
|
||||
"F-IDENTITY-CORE",
|
||||
"F-WORKFLOW-ENTRY",
|
||||
"F-WORKFLOW-CASCADE",
|
||||
"F-WORKFLOW-WAVE-LIGHT",
|
||||
"F-WORKFLOW-VENTURE",
|
||||
"F-WORKFLOW-SPECIALIZED",
|
||||
"F-ARCH-DIRECTORIES",
|
||||
"F-ARCH-ROLE-MODEL",
|
||||
"F-ARCH-COLLABORATION",
|
||||
"F-ARCH-STATE-ARTIFACT",
|
||||
"F-ARCH-HOOKS",
|
||||
"F-ARTIFACT-LAYOUT",
|
||||
"F-ARTIFACT-PROVENANCE",
|
||||
"F-PREREQ-TOOLS",
|
||||
"F-PREREQ-UI",
|
||||
"F-VERIFY-SUITE",
|
||||
"F-CI-WORKFLOW",
|
||||
"F-MATURITY-CONTEXT",
|
||||
"F-MATURITY-BENCHMARK"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "PROJECT_PROFILED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "profile",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"profile": "generic"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "README_PLANNED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "brief",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
},
|
||||
{
|
||||
"name": "outline",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"section_ids": [
|
||||
"overview",
|
||||
"operating-model",
|
||||
"quick-start",
|
||||
"workflows",
|
||||
"architecture",
|
||||
"artifacts",
|
||||
"verification",
|
||||
"limitations",
|
||||
"reference"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "README_DRAFTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "conformance",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"sections": [
|
||||
"overview",
|
||||
"operating-model",
|
||||
"quick-start",
|
||||
"workflows",
|
||||
"architecture",
|
||||
"artifacts",
|
||||
"verification",
|
||||
"limitations",
|
||||
"reference"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "claim_map",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"claims": [
|
||||
"C-IDENTITY",
|
||||
"C-VALUE",
|
||||
"C-ENTRY-MODEL",
|
||||
"C-CONTRACT-MODEL",
|
||||
"C-COLLAB-MODEL",
|
||||
"C-HUMAN-BOUNDARY",
|
||||
"C-PROVENANCE-MODEL",
|
||||
"C-HOOK-MODEL",
|
||||
"C-PREREQUISITES",
|
||||
"C-INSTALL-COMMAND",
|
||||
"C-WORKSPACE-RESOLUTION",
|
||||
"C-DOCTOR-COMMAND",
|
||||
"C-DOCTOR-SCOPE",
|
||||
"C-FIRST-COMMAND",
|
||||
"C-WORKFLOW-CASCADE",
|
||||
"C-WORKFLOW-WAVE",
|
||||
"C-WORKFLOW-LIGHT",
|
||||
"C-WORKFLOW-VENTURE",
|
||||
"C-SPECIALIZED-WORKFLOWS",
|
||||
"C-CASCADE-VISUAL",
|
||||
"C-ARCH-SOURCE",
|
||||
"C-DIRECTORY-MAP",
|
||||
"C-ROLE-MODEL",
|
||||
"C-GENERATED-AGENTS",
|
||||
"C-WORKSPACE-LAYOUT",
|
||||
"C-REPORT-RECEIPTS",
|
||||
"C-CMD-DOCTOR",
|
||||
"C-CMD-AGENTS",
|
||||
"C-CMD-TESTS",
|
||||
"C-CMD-BENCHMARK",
|
||||
"C-TEST-RUNNER",
|
||||
"C-CI",
|
||||
"C-BENCHMARK-STATUS",
|
||||
"C-LIMIT-CONTEXT",
|
||||
"C-LIMIT-HOOKS",
|
||||
"C-LIMIT-UI",
|
||||
"C-LIMIT-TOOLS",
|
||||
"C-LIMIT-EVIDENCE"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "VISUALS_PLANNED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "visual_plan",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"visuals": [
|
||||
"cascade-flow"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "STRUCTURALLY_VALIDATED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "github_markdown",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "TECHNICALLY_VERIFIED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "verify",
|
||||
"ok": true,
|
||||
"warnings": [
|
||||
"manual verification required: pip install -r requirements.txt (unsupported-static-verifier)"
|
||||
],
|
||||
"data": {
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 5,
|
||||
"verified": 4,
|
||||
"manual-required": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 15,
|
||||
"verified": 15,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: pip install -r requirements.txt (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "secret_scan",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "QUALITY_REVIEWED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "review",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"verdict": "PASS",
|
||||
"score": 93,
|
||||
"findings": []
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "READY_FOR_APPLY",
|
||||
"gates": []
|
||||
},
|
||||
{
|
||||
"state": "APPLIED",
|
||||
"gates": []
|
||||
}
|
||||
],
|
||||
"rework": {
|
||||
"iterations": 0,
|
||||
"findings": {}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 5,
|
||||
"verified": 4,
|
||||
"manual-required": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 15,
|
||||
"verified": 15,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: pip install -r requirements.txt (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
schema-version: 1
|
||||
visuals:
|
||||
- id: cascade-flow
|
||||
section: workflows
|
||||
type: sequence-diagram
|
||||
purpose: intake부터 released까지의 공식 cascade stage와 두 사람 결정 경계를 한 화면에 설명한다.
|
||||
placeholder-text: Mermaid flowchart로 stage별 slash command와 방향 수용·release 승인 gate를 순서대로 표시한다.
|
||||
must-show:
|
||||
- intake부터 acceptance까지의 여덟 stage
|
||||
- 각 stage의 slash command
|
||||
- decide 이후 사람 방향 수용
|
||||
- acceptance 이후 사람 release 승인
|
||||
- released 종단
|
||||
relationships:
|
||||
- intake -> discovery -> decide
|
||||
- decide -> 사람 방향 수용 -> design
|
||||
- design -> spec -> build -> verification -> acceptance
|
||||
- acceptance -> 사람 release 승인 -> released
|
||||
emphasize:
|
||||
- 사람 gate에서는 자동 완주하지 않음
|
||||
- 화살표는 workflow stage 순서임
|
||||
avoid:
|
||||
- wave와 light 경로를 같은 흐름에 섞기
|
||||
- artifact 세부 필드를 diagram에 모두 넣기
|
||||
- 사람 승인을 AI 자동 승인처럼 표현하기
|
||||
placement:
|
||||
after-section-id: workflows
|
||||
accessibility:
|
||||
alt-text: ceo-intake에서 ground, decide, 사람 방향 수용, design, spec, build, review-output, release-check, 사람 release 승인을 거쳐 released에 도달하는 cascade 순서
|
||||
production:
|
||||
format: mermaid
|
||||
status: embedded
|
||||
@@ -0,0 +1,651 @@
|
||||
# Org OS 하네스
|
||||
|
||||
<!-- section-id: overview -->
|
||||
## 무엇을 운영하는 저장소인가
|
||||
|
||||
Org OS 하네스는 회사 운영을 AI 에이전트에게 분담시키는 파일 기반 운영체계입니다. 역할·워크플로·산출물 계약을 파일로 고정하고 `org-os/` 디렉터리를 명세와 상태의 단일 원천으로 삼습니다. <!-- claim-id: C-IDENTITY -->
|
||||
|
||||
적용 범위는 개발에 한정되지 않습니다. 제품·개발 작업과 GTM·수익 같은 비즈니스 작업을 같은 계약 위에서 함께 다룹니다. <!-- claim-id: C-SCOPE -->
|
||||
|
||||
실행 런타임은 Claude Code 하나입니다. subagent·project command·hook이 `.claude` 어댑터 한 곳에 배선돼 있고, 다른 에이전트 런타임용 어댑터 디렉터리는 저장소에 없습니다. <!-- claim-id: C-RUNTIME-COUPLING -->
|
||||
|
||||
| 독자 | 이 문서에서 얻는 결과 |
|
||||
|---|---|
|
||||
| 저장소를 처음 쓰는 운영자·개발자 | 최소 설치 절차, 첫 실행 명령, 작업에 맞는 workflow 선택 기준 |
|
||||
| 하네스에 기여하려는 개발자 | 원본과 생성물의 경계, 재생성·재검증 명령 순서 |
|
||||
| 워크플로와 산출물 계약을 검토하는 기술 리더 | 계약 정본 위치, 검증 수준의 등급, 현재 근거의 한계 |
|
||||
|
||||
읽기 전에 범위를 하나 확인해 주십시오. 이 문서에 실린 검증 결과는 커밋된 HEAD가 아니라 2026-07-20 13:36 시점의 워킹 트리를 대상으로 합니다. <!-- claim-id: C-SCOPE-WORKINGTREE -->
|
||||
|
||||
<!-- section-id: operating-model -->
|
||||
## 운영 원리
|
||||
|
||||
이 하네스의 운영 원리는 여섯 가지입니다. 아래 여섯 가지는 계약 파일이 선언한 규칙이며, 이 분석에서 런타임 강제를 실행해 확인하지는 않았습니다. <!-- claim-id: C-RULES-DECLARED -->
|
||||
|
||||
1. **계약이 실행보다 먼저입니다.** `org-os/06-agent-work/workflow-contracts.yaml` 한 파일이 단계 그래프, 역할 `capability`, `artifact kind`, `bundle`, `exit gate`를 함께 정의합니다. <!-- claim-id: C-CONTRACT-GRAPH -->
|
||||
2. **상태 런타임은 호출자를 믿지 않습니다.** 호출자가 넘긴 `gate fact`, `artifact kind`, `option count`, `evidence grade`를 그대로 받지 않고 제출된 불변 바이트에서 다시 파생합니다. <!-- claim-id: C-TRUST-RULE -->
|
||||
3. **협업 형태는 산출물 종류가 결정합니다.** 코드·실행 산출물을 만드는 `family`는 `collapse`로 묶고, 판단·설계·분석·수익 산출물을 만드는 `family`는 `fan-out`으로 나눕니다. <!-- claim-id: C-FANOUT-RULE -->
|
||||
4. **`fan-out`은 메인 세션만 주도합니다.** Orchestrator가 `fan-out`을 몰고 가며 `subagent`는 다른 `subagent`를 호출하지 못합니다. <!-- claim-id: C-ORCH-ONLY -->
|
||||
5. **근거 없는 주장은 통과하지 못합니다.** 보고서 evidence 등급은 `E0`부터 `E5`까지이고, `E4`와 `E5` 주장은 `evidence ledger`의 실제 `receipt`와 대조해 `receipt`가 없으면 막습니다. <!-- claim-id: C-EVIDENCE-GATE -->
|
||||
6. **도구 경계는 두 겹입니다.** 1차 경계는 Claude Code 네이티브 permission 시스템이고, `guard_tools.py`는 심층 방어(defense-in-depth) 목적의 2차 방어선입니다. <!-- claim-id: C-BOUNDARY-LAYERS -->
|
||||
|
||||
종합과 결정 지점에서 상위 역할은 하위 `.report.yaml` 전문을 읽습니다. 요약본으로 대체하는 것을 금지합니다. <!-- claim-id: C-REHYDRATION -->
|
||||
|
||||
검증자 패밀리는 자기 패밀리가 작성한 산출물을 검증하지 못합니다. heavy tier 병렬 감사는 독립 검증자를 최소 3명 요구하고, 다수가 반박하면 중단합니다. <!-- claim-id: C-VERIFIER-INDEPENDENCE -->
|
||||
|
||||
<!-- section-id: quick-start -->
|
||||
## 최소 사용 절차
|
||||
|
||||
의존성 설치, workspace 지정, 배선 확인, 첫 명령 순서로 진행합니다. 명령마다 검증 수준을 함께 적었습니다. 등급의 뜻은 아래 [검증 수준의 등급](#검증-수준의-등급)에서 정의합니다.
|
||||
|
||||
<!-- section-id: prerequisites -->
|
||||
### 1. 필수 도구와 선택 도구
|
||||
|
||||
| 구분 | 도구 | 최소 버전 | 확인된 버전 | 없을 때 |
|
||||
|---|---|---|---|---|
|
||||
| 필수 | Python | 3.10 | 3.12.3 | 훅·검증기·테스트 런타임이 동작하지 않음 |
|
||||
| 필수 | PyYAML | 6.0 | 6.0.1 | SSOT YAML 파싱 불가 |
|
||||
| 권장 | jsonschema | 4.0 | 4.10.3 | 최소검증 폴백으로 내려감 |
|
||||
| 권장 | Node.js | 18.0 | 24.14.0 | design-system 빌드와 `preview_ui.py` 경로가 막힘 |
|
||||
| 권장 | D2 | 0.6 | 0.7.1 | diagram-as-code 실물 렌더 불가 |
|
||||
| 선택 | Marp | 3.0 | 미설치 | consult 덱을 HTML 대체 경로로 냄 |
|
||||
|
||||
필수 도구가 없으면 하네스 자체가 돌지 않고, 권장·선택 도구가 없으면 해당 기능 경로만 줄어듭니다. <!-- claim-id: C-PREREQ-SPLIT -->
|
||||
|
||||
버전 대조는 `.claude/hooks/doctor.py`가 맡습니다. `.claude/tool-versions.yaml`을 읽어 런타임에 설치된 버전과 맞춰 봅니다. <!-- claim-id: C-PREREQ-VERSION-CHECK -->
|
||||
|
||||
저장소가 선언한 설치 명령은 하나이며 로컬과 CI가 같습니다. <!-- claim-id: C-INSTALL -->
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
매니페스트는 `PyYAML==6.0.1`과 `jsonschema==4.10.3` 외에는 Python 표준 라이브러리만 쓴다고 선언합니다. <!-- claim-id: C-INSTALL-DEPS -->
|
||||
|
||||
이 설치 명령은 파일에서 확인만 했고 이번 분석에서 실행하지 않았습니다(검증 수준: 저장소가 선언한 명령). <!-- claim-id: C-INSTALL-LEVEL -->
|
||||
|
||||
<!-- section-id: workspace-setup -->
|
||||
### 2. workspace 지정
|
||||
|
||||
산출물이 쓰일 위치는 `ORGOS_WORKSPACE` 환경변수를 먼저 보고, 없으면 `.orgos-workspace` 포인터 파일의 첫 유효 줄을 씁니다. 주석과 빈 줄은 건너뜁니다. <!-- claim-id: C-WS-ORDER -->
|
||||
|
||||
값이 상대 경로면 저장소 루트를 기준으로 해석하고, 절대 경로면 그대로 씁니다. <!-- claim-id: C-WS-PATHRULE -->
|
||||
|
||||
둘 다 해석되지 않으면 `WorkspaceNotSetError`가 납니다. `require_workspace(advisory=False)`를 쓰는 운영 훅은 exit 2로 fail-closed 종료합니다. <!-- claim-id: C-WS-FAILCLOSED -->
|
||||
|
||||
`require_workspace(advisory=True)`를 쓰는 계측 훅인 `evidence_ledger.py`는 경고만 남기고 `None`을 돌려주며 도구 실행을 막지 않습니다. <!-- claim-id: C-WS-ADVISORY -->
|
||||
|
||||
테스트와 CI는 명령마다 `ORGOS_WORKSPACE=_sandbox`를 명시하는 관례를 따릅니다. <!-- claim-id: C-WS-SANDBOX -->
|
||||
|
||||
```bash
|
||||
export ORGOS_WORKSPACE=_sandbox
|
||||
```
|
||||
|
||||
주의할 점이 있습니다. 현재 워킹 트리의 `.orgos-workspace`는 `hyeonworks`로 채워져 있어, 환경변수를 지정하지 않아도 포인터가 해석되고 fail-closed가 걸리지 않습니다. <!-- claim-id: C-WS-POINTER-FILLED -->
|
||||
|
||||
<!-- section-id: first-command -->
|
||||
### 3. 배선 확인과 첫 명령
|
||||
|
||||
설치가 끝나면 배선부터 봅니다. `.claude/hooks/doctor.py`가 14개 영역을 점검하고 한 줄 판정으로 요약합니다. <!-- claim-id: C-DOCTOR-SCOPE -->
|
||||
|
||||
```bash
|
||||
CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/hooks/doctor.py
|
||||
```
|
||||
|
||||
12:03 실행에서는 `35 OK · 0 WARN · 0 FAIL`과 verdict `OK`, exit 0이 나왔습니다. 이후 저장소가 바뀌었으므로 현재 트리의 판정은 확인되지 않았습니다. <!-- claim-id: C-DOCTOR-RUN -->
|
||||
|
||||
배선이 정상이면 Claude Code 세션에서 `/ceo-intake`로 새 작업을 엽니다. 이 명령은 `cascade`, `wave`, `light`, `venture-bootstrap` 네 plan의 공통 진입점입니다. <!-- claim-id: C-ENTRY-COMMON -->
|
||||
|
||||
`/ceo-intake`는 `OPS-ORCH` 역할이 실행하고 `EXEC-CEO` 역할이 작성하며, `decision-brief`와 `workload-profile`을 만듭니다. <!-- claim-id: C-ENTRY-ROLES -->
|
||||
|
||||
이 단계에서 mode(`divergent` 또는 `converge`)와 tier(`light`, `standard`, `heavy`)를 선언합니다. <!-- claim-id: C-ENTRY-DECLARE -->
|
||||
|
||||
진입 단계의 exit gate는 세 조건을 요구합니다. `decision-brief-present`, `workload-profile-present`, `company-context-ready`입니다. <!-- claim-id: C-ENTRY-GATE -->
|
||||
|
||||
<!-- section-id: workflows -->
|
||||
## 작업에 맞는 workflow 고르기
|
||||
|
||||
선언된 workflow plan은 `cascade`, `wave`, `light`, `venture-bootstrap`, `design-direction` 다섯 개입니다. <!-- claim-id: C-PLAN-LIST -->
|
||||
|
||||
그래프 정본은 `org-os/06-agent-work/workflow-contracts.yaml`입니다. 같은 디렉터리의 `execution-plans.yaml`은 호환·문서용 mirror이며 런타임 정본이 아닙니다. <!-- claim-id: C-PLAN-MIRROR -->
|
||||
|
||||
slash command는 모두 18개입니다. 그중 `/ceo-intake` 하나가 앞의 네 plan이 공유하는 진입점이고, `design-direction`은 `cascade`에 종속된 하위 워크플로라 자기 진입점을 씁니다. <!-- claim-id: C-COMMAND-COUNT -->
|
||||
|
||||
| plan | 고르는 조건 | 종단 상태 | 기본 tier |
|
||||
|---|---|---|---|
|
||||
| `cascade` | 탐색·결정·설계·명세·구현·검증·수용을 모두 거치는 작업 | `released` | `standard` |
|
||||
| `wave` | 계획을 세운 뒤 실행 단계를 반복하는 작업 | `released` | `standard` |
|
||||
| `light` | 저위험·two-way-door·single-role이며 고객·매출·보안 영향이 없는 작업 | `acceptance` | `light` |
|
||||
| `venture-bootstrap` | 회사 문맥을 처음 세우는 작업 | `bootstrap-complete` | 정의 없음 |
|
||||
| `design-direction` | 제품 결정에 종속된 디자인 방향 확정 | `design-direction-approved` | 정의 없음 |
|
||||
|
||||
사람 승인 지점은 plan마다 다른 토큰으로 표시됩니다. `human-gate`는 `cascade`와 `wave`의 `acceptance` 단계에만 나오고, 두 plan의 exit gate 리스트는 문자열이 같습니다. <!-- claim-id: C-HUMAN-POINTS -->
|
||||
|
||||
`venture-bootstrap`은 `venture-decision` 단계에서 `human-acceptance-receipt-present`라는 별도 토큰을 씁니다. `light`와 `design-direction`의 exit gate에는 `human-` 리터럴이 없습니다. <!-- claim-id: C-HUMAN-TOKENS -->
|
||||
|
||||
`/run-cascade` 드라이버는 `cascade`를 순회하다 `human-gate` 지점에서 멈춥니다. <!-- claim-id: C-RUN-CASCADE-STOP -->
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
entry["/ceo-intake<br/>mode · tier 선언"] --> pick{"작업 성격에 따라<br/>plan 선택"}
|
||||
|
||||
subgraph CAS["cascade · 기본 tier standard"]
|
||||
direction TB
|
||||
c1["intake<br/>ceo-intake"] --> c2["discovery<br/>ground"]
|
||||
c2 --> c3["decide<br/>decide"]
|
||||
c3 --> c4["design<br/>design"]
|
||||
c4 --> c5["spec<br/>spec"]
|
||||
c5 --> c6["build<br/>build"]
|
||||
c6 --> c7["verification<br/>review-output"]
|
||||
c7 -->|quality-gate-passed| c8["acceptance<br/>release-check"]
|
||||
c7 -.->|quality-gate-failed| c6
|
||||
c8 --> cg{{"사람 승인 필요<br/>human-gate"}}
|
||||
cg --> c9(["released"])
|
||||
end
|
||||
|
||||
subgraph WAV["wave · 기본 tier standard"]
|
||||
direction TB
|
||||
w1["intake<br/>ceo-intake"] --> w2["plan<br/>plan-wave"]
|
||||
w2 --> w3["run<br/>run-wave"]
|
||||
w3 --> w4["verification<br/>review-output"]
|
||||
w4 -->|quality-gate-passed| w5["acceptance<br/>release-check"]
|
||||
w5 --> wg{{"사람 승인 필요<br/>human-gate"}}
|
||||
wg --> w6(["released"])
|
||||
w3 -.->|loop-stage| w3
|
||||
end
|
||||
|
||||
subgraph LGT["light · 기본 tier light · 저위험·two-way-door·single-role"]
|
||||
direction TB
|
||||
l1["intake<br/>ceo-intake"] --> l2["run<br/>run-wave"]
|
||||
l2 --> l3["verification<br/>review-output"]
|
||||
l3 -->|quality-gate-passed| l4(["acceptance<br/>terminal-stage · released 전이 없음"])
|
||||
end
|
||||
|
||||
subgraph VEN["venture-bootstrap"]
|
||||
direction TB
|
||||
v1["intake<br/>ceo-intake --plan venture-bootstrap"] --> v2["founder-setup"]
|
||||
v2 --> vh[/"사람 입력 필요<br/>founder-context.yaml: filled"/]
|
||||
vh --> v3["opportunity-discovery"]
|
||||
v3 --> v4["venture-validation<br/>venture-validate"]
|
||||
v4 --> v5["venture-decision"]
|
||||
v5 --> vg{{"사람 승인 필요<br/>human-acceptance-receipt-present"}}
|
||||
vg --> v6["company-context-commit<br/>company-bootstrap"]
|
||||
v6 --> v7(["bootstrap-complete<br/>company-context: provisional"])
|
||||
end
|
||||
|
||||
subgraph DDR["design-direction · child workflow · 진입 명령 design-direction"]
|
||||
direction TB
|
||||
d1["design-direction-intake"] --> d2["design-direction-discovery"]
|
||||
d2 --> d3["design-direction-divergence"]
|
||||
d3 --> d4["design-direction-decision"]
|
||||
d4 --> d5["design-direction-prototype"]
|
||||
d5 --> d6["design-direction-critique"]
|
||||
d6 --> d7["design-direction-finalize"]
|
||||
d7 --> d8(["design-direction-approved"])
|
||||
d6 -.->|critique-revision-requested| d5
|
||||
d6 -.->|concept-rejection-recorded| d3
|
||||
end
|
||||
|
||||
pick -->|cascade| c1
|
||||
pick -->|wave| w1
|
||||
pick -->|light| l1
|
||||
pick -->|venture-bootstrap| v1
|
||||
CAS -. "parent-binding" .-> DDR
|
||||
|
||||
classDef human fill:#fff3cd,stroke:#b8860b,stroke-width:2px,color:#000
|
||||
classDef term fill:#e8f5e9,stroke:#2e7d32,color:#000
|
||||
class cg,wg,vg,vh human
|
||||
class c9,w6,l4,v7,d8 term
|
||||
```
|
||||
|
||||
<!-- visual-id: workflow-selection -->
|
||||
|
||||
<!-- section-id: workflow-cascade -->
|
||||
### cascade — 표준 전체 경로
|
||||
|
||||
| 순서 | stage | 명령 | 산출물 |
|
||||
|---|---|---|---|
|
||||
| 1 | `intake` | `/ceo-intake` | `decision-brief`, `workload-profile` |
|
||||
| 2 | `discovery` | `/ground` | `grounding-package` |
|
||||
| 3 | `decide` | `/decide` | `executive-decision-packet` |
|
||||
| 4 | `design` | `/design` | `design-bundle` |
|
||||
| 5 | `spec` | `/spec` | `spec-bundle` |
|
||||
| 6 | `build` | `/build` | `completion-record` |
|
||||
| 7 | `verification` | `/review-output` | `quality-gate-review` |
|
||||
| 8 | `acceptance` | `/release-check` | `release-decision` |
|
||||
| 9 | `released` | 없음 | 없음 |
|
||||
|
||||
순서에서 주의할 점은 근거 탐색인 `discovery`가 `decide`보다 앞선다는 것입니다. <!-- claim-id: C-CASCADE-ORDER -->
|
||||
|
||||
`design`과 `spec`의 산출물은 고정 목록이 아니라 dynamic bundle입니다. <!-- claim-id: C-CASCADE-BUNDLE -->
|
||||
|
||||
기본 tier는 `standard`이고 종단 단계는 `released`입니다. <!-- claim-id: C-CASCADE-TIER -->
|
||||
|
||||
`verification` 단계의 exit gate는 `quality-gate-passed`와 `blocker-open-false`입니다. <!-- claim-id: C-CASCADE-VERIFY-GATE -->
|
||||
|
||||
`released` 진입 exit gate는 `release-approved`, `no-unresolved-critical-risks`, `human-gate` 세 조건입니다. <!-- claim-id: C-CASCADE-EXIT -->
|
||||
|
||||
품질 게이트가 실패하면 `verification`에서 `build`로 되돌아가는 재작업 전이가 있습니다. 이 전이의 필요 조건은 `quality-gate-failed`입니다. <!-- claim-id: C-CASCADE-REWORK -->
|
||||
|
||||
<!-- section-id: workflow-wave-light -->
|
||||
### `wave`와 `light` — 축약 경로
|
||||
|
||||
`wave`는 `intake` → `plan` → `run` → `verification` → `acceptance` → `released` 여섯 단계를 거치고, `run`이 반복 단계입니다. <!-- claim-id: C-WAVE-STAGES -->
|
||||
|
||||
`wave`가 쓰는 명령은 `/ceo-intake`, `/plan-wave`, `/run-wave`, `/review-output`, `/release-check`입니다. <!-- claim-id: C-WAVE-COMMANDS -->
|
||||
|
||||
`light`는 `plan` 단계를 생략하고 `intake` → `run` → `verification` → `acceptance` 네 단계로 끝납니다. <!-- claim-id: C-LIGHT-STAGES -->
|
||||
|
||||
`light`가 쓰는 명령은 `/ceo-intake`, `/run-wave`, `/review-output` 세 개입니다. <!-- claim-id: C-LIGHT-COMMANDS -->
|
||||
|
||||
`light`를 적용해도 되는 조건은 저위험·two-way-door·single-role이면서 고객·매출·보안 영향이 없는 작업입니다. <!-- claim-id: C-LIGHT-CONDITION -->
|
||||
|
||||
기본 tier는 `wave`가 `standard`, `light`가 `light`입니다. 종단도 달라서 `wave`는 `released`까지 가고 `light`는 `acceptance`에서 멈춥니다. <!-- claim-id: C-WAVE-LIGHT-DIFF -->
|
||||
|
||||
축약 경로라고 해서 검증 게이트가 빠지지는 않습니다. 두 경로 모두 `verification` 단계에서 `quality-gate-passed`와 `blocker-open-false`를 요구하며, 이는 `cascade`가 같은 단계에서 쓰는 게이트와 같습니다. <!-- claim-id: C-WAVE-LIGHT-VERIFY-GATE -->
|
||||
|
||||
`wave`의 `acceptance`는 `released`로 전이하며 exit gate로 `release-approved`, `no-unresolved-critical-risks`, `human-gate`를 요구합니다. 이 리스트는 `cascade`의 `acceptance`와 문자열이 같습니다. <!-- claim-id: C-WAVE-RELEASE-GATE -->
|
||||
|
||||
`light`에는 `released` 단계 자체가 없습니다. `light`의 `acceptance`가 종단 단계이고 command가 `null`이라, release 사람 게이트가 놓일 자리가 없습니다. <!-- claim-id: C-LIGHT-NO-RELEASE -->
|
||||
|
||||
빈 exit gate를 게이트가 없다는 뜻으로 읽으면 안 됩니다. 다섯 plan의 종단 단계는 모두 command `null`과 빈 exit gate를 갖고, 이는 다음 전이가 없다는 표시입니다. <!-- claim-id: C-TERMINAL-SHAPE -->
|
||||
|
||||
<!-- section-id: workflow-venture -->
|
||||
### venture-bootstrap — 회사 수립 경로
|
||||
|
||||
이 경로는 사람 입력이 먼저 차야 시작됩니다. `org-os/01-company/founder-context.yaml`의 상태가 `filled`여야 합니다. <!-- claim-id: C-VENTURE-INPUT -->
|
||||
|
||||
진입은 `/ceo-intake --plan venture-bootstrap`이고, 이어서 `/venture-validate`와 `/company-bootstrap`을 실행합니다. <!-- claim-id: C-VENTURE-ENTRY -->
|
||||
|
||||
단계는 `intake`, `founder-setup`, `opportunity-discovery`로 시작합니다. 이어서 `venture-validation`, `venture-decision`, `company-context-commit`을 거쳐 `bootstrap-complete`에서 끝납니다. <!-- claim-id: C-VENTURE-STAGES -->
|
||||
|
||||
산출물은 `org-os/01-company/company-context.yaml`이고 발급 시점의 상태는 `provisional`입니다. 상태 어휘는 `template`, `provisional`, `operating` 세 가지입니다. <!-- claim-id: C-VENTURE-OUTPUT -->
|
||||
|
||||
`company-context-commit` 단계는 exit gate 세 개를 요구합니다. `company-context-provisional-committed`, `company-context-lint-passed`, `company-context-artifact-recorded`입니다. <!-- claim-id: C-VENTURE-GATE -->
|
||||
|
||||
현재 저장소의 `company-context.yaml`은 `provisional` 상태입니다. `operating`이 아닌 동안 회사 관련 인용은 증거 등급 상한에 묶입니다. <!-- claim-id: C-VENTURE-CURRENT -->
|
||||
|
||||
<!-- section-id: workflow-design-direction -->
|
||||
### `design-direction` — `cascade`에 종속된 하위 워크플로
|
||||
|
||||
`design-direction`은 독립 워크플로가 아니라 제품 `cascade`에 종속된 하위 워크플로입니다. 종단 상태는 `design-direction-approved`입니다. <!-- claim-id: C-DD-CHILD -->
|
||||
|
||||
부모와의 결속 키는 `parent-workflow-id`, `product-decision-id`, `direction-input-brief-sha256` 세 개입니다. <!-- claim-id: C-DD-BINDING -->
|
||||
|
||||
흐름은 불변 direction-input-brief에서 3안을 독립 발산한 뒤 하나로 수렴하고, 승자 prototype을 만들어 비평 루프를 거쳐 `approved-direction`을 냅니다. <!-- claim-id: C-DD-FLOW -->
|
||||
|
||||
재작업 전이는 두 종류입니다. `critique-revision-requested`이면 `critique`에서 `prototype`으로, `concept-rejection-recorded`이면 `critique`에서 `divergence`로 되돌아갑니다. <!-- claim-id: C-DD-REWORK -->
|
||||
|
||||
승인 payload는 부모·자식 workflow id와 제품 결정 id에 더해 입력 brief, 선택된 방향, 승자 prototype의 SHA-256을 함께 고정합니다. <!-- claim-id: C-DD-PAYLOAD -->
|
||||
|
||||
<!-- section-id: workflow-specialized -->
|
||||
### 보조 진입점
|
||||
|
||||
| 명령 | 용도 |
|
||||
|---|---|
|
||||
| `/run-cascade` | 전체 cascade를 `state_engine`으로 순회하는 얇은 상위 드라이버 |
|
||||
| `/design-direction` | 3안 발산에서 `approved-direction`까지 가는 하위 워크플로 진입점 |
|
||||
| `/design-review` | winner-prototype을 7-lens 패널로 감사 |
|
||||
| `/design-system` | 기존 스택 discovery 뒤 reuse·adapt·create를 판정하고 렌더 검증까지 산출 |
|
||||
| `/consult` | engagement 유형에 따라 `FAM-CONSULTING` 또는 `FAM-DOC-CONSULT`로 분기 |
|
||||
| `/doctor` | `doctor.py` 실행 preflight를 감싸는 커맨드 |
|
||||
|
||||
`/design-review`는 상태 전이를 하지 않고 감사만 합니다. `producer-run-id`와 `reviewer-run-id`가 같으면 거부해 생산자와 검토자를 분리합니다. <!-- claim-id: C-DESIGN-REVIEW -->
|
||||
|
||||
`/run-cascade`는 평행 엔진 사용을 금지하는 얇은 드라이버입니다. 자동 승인과 자동 완주를 하지 않습니다. <!-- claim-id: C-RUN-CASCADE -->
|
||||
|
||||
각 명령의 상세 사용법은 [`.claude/commands/`](.claude/commands/)의 정의 파일에 있습니다.
|
||||
|
||||
<!-- section-id: repo-map -->
|
||||
## 저장소 구조
|
||||
|
||||
규칙의 원본은 `org-os/`에 있고, 그 규칙을 실행하는 코드는 `.claude/`에 있습니다. 고칠 위치를 찾을 때 이 경계를 먼저 봅니다. <!-- claim-id: C-REPO-SPLIT -->
|
||||
|
||||
| 경로 | 책임 |
|
||||
|---|---|
|
||||
| `org-os/` | 명세와 상태의 단일 원천 |
|
||||
| `.claude/` | Claude Code 런타임 어댑터 |
|
||||
| `benchmark/` | golden task 벤치마크와 P4 cascade 벤치마크의 정본 입력 |
|
||||
| `docs/superpowers/` | 설계 spec과 구현 plan |
|
||||
| `_sandbox/` | 테스트용 워크스페이스 |
|
||||
| `hyeonworks/` | 실제 제품 프로젝트 워크스페이스 |
|
||||
| `repomix/` | 소스에서 재생성되는 패킹 산출물 |
|
||||
|
||||
`repomix/`는 소스에서 다시 만드는 산출물이라 gitignore 대상입니다. <!-- claim-id: C-REPO-REPOMIX -->
|
||||
|
||||
<!-- section-id: repo-map-orgos -->
|
||||
### org-os — 정본 규칙 계층
|
||||
|
||||
| 경로 | 책임 |
|
||||
|---|---|
|
||||
| `org-os/00-role-registry/` | 역할·family·lens·상태 전이·권한·method 계약 활성화의 원천 |
|
||||
| `org-os/01-company/` | 회사 고유 사실을 담는 `company-context`와 `founder-context` |
|
||||
| `org-os/06-agent-work/` | workflow·artifact·협업·실행 계약과 생성된 artifact registry |
|
||||
| `org-os/02-capabilities/` 외 4개 | 아직 `README.md`만 있는 stub |
|
||||
|
||||
registry는 AI 역할 75개를 정의하고 최종 사람 소유자로 `HUMAN-001`을 둡니다. 라우팅 family는 28개, 평가 lens는 12개입니다. <!-- claim-id: C-ROLE-MODEL -->
|
||||
|
||||
역할 수는 `role-registry.roles` 항목만 셉니다. team topology, EA layer, workflow gate는 역할 수를 늘리지 않습니다. <!-- claim-id: C-ROLE-COUNT-RULE -->
|
||||
|
||||
역할별 method 절차의 원본은 `org-os/00-role-registry/role-working-methods/`이고, 라우팅은 `method-skill-registry.yaml`이 맡습니다. <!-- claim-id: C-METHOD-SOURCE -->
|
||||
|
||||
계약 활성화 기록은 `org-os/00-role-registry/method-contract-activations.yaml`에 남습니다. skill 디렉터리 78개는 13:36 시점에 그대로 있었습니다. <!-- claim-id: C-METHOD-CONTRACT -->
|
||||
|
||||
계약 machinery 집계값은 12:03 `doctor.py` 출력에서 얻었고 그 뒤 재검증하지 않았습니다. 활성화 기록 파일이 그 사이 수정됐으므로 이 문서는 해당 수치를 싣지 않습니다. <!-- claim-id: C-METHOD-CONTRACT-STALE -->
|
||||
|
||||
컴파일된 artifact registry는 artifact kind 186개를 담고 `.claude/hooks/compile_artifact_registry.py`가 만듭니다. 산출 위치는 `org-os/06-agent-work/generated/artifact-registry.yaml`입니다. <!-- claim-id: C-ARTIFACT-REGISTRY -->
|
||||
|
||||
회사 문맥 폴더 5개는 아직 `README.md`만 담고 있습니다. `02-capabilities`, `03-products`, `04-architecture`, `05-operations`, `07-knowledge-base`가 여기 해당합니다. <!-- claim-id: C-STUB-FOLDERS -->
|
||||
|
||||
<!-- section-id: repo-map-claude -->
|
||||
### .claude — 런타임 어댑터 계층
|
||||
|
||||
아래 규모는 모두 2026-07-20 13:36 시점의 관측값입니다. 저장소가 동시에 수정되던 중이라 안정된 속성이 아닙니다. <!-- claim-id: C-CLAUDE-SCALE-ASOF -->
|
||||
|
||||
| 경로 | 책임 | 규모(13:36) |
|
||||
|---|---|---|
|
||||
| `.claude/commands/` | 사용자 workflow 진입점 | 18개 |
|
||||
| `.claude/agents/` | registry에서 생성되는 concrete 실행 역할 카드 | 75개 |
|
||||
| `.claude/skills/` | 역할별 method skill과 capability skill | 78개 디렉터리 |
|
||||
| `.claude/hooks/` | 상태 엔진·검증·증거 원장·렌더러·생성기·벤치마크 | 최상위 40개 `.py` |
|
||||
| `.claude/hooks/bench_cascade/`, `.claude/hooks/orgos/` | 벤치마크 컨트롤러와 `planning`·`state` 하위 패키지 | 패키지 |
|
||||
| `.claude/schemas/` | report와 typed artifact JSON Schema | 44개 |
|
||||
| `.claude/tests/` | 하네스 강제기와 workflow 계약 테스트 | 32개 `test_*.py`와 `run_all.py` |
|
||||
|
||||
`.claude/agents/*.md`는 생성물이라 수기 편집을 금지합니다. 고칠 때는 role-profiles나 capability-families를 수정하고 `gen_agents.py`를 다시 실행합니다. <!-- claim-id: C-AGENTS-GENERATED -->
|
||||
|
||||
카드 75개의 구성은 `fan-out` worker 43개, `collapse concrete` worker 19개, `direct single-member` worker 10개, `synthesis lead` 3개입니다. <!-- claim-id: C-CARD-COMPOSITION -->
|
||||
|
||||
`family resolver`, `router`, family 메타데이터 카드는 이제 생성하지 않아 각각 0개입니다. 참조 역할 75개와 실행 가능한 concrete 카드 75개가 1대1로 대응합니다. <!-- claim-id: C-CARD-EXECUTABLE -->
|
||||
|
||||
훅은 이벤트 다섯 곳에 배선돼 있습니다. <!-- claim-id: C-HOOK-EVENTS -->
|
||||
|
||||
| 이벤트 | 스크립트 | 실패 정책 |
|
||||
|---|---|---|
|
||||
| `PreToolUse` | `guard_tools.py` | 도구 경계 검사 |
|
||||
| `PostToolUse` | `evidence_ledger.py`, `usage_observer.py` | 계측, advisory |
|
||||
| `SubagentStart` | `subagent_register.py`, `usage_observer.py` | 등록과 계측 |
|
||||
| `SubagentStop` | `usage_observer.py`, `stop_validate.py` | fail-closed |
|
||||
| `Stop` | `stop_validate.py --main` | advisory |
|
||||
|
||||
subagent 종료 검증은 fail-closed이고 메인 세션 종료 검증은 advisory입니다. <!-- claim-id: C-HOOK-WIRING -->
|
||||
|
||||
`usage_observer.py`는 13:36 재추출 시점에 새로 배선됐고, `PreToolUse` matcher에 `WebFetch`와 `WebSearch`가 추가됐습니다. <!-- claim-id: C-HOOK-NEW -->
|
||||
|
||||
다른 에이전트 런타임용 어댑터가 없으므로, 진입점과 강제를 옮기려면 이 계층 전체를 새로 배선해야 합니다. <!-- claim-id: C-ADAPTER-SINGLE -->
|
||||
|
||||
<!-- section-id: artifacts -->
|
||||
## 산출물과 증거
|
||||
|
||||
실행 결과·증거·상태는 저장소가 아니라 workspace 아래에 남습니다. 같은 명령이라도 workspace가 달라지면 기록 위치가 달라집니다. <!-- claim-id: C-ARTIFACT-LOCATION -->
|
||||
|
||||
<!-- section-id: workspace-resolution -->
|
||||
### 산출 위치가 정해지는 방식
|
||||
|
||||
`.orgos-workspace` 포인터의 현재 값은 `hyeonworks`입니다. 과거에는 이 파일이 의도적으로 비어 있었습니다. <!-- claim-id: C-WS-POINTER-VALUE -->
|
||||
|
||||
현재 워킹 트리에는 워크스페이스가 두 개 있습니다. `_sandbox`는 테스트·CI용이고 `hyeonworks`는 제품 프로젝트용입니다. <!-- claim-id: C-WS-TWO -->
|
||||
|
||||
`hyeonworks` 아래에는 `app`, `completion-records`, `design`, `design-direction`, `evidence`, `state`가 있습니다. `_sandbox` 아래에는 `completion-records`, `evidence`, `reports`, `state`가 있습니다. <!-- claim-id: C-WS-SUBDIRS -->
|
||||
|
||||
<!-- section-id: output-locations -->
|
||||
### 종류별 저장 위치
|
||||
|
||||
```text
|
||||
<workspace>/
|
||||
├── completion-records/<workflow>/ 역할별 .report.yaml
|
||||
├── evidence/ 실행 receipt 원장
|
||||
├── reports/ 사람이 읽는 렌더 산출물
|
||||
├── state/ workflow 상태
|
||||
├── slack-inbox/
|
||||
├── slack-outbox/
|
||||
└── design-system/
|
||||
```
|
||||
|
||||
보고서 경로 규칙은 `<workspace>/completion-records/<workflow>/<role>-<UTC timestamp>.report.yaml`입니다. <!-- claim-id: C-REPORT-PATH -->
|
||||
|
||||
`.report.yaml`은 덮어쓰기와 수정을 금지하며 `guard_tools`가 이를 강제합니다. 재작업도 `new_report.py`로 새 파일을 발급합니다. <!-- claim-id: C-REPORT-IMMUTABLE -->
|
||||
|
||||
실행 receipt는 `<workspace>/evidence/ledger.jsonl`에 쌓입니다. 실행한 명령과 종료 코드, stdout 해시, 기록된 산출물 경로와 SHA-256이 함께 남습니다. <!-- claim-id: C-RECEIPT-FIELDS -->
|
||||
|
||||
계측 훅이 workspace를 해석하지 못하면 기록만 건너뛰고 도구 실행 자체는 막지 않습니다. <!-- claim-id: C-RECEIPT-LIMIT -->
|
||||
|
||||
append-only 이벤트 원장은 `workflow-events.jsonl`, `artifact-events.jsonl`, `acceptance-events.jsonl`, `human-signoff.jsonl` 네 개입니다. <!-- claim-id: C-EVENT-LEDGERS -->
|
||||
|
||||
`workflow.yaml`은 이 이벤트들에서 만든 materialized view이며 버리고 다시 만들어도 되는 파생물입니다. <!-- claim-id: C-MATERIALIZED-VIEW -->
|
||||
|
||||
사람이 읽는 산출물은 `render_report.py`가 `.report.yaml`에서 MD로 만들고, `reports/INDEX.md`가 목차 역할을 합니다. <!-- claim-id: C-RENDER -->
|
||||
|
||||
대시보드는 `reports/TOKENS.md`와 `reports/KPI.md` 두 개입니다. `kpi_ledger`는 각 KPI를 measured/derived, manual, unmeasured로 구분해 표기합니다. <!-- claim-id: C-DASHBOARDS -->
|
||||
|
||||
<!-- section-id: verification -->
|
||||
## 검증 명령과 신뢰 범위
|
||||
|
||||
이 저장소는 사실 추출 도중에도 다른 세션이 수정하고 있었습니다. 그래서 검증 결과는 명령별로 기준 시점을 나눠 적습니다. <!-- claim-id: C-VERIFY-CONCURRENT -->
|
||||
|
||||
| 목적 | 명령 | 확인된 신호 | 검증 수준 | 기준 시점 |
|
||||
|---|---|---|---|---|
|
||||
| 생성 계약 | `gen_agents.py --check` | `75 concrete agents ... (profiles=75)`, exit 0 | 이번 분석에서 실행한 결과 | 13:36 현재 트리 |
|
||||
| 참조 무결성 | `lint_refs.py` | `18 command 참조 + 75 agent skills 참조 모두 해결됨`, exit 0 | 이번 분석에서 실행한 결과 | 13:36 현재 트리 |
|
||||
| registry 드리프트 | `compile_artifact_registry.py --check` | `186 kinds`, exit 0 | 이번 분석에서 실행한 결과 | 13:36 현재 트리 |
|
||||
| golden task 목록 | `benchmark.py list` | 골든태스크 13개, exit 0 | 이번 분석에서 실행한 결과 | 13:36 현재 트리 |
|
||||
| 전체 스위트 | `.claude/tests/run_all.py` | 현재 통과 여부 미확인 | 현재 트리에서 실행하지 않음 | — |
|
||||
| 배선 점검 | `.claude/hooks/doctor.py` | 현재 판정 미확인 | 현재 트리에서 실행하지 않음 | — |
|
||||
| 의존성 설치 | `pip install -r requirements.txt` | 표기 없음 | 저장소가 선언한 명령 | — |
|
||||
|
||||
12:03에 실행한 `run_all.py`와 `doctor.py`는 각각 `34/34 green`과 `35 OK · 0 WARN · 0 FAIL`을 냈습니다. 그 결과는 현재 저장소에 대한 주장이 아닙니다. <!-- claim-id: C-VERIFY-SUPERSEDED -->
|
||||
|
||||
그 사이 동시 리팩터가 agent 카드를 101개에서 75개로, 최상위 hook을 35개에서 40개로, test suite를 31개에서 32개로 바꿨습니다. 실행 대상이던 트리는 더 이상 존재하지 않습니다. <!-- claim-id: C-VERIFY-TREE-GONE -->
|
||||
|
||||
두 명령을 다시 돌리지 않은 이유가 있습니다. 동시 세션이 같은 `_sandbox` 워크스페이스에 같은 스위트를 실행 중이어서, 재실행하면 두 결과 모두 신뢰할 수 없게 됩니다. <!-- claim-id: C-VERIFY-NO-RERUN -->
|
||||
|
||||
분석 시점의 HEAD는 `00db337`이었고 워킹 트리에는 변경·미추적 항목이 269개, 삭제 항목이 26개 있었습니다. <!-- claim-id: C-VERIFY-TREE-STATE -->
|
||||
|
||||
<!-- section-id: verify-commands -->
|
||||
### 로컬 검증 진입점
|
||||
|
||||
전체 스위트 진입점은 `.claude/tests/run_all.py`입니다. 저장소가 문서화한 호출 형태는 다음과 같습니다. <!-- claim-id: C-SUITE-ENTRY -->
|
||||
|
||||
```bash
|
||||
CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/tests/run_all.py
|
||||
```
|
||||
|
||||
preflight는 `compile_artifact_registry.py --check`, `doctor.py`, `lint_refs.py` 세 개이고 `--no-preflight`로 건너뜁니다. <!-- claim-id: C-SUITE-PREFLIGHT -->
|
||||
|
||||
테스트는 `.claude/tests/test_*.py`를 suite별로 순차 실행하며, suite마다 새 프로세스 그룹에서 시작하고 300초 제한을 둡니다. 13:36 시점의 파일 수는 32개입니다. <!-- claim-id: C-SUITE-EXEC -->
|
||||
|
||||
제한값은 `ORGOS_TEST_TIMEOUT`으로 바꾸고, 초과하면 SIGTERM 뒤 필요 시 SIGKILL로 프로세스 그룹을 정리합니다. <!-- claim-id: C-SUITE-TIMEOUT -->
|
||||
|
||||
실패하거나 timeout된 suite가 하나라도 있으면 전체가 exit 1로 끝납니다. <!-- claim-id: C-SUITE-FAILURE -->
|
||||
|
||||
12:03 실행 결과는 preflight 3개와 테스트 31개를 합쳐 `34/34 green`, exit 0이었습니다. 그 뒤 저장소가 바뀌었으므로 현재 트리의 통과 여부는 확인되지 않았습니다. <!-- claim-id: C-SUITE-RUN -->
|
||||
|
||||
`doctor.py`가 보는 영역에는 settings.json 배선, workspace 해석, 커맨드에서 agent로 이어지는 참조 무결성이 들어갑니다. SSOT 소비 현황, append-only JSONL 원장 무결성, compiled artifact registry도 같은 점검에 들어갑니다. <!-- claim-id: C-DOCTOR-AREAS -->
|
||||
|
||||
`doctor.py` 자체가 이번 리팩터에서 수정됐고 배선과 카드도 함께 바뀌었습니다. 현재 트리의 판정은 확인되지 않았습니다. <!-- claim-id: C-DOCTOR-UNKNOWN -->
|
||||
|
||||
생성 계약 점검은 `gen_agents.py --check`가 맡습니다. registry에서 만든 카드 집합이 개수·구조 계약을 만족하는지 확인합니다. <!-- claim-id: C-GENCHECK-SCOPE -->
|
||||
|
||||
13:36 재실행은 exit 0으로 끝났고 `75 concrete agents`와 `profiles=75`를 보고했습니다. 12:03 실행은 같은 명령으로 101개를 보고했습니다. <!-- claim-id: C-GENCHECK-RUN -->
|
||||
|
||||
이 점검이 확인하지 않는 것도 분명합니다. 디스크에 있는 `.claude/agents/*.md` 바이트와의 비교는 이 명령의 출력에 나타나지 않습니다. <!-- claim-id: C-GENCHECK-LIMIT -->
|
||||
|
||||
참조 무결성 점검은 `lint_refs.py`가 맡습니다. 13:36 재실행에서 command 참조 18개와 agent skill 참조 75개가 모두 해결됐고 exit 0으로 끝났습니다. <!-- claim-id: C-LINTREFS -->
|
||||
|
||||
`compile_artifact_registry.py --check`도 13:36에 다시 돌려 artifact kind 186개에 드리프트가 없음을 exit 0으로 확인했습니다. <!-- claim-id: C-REGISTRY-RECHECK -->
|
||||
|
||||
<!-- section-id: verify-ci -->
|
||||
### 자동 검증 경로
|
||||
|
||||
자동 검증은 `.github/workflows/ci.yml`의 `harness-enforcers` job이고 실행 환경은 `ubuntu-latest`입니다. <!-- claim-id: C-CI-JOB -->
|
||||
|
||||
트리거는 `main`, `fix/**`, `feat/**` 브랜치 푸시와 `main`을 대상으로 하는 풀 리퀘스트입니다. <!-- claim-id: C-CI-TRIGGER -->
|
||||
|
||||
환경 설정은 `CLAUDE_PROJECT_DIR`을 `github.workspace`로, `ORGOS_WORKSPACE`를 `_sandbox`로 두고 Python 3.12와 Node 20을 씁니다. <!-- claim-id: C-CI-ENV -->
|
||||
|
||||
실행 단계는 로컬 명령과 그대로 대응합니다. <!-- claim-id: C-CI-STEPS -->
|
||||
|
||||
- `pip install -r requirements.txt`
|
||||
- D2 v0.7.1 설치
|
||||
- `python3 .claude/hooks/doctor.py`
|
||||
- `python3 .claude/hooks/lint_refs.py`
|
||||
- `python3 .claude/hooks/gen_agents.py --check`
|
||||
- `python3 .claude/tests/run_all.py --no-preflight`
|
||||
|
||||
D2 설치 단계는 실패해도 건너뛰도록 허용합니다. <!-- claim-id: C-CI-OPTIONAL -->
|
||||
|
||||
이번 분석에서는 GitHub Actions 실행 이력을 조회하지 않았습니다. CI가 최근에 통과했는지는 이 문서로 확인되지 않습니다. <!-- claim-id: C-CI-UNCHECKED -->
|
||||
|
||||
<!-- section-id: verify-levels -->
|
||||
### 검증 수준의 등급
|
||||
|
||||
이 문서는 검증 결과를 세 등급으로 나눠 표기합니다.
|
||||
|
||||
| 등급 | 뜻 | 이 문서의 사례 |
|
||||
|---|---|---|
|
||||
| 저장소가 선언한 명령 | 파일에서 정적으로 추출했고 실행하지 않음 | `pip install -r requirements.txt`, `gen_agents.py` 재생성 |
|
||||
| 이번 분석에서 실행한 결과 | 직접 실행해 종료 코드와 출력을 확인 | `gen_agents.py --check`, `lint_refs.py`, `compile_artifact_registry.py --check`, `benchmark.py list` |
|
||||
| 하네스 게이트를 통과한 결과 | 하네스의 Execution Verifier 역할이 검증 | 해당 사례 없음 |
|
||||
|
||||
이 문서에 실린 실행 결과는 모두 두 번째 등급입니다. Repository Evidence Analyst가 임시로 실행한 것이며 하네스의 Execution Verifier 게이트를 통과한 결과가 아닙니다. <!-- claim-id: C-LEVELS-SECOND -->
|
||||
|
||||
세 번째 등급에 해당하는 사례는 현재 이 문서에 없습니다. <!-- claim-id: C-LEVELS-THIRD-NONE -->
|
||||
|
||||
등급과 별개로 기준 시점을 함께 봐야 합니다. 두 번째 등급이어도 실행 시점 이후 저장소가 바뀌었다면 그 결과는 현재 트리에 대한 주장이 아닙니다. <!-- claim-id: C-LEVELS-CURRENCY -->
|
||||
|
||||
`run_all.py`와 `doctor.py`의 12:03 결과가 그런 경우입니다. 이 문서는 두 결과를 이력으로만 싣고 현재 상태의 근거로 쓰지 않습니다. <!-- claim-id: C-LEVELS-DEMOTED -->
|
||||
|
||||
앞의 절에 나온 명령에도 같은 기준으로 등급과 기준 시점을 붙였습니다.
|
||||
|
||||
<!-- section-id: evidence-status -->
|
||||
## 근거의 현재 상태
|
||||
|
||||
이 하네스가 더 나은 산출물을 낸다는 주장은 아직 성립하지 않습니다. 측정 도구는 만들어져 있고, 측정은 거의 이뤄지지 않았습니다. <!-- claim-id: C-EVIDENCE-BLUF -->
|
||||
|
||||
<!-- section-id: bench-golden -->
|
||||
### 과제 단위 벤치마크
|
||||
|
||||
golden task는 13개가 정의돼 있습니다. 카테고리는 code-bugfix, code-feature, refactor, docs, design, decision입니다. <!-- claim-id: C-GOLDEN-DEFINED -->
|
||||
|
||||
이 개수는 13:36에 `benchmark.py list`를 다시 돌려 exit 0으로 확인했습니다. <!-- claim-id: C-GOLDEN-LIST-RERUN -->
|
||||
|
||||
실행된 표본은 plain 2개와 harness 2개뿐입니다. 대상 과제는 `GT-01`과 `GT-R2` 둘이고, 둘 다 code-bugfix 저난도이며 실행일은 2026-07-11입니다. <!-- claim-id: C-GOLDEN-SAMPLES -->
|
||||
|
||||
측정된 지표는 3개이고 미측정 지표는 8개입니다. <!-- claim-id: C-GOLDEN-DIMENSIONS -->
|
||||
|
||||
| 지표 | plain | harness | 차이 |
|
||||
|---|---|---|---|
|
||||
| first-pass-acceptance | 1.0 | 1.0 | 0.0 |
|
||||
| tests-pass-rate | 1.0 | 1.0 | 0.0 |
|
||||
| unnecessary-change-lines | 0.0 | 0.0 | 0.0 |
|
||||
|
||||
측정된 세 지표가 모두 동률이고 가중 합성 차이도 0입니다. <!-- claim-id: C-GOLDEN-TIE -->
|
||||
|
||||
이 표본은 하네스의 품질 우위를 입증하지 않습니다. 설계·문서·의사결정 카테고리는 아직 실행되지 않았습니다. <!-- claim-id: C-GOLDEN-CONCLUSION -->
|
||||
|
||||
`benchmark/BENCHMARK.md`는 gitignore 대상이며 `runs.jsonl`에서 다시 만드는 재생성물입니다. `compare` 명령은 새 표본을 만들지 않습니다. <!-- claim-id: C-GOLDEN-REPORT-FILE -->
|
||||
|
||||
표본 수치는 12:03에 실행한 `compare` 출력에서 얻었습니다. 쓰기 부수효과가 있어 동시 수정 중인 트리에서 다시 돌리지 않았습니다. <!-- claim-id: C-GOLDEN-COMPARE-STALE -->
|
||||
|
||||
<!-- section-id: bench-cascade -->
|
||||
### 워크플로 단위 벤치마크
|
||||
|
||||
P4 cascade 벤치마크는 arm 세 개를 커밋 해시로 고정해 비교합니다. `A`는 P1+P2, `B`는 P1+P2+P3-A, `C`는 P1+P2+P3-B-active입니다. <!-- claim-id: C-CASCADE-ARMS -->
|
||||
|
||||
컨트롤러 CLI는 `.claude/hooks/benchmark_cascade.py`이고 모듈 13개에 총 889줄입니다. 테스트는 `test_p4_cascade.py`와 `test_p4_cascade_exec.py` 두 개입니다. <!-- claim-id: C-CASCADE-CLI -->
|
||||
|
||||
서브커맨드 8개 가운데 배선된 것은 `plan`과 `approve-budget` 둘뿐입니다. 나머지 6개인 `calibrate`, `arm-run`, `sanitize`, `judge`, `compare`, `probe`는 exit 3을 내는 stub입니다. <!-- claim-id: C-CASCADE-STUBS -->
|
||||
|
||||
이 stub 목록과 종료 코드는 `benchmark_cascade.py` 소스에서 정적으로 확인한 것입니다. 이 파일은 이번 리팩터에서 바뀌지 않았습니다. <!-- claim-id: C-CASCADE-STUBS-STATIC -->
|
||||
|
||||
stub이 내는 메시지는 `not-implemented — orchestrator 미배선(pilot 실행 단계에서 배선)`입니다. <!-- claim-id: C-CASCADE-STUB-MSG -->
|
||||
|
||||
파일럿 실행 산출물은 저장소에 없습니다. `runs` 디렉터리, `judgments.jsonl`, cascade 벤치마크 보고서가 모두 부재합니다. <!-- claim-id: C-CASCADE-NO-RUNS -->
|
||||
|
||||
12:03 실행에서 `plan`은 exit 0으로 끝났고 arm 실행 3회, pairwise 호출 18회, 예상 judge 호출 132회를 계획으로 냈습니다. preflight 위반은 없었습니다. <!-- claim-id: C-CASCADE-PLAN-RUN -->
|
||||
|
||||
`plan`은 역할·agent registry를 읽으므로 이번 리팩터의 영향을 배제할 수 없습니다. 이 결과는 재실행하지 않았습니다. <!-- claim-id: C-CASCADE-PLAN-STALE -->
|
||||
|
||||
공정성 통제로 외부 웹 접근을 막습니다. arm-runner의 `evidence_env`가 `WebFetch`와 `WebSearch`를 실행 환경에서 차단하고, 모든 arm이 같은 evidence pack을 씁니다. <!-- claim-id: C-CASCADE-FAIRNESS -->
|
||||
|
||||
예산 게이트도 걸려 있습니다. `calibrate`, `judge`, `arm-run`에 `--execute`를 주면 예산 receipt가 없을 때 exit 2로 거부합니다. <!-- claim-id: C-CASCADE-BUDGET -->
|
||||
|
||||
receipt가 있어도 실행되지는 않습니다. 세 서브커맨드 모두 현재 구현에서는 exit 3, 즉 미구현을 반환합니다. <!-- claim-id: C-CASCADE-BUDGET-STUB -->
|
||||
|
||||
승자 판정은 blinded paired pairwise 패널만 씁니다. rubric 8개 기준의 절대 점수는 calibration 진단 전용입니다. <!-- claim-id: C-CASCADE-JUDGING -->
|
||||
|
||||
설계 문서가 붙인 단서도 분명합니다. 파일럿은 arm별 단일 실행이므로 통계적 우월성이나 일반적 생산성 향상을 확정하지 않습니다. <!-- claim-id: C-CASCADE-DISCLAIMER -->
|
||||
|
||||
설계에서 의도적으로 미룬 항목은 여섯 가지입니다. <!-- claim-id: C-CASCADE-DEFERRED -->
|
||||
|
||||
- arm별 다중 repeat
|
||||
- Bradley–Terry/Elo 기반 순위화
|
||||
- 통계적 우월성 결론
|
||||
- cascade 확장
|
||||
- HUMAN judge 패널
|
||||
- live-research 트랙
|
||||
|
||||
<!-- section-id: limitations -->
|
||||
## 현재 한계
|
||||
|
||||
- 저장소가 이 문서를 쓰는 동안 다른 세션이 계속 수정했습니다. 12:03과 13:36 두 시점의 추출값이 달랐고, 13:36 이후에도 값이 다시 달라졌을 수 있습니다. <!-- claim-id: C-LIM-CONCURRENT -->
|
||||
- 저장소를 clone한 상태와 이 문서가 검증한 상태가 다릅니다. `.claude/agents`의 추적 카드는 72개인데 워킹 트리에는 75개가 있습니다. <!-- claim-id: C-LIM-UNCOMMITTED -->
|
||||
- 워킹 트리에서 지워진 `fam-*.md` 26개는 아직 커밋되지 않았습니다. HEAD는 그 파일들을 여전히 추적하므로, clone한 독자는 이 문서가 설명하는 것과 다른 저장소를 받습니다. <!-- claim-id: C-LIM-UNCOMMITTED-DELETE -->
|
||||
- 최상위 hook에 새 모듈 네 개가 나타났습니다. `compile_orgos_registry.py`, `spawn_bindings.py`, `intake_classifier.py`, `role_selector.py`는 `settings.json`에 배선돼 있지 않습니다. <!-- claim-id: C-LIM-UNWIRED-HOOKS -->
|
||||
- `doctor.py`의 14번째 점검 영역은 `compile_orgos_registry.py`를 실행합니다. 이 모듈 역시 배선돼 있지 않으므로, 점검 영역이 14개라는 사실이 14개 영역의 런타임 강제를 뜻하지는 않습니다. <!-- claim-id: C-LIM-DOCTOR-SECTION14 -->
|
||||
- 전체 test suite가 현재 트리에서 통과하는지는 확인되지 않았습니다. 마지막으로 통과를 확인한 시점은 리팩터 이전인 12:03입니다. <!-- claim-id: C-LIM-SUITE-UNKNOWN -->
|
||||
- 강제는 Claude Code가 이 저장소의 `.claude/settings.json`을 로드한 세션에서만 동작합니다. 다른 실행 환경에서는 같은 강제를 보장하지 않습니다. <!-- claim-id: C-LIM-ACTIVATION -->
|
||||
- `guard_tools.py`는 allow-by-default regex 기반 2차 방어선입니다. 저장소가 스스로 셸 조합·인용·변형으로 우회 가능하다고 선언하므로 보안 경계로 삼으면 안 됩니다. <!-- claim-id: C-LIM-GUARD -->
|
||||
- `company-context.yaml`이 `provisional`이고 창업자 확인값 5개가 비어 있습니다. 주당 가용시간, 자본·런웨이, 목표 사업 규모, 보유 유통채널, 운영·리스크 내성이 미해결입니다. <!-- claim-id: C-LIM-COMPANY -->
|
||||
- 상태가 `operating`이 아니면 company 인용 항목은 `E2`와 Med 상한에 묶이고, hypothesis 항목은 상태와 무관하게 Med 상한입니다. `validate_report`가 이를 강제합니다. <!-- claim-id: C-LIM-PROVENANCE -->
|
||||
- 회사·제품 문맥 레이어가 비어 있어, 자원 배분과 GTM 결정 전에 창업자 확인값을 먼저 채워야 합니다. <!-- claim-id: C-LIM-CONTEXT-EMPTY -->
|
||||
- 워크스페이스 미설정이 더 이상 즉시 실패로 드러나지 않습니다. 포인터 파일이 채워져 있어 환경변수를 지정하지 않은 명령도 `hyeonworks`로 해석됩니다. <!-- claim-id: C-LIM-POINTER -->
|
||||
- UI 검증은 render health만 판정합니다. 시각적 차별성, 타이포그래피, 비례, spacing의 미학 품질은 판정 범위 밖입니다. <!-- claim-id: C-LIM-UI -->
|
||||
- 일부 경로는 외부 도구에 기댑니다. 전체 렌더 점검에는 Chrome 또는 Chromium 호환 실행 파일이 필요하고, `marp`가 없으면 consult 덱은 HTML 대체 경로로 갑니다. <!-- claim-id: C-LIM-EXTERNAL -->
|
||||
|
||||
<!-- section-id: contributing -->
|
||||
## 기여할 때 고치는 위치
|
||||
|
||||
1. 정본을 먼저 고칩니다. 역할·family·method 정의는 `org-os/00-role-registry/`에, workflow와 artifact 계약은 `org-os/06-agent-work/`에 있습니다. <!-- claim-id: C-CONTRIB-SOURCE -->
|
||||
2. 생성물을 다시 만듭니다.
|
||||
3. 재검증을 돌립니다.
|
||||
|
||||
```bash
|
||||
CLAUDE_PROJECT_DIR="$PWD" python3 .claude/hooks/gen_agents.py
|
||||
CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/tests/run_all.py
|
||||
```
|
||||
|
||||
재생성 명령은 `.claude/agents/*.md`를 덮어쓰므로 이번 분석에서 실행하지 않았습니다(검증 수준: 저장소가 선언한 명령). <!-- claim-id: C-CONTRIB-REGEN -->
|
||||
|
||||
변경은 CI의 `harness-enforcers` job이 돌리는 검사들을 그대로 통과해야 합니다. <!-- claim-id: C-CONTRIB-CI -->
|
||||
|
||||
method 계약을 바꾸면 `method-contract-activations.yaml`에 활성화 기록이 남습니다. 기록에는 상태, 계약 해시, 검증 보고서와 그 해시, 수용 workflow, 활성화 주체와 시각이 들어갑니다. <!-- claim-id: C-CONTRIB-ACTIVATION -->
|
||||
|
||||
<!-- section-id: reference -->
|
||||
## 정본 파일
|
||||
|
||||
- [`org-os/06-agent-work/workflow-contracts.yaml`](org-os/06-agent-work/workflow-contracts.yaml) — 단계 그래프와 exit gate 정본
|
||||
- [`org-os/00-role-registry/roles.yaml`](org-os/00-role-registry/roles.yaml) — AI 역할 registry
|
||||
- [`org-os/00-role-registry/capability-families.yaml`](org-os/00-role-registry/capability-families.yaml) — family 라우팅과 fan-out·collapse 기본값
|
||||
- [`org-os/00-role-registry/lens-registry.yaml`](org-os/00-role-registry/lens-registry.yaml) — 평가 lens 정의
|
||||
- [`org-os/00-role-registry/tool-permission-matrix.yaml`](org-os/00-role-registry/tool-permission-matrix.yaml) — 도구 권한 기본 정책
|
||||
- [`org-os/00-role-registry/method-contract-activations.yaml`](org-os/00-role-registry/method-contract-activations.yaml) — method 계약 활성화 기록
|
||||
- [`org-os/06-agent-work/execution-policy.yaml`](org-os/06-agent-work/execution-policy.yaml) — 동시성과 검증자 독립성 정책
|
||||
- [`org-os/06-agent-work/generated/artifact-registry.yaml`](org-os/06-agent-work/generated/artifact-registry.yaml) — 컴파일된 artifact kind registry
|
||||
- [`.claude/commands/`](.claude/commands/) — slash command 정의
|
||||
- [`.claude/hooks/`](.claude/hooks/) — 상태 엔진·검증·생성기
|
||||
- [`.claude/schemas/`](.claude/schemas/) — report와 artifact JSON Schema
|
||||
- [`.claude/tests/`](.claude/tests/) — 강제기와 계약 테스트
|
||||
- [`benchmark/golden-tasks.yaml`](benchmark/golden-tasks.yaml) — golden task 정의
|
||||
- [`benchmark/cascade/arm-manifest.yaml`](benchmark/cascade/arm-manifest.yaml) — arm 커밋 고정 명세
|
||||
- [`benchmark/cascade/benchmark-policy.yaml`](benchmark/cascade/benchmark-policy.yaml) — cascade 벤치마크 공정성 정책
|
||||
|
||||
<!-- section-id: design-history -->
|
||||
### 설계 이력
|
||||
|
||||
설계 spec은 [`docs/superpowers/specs/`](docs/superpowers/specs/)에, 구현 plan은 [`docs/superpowers/plans/`](docs/superpowers/plans/)에 있습니다. <!-- claim-id: C-DESIGN-HISTORY -->
|
||||
|
||||
<!-- section-id: license -->
|
||||
## 라이선스
|
||||
|
||||
저장소 루트에 `LICENSE` 파일이 없습니다. 사용과 재배포 조건은 이 저장소에 명시돼 있지 않습니다. <!-- claim-id: C-LICENSE -->
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,634 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"policy-id": "korean-reader-prose-v1",
|
||||
"language": "ko-KR",
|
||||
"applicable": true,
|
||||
"scope": "candidate",
|
||||
"state": "PASS_WITH_WARNINGS",
|
||||
"summary": {
|
||||
"errors": 0,
|
||||
"warnings": 44,
|
||||
"sentences": 380,
|
||||
"prose-characters": 9873,
|
||||
"hangul-characters": 6686
|
||||
},
|
||||
"findings": [
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 10,
|
||||
"section": "무엇을 운영하는 저장소인가",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "Claude, Code, subagent, project, command, hook",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-001"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 30,
|
||||
"section": "운영 원리",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "Claude, Code, permission, defense-in-depth",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-002"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 47,
|
||||
"section": "1. 필수 도구와 선택 도구",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "PyYAML, SSOT, YAML",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-003"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 51,
|
||||
"section": "1. 필수 도구와 선택 도구",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "Marp, consult, HTML",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-004"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 97,
|
||||
"section": "3. 배선 확인과 첫 명령",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "Claude, Code, plan",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-005"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 112,
|
||||
"section": "작업에 맞는 workflow 고르기",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "slash, command, plan",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-006"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 122,
|
||||
"section": "작업에 맞는 workflow 고르기",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "plan, plan, exit, gate",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-007"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 251,
|
||||
"section": "와 — 축약 경로",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "exit, gate, plan, command, exit, gate",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-008"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 279,
|
||||
"section": "— 에 종속된 하위 워크플로",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "payload, workflow, brief, prototype, SHA-256",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-009"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 289,
|
||||
"section": "보조 진입점",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "discovery, reuse, adapt, create",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-010"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 308,
|
||||
"section": "저장소 구조",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "golden, task, cascade",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-011"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 321,
|
||||
"section": "org-os — 정본 규칙 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "family, lens, method",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-012"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 323,
|
||||
"section": "org-os — 정본 규칙 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "workflow, artifact, artifact, registry",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-013"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 326,
|
||||
"section": "org-os — 정본 규칙 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "registry, family, lens",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-014"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 328,
|
||||
"section": "org-os — 정본 규칙 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "team, topology, layer, workflow, gate",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-015"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 336,
|
||||
"section": "org-os — 정본 규칙 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "artifact, registry, artifact, kind",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-016"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 349,
|
||||
"section": ".claude — 런타임 어댑터 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "method, skill, capability, skill",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-017"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 352,
|
||||
"section": ".claude — 런타임 어댑터 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "report, typed, artifact, JSON, Schema",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-018"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 357,
|
||||
"section": ".claude — 런타임 어댑터 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "worker, worker, worker",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-019"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 371,
|
||||
"section": ".claude — 런타임 어댑터 계층",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "subagent, fail-closed, advisory",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-020"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 409,
|
||||
"section": "종류별 저장 위치",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "receipt, stdout, SHA-256",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-021"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 419,
|
||||
"section": "종류별 저장 위치",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "KPI, measured, derived, manual, unmeasured",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-022"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 431,
|
||||
"section": "검증 명령과 신뢰 범위",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "golden, task, exit",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-023"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 438,
|
||||
"section": "검증 명령과 신뢰 범위",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "agent, hook, test, suite",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-024"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 459,
|
||||
"section": "로컬 검증 진입점",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "timeout, suite, exit",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-025"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 463,
|
||||
"section": "로컬 검증 진입점",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "settings, json, workspace, agent, SSOT, append-only, JSONL, compiled, artifact, registry",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-026"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 473,
|
||||
"section": "로컬 검증 진입점",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "command, agent, skill, exit",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-027"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 475,
|
||||
"section": "로컬 검증 진입점",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "artifact, kind, exit",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-028"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 510,
|
||||
"section": "검증 수준의 등급",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "Repository, Evidence, Analyst, Execution, Verifier",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-029"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 528,
|
||||
"section": "과제 단위 벤치마크",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "golden, task, code-bugfix, code-feature, refactor, docs, design, decision",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-030"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 532,
|
||||
"section": "과제 단위 벤치마크",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "plain, harness, code-bugfix",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-031"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 553,
|
||||
"section": "워크플로 단위 벤치마크",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "cascade, arm, P3-A, P3-B-active",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-032"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 565,
|
||||
"section": "워크플로 단위 벤치마크",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "exit, arm, pairwise, judge, preflight",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-033"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 569,
|
||||
"section": "워크플로 단위 벤치마크",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "arm-runner, arm, evidence, pack",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-034"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 575,
|
||||
"section": "워크플로 단위 벤치마크",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "blinded, paired, pairwise, rubric, calibration",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-035"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-VAGUE-BENEFIT",
|
||||
"severity": "warning",
|
||||
"line": 577,
|
||||
"section": "워크플로 단위 벤치마크",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "설계 문서가 붙인 단서도 분명합니다. 파일럿은 arm별 단일 실행이므로 통계적 우월성이나 일반적 생산성 향상을 확정하지 않습니다.",
|
||||
"message": "작동 방식이나 결과가 빠진 추상적인 효용 표현이 있습니다.",
|
||||
"suggestion": "누가 무엇을 어떻게 할 수 있는지 구체적으로 적으세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE",
|
||||
"GITHUB-README-GUIDE"
|
||||
],
|
||||
"id": "P-036"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 582,
|
||||
"section": "워크플로 단위 벤치마크",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "Bradley, Terry, Elo",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-037"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 600,
|
||||
"section": "현재 한계",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "company, Med, hypothesis, Med",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-038"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 603,
|
||||
"section": "현재 한계",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "render, health, spacing",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-039"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 604,
|
||||
"section": "현재 한계",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "Chrome, Chromium, consult, HTML",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-040"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 609,
|
||||
"section": "기여할 때 고치는 위치",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "family, method, workflow, artifact",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-041"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 629,
|
||||
"section": "정본 파일",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "family, fan-out, collapse",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-042"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 634,
|
||||
"section": "정본 파일",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "artifact, kind, registry",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-043"
|
||||
},
|
||||
{
|
||||
"rule-id": "KO-UNMARKED-ENGLISH-DENSITY",
|
||||
"severity": "warning",
|
||||
"line": 637,
|
||||
"section": "정본 파일",
|
||||
"region-kind": "candidate",
|
||||
"excerpt": "report, artifact, JSON, Schema",
|
||||
"message": "한국어 설명문에 영문 개념어가 한꺼번에 나와 읽는 흐름을 끊습니다.",
|
||||
"suggestion": "파일·모듈·API·상태 값은 인라인 코드로 남기고 일반 개념은 한국어로 쓰세요.",
|
||||
"source-ids": [
|
||||
"NIKL-EASY-PUBLIC-LANGUAGE"
|
||||
],
|
||||
"id": "P-044"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -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
|
||||
@@ -0,0 +1,441 @@
|
||||
schema-version: 1
|
||||
sections:
|
||||
- id: overview
|
||||
title-guidance: 프로젝트 정체성과 대상 독자를 한 화면에서 판단시키는 제목
|
||||
level: 2
|
||||
purpose: 저장소가 무엇을 운영하는 물건인지, 어떤 독자를 위한 것인지, 어느 런타임에 묶여 있는지를 즉시 판단시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 파일 기반 에이전트 운영 하네스라는 구체적 정의와 org-os 디렉터리가 정본이라는 사실
|
||||
- 개발과 비즈니스를 함께 다루는 적용 범위
|
||||
- Claude Code 단일 어댑터에 묶여 있다는 전제 조건을 초반에 노출
|
||||
- 1차·2차 독자 구분과 각자가 이 문서에서 얻을 결과
|
||||
- 문서에 실린 검증 결과가 워킹 트리 기준이라는 범위 고지를 개요 단계에서 한 번 선언
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 프로젝트 정체성을 파악하는 데 그림이 필요한가?
|
||||
rationale: 정체성은 정의문과 범위 문장으로 전달되며, 그림을 두면 유일한 시각물 예산을 판단이 아니라 인상에 소모한다.
|
||||
|
||||
- id: operating-model
|
||||
title-guidance: 이 하네스가 프롬프트 모음과 다른 이유를 설명하는 제목
|
||||
level: 2
|
||||
purpose: 계약·상태·증거·권한이 어떻게 결합되어 강제로 작동하는지를 원리 수준에서 설명한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- workflow-contracts가 단계·역할 권한·산출물 kind·exit gate를 한 그래프로 정의한다는 원칙
|
||||
- 상태 런타임이 caller 제출값을 신뢰하지 않고 불변 바이트에서 파생한다는 신뢰 규칙
|
||||
- fan-out과 collapse의 구분 기준, 그리고 오케스트레이터만 fan-out한다는 제약
|
||||
- 증거 등급과 receipt 대조로 근거 없는 주장이 차단되는 경로
|
||||
- 1차 경계는 네이티브 permission이고 guard 훅은 2차 방어선이라는 구분
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 계약·상태·증거의 결합을 이해하는 데 구조도가 필요한가?
|
||||
rationale: 네다섯 개의 독립 원칙을 나열하는 성격이라 항목별 목록이 더 정확하고, 흐름도로 그리면 실제보다 단일 파이프라인처럼 오해된다.
|
||||
|
||||
- id: quick-start
|
||||
title-guidance: 최소 사용 절차를 처음부터 끝까지 잇는 제목
|
||||
level: 2
|
||||
purpose: 설치부터 workspace 지정, 배선 확인, 첫 명령 실행까지의 최단 경로를 끊김 없이 제공한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 절차를 순서가 있는 단계로 제시하고 각 단계의 성공 신호를 함께 제시
|
||||
- 각 명령의 검증 수준을 quick-start 안에서 과장 없이 표기
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 설치와 첫 실행 순서를 이해하는 데 그림이 필요한가?
|
||||
rationale: 복사 가능한 명령 블록과 기대 출력이 가장 직접적이며, 순서 자체는 번호 목록으로 충분하다.
|
||||
children:
|
||||
- id: prerequisites
|
||||
title-guidance: 필수 도구와 선택 도구를 구분하는 제목
|
||||
level: 3
|
||||
purpose: 어떤 도구가 없으면 동작하지 않고 어떤 도구가 없으면 기능만 줄어드는지를 구분시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- Python과 PyYAML의 최소·검증 버전
|
||||
- 권장 도구와 각 도구가 필요한 기능 경로
|
||||
- 선택 도구 부재 시의 대체 경로
|
||||
- 버전 대조를 수행하는 진입점
|
||||
|
||||
- id: workspace-setup
|
||||
title-guidance: workspace 지정 규칙을 다루는 제목
|
||||
level: 3
|
||||
purpose: 산출물이 어디에 쓰일지를 결정하는 workspace 해석 규칙과 미설정 시 동작을 확정시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 환경변수와 포인터 파일의 우선순위, 상대·절대 경로 해석 규칙
|
||||
- 미해석 시 fail-closed 훅과 advisory 훅의 동작 차이
|
||||
- 테스트·CI에서 sandbox workspace를 명시하는 관례
|
||||
- 현재 포인터가 채워져 있어 미설정이 곧바로 실패로 이어지지 않는다는 주의
|
||||
|
||||
- id: first-command
|
||||
title-guidance: 첫 실행과 확인을 다루는 제목
|
||||
level: 3
|
||||
purpose: 설치가 끝난 독자가 실제로 실행할 첫 명령과 그 판정 기준을 제시한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 배선 점검 진입점과 성공 판정 문구
|
||||
- 모든 workflow의 공통 진입 명령과 그 산출물
|
||||
- 진입 게이트가 요구하는 선행 조건
|
||||
|
||||
- id: workflows
|
||||
title-guidance: 작업 성격에 맞는 workflow를 고르게 하는 제목
|
||||
level: 2
|
||||
purpose: 다섯 개 workflow plan을 진입점·단계·종단 상태·사람 승인 지점 기준으로 구분해 독자가 하나를 선택하게 한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 공통 진입점과 plan 선언 방식
|
||||
- plan별 선택 기준을 판단 가능한 조건으로 제시
|
||||
- 명령 총수와 그중 workflow 진입점의 위치 관계
|
||||
- 각 plan의 종단 상태와 사람 승인이 개입하는 지점
|
||||
visual-slot:
|
||||
decision: include
|
||||
reader-question: 나는 어떤 workflow를 골라야 하고, 고른 경로는 어떤 단계를 거쳐 어디서 끝나며 사람이 승인하는 지점은 어디인가?
|
||||
rationale: 다섯 경로가 하나의 진입점을 공유하면서 단계 수·종단 상태·부모 종속 관계가 서로 다른 분기 구조라 산문이나 표로는 비교가 어렵다. 독자가 이 문서에서 실제로 내리는 유일한 선택이므로 하나뿐인 시각물 예산을 여기에 쓴다.
|
||||
purpose: 공통 진입점에서 갈라지는 plan 분기와 각 경로의 단계 진행·종단 상태·사람 승인 지점을 한 화면에서 비교시켜 독자가 자기 작업에 맞는 경로를 고르게 한다.
|
||||
children:
|
||||
- id: workflow-cascade
|
||||
title-guidance: 표준 전체 경로를 다루는 제목
|
||||
level: 3
|
||||
purpose: 가장 긴 표준 경로의 단계 순서와 각 단계 산출물, 재작업 전이를 정확히 전달한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 단계 순서를 정본 그대로 제시하고 통념과 다른 순서를 명시
|
||||
- 단계별 명령과 산출물의 대응
|
||||
- 종단 단계의 exit gate 구성
|
||||
- 품질 게이트 실패 시의 재작업 전이
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 여덟 단계 진행을 별도 그림으로 보여야 하는가?
|
||||
rationale: 상위 섹션의 유일한 시각물이 이미 단계 진행과 승인 지점을 담고, 단계별 명령과 산출물의 정확한 대응은 표가 더 정밀하다.
|
||||
|
||||
- id: workflow-wave-light
|
||||
title-guidance: 축약 경로 두 가지를 비교하는 제목
|
||||
level: 3
|
||||
purpose: 표준 경로를 줄인 두 경로가 무엇을 생략하고 어떤 작업에 적합한지를 판단시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 두 경로의 단계 구성과 생략된 단계
|
||||
- 반복 단계와 종단 단계의 차이
|
||||
- 축약 경로를 적용해도 되는 작업 조건
|
||||
- 기본 tier 차이
|
||||
|
||||
- id: workflow-venture
|
||||
title-guidance: 회사 수립 경로를 다루는 제목
|
||||
level: 3
|
||||
purpose: 사람 입력이 선행되어야 하는 경로임을 밝히고 입력·출력·현재 상태를 연결한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 진입 명령과 후속 명령 순서
|
||||
- 사람이 채워야 하는 입력 파일과 요구 상태
|
||||
- 산출 파일과 상태 어휘
|
||||
- 현재 산출물이 잠정 상태라는 사실과 그 결과
|
||||
|
||||
- id: workflow-design-direction
|
||||
title-guidance: 제품 경로에 종속된 디자인 방향 결정 경로를 다루는 제목
|
||||
level: 3
|
||||
purpose: 이 경로가 독립 워크플로가 아니라 부모 결정에 결속된 child workflow임을 이해시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 부모 워크플로와의 결속 키
|
||||
- 발산에서 승인까지의 단계 흐름과 두 종류의 재작업 전이
|
||||
- 최종 산출물과 승인 payload가 해시로 고정된다는 점
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 이 child workflow의 단계와 비평 루프를 별도 그림으로 보여야 하는가?
|
||||
rationale: 시각물 한도가 1이고 상위 선택 문제보다 우선순위가 낮다. 두 개의 재작업 전이는 조건과 함께 문장으로 적는 편이 오해가 적다.
|
||||
|
||||
- id: workflow-specialized
|
||||
title-guidance: 상태 전이를 하지 않는 보조 진입점들을 묶는 제목
|
||||
level: 3
|
||||
purpose: workflow plan이 아닌 전문 명령들의 용도와 경계를 짧게 구분시킨다.
|
||||
required: true
|
||||
content-strategy: summary-link
|
||||
target-doc: .claude/commands/
|
||||
content-requirements:
|
||||
- 명령별 한 줄 용도와 상태 전이 여부
|
||||
- 검토 명령의 생산자·검토자 분리 강제
|
||||
- 전체 경로 드라이버가 사람 게이트에서 정지한다는 제약
|
||||
- 상세 사용법은 명령 정의 파일로 링크
|
||||
|
||||
- id: repo-map
|
||||
title-guidance: 규칙의 원본과 실행 코드가 어디에 나뉘는지 보여주는 제목
|
||||
level: 2
|
||||
purpose: 주요 디렉터리의 책임을 구분해 독자가 읽을 위치와 고칠 위치를 찾게 한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 정본 규칙 계층과 런타임 어댑터 계층의 구분
|
||||
- 생성물 디렉터리와 원본 디렉터리의 구분
|
||||
- 벤치마크·문서·워크스페이스 디렉터리의 역할
|
||||
- 채워지지 않은 stub 폴더를 구조 설명 안에서 표시
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 디렉터리 책임을 파악하는 데 구조도가 필요한가?
|
||||
rationale: 경로와 책임을 1대1로 짝짓는 탐색용 정보라 표가 그림보다 정확하고, 시각물 한도는 선택 문제에 이미 배정됐다.
|
||||
children:
|
||||
- id: repo-map-orgos
|
||||
title-guidance: 정본 규칙 계층을 다루는 제목
|
||||
level: 3
|
||||
purpose: 역할·계약·회사 문맥의 원본이 어디에 있는지 확정시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 역할 registry와 family·lens 구성의 규모
|
||||
- workflow·artifact 계약 파일의 위치와 mirror 파일의 지위
|
||||
- 회사 문맥 디렉터리와 그 현재 상태
|
||||
- 컴파일된 artifact registry의 규모와 생성 경로
|
||||
|
||||
- id: repo-map-claude
|
||||
title-guidance: 런타임 어댑터 계층을 다루는 제목
|
||||
level: 3
|
||||
purpose: 명령·에이전트 카드·훅·스키마·테스트의 위치와 생성 관계를 구분시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 명령·카드·skill·훅·스키마·테스트의 개수와 책임
|
||||
- 에이전트 카드가 생성물이며 수기 편집 금지 대상이라는 규칙
|
||||
- 훅 배선 지점과 각 훅의 실패 정책
|
||||
- 이 어댑터가 유일하며 다른 런타임 어댑터는 없다는 사실
|
||||
|
||||
- id: artifacts
|
||||
title-guidance: 실행 결과와 증거가 남는 위치를 다루는 제목
|
||||
level: 2
|
||||
purpose: 산출물·증거·상태의 저장 위치와 불변성 규칙을 확정시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- workspace 아래 표준 디렉터리 구성
|
||||
- 보고서 경로 규칙과 덮어쓰기 금지 정책
|
||||
- 실행 receipt에 기록되는 항목
|
||||
- 사람이 읽는 렌더 산출물과 대시보드의 위치
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 산출물 위치를 찾는 데 그림이 필요한가?
|
||||
rationale: 경로 탐색 문제라 작은 디렉터리 트리와 설명이면 충분하고 그림은 정보를 늘리지 않는다.
|
||||
children:
|
||||
- id: workspace-resolution
|
||||
title-guidance: 산출물이 쓰일 위치가 결정되는 방식을 다루는 제목
|
||||
level: 3
|
||||
purpose: 같은 명령이 어디에 쓰는지를 결정하는 해석 규칙과 현재 트리의 실제 값을 연결한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 해석 우선순위와 포인터 파싱 규칙
|
||||
- 현재 트리에 존재하는 워크스페이스와 각각의 용도
|
||||
- 테스트용과 제품용 워크스페이스의 분리
|
||||
|
||||
- id: output-locations
|
||||
title-guidance: 산출물 종류별 저장 위치를 다루는 제목
|
||||
level: 3
|
||||
purpose: 독자가 찾는 결과물의 종류에 따라 정확한 경로로 이동시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 완료 기록·증거·보고서·상태·인박스 경로의 대응
|
||||
- append-only 이벤트 원장과 파생 뷰의 구분
|
||||
- 재생성 가능한 파일과 원장의 구분
|
||||
- 대시보드가 측정값과 수기값을 구분 표기한다는 규칙
|
||||
|
||||
- id: verification
|
||||
title-guidance: 검증 명령과 그 결과를 어디까지 믿을 수 있는지 다루는 제목
|
||||
level: 2
|
||||
purpose: 저장소가 제공하는 검증 수단을 목적별로 제시하고 각 결과의 검증 수준을 명시한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 목적·명령·성공 신호·검증 수준을 짝지어 제시
|
||||
- 실행되지 않은 명령과 실행된 명령을 표기상 구분
|
||||
- 실행 결과가 워킹 트리 기준이라는 범위 고지
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 검증 명령을 고르는 데 그림이 필요한가?
|
||||
rationale: 목적·명령·성공 신호·수준의 네 축을 짝짓는 정보라 표가 유일하게 정확한 형식이다.
|
||||
children:
|
||||
- id: verify-commands
|
||||
title-guidance: 로컬 검증 진입점을 다루는 제목
|
||||
level: 3
|
||||
purpose: 배선 점검·참조 무결성·생성 계약·전체 스위트를 각각 언제 쓰는지 구분시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 전체 스위트 진입점과 preflight 구성, 실패 계약
|
||||
- 배선 점검이 확인하는 영역과 판정 형식
|
||||
- 생성 계약 점검의 범위와 그 점검이 확인하지 않는 것
|
||||
- 참조 무결성 점검의 대상 수
|
||||
|
||||
- id: verify-ci
|
||||
title-guidance: 자동 검증 경로를 다루는 제목
|
||||
level: 3
|
||||
purpose: 어떤 검증이 자동으로 반복되는지와 그 실행 조건을 알린다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 트리거 조건과 실행 환경 설정
|
||||
- 실행 단계 목록과 로컬 명령과의 대응
|
||||
- 실패해도 넘어가는 선택 단계
|
||||
- 이번 분석에서 실행 이력을 조회하지 않았다는 범위 고지
|
||||
|
||||
- id: verify-levels
|
||||
title-guidance: 검증 수준의 등급을 정의하는 제목
|
||||
level: 3
|
||||
purpose: 저장소가 선언한 명령, 분석자가 임시로 실행한 결과, 하네스 게이트를 통과한 결과를 서로 다른 신뢰 등급으로 구분시킨다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 세 등급의 정의와 각 등급에 해당하는 실제 사례
|
||||
- 이번 문서의 실행 결과가 하네스 게이트를 통과한 것이 아니라는 사실
|
||||
- 등급 표기를 다른 섹션의 명령에도 일관 적용한다는 약속
|
||||
|
||||
- id: evidence-status
|
||||
title-guidance: 품질 우위 주장의 근거가 지금 어디까지 있는지 밝히는 제목
|
||||
level: 2
|
||||
purpose: 벤치마크 인프라의 존재와 실증 결과의 부재를 분리해, 독자가 하네스의 우위를 입증된 것으로 오해하지 않게 한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 측정 도구가 있다는 사실과 측정이 끝났다는 사실을 문장 단위로 분리
|
||||
- 우위 주장이 아직 성립하지 않는다는 결론을 명시적으로 진술
|
||||
- 비교 우위·생산성 향상 표현을 사용하지 않는다는 제약 준수
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 근거 상태를 이해하는 데 도표가 필요한가?
|
||||
rationale: 결과가 전부 동률이거나 부재라 시각화할 신호 자체가 없고, 차트는 없는 신호를 있는 것처럼 보이게 한다.
|
||||
children:
|
||||
- id: bench-golden
|
||||
title-guidance: 과제 단위 비교 벤치마크의 현재 표본을 다루는 제목
|
||||
level: 3
|
||||
purpose: 정의된 과제 수와 실제 실행 표본의 격차, 그리고 관측된 동률 결과를 정확히 전달한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 정의된 과제 수와 실행된 표본 수의 대비
|
||||
- 표본이 한 카테고리·저난도에 몰려 있다는 사실
|
||||
- 측정된 지표 수와 미측정 지표 수
|
||||
- 관측된 차이가 없다는 결과와 그로부터 도출되는 결론
|
||||
- 비교 보고 파일이 재생성물이라는 점
|
||||
|
||||
- id: bench-cascade
|
||||
title-guidance: 워크플로 단위 비교 인프라의 구현 상태를 다루는 제목
|
||||
level: 3
|
||||
purpose: 측정 인프라가 만들어졌으나 파일럿이 실행되지 않았다는 상태를 오해 없이 전달한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 비교 대상 arm 구성과 고정 방식
|
||||
- 배선된 서브커맨드와 미구현 서브커맨드의 구분 및 종료 코드
|
||||
- 실행 산출물이 저장소에 없다는 사실
|
||||
- 공정성 통제 장치와 예산 게이트의 존재
|
||||
- 파일럿이 통계적 우월성을 확정하지 않는다는 명시된 단서
|
||||
- 설계에서 의도적으로 미룬 항목들
|
||||
|
||||
- id: limitations
|
||||
title-guidance: 도입 전에 받아들여야 할 현재 한계를 모으는 제목
|
||||
level: 2
|
||||
purpose: 강제 경계, 상태 불일치, 미완성 계층을 근거와 영향으로 연결해 과장 없이 밝힌다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 워킹 트리와 추적본의 차이가 독자에게 미치는 영향
|
||||
- 강제가 특정 런타임 세션 조건에서만 성립한다는 경계
|
||||
- 2차 방어선의 자기 선언된 취약성
|
||||
- 회사 문맥의 잠정 상태와 미해결 입력이 결정에 주는 제약
|
||||
- 비어 있는 문맥 폴더와 저장소 내부 문서 불일치
|
||||
- 워크스페이스 포인터가 채워져 fail-closed가 약해진 현재 상태
|
||||
- 자동 판정 범위 밖에 있는 품질 영역과 외부 도구 의존
|
||||
- 각 한계를 근거 위치와 함께 한 줄씩 제시
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 한계를 전달하는 데 시각화가 필요한가?
|
||||
rationale: 한계는 근거와 영향을 짝지어 읽어야 하는 정보이고, 도식화는 개별 항목의 정확도를 떨어뜨린다.
|
||||
|
||||
- id: contributing
|
||||
title-guidance: 기여자가 무엇을 고치고 무엇을 재생성하는지 안내하는 제목
|
||||
level: 2
|
||||
purpose: 원본과 생성물을 구분해 잘못된 위치를 수정하는 기여를 막는다.
|
||||
required: false
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 생성물 디렉터리를 직접 수정하지 말라는 규칙과 올바른 수정 위치
|
||||
- 규칙 변경 후 재생성·재검증에 사용할 명령 순서
|
||||
- 변경이 통과해야 하는 자동 검증 항목
|
||||
- 계약 활성화 기록에 남는 항목
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 기여 절차를 이해하는 데 그림이 필요한가?
|
||||
rationale: 원본에서 생성물로 이어지는 짧은 선형 절차라 번호 목록이면 충분하다.
|
||||
|
||||
- id: reference
|
||||
title-guidance: 계약 원본과 상세 문서로 이동시키는 제목
|
||||
level: 2
|
||||
purpose: 세부 내용을 본문에 복제하지 않고 목적별로 정본 파일에 연결한다.
|
||||
required: false
|
||||
content-strategy: summary-link
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 워크플로·역할·권한·실행 정책 정본 파일 링크
|
||||
- 명령·훅·스키마·테스트 디렉터리 링크
|
||||
- 벤치마크 정의와 정책 파일 링크
|
||||
- 각 링크에 한 줄 용도만 붙이고 내용은 복제하지 않음
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 정본 파일을 찾는 데 그림이 필요한가?
|
||||
rationale: 목적별 링크 목록이 탐색과 유지보수에 가장 적합하다.
|
||||
children:
|
||||
- id: design-history
|
||||
title-guidance: 설계 이력 문서로만 연결하는 제목
|
||||
level: 3
|
||||
purpose: 설계 spec과 구현 plan의 존재만 알리고 본문 복제를 차단한다.
|
||||
required: false
|
||||
content-strategy: external-only
|
||||
target-doc: docs/superpowers/
|
||||
content-requirements:
|
||||
- spec과 plan 디렉터리의 역할 구분만 제시
|
||||
- 개별 문서 내용의 요약이나 인용은 하지 않음
|
||||
|
||||
- id: license
|
||||
title-guidance: 사용·재배포 조건의 현재 상태를 밝히는 제목
|
||||
level: 2
|
||||
purpose: 라이선스 파일의 부재라는 관측 사실만 전달하고 조건을 추정하지 않게 한다.
|
||||
required: false
|
||||
content-strategy: inline
|
||||
target-doc: null
|
||||
content-requirements:
|
||||
- 저장소 루트에 라이선스 파일이 없다는 관측 사실
|
||||
- 허용 범위를 추정하거나 특정 라이선스를 암시하지 않음
|
||||
@@ -0,0 +1,46 @@
|
||||
schema-version: 1
|
||||
target:
|
||||
repository: /home/donghyeon/workspace/ai-tool/company-haness
|
||||
readme-path: README.md
|
||||
mode: bootstrap
|
||||
profile-override: generic
|
||||
project-intent:
|
||||
purpose: 대상 저장소의 핵심 운영 흐름, 구조, 검증 방법을 실제 파일 근거에 맞춰 설명한다.
|
||||
positioning: AI 에이전트 기반 회사 운영 하네스를 처음 접하는 사용자와 기여자를 위한 저장소 진입 문서다.
|
||||
maturity: 현재 저장소에서 확인되는 구현과 한계를 과장 없이 문서화한다.
|
||||
audience:
|
||||
primary:
|
||||
- 저장소를 처음 사용하는 운영자와 개발자
|
||||
- 하네스에 기여하려는 개발자
|
||||
secondary:
|
||||
- 에이전트 워크플로와 산출물 계약을 검토하는 기술 리더
|
||||
reader-actions:
|
||||
- 프로젝트의 목적과 적용 범위를 빠르게 파악한다.
|
||||
- 대표 진입점과 최소 사용 흐름을 선택한다.
|
||||
- 주요 디렉터리와 산출물 위치를 찾는다.
|
||||
- 저장소가 정의한 검증 명령과 현재 한계를 확인한다.
|
||||
content-policy:
|
||||
language: ko-KR
|
||||
tone: 간결하고 기술적이며 검증 수준을 명시하는 설명체
|
||||
target-length: long
|
||||
preserve-existing-copy: false
|
||||
detail-docs-policy: summary-and-link
|
||||
visual-policy:
|
||||
mode: when-useful
|
||||
max-visuals: 1
|
||||
preferred-formats:
|
||||
- mermaid
|
||||
placeholder-format: HTML 주석 기반 제작 사양
|
||||
must-include:
|
||||
- 프로젝트 개요와 대상 독자
|
||||
- 대표 워크플로 진입점과 선택 기준
|
||||
- 저장소 구조와 주요 책임
|
||||
- 최소 사용 절차
|
||||
- 검증 명령과 검증 수준
|
||||
- 산출물 위치
|
||||
- 현재 한계
|
||||
must-exclude:
|
||||
- 저장소 근거가 없는 기능·버전·성능 우위 주장
|
||||
- 비밀 값 또는 개인 환경의 절대 경로
|
||||
- 상세 설계 이력의 장문 복제
|
||||
protected-sections: []
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"git-sha": "00db337cfb3a22feb0b4d8529f23d72067f9ce16",
|
||||
"dirty": true,
|
||||
"diff-hash": "sha256:f67f7223c7fd7123f3cdef81d251ad96cb75fd6e8c7a6208777721c2576b6cda",
|
||||
"scanned-at": null,
|
||||
"file-count": 784
|
||||
}
|
||||
@@ -0,0 +1,888 @@
|
||||
schema-version: 1
|
||||
verdict: NEEDS_FIX
|
||||
score: 85
|
||||
|
||||
# ATTESTATION GAP — 이 리뷰를 수행한 실행 환경에는 셸이 없어(Read/Grep/Glob/Write만 가용)
|
||||
# content-hash 값을 계산할 수 없었다. 64자리 hex를 임의로 채우는 것은 증거 날조이므로
|
||||
# 모든 content-hash를 검증기가 반드시 거부하는 자리표시자로 남긴다.
|
||||
# 드라이버는 아래 좌표(artifact · line-start · line-end)로 해시를 채운 뒤 재검증해야 한다.
|
||||
# 좌표와 관찰 내용 자체는 실제 파일을 읽고 확인한 것이다.
|
||||
|
||||
scores:
|
||||
project-specificity:
|
||||
score: 5
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: overview
|
||||
line-start: 6
|
||||
line-end: 10
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
첫 세 문단이 다른 저장소에 재사용될 수 없다. org-os/ 정본, 개발과 GTM 동시 적용,
|
||||
.claude 단일 어댑터라는 구분자가 즉시 나온다(F-IDENTITY-CORE,
|
||||
F-IDENTITY-RUNTIME-COUPLING).
|
||||
- artifact: README.candidate.md
|
||||
section-id: repo-map-claude
|
||||
line-start: 343
|
||||
line-end: 359
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
수치가 전부 이 트리의 실측값이고 재추출로 갱신됐다. 카드 75개(43+19+10+3),
|
||||
resolver·router 0개, 훅 40개, 테스트 32개가 F-ARCH-AGENT-CARD-COMPOSITION과
|
||||
F-LIMIT-CONCURRENT-REFACTOR의 13:36 관측과 일치한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: limitations
|
||||
line-start: 591
|
||||
line-end: 596
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
한계가 일반론이 아니라 이 트리의 고유 상태다. 추적 카드 72 대 워킹 트리 75,
|
||||
미커밋 fam-*.md 26개, 미배선 신규 훅, doctor 14번째 섹션의 성격까지 짚는다.
|
||||
해소된 CLAUDE.md 73-75 드리프트를 F-LIMIT-DOC-DRIFT의 RESOLVED 처리에 맞춰
|
||||
본문에서 뺀 판단도 옳다.
|
||||
reader-journey:
|
||||
score: 4
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: overview
|
||||
line-start: 18
|
||||
line-end: 18
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
R-006이 해소됐다. 개요의 provenance가 두 문단에서 한 문장으로 줄었고 HEAD 해시와
|
||||
변경 항목 수는 검증 절 L442로 옮겨졌다. readme-outline overview의 '범위 고지를
|
||||
개요 단계에서 한 번 선언' 요구와 이제 일치한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: verification
|
||||
line-start: 421
|
||||
line-end: 518
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
감점 근거는 무게 이동이다. 검증 장치가 4개 하위 절 약 100행으로 문서에서 가장 두꺼운
|
||||
블록이 됐고, 등급 어휘는 L39 약속 · L426 표 · L500-518 정의 세 곳에 흩어져 있다.
|
||||
5분 독자가 '이걸 돌려도 되나'를 판정하려면 세 곳을 왕복해야 한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: first-command
|
||||
line-start: 89
|
||||
line-end: 95
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
첫 명령이 '현재 트리의 판정은 확인되지 않았습니다'로 끝난다. 정직하지만 첫 실행
|
||||
독자가 가져갈 현재 성공 신호는 exit 0과 verdict OK뿐이고, 그 점을 문장으로
|
||||
정리해 주지 않는다.
|
||||
technical-explanation:
|
||||
score: 4
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 122
|
||||
line-end: 126
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
R-001의 근본 원인이 해소됐다. 과잉 일반화된 옛 C-HUMAN-POINTS가 plan별 토큰 지도로
|
||||
교체돼 human-gate(cascade·wave), human-acceptance-receipt-present(venture-bootstrap),
|
||||
human- 리터럴 없음(light·design-direction)을 구분한다. F-WORKFLOW-HUMAN-GATE-MAP과
|
||||
1대1로 대응한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflow-wave-light
|
||||
line-start: 245
|
||||
line-end: 251
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
네 문장이 게이트 기제를 단계별로 분해한다. wave·light가 verification에서 cascade와
|
||||
같은 게이트를 쓴다는 점, wave.acceptance의 exit gate 문자열이 cascade와 동일하다는 점,
|
||||
light에는 released 자리가 없다는 점, 빈 exit gate가 종단 표시라는 점이 각각 별도
|
||||
claim으로 분리됐다. 마지막 C-TERMINAL-SHAPE가 '빈 게이트=통제 없음' 오독을 차단한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: limitations
|
||||
line-start: 595
|
||||
line-end: 595
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'점검 영역이 14개라는 사실이 14개 영역의 런타임 강제를 뜻하지는 않는다'는 문장은
|
||||
점검 대상과 강제 배선을 구분한 드문 서술이다. F-VERIFY-DOCTOR-EXECUTED의
|
||||
section-14-detail caveat를 정확히 옮겼다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: verification
|
||||
line-start: 426
|
||||
line-end: 434
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
감점 근거는 새 등급 체계가 자기 정의를 어긴 점이다. L504-508이 등급은 셋이라고
|
||||
선언했는데 표의 '검증 수준' 칸은 네 번째 값 '현재 트리에서 실행하지 않음'을 쓴다(R-101).
|
||||
task-usability:
|
||||
score: 4
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: prerequisites
|
||||
line-start: 44
|
||||
line-end: 53
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
전제조건 표가 최소 버전·확인된 버전·없을 때의 결과를 함께 줘서 설치 전에 자기 환경을
|
||||
판정할 수 있다(F-PREREQ-TOOLS). 리팩터의 영향을 받지 않은 부분이고 그대로 유지됐다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: verify-commands
|
||||
line-start: 467
|
||||
line-end: 475
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
13:36에 다시 돌린 네 명령은 명령·출력 문자열·종료 코드·기준 시점을 모두 갖췄다.
|
||||
gen_agents --check가 확인하지 않는 범위까지 적어(L471) 도구의 한계를 함께 준다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: first-command
|
||||
line-start: 91
|
||||
line-end: 95
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
감점 근거는 첫 명령의 판정 기준이다. L39가 '명령마다 검증 수준을 함께 적었습니다'라고
|
||||
약속하지만 이 명령에는 등급 표기가 없고, 제시된 출력 '35 OK'는 13개 섹션 시절의
|
||||
것이다(R-101, R-105).
|
||||
prose-clarity:
|
||||
score: 4
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflow-wave-light
|
||||
line-start: 231
|
||||
line-end: 231
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
R-003이 해소됐다. 절 제목의 plan 이름이 인라인 코드로 바뀌어 KO-ENGLISH-HEADING
|
||||
경고 2건(옛 P-014·P-015)이 prose-report.json에서 사라졌다. 경고 총계는 53에서 44로
|
||||
줄었고 errors는 0이다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: operating-model
|
||||
line-start: 25
|
||||
line-end: 30
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
R-002의 핵심 지점이 반영됐다. 운영 원리 6항의 계약 키가 인라인 코드로 바뀌었고,
|
||||
일반명사였던 caller는 '호출자'로, defense-in-depth는 '심층 방어(defense-in-depth)'로
|
||||
정리돼 식별자와 개념어가 구분된다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: verify-commands
|
||||
line-start: 463
|
||||
line-end: 463
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
감점 근거는 잔여 밀도다. R-002가 지목한 두 곳만 고쳐 이 문장이 문서에서 가장 조밀한
|
||||
맨 영문 줄로 남았다. KO-UNMARKED-ENGLISH-DENSITY P-026이 한 문장에서 10개 토큰을
|
||||
집계한다(R-108).
|
||||
- artifact: README.candidate.md
|
||||
section-id: bench-cascade
|
||||
line-start: 577
|
||||
line-end: 577
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
KO-VAGUE-BENEFIT P-036을 전 심사가 오탐으로 판정하고 그대로 뒀는데, 절반만 맞다.
|
||||
두 번째 문장('통계적 우월성을 확정하지 않습니다')은 구체적 부정 단서가 맞지만 앞의
|
||||
'설계 문서가 붙인 단서도 분명합니다'는 예고 문장이다(R-110).
|
||||
visual-judgment:
|
||||
score: 4
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 146
|
||||
line-end: 155
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
R-001의 시각 결함이 해소됐다. wave의 acceptance -> released에 cascade와 같은 육각형
|
||||
human-gate 노드(wg)가 놓여 두 경로가 같은 통제를 받는다는 점이 대비 없이 읽힌다.
|
||||
F-WORKFLOW-WAVE-LIGHT의 wave-vs-cascade-acceptance와 일치한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 157
|
||||
line-end: 162
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
light의 '게이트 없음' 오독은 재배치가 아니라 실제로 닫혔다. l3 -> l4 간선이
|
||||
cascade·wave와 같은 quality-gate-passed 라벨을 달았고, 종단 노드가 자기 사유
|
||||
'terminal-stage · released 전이 없음'을 스스로 적는다. 도형도 released 종단과 같은
|
||||
stadium이라 C-TERMINAL-SHAPE의 규칙성과 어긋나지 않는다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 164
|
||||
line-end: 174
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
venture-decision에 human-acceptance-receipt-present를 자기 리터럴로 표기한 판단이
|
||||
옳다. 승인 게이트는 육각형(cg·wg·vg), 사람 입력 선행조건은 평행사변형(vh)으로
|
||||
도형이 구분되므로 classDef human이 같은 색을 줘도 색맹 독자가 종류를 구별할 수 있다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 140
|
||||
line-end: 154
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
감점 근거는 R-001과 같은 모양의 잔여 비대칭이다. cascade에만 quality-gate-failed
|
||||
재작업 점선이 있고 wave·light에는 실패 경로가 없다. 근본 원인도 같다 —
|
||||
F-WORKFLOW-CASCADE와 F-WORKFLOW-DESIGN-DIRECTION에는 rework-transition 항목이
|
||||
있는데 F-WORKFLOW-WAVE-LIGHT에는 없다(R-109).
|
||||
|
||||
hard-gates:
|
||||
passed: true
|
||||
failures: []
|
||||
|
||||
reader-simulations:
|
||||
30-seconds:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: overview
|
||||
line-start: 6
|
||||
line-end: 10
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
무엇인가·왜 존재하는가 — '회사 운영을 AI 에이전트에게 분담시키는 파일 기반 운영체계'와
|
||||
계약을 파일로 고정하는 목적, 개발과 비즈니스를 같은 계약에서 다룬다는 범위를 세 문단에서
|
||||
얻는다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: overview
|
||||
line-start: 12
|
||||
line-end: 16
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
누구에게 필요한가 — 독자 표가 세 유형과 각자 이 문서에서 가져갈 결과를 직접 적는다.
|
||||
추론이 필요 없다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: overview
|
||||
line-start: 18
|
||||
line-end: 18
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
범위 고지가 한 문장으로 줄어 30초 독자의 판단을 더 이상 지연시키지 않는다. 전 심사
|
||||
R-006의 감점 사유가 사라졌다.
|
||||
5-minutes:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: operating-model
|
||||
line-start: 23
|
||||
line-end: 34
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
핵심 가치 — 계약 우선, 호출자 불신, 증거 receipt 대조, 2중 도구 경계를 기제 수준에서
|
||||
파악한다. 도입부 한 문장이 '계약 파일이 선언한 규칙이며 런타임 강제를 실행해 확인하지
|
||||
않았다'고 밝혀 전 심사 R-004가 해소됐다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: quick-start
|
||||
line-start: 39
|
||||
line-end: 103
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
실행 방법 — 설치·workspace·배선 확인·첫 명령이 끊김 없이 이어진다. 다만 L39가 약속한
|
||||
명령별 검증 수준 표기가 L92 doctor 명령에는 없다(R-101).
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 108
|
||||
line-end: 199
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
구조 — 표와 다이어그램이 다섯 plan을 단계·종단 상태·사람 승인 지점으로 비교시킨다.
|
||||
wave를 고른 독자가 '릴리스에 사람 승인이 필요 없다'는 잘못된 결론을 얻던 전 심사의
|
||||
5분 시뮬레이션 결함이 제거됐다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: limitations
|
||||
line-start: 591
|
||||
line-end: 604
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
한계 — 14개 항목이 근거와 영향을 짝지어 준다. 미검증 범위(스위트 통과 여부 UNKNOWN)와
|
||||
미커밋 삭제가 분리돼 있다.
|
||||
contributor:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: contributing
|
||||
line-start: 609
|
||||
line-end: 616
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
코드 추가 위치와 테스트 방법 — '정본을 먼저 고칩니다'가 role-registry와 06-agent-work를
|
||||
지목하고, 재생성·재검증 명령이 순서대로 주어진다. L355가 생성물 직접 수정을 금지한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: reference
|
||||
line-start: 627
|
||||
line-end: 641
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
상세 문서 이동 — 정본 파일 14개와 설계 이력 링크가 본문 복제 없이 연결된다.
|
||||
verification.json이 path 18/18, anchor 1/1 해결을 확인했다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: contributing
|
||||
line-start: 613
|
||||
line-end: 620
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
체크리스트 3항은 충족하나 조건부다. HEAD를 clone한 기여자가 이 절차를 그대로 따르면
|
||||
gen_agents.py가 문서와 다른 카드 집합을 만든다. 이 오해는 R-102로 별도 기록한다.
|
||||
|
||||
findings:
|
||||
- id: R-101
|
||||
severity: major
|
||||
category: verification-honesty
|
||||
subject: verification-level-grading
|
||||
section: verification
|
||||
message: >-
|
||||
등급(grade)과 기준 시점(currency)을 두 축으로 나눈 재구성은 방향이 옳지만, 그 축을
|
||||
싣고 있는 표가 자기 정의를 어긴다. L502는 '이 문서는 검증 결과를 세 등급으로 나눠
|
||||
표기합니다'라고 선언하고 L504-508이 세 등급을 정의한다. 그런데 L426 표의 '검증 수준'
|
||||
칸은 네 번째 값 '현재 트리에서 실행하지 않음'을 쓴다. 이것은 등급이 아니라 기준 시점
|
||||
진술이고, 바로 옆에 기준 시점 칸이 따로 있는데도 그 칸에는 '—'가 들어간다. 그 결과
|
||||
run_all.py와 doctor.py 행은 등급도 시점도 잃는다. 두 명령은 실제로 12:03에 실행됐으므로
|
||||
이 모델에서 정확한 표기는 등급 '이번 분석에서 실행한 결과' · 기준 시점 '12:03(무효)'이며,
|
||||
그 정보는 표 밖 L436에만 있다. 분리한 두 축을 정작 두 축이 필요한 행에서 합쳐 버린 셈이다.
|
||||
같은 결함이 약속 층위에서도 반복된다. L39는 '명령마다 검증 수준을 함께 적었습니다',
|
||||
L518은 '앞의 절에 나온 명령에도 같은 기준으로 등급과 기준 시점을 붙였습니다'라고 하지만,
|
||||
L92 doctor 명령과 L450 run_all.py 명령에는 등급 표기가 없다. pip install(L65)과 재생성
|
||||
명령(L618)에만 '(검증 수준: ...)'이 붙어 있다. readme-outline의 quick-start
|
||||
content-requirements '각 명령의 검증 수준을 quick-start 안에서 과장 없이 표기'와
|
||||
verify-levels의 '등급 표기를 다른 섹션의 명령에도 일관 적용한다는 약속'이 모두 미충족이다.
|
||||
수정은 새 사실 없이 가능하다. 표의 '검증 수준' 칸을 세 등급으로만 채우고 무효 사실은
|
||||
기준 시점 칸에 '12:03 — 현재 트리 아님'으로 옮긴 뒤, L92와 L450에도 같은 표기를 붙이면
|
||||
된다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: verification
|
||||
line-start: 432
|
||||
line-end: 433
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
두 행의 '검증 수준' 칸이 '현재 트리에서 실행하지 않음', 기준 시점 칸이 '—'다.
|
||||
'확인된 신호' 칸도 '현재 통과 여부 미확인'이어서 세 칸이 같은 말을 반복하고
|
||||
F-VERIFY-SUITE-EXECUTED가 보유한 12:03 결과는 표에 남지 않는다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: verify-levels
|
||||
line-start: 502
|
||||
line-end: 508
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
등급 어휘를 세 개로 못박은 정의표. 표에 쓰인 네 번째 값은 여기에 없다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: quick-start
|
||||
line-start: 39
|
||||
line-end: 39
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'명령마다 검증 수준을 함께 적었습니다'라는 약속. 같은 절 L92 명령에는 표기가 없다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: verify-levels
|
||||
line-start: 518
|
||||
line-end: 518
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'앞의 절에 나온 명령에도 같은 기준으로 등급과 기준 시점을 붙였습니다'는 진술이
|
||||
L92·L450에서 사실이 아니다.
|
||||
route-to: README_DRAFTED
|
||||
status: open
|
||||
|
||||
- id: R-102
|
||||
severity: major
|
||||
category: verification-honesty
|
||||
subject: head-clone-divergence
|
||||
section: contributing
|
||||
message: >-
|
||||
미커밋 상태에 대한 고지가 '파일 개수'까지만 도달하고 '명령의 동작'에는 도달하지 않는다.
|
||||
L592-593은 추적 카드 72 대 워킹 트리 75, 삭제된 fam-*.md 26개를 밝히고 'clone한 독자는
|
||||
이 문서가 설명하는 것과 다른 저장소를 받습니다'라고까지 적는다. 여기까지는 정직하다.
|
||||
문제는 기여 절차다. L609-616은 HEAD를 clone한 기여자에게 gen_agents.py 재생성과
|
||||
run_all.py 재검증을 그대로 지시하는데, 이 재작성이 근거로 삼은 사실에 따르면 HEAD의
|
||||
gen_agents.py는 워킹 트리의 것과 다른 프로그램이다. F-LIMIT-CONCURRENT-REFACTOR는
|
||||
gen_agents.py가 831행에서 537행으로 줄고 resolver/router/fam 카운터 코드가 제거됐다고
|
||||
기록하고, F-LIMIT-UNCOMMITTED-REGENERATION은 'gen_agents는 이제 75개 concrete 카드만
|
||||
생성하며 router/resolver/family 카드를 생성하지 않는다'고 기록한다. 즉 HEAD를 clone해
|
||||
L614를 실행한 기여자는 문서가 말한 75장이 아니라 다른 카드 집합을 얻고, 이어지는
|
||||
gen_agents.py --check도 문서에 실린 '75 concrete agents (profiles=75)'와 다른 값을 낸다.
|
||||
L357·L359의 카드 구성과 'resolver·router 각각 0개'도 그 독자에게는 성립하지 않는다.
|
||||
새 사실은 필요 없다. 이미 있는 두 사실을 근거로, 한계 절이나 기여 절에 '이 변경은 파일
|
||||
삭제만이 아니라 생성기 자체의 동작 변경을 포함하므로, HEAD를 clone한 뒤 재생성하면 이
|
||||
문서의 카드 수치가 재현되지 않습니다' 한 문장을 더하면 닫힌다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: contributing
|
||||
line-start: 613
|
||||
line-end: 618
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
재생성·재검증 명령 블록. HEAD clone 독자에게 이 절차가 문서와 다른 결과를 낸다는
|
||||
단서가 없다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: limitations
|
||||
line-start: 592
|
||||
line-end: 593
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
미커밋 고지가 카드 개수와 삭제 파일에만 걸려 있다. 생성기 동작 차이는 언급되지 않는다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: repo-map-claude
|
||||
line-start: 357
|
||||
line-end: 359
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
카드 구성 43/19/10/3과 'resolver·router 0개'는 워킹 트리 전용 값인데 절 도입부
|
||||
L343의 13:36 고지 범위가 표까지로 읽히기 쉬워 구조적 속성처럼 보인다.
|
||||
route-to: README_DRAFTED
|
||||
status: open
|
||||
|
||||
- id: R-103
|
||||
severity: major
|
||||
category: claim-integrity
|
||||
subject: commands-block-currency
|
||||
section: verification
|
||||
message: >-
|
||||
repository-facts.yaml의 commands 블록이 재추출을 따라가지 못해 같은 파일 안에서 서로
|
||||
모순된다. CMD-3에는 이번 재작업에서 '그 결과(35 OK)는 SUPERSEDED다 ... 현재 verdict는
|
||||
확인되지 않았다'는 무효 표시가 정확히 들어갔다. 그런데 같은 성격의 나머지 세 항목은
|
||||
그대로다. CMD-6의 limitations는 'ad-hoc 실행한 결과는 F-VERIFY-GENAGENTS-EXECUTED에
|
||||
기록됨(exit 0, 101 agents)'이라고 적는데, 그 F-VERIFY-GENAGENTS-EXECUTED는 이제
|
||||
'75 concrete agents ... (profiles=75)'를 기록한다. 참조와 피참조가 정면으로 어긋난다.
|
||||
CMD-2는 'exit 0, 34/34 green'을, CMD-8은 'run_all.py 전체 실행에는 포함됐고 green이었음'을
|
||||
무효 표시 없이 단정하지만 F-VERIFY-SUITE-EXECUTED의 current-pass-state는 UNKNOWN이다.
|
||||
README 본문은 이 오염을 물려받지 않았다 — L469가 75와 101을 시점과 함께 정확히 구분한다.
|
||||
그래서 독자 피해는 없고 심각도를 critical로 올리지 않는다. 그러나 commands 블록은
|
||||
claim-map이 참조하는 사실 원본이자 이후 refresh·audit이 읽는 입력이므로, 여기 남은
|
||||
'101 agents'와 '34/34 green'은 다음 실행에서 되살아날 수 있는 값이다. 이번 수정이
|
||||
한 곳(CMD-3)에만 적용되고 같은 종류의 나머지에 적용되지 않았다는 점 자체가 신호다.
|
||||
evidence:
|
||||
- artifact: repository-facts.yaml
|
||||
section-id: commands
|
||||
line-start: 1547
|
||||
line-end: 1557
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
CMD-6이 '(exit 0, 101 agents)'로 F-VERIFY-GENAGENTS-EXECUTED를 인용하지만 그 사실의
|
||||
stdout은 '75 concrete agents ... (profiles=75)'다.
|
||||
- artifact: repository-facts.yaml
|
||||
section-id: commands
|
||||
line-start: 1498
|
||||
line-end: 1508
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
CMD-2가 'exit 0, 34/34 green'을 무효 표시 없이 단정한다. 대응 사실의
|
||||
current-pass-state는 UNKNOWN이다.
|
||||
- artifact: repository-facts.yaml
|
||||
section-id: commands
|
||||
line-start: 1510
|
||||
line-end: 1521
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
대조 근거 — CMD-3에는 SUPERSEDED 표시가 정확히 들어갔다. 같은 처리가 CMD-2·6·8에는
|
||||
적용되지 않았다.
|
||||
- artifact: repository-facts.yaml
|
||||
section-id: commands
|
||||
line-start: 1569
|
||||
line-end: 1577
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
CMD-8이 'run_all.py 전체 실행에는 포함됐고 green이었음'이라고 적어 무효화된 실행을
|
||||
현재 상태처럼 서술한다.
|
||||
route-to: FACTS_EXTRACTED
|
||||
status: open
|
||||
|
||||
- id: R-104
|
||||
severity: minor
|
||||
category: claim-integrity
|
||||
subject: new-hook-module-count
|
||||
section: limitations
|
||||
message: >-
|
||||
L594의 '최상위 hook에 새 모듈 네 개가 나타났습니다'는 사실과 어긋난다.
|
||||
F-LIMIT-CONCURRENT-REFACTOR의 new-hook-modules는 usage_observer.py를 포함해 다섯 개이며,
|
||||
그중 네 개가 settings.json에 배선되지 않았다. 문장이 뒤에 네 개만 나열하므로 독자는
|
||||
'새로 나타난 모듈이 넷'으로 읽는데, 같은 문서 L373은 usage_observer.py가 13:36에 새로
|
||||
배선됐다고 적는다. 두 문장을 합치면 새 모듈은 다섯이다. 정확한 표기는 '새 모듈 다섯 개
|
||||
가운데 네 개는 배선돼 있지 않습니다'이며 새 사실이 필요 없다. 주목할 점은 대응 claim
|
||||
C-LIM-UNWIRED-HOOKS의 statement가 이 첫 문장을 제외하고 두 번째 문장만 담고 있다는
|
||||
것이다. 수치를 담은 문장이 claim 추적 밖에 있어 검증 대상이 되지 못했다(R-106과 같은 패턴).
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: limitations
|
||||
line-start: 594
|
||||
line-end: 594
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'새 모듈 네 개가 나타났습니다' — F-LIMIT-CONCURRENT-REFACTOR는 다섯 개를 기록한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: repo-map-claude
|
||||
line-start: 373
|
||||
line-end: 373
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
같은 문서가 다섯 번째 신규 모듈 usage_observer.py의 신규 배선을 별도로 서술한다.
|
||||
- artifact: claim-map.yaml
|
||||
section-id: limitations
|
||||
line-start: 936
|
||||
line-end: 941
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
C-LIM-UNWIRED-HOOKS의 statement가 '네 개' 문장을 제외해 부정확한 부분이 추적 밖에 있다.
|
||||
route-to: README_DRAFTED
|
||||
status: open
|
||||
|
||||
- id: R-105
|
||||
severity: minor
|
||||
category: verification-honesty
|
||||
subject: doctor-section-count
|
||||
section: first-command
|
||||
message: >-
|
||||
L89는 doctor.py가 14개 영역을 점검한다고 현재 값으로 적고, 여섯 줄 뒤 L95는 12:03 실행의
|
||||
'35 OK · 0 WARN · 0 FAIL'을 제시한다. 그런데 F-VERIFY-DOCTOR-EXECUTED에 따르면 그 35 OK를
|
||||
낸 실행 시점의 섹션 수는 13이고(section-count-historical), 14는 재추출 시점에 소스에서
|
||||
정적으로 확인한 현재 값이다(section-count-currency: CURRENT). 즉 인접한 두 수치가 서로
|
||||
다른 트리에서 왔는데 14 쪽에는 시점 표기가 없다. 문서가 '현재 트리의 판정은 확인되지
|
||||
않았습니다'로 보정하므로 오독의 폭은 크지 않지만, 첫 명령을 실행한 독자가 자기 출력의
|
||||
항목 수를 35와 대조하게 되는 자리다. 14에 시점을 붙이거나, 섹션 14가 12:03 이후 추가됐다는
|
||||
한 구절(F-VERIFY-DOCTOR-EXECUTED의 section-14-detail.added-by에 이미 있다)을 덧붙이면
|
||||
해소된다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: first-command
|
||||
line-start: 89
|
||||
line-end: 89
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'14개 영역'에 기준 시점 표기가 없다. 이 값은 13:36 정적 확인값이다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: first-command
|
||||
line-start: 95
|
||||
line-end: 95
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'35 OK · 0 WARN · 0 FAIL'은 섹션이 13개이던 12:03 실행의 출력이다. 두 수치가 같은
|
||||
트리에서 온 것처럼 인접해 있다.
|
||||
route-to: README_DRAFTED
|
||||
status: open
|
||||
|
||||
- id: R-106
|
||||
severity: minor
|
||||
category: claim-integrity
|
||||
subject: claim-statement-drift
|
||||
section: operating-model
|
||||
message: >-
|
||||
대규모 수정 과정에서 claim statement가 README 문장보다 좁아진 사례가 반복된다. 세 곳에서
|
||||
claim-id가 붙은 단락의 첫 문장 또는 둘째 문장이 claim statement에 포함되지 않았고,
|
||||
공교롭게 그 빠진 문장이 수치를 담은 쪽인 경우가 있다. (1) L23은 '이 하네스의 운영 원리는
|
||||
여섯 가지입니다'로 시작하지만 C-RULES-DECLARED의 statement는 두 번째 문장부터 시작한다.
|
||||
(2) L591은 '12:03과 13:36 두 시점의 추출값이 달랐고, 13:36 이후에도 값이 다시 달라졌을 수
|
||||
있습니다'라는 둘째 문장을 갖는데 C-LIM-CONCURRENT의 statement는 첫 문장뿐이다.
|
||||
(3) L594는 R-104가 지적한 '네 개' 문장을 갖는데 C-LIM-UNWIRED-HOOKS의 statement에는 없다.
|
||||
전 심사 R-007이 요구한 claim-id 부착 자체는 이행됐고(L23의 비교 프레이밍 제거, L361
|
||||
C-HOOK-EVENTS 신설) 이 항목은 그보다 좁은 잔여 문제다. claim statement가 실제 README
|
||||
문장과 1대1이 아니면 다음 refresh에서 추적 밖 문장이 소리 없이 바뀔 수 있다.
|
||||
evidence:
|
||||
- artifact: claim-map.yaml
|
||||
section-id: operating-model
|
||||
line-start: 30
|
||||
line-end: 35
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
C-RULES-DECLARED statement가 README L23의 첫 문장 '이 하네스의 운영 원리는 여섯
|
||||
가지입니다'를 포함하지 않는다.
|
||||
- artifact: claim-map.yaml
|
||||
section-id: limitations
|
||||
line-start: 918
|
||||
line-end: 923
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
C-LIM-CONCURRENT statement가 README L591의 둘째 문장(두 추출 시점과 그 이후 변동
|
||||
가능성)을 담지 않는다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: operating-model
|
||||
line-start: 23
|
||||
line-end: 23
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
한 줄에 두 문장이 있고 claim-id는 하나다. 덧붙여 '여섯 가지'가 인접 두 문장에서
|
||||
반복돼 정직성 문장이 길어진 만큼 읽기 부담이 늘었다.
|
||||
route-to: README_DRAFTED
|
||||
status: open
|
||||
|
||||
- id: R-107
|
||||
severity: minor
|
||||
category: prose-clarity
|
||||
rule-id: KO-UNMARKED-ENGLISH-DENSITY
|
||||
subject: worker
|
||||
section: repo-map-claude
|
||||
message: >-
|
||||
Writer의 반론을 인정한다. 맨 명사 worker를 인라인 코드로 감싸지 않은 판단은 옳다.
|
||||
gen_agents.py의 리터럴 키는 fan-out-workers처럼 복합어이고 worker 단독은 식별자가
|
||||
아니므로, 코드 표기는 존재하지 않는 식별자를 존재한다고 주장하는 셈이 된다.
|
||||
korean-reader-prose.md의 인라인 코드 규칙은 '파일·모듈·API·상태 값·제품명'을 대상으로
|
||||
하므로 일반명사에는 적용되지 않는다. P-019는 이 지점에서 오탐이다.
|
||||
다만 같은 논리가 같은 문장의 나머지에도 적용된다. `collapse concrete`, `direct
|
||||
single-member`, `synthesis lead`, 그리고 L359의 `family resolver`는 모두 공백으로 이어
|
||||
쓴 형태이고, F-ARCH-AGENT-CARD-COMPOSITION의 실제 키는
|
||||
collapse-concrete-workers·direct-single-member-workers·synthesis-leads·family-resolvers로
|
||||
하이픈 연결이다. 즉 이들도 리터럴이 아닌데 코드로 표기돼 있어 Writer 자신의 기준이 한
|
||||
문장 안에서 갈린다. 선택지는 둘이다. 하이픈 리터럴로 통일하거나(`fan-out`,
|
||||
`collapse-concrete`, `direct-single-member`, `synthesis-lead`), 이 자리를 카드 종류를
|
||||
가리키는 한국어 서술로 바꾸고 코드 표기를 걷어내는 것이다. 어느 쪽이든 새 사실이 필요 없다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: repo-map-claude
|
||||
line-start: 357
|
||||
line-end: 357
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
한 문장 안에서 공백형 다어절 3개는 코드 표기, 맨 명사 worker는 비표기다.
|
||||
prose-report P-019가 worker 3회를 집계한다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: repo-map-claude
|
||||
line-start: 359
|
||||
line-end: 359
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
`family resolver`도 공백형이다. 사실의 키는 family-resolvers다.
|
||||
route-to: README_DRAFTED
|
||||
status: open
|
||||
|
||||
- id: R-108
|
||||
severity: minor
|
||||
category: prose-clarity
|
||||
rule-id: KO-UNMARKED-ENGLISH-DENSITY
|
||||
section: verify-commands
|
||||
message: >-
|
||||
R-002가 지목한 두 위치(운영 원리 6항, 카드 구성 문장)는 고쳐졌으나 그 지적은 위치가
|
||||
아니라 원칙이었다. 원칙을 문서 전체에 적용하지 않아 L463이 이제 문서에서 가장 조밀한
|
||||
맨 영문 문장으로 남았다. P-026이 한 문장에서 settings, json, workspace, agent, SSOT,
|
||||
append-only, JSONL, compiled, artifact, registry 열 개 토큰을 집계한다. 이 가운데
|
||||
settings.json·SSOT·JSONL은 파일명·약어라 인라인 코드가 정보를 늘리고, compiled artifact
|
||||
registry는 앞서 L336에서 이미 설명한 대상이므로 그 표기를 재사용하면 된다. 나머지 잔여
|
||||
경고 대부분은 고유명사이거나 이미 코드 표기된 항목을 토크나이저가 재집계한 것으로,
|
||||
추가 조치가 필요 없다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: verify-commands
|
||||
line-start: 463
|
||||
line-end: 463
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
KO-UNMARKED-ENGLISH-DENSITY P-026 — 한 문장 10개 토큰. R-002 수정 범위 밖에 있었다.
|
||||
route-to: README_DRAFTED
|
||||
status: open
|
||||
|
||||
- id: R-109
|
||||
severity: minor
|
||||
category: architecture-mismatch
|
||||
subject: wave-light-rework-transitions
|
||||
section: workflows
|
||||
message: >-
|
||||
R-001을 낳은 추출 공백이 인접한 축에 그대로 남아 있다. F-WORKFLOW-CASCADE에는
|
||||
rework-transition('verification -> build, quality-gate-failed')이 있고
|
||||
F-WORKFLOW-DESIGN-DIRECTION에는 rework-transitions 두 개가 있는데,
|
||||
F-WORKFLOW-WAVE-LIGHT에는 재작업·실패 전이 항목 자체가 없다. 그 결과 다이어그램은
|
||||
cascade에만 quality-gate-failed 점선을 그리고 wave·light에는 실패 경로를 그리지 않는다.
|
||||
이것은 R-001과 같은 모양의 구조다 — 나란히 놓인 경로에서 한쪽에만 그린 간선은 다른 쪽에
|
||||
그 전이가 없다는 적극적 암시로 읽힌다. 다만 R-001과 달리 본문이 wave·light의 실패 경로를
|
||||
단정하지 않고, 두 경로 모두 verification 게이트를 공유한다는 사실은 L245가 명시하므로
|
||||
독자가 얻는 오해의 폭이 작다. 그래서 critical이 아니라 minor로 기록한다. 조치는
|
||||
FACTS_EXTRACTED에서 wave·light의 side-transition과 재작업 전이 유무를 정본에서 확인해
|
||||
확정하는 것이다. 확인 전까지는 '있다'로도 '없다'로도 읽히지 않게 두어야 한다. 심사자
|
||||
관찰이며 새 사실 정의가 아니다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 140
|
||||
line-end: 141
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
cascade는 quality-gate-passed 정방향과 quality-gate-failed 점선 재작업을 함께 그린다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 150
|
||||
line-end: 154
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
wave는 quality-gate-passed 정방향과 loop-stage 자기순환만 있고 실패 전이가 없다.
|
||||
light(L160-161)도 같다. 근거 공백은 F-WORKFLOW-WAVE-LIGHT에 rework 항목이 없다는 점이다.
|
||||
route-to: FACTS_EXTRACTED
|
||||
status: open
|
||||
|
||||
- id: R-110
|
||||
severity: minor
|
||||
category: prose-clarity
|
||||
rule-id: KO-VAGUE-BENEFIT
|
||||
section: bench-cascade
|
||||
message: >-
|
||||
설명 예고 문장이 누적된다. quality-review.md가 흔한 결함으로 꼽는 '설명할 내용을 예고한
|
||||
뒤에 사실을 말하는' 형태다. L577 '설계 문서가 붙인 단서도 분명합니다', L471 '이 점검이
|
||||
확인하지 않는 것도 분명합니다', L440 '두 명령을 다시 돌리지 않은 이유가 있습니다',
|
||||
L84 '주의할 점이 있습니다'가 모두 뒤 문장을 예고만 하고 정보를 더하지 않는다. 이 가운데
|
||||
L440과 L577은 이번 재작업이 늘린 문장이라, 정직성 서술이 진실해진 것 이상으로 길어졌다는
|
||||
신호로 읽힌다. 전 심사가 P-036을 오탐으로 판정한 것은 절반만 옳다. 지적된 두 문장 중
|
||||
뒤 문장('통계적 우월성이나 일반적 생산성 향상을 확정하지 않습니다')은 구체적 부정 단서가
|
||||
맞지만, 앞 문장은 KO-VAGUE-BENEFIT이 겨냥하는 바로 그 형태다. 예고 문장을 지우고 사실
|
||||
문장만 남기면 뜻이 줄지 않고 분량만 준다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: bench-cascade
|
||||
line-start: 577
|
||||
line-end: 577
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
KO-VAGUE-BENEFIT P-036이 두 문장을 함께 집계한다. 앞 문장이 예고, 뒤 문장이 사실이다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: verification
|
||||
line-start: 440
|
||||
line-end: 440
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'두 명령을 다시 돌리지 않은 이유가 있습니다' — 이번 재작업에서 추가된 예고 문장.
|
||||
뒤 문장이 이유를 온전히 담고 있다.
|
||||
route-to: README_DRAFTED
|
||||
status: open
|
||||
|
||||
# ── 전 심사 지적의 재검증 결과 ─────────────────────────────────────────────
|
||||
- id: R-001
|
||||
severity: critical
|
||||
category: architecture-mismatch
|
||||
subject: workflow-selection
|
||||
section: workflows
|
||||
message: >-
|
||||
해소됨. 사실 층위에서 근본 원인이 제거됐다. F-WORKFLOW-WAVE-LIGHT에 stage별 exit-gate가
|
||||
추가돼 wave.acceptance가 [release-approved, no-unresolved-critical-risks, human-gate]를
|
||||
갖는다는 점과 light.acceptance가 command null · exit-gate []인 종단이라는 점이 분리
|
||||
기록됐고, 새 사실 F-WORKFLOW-HUMAN-GATE-MAP이 plan별 사람 승인 토큰과 종단 stage 규칙성을
|
||||
확정했다. 다이어그램은 wave에 cascade와 동일한 육각형 human-gate 노드를 두어 비대칭을
|
||||
없앴고, venture-decision에도 자기 리터럴로 노드를 추가해 같은 결함이 한 plan 건너
|
||||
재발하는 것을 막았다. 본문은 C-HUMAN-POINTS를 plan별 토큰 지도로 교체하고
|
||||
C-WAVE-RELEASE-GATE·C-LIGHT-NO-RELEASE·C-TERMINAL-SHAPE를 신설했다. light가 '게이트가
|
||||
없다'로 읽히던 문제는 재배치가 아니라 실제로 닫혔다 — 공유 quality-gate-passed 간선을
|
||||
그리고 종단 노드가 자기 사유를 적기 때문이다. 잔여 사항은 R-109로 분리 기록한다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflows
|
||||
line-start: 151
|
||||
line-end: 153
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
w5 --> wg{{human-gate}} --> w6(released) — cascade L140-143과 도형·라벨이 같다.
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflow-wave-light
|
||||
line-start: 247
|
||||
line-end: 249
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
본문이 wave의 release exit gate 세 조건과 cascade와의 문자열 동일성을 명시하고,
|
||||
light에 자리가 없는 이유를 별도 문장으로 준다.
|
||||
route-to: FACTS_EXTRACTED
|
||||
status: resolved
|
||||
|
||||
- id: R-002
|
||||
severity: major
|
||||
category: prose-clarity
|
||||
rule-id: KO-UNMARKED-ENGLISH-DENSITY
|
||||
section: operating-model
|
||||
message: >-
|
||||
해소됨. 지목된 두 위치가 모두 반영됐다. 운영 원리 6항의 계약 키가 인라인 코드로 바뀌고
|
||||
caller는 '호출자', hook·validator·test는 '훅·검증기·테스트', push·pull request는
|
||||
한국어로, defense-in-depth는 '심층 방어(defense-in-depth)'로 정리됐다. 경고 총계는
|
||||
53에서 44로 줄었다. 원칙의 미적용 잔여분은 R-108로 분리 기록한다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: operating-model
|
||||
line-start: 25
|
||||
line-end: 32
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
6항 전체가 계약 키를 인라인 코드로 표기하고 일반명사는 한국어로 바뀌었다.
|
||||
route-to: README_DRAFTED
|
||||
status: resolved
|
||||
|
||||
- id: R-003
|
||||
severity: minor
|
||||
category: prose-clarity
|
||||
rule-id: KO-ENGLISH-HEADING
|
||||
section: workflow-wave-light
|
||||
message: >-
|
||||
해소됨. L231과 L269의 절 제목이 plan 식별자를 인라인 코드로 표기하고 child workflow라는
|
||||
맨 영문도 '하위 워크플로'로 바뀌었다. prose-report.json에 KO-ENGLISH-HEADING 항목이
|
||||
더 이상 없다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: workflow-wave-light
|
||||
line-start: 231
|
||||
line-end: 231
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'`wave`와 `light` — 축약 경로'. L269도 같은 방식으로 수정됐다.
|
||||
route-to: README_DRAFTED
|
||||
status: resolved
|
||||
|
||||
- id: R-004
|
||||
severity: minor
|
||||
category: verification-honesty
|
||||
section: operating-model
|
||||
message: >-
|
||||
해소됨. L23에 '아래 여섯 가지는 계약 파일이 선언한 규칙이며, 이 분석에서 런타임 강제를
|
||||
실행해 확인하지는 않았습니다'가 추가돼 강제 서술의 assertion-type이 명시됐다.
|
||||
제안된 문장과 사실상 같고 새 사실을 만들지 않았다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: operating-model
|
||||
line-start: 23
|
||||
line-end: 23
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
claim C-RULES-DECLARED가 F-ARCH-STATE-ARTIFACT·F-ARCH-HOOKS·F-LIMIT-HOOK-ACTIVATION을
|
||||
근거로 붙었다.
|
||||
route-to: README_DRAFTED
|
||||
status: resolved
|
||||
|
||||
- id: R-005
|
||||
severity: minor
|
||||
category: verification-honesty
|
||||
section: bench-cascade
|
||||
message: >-
|
||||
해소됨. L573에 'receipt가 있어도 실행되지는 않습니다. 세 서브커맨드 모두 현재 구현에서는
|
||||
exit 3, 즉 미구현을 반환합니다'가 신설돼(C-CASCADE-BUDGET-STUB) CMD-15 limitations가
|
||||
담고 있던 나머지 절반이 본문에 들어왔다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: bench-cascade
|
||||
line-start: 571
|
||||
line-end: 573
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
exit 2 거부와 exit 3 미구현이 연속 두 문장으로 붙어 있어 한 절 안에서 상충 인상이
|
||||
사라졌다.
|
||||
route-to: README_DRAFTED
|
||||
status: resolved
|
||||
|
||||
- id: R-006
|
||||
severity: minor
|
||||
category: reader-journey
|
||||
section: overview
|
||||
message: >-
|
||||
해소됨. 개요의 provenance 두 문단이 L18 한 문장으로 줄었고 HEAD 해시와 변경 항목 수는
|
||||
검증 절 L442로 이동했다. 이동 과정에서 수치도 재추출값(269 · 26)으로 갱신됐다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: verification
|
||||
line-start: 442
|
||||
line-end: 442
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
HEAD 00db337 · 변경/미추적 269 · 삭제 26이 검증 절로 옮겨졌고 F-IDENTITY-SNAPSHOT의
|
||||
13:36 값과 일치한다.
|
||||
route-to: README_DRAFTED
|
||||
status: resolved
|
||||
|
||||
- id: R-007
|
||||
severity: minor
|
||||
category: claim-integrity
|
||||
section: operating-model
|
||||
message: >-
|
||||
해소됨. L25의 비교 단정이 '이 하네스의 운영 원리는 여섯 가지입니다'로 바뀌어 근거 없는
|
||||
비교 프레이밍이 제거됐고, 훅 배선 문장에는 claim-id C-HOOK-EVENTS가 붙었다.
|
||||
claim statement 범위 문제는 R-106으로 분리 기록한다.
|
||||
evidence:
|
||||
- artifact: README.candidate.md
|
||||
section-id: repo-map-claude
|
||||
line-start: 361
|
||||
line-end: 361
|
||||
content-hash: "sha256:UNCOMPUTED-NO-HASH-TOOL-IN-REVIEW-ENVIRONMENT"
|
||||
observation: >-
|
||||
'훅은 이벤트 다섯 곳에 배선돼 있습니다. <!-- claim-id: C-HOOK-EVENTS -->' —
|
||||
claim-map에 F-ARCH-HOOKS 근거로 등재됐다.
|
||||
route-to: README_DRAFTED
|
||||
status: resolved
|
||||
@@ -0,0 +1,148 @@
|
||||
# 품질 심사 — company-haness README (20260720-rewrite)
|
||||
|
||||
- **판정: NEEDS_FIX**
|
||||
- 가중 점수: **82 / 100** (통과 기준 80)
|
||||
- Hard gate: **실패** — `architecture-mismatch`
|
||||
- 미해결 차단 항목: critical 1건, major 1건
|
||||
- 재개 지점(권고): `FACTS_EXTRACTED`
|
||||
|
||||
문장은 잘 편집돼 있고 정직성 요구도 대부분 지켰다. 그런데 다이어그램이 정본 계약과 다른 구조를
|
||||
보여주고 본문이 그것을 보정하지 않아, 거버넌스 통제 하나에서 독자가 잘못된 결론에 도달한다.
|
||||
글의 문제가 아니라 사실 추출의 구멍이며, 그래서 점수는 높은데 통과하지 못한다.
|
||||
|
||||
## 차원 점수
|
||||
|
||||
| 차원 | 가중치 | 점수 | 기여 | 한 줄 근거 |
|
||||
|---|---|---|---|---|
|
||||
| project-specificity | 25 | 5 | 25 | 첫 문단부터 수치·경로가 이 저장소에만 해당한다 |
|
||||
| reader-journey | 20 | 4 | 16 | 순서는 brief와 일치하나 개요가 분석 provenance로 무겁다 |
|
||||
| technical-explanation | 20 | 3 | 12 | 기제 설명은 강하나 wave의 사람 승인 기제가 통째로 빠졌다 |
|
||||
| task-usability | 15 | 5 | 15 | 전제조건·기대 출력·종료 코드·검증 수준이 모두 붙어 있다 |
|
||||
| prose-clarity | 15 | 4 | 12 | 번역투·홍보어 없음. 계약 키 표기만 일관되지 않다 |
|
||||
| visual-judgment | 5 | 2 | 2 | 포함 판단은 옳으나 위임받은 비교축에서 틀렸다 |
|
||||
| **합계** | **100** | | **82** | |
|
||||
|
||||
`prose-clarity` 4로 한국어 PASS 하한(4)은 충족한다. `visual-judgment` 2는 차원 최소치(3)에 미달한다.
|
||||
|
||||
## 독자 시뮬레이션
|
||||
|
||||
| 시뮬레이션 | 결과 | 요지 |
|
||||
|---|---|---|
|
||||
| 30초 | PASS | 정의(L6), 존재 이유(L6-8), 독자 표(L12-16)가 추론 없이 답을 준다 |
|
||||
| 5분 | PASS | 가치·실행·구조·한계 네 항목 모두 확인 가능. 단 wave 독자는 승인 게이트를 오해한 채 끝난다 |
|
||||
| 기여자 | PASS | 원본·생성물 경계(L288, L336), 재생성·재검증 명령(L559-562), 정본 링크가 모두 있다 |
|
||||
|
||||
## Hard gate
|
||||
|
||||
| 게이트 | 결과 |
|
||||
|---|---|
|
||||
| unsupported-high-risk-claim | 통과 — 우위 주장을 반복해 부정한다(L482, L501, L526) |
|
||||
| unrunnable-command-presented-as-verified | 통과 — 명령 5개에 등급 표기, 미실행 1개를 명시(L67, L409) |
|
||||
| wrong-module-description | 통과 |
|
||||
| architecture-mismatch | **실패 — R-001** |
|
||||
| invalid-link | 통과 — verification.json path 18/18, anchor 1/1 |
|
||||
| secret-leak | 통과 — 비밀 값 없음, 절대 개인 경로 없음 |
|
||||
| protected-content-modified | 해당 없음 (bootstrap, protected-sections 비어 있음) |
|
||||
| prompt-injection-accepted | 통과 — 저장소 내용을 지시가 아닌 데이터로 다뤘다 |
|
||||
|
||||
## 발견 사항
|
||||
|
||||
| id | 심각도 | 분류 | 절 | 요지 | 라우팅 |
|
||||
|---|---|---|---|---|---|
|
||||
| R-001 | critical | architecture-mismatch | workflows | wave 종단 전이의 사람 승인 게이트 누락 | `FACTS_EXTRACTED` |
|
||||
| R-002 | major | prose-clarity | operating-model | 계약 키 인라인 코드 표기 불일치 | `README_DRAFTED` |
|
||||
| R-003 | minor | prose-clarity | workflow-wave-light | 절 제목의 plan 식별자 코드 미표기 | `README_DRAFTED` |
|
||||
| R-004 | minor | verification-honesty | operating-model | 강제 기제가 검증 수준 없이 현재형 단정 | `README_DRAFTED` |
|
||||
| R-005 | minor | verification-honesty | bench-cascade | 예산 게이트가 exit 3 사실을 누락 | `README_DRAFTED` |
|
||||
| R-006 | minor | reader-journey | overview | 개요가 분석 provenance로 과부하 | `README_DRAFTED` |
|
||||
| R-007 | minor | claim-integrity | operating-model | 비교 프레이밍 문장에 claim-id·근거 없음 | `README_DRAFTED` |
|
||||
|
||||
### R-001 (critical) — wave 경로가 사람 승인 없이 릴리스되는 것처럼 보인다
|
||||
|
||||
다이어그램은 cascade의 `acceptance -> released`에 `human-gate 사람 승인 필요` 노드를 그리고,
|
||||
wave의 동일한 `acceptance -> released`에는 아무 노드도 두지 않는다(L140 대 L149-150).
|
||||
네 경로를 나란히 놓고 비교시키는 그림이므로 이 비대칭은 생략이 아니라 암시로 읽힌다.
|
||||
|
||||
본문도 보정하지 않는다. wave·light 절(L227-237)은 단계·명령·tier·종단 상태를 열거하면서
|
||||
exit gate를 한 번도 언급하지 않고, L124는 "사람 승인은 plan의 exit gate 조건으로 박혀 있습니다"라고
|
||||
일반화한 뒤 cascade만 예로 들어 나머지는 다르다는 인상을 남긴다. 결과적으로 독자는 같은 질문에
|
||||
대해 서로 반대 방향의 근거 없는 신호를 두 개 받는다.
|
||||
|
||||
근본 원인은 사실 추출이다. `F-WORKFLOW-CASCADE`는 `release-exit-gates`를 기록했지만
|
||||
`F-WORKFLOW-WAVE-LIGHT`는 같은 정본 파일에서 stage별 `exit-gate`를 추출하지 않았고, 그 공백이
|
||||
`visual-plan.yaml`의 avoid 규칙("wave·light 경로에 근거 없는 human-gate 노드를 추가하기")으로
|
||||
굳어져 다이어그램까지 전파됐다. Visual Planner는 주어진 사실 안에서 옳게 판단했다.
|
||||
|
||||
**심사자 관찰(사실 정의 아님)** — 정본 `org-os/06-agent-work/workflow-contracts.yaml`의
|
||||
`wave.acceptance` 행에는 cascade와 동일한 세 조건 exit-gate가 기재돼 있다. 따라서 이것은 근거
|
||||
부재가 아니라 추출 누락일 가능성이 높다. `FACTS_EXTRACTED`에서 wave·light 전 stage의 exit-gate를
|
||||
재추출해 확정한 뒤 다이어그램과 본문을 함께 고쳐야 한다.
|
||||
|
||||
### R-002 (major) — 계약 키를 인라인 코드로 표기하라
|
||||
|
||||
영문 용어를 한국어로 옮기라는 지적이 아니다. 이 용어들은 저장소 YAML 계약의 실제 키이므로
|
||||
번역하면 README와 코드의 대응이 깨진다. 요구하는 수정은 표기이며, 같은 문서가 L105와 L124에서
|
||||
이미 동일 성격의 값을 코드로 쓰고 있어 내부 불일치다.
|
||||
|
||||
**코드로 바꿀 것 —** L27 `capability` `artifact kind` `bundle` `exit gate` / L28 `gate fact`
|
||||
`artifact kind` `option count` `evidence grade` / L29 `family` `collapse` `fan-out` /
|
||||
L30 `fan-out` `subagent` / L31 `evidence ledger` `receipt` / L338 `worker` `fan-out`
|
||||
`collapse concrete` `direct single-member` `synthesis lead` `family resolver` `router`.
|
||||
|
||||
**한국어로 바꿀 것 —** L28 `caller`(앞 문장이 이미 "호출자"라 중복), L48 hook·validator·test →
|
||||
훅·검증기·테스트, L445 push·pull request, L32 defense-in-depth → "심층 방어"(원어 1회 병기).
|
||||
|
||||
**그대로 둘 것 —** Bradley-Terry, Elo, Chrome, Chromium, Marp, SHA-256, JSON Schema, Python,
|
||||
PyYAML, Node.js, D2, Claude Code.
|
||||
|
||||
## 정직성 요구 확인
|
||||
|
||||
이 재작성의 존재 이유였던 다섯 항목은 모두 이행됐다.
|
||||
|
||||
| 요구 | 결과 | 위치 |
|
||||
|---|---|---|
|
||||
| 워킹 트리 대 HEAD 범위 고지(추적 72 대 워킹 트리 101) | 이행 | L18-20, L411, L540 |
|
||||
| 검증 신뢰 등급 3단계 | 이행 — 3등급은 "해당 사례 없음"으로 비워 둠 | L465-475 |
|
||||
| 도구의 존재와 측정의 발생 분리 | 이행 — "측정 도구는 만들어져 있고, 측정은 거의 이뤄지지 않았습니다" | L482 |
|
||||
| 8개 중 6개 exit 3 stub과 파일럿 부재 | 이행 | L512-516 |
|
||||
| 골든 벤치마크 동률이 우위를 입증하지 않음 | 이행 | L499-501 |
|
||||
|
||||
`must-exclude` 3항도 위반이 없다. 우위·성능 주장 없음, 비밀 값 없음, 절대 개인 경로 없음
|
||||
(`hyeonworks`는 저장소 상대 워크스페이스 디렉터리명이다).
|
||||
|
||||
남은 정직성 흠은 두 개이며 모두 minor다. 강제 기제 서술에 검증 수준이 붙지 않았고(R-004),
|
||||
예산 게이트 문장이 exit 3 사실을 빠뜨렸다(R-005).
|
||||
|
||||
## 문체 경고 판단 (경고 53건, 오류 0건)
|
||||
|
||||
**결론: 일괄 면제도 아니고 일괄 수정도 아니다. 두 지점만 고치면 된다.**
|
||||
|
||||
밀도 경고 51건의 상당수는 저장소 YAML 계약의 실제 키를 가리킨다. 이것을 한국어로 번역하면
|
||||
README와 코드의 대응이 끊어지므로 번역은 오답이다. 그러나 그것은 "그대로 두라"는 근거가 아니라
|
||||
"인라인 코드로 표시하라"는 근거다. `korean-reader-prose.md`가 파일·모듈·API·상태 값·제품명을
|
||||
인라인 코드로 쓰라고 이미 정해 두었고, 이 문서 자체가 L105·L124에서는 그 규칙을 지키고 있다.
|
||||
지금 상태에서 독자는 어떤 문자열이 grep할 식별자이고 어떤 것이 일반명사인지 구분할 수 없다.
|
||||
|
||||
이것이 독자를 실제로 방해하는가 — 문서 전체로는 아니고, 두 지점에서는 그렇다.
|
||||
운영 원리 L27-32는 6개 원칙 중 5개가 연속 경고이며 문서의 개념 모델이 놓인 자리다.
|
||||
L338은 한 문장에 맨 영문 토큰이 11개로, 어느 것이 카드 종류의 리터럴 값인지 모르면 해석되지 않는다.
|
||||
그래서 이 두 곳만 major로 요구하고(R-002), 나머지 밀도 경고는 같은 원칙을 적용하면 함께 해소된다.
|
||||
|
||||
`KO-ENGLISH-HEADING` 2건도 번역 대상이 아니다. `wave`·`light`·`design-direction`은 plan
|
||||
식별자이므로 코드 표기가 답이다(R-003).
|
||||
|
||||
`KO-VAGUE-BENEFIT` 1건(P-044, L526)은 **오탐**이다. 해당 문장은 추상적 효용이 아니라
|
||||
"통계적 우월성을 확정하지 않는다"는 구체적 부정 단서이며, 이 문서에서 가장 정직한 문장 축에 든다.
|
||||
수정을 요구하지 않는다.
|
||||
|
||||
문체 자체는 좋다. 되어지다·~에 의해서·~에 있어서 같은 번역투 0건, 작성 과정 설명 0건,
|
||||
홍보성 수식어 0건이고 종결어미가 기계적으로 반복되지 않는다. `prose-clarity`를 4로 둔 이유이며,
|
||||
남은 결함은 문장력이 아니라 표기 일관성이다.
|
||||
|
||||
## 재작업 순서 (권고)
|
||||
|
||||
1. `FACTS_EXTRACTED` — wave·light 전 stage의 exit-gate를 정본에서 재추출한다 (R-001).
|
||||
2. `VISUALS_PLANNED` — 재추출 결과에 맞춰 avoid 규칙과 wave 경로 노드를 갱신한다 (R-001).
|
||||
3. `README_DRAFTED` — wave 절에 exit gate를 서술하고, R-002~R-007을 함께 처리한다.
|
||||
|
||||
라우팅은 권고이며 실제 재개 지점은 엔진이 발견 항목에서 다시 계산한다.
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"run-id": "20260720-rewrite",
|
||||
"repo-id": "company-haness",
|
||||
"mode": "bootstrap",
|
||||
"target-repository": "/home/donghyeon/workspace/ai-tool/company-haness",
|
||||
"harness-version": "0.1.0",
|
||||
"started-at": null,
|
||||
"tool-adapter": "claude",
|
||||
"input-hashes": {}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"mode": "bootstrap",
|
||||
"current": "INITIALIZED",
|
||||
"history": [
|
||||
{
|
||||
"state": "INITIALIZED"
|
||||
}
|
||||
],
|
||||
"rework": {
|
||||
"iterations": 0,
|
||||
"findings": {}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 5,
|
||||
"verified": 4,
|
||||
"manual-required": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 18,
|
||||
"verified": 18,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 1,
|
||||
"verified": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: pip install -r requirements.txt (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,72 @@
|
||||
schema-version: 1
|
||||
visuals:
|
||||
- id: workflow-selection
|
||||
section: workflows
|
||||
type: request-flow
|
||||
purpose: 하나의 진입 명령에서 갈라지는 네 plan과 cascade에 결속된 child workflow를 단계 진행·종단 상태·사람 개입 지점 기준으로 나란히 비교시켜 독자가 자기 작업에 맞는 경로 하나를 고르게 한다.
|
||||
placeholder-text: GitHub에서 렌더되는 순수 mermaid flowchart로, /ceo-intake 진입에서 cascade·wave·light·venture-bootstrap로 갈라지는 분기와 각 경로의 stage 사슬, 계약에 실제로 존재하는 사람 승인 토큰(cascade·wave의 human-gate, venture-bootstrap의 human-acceptance-receipt-present)과 사람 입력 선행조건, 서로 다른 종단 상태, 그리고 cascade에 parent-binding으로 매달린 design-direction child workflow를 한 화면에 배치한다.
|
||||
must-show:
|
||||
- 공통 진입 명령 /ceo-intake와 그 자리에서 mode·tier를 선언한다는 사실
|
||||
- cascade·wave·light·venture-bootstrap 네 plan이 /ceo-intake 하나에서 갈라지는 분기
|
||||
- design-direction은 /ceo-intake 분기에 속하지 않고 cascade에 결속된 child workflow라는 구분
|
||||
- plan별 stage 이름과 그 stage를 실행하는 slash command
|
||||
- plan마다 다른 종단 상태 released·acceptance·bootstrap-complete·design-direction-approved
|
||||
- cascade acceptance와 wave acceptance 양쪽에 동일하게 놓인 human-gate 사람 승인 지점
|
||||
- light가 verification에서 cascade·wave와 같은 quality-gate-passed 게이트를 거친다는 점
|
||||
- light의 acceptance가 terminal-stage이며 released로 가는 전이 자체가 없다는 점
|
||||
- venture-bootstrap venture-decision의 human-acceptance-receipt-present 사람 승인 지점
|
||||
- venture-bootstrap이 요구하는 founder-context.yaml filled 사람 입력 지점
|
||||
- cascade verification에서 build로 되돌아가는 quality-gate-failed 재작업 전이
|
||||
- wave의 run이 반복 단계라는 표시
|
||||
- light가 plan stage를 생략하고 acceptance에서 종료된다는 점
|
||||
- plan별 기본 tier(cascade standard·wave standard·light light)
|
||||
relationships:
|
||||
- /ceo-intake -> plan 선택 분기
|
||||
- plan 선택 분기 -> cascade
|
||||
- plan 선택 분기 -> wave
|
||||
- plan 선택 분기 -> light
|
||||
- plan 선택 분기 -> venture-bootstrap
|
||||
- cascade -> design-direction (parent-binding으로 결속된 child workflow, 점선)
|
||||
- intake -> discovery -> decide -> design -> spec -> build -> verification -> acceptance (cascade)
|
||||
- verification -> build (quality-gate-failed 재작업)
|
||||
- verification -> acceptance (quality-gate-passed, cascade·wave·light 공통)
|
||||
- acceptance -> human-gate 사람 승인 -> released (cascade)
|
||||
- intake -> plan -> run -> verification -> acceptance (wave)
|
||||
- acceptance -> human-gate 사람 승인 -> released (wave, cascade와 문자열이 동일한 exit-gate)
|
||||
- run -> run (wave loop-stage)
|
||||
- intake -> run -> verification -> acceptance (light, acceptance가 terminal-stage이고 released 전이 없음)
|
||||
- intake -> founder-setup -> 사람 입력 founder-context.yaml filled -> opportunity-discovery
|
||||
- opportunity-discovery -> venture-validation -> venture-decision
|
||||
- venture-decision -> human-acceptance-receipt-present 사람 승인 -> company-context-commit -> bootstrap-complete
|
||||
- design-direction-critique -> design-direction-prototype (critique-revision-requested)
|
||||
- design-direction-critique -> design-direction-divergence (concept-rejection-recorded)
|
||||
- design-direction-finalize -> design-direction-approved
|
||||
emphasize:
|
||||
- 계약의 사람 승인 토큰은 육각형, 사람 입력 선행조건은 평행사변형으로 그려 종류를 구분하고, 라벨에 '사람'과 토큰 리터럴을 함께 적어 색에 의존하지 않게 한다
|
||||
- cascade와 wave의 human-gate는 같은 도형·같은 라벨로 그려 동일한 통제임을 드러낸다(두 plan의 acceptance exit-gate 리스트는 문자열이 동일하다)
|
||||
- 사람 승인 노드는 우회 불가능한 필수 경유 지점으로 그린다(/run-cascade 드라이버도 이 지점에서 정지한다)
|
||||
- light에는 사람 노드를 두지 않되 verification의 quality-gate-passed를 표시해 게이트가 없는 것이 아니라 released 전이가 없을 뿐임을 드러낸다
|
||||
- 종단 stage의 빈 exit-gate는 '종단이라 다음 전이가 없음'이지 '게이트 없음'이 아니므로, light 종단에 terminal-stage 표기를 붙인다
|
||||
- 네 갈래의 종단 상태가 서로 다르다는 점을 종단 도형으로 구분해 한눈에 비교되게 한다
|
||||
- design-direction은 진입 분기가 아니라 cascade에서 내려오는 점선 종속 관계로만 연결한다
|
||||
- 재작업 전이는 점선으로 그려 정방향 stage 진행과 시각적으로 구분한다
|
||||
- stage 이름·명령명·상태 어휘는 원문 표기를 유지한다
|
||||
avoid:
|
||||
- design-direction을 /ceo-intake의 다섯 번째 분기처럼 그리기(applies-to에 포함되지 않는다)
|
||||
- 사람 승인 지점을 자동 전이나 AI 자동 승인처럼 표현하기
|
||||
- wave의 acceptance에서 human-gate를 빠뜨려 cascade에만 승인 노드가 있는 비대칭을 만들기 — wave.acceptance의 exit-gate는 cascade.acceptance와 문자열이 동일한 [release-approved, no-unresolved-critical-risks, human-gate]이고 둘 다 acceptance -> released 전이를 지킨다. 한쪽만 그리면 wave가 자동 release되는 것처럼 읽힌다
|
||||
- light에 사람 승인 노드를 추가하기 — light의 terminal-stage는 acceptance(command null · exit-gate [])이고 released 전이가 정의돼 있지 않아 release 사람 게이트가 놓일 자리가 없다
|
||||
- light의 빈 종단 exit-gate를 '게이트 없음'이나 '거버넌스 생략'으로 읽히게 그리기 — verification의 quality-gate-passed·blocker-open-false는 cascade·wave·light가 공유하고, 빈 exit-gate는 5개 plan의 모든 terminal stage가 공유하는 형태다
|
||||
- venture-bootstrap의 human-acceptance-receipt-present를 human-gate로 표기하기(그 리터럴은 해당 자리에 등장하지 않는 별개 토큰이다)
|
||||
- design-direction-finalize의 approved-direction-valid·approval-receipt-bound·parent-approval-link-recorded를 사람 승인 게이트로 표현하기(design-direction에는 human-* 리터럴이 없다)
|
||||
- workflow-contracts.yaml에 없는 stage·command·전이를 추가하기
|
||||
- 각 stage의 artifact 필드나 exit gate 전체 목록을 노드 안에 나열하기
|
||||
- 18개 slash command 전체를 그림에 넣어 선택 문제를 흐리기
|
||||
- 외부 테마·CSS·mermaid 자체 <br/> 외의 HTML 사용하기
|
||||
placement:
|
||||
after-section-id: workflows
|
||||
accessibility:
|
||||
alt-text: /ceo-intake로 진입해 mode와 tier를 선언한 뒤 cascade·wave·light·venture-bootstrap 네 plan으로 갈라지는 분기도. cascade는 intake·discovery·decide·design·spec·build·verification을 거치고 quality-gate-passed로 acceptance에 이른 뒤 사람이 승인하는 human-gate를 통과해야 released에 도달하며, verification에서 build로 되돌아가는 quality-gate-failed 재작업 전이가 있다. wave는 plan·run·verification·acceptance를 거치는데 run이 반복 단계이고, acceptance 다음에 cascade와 동일한 human-gate 사람 승인 노드를 통과해야 released에 도달한다. light는 plan 단계를 생략하고 verification에서 같은 quality-gate-passed를 거치지만 acceptance가 terminal-stage라 released로 가는 전이 자체가 없어 release 사람 게이트도 없다. venture-bootstrap은 founder-context.yaml이 filled여야 다음 단계로 진행되고, venture-decision 다음에 human-acceptance-receipt-present 사람 승인을 거쳐 company-context-commit으로 넘어가며 bootstrap-complete에서 company-context를 provisional 상태로 남긴다. design-direction은 진입 명령 분기가 아니라 cascade에 parent-binding으로 결속된 child workflow이며, critique에서 prototype 또는 divergence로 되돌아간 뒤 design-direction-approved로 끝난다.
|
||||
production:
|
||||
format: mermaid
|
||||
status: embedded
|
||||
Reference in New Issue
Block a user