# Design-System Review Schema — Layer 3 Specialized Document Type
# KNO Schema Version: 0.1.0
#
# Layer 3 schema that extends document-schema.kno for design-system review entities.
# Defines the structure for review outputs produced by the design-reviewer capability
# in either page-scale or DS-scale mode.
#
# PURPOSE: Define the schema for design-system review documents.
# Every file with `type: design-system-review` conforms to this schema.
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
# RELATED: style-guide-schema.kno (review subjects conform to that schema)
#
# Sibling-schema rationale (per Pass 11 §4):
#   - R-900-series rules describe review entities, not style-guide entities
#   - The shape (per-lens findings, kinship scores, severity tuples) is fundamentally
#     different from style-guide token shape
#   - Independent versioning cadence (lens framework will iterate; shouldn't drag
#     style-guide-schema along)
#   - Cross-reference is clean: style-guide.review_capability.schema points here

# =============================================================================
# SCHEMA DECLARATION (RFC-007)
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KZ4Y8DQR8WDVP1G2C7N9MZBE
slug: design-system-review-schema
type: spec
version: 0.1.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Design-System Review Schema"
purpose: |
  Define the schema for design-system review entities produced by the
  design-reviewer capability (page-scale and DS-scale modes).

  **Two review modes** (R-901):
  - **page-scale** — single page/flow review using the 5-lens model
    (IA / UX / UI-A11y / DS / Brand)
  - **ds-scale** — whole design-system review using the 10-lens model
    (L1 Identity / L2 Tokens / L3 Components / L4 Documentation /
    L5 Governance / L6 Versioning / L7 Contribution + L7a/L7b sub-lenses /
    L8 Agent-Affordance / L9 Cross-Tier-Integrity / L10 Coherence)

  **No aggregate score** (R-907): the schema MUST NOT contain a single
  rolled-up "design system maturity" score field. Severity counts and
  per-lens verdicts are reportable; a single number is not.

  **Verdict tuple** (R-920): per-lens scores use the 5-tuple
  PASS / PARTIAL / FAIL / SKIP / UNTESTABLE — distinct from finding
  severity (BLOCKER / MAJOR / MINOR / COSMETIC / PE positive-evidence).

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
provenance:
  origin:
    id: 01KZ4Y8DQR8WDVP1G2C7N9MZBE
    timestamp: "2026-04-30T00:00:00Z"
    tool: manual-creation
    rationale: "Pass 11 schema-extension proposal §4 — sibling schema for R-900
      lens-framework series"

taxonomy:
  topics:
    - design-systems
    - review
    - audit
    - quality
    - lens-framework
  keywords:
    - design-system-review
    - lens-framework
    - kinship-scoring
    - severity-rubric
    - verdict-tuple

relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type"

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "kno@0.0.9 defines the format"

  composes:
    - xri: "kno://specs/identity-schema"
      reason: "Layer 1: id, canonical_id"
    - xri: "kno://specs/history-schema"
      reason: "Layer 1: _history, changelog"
    - xri: "kno://specs/quality-schema"
      reason: "Layer 1: quality, validation"

  related_to:
    - xri: "kno://specs/style-guide-schema"
      reason: "Reviews target style-guide entities; style-guide.review_capability
        points here"
    - xri: "kno://capabilities/design-reviewer"
      reason: "Capability that produces review entities conforming to this schema"

quality:
  completeness: 0.85
  last_reviewed: "2026-04-30"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY (P9 Temporal)
