33 KiB
P3-B 설계 v2 — Role Method Contract Hardening (실행 가능한 업무 계약)
리뷰 로드맵 P3. P3-A(구조 인프라) + P3-B(방법론 강화)를 하나의 통합 P3 구현으로 실행한다(§3). P3-A는 별도 선행 merge가 아니라 통합 P3의 infrastructure phase다. 관련 SoT:
role-working-methods/(신설 디렉터리),validate_report.py,state_engine.py,context_package.py,design-craft/design-brief-spec/design-direction-spec(P2). 개정: 사용자 리뷰 10건 반영(다중 method profile·역할경계·activation registry 분리·2지점 handoff gate·artifact 증명 trace·contract hash·machine/judgment gate·구조화 evidence/alternatives·파일 분리·통합 구현).
1. 문제와 목표 (BLUF)
bottom-line: P3-A는 절차가 누락 없이 도달하는 구조만 보장한다. role-working-methods의 절차는 얕은 문장 목록이라 얕은 결과가 안정적으로 반복될 뿐이다. P3-B는 이를 **실행 가능한 업무 계약(Contract v2)**으로 만든다 — 역할당 다중 method profile(호출 목적별) · 입력→단계→산출물→machine/judgment 게이트→판단규칙→구조화 근거→구조화 대안→금지→handoff→자기검증. 그리고 존재≠수행을 막는 실행 강제(artifact로 증명하는 method-execution trace + validator Hard Fail + 2지점 handoff gate)를 tier·활성화상태로 안전하게 건다.
decision-needed: 사용자 spec v2 승인 → 통합 P3 구현 계획(writing-plans, Phase 0–7) → SDD. approver: 사용자(theorose49).
confidence: High(E3) — 기존 machinery 실측: validate_report.py가 report-header·dissent·primary-artifacts 강제, decision.schema.json에 options 존재. P3-B는 확장. 강제 지점(spawn·transition·validate)도 기존 훅(context_package·state_engine·validate_report)에 매핑.
risks: (a) 75역할×다중 profile은 대규모 → wave 이행 + activation registry로 deadlock 없이 점진. (b) 방법론 SoT를 runtime이 수정하면 안 됨 → status를 별도 activation registry로 분리. (c) self-report trace는 무의미 → step-results를 artifact/evidence/receipt hash로 증명. (d) 모든 gate를 자동판정하면 오탐 → machine gate(hard) vs judgment gate(reviewer) 분리.
핵심 목표:
- 다중 method profile Contract v2: 호출 목적별 절차(§4).
- 공통 품질=validator, 역할별 사고=계약(§9).
- artifact로 증명하는 실행 강제: step-results·2지점 handoff gate·contract hash(§11–§13).
- SoT/runtime 분리: 계약 본문 = 방법론 SoT, 활성화 = activation registry(§14).
- 75역할 wave 이행, all-active cutover(§18).
2. 3-way 책임 분리 (중복 없이)
| 층 | 무엇 | 어디 |
|---|---|---|
| Role method contract | 누가·언제(어떤 task-type)·어떤 순서로·무엇을 산출·넘기는가 | role-working-methods/*.yaml(Contract v2) → gen → method-skill |
| Capability skill | 전문 판단을 어떤 기준으로 (정본) | 수제 design-craft/diagram-craft/build-loop + design-brief-spec |
| Artifact (결과) | 그 기준을 적용해 나온 실제 산출물 | P2 design-direction, completion-records |
계약 step은 uses-capability로 capability-skill 절을 참조, required-inputs로 upstream artifact를 명시. 세 군데 복제 금지.
3. 통합 P3 구현 (A+B 하나의 브랜치·최종 1회 cutover)
P3-A(구조 인프라)는 별도 선행 merge가 아니라 통합 P3의 인프라 phase다. generator·카드 배선이 대표 역할 golden task보다 먼저 존재해야 golden task 검증이 성립한다(golden task 실행 = v2 generator + 생성 method-skill + 카드 skills 배선 + method-selection + runtime auto-load 전부 필요). 카드/skill은 wave마다 재생성하되 최종 cutover는 1회.
구현 순서(Phase) — generator/배선을 앞으로:
- Phase 0 — Baseline + skill auto-load probe(§0.1, load-bearing). 회귀 기준.
- Phase 1 — Contract v2 스키마(다중 profile · gate catalog · artifact vocabulary · 파일분리/index)(§4,§7,§17).
- Phase 2 — P3-A 인프라(method registry · gen_method_skills v2 · gen_agents spine/skills · reference/orphan/drift gate · v1/v2 dual rendering)(§10). golden task 이전에 배선 완성.
- Phase 3 — Runtime contract resolution(method-selection · activation registry · method_contracts.py 공용 policy engine · contract/capability canonical hash · activation trusted CLI)(§5,§13.1,§14,§16).
- Phase 4 — Enforcement(validate_report · spawn handoff gate · transition handoff gate · migration debt)(§12,§13).
- Phase 5 — 대표 역할 golden task(draft→review→active)(§6,§18).
- Phase 6 — family wave 이행(wave마다 계약 작성·검증·활성화·재생성)(§18).
- Phase 7 — final cutover(production 참조 profile all-active · debt 0 · v1 제거 · 최종 skill/card 재생성)(§18).
0.1 Phase 0 — skill auto-load probe (P3-A 복원, load-bearing)
.claude/skills/generated/<role>-method/SKILL.md 중첩 경로를 subagent가 실제로 auto-load하지 못하면 P3 전체 구조가 작동하지 않는다(구현 세부가 아니라 load-bearing assumption). Phase 0 필수:
- nested generated skill 1개 생성 → 2. throwaway agent
skills:에 연결 → 3. 실제 subagent dispatch → 4. sentinel 응답 검증 → 5. 실패 시 flat layout 폴백(generated-dir: .claude/skills) → 6. probe 제거. 결과를 ledger에 기록(이후 phase가generated-dir참조).
4. Contract v2 스키마 — 역할당 다중 method profile
같은 역할도 호출 목적(task-type)에 따라 절차가 다르다. 단일 선형 workflow는 불필요 절차를 강제하거나(전체 실행) 누락 판정을 유발한다(일부 실행). 역할 skill은 하나, 내부에 여러 method profile을 둔다.
role-method-contracts:
DES-PROD:
method-contract: { version: 2 } # 활성화 상태는 여기 없음 — activation registry(§14)
role-boundary: # 역할 경계 명시(다른 역할 침범 방지, §6)
owns: [제품 목표, 사용자 핵심 작업, 정보구조, 상호작용 흐름, 상태(빈/에러/로딩/복구), 대표 화면, 사용성 판단]
not-owns: [reference-cluster(-> DES-VISUAL), token(-> DES-PLATFORM), 방향 수렴/locked(-> DES-DIRECTOR)]
methods:
- method-id: product-experience-definition
applies-when: { task-types: [product-definition, experience-architecture] }
required-inputs: [{ artifact-type: product-decision }, { artifact-type: user-research, optional: true }]
workflow: [ … ] # §6
decision-rules: [ … ] # §8
evidence-policy: { … } # §8
alternatives-policy: { applies-when: decision-step, min-alternatives: 2 }
output-artifacts: [{ kind: experience-constraints }]
handoff-contract: [ … ] # §13
prohibited-shortcuts: [ … ]
escalation-conditions: [ … ]
self-check: [ … ] # 역할 고유만(P3-A §5)
- method-id: interaction-design
applies-when: { task-types: [interaction-design, core-flow-prototype] }
required-inputs: [{ artifact-type: selected-direction }, { artifact-type: locked-invariants }]
output-artifacts: [{ kind: interaction-state-model }, { kind: design-decision-record }]
# …
- method-id: product-design-review
applies-when: { task-types: [design-review] }
# …
- method-selection: context-package가 실행 profile을 명시(§5). 없으면 applies-when.task-types로 추론(모호하면 진입 거부).
- cutover 기준(§18): 단순 "75 roles active"가 아니라 — 모든 역할에 ≥1 필수 method profile 존재 + production workflow가 참조하는 profile 전부 active + unresolved handoff edge 0.
5. method-selection (context-package) — standard/heavy 필수
어느 profile을 실행하는지 런타임에 주입:
# context-package
method-selection: { role-id: DES-PROD, method-id: interaction-design, contract-sha256: … }
선택 정책(자동 추론은 위험 — 두 profile이 task-type 일부 공유·표현 누락 시 오선택):
- light: method-selection 생략 시 유일 후보만 auto-infer. 복수 후보 → warning/거부.
- standard/heavy: method-selection 필수, auto-infer 금지. 없으면 context-package 컴파일 거부(
context_package.py).
validator 일치 검사(§12): 보고서 method-execution.method-id가 context-package에서 선택된 method와 정확히 일치해야 한다(다른 profile 실행 보고 방지). method_contracts.validate_method_selection(§13.1)이 판정.
activation registry — 활성화 상태는 방법론 SoT가 아니라 별도 파일(§14). role-working-methods/(방법론 SoT)를 runtime이 수정하지 않는다.
6. 역할 경계 재분리 + method profile (디자인 예시)
역할 경계를 침범하지 않게 재분리(같은 분야 안에서도 평균화 금지):
| 역할 | owns (method profile 초점) |
|---|---|
| DES-PROD | 제품 목표·사용자 핵심 작업·정보구조·상호작용 흐름·상태(빈/에러/로딩/복구)·대표 화면·사용성 판단 |
| DES-VISUAL | reference-cluster·visual thesis·form language·typography character·signature element·motion grammar·anti-reference |
| DES-PLATFORM | token semantics·token hierarchy·component boundary·state/variant·composition·governance·migration/deprecation |
| DES-DIRECTOR | 발산 프레이밍·방향 비교·단일 방향 선택·locked-invariants·평균 금지·critique synthesis |
DES-PROD pre/post-direction profile 분리(시간순 모순 해소) — 이전 스키마는 DES-PROD가 direction-input-brief를 생성하면서 required-inputs에도 뒀다. 분리:
product-experience-definition(pre):product-decision→ experience-constraints 산출.interaction-design(post):selected-direction+locked-invariants(DES-DIRECTOR 산출) → interaction-state-model/flow 산출.
workflow step 예(interaction-design):
workflow:
- step-id: model-core-flow
objective: 핵심 사용자 흐름과 상태 모델을 설계한다.
uses-capability: { skill-id: design-craft, section-id: decisions }
inputs: [selected-direction, locked-invariants]
required-output: interaction-state-model
skippable: false
completion-gates: { … } # §7
- step-id: validate-exception-states
objective: 빈/에러/로딩/복구 상태를 설계한다.
skippable: true
skip-rules: [{ skip-rule-id: SKIP-NO-ASYNC-FLOW, condition: "동기 단일 화면·비동기 없음" }]
7. completion-gates — machine vs judgment + enforcement level
문자열 게이트는 validator가 안정적으로 검사할 수 없다. machine gate(자동 Hard 가능)와 judgment gate(reviewer 판단)로 분리하고, 각 항목의 강제 수준을 명시.
completion-gates:
machine:
- gate-id: CORE-TASK-PRESENT
check: artifact-field-present
artifact: direction-input-brief
field: core-task
enforcement: hard
- gate-id: VISUAL-FIELDS-ABSENT
check: artifact-fields-absent
artifact: direction-input-brief
fields: [color-palette, typography, visual-metaphor]
enforcement: hard
judgment:
- gate-id: BRIEF-SPECIFICITY
reviewer-role: DES-DIRECTOR
criterion: target-user·success-condition이 실행 가능한 수준으로 구체적인가
enforcement: warning # judgment 는 hard 자동판정 금지(오탐 방지)
- check 어휘(machine):
artifact-field-present/artifact-fields-absent/artifact-field-matches/artifact-exists/receipt-exists— validator가 실제 검사할 수 있는 술어. enforcement: hard | warning | instructional. decision-rules·prohibited-shortcuts·self-check는 대부분 instructional/judgment(전문 판단 가이드) — 자동 Hard Fail 금지.- judgment gate는 heavy tier의 독립 reviewer가 평가(§15).
8. 기계 판정 가능한 evidence · alternatives
evidence-policy(one-of, 등급별):
evidence-policy:
one-of:
- { evidence-type: user-research, min-grade: E2 }
- { evidence-type: behavioral-data, min-grade: E2 }
- { evidence-type: usability-test, min-grade: E2 }
unsupported-claim-treatment: { standard: confidence-cap, heavy: hard-fail }
alternatives(구조화 — 정수만으론 비교 증명 불가):
# method-execution.decisions (report trace, §11)
decisions:
- decision-id: card-vs-list
alternatives:
- { option-id: OPT-CARD, evidence-refs: [] }
- { option-id: OPT-LIST, evidence-refs: [] }
- { option-id: OPT-STATUS-QUO, evidence-refs: [] }
selected-option-id: OPT-LIST
rejection-rationales: { OPT-CARD: "…", OPT-STATUS-QUO: "…" }
validator: len(alternatives) >= min-alternatives + selected-option-id ∈ alternatives + 나머지에 rejection-rationale 존재. decision.schema.options 재사용.
9. 공통 품질 vs 역할별 사고 (평균화 방지)
공통 품질은 75역할에 복제하지 않는다 — validator/schema 강제. 역할별 계약은 역할 고유 사고만.
| 공통 (validator/schema) | 역할별 (계약) |
|---|---|
| 근거 없는 결론 금지 · 대안 비교(decision) · dissent(heavy) · required-artifact · handoff 명시 · 생략+사유 기록 · report-header/evidence 등급 | 무엇을·어떤 순서로 분석 · 근거 자료 · 판단 규칙 · 전문 산출물 · handoff 대상 · 흔한 오류(prohibited-shortcuts) |
10. gen_method_skills v2 — profile별 실행 skill 렌더
P3-A gen_method_skills.py 확장(v1 flat / v2 contract 분기). v2는 method profile마다 섹션 렌더:
# DES-PROD 실무 계약
## 역할 경계 (owns / not-owns)
## Method: interaction-design (task-types: interaction-design, core-flow-prototype)
### 필수 입력 ### 워크플로(step: 목표/uses-capability/입력/산출/machine·judgment 게이트/skippable)
### 판단 규칙 ### 근거 정책 ### 대안 정책 ### 산출물 ### Handoff ### 금지 ### 자기검증
## Method: product-experience-definition …
uses-capability는 참조 링크로(내용 복제 안 함). v1 역할은 P3-A 렌더 그대로. drift--check유지.
11. method-execution trace — artifact로 증명 (자기신고 금지)
이름만 나열하면 통과하는 self-report를 금지. step-results를 artifact/evidence/receipt로 연결:
method-execution:
role-id: DES-PROD
method-id: interaction-design
contract-sha256: <정규화 contract YAML hash> # §16 — skill md hash 아님
capability-bindings: # §16 — 참조한 craft 버전
- { skill-id: design-craft, section-id: decisions, skill-sha256: <hash> }
step-results:
- step-id: model-core-flow
status: completed
artifact-refs: [{ report-id: interaction-state-model-01, sha256: <hash> }]
evidence-refs: [{ source-uri: "…", grade: E2 }]
- step-id: validate-exception-states
status: skipped
skip-rule-id: SKIP-NO-ASYNC-FLOW # contract의 허용 skip-rule 이어야
reason: "동기 단일 화면"
handoffs: # 배열(다수 consumer)
- { to-role: DES-PLATFORM, artifact-refs: [{ report-id: selected-direction, sha256: <hash> }] }
- { to-role: ENG-FE, artifact-refs: [{ report-id: design-decision-record, sha256: <hash> }] }
- step-id는 contract step-id와 동일 명칭(이전 completed-phases 명칭 불일치 수정).
step-results로 통일. - report.schema에 additive(active+tier≥standard에서 required 승격).
12. 강제 ① validate_report (step-results 검증)
보고서 role-id+method-execution.method-id로 계약 profile을 조회. profile이 active·tier≥standard일 때:
- completed step: 해당 step의 required-output artifact-ref 실존 + machine completion-gate 통과 + (필요 시) receipt. 없으면 Hard Fail.
- skipped step: contract에
skippable: true+skip-rule-id가 허용 skip-rule과 일치. 자유 사유 한 줄만 → Hard Fail. - required step 누락(completed·skipped 어디에도 없음) → Hard Fail.
- alternatives-policy applies: decisions 구조 검증(§8) → 미달 Hard Fail.
- evidence-policy: one-of 미충족 → standard=confidence-cap, heavy=hard-fail.
- contract-sha256 불일치(현 active 계약과): 보고서는 historical-valid로 유지(감사), 단 current-usable=false → 후속 handoff 입력으로 stale(§16).
draft profile·light tier는 schema warning + trace 기록만(Hard Fail 없음).
13. 강제 ② handoff gate — 2지점 (spawn + transition)
stage transition gate만으로는 우회가 남는다(같은 stage 내 fan-out/순차 subagent 호출: DES-PROD→DES-PLATFORM). 두 지점에서 강제:
(A) consumer subagent spawn 직전(호출 단위 gate) — context_package.py/subagent_register.py가 consumer의 required-inputs(=upstream handoff artifact)가 실존·Accepted인지 검사. 없으면 context-package 생성/dispatch 차단(consumer가 추측으로 시작하는 것 방지).
(B) stage transition(stage gate) — state_engine.py가 해당 stage 전체의 handoff 완료를 확인해야 다음 stage 전이 허용(workflow 미완성 전이 방지). P2 gate와 동형.
handoff edge = profile-to-profile(role-to-role 아님) — consumer 역할도 다중 profile이라, 어느 profile의 입력인지 알아야 required-input과 정확히 연결된다:
handoff-contract:
- edge-id: DES-PROD-INTERACTION_TO_DES-PLATFORM-SYSTEM-01
from: { role-id: DES-PROD, method-id: interaction-design }
to: { role-id: DES-PLATFORM, method-id: design-system-architecture }
applies-when: { task-types: [design-system] }
required-artifacts:
- artifact-type: interaction-state-model
schema-ref: interaction-state-model.schema.json
cardinality: one # one | many
required-state: Accepted
binding: { workflow: same, product-decision: same } # 같은 wf·결정 산출인지
freshness: current-usable # §16 stale 정책
producer role/method · consumer role/method · cardinality · schema · acceptance 상태 · workflow/product/decision binding · freshness까지 명시 → spawn gate와 transition gate가 같은 판단을 하게 한다.
- 활성 조건(deadlock 방지): producer profile active AND consumer profile active AND edge 명시 → hard gate. 한쪽 draft → warning + migration-debt event(§14).
- light tier: hard gate 미적용, 필수 입력 존재만 경량 검사(§23).
13.1 공용 policy engine (method_contracts.py) — 정책 해석 한 곳, 강제 두 곳
spawn gate와 transition gate에 별도 로직을 두면 시간이 지나며 판정이 갈린다. 정책 해석은 단일 모듈, 강제 시점만 2곳:
.claude/hooks/method_contracts.py
resolve_method_profile(role_id, method_id) # 계약 profile 로드(파일분리 병합)
resolve_activation(role_id, method_id) # activation registry 조회(status/hash)
validate_method_selection(context_package) # tier별 필수·유일후보·hash 일치
evaluate_required_inputs(role_id, method_id, ws) # required-inputs 실존·Accepted
evaluate_handoff_edge(edge, ws, phase) # phase: "spawn" | "transition"
validate_method_execution(report, ws) # step-results artifact 증명(§11)
canonical_contract_hash(contract) # 정규화 YAML hash(§16)
호출 구조:
context_package.py/subagent_register.py→evaluate_handoff_edge(..., phase="spawn")+validate_method_selection.state_engine.py→evaluate_handoff_edge(..., phase="transition").validate_report.py→validate_method_execution(...).
14. 활성화 상태 — activation registry (SoT/runtime 분리)
방법론 SoT(role-working-methods/)를 runtime이 수정하지 않는다. 활성화 상태는 별도 registry(구조화 key):
# org-os/00-role-registry/method-contract-activations.yaml
method-contract-activations:
roles:
DES-PROD:
methods:
interaction-design:
status: active # draft | active | retired
contract-sha256: <정규화 hash>
accepted-by: HUMAN-001
accepted-at: 2026-07-13T…
validation-report-ref: <golden-task 검증 보고서>
validation-report-sha256: <hash>
activation 직접 수정 금지 — trusted CLI(guard_tools가 registry 직접 write 차단, P1 commit_company_context와 동형):
python3 .claude/hooks/activate_method_contract.py \
--role DES-PROD --method interaction-design \
--contract-sha256 … --validation-report … --acceptance-event …
CLI 확인: 계약 schema/lint 통과 + golden task report 실존 + validation-report hash 일치 + HUMAN acceptance hash 일치 + 현재 contract hash 일치 → registry 임시파일 write → os.replace 원자 교체 → activation receipt 기록.
상태(draft/active/retired — deprecated 아님):
| status | schema | trace | validate Hard Fail | handoff gate |
|---|---|---|---|---|
| draft | warning | 기록 | ❌ | ❌ (warning + debt) |
| active | required | 필수 | ✅ (standard/heavy) | ✅ (양쪽 active 시) |
| retired | — | — | v1/구 계약 fallback 금지 | — |
승격 과정: 계약 작성 → schema/lint → 대표 task(golden) 검증 → contract review → HUMAN acceptance → activation registry 갱신(contract-sha256 바인딩). OPS-ORCH는 HUMAN receipt를 확인해 활성 상태를 집행하지만, 혼자 전문 절차 품질을 승인하지 않는다(P1 company-context human-gate와 동형).
migration-debt = event 원장(단순 append 아님) — 해소된 debt와 현재 debt를 구별해야 한다. state/method-contract-debt.jsonl에 이벤트로:
{ event-type: opened|resolved, debt-id, workflow-id, edge-id,
producer-contract-sha256, consumer-contract-sha256, reason, created-at, resolved-at }
현재 unresolved debt = 각 debt-id의 최신 이벤트가 opened인 항목(fold). cutover 게이트가 이 계산=0 요구. doctor가 status 분포 + unresolved debt 리포트.
15. tier별 강도
| tier | 강제 |
|---|---|
| light | 필수 입력·핵심 단계·주요 산출물·handoff 요약. 대안 조건부. handoff hard gate 미적용(입력 존재만). |
| standard | 전체 required steps·evidence(one-of)·대안+기각사유·handoff artifact. machine gate·machine-check 연결 prohibited만 hard. |
| heavy | standard 전체 + 독립 반대검토(judgment reviewer)·dissent·hash-bound artifact. HUMAN 승인은 approval-policy 조건일 때만. |
- prohibited-shortcuts는 자동 Hard Fail 아님: 대부분 자연어 판단이다.
check-ref로 machine-check가 연결된 항목만 Hard Fail 가능, 자연어 항목은 judgment review 또는 self-check(오탐 방지). - heavy의 HUMAN 승인은 profile별 approval-policy로 제한(모든 heavy 결과에 HUMAN 요구 시 자동화 과다 정지):
heavy → judgment reviewer 필수. HUMAN receipt → 해당 profile approval-policy가 요구할 때만.
# method profile approval-policy: human-required-when: [irreversible-decision, external-side-effect, company-strategy-change, security-risk-acceptance]
16. contract hash · capability section ID · historical vs current
- contract-sha256: 정규화된 method contract YAML hash(공백·제목만 바뀌는 md hash 아님). 실제 계약 변경 여부 기준.
canonical_contract_hash(§13.1)가 산출. - generated-skill-sha256(선택): 생성 drift 검사용.
- capability section = stable ID manifest(제목 문자열 아님) — doctor가 SKILL.md 제목을 검색하면 제목 변경·번역에 깨진다. 각 capability skill은 안정적 section ID manifest를 갖는다:
계약은 ID만 참조:
# design-craft frontmatter 또는 별도 capability-sections.yaml capability-sections: - { id: brief, heading: Design Brief } - { id: reference-cluster, heading: Reference Cluster } - { id: constraints, heading: Constraint System } - { id: token-semantics, heading: Token Semantics } - { id: decisions, heading: Design Decisions }uses-capability: { skill-id: design-craft, section-id: decisions }. doctor는 section-id가 manifest에 실존하는지 검사(제목 무관). - capability-bindings(section 단위 hash) — capability가 바뀌면 같은 계약이라도 수행 규칙이 달라짐 → 재현성 위해 section 내용만 hash:
capability-bindings: - { skill-id: design-craft, section-id: decisions, section-sha256: … } - historical-valid vs current-usable: 과거 보고서는 생성 당시 계약으로 유효(감사 기록 유지). 단 현재 active 계약과 contract-sha256이 다르면 current-usable=false → 후속 handoff 입력으로는 stale. 계약 수정이 과거 보고서를 전부 무효화하지 않는다.
17. 파일 분리 (지금 — 75계약은 YAGNI 아님)
org-os/00-role-registry/role-working-methods/
index.yaml # role-method-contracts: { includes: [...] }
executive.yaml product.yaml design.yaml architecture.yaml
engineering.yaml platform-security-data.yaml gtm-operations.yaml
consulting-documentation.yaml
논리적으로는 단일 SoT. gen/doctor 강제: 중복 role-id 0 · 누락 role-id 0 · include 안 된 파일 0 · 전체 contract hash 재현 가능 · family 파일↔role registry 정합. (기존 단일 role-working-methods.yaml은 migration 중 v1 fallback로 잔존 가능, 최종 cutover서 흡수.)
18. Wave 이행 + cutover 기준
하나의 브랜치·하나의 Contract v2·하나의 cutover. 각 wave는 draft 작성 → golden task 검증 → active 승격.
| Wave | 대상 | gate |
|---|---|---|
| 0 | Contract v2 스키마 + 파일분리 + gen v2 + validator + 2지점 handoff gate + activation registry + status 머신 | 인프라 테스트 green(계약 없이 v1 통과) |
| 1 | 대표 역할(아래) 계약 + golden task end-to-end | 계약 유형 전부 검증 |
| 2 | 임원·제품·전략·재무 | wave gate |
| 3 | 디자인·아키텍처·데이터·보안 | wave gate |
| 4 | 개발·인프라·QA | wave gate |
| 5 | GTM·운영·컨설팅·문서 | wave gate |
| 6 | 전체 handoff graph + 회귀 | cutover: 모든 역할 ≥1 필수 profile 존재 + production 참조 profile 전부 active + handoff edge 0 debt |
대표 검증군(Wave 1, 계약 유형 전부): DES-DIRECTOR·DES-PROD·DES-PLATFORM·DES-VISUAL(발산·수렴), EXEC-CEO·EXEC-CFO·PROD-PM(사업 판단), ARCH-TECH(기술 설계), ENG-BE(구현), INFRA-PLATFORM 또는 SRE·QA(운영·검증), GTM-PRICING(가격 분석), DOC-LEAD(문서 handoff).
"production 참조 profile" 출처(cutover 계산): commands + execution-plans + context-package의 method-selection + handoff graph에서 참조되는 method profile 집합을 스캔 산출(자동), 또는 명시 매트릭스:
# required-profile-matrix (선택 — 자동 스캔 보완)
required-profile-matrix:
cascade: [EXEC-CEO/venture-decision, PROD-PM/product-definition, DES-PROD/interaction-design, ENG-BE/backend-implementation]
cutover 조건: 참조되는 method profile ⊆ activation registry의 active profile AND unresolved handoff debt=0 AND 모든 역할 ≥1 필수 profile 존재. (참조 안 되는 profile은 draft로 남아도 cutover 무방 — 실사용 profile만 강제.)
19. 하위호환
- v1 flat과 v2 contract 브랜치 내부 공존(migration용). gen 분기 렌더. validator는 active 계약에만 Hard Fail.
- 최종 merge = all-active — v1 flat·구 단일 파일 제거(없어도 됨). retired는 fallback 금지(스테일 방지).
20. 하네스 정합성 (확장, 중복 아님)
- 신설
method_contracts.py(공용 policy engine, §13.1) — 정책 해석 단일 지점. 아래 훅이 이를 호출(강제 시점만 분산). validate_report.py확장 →method_contracts.validate_method_execution(step-results 증명).decision.schema.optionsalternatives에 재사용.state_engine.py확장 →evaluate_handoff_edge(phase="transition").context_package.py/subagent_register.py확장 →evaluate_handoff_edge(phase="spawn")+validate_method_selection. 2지점, 동일 판정.gen_method_skills.py(P3-A) 확장(v2 profile 렌더). registry·카드 구조(P3-A) 불변.- 신설:
role-working-methods/(분리+index),method-contract-activations.yaml,activate_method_contract.py(trusted CLI), artifact-type/handoff vocabulary, capability-sections manifest, method-execution schema, debt event 원장. guard_tools확장: activation registry 직접 write 차단(CLI만 허용). 에이전트 72·역할 75 불변.
21. 테스트 계획 (test_p3b_*.py, wave별 + 통합)
- 스키마 v1/v2 공존·파일분리 정합(중복/누락/미include role-id 0, 전체 contract hash 재현).
- 다중 method profile: applies-when.task-types 선택. method-selection standard/heavy 필수(없으면 context-package 거부), light 유일후보 추론·복수후보 거부.
- method-selection 일치: 보고서 method-execution.method-id == context-package 선택 method(불일치→Hard Fail).
- gen v2 렌더: profile별 섹션(입력·단계·machine/judgment 게이트·근거·대안·금지·handoff·self-check).
- capability section-id 해소: contract가 section-id 참조, manifest에 실존(제목 무관), 미존재→doctor FAIL. section-sha256 기록.
- method-execution 증명: completed step artifact-ref 실존, skipped=허용 skip-rule 일치, self-report(artifact 없음)→Hard Fail. step-id==contract step-id.
- evidence one-of / alternatives 구조: one-of 미충족·option-id/rejection-rationale 누락→Hard Fail(정수만으론 불충분).
- machine vs judgment gate: machine hard 자동, judgment는 hard 자동판정 안 함. prohibited-shortcuts 자연어→자동 Hard Fail 안 함.
- 공용 policy engine:
method_contracts.evaluate_handoff_edge가 spawn·transition 동일 판정(profile-to-profile edge, binding/cardinality/required-state). - 2지점 handoff gate: consumer spawn 차단(required-input 부재) + stage transition 차단. 양쪽 active만 hard, 한쪽 draft→warning+debt event.
- activation trusted CLI: registry 직접 write 차단(guard_tools), CLI가 golden+validation+HUMAN hash 확인 후 os.replace. draft→active 전이, retired fallback 금지.
- debt event fold: opened/resolved 이벤트, unresolved=최신 opened, cutover=0 계산.
- contract hash / historical: contract-sha256 기준, 과거 보고서 historical-valid·current-usable=false stale.
- tier 강도 + approval-policy: light/standard/heavy 차등, heavy HUMAN은 approval-policy 조건일 때만.
- cutover 계산: 참조 profile(commands+plans+handoff scan) ⊆ active + debt 0 + 모든 역할 ≥1 필수 profile.
- doctor 확장: status 분포·unresolved debt·capability section-id·파일분리 정합.
- run_all green + all-active cutover.
22. 비목표
- capability-skill(design-craft 등) 내용 재작성 금지 — 계약은 참조만.
- 새 역할·family·에이전트 없음. lens·collaboration 정책 불변.
- 모든 gate 자동판정 금지 — judgment gate는 reviewer(오탐 방지).
- P4(벤치마크) 별도(Baseline/P3-A/P3-B 3단 비교).
23. 열린 결정 (권장값 확정)
| 결정 | 권장(확정) |
|---|---|
| 계약 저장 | family별 파일 분리 + index, 논리적 단일 SoT(§17) |
| method-execution 위치 | report 공통 필드, step-results + artifact hash(§11) |
| light tier handoff | hard gate 미적용, 필수 입력 존재만 경량 검사 |
| active 승격 권한 | 대표 task 검증 + contract-review + HUMAN acceptance, OPS-ORCH는 검증된 receipt 집행 |
24. 구현 체크리스트 (writing-plans가 Phase별 TDD/wave 태스크로 분해)
- Phase 0: baseline + skill auto-load probe(§0.1) → generated-dir 확정.
- Phase 1: Contract v2 다중 profile 스키마 + gate catalog(machine/judgment) + artifact vocabulary +
role-working-methods/분리+index(§4,§7,§17). - Phase 2: P3-A 인프라(method registry · gen_method_skills v2 · gen_agents spine/skills · ref/orphan/drift gate · v1/v2 dual)(§10) — golden task 이전에 배선.
- Phase 3:
method_contracts.py공용 policy engine + method-selection +method-contract-activations.yaml+activate_method_contract.py(trusted CLI) + canonical contract/capability hash(§5,§13.1,§14,§16). - Phase 4: Enforcement — validate_report(step-results·evidence·alternatives·method-id 일치) + spawn gate(context_package/subagent_register) + transition gate(state_engine) + debt event 원장(§12,§13).
- Phase 5: 대표 역할(§18) 계약(draft) + golden task + HUMAN acceptance → active 승격.
- Phase 6: family wave 2–5 이행(각 wave 계약·검증·활성화·재생성).
- Phase 7: cutover(참조 profile all-active · debt 0 · v1 제거 · 최종 skill/card 재생성) +
test_p3b_*+ run_all green. - CLAUDE.md·문서 갱신(Contract v2·다중 profile·2지점 gate·activation registry·policy engine).