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

package/dist/lib/catalogue/scores-coverage.js

@@ -0,0 +1,573 @@
+/**
+ * Scores coverage — M-ADR 0205 §4.5's coverage instrument, the fourteenth
+ * engine check (Phase B, B2). SQL on the §4.1 engine, like every other
+ * catalogue-reading predicate; `check-repo-config-coverage.sh` remains the
+ * only shell survivor and is not the model for this.
+ *
+ * The claim: *every eligible artefact carries a current score*. Eligibility is
+ * computed per rubric against the catalogue that holds its targets, and the
+ * predicate reports BOTH directions, because the two say different things:
+ *
+ *   - an eligible target with no score is a GAP — nobody has judged it;
+ *   - a score whose target does not resolve is an ORPHANED SCORE — the
+ *     assessment corpus has decayed away from the model it describes.
+ *
+ * The second direction is not decoration. Measured on the forward estate at
+ * introduction: 85 of 99 ADR scores point at ids that no longer exist, because
+ * a rename moved the ADR canon and the registry keys were never migrated. A
+ * one-directional predicate would have reported that estate as having 99
+ * scored ADRs while none of them resolved.
+ *
+ * THE JOIN VOCABULARY IS THE WHOLE DIFFICULTY, and it is declared rather than
+ * guessed. A registry's entry keys are not the catalogue's ids, and the
+ * mismatch differs per rubric — measured, not assumed:
+ *
+ *   - contract-quality keys are SPEC PATHS (`contracts-avro/.../X.avsc`),
+ *     joining `contracts.spec_path`; against `contracts.id` they score 0 of 55.
+ *   - adr-quality keys carry a tier prefix (`M-ADR-0001`) the catalogue strips
+ *     (`ADR-0001`); the raw join scores 0 of 99.
+ *   - domain-architecture keys are plain domain slugs and join `domains.id`
+ *     directly, 13 of 13.
+ *
+ * So each rubric declares its catalogue, its join column and its reference
+ * transform, and the predicate REPORTS the resolution rate it achieved. A join
+ * that silently resolves nothing looks exactly like an estate that has scored
+ * nothing — the confident-false-zero shape this whole phase exists to remove.
+ *
+ * Rubrics whose targets have NO catalogue (c4-diagram, strategic-doc,
+ * user-story, work-order) have no eligibility denominator to compute. They are
+ * reported as such by name and their scores are still resolution-checked as
+ * far as they can be — never silently omitted, because a rubric missing from
+ * the output reads as a rubric with nothing to say.
+ *
+ * Reporting-only at both tiers, per §4.5. Exemption vocabulary starts EMPTY
+ * (M-ADR 0199): there is no way to mark a target exempt yet, deliberately, so
+ * the first figure is the honest total.
+ *
+ * ADOPTION GATING — a rubric is measured only where its REGISTRY EXISTS. An SDD
+ * that carries no `<rubric>-scores.yaml` has not adopted that rubric, so it has
+ * no eligible population for it, and reporting its whole ADR/contract/capability
+ * corpus as unscored would be true-but-useless noise. This is the same n/a rule
+ * the repo-config predicate applies and the same rule the quality-scores builder
+ * applies to an absent registry directory: absence of the whole surface is not a
+ * gap in it. Measured before adopting it: without this rule ONE reverse-estate
+ * SDD emits 630 gap lines for rubrics it has never used, which across that
+ * estate would swamp the baseline re-take and bury the real signal.
+ *
+ * The distinction that must NOT be lost, and is not: a registry that EXISTS but
+ * is EMPTY reports its full population as gaps. That is the method repo's own
+ * state — fifteen deliberately-empty containers — and it is exactly the silence
+ * §4.5 exists to make loud. Absent surface and empty surface are different
+ * claims, and conflating them is the defect this whole phase is about.
+ *
+ * The n/a count is always printed. A rubric skipped silently reads as a rubric
+ * with nothing to report.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readLockFile } from "../lock-file.js";
+/**
+ * The declared mapping. Three entries are EXERCISED against real estate data
+ * (adr-quality, contract-quality, domain-architecture); the rest are declared
+ * from the registry and rubric shapes and have no populated corpus to verify
+ * against yet — a distinction the metric line states rather than blurs.
+ */
+export const RUBRIC_ELIGIBILITY = [
+    // ── The banded reverse family (schema 3.3.0, Phase B4) ──────────────────
+    //
+    // EVERY join below was MEASURED against a real estate before being declared,
+    // and the three that do not resolve are declared unmeasurable rather than
+    // given a plausible transform. That discipline is not decorative: an earlier
+    // ADR mapping in this arc was "verified" by checking that its targets EXISTED
+    // in a dense id range, which is nearly free, and it turned out to point 75 of
+    // 99 scores at the wrong ADR. Existence is not correctness.
+    {
+        rubricId: "reverse-repo-quality.reverseability",
+        registryFile: "reverse-repo-quality-scores.yaml",
+        targetKind: "repository",
+        catalogue: "repositories",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Every catalogued repository. Measured 123/123 resolving against 370 repositories — a real 33% coverage figure, not a join defect.",
+    },
+    {
+        rubricId: "reverse-repo-quality.repo_doc_quality",
+        registryFile: "reverse-repo-quality-scores.yaml",
+        targetKind: "repository",
+        catalogue: "repositories",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Same population as reverseability — the two rubrics judge different things about the same repository. Measured 123/123.",
+    },
+    {
+        rubricId: "reverse-product-quality.product_synthesis_quality",
+        registryFile: "reverse-product-quality-scores.yaml",
+        targetKind: "product",
+        catalogue: "domains",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Joins DOMAINS, not products, and that is measured rather than inferred from the name: 9/9 against domains, 0/9 against products. The reverse method's 'product' units are per-domain product areas; the target_kind records what the rubric calls them, the join records where they resolve.",
+    },
+    {
+        rubricId: "reverse-platform-evidence-quality.reverse_platform_evidence_quality",
+        registryFile: "reverse-platform-evidence-quality-scores.yaml",
+        targetKind: "platform_evidence",
+        catalogue: "domains",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Platform evidence is assessed per domain. Measured 9/9.",
+    },
+    {
+        rubricId: "reverse-data-model-quality",
+        registryFile: "domain-artifact-scores.yaml",
+        targetKind: "data-model",
+        catalogue: "domain_models",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Every domain model. Measured 9/9 against 12.",
+    },
+    {
+        rubricId: "reverse-glossary-quality",
+        registryFile: "domain-artifact-scores.yaml",
+        targetKind: "glossary",
+        catalogue: "domains",
+        joinColumn: "id",
+        refTransform: (r) => `regexp_replace(${r}, '-glossary$', '')`,
+        eligibilityFilter: null,
+        eligibilityNote: "One glossary per domain; refs are '<domain>-glossary'. Measured 9/9 after the suffix strip, 0/9 without it.",
+    },
+    {
+        rubricId: "reverse-c4-quality",
+        registryFile: "domain-artifact-scores.yaml",
+        targetKind: "c4-l2",
+        catalogue: "domains",
+        joinColumn: "id",
+        refTransform: (r) => `regexp_replace(${r}, '-c4-l2$', '')`,
+        eligibilityFilter: null,
+        eligibilityNote: "One L2 diagram per domain; refs are '<domain>-c4-l2'. Measured 8/8 after the strip, 0/8 without it.",
+    },
+    {
+        rubricId: "reverse-capability-spec-quality",
+        registryFile: "domain-artifact-scores.yaml",
+        targetKind: "capability-spec",
+        catalogue: "capabilities",
+        joinColumn: "id",
+        // Refs are '<domain>-capability-spec-<capability>'; the capability is the tail.
+        refTransform: (r) => `regexp_replace(${r}, '^.*-capability-spec-', '')`,
+        eligibilityFilter: "status <> 'deprecated'",
+        eligibilityNote: "Measured 19/19 on the tail. The domain prefix is NOT part of capabilities.id here, so the whole ref resolves to nothing (0/19) — the transform is required, not cosmetic. Excludes deprecated capabilities on the same footing as feature-grounding and traceability-manifest: three rubrics judging one catalogue must agree about who is in the population, and a rubric that disagreed would reintroduce as a metric discrepancy exactly the retirement the other two just retired. Missed on the first pass because the control hardcoded two rubric names instead of deriving them; it now derives them.",
+    },
+    // ── Banded rubrics with NO catalogued eligibility population ─────────────
+    {
+        rubricId: "reverse-feature-grounding-quality",
+        registryFile: "domain-artifact-scores.yaml",
+        targetKind: "feature-grounding",
+        catalogue: null,
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "NO local population, measured rather than assumed. Refs are '<domain>-feature-grounding-<slug>' and the tails are SIBLING SDD SLUGS (app-shell, cold-chain, connect-rapide), not rows in this SDD: 0/15 against products, applications, features and repositories, and 1/15 against capabilities — a coincidence, not a join. A cross-SDD reference the member tier cannot resolve, so its coverage is declared unmeasurable rather than given a transform that would produce plausible wrong numbers.",
+    },
+    {
+        rubricId: "reverse-contract-quality",
+        registryFile: "domain-artifact-scores.yaml",
+        targetKind: "contract",
+        catalogue: null,
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "HETEROGENEOUS targets in one rubric: '<domain>-event-catalog' (resolves to domains, 2/2) and '<domain>-openapi-<service>' (0/4 against contracts — the tails are service names, not contract ids). A rubric gets one eligibility entry, and half a join is worse than none, so the whole rubric is declared unmeasurable until the reverse method splits it.",
+    },
+    // ── The forward house form ───────────────────────────────────────────────
+    {
+        rubricId: "adr-quality",
+        targetKind: "adr",
+        catalogue: "adrs",
+        joinColumn: "id",
+        // The catalogue strips the tier prefix (M-ADR 0186 §4.4); registries keep it.
+        refTransform: (r) => `regexp_replace(${r}, '^[A-Z]+-ADR-', 'ADR-')`,
+        eligibilityFilter: "status = 'Accepted'",
+        managedPathColumn: "doc_path",
+        canonicalPathColumn: "doc_path",
+        eligibilityNote: "Accepted only, and adopter-owned only. A Proposed ADR is mid-decision and a Superseded one is history; requiring a current score on either would manufacture a gap nobody should close. The managed-path rule adds the second half of the same argument, ruled 2026-08-07: an adopter cannot remediate an ADR that sync overwrites, so a method-managed ADR is not in the adopter's denominator — its quality belongs to the producer's own registry, and an adopter's assessment of it is feedback to raise rather than a row to maintain. Measured at both estates 2026-08-08 (committed catalogues, member tier): forward 203 Accepted -> 83 adopter-owned (120 excluded); reverse 182 Accepted -> 62 adopter-owned (120 excluded). Zero rows under a producer path escaped the lock at either estate, so the lock and a path heuristic agree on today's data — the lock is used anyway, because agreement today is not the same as being the right rule.",
+    },
+    {
+        rubricId: "contract-quality",
+        targetKind: "contract",
+        catalogue: "contracts",
+        joinColumn: "spec_path",
+        refTransform: null,
+        eligibilityFilter: "status <> 'deprecated'",
+        canonicalPathColumn: "spec_path",
+        eligibilityNote: "Every non-deprecated contract. Deprecated contracts are excluded for the same reason the contract-coverage predicate excludes them — they are on the way out, and scoring them is work with no consumer.",
+    },
+    {
+        rubricId: "domain-architecture",
+        targetKind: "domain",
+        catalogue: "domains",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Every domain on disk. A domain that exists is a domain that should be assessed.",
+    },
+    {
+        rubricId: "intent-quality",
+        targetKind: "domain",
+        catalogue: "domains",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Every domain, same population as domain-architecture — the two rubrics judge different things about the same unit.",
+    },
+    {
+        rubricId: "feature-grounding",
+        targetKind: "capability",
+        catalogue: "capabilities",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: "status <> 'deprecated'",
+        eligibilityNote: "Every capability. EXCLUDES DEPRECATED CAPABILITIES — the SAME PATTERN contract-quality already applies to the contracts catalogue (identical operator and value, and its note gives the same reason: they are on the way out, and scoring them is work with no consumer), and the same argument adr-quality makes for a Superseded ADR. This applies an existing pattern to a third catalogue rather than setting a new one. This is the mechanism that retires a withdrawn capability's permanently-unanswerable findings, replacing the M-ADR 0199 exemption vocabulary that was investigated and NOT built: across both estates the authored-intent evidence base was zero, and a retirement expressed in the catalogue's OWN documented vocabulary needs no annotation surface. It resolves only where the retirement is DECLARED — a capability whose traceability manifest was deleted has no authored status and falls to the builder's hardcoded default, so declaring the state is the estate-side half.",
+    },
+    {
+        rubricId: "traceability-manifest",
+        targetKind: "capability",
+        catalogue: "capabilities",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: "status <> 'deprecated'",
+        eligibilityNote: "Every capability. Excludes deprecated capabilities per feature-grounding's note — the rubrics judging this catalogue must agree about who is in the population.",
+    },
+    {
+        rubricId: "glossary",
+        targetKind: "glossary",
+        catalogue: "domains",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "One glossary per domain — the registry keys by domain slug, so the eligible population is domains, not glossary_items (a glossary is scored whole, not term by term).",
+    },
+    {
+        rubricId: "persona",
+        targetKind: "persona",
+        catalogue: "personas",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Every persona.",
+    },
+    {
+        rubricId: "product-definition",
+        targetKind: "product",
+        catalogue: "products",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Every product.",
+    },
+    {
+        rubricId: "screen-spec",
+        targetKind: "screen",
+        catalogue: "screens",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Every screen.",
+    },
+    {
+        rubricId: "integration-sdd-quality",
+        targetKind: "integration",
+        catalogue: "integrations",
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Every integration.",
+    },
+    // ── No catalogued eligibility population ────────────────────────────────
+    // These rubrics score artefacts the catalogue model does not hold, so there
+    // is no denominator to compute. Declared explicitly so they appear in the
+    // output as "no denominator" rather than being absent — an absent rubric
+    // reads as a rubric with nothing to report.
+    {
+        rubricId: "c4-diagram",
+        targetKind: "c4_diagram",
+        catalogue: null,
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Diagrams are files, not catalogue rows.",
+    },
+    {
+        rubricId: "strategic-doc",
+        targetKind: "strategic_doc",
+        catalogue: null,
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Strategic documents are not catalogued.",
+    },
+    {
+        rubricId: "user-story",
+        targetKind: "user_story",
+        catalogue: null,
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "User stories are not catalogued.",
+    },
+    {
+        rubricId: "work-order",
+        targetKind: "work_order",
+        catalogue: null,
+        joinColumn: "id",
+        refTransform: null,
+        eligibilityFilter: null,
+        eligibilityNote: "Work orders are not catalogued.",
+    },
+];
+const sqlStr = (s) => `'${s.replace(/'/g, "''")}'`;
+async function rows(session, sql) {
+    const reader = await session.conn.runAndReadAll(sql);
+    return reader.getRows();
+}
+/**
+ * Every path claimed by a synced bundle in this repo's lock, mapped to the
+ * bundle claiming it.
+ *
+ * Empty at the producer — it carries no `method-baseline.lock`, so nothing is
+ * written from elsewhere and nothing is excluded. That is the degenerate case
+ * working by construction rather than by a repo-kind check: `canonical-method`
+ * is not even a member of the CLI's `RepoKind` union, so a check on it would
+ * have been a special case resting on a marker the type system does not model.
+ */
+async function managedPathOwners(sddRoot) {
+    const lock = await readLockFile(sddRoot);
+    const owners = new Map();
+    if (!lock)
+        return owners;
+    for (const bundle of lock.bundles) {
+        for (const p of bundle.managedPaths) {
+            // First claim wins, matching `pathToBundleMap`: a path claimed twice is a
+            // sync-side concern, and this predicate is not the place to adjudicate it.
+            if (!owners.has(p))
+                owners.set(p, bundle.name);
+        }
+    }
+    return owners;
+}
+/**
+ * Runs the predicate. `available` names the catalogues actually present, so a
+ * rubric whose population file is absent is skipped the way every other
+ * predicate skips an absent population — silently, because absence of the
+ * whole surface is not a gap in it — while a rubric whose population is
+ * PRESENT but empty still reports its zero.
+ */
+export async function runScoresCoverage(session, options) {
+    const findings = [];
+    const metrics = [];
+    if (!options.available.has("quality_scores")) {
+        return {
+            findings: [],
+            metrics: [],
+            undeclaredRubrics: [],
+            notAdopted: [],
+            stalenessBasis: { corpusRef: 0, scoredAt: 0, none: 0 },
+            totalScores: 0,
+            transformBridgedRefs: 0,
+        };
+    }
+    const totalScores = Number((await rows(session, `SELECT COUNT(*) FROM "quality_scores";`))[0][0]);
+    const transformBridgedRefs = Number((await rows(session, `SELECT COUNT(*) FROM "quality_scores"
+         WHERE rubric_id = 'adr-quality' AND regexp_matches(target_ref, '^[A-Z]+-ADR-');`))[0][0]);
+    const basis = await rows(session, `SELECT staleness_basis, COUNT(*) FROM "quality_scores" GROUP BY 1 ORDER BY 1;`);
+    const stalenessBasis = { corpusRef: 0, scoredAt: 0, none: 0 };
+    for (const [b, n] of basis) {
+        const c = Number(n);
+        if (b === "corpus_ref")
+            stalenessBasis.corpusRef = c;
+        else if (b === "scored_at")
+            stalenessBasis.scoredAt = c;
+        else
+            stalenessBasis.none = c;
+    }
+    // A row that can support no staleness verdict at all is its own finding.
+    // Without it the predicate would silently treat "unknown" as "fresh", which
+    // is the basis error this column exists to prevent.
+    if (stalenessBasis.none > 0) {
+        findings.push({
+            kind: "unresolvable-staleness",
+            rubricId: "(all)",
+            subject: `${stalenessBasis.none} score(s) carry neither corpus_ref nor a resolvable target_path — their currency is UNKNOWN, not fresh`,
+        });
+    }
+    const managedOwners = await managedPathOwners(options.sddRoot);
+    const declared = new Set(RUBRIC_ELIGIBILITY.map((r) => r.rubricId));
+    const present = await rows(session, `SELECT DISTINCT rubric_id FROM "quality_scores" ORDER BY 1;`);
+    const undeclaredRubrics = present
+        .map((r) => String(r[0]))
+        .filter((r) => !declared.has(r));
+    const adopted = (spec) => existsSync(join(options.sddRoot, "orchestration", "gate-registry", spec.registryFile ?? `${spec.rubricId}-scores.yaml`));
+    const notAdopted = [];
+    for (const spec of RUBRIC_ELIGIBILITY) {
+        if (!adopted(spec)) {
+            notAdopted.push(spec.rubricId);
+            continue;
+        }
+        const scored = Number((await rows(session, `SELECT COUNT(*) FROM "quality_scores" WHERE rubric_id = ${sqlStr(spec.rubricId)};`))[0][0]);
+        // No catalogued population: report the scores, state that there is no
+        // denominator, and do not invent one.
+        if (spec.catalogue === null) {
+            if (scored > 0) {
+                metrics.push({
+                    rubricId: spec.rubricId,
+                    targetKind: spec.targetKind,
+                    eligible: null,
+                    covered: scored,
+                    scored,
+                    orphaned: 0,
+                    managedExcluded: 0,
+                    managedExcludedByBundle: {},
+                    recordedPath: null,
+                });
+            }
+            continue;
+        }
+        if (!options.available.has(spec.catalogue))
+            continue;
+        // The method-managed exclusion, resolved BEFORE any count is taken so that
+        // every figure below shares one denominator. Computed here rather than
+        // inlined at each query because `eligibleWhere` reaches four call sites,
+        // and a rule applied to three of them is worse than a rule applied to none.
+        const excludedRows = spec.managedPathColumn && managedOwners.size > 0
+            ? await rows(session, `SELECT "${spec.managedPathColumn}" FROM "${spec.catalogue}"
+              WHERE (${spec.eligibilityFilter ?? "TRUE"})
+                AND "${spec.managedPathColumn}" IN (${[...managedOwners.keys()].map(sqlStr).join(", ")});`)
+            : [];
+        const managedExcludedByBundle = {};
+        for (const [p] of excludedRows) {
+            const bundle = managedOwners.get(String(p)) ?? "(unknown bundle)";
+            managedExcludedByBundle[bundle] = (managedExcludedByBundle[bundle] ?? 0) + 1;
+        }
+        const managedExcluded = excludedRows.length;
+        const eligibleWhere = managedExcluded > 0
+            ? `(${spec.eligibilityFilter ?? "TRUE"}) AND "${spec.managedPathColumn}" NOT IN (${[
+                ...managedOwners.keys(),
+            ]
+                .map(sqlStr)
+                .join(", ")})`
+            : (spec.eligibilityFilter ?? "TRUE");
+        if (scored === 0) {
+            // The population exists and nothing is scored — the loudest case, and
+            // exactly the silence M-ADR 0205 §4.5 names. Every eligible row is a gap.
+            const eligibleRows = await rows(session, `SELECT id FROM "${spec.catalogue}" WHERE (${eligibleWhere}) ORDER BY id;`);
+            for (const [id] of eligibleRows) {
+                findings.push({ kind: "uncovered", rubricId: spec.rubricId, subject: String(id) });
+            }
+            metrics.push({
+                rubricId: spec.rubricId,
+                targetKind: spec.targetKind,
+                eligible: eligibleRows.length,
+                covered: 0,
+                scored: 0,
+                orphaned: 0,
+                managedExcluded,
+                managedExcludedByBundle,
+                recordedPath: spec.canonicalPathColumn !== undefined ? { agree: 0, mismatch: 0, noRecordedPath: 0 } : null,
+            });
+            continue;
+        }
+        const ref = spec.refTransform ? spec.refTransform("s.target_ref") : "s.target_ref";
+        // Eligibility is always a conjunct, so it composes with the not-exists
+        // clause without any string surgery on an assembled WHERE — `TRUE` for the
+        // unfiltered case keeps one query shape instead of two.
+        const scoreSet = `SELECT * FROM "quality_scores" WHERE rubric_id = ${sqlStr(spec.rubricId)}`;
+        // Direction 1 — eligible targets with no score.
+        const uncovered = await rows(session, `SELECT c.id FROM "${spec.catalogue}" c
+        WHERE (${eligibleWhere})
+          AND NOT EXISTS (SELECT 1 FROM (${scoreSet}) s WHERE ${ref} = c."${spec.joinColumn}")
+        ORDER BY c.id;`);
+        for (const [id] of uncovered) {
+            findings.push({ kind: "uncovered", rubricId: spec.rubricId, subject: String(id) });
+        }
+        // Direction 2 — scores whose target does not resolve.
+        const orphaned = await rows(session, `SELECT s.target_ref FROM (${scoreSet}) s
+        WHERE NOT EXISTS (
+          SELECT 1 FROM "${spec.catalogue}" c WHERE c."${spec.joinColumn}" = ${ref}
+        )
+        ORDER BY s.target_ref;`);
+        for (const [r] of orphaned) {
+            findings.push({ kind: "orphaned-score", rubricId: spec.rubricId, subject: String(r) });
+        }
+        // Direction 3 — scores whose target RESOLVES but sits outside this repo's
+        // scope. Only reachable where the managed rule actually excluded something.
+        if (managedExcluded > 0) {
+            const outOfScope = await rows(session, `SELECT s.target_ref FROM (${scoreSet}) s
+          WHERE EXISTS (
+            SELECT 1 FROM "${spec.catalogue}" c
+             WHERE c."${spec.joinColumn}" = ${ref}
+               AND c."${spec.managedPathColumn}" IN (${[...managedOwners.keys()]
+                .map(sqlStr)
+                .join(", ")})
+          )
+          ORDER BY s.target_ref;`);
+            for (const [r] of outOfScope) {
+                findings.push({
+                    kind: "out-of-scope-score",
+                    rubricId: spec.rubricId,
+                    subject: String(r),
+                });
+            }
+        }
+        // Direction 4 — a resolved score whose RECORDED path is not the target's
+        // canonical path (decision #3, report-only). Paths are normalised on both
+        // sides (leading `./` stripped, backslashes to `/`) before comparison. A
+        // path the builder filled in from the catalogue agrees by construction —
+        // the metric says "agree", not "verified".
+        let recordedPath = null;
+        if (spec.canonicalPathColumn !== undefined) {
+            const pairs = await rows(session, `SELECT s.target_ref, s.target_path, c."${spec.canonicalPathColumn}"
+           FROM (${scoreSet}) s
+           JOIN "${spec.catalogue}" c ON c."${spec.joinColumn}" = ${ref}
+          ORDER BY s.target_ref;`);
+            let agree = 0;
+            let mismatch = 0;
+            let noRecordedPath = 0;
+            const n = (v) => String(v ?? "").replace(/\\/g, "/").replace(/^(\.\/)+/, "");
+            for (const [targetRef, recorded, canonical] of pairs) {
+                const r = n(recorded);
+                const c = n(canonical);
+                if (r === "")
+                    noRecordedPath++;
+                else if (c === "" || r === c)
+                    agree++;
+                else {
+                    mismatch++;
+                    findings.push({
+                        kind: "recorded-path-mismatch",
+                        rubricId: spec.rubricId,
+                        subject: `${String(targetRef)} — recorded "${r}", catalogue "${c}"`,
+                    });
+                }
+            }
+            recordedPath = { agree, mismatch, noRecordedPath };
+        }
+        const eligible = Number((await rows(session, `SELECT COUNT(*) FROM "${spec.catalogue}" WHERE (${eligibleWhere});`))[0][0]);
+        metrics.push({
+            rubricId: spec.rubricId,
+            targetKind: spec.targetKind,
+            eligible,
+            covered: eligible - uncovered.length,
+            scored,
+            orphaned: orphaned.length,
+            managedExcluded,
+            managedExcludedByBundle,
+            recordedPath,
+        });
+    }
+    return { findings, metrics, undeclaredRubrics, notAdopted, stalenessBasis, totalScores, transformBridgedRefs };
+}
+//# sourceMappingURL=scores-coverage.js.map

