fix(metrics): metric calibration — fidelity improvements across all dimensions

config/dimensions.yaml

@@ -11,6 +11,8 @@ dimensions:
     applies_to:
       product_types: ["charm", "snap"]
     aggregation: "worst_in_scope"
+    required_metrics_for_scoring:
+      - latest_build_passing
     outputs:
       coverage_pct: {type: number, range: "0–100", label: "Coverage", description: "Percentage of automated test checks passing in the latest Allure summary."}
       stability_pct: {type: number, range: "0–100", label: "Stability", description: "Percentage of non-broken, non-failed checks in the latest Allure summary."}
@@ -29,6 +31,10 @@ dimensions:
     applies_to:
       product_types: ["charm", "snap"]
     aggregation: "worst_in_scope"
+    required_metrics_for_scoring:
+      - readme_meets_structure
+      - contributing_meets_structure
+      - has_security
     outputs:
       readme_meets_structure: {type: boolean, label: "README meets structure", description: "README differs from the single-charm template and contains required sections. Uses canonical/platform-engineering-charm-template and canonical/backup-operators to distinguish repo types."}
       contributing_meets_structure: {type: boolean, label: "CONTRIBUTING meets structure", description: "CONTRIBUTING differs from template and contains required contribution and governance sections."}
@@ -49,6 +55,9 @@ dimensions:
     applies_to:
       product_types: ["charm"]
     aggregation: "worst_in_scope"
+    required_metrics_for_scoring:
+      - supports_juju_3
+      - substrate_test_evidence_present
     outputs:
       supports_juju_3: {type: boolean, label: "Juju 3 support", description: "Workflow or metadata evidence declares Juju 3 support."}
       supports_juju_4: {type: boolean, label: "Juju 4 support", description: "Workflow or metadata evidence declares Juju 4 support."}
@@ -65,6 +74,9 @@ dimensions:
     applies_to:
       product_types: ["charm", "snap"]
     aggregation: "worst_in_scope"
+    required_metrics_for_scoring:
+      - branch_protection_required_checks
+      - renovate_enabled
     outputs:
       renovate_enabled: {type: boolean, label: "Renovate enabled", description: "Repository is configured for Renovate updates."}
       canonical_repo_automation_registered: {type: boolean, label: "Canonical repo automation registered", description: "Repository is onboarded in canonical-repo-automation."}
@@ -82,6 +94,10 @@ dimensions:
     applies_to:
       product_types: ["root", "charm", "snap"]
     aggregation: "worst_in_scope"
+    required_metrics_for_scoring:
+      - avg_triage_days
+      - avg_pr_review_days
+      - response_coverage_rate
     outputs:
       avg_triage_days: {type: number, range: "≥ 0 days", label: "Avg. triage time", description: "Average days from issue creation to first non-author response."}
       avg_pr_review_days: {type: number, range: "≥ 0 days", label: "Avg. PR review time", description: "Average days from PR opening to first submitted review."}

config/schemas/dimensions.schema.json

@@ -72,6 +72,14 @@
           "type": "string",
           "enum": ["worst_in_scope"],
           "description": "How leaf results are aggregated into the root product medal. worst_in_scope: minimum medal among in-scope leaves."
+        },
+        "required_metrics_for_scoring": {
+          "type": "array",
+          "description": "Metric keys that must be present and non-null before this dimension is scoreable. If any are missing, the dimension becomes insufficient_data instead of falling back to bronze/unrated semantics.",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          }
         }
       }
     },

docs/local-scoring.md

@@ -101,6 +101,34 @@ are evaluated by `assemble.py`, so `make _assemble` alone picks them up from the
 
 ---
 
+## Measurability gates (`required_metrics_for_scoring`)
+
+Each dimension may declare `required_metrics_for_scoring` in `config/dimensions.yaml`.
+This is a list of metric keys that must be present and non-null before PQF will score that
+dimension.
+
+- If every required metric is present, the normal medal rubric runs.
+- If any required metric is missing or `null`, the dimension becomes
+  `insufficient_data` and its medal is forced to `unrated`.
+- Use this for **measurability** checks only — for example, a missing latest test result or
+  a support sample that was too small to calculate averages.
+- Do **not** use it for normal failing values. A measured `false`, `0`, or low percentage
+  should still be scored by the rubric.
+
+Current examples:
+
+- `test_verification` requires `latest_build_passing`
+- `documentation` requires the core documentation presence/structure booleans
+- `substrate_compat` requires a declared Juju support signal plus substrate CI evidence
+- `security_ssdlc` requires branch protection and dependency-update measurability
+- `support_engagement` requires the sampled response metrics that can otherwise be `null`
+
+This means a rubric-only change still needs a full recompute when scorer outputs or nullability
+semantics change, because regenerated `computed/*.json` data may now shift products from
+`scored` to `insufficient_data`.
+
+---
+
 ## Documentation scoring without LLM
 
 `score-no-llm` and `score` currently produce the same documentation outputs. The