@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/lib/catalogue/builders/quality-scores.js

@@ -0,0 +1,635 @@
+// Quality-scores builder — emits the rubric-assessment catalogues (M-ADR 0205
+// §4.5, schema 3.2.0):
+//   quality_scores, quality_score_dimensions
+//
+// Source: `orchestration/gate-registry/<rubric>-scores.yaml`. The authored
+// surface stays YAML because a score is a judgment, authored where it asserts
+// intent; these rows are DERIVED and never edited.
+//
+// Three shapes here are counter-intuitive enough that a builder written from
+// the method's own registry TEMPLATES would get all three wrong. Each was
+// measured across 15 method-side + 152 estate-side registry files (the Phase-B
+// B0 survey, 2026-08-06), and each is guarded by a control:
+//
+//   1. TWO AUTHORED DIALECTS. All fifteen method templates specify a nested
+//      shape (`selection_policy` / `current` / `reviews`), but the live forward
+//      data is overwhelmingly FLAT — `gate` / `weighted_score` / `scored_at` /
+//      `scored_by` / `scores` / `flags` directly on the entry. Reading only the
+//      template shape would catalogue 6 entries out of 204. Both are legitimate:
+//      the templates were modernised, the data was not migrated.
+//   2. THE CONTAINER KEY IDENTIFIES NOTHING. It drifts between template and
+//      estate in 4 of 10 files (`diagrams` vs `c4_diagram_scores`, `capabilities`
+//      vs `feature_grounding_scores`, ...) and is non-unique method-side
+//      (`domains` names BOTH domain-architecture and intent-quality;
+//      `capabilities` names BOTH feature-grounding and traceability-manifest).
+//      So `rubric_id` comes from the file's `registry_type` when declared, else
+//      the filename stem minus `-scores`. Never the key.
+//   3. `corpus_ref` IS NEW AUTHORING. M-ADR 0205 §4.5 names it and the coverage
+//      instrument's staleness rule depends on it, but nothing authors it in
+//      either estate today. Rows therefore carry `staleness_basis` saying which
+//      anchor they can actually support, so no consumer can state a staleness
+//      verdict without its basis.
+//
+// LOUDNESS CONTRACT. Nothing here drops silently — that is the whole point of
+// the class. An unparseable registry, an unknown rubric_id, an ambiguous
+// container, a registry_type disagreeing with its filename, and an
+// out-of-vocabulary gate value each produce a finding naming the file, the
+// entry and the remedy. The one thing that is NOT a finding is a registry with
+// an empty container: the method repo ships fifteen of those deliberately, and
+// their emptiness is the signal the B2 coverage predicate reads, not an error
+// here.
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const REGISTRY_DIR_REL = "orchestration/gate-registry";
+/**
+ * File-level keys that are registry metadata rather than scored entries.
+ * Anything else at the top level is the entry container. The reverse family's
+ * `registry_type` / `assessed_at` / `assessed_by` are here too so that family
+ * parses with the same code path, even though only the weighted house form is
+ * emitted today (schema 3.2.0's `scoring_form` reserves the banded case).
+ */
+const HEADER_KEYS = new Set([
+    "schema_version",
+    "description",
+    "pass_threshold",
+    "registry_type",
+    "assessed_at",
+    "assessed_by",
+]);
+const BANDED_FAMILIES = new Map([
+    [
+        "reverse-repo-quality",
+        { targetKind: "repository", rubrics: ["reverseability", "repo_doc_quality"], pathField: "doc_path" },
+    ],
+    [
+        "reverse-product-quality",
+        { targetKind: "product", rubrics: ["product_synthesis_quality"], pathField: "product_path" },
+    ],
+    [
+        "reverse-platform-evidence-quality",
+        { targetKind: "platform_evidence", rubrics: ["reverse_platform_evidence_quality"], pathField: "evidence_path" },
+    ],
+]);
+/**
+ * `domain-artifact` is a THIRD shape and does not fit either map: it wraps a
+ * banded score (`current.artifact_quality` = {total, band}) in the multi-review
+ * envelope, and names its rubric per-unit in a `rubric:` field pointing at a
+ * rubric FILE. Six distinct rubrics across one estate's 66 units, so the
+ * registry_type cannot supply rubric_id and the sub-block list cannot either.
+ */
+const DOMAIN_ARTIFACT_TYPE = "reverse-domain-artifact-quality";
+const TARGET_KIND_BY_RUBRIC = new Map([
+    ["adr-quality", "adr"],
+    ["contract-quality", "contract"],
+    ["c4-diagram", "c4_diagram"],
+    ["domain-architecture", "domain"],
+    ["intent-quality", "domain"],
+    ["feature-grounding", "capability"],
+    ["traceability-manifest", "capability"],
+    ["glossary", "glossary"],
+    ["persona", "persona"],
+    ["product-definition", "product"],
+    ["screen-spec", "screen"],
+    ["strategic-doc", "strategic_doc"],
+    ["user-story", "user_story"],
+    ["work-order", "work_order"],
+    ["integration-sdd-quality", "integration"],
+]);
+/** schema 3.2.0 `quality_gate`. Deliberately UNBOUND — see that enum's note. */
+// pass-with-waiver adopted into the method vocabulary 2026-08-07 (ruled; the
+// domain-architecture rubric's waiver machinery generalised). A review
+// carrying it MUST record a waiver block — a waiver that is not recorded is
+// a fail being ignored, so its absence is a convention finding.
+const GATE_VALUES = new Set(["pass", "pass-with-waiver", "conditional", "fail", "unscored"]);
+/** §3i: rubric families whose targets live in a catalogue with a path column. */
+const RUBRIC_PATH_FAMILY = {
+    "adr-quality": "adrs",
+    "contract-quality": "contracts",
+    "intent-quality": "capabilities",
+};
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v) => typeof v === "string" ? v : typeof v === "number" ? String(v) : null;
+const num = (v) => {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v))) {
+        return Number(v);
+    }
+    return null;
+};
+/**
+ * Count raised flags across the two authored dialects:
+ *   `flags: { over_scope_risk: true, ... }`  -> count the true ones
+ *   `flags_raised: [name, ...]`              -> count the list
+ * A scalar `flags_raised: 0` also occurs in the wild (one estate authors it),
+ * and reads as zero rather than as a parse defect.
+ */
+function countFlags(entry, current) {
+    const raised = current["flags_raised"] ?? entry["flags_raised"];
+    if (Array.isArray(raised))
+        return raised.length;
+    if (typeof raised === "number")
+        return raised;
+    const flags = current["flags"] ?? entry["flags"];
+    if (isRecord(flags))
+        return Object.values(flags).filter((v) => v === true).length;
+    return 0;
+}
+/**
+ * Hard-gate state across the two dialects:
+ *   `hard_gates: { triggered: bool, reasons: [] }`
+ *   `hard_gates_triggered: [reasons]`  (empty list = not triggered)
+ */
+function hardGateTriggered(entry, current) {
+    const list = current["hard_gates_triggered"] ?? entry["hard_gates_triggered"];
+    if (Array.isArray(list))
+        return list.length > 0;
+    const hg = current["hard_gates"] ?? entry["hard_gates"];
+    if (isRecord(hg))
+        return hg["triggered"] === true;
+    return false;
+}
+function requiredActionsCount(entry, current) {
+    const explicit = num(current["required_actions_count"] ?? entry["required_actions_count"]);
+    if (explicit !== null)
+        return explicit;
+    const list = current["required_actions"] ?? entry["required_actions"];
+    return Array.isArray(list) ? list.length : 0;
+}
+/**
+ * Scorer provenance across three dialects: the nested `scorer:` block, the flat
+ * `scored_by:` free-text field, and the reverse family's file-level
+ * `assessed_by:`. A flat-dialect row therefore lands its whole provenance in
+ * `scorer_model` as free text — expected, and documented in the schema, so it
+ * does not read as a parse defect to whoever queries it later.
+ */
+function scorerFields(entry, current, fileAssessedBy) {
+    const scorer = current["scorer"] ?? entry["scorer"];
+    if (isRecord(scorer)) {
+        return {
+            scorer_provider: str(scorer["provider"]),
+            scorer_tool: str(scorer["tool"]),
+            scorer_model: str(scorer["model"]),
+            scorer_model_family: str(scorer["model_family"]),
+            scorer_prompt_version: str(scorer["prompt_version"]),
+        };
+    }
+    const flat = str(current["scored_by"] ?? entry["scored_by"]) ?? fileAssessedBy;
+    return {
+        scorer_provider: null,
+        scorer_tool: null,
+        scorer_model: flat,
+        scorer_model_family: null,
+        scorer_prompt_version: null,
+    };
+}
+/** Slug a target ref into a PK-safe token without collapsing distinct refs. */
+const slugToken = (s) => s
+    .trim()
+    .replace(/[^A-Za-z0-9_.-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+/**
+ * The effective review for a nested entry, or null when there is nothing to
+ * select. Resolution order, deliberately explicit rather than "latest wins":
+ *
+ *   1. `selection_policy.selected_review_run_id` matched against
+ *      `reviews[].review_run_id` — the registry SAYING which review is
+ *      effective is authoritative, whatever the dates say.
+ *   2. `current.review_run_id` matched the same way — the summary naming its
+ *      own source.
+ *   3. Exactly one review and no id anywhere: it is unambiguous, so use it.
+ *
+ * Several reviews with no resolvable id is NOT guessed at — the caller reports
+ * it. Picking the newest would silently choose a verdict the registry never
+ * nominated, and a scores registry's whole point is that the effective record
+ * is declared rather than inferred.
+ */
+function selectReview(entry, current) {
+    const reviews = entry["reviews"];
+    if (!Array.isArray(reviews))
+        return null;
+    const records = reviews.filter(isRecord);
+    if (records.length === 0)
+        return null;
+    const policy = entry["selection_policy"];
+    const wanted = (isRecord(policy) ? str(policy["selected_review_run_id"]) : null) ??
+        str(current["review_run_id"]);
+    if (wanted !== null) {
+        const hit = records.find((r) => str(r["review_run_id"]) === wanted);
+        if (hit)
+            return hit;
+    }
+    return records.length === 1 ? records[0] : null;
+}
+/**
+ * Fields present on `current` win; anything absent there falls back to the
+ * selected review. That direction matters: `current` is the registry's own
+ * statement of the effective headline, so a gate or weighted_score recorded
+ * there overrides the review's copy if they ever disagree — while the detail
+ * `current` does not carry comes from the review it points at.
+ */
+function mergePreferringCurrent(current, review) {
+    const out = { ...review };
+    for (const [k, v] of Object.entries(current)) {
+        if (v !== undefined && v !== null)
+            out[k] = v;
+    }
+    return out;
+}
+/** Rows for one banded sub-block, or null when the unit does not carry it. */
+function bandedRows(block, ctx) {
+    if (!isRecord(block))
+        return null;
+    const id = `${ctx.rubricId}__${ctx.targetKind}__${slugToken(ctx.targetRef)}`;
+    const stalenessBasis = ctx.corpusRef !== null ? "corpus_ref" : ctx.targetPath !== null ? "scored_at" : "none";
+    const row = {
+        id,
+        rubric_id: ctx.rubricId,
+        scoring_form: "banded",
+        target_kind: ctx.targetKind,
+        target_ref: ctx.targetRef,
+        target_path: ctx.targetPath,
+        gate: null,
+        weighted_score: null,
+        score_denominator: null,
+        band: str(block["band"]),
+        band_total: num(block["total"]),
+        scored_at: ctx.scoredAt,
+        corpus_ref: ctx.corpusRef,
+        staleness_basis: stalenessBasis,
+        review_run_id: null,
+        selection_method: null,
+        scorer_provider: null,
+        scorer_tool: null,
+        scorer_model: ctx.assessedBy,
+        scorer_model_family: null,
+        scorer_prompt_version: null,
+        flag_count: 0,
+        hard_gate_triggered: false,
+        required_actions_count: 0,
+        sdd_id: ctx.sddId,
+        source_sdd_id: null,
+    };
+    const dims = [];
+    const d = block["dimensions"];
+    if (isRecord(d)) {
+        for (const [k, v] of Object.entries(d)) {
+            dims.push({
+                id: `${id}__${slugToken(k)}`,
+                quality_score_id: id,
+                rubric_id: ctx.rubricId,
+                target_kind: ctx.targetKind,
+                target_ref: ctx.targetRef,
+                dimension_key: k,
+                dimension_score: num(v),
+                dimension_weight: null,
+                source_sdd_id: null,
+            });
+        }
+    }
+    return { row, dims };
+}
+export async function buildQualityScores(inputs) {
+    let derivedPathCount = 0;
+    const { sddPath, findings, sddId } = inputs;
+    const dir = join(sddPath, REGISTRY_DIR_REL);
+    let files;
+    try {
+        files = (await readdir(dir))
+            .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+            .sort();
+    }
+    catch {
+        // No gate-registry directory. Headers-only, and NOT a finding: the surface
+        // is optional per profile, and absence of the whole surface is not an
+        // authoring gap in it (the repo-config predicate's n/a rule, same reasoning).
+        return { qualityScores: [], qualityScoreDimensions: [] };
+    }
+    const qualityScores = [];
+    const qualityScoreDimensions = [];
+    for (const file of files) {
+        const rel = `${REGISTRY_DIR_REL}/${file}`;
+        const raw = await readFile(join(dir, file), "utf8");
+        let doc;
+        try {
+            doc = parseYaml(raw);
+        }
+        catch (e) {
+            // Measured: 3 of one estate's 10 registries do not parse (two mixing
+            // mapping and sequence entries under one container, one with a duplicate
+            // key whose two blocks hold CONTRADICTORY verdicts for the same target).
+            // A parser that tolerates duplicate keys reports the flattering figure
+            // and hides it; this one refuses, and says so.
+            // WARN, not error, and the choice is deliberate. Score registries are
+            // scoring-run output, not a method-mandated authoring surface, and the
+            // same reasoning that leaves `quality_gate` unbound applies here: this
+            // class must not hard-fail an estate's whole catalogue build over data
+            // that predates it (measured: one estate carries three such files). The
+            // loudness comes from the findings baseline — a new unbaselined finding
+            // fails the gate — which is how this method makes things loud without
+            // making builds brittle.
+            findings.add("divergence", `${rel} is not parseable YAML (${String(e.message).split("\n")[0]}) — every score it holds is invisible to the catalogue; repair the file (a duplicate key silently discards one of two judgments, and a mapping/sequence mix is invalid in every parser)`);
+            continue;
+        }
+        if (!isRecord(doc))
+            continue;
+        // --- rubric_id: registry_type, else filename. Never the container key. ---
+        const stem = basename(file).replace(/\.(yaml|yml)$/, "");
+        const fromFilename = stem.replace(/-scores$/, "");
+        const declared = str(doc["registry_type"]);
+        const rubricId = declared ?? fromFilename;
+        if (declared !== null && declared !== fromFilename) {
+            findings.add("convention", `${rel} declares registry_type '${declared}' but its filename says '${fromFilename}' — rubric_id uses the declared value; rename the file or correct registry_type so the two agree`);
+        }
+        const fileAssessedBy = str(doc["assessed_by"]);
+        // --- the banded reverse family (schema 3.3.0) ---
+        const banded = BANDED_FAMILIES.get(rubricId);
+        if (banded !== undefined || rubricId === DOMAIN_ARTIFACT_TYPE) {
+            const units = doc["units"];
+            if (!isRecord(units)) {
+                findings.add("convention", `${rel} declares registry_type '${rubricId}' but has no \`units:\` mapping — the banded family keys its entries there; no scores read from this file`);
+                continue;
+            }
+            const fileScoredAt = str(doc["assessed_at"]);
+            for (const [unitKey, unitVal] of Object.entries(units)) {
+                if (!isRecord(unitVal))
+                    continue;
+                const targetRef = str(unitVal["unit_id"]) ?? unitKey;
+                // The reverse family records the exported snapshot it read — the one
+                // place a corpus anchor is already authored anywhere in either estate.
+                const snap = unitVal["snapshot"];
+                const corpusRef = isRecord(snap) ? str(snap["source_revision"]) : null;
+                if (banded !== undefined) {
+                    const targetPath = banded.pathField ? str(unitVal[banded.pathField]) : null;
+                    for (const sub of banded.rubrics) {
+                        const built = bandedRows(unitVal[sub], {
+                            rubricId: `${rubricId}.${sub}`,
+                            targetKind: banded.targetKind,
+                            targetRef,
+                            targetPath,
+                            scoredAt: fileScoredAt,
+                            corpusRef,
+                            assessedBy: fileAssessedBy,
+                            sddId,
+                        });
+                        if (built) {
+                            qualityScores.push(built.row);
+                            qualityScoreDimensions.push(...built.dims);
+                        }
+                    }
+                }
+                else {
+                    // domain-artifact: rubric named per unit, banded score inside `current`.
+                    const current = isRecord(unitVal["current"]) ? unitVal["current"] : {};
+                    const rubricPath = str(unitVal["rubric"]);
+                    if (rubricPath === null) {
+                        findings.add("coverage", `${rel}: ${unitKey} names no \`rubric:\` — this family identifies its rubric per unit, so the score cannot be attributed; add the rubric path`);
+                        continue;
+                    }
+                    const stem = rubricPath.split("/").pop().replace(/\.md$/, "");
+                    const built = bandedRows(current["artifact_quality"], {
+                        rubricId: stem,
+                        targetKind: str(unitVal["artifact_type"]) ?? "domain_artifact",
+                        targetRef,
+                        targetPath: str(unitVal["doc_path"]),
+                        scoredAt: str(current["scored_at"]) ?? fileScoredAt,
+                        corpusRef,
+                        assessedBy: fileAssessedBy,
+                        sddId,
+                    });
+                    if (built) {
+                        qualityScores.push(built.row);
+                        qualityScoreDimensions.push(...built.dims);
+                    }
+                }
+            }
+            continue;
+        }
+        const targetKind = TARGET_KIND_BY_RUBRIC.get(rubricId);
+        if (targetKind === undefined) {
+            findings.add("coverage", `${rel} uses rubric '${rubricId}', which has no target-kind mapping — its scores are NOT catalogued; add the rubric to the quality-scores builder's TARGET_KIND_BY_RUBRIC map (a new rubric ships its registry, rubric, skill trio and seed rows; this is the fifth surface)`);
+            continue;
+        }
+        // --- the entry container: the single non-header mapping OF ENTRIES ---
+        //
+        // Detected STRUCTURALLY, not positionally. The first version counted
+        // non-header mapping keys and refused any file with more than one — which
+        // cost a whole registry whenever an author put a `rollup:` summary block
+        // beside the entries. Measured: two registries in one estate, 11 authored
+        // units and 75 dimension rows silently uncatalogued, and the summary is
+        // trivially distinguishable — its values are scalars (scored_at, total,
+        // pass/conditional/fail, note) while an entry container's values are
+        // themselves mappings.
+        //
+        // The ambiguity guard survives for the case it was actually written for:
+        // if TWO mappings both hold entry-shaped values, that is genuinely
+        // ambiguous and is still refused rather than guessed.
+        const containers = Object.entries(doc).filter(([k, v]) => !HEADER_KEYS.has(k) &&
+            isRecord(v) &&
+            Object.values(v).some((x) => isRecord(x)));
+        if (containers.length === 0)
+            continue; // headers-only registry: deliberate, silent
+        if (containers.length > 1) {
+            findings.add("convention", `${rel} has ${containers.length} mappings holding entry-shaped values (${containers.map(([k]) => k).join(", ")}) — a registry declares exactly one entry container; no scores read from this file. A scalar-valued summary block beside the entries is fine and is ignored; two containers of entries are not.`);
+            continue;
+        }
+        const container = containers[0]?.[1];
+        if (!isRecord(container))
+            continue;
+        checkNaRationale(rel, container, findings);
+        for (const [entryKey, entryVal] of Object.entries(container)) {
+            if (!isRecord(entryVal))
+                continue;
+            // --- dialect detection: nested (templates) vs flat (live estate data) ---
+            const nested = isRecord(entryVal["current"]);
+            const currentBlock = nested
+                ? entryVal["current"]
+                : entryVal;
+            // `current` is a SUMMARY, not necessarily the whole record. In the
+            // multi-review shape the method's own templates specify, the detail —
+            // scores, flags, hard_gates, required_actions — lives ONLY in the
+            // selected `reviews[]` entry, and `current` carries just the headline
+            // (run id, date, gate, weighted_score, scorer). Reading `current` alone
+            // therefore drops the detail SILENTLY, which is exactly what it did:
+            // measured on a real estate, six user-story entries lost 36 dimension
+            // rows and 13 required-action counts, and their flag counts read 0 only
+            // because those six happened to raise none — luck, not correctness.
+            const selected = selectReview(entryVal, currentBlock);
+            const current = selected
+                ? mergePreferringCurrent(currentBlock, selected)
+                : currentBlock;
+            if (nested && selected === null && !isRecord(currentBlock["scores"])) {
+                const reviews = entryVal["reviews"];
+                if (Array.isArray(reviews) && reviews.length > 0) {
+                    findings.add("coverage", `${rel}: ${entryKey} has ${reviews.length} review(s) but none can be selected as effective (selection_policy.selected_review_run_id matches no review_run_id, and current.review_run_id does not either) — its dimension scores are NOT catalogued; set selected_review_run_id to one of the recorded runs`);
+                }
+            }
+            // Flat headline keys beside a `current:` block are a compatibility
+            // shim, and a shim that DISAGREES with the effective record is the
+            // silent-failure shape found live (ledger §3am): an ingestion updated
+            // the flat score and left `current:` stale, and the catalogue published
+            // the stale value with the right one inches away in the same entry —
+            // no complaint anywhere. The disagreement is loud now. scored_at is
+            // deliberately not compared (YAML date-typing would false-positive).
+            if (nested) {
+                const disagreements = [];
+                for (const key of ["gate", "weighted_score", "corpus_ref"]) {
+                    const flat = entryVal[key];
+                    const eff = current[key];
+                    if (flat !== undefined && flat !== null && String(flat) !== String(eff ?? "")) {
+                        disagreements.push(`${key} (flat ${String(flat)} vs effective ${String(eff ?? "(empty)")})`);
+                    }
+                }
+                if (disagreements.length > 0) {
+                    findings.add("convention", `${rel}: ${entryKey} carries flat headline keys that disagree with its effective current/selected review: ${disagreements.join("; ")} — \`current:\` is authoritative and the flat keys are a compatibility shim (scoring-registry guide); update current:, and keep the flat keys agreeing or remove them`);
+                }
+            }
+            const targetRef = str(entryVal["unit_id"]) ?? entryKey;
+            let targetPath = str(entryVal["file_path"]) ?? str(current["file_path"]);
+            if (targetPath === null && inputs.cataloguePathIndex !== undefined) {
+                const family = RUBRIC_PATH_FAMILY[rubricId];
+                const index = family === undefined ? undefined : inputs.cataloguePathIndex.get(family);
+                if (index !== undefined) {
+                    const key = family === "adrs" ? targetRef.replace(/^[A-Z]+-ADR-/, "ADR-") : targetRef;
+                    const derived = index.get(key);
+                    if (derived !== undefined && derived !== "") {
+                        targetPath = derived;
+                        derivedPathCount += 1;
+                    }
+                }
+            }
+            // --- gate: unbound vocabulary, convention finding + empty cell ---
+            const rawGate = str(current["gate"]);
+            let gate = null;
+            if (rawGate !== null && rawGate.trim() !== "") {
+                if (GATE_VALUES.has(rawGate)) {
+                    gate = rawGate;
+                    if (rawGate === "pass-with-waiver") {
+                        const waiver = entryVal["waiver"] ?? current["waiver"];
+                        if (!isRecord(waiver) || str(waiver["granted_by"]) === null || str(waiver["expires"]) === null) {
+                            findings.add("convention", `${rel}: ${entryKey} is pass-with-waiver but records no waiver block (granted_by + expires required) — an unrecorded waiver is a fail being ignored; record the waiver or re-score`);
+                        }
+                    }
+                }
+                else {
+                    findings.add("convention", `${rel}: ${entryKey} has gate '${rawGate}', outside the quality_gate vocabulary (${[...GATE_VALUES].join(" | ")}) — the cell is left EMPTY rather than emitting a value no consumer can interpret; use an in-vocabulary value, or raise the extension as a method decision if the concept is real`);
+                }
+            }
+            const corpusRef = str(current["corpus_ref"]) ?? str(entryVal["corpus_ref"]);
+            const stalenessBasis = corpusRef !== null ? "corpus_ref" : targetPath !== null ? "scored_at" : "none";
+            const selectionPolicy = entryVal["selection_policy"];
+            const selectionMethod = isRecord(selectionPolicy)
+                ? str(selectionPolicy["method"])
+                : null;
+            const id = `${rubricId}__${targetKind}__${slugToken(targetRef)}`;
+            qualityScores.push({
+                id,
+                rubric_id: rubricId,
+                scoring_form: "weighted",
+                target_kind: targetKind,
+                target_ref: targetRef,
+                target_path: targetPath,
+                gate,
+                weighted_score: num(current["weighted_score"]),
+                score_denominator: num(entryVal["score_denominator"] ?? current["score_denominator"]),
+                // Empty on a weighted row by design — the two scales never share a
+                // column, so an average over weighted_score is correct by construction.
+                band: null,
+                band_total: null,
+                scored_at: str(current["scored_at"]) ?? str(entryVal["scored_at"]),
+                corpus_ref: corpusRef,
+                staleness_basis: stalenessBasis,
+                review_run_id: str(current["review_run_id"]),
+                selection_method: selectionMethod,
+                ...scorerFields(entryVal, current, fileAssessedBy),
+                flag_count: countFlags(entryVal, current),
+                hard_gate_triggered: hardGateTriggered(entryVal, current),
+                required_actions_count: requiredActionsCount(entryVal, current),
+                sdd_id: sddId,
+                source_sdd_id: null,
+            });
+            // --- dimensions: the rubric's own keys, verbatim ---
+            const scores = current["scores"];
+            if (isRecord(scores)) {
+                for (const [dimKey, dimVal] of Object.entries(scores)) {
+                    qualityScoreDimensions.push({
+                        id: `${id}__${slugToken(dimKey)}`,
+                        quality_score_id: id,
+                        rubric_id: rubricId,
+                        target_kind: targetKind,
+                        target_ref: targetRef,
+                        dimension_key: dimKey,
+                        dimension_score: num(dimVal),
+                        dimension_weight: null,
+                        source_sdd_id: null,
+                    });
+                }
+            }
+        }
+    }
+    // Total order, per M-ADR 0205 §4.2 — the committed CSV must be byte-stable.
+    qualityScores.sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+    qualityScoreDimensions.sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+    // Duplicate ids mean two entries scored the same target under one rubric.
+    // BOTH rows are emitted rather than one being dropped: dropping would pick a
+    // winner between two possibly-contradictory verdicts, which is precisely how
+    // that defect stayed invisible in an estate for a month. The builder
+    // diagnoses; the downstream pk-duplicate check owns fatality, which is where
+    // PK integrity belongs.
+    const seen = new Set();
+    for (const row of qualityScores) {
+        const id = String(row["id"]);
+        if (seen.has(id)) {
+            findings.add("divergence", `quality_scores: duplicate id '${id}' — two registry entries score the same target under the same rubric; both rows are emitted (the pk check fails on them) rather than one being silently preferred, because the two verdicts may disagree`);
+        }
+        seen.add(id);
+    }
+    // §3i: derivation is RECORDED, not silent — a derived path changes a row's
+    // staleness basis, and an unstated basis change is the class this whole
+    // family exists to prevent.
+    if (derivedPathCount > 0) {
+        inputs.findings.add("coverage", `quality_scores: ${derivedPathCount} target path(s) resolved through the catalogue rather than authored in the registry — staleness basis becomes scored_at (coarse); author file_path (or corpus_ref, precise) to upgrade`);
+    }
+    return { qualityScores, qualityScoreDimensions };
+}
+/**
+ * `na_rationale` (scoring-registry guide, ruled 2026-10-01): an N/A dimension is ABSENT from
+ * `scores` and explained in a `na_rationale` mapping beside it, keyed by the same dimension key.
+ * Checked on the effective record (the selected review merged with `current`), report-only:
+ *   - na_rationale must be a mapping (a single string cannot say WHICH dimension it explains);
+ *   - a dimension cannot be both scored and N/A.
+ * NOT checked here: that every N/A dimension HAS a reason. That needs the rubric's own dimension
+ * list. Deriving it from the registry being checked (the union of keys its entries score) was tried
+ * and measured wrong twice on one estate: a registry mixing two spellings of one rubric's keys, and
+ * entries scored before the rubric gained a dimension. Both are artefacts of a self-supplied
+ * denominator, not missing reasons.
+ */
+export function checkNaRationale(rel, container, findings) {
+    const effective = [];
+    for (const [entryKey, entryVal] of Object.entries(container)) {
+        if (!isRecord(entryVal))
+            continue;
+        const currentBlock = isRecord(entryVal["current"]) ? entryVal["current"] : entryVal;
+        const selected = selectReview(entryVal, currentBlock);
+        effective.push([entryKey, selected ? mergePreferringCurrent(currentBlock, selected) : currentBlock]);
+    }
+    for (const [entryKey, rec] of effective) {
+        if (!isRecord(rec["scores"]))
+            continue;
+        const scored = new Set(Object.keys(rec["scores"]));
+        const na = rec["na_rationale"];
+        if (na !== undefined && !isRecord(na)) {
+            findings.add("convention", `${rel}: ${entryKey} na_rationale is a ${Array.isArray(na) ? "list" : typeof na}, not a mapping — key each reason by the dimension it explains (scoring-registry guide, Recording N/A)`, "warn", `na_rationale:${rel}:${entryKey}`);
+            continue;
+        }
+        const explained = new Set(isRecord(na) ? Object.keys(na) : []);
+        for (const k of explained) {
+            if (scored.has(k)) {
+                findings.add("convention", `${rel}: ${entryKey} dimension ${k} is both scored and given an N/A reason — it is one or the other`, "warn", `na_rationale:${rel}:${entryKey}:${k}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=quality-scores.js.map