donghyeon.kang/readme-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
c708cbcf9a700be954dbb545b5d2b1b23e62cfda
readme-haness/runs/company-haness/20260720-rewrite
T
History

README.candidate.md

Org OS 하네스

무엇을 운영하는 저장소인가

Org OS 하네스는 회사 운영을 AI 에이전트에게 분담시키는 파일 기반 운영체계입니다. 역할·워크플로·산출물 계약을 파일로 고정하고 org-os/ 디렉터리를 명세와 상태의 단일 원천으로 삼습니다.

적용 범위는 개발에 한정되지 않습니다. 제품·개발 작업과 GTM·수익 같은 비즈니스 작업을 같은 계약 위에서 함께 다룹니다.

실행 런타임은 Claude Code 하나입니다. subagent·project command·hook이 .claude 어댑터 한 곳에 배선돼 있고, 다른 에이전트 런타임용 어댑터 디렉터리는 저장소에 없습니다.

독자 이 문서에서 얻는 결과
저장소를 처음 쓰는 운영자·개발자 최소 설치 절차, 첫 실행 명령, 작업에 맞는 workflow 선택 기준
하네스에 기여하려는 개발자 원본과 생성물의 경계, 재생성·재검증 명령 순서
워크플로와 산출물 계약을 검토하는 기술 리더 계약 정본 위치, 검증 수준의 등급, 현재 근거의 한계

읽기 전에 범위를 하나 확인해 주십시오. 이 문서에 실린 검증 결과는 커밋된 HEAD가 아니라 2026-07-20 13:36 시점의 워킹 트리를 대상으로 합니다.

운영 원리

이 하네스의 운영 원리는 여섯 가지입니다. 아래 여섯 가지는 계약 파일이 선언한 규칙이며, 이 분석에서 런타임 강제를 실행해 확인하지는 않았습니다.

  1. 계약이 실행보다 먼저입니다. org-os/06-agent-work/workflow-contracts.yaml 한 파일이 단계 그래프, 역할 capability, artifact kind, bundle, exit gate를 함께 정의합니다.
  2. 상태 런타임은 호출자를 믿지 않습니다. 호출자가 넘긴 gate fact, artifact kind, option count, evidence grade를 그대로 받지 않고 제출된 불변 바이트에서 다시 파생합니다.
  3. 협업 형태는 산출물 종류가 결정합니다. 코드·실행 산출물을 만드는 family는 collapse로 묶고, 판단·설계·분석·수익 산출물을 만드는 family는 fan-out으로 나눕니다.
  4. fan-out은 메인 세션만 주도합니다. Orchestrator가 fan-out을 몰고 가며 subagent는 다른 subagent를 호출하지 못합니다.
  5. 근거 없는 주장은 통과하지 못합니다. 보고서 evidence 등급은 E0부터 E5까지이고, E4와 E5 주장은 evidence ledger의 실제 receipt와 대조해 receipt가 없으면 막습니다.
  6. 도구 경계는 두 겹입니다. 1차 경계는 Claude Code 네이티브 permission 시스템이고, guard_tools.py는 심층 방어(defense-in-depth) 목적의 2차 방어선입니다.

종합과 결정 지점에서 상위 역할은 하위 .report.yaml 전문을 읽습니다. 요약본으로 대체하는 것을 금지합니다.

검증자 패밀리는 자기 패밀리가 작성한 산출물을 검증하지 못합니다. heavy tier 병렬 감사는 독립 검증자를 최소 3명 요구하고, 다수가 반박하면 중단합니다.

최소 사용 절차

의존성 설치, workspace 지정, 배선 확인, 첫 명령 순서로 진행합니다. 명령마다 검증 수준을 함께 적었습니다. 등급의 뜻은 아래 검증 수준의 등급에서 정의합니다.

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 대체 경로로 냄

필수 도구가 없으면 하네스 자체가 돌지 않고, 권장·선택 도구가 없으면 해당 기능 경로만 줄어듭니다.

버전 대조는 .claude/hooks/doctor.py가 맡습니다. .claude/tool-versions.yaml을 읽어 런타임에 설치된 버전과 맞춰 봅니다.

저장소가 선언한 설치 명령은 하나이며 로컬과 CI가 같습니다. 

pip install -r requirements.txt

매니페스트는 PyYAML==6.0.1과 jsonschema==4.10.3 외에는 Python 표준 라이브러리만 쓴다고 선언합니다.

