@shrkcrft/inspector 0.1.0-alpha.29 → 0.1.0-alpha.31

package/dist/quality-report.d.ts

@@ -1,5 +1,6 @@
 import { type IDriftReport } from './drift.js';
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import { type IVerdictCoverage } from '@shrkcrft/core';
 export interface IQualityGateResult {
     id: string;
     label: string;
@@ -13,7 +14,15 @@ export interface IQualityGateResult {
     data?: Record<string, unknown>;
 }
 export interface IQualityReport {
-    overall: 'pass' | 'fail' | 'warn';
+    /**
+     * `fail` — a blocking gate failed. `not-verified` — no blocking gate failed,
+     * but a gate could not run, examined nothing while required, or examined
+     * only part of its scope (core's `coverageShortfall` over {@link coverage}):
+     * never a pass, for MCP, the dashboard and the report site alike. `warn` —
+     * a non-blocking gate failed. `pass` — every gate that was asked for
+     * examined its whole scope and passed.
+     */
+    overall: 'pass' | 'fail' | 'warn' | 'not-verified';
     blockers: number;
     warnings: number;
     score: number;
@@ -21,6 +30,14 @@ export interface IQualityReport {
     nextRecommendations: readonly string[];
     /** Drift report attached when the drift gate ran. */
     drift?: IDriftReport;
+    /**
+     * What the report examined (unit `quality gates`), from the one
+     * classification `shrk quality` also reads (`examineQualityGate`).
+     * Always set by `buildQualityReport`.
+     */
+    coverage?: IVerdictCoverage;
+    /** The shortfall that made `overall` `not-verified`, when one did. */
+    shortfalls?: readonly string[];
 }
 export interface IQualityConfig {
     minReadiness?: number;
@@ -40,6 +57,16 @@ export interface IBuildQualityReportInput {
      * read-only path so the server never executes shell commands.
      */
     skipShell?: boolean;
+    /** Narrow the knowledge stale-check gate to entries referencing these files (`shrk quality --changed-only`). */
+    changedFiles?: readonly string[];
+    /**
+     * Set ONLY by `shrk quality`, which runs the seven data-defined gate planes
+     * itself (some spawn shells). Every other consumer — MCP, the dashboard, the
+     * report site — does not run them, so it gets a `gate-planes` row with
+     * `executed: false` whenever the config declares any plane rule: the report
+     * is then `not-verified`, never a `pass` over rules it never evaluated.
+     */
+    callerRunsGatePlanes?: boolean;
 }
 /**
  * Build a quality report from an inspection. Pure orchestration over the

package/dist/quality-report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quality-report.d.ts","sourceRoot":"","sources":["../src/quality-report.ts"],"names":[],"mappings":"AAOA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAUjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,qDAAqD;IACrD,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,qBAAqB,CAAC;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,cAAc,CAAC,CA0OzB"}
+{"version":3,"file":"quality-report.d.ts","sourceRoot":"","sources":["../src/quality-report.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAcjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAS1E,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,qDAAqD;IACrD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,sEAAsE;IACtE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,qBAAqB,CAAC;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gHAAgH;IAChH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAkZzB"}

package/dist/quality-report.js

@@ -1,10 +1,19 @@
-import { evaluateBoundaries, loadTsconfigPaths, scanImports, } from '@shrkcrft/boundaries';
 import { buildAiReadinessReport } from "./ai-readiness.js";
+import { describeBoundaryConfiguration } from "./boundary-configuration-status.js";
+import { boundaryLoadIssueLabel, runBoundaryCheck } from "./run-boundary-check.js";
 import { buildCoverageReport } from "./coverage-report.js";
 import { buildDriftReport } from "./drift.js";
-import { buildPackDoctorReport } from "./pack-doctor.js";
+import { buildPackDoctorReportAsync } from "./pack-doctor.js";
+import { packDoctorVerdict } from "./pack-doctor-verdict.js";
+import { declaredGatePlaneRules } from "./declared-gate-plane-rules.js";
+import { knowledgeStaleQualityGate } from "./knowledge-stale-quality-gate.js";
 import { runDoctor } from "./sharkcraft-inspector.js";
+import { doctorVerdict } from "./doctor-verdict.js";
 import { loadAgentContractTests, loadContextTests, runAgentContractTest, runContextTest, } from "./test-runner.js";
+import { warmReferenceRegistries } from "./reference-registry.js";
+import { coverageShortfall } from '@shrkcrft/core';
+import { qualityReportCoverage } from "./quality-report-coverage.js";
+import { buildDeclaredXrefReport, declaredXrefCoverage, declaredXrefSummaryLine, isBrokenXref, } from "./declared-cross-references.js";
 /**
  * Build a quality report from an inspection. Pure orchestration over the
  * existing inspector helpers — no IO outside what those helpers already do.
@@ -12,8 +21,12 @@ import { loadAgentContractTests, loadContextTests, runAgentContractTest, runCont
 export async function buildQualityReport(input) {
     const { inspection, config, strict = false, skipShell = false } = input;
     const gates = [];
-    // 1. Doctor.
+    // 1. Doctor. A scope the doctor could not verify (a compiled pack build with
+    // no build record) is PARTIAL here, exactly as `shrk doctor` settles it to 2.
     const doctor = runDoctor(inspection);
+    // THE doctor settlement (`doctorVerdict`) — the one `shrk doctor`, `shrk
+    // check`, the dashboard and MCP `inspect_sharkcraft_setup` read.
+    const doctorShortfalls = doctorVerdict(doctor).shortfalls;
     gates.push({
         id: 'doctor',
         label: 'Project doctor',
@@ -21,13 +34,15 @@ export async function buildQualityReport(input) {
         blocking: true,
         runsShell: false,
         executed: true,
-        notes: doctor.checks
-            .filter((c) => c.severity === 'error')
-            .map((c) => `${c.title}: ${c.message}`),
+        notes: [
+            ...doctor.checks.filter((c) => c.severity === 'error').map((c) => `${c.title}: ${c.message}`),
+            ...(doctorShortfalls.length > 0 ? [`NOT VERIFIED — ${doctorShortfalls.join('; ')}`] : []),
+        ],
         data: {
             errors: doctor.summary.errors,
             warnings: doctor.summary.warnings,
             ok: doctor.summary.ok,
+            ...(doctorShortfalls.length > 0 ? { partial: true, shortfalls: doctorShortfalls } : {}),
         },
     });
     // 2. Readiness threshold.
@@ -46,7 +61,9 @@ export async function buildQualityReport(input) {
         data: { score: readiness.score, min: readinessMin, grade: readiness.grade },
     });
     // 3. Boundaries. The boundary scan reads files from disk but does not run
-    // shell commands; safe for MCP.
+    // shell commands; safe for MCP. Through the ONE boundary orchestrator
+    // (round 11), so this gate reports exactly what `check boundaries` does —
+    // an errored rule counts as an error, a partial scope is never a pass.
     const boundaries = checkBoundaries(inspection);
     gates.push({
         id: 'boundaries',
@@ -56,7 +73,12 @@ export async function buildQualityReport(input) {
         runsShell: false,
         executed: true,
         notes: boundaries.notes,
-        data: { errors: boundaries.errors, warnings: boundaries.warnings },
+        data: {
+            errors: boundaries.errors,
+            warnings: boundaries.warnings,
+            examinedNothing: boundaries.examinedNothing === true,
+            ...(boundaries.partial ? { partial: true, shortfalls: boundaries.shortfalls ?? [] } : {}),
+        },
     });
     // 4. Coverage.
     const cov = buildCoverageReport(inspection);
@@ -103,7 +125,11 @@ export async function buildQualityReport(input) {
         gates.push({
             id: 'drift',
             label: 'Drift report',
-            passed: true,
+            // A gate that threw proved NOTHING. `passed: true` here would fold an
+            // unmeasured verdict into the green count and the score — the exact
+            // silent-green the loud-skip contract exists to prevent. `executed:
+            // false` marks it unmeasured; the score below excludes it either way.
+            passed: false,
             blocking: false,
             runsShell: false,
             executed: false,
@@ -124,14 +150,21 @@ export async function buildQualityReport(input) {
             runsShell: false,
             executed: true,
             notes: failed > 0 ? [`${failed}/${results.length} context tests failed`] : [],
-            data: { total: results.length, failed },
+            // `failed === 0` over ZERO tests is not a pass — it examined nothing.
+            // Flagged so the CLI aggregate reports the gate as skipped (a deliberate
+            // skip when the gate is optional, NOT verified when it is required).
+            data: { total: results.length, failed, examinedNothing: results.length === 0 },
         });
     }
     catch (e) {
         gates.push({
             id: 'context-tests',
             label: 'Context tests',
-            passed: true,
+            // A gate that threw proved NOTHING. `passed: true` here would fold an
+            // unmeasured verdict into the green count and the score — the exact
+            // silent-green the loud-skip contract exists to prevent. `executed:
+            // false` marks it unmeasured; the score below excludes it either way.
+            passed: false,
             blocking: false,
             runsShell: false,
             executed: false,
@@ -140,9 +173,24 @@ export async function buildQualityReport(input) {
     }
     // 7. Agent tests. Likewise, pure orchestration.
     try {
+        // The agent-test runner reads the shared reference registry (MCP ≡ CLI);
+        // a warm here keeps any command resolver a CLI caller already injected.
+        await warmReferenceRegistries(inspection);
         const all = await loadAgentContractTests(inspection);
         const results = all.map((t) => runAgentContractTest(inspection, t));
-        const failed = results.filter((r) => !r.passed).length;
+        // A FAILURE is a test whose verdict is `fail`. A `not-verified` test (an
+        // expectation the runner could not evaluate — e.g. an `expectedCommands`
+        // entry with no command index injected, the MCP path) is an unexamined
+        // unit, the same verdict `shrk test agent` gives it (2): never a failure,
+        // never a pass. With no real failure the gate is PARTIAL, which the CLI
+        // aggregate reports as an accidental skip (NOT VERIFIED).
+        const failed = results.filter((r) => r.verdict === 'fail').length;
+        const notVerified = results.filter((r) => r.verdict === 'not-verified');
+        const partial = failed === 0 && notVerified.length > 0;
+        const notVerifiedNote = `NOT VERIFIED — ${notVerified.length} agent test(s) could not be evaluated: ${notVerified
+            .slice(0, 5)
+            .map((r) => r.id)
+            .join(', ')}${notVerified.length > 5 ? ` (+${notVerified.length - 5} more)` : ''}`;
         gates.push({
             id: 'agent-tests',
             label: 'Agent contract tests',
@@ -150,15 +198,29 @@ export async function buildQualityReport(input) {
             blocking: config.requireAgentTests === true || strict,
             runsShell: false,
             executed: true,
-            notes: failed > 0 ? [`${failed}/${results.length} agent tests failed`] : [],
-            data: { total: results.length, failed },
+            notes: [
+                ...(failed > 0 ? [`${failed}/${results.length} agent tests failed`] : []),
+                ...(notVerified.length > 0 ? [notVerifiedNote] : []),
+            ],
+            // Zero agent tests examined nothing — see the context-tests note above.
+            data: {
+                total: results.length,
+                failed,
+                notVerified: notVerified.length,
+                examinedNothing: results.length === 0,
+                ...(partial ? { partial: true, shortfalls: [notVerifiedNote] } : {}),
+            },
         });
     }
     catch (e) {
         gates.push({
             id: 'agent-tests',
             label: 'Agent contract tests',
-            passed: true,
+            // A gate that threw proved NOTHING. `passed: true` here would fold an
+            // unmeasured verdict into the green count and the score — the exact
+            // silent-green the loud-skip contract exists to prevent. `executed:
+            // false` marks it unmeasured; the score below excludes it either way.
+            passed: false,
             blocking: false,
             runsShell: false,
             executed: false,
@@ -166,10 +228,20 @@ export async function buildQualityReport(input) {
         });
     }
     // 8. Packs doctor. Signature verification reads files but does not exec.
+    // Settled by THE pack-doctor verdict (`packDoctorVerdict`, the one `shrk
+    // packs doctor` exits on): ZERO packs examined nothing — a deliberate skip
+    // when the gate is optional, NOT verified when required — and a compiled
+    // build never compared to its source is PARTIAL. Never `passed` over either.
     try {
-        const report = buildPackDoctorReport(inspection, {
+        // THE async doctor `shrk packs doctor` runs: registry-backed rejections
+        // included, so this row cannot pass a pack the verb fails (R12-X2).
+        const report = await buildPackDoctorReportAsync(inspection, {
             requireSignatures: config.requirePackSignatures === true,
         });
+        const verdict = packDoctorVerdict(report, inspection);
+        const compiledShortfall = report.compiledArtifactCoverage
+            ? coverageShortfall(report.compiledArtifactCoverage)
+            : undefined;
         gates.push({
             id: 'packs',
             label: 'Packs doctor',
@@ -177,13 +249,20 @@ export async function buildQualityReport(input) {
             blocking: config.requirePackSignatures === true || strict,
             runsShell: false,
             executed: true,
-            notes: report.issues
-                .filter((i) => i.severity === 'error')
-                .slice(0, 5)
-                .map((i) => `${i.packageName}: ${i.message}`),
+            notes: [
+                ...report.issues
+                    .filter((i) => i.severity === 'error')
+                    .slice(0, 5)
+                    .map((i) => `${i.packageName}: ${i.message}`),
+                ...(verdict.examinedNothing ? ['0 packs discovered — nothing to examine'] : []),
+                ...(compiledShortfall ? [`NOT VERIFIED — ${compiledShortfall}`] : []),
+            ],
             data: {
                 errors: report.summary.errors,
                 warnings: report.summary.warnings,
+                packsDiscovered: verdict.packsDiscovered,
+                ...(verdict.examinedNothing ? { examinedNothing: true } : {}),
+                ...(compiledShortfall !== undefined && report.passed ? { partial: true, shortfalls: [compiledShortfall] } : {}),
             },
         });
     }
@@ -191,13 +270,101 @@ export async function buildQualityReport(input) {
         gates.push({
             id: 'packs',
             label: 'Packs doctor',
-            passed: true,
+            // A gate that threw proved NOTHING. `passed: true` here would fold an
+            // unmeasured verdict into the green count and the score — the exact
+            // silent-green the loud-skip contract exists to prevent. `executed:
+            // false` marks it unmeasured; the score below excludes it either way.
+            passed: false,
             blocking: false,
             runsShell: false,
             executed: false,
             notes: [`could not run pack doctor: ${e.message}`],
         });
     }
+    // 9. Declared cross-references (round 11, 4.2) — the collector the
+    // self-config doctor reads, so the bundle and the verb cannot disagree. A
+    // dangling id is a warning (non-blocking unless --strict); a dangling
+    // `supersededBy`, a supersession cycle or an unknown facet kind blocks. An id
+    // that could not be looked up is an unexamined unit: with no blocking error
+    // the gate is PARTIAL (never a pass), and `data.coverage` carries the record.
+    try {
+        const xrefs = await buildDeclaredXrefReport(inspection);
+        const coverage = declaredXrefCoverage(xrefs);
+        const c = xrefs.counts;
+        const nothing = c.ids === 0 && xrefs.issues.length === 0 && xrefs.examined.unreadSources.length === 0;
+        const shortfall = nothing ? undefined : coverageShortfall(coverage);
+        gates.push({
+            id: 'cross-references',
+            label: 'Declared cross-references',
+            passed: c.errors === 0 && ((c.warnings === 0) || shortfall !== undefined),
+            blocking: c.errors > 0 || (strict && !nothing),
+            runsShell: false,
+            executed: true,
+            notes: [
+                declaredXrefSummaryLine(xrefs),
+                ...xrefs.rows
+                    .filter(isBrokenXref)
+                    .slice(0, 5)
+                    .map((r) => `${r.severity}: ${r.message}${r.file ? ` (${r.file})` : ''}`),
+                ...xrefs.issues.slice(0, 3).map((i) => `${i.severity}: ${i.message}`),
+                ...(shortfall ? [`NOT VERIFIED — ${shortfall}`] : []),
+            ],
+            data: {
+                ids: c.ids,
+                dangling: c.dangling,
+                wrongKind: c.wrongKind,
+                unverified: c.unverified,
+                errors: c.errors,
+                warnings: c.warnings,
+                coverage,
+                ...(nothing ? { examinedNothing: true } : {}),
+                ...(shortfall !== undefined && c.errors === 0 ? { partial: true } : {}),
+            },
+        });
+    }
+    catch (e) {
+        gates.push({
+            id: 'cross-references',
+            label: 'Declared cross-references',
+            // Could not run → proved nothing; never folded into a pass.
+            passed: false,
+            blocking: false,
+            runsShell: false,
+            executed: false,
+            notes: [`could not collect declared cross-references: ${e.message}`],
+        });
+    }
+    // 10. The knowledge stale-check — THE gate `shrk knowledge stale-check` and
+    // `shrk quality` settle (`knowledgeStaleQualityGate`), so this report and
+    // the CLI bundle cannot disagree about the corpus (round 11 review: it was
+    // CLI-only, and MCP read `pass` over a stale corpus `shrk quality` failed).
+    gates.push(await knowledgeStaleQualityGate(inspection, input.changedFiles));
+    // 11. The seven data-defined gate planes. `shrk quality` runs them itself;
+    // every other consumer does not (some spawn shells), so a config that
+    // declares plane rules gets a NOT-RUN row — the report is `not-verified`,
+    // never a `pass` over rules nobody evaluated.
+    if (input.callerRunsGatePlanes !== true) {
+        const planes = await declaredGatePlaneRules(inspection.projectRoot);
+        if (planes.total > 0 || planes.loadError !== undefined) {
+            const breakdown = Object.entries(planes.byPlane)
+                .map(([plane, n]) => `${plane} ${n}`)
+                .join(', ');
+            gates.push({
+                id: 'gate-planes',
+                label: 'Data-defined gate planes',
+                passed: false,
+                blocking: false,
+                runsShell: false,
+                executed: false,
+                notes: [
+                    planes.loadError !== undefined
+                        ? `could not resolve the config (${planes.loadError}), so the data-defined planes were not evaluated — run \`shrk gates check\``
+                        : `${planes.total} plane rule(s) declared (${breakdown}) — not evaluated by this report; run \`shrk gates check\` (or \`shrk quality\`)`,
+                ],
+                data: { rules: planes.total, byPlane: planes.byPlane },
+            });
+        }
+    }
     // If `skipShell` were true and any gate listed runsShell=true, we'd record
     // it as skipped here. Today every gate is pure inspection — no shell. The
     // flag is kept so MCP callers can pre-declare the intent and future gates
@@ -221,7 +388,13 @@ export async function buildQualityReport(input) {
     const executed = gates.filter((g) => g.executed).length;
     const passCount = gates.filter((g) => g.passed).length;
     const score = executed > 0 ? Math.round((passCount / executed) * 100) : 100;
-    const overall = blockers > 0 ? 'fail' : warnings > 0 ? 'warn' : 'pass';
+    // Settled through core's coverage rule, like every CLI verdict: a blocking
+    // failure is `fail`; otherwise a gate that could not run, examined nothing
+    // while required, or examined only part of its scope makes the report
+    // `not-verified` — never `pass` (or `warn`) over it.
+    const coverage = qualityReportCoverage(gates);
+    const shortfall = coverageShortfall(coverage);
+    const overall = blockers > 0 ? 'fail' : shortfall !== undefined ? 'not-verified' : warnings > 0 ? 'warn' : 'pass';
     const nextRecommendations = buildRecommendations(gates);
     const report = {
         overall,
@@ -230,6 +403,8 @@ export async function buildQualityReport(input) {
         score,
         gates,
         nextRecommendations,
+        coverage,
+        shortfalls: shortfall !== undefined ? [shortfall] : [],
     };
     if (drift)
         report.drift = drift;
@@ -237,21 +412,58 @@ export async function buildQualityReport(input) {
 }
 function checkBoundaries(inspection) {
     const rules = inspection.boundaryRegistry.list();
-    if (rules.length === 0) {
-        return { errors: 0, warnings: 0, notes: ['no boundary rules configured'] };
+    const loadIssues = inspection.boundaryLoadIssues ?? [];
+    if (rules.length === 0 && loadIssues.length === 0) {
+        // Zero errors over ZERO rules is not a clean boundary check — it examined
+        // nothing. Flagged so the CLI aggregate reports it as a skip, not a pass;
+        // the notes say WHY (e.g. a boundaries.ts that is not listed).
+        return {
+            errors: 0,
+            warnings: 0,
+            notes: ['no boundary rules configured', ...describeBoundaryConfiguration(inspection).diagnostics],
+            examinedNothing: true,
+        };
     }
     try {
-        const scan = scanImports({ projectRoot: inspection.projectRoot });
-        const tsconfigPaths = loadTsconfigPaths(inspection.projectRoot);
-        const evalResult = evaluateBoundaries(scan, rules, {
-            ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
-        });
+        const r = runBoundaryCheck(inspection);
+        // An errored rule, a stale exception and a failOnEmpty skip fail the gate
+        // exactly as they fail `check boundaries`.
+        const errors = r.counts.error +
+            r.loadIssues.length +
+            r.staleExceptions.length +
+            r.rules.filter((x) => x.failedOnEmpty === true).length;
+        const partial = errors === 0 && r.exitCode === 2;
         return {
-            errors: evalResult.counts.error,
-            warnings: evalResult.counts.warning,
-            notes: evalResult.violations
-                .slice(0, 5)
-                .map((v) => `${v.severity}: ${v.file}:${v.line} → ${v.importSpecifier}`),
+            errors,
+            warnings: r.counts.warning,
+            notes: [
+                ...r.violations.slice(0, 5).map((v) => `${v.severity}: ${v.file}:${v.line} → ${v.importSpecifier}`),
+                ...r.loadIssues.map((i) => `error: ${boundaryLoadIssueLabel(i)} (${i.file}) — ${i.kind}: ${i.issues.join('; ')} — NOT evaluated`),
+                ...r.staleExceptions.map((s) => `error: ${s.file} — ${s.message}`),
+                ...(partial ? [`NOT VERIFIED — ${r.shortfalls.slice(0, 3).join('; ')}`] : []),
+                // Round 13 (lane B): dead selector units and went-live expectEmpty
+                // markers are ADVISORY here — listed, never an error: `check
+                // boundaries --fail-on-dead-units` is where they fail. Quality used to
+                // report `passed` with no note while `check boundaries` withheld its ✓.
+                ...r.deadUnits.slice(0, 5).map((d) => `advisory: dead selector unit [${d.unit}] ${d.ruleId}: ${d.selector} — ${d.reason}`),
+                ...(r.deadUnits.length > 5
+                    ? [`advisory: ${r.deadUnits.length - 5} more dead selector unit(s) — \`shrk check boundaries\` lists them`]
+                    : []),
+                // A PACK marker that went live is INFO (round 13 review), as `check
+                // boundaries` prints it in its own block — never counted as advisory.
+                ...r.wentLive
+                    .slice(0, 5)
+                    .map((u) => `${u.packageName !== undefined ? 'info' : 'advisory'}: [${u.unit}] ${u.ruleId}: ${u.selector} — ${u.reason}`),
+                ...(r.wentLive.length > 5
+                    ? [`advisory: ${r.wentLive.length - 5} more went-live expectEmpty marker(s) — \`shrk check boundaries\` lists them`]
+                    : []),
+                // …and every intended-empty unit the run ACCEPTED is printed, never
+                // silent (round 13 review) — the orchestrator's settled acceptance
+                // lines (present only at exit 0), worded as the gate planes' coverage
+                // item prints theirs.
+                ...r.accepted.map((a) => `accepted: ${a}`),
+            ],
+            ...(partial ? { partial: true, shortfalls: [...r.shortfalls] } : {}),
         };
     }
     catch (e) {
@@ -261,7 +473,14 @@ function checkBoundaries(inspection) {
 function buildRecommendations(gates) {
     const out = [];
     for (const g of gates) {
-        if (g.passed)
+        if (g.id === 'agent-tests' && g.passed && g.data?.['partial'] === true) {
+            // Not a failure, not a pass: an expectation the runner could not evaluate.
+            out.push('Run `shrk test agent` from the CLI — it injects the command index, so every `expectedCommands` entry is evaluated.');
+            continue;
+        }
+        // A gate that passed over PART of its scope still gets its repro: the
+        // report is not-verified because of it.
+        if (g.passed && g.data?.['partial'] !== true)
             continue;
         switch (g.id) {
             case 'doctor':
@@ -288,6 +507,15 @@ function buildRecommendations(gates) {
             case 'packs':
                 out.push('Run `shrk packs doctor --require-signatures` to inspect pack issues.');
                 break;
+            case 'cross-references':
+                out.push('Run `shrk self-config xrefs --dangling-only` to list dangling cross-reference ids (`shrk self-config resolve <id>` explains one).');
+                break;
+            case 'knowledge-stale':
+                out.push('Run `shrk knowledge stale-check` to see the stale, missing and unverifiable knowledge references.');
+                break;
+            case 'gate-planes':
+                out.push('Run `shrk gates check` (or `shrk quality`) to evaluate the data-defined gate planes this report did not run.');
+                break;
             default:
                 break;
         }

package/dist/query-intent-kind.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The shape of work a free-text query asks for — THE intent vocabulary
+ * `classifyQueryIntent` answers in. The recommender gates source-writing
+ * scaffolds on `Create`, pins grounding on `Plan`, and change-intent /
+ * prepare-agent-task consult it instead of their own verb regexes.
+ */
+export declare enum QueryIntent {
+    Create = "create",
+    Diagnose = "diagnose",
+    Repair = "repair",
+    Refactor = "refactor",
+    Review = "review",
+    Plan = "plan",
+    Explain = "explain",
+    Release = "release",
+    Unknown = "unknown"
+}
+//# sourceMappingURL=query-intent-kind.d.ts.map

package/dist/query-intent-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-intent-kind.d.ts","sourceRoot":"","sources":["../src/query-intent-kind.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,WAAW;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,OAAO,YAAY;CACpB"}

package/dist/query-intent-kind.js

@@ -0,0 +1,18 @@
+/**
+ * The shape of work a free-text query asks for — THE intent vocabulary
+ * `classifyQueryIntent` answers in. The recommender gates source-writing
+ * scaffolds on `Create`, pins grounding on `Plan`, and change-intent /
+ * prepare-agent-task consult it instead of their own verb regexes.
+ */
+export var QueryIntent;
+(function (QueryIntent) {
+    QueryIntent["Create"] = "create";
+    QueryIntent["Diagnose"] = "diagnose";
+    QueryIntent["Repair"] = "repair";
+    QueryIntent["Refactor"] = "refactor";
+    QueryIntent["Review"] = "review";
+    QueryIntent["Plan"] = "plan";
+    QueryIntent["Explain"] = "explain";
+    QueryIntent["Release"] = "release";
+    QueryIntent["Unknown"] = "unknown";
+})(QueryIntent || (QueryIntent = {}));

package/dist/query-intent-result.d.ts

@@ -0,0 +1,23 @@
+import type { QueryIntent } from './query-intent-kind.js';
+/** `classifyQueryIntent`'s answer. */
+export interface IQueryIntentResult {
+    /** The primary intent. */
+    readonly intent: QueryIntent;
+    /**
+     * The create verb that makes this a create/build query, when one does —
+     * set even when a planning verb earlier in the query makes the primary
+     * intent `Plan` ("plan to add …").
+     */
+    readonly createVerb?: string;
+    /** A planning verb in the first four terms ("help me plan …"), when present. */
+    readonly planVerb?: string;
+    /**
+     * A create word that was found but does NOT make this a create query,
+     * because a repair/diagnosis marker is present ("fix the broken BUILD",
+     * "why does the NEW route fail") — names the marker.
+     */
+    readonly vetoedBy?: string;
+    /** The normalised terms the decision was made over. */
+    readonly terms: readonly string[];
+}
+//# sourceMappingURL=query-intent-result.d.ts.map

package/dist/query-intent-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-intent-result.d.ts","sourceRoot":"","sources":["../src/query-intent-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC"}

package/dist/query-intent-result.js

@@ -0,0 +1 @@
+export {};

package/dist/query-intent.d.ts

@@ -0,0 +1,18 @@
+import type { IQueryIntentResult } from './query-intent-result.js';
+/**
+ * THE eligibility rule for SOURCE-WRITING offers — a scaffold, a `gen` /
+ * `apply` command, a suggested generation: only a create/build query admits
+ * them. The recommender gates its writes-source candidates on it and the task
+ * packet gates its suggested generation on it, so the two cannot disagree
+ * about one query (spec 2.3, round 11 review R11-GAP-6).
+ */
+export declare function intentAdmitsSourceWrites(intent: IQueryIntentResult): boolean;
+/**
+ * A diagnose / repair query ("fix the broken build", "why does the new route
+ * fail"): a create/scaffold pipeline, a template, or a source-writing command
+ * is never an answer to it — the task packet drops them.
+ */
+export declare function intentIsRepairOrDiagnosis(intent: IQueryIntentResult): boolean;
+/** Classify a free-text query. Pure and deterministic. */
+export declare function classifyQueryIntent(query: string): IQueryIntentResult;
+//# sourceMappingURL=query-intent.d.ts.map

package/dist/query-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-intent.d.ts","sourceRoot":"","sources":["../src/query-intent.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AA+QnE;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAE7E;AAED,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAoCrE"}