# design-direction-spec — design-direction child plan 의 9 아티팩트 계약(정본).
# 정본 = 이 YAML + lint_design_direction.py(hand-coded). 별도 JSON Schema 파일 없음.
# spec: docs/superpowers/specs/2026-07-13-p2-design-direction-design.md (rev2: 7 아티팩트·finalize·exact 바인딩)
design-direction-spec:
  version: 3
  purpose: "제품 cascade 종속 child plan 의 아티팩트 계약. brief 를 발산 이전/승인 이후로 분리(S1)."

  artifacts:
    # ① 발산 이전 입력 — 부모 /design 이 완성·불변화, child init 에서 hash 바인딩. child 는 수정 금지.
    direction-input-brief:
      required: [product-goal, core-users, core-tasks, information-density,
                 required-accessibility, brand-constraints, avoid-cliches,
                 representative-screen-requirement, tech-platform-constraints]
      prohibited: [reference-cluster, color-palette, typography, layout-grammar, tokens, visual-metaphor]
      note: "prohibited 항목은 승인 이후 design-system-brief 가 approved-direction 으로부터 확정."
      conditional-required:
        when: "parent workload가 public-website 또는 new-product|major-redesign"
        fields: [competitive-experience-benchmark-ref, competitive-experience-benchmark-sha256,
                 experience-blueprint-ref, experience-blueprint-sha256,
                 wireframe-set-ref, wireframe-set-sha256]
        enforcement: "state_engine.init_ledger가 부모 experience-foundation approval exact refs와 대조"

    # ② discovery 산출 — 불변 brief 를 분석(수정 아님).
    direction-discovery:
      required: [direction-input-brief-sha256, findings, constraints-restated, opportunity-notes]

    # ③ 발산 전 계약 — 완성 direction-set 과 분리한다. 각 워커가 답할 질문과
    # 조형 영역을 먼저 직교 분할하여 "같은 카드 셸의 색상 변주"를 차단한다.
    divergence-charter:
      required: [direction-cycle-id, representative-screen, directions, pairwise-separation]
      direction-required: [id, design-question, layout-topology, navigation-model,
                           typography-voice, imagery-strategy, motion-model,
                           dominant-primitives, exclusive-primitives, forbidden-primitives]
      rules:
        - "정확히 3개 방향, id 중복 금지"
        - "모든 방향 쌍은 layout/navigation/type/imagery/motion/primitives 중 최소 4축이 다르다"
        - "exclusive-primitives 는 방향 간 겹치지 않는다"
        - "한 방향이 centered-card/progress-rail/pill-cta 조합을 쓰면 다른 방향은 이를 금지한다"

    # ④ divergence 산출 — 3안 독립 생산 + 실제 비교 렌더.
    direction-set:
      required: [direction-cycle-id, divergence-charter-ref, divergence-charter-sha256,
                 representative-screen, directions, comparison-preview]
      representative-screen: {required: [id, kind, description], kind-enum: [first-entry, core-task, signature-moment]}
      comparison-preview:
        required: [receipt-ref, receipt-sha256, gallery-path, representative-screen-id]
      experience-foundation-binding:
        when: "parent workload가 foundation을 요구"
        required: [experience-blueprint-ref, experience-blueprint-sha256,
                   wireframe-set-ref, wireframe-set-sha256]
        per-direction-required: [content-contract-sha256]
        rule: "세 방향의 content-contract-sha256은 동일한 accepted wireframe-set SHA여야 한다."
      direction-required: [id, producer-role-id, producer-run-id, context-package-id,
                           concept-artifact, reference-cluster, visual-thesis, layout-grammar,
                           interaction-grammar, typography-token-direction, primitive-inventory,
                           reference-board-ref, reference-board-sha256,
                           full-size-preview-ref, full-size-preview-sha256,
                           coded-slice, coded-slice-sha256]
      reference-cluster-rules:
        - "3~6개로 집중한다(20개 산만보다 6개 집중)"
        - "각 항목은 name, signal, why-relevant 를 가진다"
        - "형용사(modern/clean/minimal/sleek)만으로 설명하지 않는다"
        - "방향 쌍 사이 reference name 중복은 최대 1개"

    # ⑤ 선택 전 비교 감사 — 이 렌즈만 sibling isolation 을 적용하지 않는다.
    comparative-divergence-audit:
      required: [direction-cycle-id, divergence-charter-ref, divergence-charter-sha256,
                 direction-set-ref, direction-set-sha256, reviewer-role-id, reviewer-run-id,
                 verdict, pairwise-comparisons, full-size-previews, blocking-findings]
      verdict-enum: [pass, revise, re-diverge]
      benchmark-relative-required-when-foundation:
        fields: [competitive-experience-benchmark-ref,
                 competitive-experience-benchmark-sha256, benchmark-relative-findings]
        min-findings: 3
      rules:
        - "pass 는 모든 방향 쌍 비교와 full-size preview hash 검증이 완료된 경우만 가능"
        - "각 방향 쌍은 최소 4개 조형 축에서 달라야 한다"
        - "primitive collision 또는 blocking finding 이 하나라도 있으면 pass 금지"
        - "색을 제거해도 layout/type/imagery/interaction 구조로 식별 가능해야 한다"

    # ⑥ decision 산출 — 1안 선택(승인 아님). 평균금지(S5). direction-set 에 바인딩.
    selected-direction:
      required: [direction-cycle-id, direction-set-ref, direction-set-sha256, selection-decision,
                 rejected-directions, parent-workflow-id, product-decision-id,
                 direction-input-brief-sha256, selection-acceptance-receipt]
      optional: [flexible-elements, adopted-elements]
      rules:
        - "selection-decision은 selected 또는 none-of-the-above. selected이면 selected-direction-id 정확히 1개이고 direction-set에 실존"
        - "selected이면 locked-invariants >= 3"
        - "none-of-the-above이면 세 안을 모두 사유와 함께 reject하고 locked/adopted 요소 없이 discovery로 되돌린다"
        - "rejected-directions 가 모든 비선택 방향을 정확히 덮는다(유령/누락 금지), 각 reason 필수"
        - "locked-invariants >= 3"
        - "secondary-influence-id 필드 금지(평균의 뒷문)"
        - "adopted-elements <= 1, from-direction-id 실존, element-id+rationale 필수, 포괄표현 금지, locked-invariant 침범 금지"

    # ⑦ prototype 산출 — 승자 핵심흐름 + 실제 preview receipt. revision 추적.
    winner-prototype:
      required: [direction-cycle-id, selected-direction-ref, selected-direction-sha256,
                 prototype-path, prototype-sha256, preview-receipt-ref, preview-receipt-sha256, revision]

    # ⑧ critique 산출 — 다관점 패널(S3). producer != reviewer.
    design-review-panel:
      required: [direction-cycle-id, target-prototype, preview-receipt, reviews, synthesis]
      review-required: [reviewer-role-id, reviewer-run-id, lens, verdict, report-ref, report-sha256]
      required-lenses: [product-fit, usability, distinctiveness, visual-craft,
                        systematizability, market-memorability, implementability]
      synthesis: {required: [role-id, verdict, unresolved-dissent], verdict-enum: [pass, minor-revision, concept-flaw]}
      veto-rules:
        - "모든 개별 lens verdict 가 pass 여야 synthesis pass 가능"
        - "distinctiveness 또는 visual-craft 비통과는 synthesis 가 덮을 수 없다"
        - "blocking/critical finding 또는 unresolved-dissent 가 있으면 pass 금지"

    # ⑨ terminal 불변 report — 전부를 hash 로 묶음(S2). completion-records 경로.
    approved-direction:
      required: [child-workflow-id, direction-cycle-id, selected-direction-ref, selected-direction-sha256,
                 winner-prototype-ref, winner-prototype-sha256, critique-report-refs, critique-pass-receipt,
                 preview-receipt-ref, locked-invariants, approved-at,
                 parent-workflow-id, product-decision-id, direction-input-brief-sha256]
      path: "<ws>/completion-records/<child-workflow-id>/approved-direction-<ts>.report.yaml"
      parent-ledger-ref: {key: design-direction-approval, fields: [report-ref, report-sha256, child-workflow-id]}

  cross-references:
    - "design-brief-spec.yaml (design-system-brief = brief-phase: system-ready)"
    - "state-transition-rules.yaml / execution-plans.yaml (design-direction plan)"
    - "collaboration-map.yaml (direction-gate)"