이 설치 명령은 파일에서 확인만 했고 이번 분석에서 실행하지 않았습니다(검증 수준: 저장소가 선언한 명령).

2. workspace 지정

산출물이 쓰일 위치는 ORGOS_WORKSPACE 환경변수를 먼저 보고, 없으면 .orgos-workspace 포인터 파일의 첫 유효 줄을 씁니다. 주석과 빈 줄은 건너뜁니다.

값이 상대 경로면 저장소 루트를 기준으로 해석하고, 절대 경로면 그대로 씁니다.

둘 다 해석되지 않으면 WorkspaceNotSetError가 납니다. require_workspace(advisory=False)를 쓰는 운영 훅은 exit 2로 fail-closed 종료합니다.

require_workspace(advisory=True)를 쓰는 계측 훅인 evidence_ledger.py는 경고만 남기고 None을 돌려주며 도구 실행을 막지 않습니다.

테스트와 CI는 명령마다 ORGOS_WORKSPACE=_sandbox를 명시하는 관례를 따릅니다. 

export ORGOS_WORKSPACE=_sandbox

주의할 점이 있습니다. 현재 워킹 트리의 .orgos-workspace는 hyeonworks로 채워져 있어, 환경변수를 지정하지 않아도 포인터가 해석되고 fail-closed가 걸리지 않습니다.

3. 배선 확인과 첫 명령

설치가 끝나면 배선부터 봅니다. .claude/hooks/doctor.py가 14개 영역을 점검하고 한 줄 판정으로 요약합니다. 

CLAUDE_PROJECT_DIR="$PWD" ORGOS_WORKSPACE=_sandbox python3 .claude/hooks/doctor.py

12:03 실행에서는 35 OK · 0 WARN · 0 FAIL과 verdict OK, exit 0이 나왔습니다. 이후 저장소가 바뀌었으므로 현재 트리의 판정은 확인되지 않았습니다.

배선이 정상이면 Claude Code 세션에서 /ceo-intake로 새 작업을 엽니다. 이 명령은 cascade, wave, light, venture-bootstrap 네 plan의 공통 진입점입니다.

/ceo-intake는 OPS-ORCH 역할이 실행하고 EXEC-CEO 역할이 작성하며, decision-brief와 workload-profile을 만듭니다.

이 단계에서 mode(divergent 또는 converge)와 tier(light, standard, heavy)를 선언합니다.

진입 단계의 exit gate는 세 조건을 요구합니다. decision-brief-present, workload-profile-present, company-context-ready입니다.

작업에 맞는 workflow 고르기

선언된 workflow plan은 cascade, wave, light, venture-bootstrap, design-direction 다섯 개입니다.

그래프 정본은 org-os/06-agent-work/workflow-contracts.yaml입니다. 같은 디렉터리의 execution-plans.yaml은 호환·문서용 mirror이며 런타임 정본이 아닙니다.

slash command는 모두 18개입니다. 그중 /ceo-intake 하나가 앞의 네 plan이 공유하는 진입점이고, design-direction은 cascade에 종속된 하위 워크플로라 자기 진입점을 씁니다.

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 리스트는 문자열이 같습니다.

venture-bootstrap은 venture-decision 단계에서 human-acceptance-receipt-present라는 별도 토큰을 씁니다. light와 design-direction의 exit gate에는 human- 리터럴이 없습니다.

/run-cascade 드라이버는 cascade를 순회하다 human-gate 지점에서 멈춥니다. 

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

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보다 앞선다는 것입니다.

design과 spec의 산출물은 고정 목록이 아니라 dynamic bundle입니다.

기본 tier는 standard이고 종단 단계는 released입니다.

verification 단계의 exit gate는 quality-gate-passed와 blocker-open-false입니다.

released 진입 exit gate는 release-approved, no-unresolved-critical-risks, human-gate 세 조건입니다.

품질 게이트가 실패하면 verification에서 build로 되돌아가는 재작업 전이가 있습니다. 이 전이의 필요 조건은 quality-gate-failed입니다.

wave와 light — 축약 경로

wave는 intake → plan → run → verification → acceptance → released 여섯 단계를 거치고, run이 반복 단계입니다.

wave가 쓰는 명령은 /ceo-intake, /plan-wave, /run-wave, /review-output, /release-check입니다.

