# Architect scorecard contract.
#
# Source of truth for score dimensions, 0..100 bands and anchors, confidence
# levels, and report comparability rules. Report frontmatter references these by
# name. Bump rubric_version when any dimension, band edge, or anchor changes;
# reports built under different rubric versions are not directly comparable.

rubric_version: 1
# Score bands map a 0..100 value to a qualitative label. Edges are inclusive.
bands:
  - name: critical
    min: 0
    max: 20
    anchor: Boundaries absent or routinely bypassed. Changes ripple unpredictably. Architecture intent is neither documented nor enforced.
  - name: poor
    min: 21
    max: 40
    anchor: Some structure exists but is widely violated. Frequent cross-boundary coupling and cycles. Intent and reality diverge sharply.
  - name: mixed
    min: 41
    max: 60
    anchor: Structure holds in parts. Notable violations and hotspots remain. Intent is partly enforced, partly aspirational.
  - name: serviceable
    min: 61
    max: 80
    anchor: Boundaries mostly respected. Few cycles. Most change stays local. Some intent is enforced by checks.
  - name: strong
    min: 81
    max: 100
    anchor: Boundaries explicit and enforced. Healthy dependency graph. Change stays local. Architecture intent is executable via fitness checks.
# Confidence levels describe how trustworthy the assessment is, independent of
# the quality value itself.
confidence_levels:
  - name: low
    meaning: Thin or indirect evidence. Key tools missing or failed. Treat scores as provisional.
  - name: medium
    meaning: Multiple evidence sources but gaps remain in coverage or recency.
  - name: high
    meaning: Applicable evidence dimensions covered with working tools and direct file/graph references.
# Core scored dimensions. analysis_confidence is meta: it scores the review,
# not the architecture.
dimensions:
  - name: boundary_integrity
    measures: Whether code respects intended module, layer, and ownership boundaries.
  - name: coupling_balance
    measures: Integration strength vs distance vs volatility (Balanced Coupling).
  - name: dependency_graph_health
    measures: Cycles, hubs, bypassed layers, clusters vs intended modules.
  - name: cohesion_modularity
    measures: Whether modules group related behavior; size skew; vocabulary mixing.
  - name: change_locality
    measures: Whether changes stay inside intended boundaries over history.
  - name: architecture_fitness
    measures: Whether architecture intent is executable via checks, not just docs.
  - name: analysis_confidence
    measures: How trustworthy this review is given tool coverage and evidence.
# Rules enforced by validate-report and compare-reports.
rules:
  # A score's band must match its value against the bands table.
  band_matches_value: true
  # A high quality band (serviceable or strong) requires at least medium
  # confidence. Low-confidence reviews cannot present high quality as settled.
  high_quality_requires_confidence:
    bands:
      - serviceable
      - strong
    min_confidence: medium
  # Every non-meta score must carry at least one evidence reference. Absence of
  # findings is evidence only when a current tool covered that problem class.
  score_requires_evidence: true
  # Coverage-gap calibration (advisory; applied by the scorecard skill, not the
  # validator, because "independently re-established" needs agent judgment).
  # Missing/partial/stale PRIMARY evidence for a dimension forces low confidence
  # and caps the band at mixed (value <= 60); default to the band midpoint. This
  # makes down-calibration of tool false-greens reproducible in magnitude.
  coverage_gap_caps_quality:
    max_band: mixed
    max_value: 60
    confidence: low
# Two reports are comparable only when all of these match. compare-reports must
# emit an explicit non-comparability reason otherwise.
comparability:
  must_match:
    - scope
    - rubric_version
    - tool_coverage_level
  tool_coverage_levels:
    - minimal
    - standard
    - deep