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 유지 → 커밋(사용자 승인 시).

8.0 KiB Raw Permalink Blame History