light는 plan 단계를 생략하고 intake → run → verification → acceptance 네 단계로 끝납니다.

light가 쓰는 명령은 /ceo-intake, /run-wave, /review-output 세 개입니다.

light를 적용해도 되는 조건은 저위험·two-way-door·single-role이면서 고객·매출·보안 영향이 없는 작업입니다.

기본 tier는 wave가 standard, light가 light입니다. 종단도 달라서 wave는 released까지 가고 light는 acceptance에서 멈춥니다.

축약 경로라고 해서 검증 게이트가 빠지지는 않습니다. 두 경로 모두 verification 단계에서 quality-gate-passed와 blocker-open-false를 요구하며, 이는 cascade가 같은 단계에서 쓰는 게이트와 같습니다.

wave의 acceptance는 released로 전이하며 exit gate로 release-approved, no-unresolved-critical-risks, human-gate를 요구합니다. 이 리스트는 cascade의 acceptance와 문자열이 같습니다.

light에는 released 단계 자체가 없습니다. light의 acceptance가 종단 단계이고 command가 null이라, release 사람 게이트가 놓일 자리가 없습니다.

빈 exit gate를 게이트가 없다는 뜻으로 읽으면 안 됩니다. 다섯 plan의 종단 단계는 모두 command null과 빈 exit gate를 갖고, 이는 다음 전이가 없다는 표시입니다.

venture-bootstrap — 회사 수립 경로

이 경로는 사람 입력이 먼저 차야 시작됩니다. org-os/01-company/founder-context.yaml의 상태가 filled여야 합니다.

진입은 /ceo-intake --plan venture-bootstrap이고, 이어서 /venture-validate와 /company-bootstrap을 실행합니다.

단계는 intake, founder-setup, opportunity-discovery로 시작합니다. 이어서 venture-validation, venture-decision, company-context-commit을 거쳐 bootstrap-complete에서 끝납니다.

산출물은 org-os/01-company/company-context.yaml이고 발급 시점의 상태는 provisional입니다. 상태 어휘는 template, provisional, operating 세 가지입니다.

company-context-commit 단계는 exit gate 세 개를 요구합니다. company-context-provisional-committed, company-context-lint-passed, company-context-artifact-recorded입니다.

현재 저장소의 company-context.yaml은 provisional 상태입니다. operating이 아닌 동안 회사 관련 인용은 증거 등급 상한에 묶입니다.

design-direction — cascade에 종속된 하위 워크플로

design-direction은 독립 워크플로가 아니라 제품 cascade에 종속된 하위 워크플로입니다. 종단 상태는 design-direction-approved입니다.

부모와의 결속 키는 parent-workflow-id, product-decision-id, direction-input-brief-sha256 세 개입니다.

흐름은 불변 direction-input-brief에서 3안을 독립 발산한 뒤 하나로 수렴하고, 승자 prototype을 만들어 비평 루프를 거쳐 approved-direction을 냅니다.

재작업 전이는 두 종류입니다. critique-revision-requested이면 critique에서 prototype으로, concept-rejection-recorded이면 critique에서 divergence로 되돌아갑니다.

승인 payload는 부모·자식 workflow id와 제품 결정 id에 더해 입력 brief, 선택된 방향, 승자 prototype의 SHA-256을 함께 고정합니다.

보조 진입점

명령 용도
/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가 같으면 거부해 생산자와 검토자를 분리합니다.

/run-cascade는 평행 엔진 사용을 금지하는 얇은 드라이버입니다. 자동 승인과 자동 완주를 하지 않습니다.

각 명령의 상세 사용법은 .claude/commands/의 정의 파일에 있습니다.

저장소 구조

규칙의 원본은 org-os/에 있고, 그 규칙을 실행하는 코드는 .claude/에 있습니다. 고칠 위치를 찾을 때 이 경계를 먼저 봅니다.

경로 책임
org-os/ 명세와 상태의 단일 원천
.claude/ Claude Code 런타임 어댑터
benchmark/ golden task 벤치마크와 P4 cascade 벤치마크의 정본 입력
docs/superpowers/ 설계 spec과 구현 plan
_sandbox/ 테스트용 워크스페이스
hyeonworks/ 실제 제품 프로젝트 워크스페이스
repomix/ 소스에서 재생성되는 패킹 산출물

repomix/는 소스에서 다시 만드는 산출물이라 gitignore 대상입니다.

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개입니다.