package/dist/lib/catalogue/screen-validation-loader.js

@@ -0,0 +1,89 @@
+/**
+ * Loader for the optional `.sdd/screen-validation.yaml` config — the
+ * adopter-tunable parameters for screen-spec composition-depth validation
+ * (ADR 0168 §4.5) and the archetype overlay (ADR 0169 §4.3).
+ *
+ * Every field is optional and carries a method default; an absent file means
+ * "method defaults only" (the vocabulary-free checks all still run). Follows
+ * the same shape convention as the `.sdd/*-aliases.yaml` loaders.
+ *
+ * File shape:
+ *
+ *     flat_threshold: 6                 # screen-flat-composition N (default 6)
+ *     decorative_primitives:            # unlocks screen-styling-primitive-as-structure
+ *       - Spacer
+ *       - Divider
+ *     archetype_overlays:               # per-platform overlay (ADR 0169 §4.3)
+ *       web-generic:
+ *         strip_prefixes: [Mdc, Mde]    # render-only: stripped when humanising labels
+ *         overrides:
+ *           VBespokeGrid: grid
+ *       swiftui:
+ *         overrides:
+ *           BrandCard: card
+ *
+ * The decorative set + the overlays are adopter-owned (vendor-standard defaults
+ * ship in the method; bespoke names live here). The checks themselves stay
+ * vocabulary-free — they consume these parameters, they don't hardcode them.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const SCREEN_VALIDATION_REL_PATH = join(".sdd", "screen-validation.yaml");
+/**
+ * Load the optional screen-validation config. Returns `null` when the file is
+ * absent — callers apply method defaults. Throws on malformed YAML.
+ */
+export async function loadScreenValidationConfig(sddPath) {
+    const full = join(sddPath, SCREEN_VALIDATION_REL_PATH);
+    let text;
+    try {
+        text = await readFile(full, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const raw = parseYaml(text);
+    if (raw === null || typeof raw !== "object") {
+        throw new Error(`${SCREEN_VALIDATION_REL_PATH}: expected a mapping at the document root`);
+    }
+    const flatThreshold = typeof raw.flat_threshold === "number" && Number.isFinite(raw.flat_threshold) && raw.flat_threshold > 0
+        ? raw.flat_threshold
+        : undefined;
+    const decorativePrimitives = new Set();
+    if (Array.isArray(raw.decorative_primitives)) {
+        for (const v of raw.decorative_primitives) {
+            if (typeof v === "string" && v !== "")
+                decorativePrimitives.add(v);
+        }
+    }
+    const archetypeOverlays = new Map();
+    if (raw.archetype_overlays !== null && typeof raw.archetype_overlays === "object" && !Array.isArray(raw.archetype_overlays)) {
+        for (const [platform, body] of Object.entries(raw.archetype_overlays)) {
+            const overrides = toStringMap(body?.overrides);
+            const stripPrefixes = toStringList(body?.strip_prefixes);
+            if (Object.keys(overrides).length > 0 || stripPrefixes.length > 0) {
+                archetypeOverlays.set(platform, { overrides, strip_prefixes: stripPrefixes });
+            }
+        }
+    }
+    return { flatThreshold, decorativePrimitives, archetypeOverlays, relPath: SCREEN_VALIDATION_REL_PATH };
+}
+function toStringMap(raw) {
+    const out = {};
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return out;
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v === "string" && v !== "")
+            out[k] = v;
+    }
+    return out;
+}
+function toStringList(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((v) => typeof v === "string" && v !== "");
+}
+//# sourceMappingURL=screen-validation-loader.js.map