company-haness/docs/superpowers/specs/2026-07-08-workspace-separation-design.md

org-os SSOT ↔ 프로젝트 워크스페이스 분리 — 설계

• 날짜: 2026-07-08
• 상태: 구현 완료(2026-07-08) — 프로젝트별 root 폴더(test-labs-documents·ca-tmpl·_sandbox), 훅 8개 _workspace 중앙화, 128/128 테스트, org-os=SSOT only
• 관련: design-system-pipeline, completion-records refs 마이그레이션(직전)

원칙

• org-os = SSOT only — 하네스의 정의·규칙·계약만. 생성물/런타임 상태는 없음.
• 작업 산출물 = 프로젝트별 root 폴더 — test-labs-documents/처럼 각 프로젝트가 자기완결 폴더.

SSOT ↔ 작업물 경계

org-os에 남김 (SSOT):

• 00-role-registry/* (roles·families·lenses·profiles·methods·matrices·drai·tool-permission·scorecard·team-topology·state-transition)
• 06-agent-work/의 계약 spec: collaboration-modes·map, governance-tiers, execution-policy, context-package-spec, report-templates, design-brief-spec, agent-operating-kpi (+ README)

프로젝트 폴더로 빼냄 (생성물·런타임):

• completion-records/ · evidence/ · reports/(INDEX·TOKENS)
• 런타임 상태: workflow-state-registry.yaml · work-queue.yaml · evidence-ledger.yaml · token-ledger.jsonl
• slack-inbox/ · slack-outbox/
• root의 design-system/

프로젝트 폴더 레이아웃 (자기완결)

<project>/                         # 예: test-labs-documents/, ca-tmpl/
  *.md                             # 대표용 결과물(decision-brief·synthesis 등)
  completion-records/<wf>/         # 리포트(불변)
  evidence/<wf>/                   # 인용 근거
  reports/INDEX.md, TOKENS.md      # 이 프로젝트 목차·토큰 대시보드
  state/                           # workflow-state-registry, work-queue, evidence-ledger, token-ledger.jsonl
  slack-outbox/, slack-inbox/      # 알림 큐
  design-system/                   # (있으면) 그 프로젝트 디자인 시스템

워크스페이스 라우팅 (훅 경로 중앙화)

신규 공유 모듈 .claude/hooks/_workspace.py — 모든 훅이 work_root()로 출력 루트 해석:

1. 환경변수 ORGOS_WORKSPACE(절대 or repo-상대) 있으면 그것
2. 없으면 포인터 파일 org-os/00-role-registry/active-workspace.txt의 프로젝트명
3. 둘 다 없으면 기본값(안전 폴백) test-labs-documents

• 커맨드(/ceo-intake·/plan-wave 등)가 엔게이지먼트 시작 시 active-workspace를 선언.
• new_report.py·render_report.py·report_tags.py·token_ledger.py·guard_tools.py·notify_slack.py·slack_inbox.py·stop_validate.py → 하드코딩 경로를 work_root() 기반으로 교체.
• 커맨드 8개(build·consult·decide·design·ground·review-output·run-wave·spec)의 경로 문구도 <project>/...로 갱신.

기존 워크플로우 → 프로젝트 매핑 (제안 — 사용자 확정)

워크플로우	→ 프로젝트 폴더	비고
wf-docapp	test-labs-documents/ (기존)	문서관리 웹앱
wf-caclean, wf-cadoc	ca-tmpl/	클린아키텍처(ca-tmpl) + design-system 이관
root design-system/	ca-tmpl/design-system/	ca-tmpl 테마
probilling, wf-churn-01, live-demo, wf-harness-audit	_sandbox/	하네스 개발·데모 런

마이그레이션 절차 (직전 refs 마이그레이션과 동형, 검증 포함)

1. 프로젝트 폴더 생성 + 각 워크플로우 outputs(records·evidence·reports 조각) 이동.
2. 런타임 상태(ledgers·slack)를 각 프로젝트 state/로. (기존 단일 파일 → 프로젝트별 분할 or 기본 프로젝트에 귀속 — 사용자 확정 필요; 기본: 데모성은 _sandbox, 실사용은 해당 프로젝트)
3. 모든 참조 경로 문자열 치환(리포트 source-uri·linked-reports·INDEX·커맨드·훅) — 결론 불변, 경로만.
4. 훅 경로 중앙화(_workspace.py) + 17개 파일 갱신.
5. org-os/06-agent-work README를 "계약 spec only"로 갱신.
6. 검증: 옛 경로 잔존 0, evidence source-uri 실존 0-missing, render_report --index 프로젝트별 재생성, enforcement 테스트, gen_agents.

열린 결정 (사용자 확정)

1. 프로젝트 폴더 이름(특히 probilling/churn/live-demo/harness-audit → _sandbox/ 하나로 vs 개별).
2. 단일 런타임 ledger(work-queue 등)를 프로젝트별로 쪼갤지, 아니면 크로스-프로젝트 1개를 어디 둘지.
3. 기본 워크스페이스(active-workspace 미지정 시).

비목표(YAGNI)

• 멀티 워크스페이스 동시 실행·워크스페이스 간 참조는 후속.
• org-os/06-agent-work 디렉터리명 변경은 하지 않음(참조 과다) — 계약 spec only로 의미만 재정의.