# 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)** 분리.

**핵심 목표:**
1. **다중 method profile Contract v2**: 호출 목적별 절차(§4).
2. **공통 품질=validator, 역할별 사고=계약**(§9).
3. **artifact로 증명하는 실행 강제**: step-results·2지점 handoff gate·contract hash(§11–§13).
4. **SoT/runtime 분리**: 계약 본문 = 방법론 SoT, 활성화 = activation registry(§14).
5. **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 필수:
1. 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**을 둔다.

```yaml
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을 실행하는지 런타임에 주입:
```yaml
# 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):
```yaml
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 판단)로 분리**하고, 각 항목의 강제 수준을 명시.

```yaml
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, 등급별):**
```yaml
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(구조화 — 정수만으론 비교 증명 불가):**
```yaml
# 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로 연결**:
```yaml
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과 정확히 연결된다:
```yaml
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):
```yaml
# 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와 동형):
```bash
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`에 이벤트로:
```yaml
{ 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 요구 시 자동화 과다 정지):
  ```yaml
  # method profile
  approval-policy:
    human-required-when: [irreversible-decision, external-side-effect, company-strategy-change, security-risk-acceptance]
  ```
  heavy → judgment reviewer 필수. **HUMAN receipt → 해당 profile approval-policy가 요구할 때만**.

## 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를 갖는다:
  ```yaml
  # 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 }
  ```
  계약은 **ID만 참조**: `uses-capability: { skill-id: design-craft, section-id: decisions }`. doctor는 section-id가 manifest에 실존하는지 검사(제목 무관).
- **capability-bindings(section 단위 hash)** — capability가 바뀌면 같은 계약이라도 수행 규칙이 달라짐 → 재현성 위해 **section 내용만 hash**:
  ```yaml
  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 집합**을 스캔 산출(자동), 또는 명시 매트릭스:
```yaml
# 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.options` alternatives에 재사용.
- `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별 + 통합)

1. **스키마 v1/v2 공존·파일분리 정합**(중복/누락/미include role-id 0, 전체 contract hash 재현).
2. **다중 method profile**: applies-when.task-types 선택. **method-selection standard/heavy 필수**(없으면 context-package 거부), light 유일후보 추론·복수후보 거부.
3. **method-selection 일치**: 보고서 method-execution.method-id == context-package 선택 method(불일치→Hard Fail).
4. **gen v2 렌더**: profile별 섹션(입력·단계·machine/judgment 게이트·근거·대안·금지·handoff·self-check).
5. **capability section-id 해소**: contract가 section-id 참조, manifest에 실존(제목 무관), 미존재→doctor FAIL. section-sha256 기록.
6. **method-execution 증명**: completed step artifact-ref 실존, skipped=허용 skip-rule 일치, self-report(artifact 없음)→Hard Fail. step-id==contract step-id.
7. **evidence one-of / alternatives 구조**: one-of 미충족·option-id/rejection-rationale 누락→Hard Fail(정수만으론 불충분).
8. **machine vs judgment gate**: machine hard 자동, judgment는 hard 자동판정 안 함. prohibited-shortcuts 자연어→자동 Hard Fail 안 함.
9. **공용 policy engine**: `method_contracts.evaluate_handoff_edge`가 spawn·transition 동일 판정(profile-to-profile edge, binding/cardinality/required-state).
10. **2지점 handoff gate**: consumer spawn 차단(required-input 부재) + stage transition 차단. 양쪽 active만 hard, 한쪽 draft→warning+debt event.
11. **activation trusted CLI**: registry 직접 write 차단(guard_tools), CLI가 golden+validation+HUMAN hash 확인 후 os.replace. draft→active 전이, retired fallback 금지.
12. **debt event fold**: opened/resolved 이벤트, unresolved=최신 opened, cutover=0 계산.
13. **contract hash / historical**: contract-sha256 기준, 과거 보고서 historical-valid·current-usable=false stale.
14. **tier 강도 + approval-policy**: light/standard/heavy 차등, heavy HUMAN은 approval-policy 조건일 때만.
15. **cutover 계산**: 참조 profile(commands+plans+handoff scan) ⊆ active + debt 0 + 모든 역할 ≥1 필수 profile.
16. **doctor 확장**: status 분포·unresolved debt·capability section-id·파일분리 정합.
17. **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).