# =============================================================================
_history:
  retention: full
  format: snapshot

  versions:
    - version: "0.1.0"
      date: "2026-04-30"
      author: "claude"
      summary: "Initial schema — codifies R-900 lens-framework series from Pass 7-10
        catalog"
      changes:
        - "Created Layer 3 schema for design-system review entities"
        - "Defined required_fields: review_mode, framework_version, subject,
          cluster_inferred, ds_definition_inferred"
        - "Defined recommended_sections: lenses (per-lens findings),
          agent_affordance_intensity, secondary_tags, kinship, summary"
        - "Defined validation rules: no_aggregate_score, review_mode_required,
          lens_count_matches_mode"
        - "Catalog source: tmp/design-rules-catalog/10-canonical-catalog.md
          (R-900-R-941)"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Draft

  description: |
    ## What is a design-system review?

    A **design-system review** is a structured audit of a design system's
    quality, maturity, and conformance. Reviews come in two scopes:

    - **page-scale** reviews evaluate a single page or user flow against the
      5-lens model (IA, UX, UI-A11y, DS, Brand)
    - **ds-scale** reviews evaluate an entire design system against the
      10-lens framework (L1-L10 plus L7a/L7b contribution sub-lenses)

    ## Schema philosophy

    **No aggregate score.** Maturity is multi-dimensional. Reviews report
    severity counts, per-lens verdicts, and recommended actions — but never
    a single rolled-up "score". Consumers wanting a one-number proxy must
    derive it themselves from severity_counts.

    **Severity ≠ verdict.** A finding's `severity` (BLOCKER/MAJOR/MINOR/
    COSMETIC/PE) is distinct from a lens's `score` (PASS/PARTIAL/FAIL/SKIP/
    UNTESTABLE). Severity describes a single observation; verdict describes
    a whole-lens assessment.

    **Cluster-aware weighting.** The 10 lenses are weighted differently per
    DS cluster (1-5). A documentation-heavy DS (cluster 4) weights L4 high
    and L8 medium; a tooling-heavy DS (cluster 2) weights L8 high and L4
    medium.

  # ===========================================================================
  # REQUIRED FIELDS (R-901, R-908, R-900)
  # ===========================================================================
  required_fields:
    review_mode:
      # R-901
      type: enum
      values: [ "page-scale", "ds-scale" ]
      description: "Selects the lens count and weighting model"
    framework_version:
      type: string
      example: "1.0"
      description: "Version of the lens framework spec used
        (research/2026_04_21-design-systems-research/09-design-systems-lens-fra\
        mework.md)"
    subject:
      type: object
      fields:
        url: string
        organization: string
        ds_name: string
        commit_sha: string # Optional — pin review to a specific source state
    cluster_inferred:
      # R-908
      type: enum
      values: [ 1, 2, 3, 4, 5 ]
      description: "Which of 5 DS clusters this subject belongs to (drives lens weighting)"
    ds_definition_inferred:
      # R-900
      type: enum
      values: [ "library", "discipline", "gateway", "multi-ds-portal", "multi-context" ]
      description: "What kind of design-system the subject is"

  # ===========================================================================
  # RECOMMENDED SECTIONS
  # ===========================================================================
  recommended_sections:
    - name: "lenses"
      description: "Per-lens findings (10 + L7a/L7b for ds-scale; 5 for page-scale)"
      structure:
        type: array
        items:
          id: string # "L1"…"L10","L7a","L7b" or "page-scale-1"…"page-scale-5"
          name: string
          weight_for_cluster:
            # R-910
            type: enum
            values: [ "high", "medium", "low", "na" ]
          tier_target:
            # R-911
            type: enum
            values: [ "A", "B", "C" ]
          score:
            # R-920 verdict tuple
            type: enum
            values: [ "PASS", "PARTIAL", "FAIL", "SKIP", "UNTESTABLE" ]
          findings:
            type: array
            items:
              severity:
                # R-906 severity rubric
                type: enum
                values: [ "BLOCKER", "MAJOR", "MINOR", "COSMETIC", "PE" ]
              title: string
              evidence_url: string
              evidence_observation: string
              catalog_citation: string # P_N | AP-NN | PE-NN
              recommendation: string
          strengths: string[]
          opportunities: string[]

    - name: "agent_affordance_intensity"
      description: "L8 6-rung intensity assessment (R-905)"
      structure:
        rung:
          type: enum
          values: [ 0, 1, 2, 3, 4, 5 ]
        evidence: string

    - name: "secondary_tags"
      description: "9-tag secondary taxonomy (R-909)"
      structure:
        hosting:
          type: enum
        ecosystem:
          type: enum
        ai_chrome:
          type: enum
        event_tied_release:
          type: enum
        landmark_hygiene:
          type: enum
        generational_migration:
          type: enum
        authorship_culture:
          type: enum
        token_a11y_aware:
          type: enum
        dual_audience:
          type: enum

    - name: "kinship"
      description: "Kinship-scoring output (R-913)"
      structure:
        top_kin:
          type: array
          items:
            site: string
            score: number
            shared_dimensions: string[]
        structurally_kin_to: string[]
        cross_cluster_bridges: string[]

    - name: "summary"
      description: "Severity counts + meta-pattern presence + recommended actions.
        MUST NOT contain a single aggregate score field (R-907)."
      structure:
        severity_counts:
          blocker: integer
          major: integer
          minor: integer
          cosmetic: integer
          pe: integer
        no_aggregate_score:
          # R-907 — must remain true
          type: boolean
          required_value: true
          description: "Sentinel field that asserts no rolled-up score field exists"
        strong_meta_patterns_present: string[]
        anti_pattern_meta_findings: string[]
        recommended_actions:
          type: array
          items:
            priority: integer # 1-5
            title: string
            lens: string
            severity:
              type: enum
              values: [ "BLOCKER", "MAJOR", "MINOR", "COSMETIC", "PE" ]

  # ===========================================================================
  # VALIDATION RULES
  # ===========================================================================
  validation:
    rules:
      - name: "no_aggregate_score"
        description: "summary MUST NOT contain a single rolled-up score field;
          summary.no_aggregate_score MUST equal true (R-907)"
        rollout: strict
      - name: "review_mode_required"
        description: "review_mode field MUST be set (R-901)"
        rollout: strict
      - name: "lens_count_matches_mode"
        description: "page-scale → 5 lenses; ds-scale → 12 lenses (10 + L7a + L7b)
          (R-902, R-903, R-912)"
        rollout: strict
      - name: "verdict_uses_5_tuple"
        description: "lens.score MUST be one of PASS/PARTIAL/FAIL/SKIP/UNTESTABLE —
          distinct from severity (R-920)"
        rollout: strict
      - name: "severity_uses_rubric"
        description: "finding.severity MUST be one of BLOCKER/MAJOR/MINOR/COSMETIC/PE
          (R-906)"
        rollout: strict
      - name: "framework_version_pinned"
        description: "framework_version MUST be a pinned semver string"
        rollout: warn

  # ===========================================================================
  # EXAMPLE STRUCTURE
  # ===========================================================================
  example:
    minimal: |
      id: 01KZ4Y8DQR8WDVP1G2C7N9MZBF
      type: design-system-review
      version: 0.1.0
      title: "DS Review — example.com"
      purpose: "ds-scale review"

      review_mode: ds-scale
      framework_version: "1.0"
      subject:
        url: "https://example.com/design-system"
        organization: "Example Co"
        ds_name: "Example DS"
      cluster_inferred: 4
      ds_definition_inferred: discipline

      lenses:
        - id: L1
          name: "Identity"
          weight_for_cluster: medium
          tier_target: B
          score: PARTIAL
          findings: []
          strengths: ["Wordmark canonicalised"]
          opportunities: ["Brand voice not codified"]

      summary:
        severity_counts: {blocker: 0, major: 2, minor: 5, cosmetic: 1, pe: 3}
        no_aggregate_score: true
        strong_meta_patterns_present: ["canonicalisation discipline"]
        anti_pattern_meta_findings: []
        recommended_actions:
          - priority: 1
            title: "Codify brand voice"
            lens: L1
            severity: MAJOR

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "spec/required_fields"
    keywords: [ review_mode, framework_version, cluster, ds_definition ]
  - path: "spec/recommended_sections/lenses"
    keywords: [ lenses, findings, severity, verdict ]
  - path: "spec/recommended_sections/summary"
    keywords: [ severity_counts, no_aggregate_score, recommended_actions ]
  - path: "spec/validation"
    keywords: [ no_aggregate_score, lens_count_matches_mode ]

contains:
  - xri: "#identity"
    role: section
    title: "Schema Metadata"
    keywords: [ id, type, version ]
  - xri: "#spec"
    role: section
    title: "Design-System Review Schema"
    keywords: [ lenses, findings, severity, verdict, kinship ]
  - xri: "#examples"
    role: section
    title: "Usage Examples"
    keywords: [ minimal, ds-scale, page-scale ]