역할 수는 role-registry.roles 항목만 셉니다. team topology, EA layer, workflow gate는 역할 수를 늘리지 않습니다.

역할별 method 절차의 원본은 org-os/00-role-registry/role-working-methods/이고, 라우팅은 method-skill-registry.yaml이 맡습니다.

계약 활성화 기록은 org-os/00-role-registry/method-contract-activations.yaml에 남습니다. skill 디렉터리 78개는 13:36 시점에 그대로 있었습니다.

계약 machinery 집계값은 12:03 doctor.py 출력에서 얻었고 그 뒤 재검증하지 않았습니다. 활성화 기록 파일이 그 사이 수정됐으므로 이 문서는 해당 수치를 싣지 않습니다.

컴파일된 artifact registry는 artifact kind 186개를 담고 .claude/hooks/compile_artifact_registry.py가 만듭니다. 산출 위치는 org-os/06-agent-work/generated/artifact-registry.yaml입니다.

회사 문맥 폴더 5개는 아직 README.md만 담고 있습니다. 02-capabilities, 03-products, 04-architecture, 05-operations, 07-knowledge-base가 여기 해당합니다.

.claude — 런타임 어댑터 계층

아래 규모는 모두 2026-07-20 13:36 시점의 관측값입니다. 저장소가 동시에 수정되던 중이라 안정된 속성이 아닙니다.

