477 lines
33 KiB
Markdown
477 lines
33 KiB
Markdown
# 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).
|