# P1 Tranche 3 — 단일 상태머신 엔진 (#7 + #13)

status: approved
follows: 2026-07-10-p1-structural-quality-design.md
applies-to-version: company-haness @ fix/p0-execution-integrity
date: 2026-07-10

## 목표
`state-transition-rules.yaml`를 **실제 실행·강제하는 엔진**을 만들고(#13), wave·cascade를 그 엔진 위의
**preset plan**으로 통합한다(#7). 현재 wave(progress.yaml)·cascade(collaboration-map)·상태규칙(미실행)이 분리돼 있다.
사용자 승인: 리뷰 권고대로 **실행 순서를 ground(discovery)→decide(converge)로 교정**한다(anchoring 제거).

## 통합 workflow-stage 어휘 (SSOT)
하나의 stage 어휘로 wave/cascade 이중 어휘를 대체한다:
```
intake → discovery → decide → design → spec → build → verification → acceptance → released → closed
(+ blocked: 어느 stage에서든 진입 가능한 사이드 상태)
```
- `discovery`(구 GROUND): 문제·시장·사용자·경쟁·재무 근거 접지 + **option-set** 산출(결정 아님).
- `decide`(converge): C-Level이 discovery의 근거+옵션을 읽고 하나로 수렴 → ExecutiveDecisionPacket.
- `spec`=구 DETAIL, `build`=구 implementation, `acceptance`=review/release-acceptance.
- 각 stage 내부의 개별 산출물은 여전히 document-state(Draft/Review/Approved/Closed), 부모-자식 수용 1건은 review-state(Submitted-for-Review/Accepted/Changes-Requested/Blocked)를 가진다(기존 유지).

## 상태 전이 (state-transition-rules.yaml에 workflow-stage 전이로 추가 — E1)
각 전이 = `{from, to, allowed-by, required-conditions, forbidden-if?, tier-modifiers}`:
- `intake → discovery`: decision-brief-present
- `discovery → decide`: grounding-evidence-present, option-set-present (≥2 옵션)
- `decide → design`: decision-packet-accepted (review-state Accepted), evidence_grade_min(tier)
- `design → spec`: design-accepted
- `spec → build`: spec-accepted **AND** design-to-build-contract.must-read-designs 전부 Accepted (collaboration-map 참조 — **핵심 게이트**)
- `build → verification`: completion-record-present
- `verification → acceptance`: quality_gate_status=Passed, blocker_open=false
- `acceptance → released`: release_acceptance_status=Approved, unresolved_critical_risks=false, human-gate(heavy)
- `* → blocked`: blocked-report-present, resume-condition-present
- `blocked → <resume>`: resume-condition-satisfied, human-instruction-applied-if-needed
- `released → closed`: —
기존 document-state/review-state 전이(현 파일 내용)는 보존한다. tier-modifiers는 governance-tiers.yaml가 SSOT(참조).

## 구성요소

### ① state_engine.py (신규 hook — E1 소유)
- `state-transition-rules.yaml`(SSOT) + `governance-tiers.yaml`(tier) + `collaboration-map.yaml`(design-to-build-contract) + `execution-plans.yaml`(plan)를 읽는다.
- import API(예외 없이 값 반환):
  - `current_stage(wf) -> str`
  - `allowed_next(wf) -> [str]`
  - `can_transition(wf, to, ctx=None) -> (bool, [unmet_reason])` — required-conditions/forbidden-if/tier 검사. 조건 평가는 워크플로 원장 + 보고서(evidence-grade via validate_report/receipt) + acceptance_log(review-state) + collaboration-map(must-read-designs Accepted)에서 파생.
  - `transition(wf, to, evidence, actor) -> (ok, [reason])` — 통과 시 원장 stage 갱신 + **append-only 전이 이벤트**(acceptance_log 메커니즘 재사용, `<state_dir>/<wf>/state-events.jsonl`).
- CLI: `state_engine.py current|allowed|check|transition --workflow <wf> [--to <stage>] ...`.
- **guard 모드**: `state_engine.py guard --workflow <wf> --to <stage>` → 커맨드가 진입 시 호출, exit 2면 커맨드가 전이 거부(선행조건 미충족 사유 출력). workspace 미설정/원장 없음은 fail-safe(명확 메시지).
- 절대 pipeline crash 금지(P0 hook 규율): 예외는 안전값으로 degrade.

### ② 통합 워크플로 원장 (E2 소유)
- 경로: `<state_dir>/<wf-id>/workflow.yaml` — 하나의 wf-id에:
  `workflow-id, stage(SSOT), plan(cascade|wave|light), tier, mode, artifacts:[{path, document-state, review-state}], progress:{round, is_progress_being_made, stall_count, next, governance_limits}`.
- wave의 `progress.yaml` 필드를 `progress:` 하위로 흡수(하위호환: plan-wave/run-wave가 이 원장을 읽고 쓴다). 원장 생성/갱신 helper(`workflow_ledger.py` 또는 state_engine의 일부).

### ③ execution-plans.yaml (신규 — E1 소유)
named plan = stage 순서(같은 state graph 위):
```
plans:
  cascade: [intake, discovery, decide, design, spec, build, verification, acceptance, released]
  wave:    [intake, plan, run, verification, acceptance, released]   # plan/run = Magentic 루프(run은 stage 반복)
  light:   [intake, run, verification, acceptance]
```
cascade는 별도 시스템이 아니라 이 plan. mid-start = 선행 stage의 gating 산출물이 존재하면 그 stage로 진입(엔진이 검증).

### ④ 커맨드 통합 (E2 소유)
- 각 cascade/wave 커맨드(ground/decide/design/spec/build/plan-wave/run-wave/review-output/release-check)가 **진입 시 `state_engine guard`를 호출**해 현재 stage 유효성+전이 선행조건을 확인하고, 미충족이면 거부(BlockedReport). 종료 시 `state_engine transition`으로 stage 전진.
- `/build`는 design-to-build-contract must-read-designs가 Accepted 아니면 엔진이 거부(현재 프롬프트 문구 → 실제 강제).
- 커맨드는 workflow-id를 명시적으로 받는다(없으면 새 wf 발급).
- **순서 교정**: `/ground`(discovery: 근거+option-set) → `/decide`(converge: 옵션→결정). ground.md/decide.md 재프레이밍. divergent /decide는 per-lens 옵션 평가 → CEO converge.

### ⑤ #7 모순 제거 (E2 소유)
- collaboration-map.yaml `cascade-phases`에 **GROUND/discovery 단계 추가**(현재 누락) + DECIDE를 그 뒤로.
- README/CLAUDE.md의 "항상 /ceo-intake" → "새 워크플로=ceo-intake; 기존 wf-id는 중간 stage 재개"(문서는 P1 close에서 오케스트레이터가 반영).
- 경량 경로(plan-wave 없이 run-wave)도 `light` plan으로 정식화.

## 빌드 분할 (순차 — E2가 E1 API에 의존)

### E1 — 코어 엔진 (한 subagent)
소유: `.claude/hooks/state_engine.py`(신규), `org-os/00-role-registry/state-transition-rules.yaml`(workflow-stage 전이 추가), `org-os/06-agent-work/execution-plans.yaml`(신규), `.claude/tests/test_state_engine.py`(신규).
수용: 엔진이 전이 규칙을 로드·강제; `spec→build`가 must-read-designs 미Accepted면 거부; `discovery→decide` 옵션셋 없으면 거부; heavy `acceptance→released` human-gate; CLI/guard 동작; 전이 이벤트 append-only; workspace 미설정 fail-safe. test_enforcement 편집 금지(깨지면 보고).

### E2 — 통합·커맨드 배선 (E1 이후 한 subagent)
소유: 통합 원장 helper, 커맨드 9개(ground/decide/design/spec/build/plan-wave/run-wave/review-output/release-check), `collaboration-map.yaml`(GROUND 추가+순서), `.claude/tests/test_p1_cascade.py`(신규).
수용: 커맨드가 state_engine guard/transition 호출; cascade 순서 ground→decide; `/build` design 미승인 거부; wave progress가 통합 원장 사용; mid-start 검증; 기존 커맨드 계속 동작. test_enforcement 편집 금지(collaboration-map "cascade has DECIDE/DESIGN/BUILD"·"family-ids exist"·"6 edges"는 유지, 깨지면 보고).

## 공유 규칙
- P0/P1 계약(report-header·receipt·workspace 강제·70 agents·context_package·불변보고서·acceptance_log) 불변.
- `test_enforcement.py` 편집 금지 — 새 테스트는 새 파일. 깨진 assertion은 오케스트레이터가 한 곳에서 반영.
- git commit/branch 금지. workspace 필요 시 ORGOS_WORKSPACE=_sandbox.
- 끝에 doctor + 전체 suite green 유지.

## 종료 처리(오케스트레이터)
E1·E2 각각 직접 재현 검증 → 깨진 test_enforcement 반영 → doctor + 전체 suite → CLAUDE.md/README 정직성(상태엔진·순서교정·plan) → settings.json 유지 → 커밋(사용자 승인 시).