경로 책임 규모(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를 다시 실행합니다.

카드 75개의 구성은 fan-out worker 43개, collapse concrete worker 19개, direct single-member worker 10개, synthesis lead 3개입니다.

family resolver, router, family 메타데이터 카드는 이제 생성하지 않아 각각 0개입니다. 참조 역할 75개와 실행 가능한 concrete 카드 75개가 1대1로 대응합니다.

훅은 이벤트 다섯 곳에 배선돼 있습니다.

이벤트 스크립트 실패 정책
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입니다.

usage_observer.py는 13:36 재추출 시점에 새로 배선됐고, PreToolUse matcher에 WebFetch와 WebSearch가 추가됐습니다.

다른 에이전트 런타임용 어댑터가 없으므로, 진입점과 강제를 옮기려면 이 계층 전체를 새로 배선해야 합니다.

산출물과 증거

실행 결과·증거·상태는 저장소가 아니라 workspace 아래에 남습니다. 같은 명령이라도 workspace가 달라지면 기록 위치가 달라집니다.

산출 위치가 정해지는 방식

.orgos-workspace 포인터의 현재 값은 hyeonworks입니다. 과거에는 이 파일이 의도적으로 비어 있었습니다.

현재 워킹 트리에는 워크스페이스가 두 개 있습니다. _sandbox는 테스트·CI용이고 hyeonworks는 제품 프로젝트용입니다.

hyeonworks 아래에는 app, completion-records, design, design-direction, evidence, state가 있습니다. _sandbox 아래에는 completion-records, evidence, reports, state가 있습니다.

종류별 저장 위치

<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입니다.

.report.yaml은 덮어쓰기와 수정을 금지하며 guard_tools가 이를 강제합니다. 재작업도 new_report.py로 새 파일을 발급합니다.

실행 receipt는 <workspace>/evidence/ledger.jsonl에 쌓입니다. 실행한 명령과 종료 코드, stdout 해시, 기록된 산출물 경로와 SHA-256이 함께 남습니다.

계측 훅이 workspace를 해석하지 못하면 기록만 건너뛰고 도구 실행 자체는 막지 않습니다.

append-only 이벤트 원장은 workflow-events.jsonl, artifact-events.jsonl, acceptance-events.jsonl, human-signoff.jsonl 네 개입니다.

workflow.yaml은 이 이벤트들에서 만든 materialized view이며 버리고 다시 만들어도 되는 파생물입니다.

사람이 읽는 산출물은 render_report.py가 .report.yaml에서 MD로 만들고, reports/INDEX.md가 목차 역할을 합니다.

대시보드는 reports/TOKENS.md와 reports/KPI.md 두 개입니다. kpi_ledger는 각 KPI를 measured/derived, manual, unmeasured로 구분해 표기합니다.

검증 명령과 신뢰 범위

이 저장소는 사실 추출 도중에도 다른 세션이 수정하고 있었습니다. 그래서 검증 결과는 명령별로 기준 시점을 나눠 적습니다.

목적 명령 확인된 신호 검증 수준 기준 시점
생성 계약 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을 냈습니다. 그 결과는 현재 저장소에 대한 주장이 아닙니다.

그 사이 동시 리팩터가 agent 카드를 101개에서 75개로, 최상위 hook을 35개에서 40개로, test suite를 31개에서 32개로 바꿨습니다. 실행 대상이던 트리는 더 이상 존재하지 않습니다.

두 명령을 다시 돌리지 않은 이유가 있습니다. 동시 세션이 같은 _sandbox 워크스페이스에 같은 스위트를 실행 중이어서, 재실행하면 두 결과 모두 신뢰할 수 없게 됩니다.

분석 시점의 HEAD는 00db337이었고 워킹 트리에는 변경·미추적 항목이 269개, 삭제 항목이 26개 있었습니다.

로컬 검증 진입점

전체 스위트 진입점은 .claude/tests/run_all.py입니다. 저장소가 문서화한 호출 형태는 다음과 같습니다. 

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로 건너뜁니다.

테스트는 .claude/tests/test_*.py를 suite별로 순차 실행하며, suite마다 새 프로세스 그룹에서 시작하고 300초 제한을 둡니다. 13:36 시점의 파일 수는 32개입니다.

제한값은 ORGOS_TEST_TIMEOUT으로 바꾸고, 초과하면 SIGTERM 뒤 필요 시 SIGKILL로 프로세스 그룹을 정리합니다.

실패하거나 timeout된 suite가 하나라도 있으면 전체가 exit 1로 끝납니다.

12:03 실행 결과는 preflight 3개와 테스트 31개를 합쳐 34/34 green, exit 0이었습니다. 그 뒤 저장소가 바뀌었으므로 현재 트리의 통과 여부는 확인되지 않았습니다.

doctor.py가 보는 영역에는 settings.json 배선, workspace 해석, 커맨드에서 agent로 이어지는 참조 무결성이 들어갑니다. SSOT 소비 현황, append-only JSONL 원장 무결성, compiled artifact registry도 같은 점검에 들어갑니다.

doctor.py 자체가 이번 리팩터에서 수정됐고 배선과 카드도 함께 바뀌었습니다. 현재 트리의 판정은 확인되지 않았습니다.

생성 계약 점검은 gen_agents.py --check가 맡습니다. registry에서 만든 카드 집합이 개수·구조 계약을 만족하는지 확인합니다.

13:36 재실행은 exit 0으로 끝났고 75 concrete agents와 profiles=75를 보고했습니다. 12:03 실행은 같은 명령으로 101개를 보고했습니다.

이 점검이 확인하지 않는 것도 분명합니다. 디스크에 있는 .claude/agents/*.md 바이트와의 비교는 이 명령의 출력에 나타나지 않습니다.

참조 무결성 점검은 lint_refs.py가 맡습니다. 13:36 재실행에서 command 참조 18개와 agent skill 참조 75개가 모두 해결됐고 exit 0으로 끝났습니다.

compile_artifact_registry.py --check도 13:36에 다시 돌려 artifact kind 186개에 드리프트가 없음을 exit 0으로 확인했습니다.

자동 검증 경로

자동 검증은 .github/workflows/ci.yml의 harness-enforcers job이고 실행 환경은 ubuntu-latest입니다.

트리거는 main, fix/**, feat/** 브랜치 푸시와 main을 대상으로 하는 풀 리퀘스트입니다.

환경 설정은 CLAUDE_PROJECT_DIR을 github.workspace로, ORGOS_WORKSPACE를 _sandbox로 두고 Python 3.12와 Node 20을 씁니다.

실행 단계는 로컬 명령과 그대로 대응합니다.

  • 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 설치 단계는 실패해도 건너뛰도록 허용합니다.

이번 분석에서는 GitHub Actions 실행 이력을 조회하지 않았습니다. CI가 최근에 통과했는지는 이 문서로 확인되지 않습니다.

검증 수준의 등급

이 문서는 검증 결과를 세 등급으로 나눠 표기합니다.

등급 뜻 이 문서의 사례
저장소가 선언한 명령 파일에서 정적으로 추출했고 실행하지 않음 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 게이트를 통과한 결과가 아닙니다.

세 번째 등급에 해당하는 사례는 현재 이 문서에 없습니다.

등급과 별개로 기준 시점을 함께 봐야 합니다. 두 번째 등급이어도 실행 시점 이후 저장소가 바뀌었다면 그 결과는 현재 트리에 대한 주장이 아닙니다.

run_all.py와 doctor.py의 12:03 결과가 그런 경우입니다. 이 문서는 두 결과를 이력으로만 싣고 현재 상태의 근거로 쓰지 않습니다.

앞의 절에 나온 명령에도 같은 기준으로 등급과 기준 시점을 붙였습니다.

근거의 현재 상태

이 하네스가 더 나은 산출물을 낸다는 주장은 아직 성립하지 않습니다. 측정 도구는 만들어져 있고, 측정은 거의 이뤄지지 않았습니다.

과제 단위 벤치마크

golden task는 13개가 정의돼 있습니다. 카테고리는 code-bugfix, code-feature, refactor, docs, design, decision입니다.

이 개수는 13:36에 benchmark.py list를 다시 돌려 exit 0으로 확인했습니다.

실행된 표본은 plain 2개와 harness 2개뿐입니다. 대상 과제는 GT-01과 GT-R2 둘이고, 둘 다 code-bugfix 저난도이며 실행일은 2026-07-11입니다.

측정된 지표는 3개이고 미측정 지표는 8개입니다.

지표 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입니다.

이 표본은 하네스의 품질 우위를 입증하지 않습니다. 설계·문서·의사결정 카테고리는 아직 실행되지 않았습니다.

benchmark/BENCHMARK.md는 gitignore 대상이며 runs.jsonl에서 다시 만드는 재생성물입니다. compare 명령은 새 표본을 만들지 않습니다.

표본 수치는 12:03에 실행한 compare 출력에서 얻었습니다. 쓰기 부수효과가 있어 동시 수정 중인 트리에서 다시 돌리지 않았습니다.

워크플로 단위 벤치마크

P4 cascade 벤치마크는 arm 세 개를 커밋 해시로 고정해 비교합니다. A는 P1+P2, B는 P1+P2+P3-A, C는 P1+P2+P3-B-active입니다.

컨트롤러 CLI는 .claude/hooks/benchmark_cascade.py이고 모듈 13개에 총 889줄입니다. 테스트는 test_p4_cascade.py와 test_p4_cascade_exec.py 두 개입니다.

서브커맨드 8개 가운데 배선된 것은 plan과 approve-budget 둘뿐입니다. 나머지 6개인 calibrate, arm-run, sanitize, judge, compare, probe는 exit 3을 내는 stub입니다.

이 stub 목록과 종료 코드는 benchmark_cascade.py 소스에서 정적으로 확인한 것입니다. 이 파일은 이번 리팩터에서 바뀌지 않았습니다.

stub이 내는 메시지는 not-implemented — orchestrator 미배선(pilot 실행 단계에서 배선)입니다.

파일럿 실행 산출물은 저장소에 없습니다. runs 디렉터리, judgments.jsonl, cascade 벤치마크 보고서가 모두 부재합니다.

12:03 실행에서 plan은 exit 0으로 끝났고 arm 실행 3회, pairwise 호출 18회, 예상 judge 호출 132회를 계획으로 냈습니다. preflight 위반은 없었습니다.

plan은 역할·agent registry를 읽으므로 이번 리팩터의 영향을 배제할 수 없습니다. 이 결과는 재실행하지 않았습니다.

공정성 통제로 외부 웹 접근을 막습니다. arm-runner의 evidence_env가 WebFetch와 WebSearch를 실행 환경에서 차단하고, 모든 arm이 같은 evidence pack을 씁니다.

예산 게이트도 걸려 있습니다. calibrate, judge, arm-run에 --execute를 주면 예산 receipt가 없을 때 exit 2로 거부합니다.

receipt가 있어도 실행되지는 않습니다. 세 서브커맨드 모두 현재 구현에서는 exit 3, 즉 미구현을 반환합니다.

승자 판정은 blinded paired pairwise 패널만 씁니다. rubric 8개 기준의 절대 점수는 calibration 진단 전용입니다.

설계 문서가 붙인 단서도 분명합니다. 파일럿은 arm별 단일 실행이므로 통계적 우월성이나 일반적 생산성 향상을 확정하지 않습니다.

설계에서 의도적으로 미룬 항목은 여섯 가지입니다.

  • arm별 다중 repeat
  • Bradley–Terry/Elo 기반 순위화
  • 통계적 우월성 결론
  • cascade 확장
  • HUMAN judge 패널
  • live-research 트랙

현재 한계

  • 저장소가 이 문서를 쓰는 동안 다른 세션이 계속 수정했습니다. 12:03과 13:36 두 시점의 추출값이 달랐고, 13:36 이후에도 값이 다시 달라졌을 수 있습니다.
  • 저장소를 clone한 상태와 이 문서가 검증한 상태가 다릅니다. .claude/agents의 추적 카드는 72개인데 워킹 트리에는 75개가 있습니다.
  • 워킹 트리에서 지워진 fam-*.md 26개는 아직 커밋되지 않았습니다. HEAD는 그 파일들을 여전히 추적하므로, clone한 독자는 이 문서가 설명하는 것과 다른 저장소를 받습니다.
  • 최상위 hook에 새 모듈 네 개가 나타났습니다. compile_orgos_registry.py, spawn_bindings.py, intake_classifier.py, role_selector.py는 settings.json에 배선돼 있지 않습니다.
  • doctor.py의 14번째 점검 영역은 compile_orgos_registry.py를 실행합니다. 이 모듈 역시 배선돼 있지 않으므로, 점검 영역이 14개라는 사실이 14개 영역의 런타임 강제를 뜻하지는 않습니다.
  • 전체 test suite가 현재 트리에서 통과하는지는 확인되지 않았습니다. 마지막으로 통과를 확인한 시점은 리팩터 이전인 12:03입니다.
  • 강제는 Claude Code가 이 저장소의 .claude/settings.json을 로드한 세션에서만 동작합니다. 다른 실행 환경에서는 같은 강제를 보장하지 않습니다.
  • guard_tools.py는 allow-by-default regex 기반 2차 방어선입니다. 저장소가 스스로 셸 조합·인용·변형으로 우회 가능하다고 선언하므로 보안 경계로 삼으면 안 됩니다.
  • company-context.yaml이 provisional이고 창업자 확인값 5개가 비어 있습니다. 주당 가용시간, 자본·런웨이, 목표 사업 규모, 보유 유통채널, 운영·리스크 내성이 미해결입니다.
  • 상태가 operating이 아니면 company 인용 항목은 E2와 Med 상한에 묶이고, hypothesis 항목은 상태와 무관하게 Med 상한입니다. validate_report가 이를 강제합니다.
  • 회사·제품 문맥 레이어가 비어 있어, 자원 배분과 GTM 결정 전에 창업자 확인값을 먼저 채워야 합니다.
  • 워크스페이스 미설정이 더 이상 즉시 실패로 드러나지 않습니다. 포인터 파일이 채워져 있어 환경변수를 지정하지 않은 명령도 hyeonworks로 해석됩니다.
  • UI 검증은 render health만 판정합니다. 시각적 차별성, 타이포그래피, 비례, spacing의 미학 품질은 판정 범위 밖입니다.
  • 일부 경로는 외부 도구에 기댑니다. 전체 렌더 점검에는 Chrome 또는 Chromium 호환 실행 파일이 필요하고, marp가 없으면 consult 덱은 HTML 대체 경로로 갑니다.

기여할 때 고치는 위치

  1. 정본을 먼저 고칩니다. 역할·family·method 정의는 org-os/00-role-registry/에, workflow와 artifact 계약은 org-os/06-agent-work/에 있습니다.
  2. 생성물을 다시 만듭니다.
  3. 재검증을 돌립니다.
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를 덮어쓰므로 이번 분석에서 실행하지 않았습니다(검증 수준: 저장소가 선언한 명령).

변경은 CI의 harness-enforcers job이 돌리는 검사들을 그대로 통과해야 합니다.

method 계약을 바꾸면 method-contract-activations.yaml에 활성화 기록이 남습니다. 기록에는 상태, 계약 해시, 검증 보고서와 그 해시, 수용 workflow, 활성화 주체와 시각이 들어갑니다.

정본 파일

설계 이력

설계 spec은 docs/superpowers/specs/에, 구현 plan은 docs/superpowers/plans/에 있습니다.

라이선스

저장소 루트에 LICENSE 파일이 없습니다. 사용과 재배포 조건은 이 저장소에 명시돼 있지 않습니다.

Reference in New Issue View Git Blame Copy Permalink