@shrkcrft/quality-gates 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/gates/arch-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arch-gate.d.ts","sourceRoot":"","sources":["../../src/gates/arch-gate.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,WAAW,CAyKzF"}
+{"version":3,"file":"arch-gate.d.ts","sourceRoot":"","sources":["../../src/gates/arch-gate.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,WAAW,CAyKzF"}

package/dist/gates/arch-gate.js

@@ -1,4 +1,4 @@
-import { ArchReportStore, diffSnapshots, runArchCheck, snapshotFromReport, violationId, } from '@shrkcrft/architecture-guard';
+import { ArchReportStore, archStoreMissing, diffSnapshots, runArchCheck, snapshotFromReport, violationId, } from '@shrkcrft/architecture-guard';
 /**
  * Architecture-guard gate.
  *
@@ -21,7 +21,7 @@ import { ArchReportStore, diffSnapshots, runArchCheck, snapshotFromReport, viola
 export function archGate(projectRoot, options = {}) {
     const start = Date.now();
     const report = runArchCheck({ projectRoot });
-    if (report.diagnostics.some((d) => d.includes('code-graph store missing'))) {
+    if (archStoreMissing(report)) {
         return {
             id: 'arch',
             label: 'Architecture',

package/dist/gates/graph-fresh-gate.d.ts

@@ -1,8 +1,18 @@
+import { type IGraphFreshness } from '@shrkcrft/graph';
 import type { IGateResult } from '../schema/quality-gate.js';
 /**
- * Check whether the code-graph store exists AND the manifest digest
- * matches the on-disk JSONL fingerprints. Catches: missing index;
- * tampered / partial store; schema mismatch.
+ * Check whether the code-graph store exists, its manifest digest matches the
+ * on-disk JSONL fingerprints, AND it is current with the working tree.
+ * Catches: missing index; tampered / partial store; schema mismatch; an index
+ * behind the working tree.
+ *
+ * Digest-valid is not current (round 11 review R11-GAP-2): a store can be
+ * intact yet stale. Freshness is decided by THE authority —
+ * `detectGraphFreshness`, the one `graph status`, doctor, code-intel and MCP
+ * read (the runner passes the measurement it already made) — so this gate can
+ * never call "fresh" an index `graph status` calls stale. A stale index is a
+ * `warn` carrying the shared coverage record, which settles `shrk gate` and MCP
+ * `get_quality_gate` to NOT VERIFIED (2).
  */
-export declare function graphFreshGate(projectRoot: string): IGateResult;
+export declare function graphFreshGate(projectRoot: string, freshness?: IGraphFreshness): IGateResult;
 //# sourceMappingURL=graph-fresh-gate.d.ts.map

package/dist/gates/graph-fresh-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-fresh-gate.d.ts","sourceRoot":"","sources":["../../src/gates/graph-fresh-gate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAgC/D"}
+{"version":3,"file":"graph-fresh-gate.d.ts","sourceRoot":"","sources":["../../src/gates/graph-fresh-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,eAAe,GAAG,WAAW,CAsD5F"}

package/dist/gates/graph-fresh-gate.js

@@ -1,10 +1,19 @@
-import { GraphStore } from '@shrkcrft/graph';
+import { detectGraphFreshness, GraphStore, graphFreshnessBehind, graphFreshnessCoverage, graphFreshnessRemedy, } from '@shrkcrft/graph';
 /**
- * Check whether the code-graph store exists AND the manifest digest
- * matches the on-disk JSONL fingerprints. Catches: missing index;
- * tampered / partial store; schema mismatch.
+ * Check whether the code-graph store exists, its manifest digest matches the
+ * on-disk JSONL fingerprints, AND it is current with the working tree.
+ * Catches: missing index; tampered / partial store; schema mismatch; an index
+ * behind the working tree.
+ *
+ * Digest-valid is not current (round 11 review R11-GAP-2): a store can be
+ * intact yet stale. Freshness is decided by THE authority —
+ * `detectGraphFreshness`, the one `graph status`, doctor, code-intel and MCP
+ * read (the runner passes the measurement it already made) — so this gate can
+ * never call "fresh" an index `graph status` calls stale. A stale index is a
+ * `warn` carrying the shared coverage record, which settles `shrk gate` and MCP
+ * `get_quality_gate` to NOT VERIFIED (2).
  */
-export function graphFreshGate(projectRoot) {
+export function graphFreshGate(projectRoot, freshness) {
     const start = Date.now();
     const store = new GraphStore(projectRoot);
     if (!store.exists()) {
@@ -29,6 +38,28 @@ export function graphFreshGate(projectRoot) {
             durationMs: Date.now() - start,
         };
     }
+    const fresh = freshness ?? detectGraphFreshness(projectRoot);
+    const coverage = graphFreshnessCoverage(fresh, 'graph-fresh');
+    if (coverage) {
+        return {
+            id: 'graph-fresh',
+            label: 'Code graph indexed',
+            status: 'warn',
+            message: fresh.hasIndex
+                ? `Code-graph index is stale — ${fresh.modified.length} modified, ${fresh.added.length} new, ${fresh.deleted.length} deleted, ${fresh.packagesChanged.length} package(s) changed since it was built (NOT VERIFIED).`
+                : 'Code-graph index freshness could not be measured against the working tree (NOT VERIFIED).',
+            details: {
+                behind: graphFreshnessBehind(fresh),
+                modified: fresh.modified.length,
+                added: fresh.added.length,
+                deleted: fresh.deleted.length,
+                packagesChanged: fresh.packagesChanged,
+            },
+            coverage: [coverage],
+            nextCommands: [graphFreshnessRemedy(fresh)],
+            durationMs: Date.now() - start,
+        };
+    }
     return {
         id: 'graph-fresh',
         label: 'Code graph indexed',

package/dist/gates/knowledge-symbol-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-symbol-gate.d.ts","sourceRoot":"","sources":["../../src/gates/knowledge-symbol-gate.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAK7D,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,6EAA6E;IAC7E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,2BAAgC,GACxC,WAAW,CA0Eb"}
+{"version":3,"file":"knowledge-symbol-gate.d.ts","sourceRoot":"","sources":["../../src/gates/knowledge-symbol-gate.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAK7D,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,6EAA6E;IAC7E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,2BAAgC,GACxC,WAAW,CAmHb"}

package/dist/gates/knowledge-symbol-gate.js

@@ -1,5 +1,6 @@
+import { coverageShortfall } from '@shrkcrft/core';
 import { loadGraphApiCached } from '@shrkcrft/graph';
-import { buildKnowledgeStaleReport, ReferenceCheckOutcome, } from '@shrkcrft/inspector';
+import { buildKnowledgeStaleReport, declaredReferenceCoverage, ReferenceCheckOutcome, } from '@shrkcrft/inspector';
 /** Reference kinds this gate is responsible for (symbol-ref integrity). */
 const SCOPED_REF_KINDS = new Set(['symbol', 'file']);
 /**
@@ -50,13 +51,51 @@ export function knowledgeSymbolGate(projectRoot, options = {}) {
         };
     }
     const broken = scoped.filter((c) => c.outcome === ReferenceCheckOutcome.Stale || c.outcome === ReferenceCheckOutcome.Missing);
+    // THE declared-reference fold (`declaredReferenceCoverage`) — the one the
+    // stale-check's own verdict settles on — restricted to this gate's kinds.
+    // Only a CHECKED reference counts as examined: an `unknown` one (unpinned,
+    // ambiguous, a file that failed to read) is neither resolving nor broken,
+    // and a malformed one was never checked. This gate used to count both as
+    // "resolve" and PASS where `shrk knowledge stale-check` exits 2.
+    const refCoverage = { ...declaredReferenceCoverage({ references: scoped }), subject: 'knowledge-symbol' };
+    const gateCoverage = [refCoverage];
+    const ok = scoped.filter((c) => c.outcome === ReferenceCheckOutcome.Ok).length;
+    const unknown = scoped.filter((c) => c.outcome === ReferenceCheckOutcome.Unknown).length;
+    const invalid = scoped.filter((c) => c.outcome === ReferenceCheckOutcome.Invalid).length;
+    const tally = `${ok} of ${evaluated} symbol/file reference(s) resolve` +
+        (unknown > 0 ? `; ${unknown} could not be verified (unpinned, ambiguous or unreadable)` : '') +
+        (invalid > 0 ? `; ${invalid} malformed` : '');
+    // This gate is scoped to symbol/file references, so its pass says nothing
+    // about entries that declare none — name them instead of letting "N resolve"
+    // read as "the corpus is healthy". (`shrk knowledge stale-check` gates them.)
+    const coverage = report.coverage;
+    const unverifiableNote = coverage.unverifiable > 0
+        ? `; ${coverage.unverifiable} of ${coverage.entriesInScope} entries unverifiable (no checkable reference — see \`shrk knowledge stale-check\`)`
+        : '';
     if (broken.length === 0) {
+        const shortfall = coverageShortfall(refCoverage);
+        if (shortfall !== undefined) {
+            // Nothing broken among what was checked, but not everything asked for
+            // was checked: NOT VERIFIED — `shrk gate` settles it to 2 through the
+            // coverage below, as `knowledge stale-check` does.
+            return {
+                id: 'knowledge-symbol',
+                label: 'Knowledge symbol refs',
+                status: 'warn',
+                message: `NOT VERIFIED — ${shortfall}. ${tally}${unverifiableNote}. This is not a pass.`,
+                details: { evaluated, ok, unknown, invalid, graphResolved: Boolean(graph), coverage, shortfalls: [shortfall] },
+                coverage: gateCoverage,
+                nextCommands: ['shrk knowledge stale-check'],
+                durationMs: Date.now() - start,
+            };
+        }
         return {
             id: 'knowledge-symbol',
             label: 'Knowledge symbol refs',
             status: 'pass',
-            message: `${evaluated} symbol/file reference(s) resolve.`,
-            details: { evaluated, graphResolved: Boolean(graph) },
+            message: `${tally}${unverifiableNote}.`,
+            details: { evaluated, ok, unknown, invalid, graphResolved: Boolean(graph), coverage },
+            coverage: gateCoverage,
             durationMs: Date.now() - start,
         };
     }
@@ -73,7 +112,8 @@ export function knowledgeSymbolGate(projectRoot, options = {}) {
         label: 'Knowledge symbol refs',
         status: failOnStale ? 'fail' : 'warn',
         message: `${broken.length}/${evaluated} symbol/file reference(s) stale or missing (moved/renamed).`,
-        details: { evaluated, broken: broken.length, samples, graphResolved: Boolean(graph) },
+        details: { evaluated, broken: broken.length, ok, unknown, invalid, samples, graphResolved: Boolean(graph) },
+        coverage: gateCoverage,
         nextCommands: ['shrk knowledge audit', 'shrk doctor'],
         durationMs: Date.now() - start,
     };

package/dist/gates/policy-lint-gate.d.ts

@@ -1,4 +1,4 @@
-import type { IPolicyRule } from '@shrkcrft/core';
+import { type IPolicyRule } from '@shrkcrft/core';
 import type { IGateResult } from '../schema/quality-gate.js';
 export interface IPolicyLintGateOptions {
     /** The project's policy rules (from `sharkcraft.config.ts` `policyRules[]`). */
@@ -13,6 +13,12 @@ export interface IPolicyLintGateOptions {
      * disable the policy plane.
      */
     configError?: string;
+    /**
+     * Project-relative directories the walk prunes: THE plane scan scope
+     * (`planeScanExcludeDirs`), the one `policy-lint` uses. The caller passes it
+     * so this gate and the verb examine the same files for the same rule.
+     */
+    excludeDirs?: readonly string[];
 }
 /**
  * The "policy plane" gate: runs the project's data-defined policy-lint rules

package/dist/gates/policy-lint-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-lint-gate.d.ts","sourceRoot":"","sources":["../../src/gates/policy-lint-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,yFAAyF;IACzF,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,WAAW,CA2ErG"}
+{"version":3,"file":"policy-lint-gate.d.ts","sourceRoot":"","sources":["../../src/gates/policy-lint-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,yFAAyF;IACzF,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,WAAW,CA4IrG"}

package/dist/gates/policy-lint-gate.js

@@ -1,3 +1,4 @@
+import { coverageShortfall } from '@shrkcrft/core';
 import { runPolicyLint } from '@shrkcrft/boundaries';
 /**
  * The "policy plane" gate: runs the project's data-defined policy-lint rules
@@ -14,6 +15,16 @@ export function policyLintGate(projectRoot, options = {}) {
             label: 'Policy lint',
             status: 'warn',
             message: `Config could not be loaded — policy rules not evaluated: ${options.configError}`,
+            // Nothing declared was examined — never a clean `shrk gate` exit.
+            coverage: [
+                {
+                    unit: 'config files',
+                    expected: 1,
+                    examined: 0,
+                    subject: 'policy',
+                    reason: 'failed to load, so no policy rule was evaluated',
+                },
+            ],
             nextCommands: ['shrk doctor'],
             durationMs: Date.now() - start,
         };
@@ -30,12 +41,14 @@ export function policyLintGate(projectRoot, options = {}) {
     }
     const report = runPolicyLint(projectRoot, rules, {
         ...(options.changedOnly ? { changedOnly: true, changedFiles: options.changedFiles ?? [] } : {}),
+        ...(options.excludeDirs ? { excludeDirs: options.excludeDirs } : {}),
     });
-    // Loud zero case: rules exist but none actually scanned a file (their globs
-    // matched no files — e.g. a `style` rule in a project with no stylesheets — or
-    // `--changed-only` filtered them all out). Surface it as skipped rather than a
-    // silent green pass.
-    if (report.rules.length === 0 || report.evaluated === 0) {
+    // Nothing SELECTED: no rule has content in the run's scope (`--changed-only`
+    // left none — no rule's globs match content the change touched). That is
+    // deliberate narrowing, not a gap in any rule — skipped, loudly, never a
+    // pass. A rule that WAS selected but scanned nothing is not this case; it
+    // carries its coverage below.
+    if (report.rules.length === 0) {
         return {
             id: 'policy',
             label: 'Policy lint',
@@ -45,35 +58,86 @@ export function policyLintGate(projectRoot, options = {}) {
             durationMs: Date.now() - start,
         };
     }
+    // The engine's per-rule coverage (`IPolicyRuleResult.coverage`), owned by the
+    // rule id — the ONE record `policy-lint`, `gates check` and `quality` settle
+    // on. Carried on EVERY result below, so `shrk gate` settles its exit on the
+    // same records (settleVerdict): a rule that scanned nothing is not a pass
+    // here either, whether it sits next to a live rule or alone.
+    const coverage = report.rules.map((r) => ({ ...r.coverage, subject: r.coverage.subject ?? r.ruleId }));
+    const shortfalls = coverage.flatMap((c) => {
+        const s = coverageShortfall(c);
+        return s === undefined ? [] : [`${c.subject}: ${s}`];
+    });
+    const more = shortfalls.length > 1 ? ` (+${shortfalls.length - 1} more)` : '';
+    // A rule that matched nothing under `failOnEmpty` (the default at `error`
+    // severity) FAILED: `policy-lint` exits 1 on it, so this gate fails too.
+    const emptyFailed = report.skipped.filter((s) => s.failed).map((s) => s.ruleId);
+    const failedOnEmpty = emptyFailed.length > 0 ? { failedOnEmpty: emptyFailed } : {};
+    const failed = report.verdict === 'errors' || emptyFailed.length > 0;
     const errors = report.findings.filter((f) => f.severity === 'error').length;
     const warnings = report.findings.filter((f) => f.severity === 'warning').length;
     const samples = report.findings
         .slice(0, 8)
         .map((f) => `${f.ruleId}: ${f.match} (${f.file}:${f.line})`);
     const diagnostics = report.diagnostics;
+    // Rules were selected, but none scanned a content unit (their globs matched
+    // no files). The selected rule set proved nothing: `warn` + coverage (NOT
+    // VERIFIED — `shrk gate` settles it to 2), or `fail` when a failOnEmpty rule
+    // failed. Never `skipped`, which `shrk gate` would read as a clean 0.
+    if (report.evaluated === 0) {
+        return {
+            id: 'policy',
+            label: 'Policy lint',
+            status: failed ? 'fail' : 'warn',
+            message: failed
+                ? `FAILED — nothing evaluated: ${emptyFailed.length} rule(s) matched no content and fail on empty (${emptyFailed.join(', ')}). A rule that matches nothing is a bug in the rule.`
+                : `NOT VERIFIED — nothing evaluated: ${shortfalls[0] ?? 'no selected rule scanned a content unit'}${more}. This is not a pass.`,
+            details: { rules: report.rules.length, evaluated: 0, shortfalls, ...failedOnEmpty },
+            coverage,
+            nextCommands: ['shrk policy-lint'],
+            durationMs: Date.now() - start,
+        };
+    }
     if (report.verdict === 'pass') {
+        if (shortfalls.length > 0) {
+            return {
+                id: 'policy',
+                label: 'Policy lint',
+                status: 'warn',
+                message: `NOT VERIFIED — ${shortfalls[0]}${more}. No violations among what was scanned; this is not a pass.`,
+                details: { rules: report.rules.length, evaluated: report.evaluated, shortfalls },
+                coverage,
+                nextCommands: ['shrk policy-lint'],
+                durationMs: Date.now() - start,
+            };
+        }
         return {
             id: 'policy',
             label: 'Policy lint',
             status: 'pass',
             message: `${report.rules.length} policy rule(s) — no violations.`,
             details: { rules: report.rules.length, evaluated: report.evaluated },
+            coverage,
             durationMs: Date.now() - start,
         };
     }
     const misconfig = diagnostics.length > 0 ? `, ${diagnostics.length} misconfigured rule(s)` : '';
+    const empty = emptyFailed.length > 0 ? `, ${emptyFailed.length} rule(s) matched nothing (failOnEmpty: ${emptyFailed.join(', ')})` : '';
     return {
         id: 'policy',
         label: 'Policy lint',
-        status: report.verdict === 'errors' ? 'fail' : 'warn',
-        message: `${errors} error(s), ${warnings} warning(s)${misconfig}: policy violation(s).`,
+        status: failed ? 'fail' : 'warn',
+        message: `${errors} error(s), ${warnings} warning(s)${misconfig}${empty}: policy violation(s).`,
         details: {
             errors,
             warnings,
             samples,
             evaluated: report.evaluated,
             ...(diagnostics.length > 0 ? { diagnostics } : {}),
+            ...(shortfalls.length > 0 ? { shortfalls } : {}),
+            ...failedOnEmpty,
         },
+        coverage,
         nextCommands: ['shrk policy-lint'],
         durationMs: Date.now() - start,
     };

package/dist/gates/wiring-gate.d.ts

@@ -1,4 +1,4 @@
-import type { IWiringRule } from '@shrkcrft/core';
+import { type IWiringRule } from '@shrkcrft/core';
 import type { IGateResult } from '../schema/quality-gate.js';
 export interface IWiringGateOptions {
     /** The project's wiring rules (from `sharkcraft.config.ts` `wiringRules[]`). */
@@ -13,6 +13,12 @@ export interface IWiringGateOptions {
      * disable the wiring plane.
      */
     configError?: string;
+    /**
+     * Project-relative directories the walk prunes: THE plane scan scope
+     * (`planeScanExcludeDirs`), the one `check wiring` uses. The caller passes
+     * it so this gate and the verb examine the same files for the same rule.
+     */
+    excludeDirs?: readonly string[];
 }
 /**
  * The "completeness plane" gate: runs the project's data-defined wiring rules

package/dist/gates/wiring-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wiring-gate.d.ts","sourceRoot":"","sources":["../../src/gates/wiring-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAwE7F"}
+{"version":3,"file":"wiring-gate.d.ts","sourceRoot":"","sources":["../../src/gates/wiring-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,WAAW,CA+I7F"}

package/dist/gates/wiring-gate.js

@@ -1,3 +1,4 @@
+import { coverageShortfall } from '@shrkcrft/core';
 import { runWiring } from '@shrkcrft/boundaries';
 /**
  * The "completeness plane" gate: runs the project's data-defined wiring rules
@@ -12,6 +13,16 @@ export function wiringGate(projectRoot, options = {}) {
             label: 'Wiring (completeness)',
             status: 'warn',
             message: `Config could not be loaded — wiring rules not evaluated: ${options.configError}`,
+            // Nothing declared was examined — never a clean `shrk gate` exit.
+            coverage: [
+                {
+                    unit: 'config files',
+                    expected: 1,
+                    examined: 0,
+                    subject: 'wiring',
+                    reason: 'failed to load, so no wiring rule was evaluated',
+                },
+            ],
             nextCommands: ['shrk doctor'],
             durationMs: Date.now() - start,
         };
@@ -28,11 +39,13 @@ export function wiringGate(projectRoot, options = {}) {
     }
     const report = runWiring(projectRoot, rules, {
         ...(options.changedOnly ? { changedOnly: true, changedFiles: options.changedFiles ?? [] } : {}),
+        ...(options.excludeDirs ? { excludeDirs: options.excludeDirs } : {}),
     });
-    // Loud zero case: rules exist but none actually ran a comparison (their globs
-    // matched no files, or `--changed-only` filtered them all out). Surface it as
-    // skipped rather than a silent green pass.
-    if (report.rules.length === 0 || report.evaluated === 0) {
+    // Nothing SELECTED: `--changed-only` filtered every rule out (no rule's
+    // footprint intersects the changeset). That is deliberate narrowing, not a
+    // gap in any rule — skipped, loudly, never a pass. A rule that WAS selected
+    // but examined nothing is not this case; it carries its coverage below.
+    if (report.rules.length === 0) {
         return {
             id: 'wiring',
             label: 'Wiring (completeness)',
@@ -46,29 +59,86 @@ export function wiringGate(projectRoot, options = {}) {
     const warnings = report.violations.filter((v) => v.severity === 'warning').length;
     const samples = report.violations.slice(0, 8).map((v) => `${v.ruleId}: ${v.token} (${v.file}:${v.line})`);
     const diagnostics = report.diagnostics;
+    // Every rule's coverage shortfall, through core's one rule — the same set
+    // `check wiring` / `gates check` settle their exit on. A rule that passed
+    // over part of its scope (a subset rule whose declared selector never
+    // produced some registered tokens) or checked nothing is NOT a pass here
+    // either, so `shrk gate`, the MCP quality-gate tool and the dashboard cannot
+    // read green where `check wiring` reads not-verified.
+    // The engine's per-rule coverage, owned by the rule id — carried on the
+    // result so `shrk gate` settles its EXIT on the same records (settleVerdict),
+    // and the `shortfalls` detail below is a rendering of them, not a re-derivation.
+    const coverage = report.rules.map((r) => ({ ...r.coverage, subject: r.coverage.subject ?? r.ruleId }));
+    const shortfalls = coverage.flatMap((c) => {
+        const s = coverageShortfall(c);
+        return s === undefined ? [] : [`${c.subject}: ${s}`];
+    });
+    const more = shortfalls.length > 1 ? ` (+${shortfalls.length - 1} more)` : '';
+    // A rule that matched nothing under `failOnEmpty` carries no violation of its
+    // own — named next to the counts so a failing result says what failed.
+    const emptyFailed = report.skipped.filter((s) => s.failed).map((s) => s.ruleId);
+    const failedOnEmpty = emptyFailed.length > 0 ? { failedOnEmpty: emptyFailed } : {};
+    // Rules were SELECTED, but none ran a comparison (their source globs matched
+    // no files, or extracted no ids). The selected rule set proved nothing:
+    // `warn` + coverage (NOT VERIFIED — `shrk gate` settles it to 2), or `fail`
+    // when an error-severity failOnEmpty rule failed — exactly where `check
+    // wiring` exits 1. Never `skipped`, which `shrk gate` would read as a 0.
+    if (report.evaluated === 0) {
+        const failed = report.verdict === 'errors';
+        return {
+            id: 'wiring',
+            label: 'Wiring (completeness)',
+            status: failed ? 'fail' : 'warn',
+            message: failed
+                ? `FAILED — nothing evaluated: ${emptyFailed.length} rule(s) matched nothing and fail on empty (${emptyFailed.join(', ')}). A rule that matches nothing is a bug in the rule.`
+                : `NOT VERIFIED — nothing evaluated: ${shortfalls[0] ?? 'no selected rule ran a comparison'}${more}. This is not a pass.`,
+            details: { rules: report.rules.length, evaluated: 0, shortfalls, ...failedOnEmpty },
+            coverage,
+            nextCommands: ['shrk check wiring'],
+            durationMs: Date.now() - start,
+        };
+    }
     if (report.verdict === 'pass') {
+        if (shortfalls.length > 0) {
+            return {
+                id: 'wiring',
+                label: 'Wiring (completeness)',
+                status: 'warn',
+                message: `NOT VERIFIED — ${shortfalls[0]}${more}. No violations among what was examined; this is not a pass.`,
+                details: { rules: report.rules.length, evaluated: report.evaluated, shortfalls },
+                coverage,
+                nextCommands: ['shrk check wiring'],
+                durationMs: Date.now() - start,
+            };
+        }
         return {
             id: 'wiring',
             label: 'Wiring (completeness)',
             status: 'pass',
             message: `${report.rules.length} wiring rule(s) — every declared token is wired.`,
             details: { rules: report.rules.length, evaluated: report.evaluated },
+            // Carries any explicit acceptance (registeredExtras) so it is printed.
+            coverage,
             durationMs: Date.now() - start,
         };
     }
     const misconfig = diagnostics.length > 0 ? `, ${diagnostics.length} misconfigured rule(s)` : '';
+    const empty = emptyFailed.length > 0 ? `, ${emptyFailed.length} rule(s) matched nothing (failOnEmpty: ${emptyFailed.join(', ')})` : '';
     return {
         id: 'wiring',
         label: 'Wiring (completeness)',
         status: report.verdict === 'errors' ? 'fail' : 'warn',
-        message: `${errors} error(s), ${warnings} warning(s)${misconfig}: declared but not wired.`,
+        message: `${errors} error(s), ${warnings} warning(s)${misconfig}${empty}: declared but not wired.`,
         details: {
             errors,
             warnings,
             samples,
             evaluated: report.evaluated,
             ...(diagnostics.length > 0 ? { diagnostics } : {}),
+            ...(shortfalls.length > 0 ? { shortfalls } : {}),
+            ...failedOnEmpty,
         },
+        coverage,
         nextCommands: ['shrk check wiring'],
         durationMs: Date.now() - start,
     };

package/dist/index.d.ts

@@ -13,6 +13,9 @@ export * from './gates/wiring-gate.js';
 export * from './gates/policy-lint-gate.js';
 export * from './gates/knowledge-symbol-gate.js';
 export * from './runner/run-gates.js';
+export * from './runner/prepare-gate-run.js';
+export * from './schema/gate-run-request.js';
+export * from './schema/prepared-gate-run.js';
 export * from './runner/report-store.js';
 export * from './runner/render-markdown.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC"}

package/dist/index.js

@@ -13,5 +13,8 @@ export * from "./gates/wiring-gate.js";
 export * from "./gates/policy-lint-gate.js";
 export * from "./gates/knowledge-symbol-gate.js";
 export * from "./runner/run-gates.js";
+export * from "./runner/prepare-gate-run.js";
+export * from "./schema/gate-run-request.js";
+export * from "./schema/prepared-gate-run.js";
 export * from "./runner/report-store.js";
 export * from "./runner/render-markdown.js";

package/dist/runner/prepare-gate-run.d.ts

@@ -0,0 +1,34 @@
+import { type ISettledVerdict } from '@shrkcrft/core';
+import type { IGateRunRequest } from '../schema/gate-run-request.js';
+import type { IPreparedGateRun } from '../schema/prepared-gate-run.js';
+import type { GateStatus, IQualityGateReport } from '../schema/quality-gate.js';
+/**
+ * THE option assembly for a quality-gate run — `shrk gate` and MCP
+ * `get_quality_gate` both call it, so the two cannot run different gate sets.
+ *
+ * Round 11 review: the MCP tool passed only the impact options, so it never
+ * loaded the project's wiring / policy rules or the knowledge inspection —
+ * it said "No wiring rules configured" over a failing rule and returned
+ * `overall: pass` where `shrk gate` exited 1.
+ *
+ *   - wiring + policy rules come from `resolveProjectConfig` (pack
+ *     contributions included); an INVALID config is surfaced to both gates
+ *     (a `warn` with coverage), never a silent disable;
+ *   - both gates walk THE plane scan scope (`planeScanExcludeDirs`);
+ *   - `--changed-only` / `--staged` / `--files` / `--since` scope wiring,
+ *     policy and knowledge-symbol to the changeset and drive the impact gate;
+ *   - the architecture gate's NEW is always change-scoped (the worktree diff
+ *     vs HEAD when no scope is given);
+ *   - blast-radius risk is advisory unless `failOn` is given.
+ */
+export declare function prepareQualityGateRun(req: IGateRunRequest): Promise<IPreparedGateRun>;
+/** The PROPOSED exit from the overall status; the settle may veto a clean one. */
+export declare function qualityGateProposedExit(overall: GateStatus, strict: boolean): number;
+/**
+ * THE settlement of a quality-gate report: the proposed exit (from `overall`,
+ * `--strict` promoting a warn) vetoed by any gate coverage with a shortfall —
+ * core's `settleVerdict`, so a `warn` that says "this is not a pass" never
+ * settles to 0. `shrk gate` and MCP `get_quality_gate` both call it.
+ */
+export declare function settleQualityGateReport(report: IQualityGateReport, strict?: boolean): ISettledVerdict;
+//# sourceMappingURL=prepare-gate-run.d.ts.map

package/dist/runner/prepare-gate-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare-gate-run.d.ts","sourceRoot":"","sources":["../../src/runner/prepare-gate-run.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAOrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiF3F;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAIpF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,UAAQ,GAAG,eAAe,CAKnG"}

package/dist/runner/prepare-gate-run.js

@@ -0,0 +1,121 @@
+import { planeScanExcludeDirs } from '@shrkcrft/boundaries';
+import { settleVerdict } from '@shrkcrft/core';
+import { inspectSharkcraft, resolveChangedFiles, resolveProjectConfig, } from '@shrkcrft/inspector';
+/**
+ * THE option assembly for a quality-gate run — `shrk gate` and MCP
+ * `get_quality_gate` both call it, so the two cannot run different gate sets.
+ *
+ * Round 11 review: the MCP tool passed only the impact options, so it never
+ * loaded the project's wiring / policy rules or the knowledge inspection —
+ * it said "No wiring rules configured" over a failing rule and returned
+ * `overall: pass` where `shrk gate` exited 1.
+ *
+ *   - wiring + policy rules come from `resolveProjectConfig` (pack
+ *     contributions included); an INVALID config is surfaced to both gates
+ *     (a `warn` with coverage), never a silent disable;
+ *   - both gates walk THE plane scan scope (`planeScanExcludeDirs`);
+ *   - `--changed-only` / `--staged` / `--files` / `--since` scope wiring,
+ *     policy and knowledge-symbol to the changeset and drive the impact gate;
+ *   - the architecture gate's NEW is always change-scoped (the worktree diff
+ *     vs HEAD when no scope is given);
+ *   - blast-radius risk is advisory unless `failOn` is given.
+ */
+export async function prepareQualityGateRun(req) {
+    const cwd = req.cwd;
+    const files = req.files ?? [];
+    const wantChangedScope = req.changedOnly === true || req.staged === true || Boolean(req.sinceRef) || files.length > 0;
+    let changedFiles;
+    if (wantChangedScope) {
+        changedFiles = resolveChangedFiles({
+            projectRoot: cwd,
+            ...(files.length > 0 ? { files: [...files] } : {}),
+            ...(req.staged ? { staged: true } : {}),
+            ...(req.sinceRef ? { since: req.sinceRef } : {}),
+            ...(req.changedOnly && !req.staged && !req.sinceRef && files.length === 0 ? { includeWorktree: true } : {}),
+        }).files;
+    }
+    const loadedConfig = await resolveProjectConfig(cwd);
+    const wiringRules = loadedConfig.ok ? (loadedConfig.value.config.wiringRules ?? []) : [];
+    const policyRules = loadedConfig.ok ? (loadedConfig.value.config.policyRules ?? []) : [];
+    const configError = loadedConfig.ok ? undefined : loadedConfig.error.message;
+    const excludeDirs = loadedConfig.ok ? planeScanExcludeDirs(cwd, loadedConfig.value.sharkcraftDir) : undefined;
+    const scopeOpts = wantChangedScope ? { changedOnly: true, changedFiles: changedFiles ?? [] } : {};
+    // §3.1 — the architecture gate's "NEW" is ALWAYS change-scoped: a NEW error
+    // means one introduced by the working change (diff vs HEAD), never drift
+    // against a frozen (possibly months-old) baseline in a file the change never
+    // touched. `archAll` (baselineRelative:false) ignores this and fails on total
+    // errors, keeping a clean-tree CI demand expressible.
+    const archChangedFiles = wantChangedScope
+        ? (changedFiles ?? [])
+        : resolveChangedFiles({ projectRoot: cwd, includeWorktree: true }).files;
+    // Knowledge symbol-ref integrity needs the loaded knowledge entries. A
+    // caller that already has an inspection (MCP) passes it; otherwise one is
+    // built — best-effort: a failed inspection skips the gate, never fails it.
+    let inspection = req.inspection;
+    if (!inspection && !req.disable?.includes('knowledge-symbol')) {
+        try {
+            inspection = await inspectSharkcraft({ cwd });
+        }
+        catch {
+            inspection = undefined;
+        }
+    }
+    return {
+        options: {
+            projectRoot: cwd,
+            arch: {
+                ...(req.archAll ? { baselineRelative: false } : {}),
+                changedFiles: archChangedFiles,
+            },
+            wiring: {
+                ...(configError ? { configError } : wiringRules.length > 0 ? { rules: wiringRules } : {}),
+                ...scopeOpts,
+                ...(excludeDirs ? { excludeDirs } : {}),
+            },
+            policy: {
+                ...(configError ? { configError } : policyRules.length > 0 ? { rules: policyRules } : {}),
+                ...scopeOpts,
+                ...(excludeDirs ? { excludeDirs } : {}),
+            },
+            ...(inspection
+                ? {
+                    knowledgeSymbol: {
+                        inspection,
+                        ...(wantChangedScope ? { changedFiles: changedFiles ?? [] } : {}),
+                    },
+                }
+                : {}),
+            impact: {
+                ...(req.sinceRef ? { sinceRef: req.sinceRef } : {}),
+                // Blast-radius risk is PRE-EXISTING structure, so the composite gate
+                // treats it as advisory by default — `failOn: []` warns instead of
+                // redding. `failOn: ['critical']` opts into a hard fail.
+                failOn: req.failOn ?? [],
+                // With `--since` the gitref diff drives it; with `--changed-only` /
+                // `--staged` / `--files` the resolved changed-file set does.
+                ...(wantChangedScope && !req.sinceRef ? { files: changedFiles ?? [] } : {}),
+            },
+            ...(req.apiDiff ? { apiDiff: req.apiDiff } : {}),
+            ...(req.disable ? { disable: req.disable } : {}),
+        },
+        planeDiagnostics: loadedConfig.ok ? loadedConfig.value.planeDiagnostics : [],
+        ...(changedFiles ? { changedFiles } : {}),
+    };
+}
+/** The PROPOSED exit from the overall status; the settle may veto a clean one. */
+export function qualityGateProposedExit(overall, strict) {
+    if (overall === 'fail')
+        return 1;
+    if (overall === 'warn' && strict)
+        return 1;
+    return 0;
+}
+/**
+ * THE settlement of a quality-gate report: the proposed exit (from `overall`,
+ * `--strict` promoting a warn) vetoed by any gate coverage with a shortfall —
+ * core's `settleVerdict`, so a `warn` that says "this is not a pass" never
+ * settles to 0. `shrk gate` and MCP `get_quality_gate` both call it.
+ */
+export function settleQualityGateReport(report, strict = false) {
+    return settleVerdict(qualityGateProposedExit(report.overall, strict), report.gates.flatMap((g) => g.coverage ?? []));
+}

package/dist/runner/run-gates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-gates.d.ts","sourceRoot":"","sources":["../../src/runner/run-gates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAElF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAmB,KAAK,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAE9F,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAc,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAc,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,sDAAsD;IACtD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,yCAAyC;IACzC,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,6CAA6C;IAC7C,eAAe,CAAC,EAAE,2BAA2B,CAAC;IAC9C,4CAA4C;IAC5C,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,8BAA8B,CAAC;IACpD,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,4BAA4B,CAAC;IAChD,8EAA8E;IAC9E,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,mFAAmF;IACnF,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC;;;OAGG;IACH,eAAe,CAAC,EAAE,2BAA2B,CAAC;IAC9C,oCAAoC;IACpC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,CA2D7E"}
+{"version":3,"file":"run-gates.d.ts","sourceRoot":"","sources":["../../src/runner/run-gates.ts"],"names":[],"mappings":"AAQA,OAAO,EAAe,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAElF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAmB,KAAK,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAE9F,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAc,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAc,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,sDAAsD;IACtD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,yCAAyC;IACzC,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,6CAA6C;IAC7C,eAAe,CAAC,EAAE,2BAA2B,CAAC;IAC9C,4CAA4C;IAC5C,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,8BAA8B,CAAC;IACpD,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,4BAA4B,CAAC;IAChD,8EAA8E;IAC9E,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,mFAAmF;IACnF,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC;;;OAGG;IACH,eAAe,CAAC,EAAE,2BAA2B,CAAC;IAC9C,oCAAoC;IACpC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AA4BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,CAwE7E"}

package/dist/runner/run-gates.js

@@ -1,3 +1,4 @@
+import { detectGraphFreshness, GraphStore, graphFreshnessBehind, graphFreshnessCoverage, graphFreshnessRemedy, } from '@shrkcrft/graph';
 import { apiDiffGate } from "../gates/api-diff-gate.js";
 import { archGate } from "../gates/arch-gate.js";
 import { graphCyclesGate } from "../gates/graph-cycles-gate.js";
@@ -11,6 +12,32 @@ import { wiringGate } from "../gates/wiring-gate.js";
 import { policyLintGate } from "../gates/policy-lint-gate.js";
 import { knowledgeSymbolGate, } from "../gates/knowledge-symbol-gate.js";
 import { QUALITY_GATE_SCHEMA, } from "../schema/quality-gate.js";
+/** The gates whose answer is DERIVED from the persisted code-graph index. */
+const INDEX_DERIVED_GATES = new Set(['arch', 'impact', 'graph-cycles', 'graph-unresolved']);
+/**
+ * The loud skip of a gate derived from an index behind the working tree: it is
+ * not run over the stale input (a cycle count, an arch verdict or a blast
+ * radius from it misses real findings and reports fixed ones), and it carries
+ * the shared freshness coverage record, so the run settles NOT VERIFIED (2).
+ * `undefined` when the index is current (or there is none — each gate reports
+ * a missing store itself).
+ */
+function staleIndexSkip(id, label, freshness) {
+    if (freshness === undefined)
+        return undefined;
+    const coverage = graphFreshnessCoverage(freshness, id);
+    if (coverage === undefined)
+        return undefined;
+    return {
+        id,
+        label,
+        status: 'skipped',
+        message: `Skipped — derived from the code-graph index, which is behind the working tree (${graphFreshnessBehind(freshness)} change(s) since it was built) — NOT VERIFIED.`,
+        nextCommands: [graphFreshnessRemedy(freshness)],
+        coverage: [coverage],
+        durationMs: 0,
+    };
+}
 /**
  * Run the quality-gate aggregator over a project.
  *
@@ -38,21 +65,28 @@ export function runQualityGates(options) {
     const disabled = new Set(options.disable ?? []);
     const diagnostics = [];
     const gates = [];
+    // THE freshness answer (`detectGraphFreshness`, the authority `graph status`
+    // reads), measured ONCE for graph-fresh and every gate derived from the index
+    // (round 11 review R11-GAP-2): a digest-valid store can be behind the tree.
+    const wantsIndex = ['graph-fresh', ...INDEX_DERIVED_GATES].some((id) => !disabled.has(id));
+    const freshness = wantsIndex && new GraphStore(options.projectRoot).exists() ? detectGraphFreshness(options.projectRoot) : undefined;
     // graph-fresh is always first — other gates depend on it.
     if (!disabled.has('graph-fresh')) {
-        gates.push(graphFreshGate(options.projectRoot));
+        gates.push(graphFreshGate(options.projectRoot, freshness));
     }
     if (!disabled.has('arch')) {
-        gates.push(archGate(options.projectRoot, options.arch ?? {}));
+        gates.push(staleIndexSkip('arch', 'Architecture', freshness) ?? archGate(options.projectRoot, options.arch ?? {}));
     }
     if (!disabled.has('impact')) {
-        gates.push(impactGate(options.projectRoot, options.impact ?? {}));
+        gates.push(staleIndexSkip('impact', 'Impact', freshness) ?? impactGate(options.projectRoot, options.impact ?? {}));
     }
     if (!disabled.has('graph-cycles')) {
-        gates.push(graphCyclesGate(options.projectRoot, options.graphCycles ?? {}));
+        gates.push(staleIndexSkip('graph-cycles', 'Graph cycles', freshness) ??
+            graphCyclesGate(options.projectRoot, options.graphCycles ?? {}));
     }
     if (!disabled.has('graph-unresolved')) {
-        gates.push(graphUnresolvedGate(options.projectRoot, options.graphUnresolved ?? {}));
+        gates.push(staleIndexSkip('graph-unresolved', 'Graph unresolved imports', freshness) ??
+            graphUnresolvedGate(options.projectRoot, options.graphUnresolved ?? {}));
     }
     if (!disabled.has('impact-baseline')) {
         gates.push(impactBaselineGate(options.projectRoot, options.impactBaseline ?? {}));

package/dist/schema/gate-run-request.d.ts

@@ -0,0 +1,32 @@
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IApiDiffGateOptions } from '../gates/api-diff-gate.js';
+/**
+ * What a caller asks the quality-gate aggregator to run — `shrk gate`'s flags,
+ * or MCP `get_quality_gate`'s input. `prepareQualityGateRun` turns it into the
+ * one `IRunGatesOptions` both surfaces run.
+ */
+export interface IGateRunRequest {
+    readonly cwd: string;
+    /** `--since <ref>`: drives the impact gate AND scopes wiring / policy / knowledge-symbol to the diff. */
+    readonly sinceRef?: string;
+    /** `--changed-only` (tracked + untracked worktree). */
+    readonly changedOnly?: boolean;
+    /** `--staged`. */
+    readonly staged?: boolean;
+    /** `--files a,b`. */
+    readonly files?: readonly string[];
+    /** `--fail-on high,critical` for the impact gate; absent = advisory (`[]`). */
+    readonly failOn?: readonly ('high' | 'critical')[];
+    /** `--arch-all`: fail on TOTAL architecture errors, ignoring the frozen baseline. */
+    readonly archAll?: boolean;
+    /** Gate ids to skip. */
+    readonly disable?: readonly string[];
+    /** `--api-baseline` opts the api-diff gate in. */
+    readonly apiDiff?: IApiDiffGateOptions;
+    /**
+     * An inspection already loaded (MCP's `ctx.inspection`) for the
+     * knowledge-symbol gate. When omitted and the gate is enabled, one is built.
+     */
+    readonly inspection?: ISharkcraftInspection;
+}
+//# sourceMappingURL=gate-run-request.d.ts.map

package/dist/schema/gate-run-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-run-request.d.ts","sourceRoot":"","sources":["../../src/schema/gate-run-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yGAAyG;IACzG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,kBAAkB;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,qBAAqB;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC;IACnD,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,wBAAwB;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CAC7C"}

package/dist/schema/gate-run-request.js

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

package/dist/schema/prepared-gate-run.d.ts

@@ -0,0 +1,10 @@
+import type { IRunGatesOptions } from '../runner/run-gates.js';
+/** A gate run ready to execute: the options, plus the config merge notes to surface (stderr / JSON). */
+export interface IPreparedGateRun {
+    readonly options: IRunGatesOptions;
+    /** Pack-plane merge notes (missing / invalid pack rule files, dropped collisions). */
+    readonly planeDiagnostics: readonly string[];
+    /** The resolved changeset, when the request was scoped. */
+    readonly changedFiles?: readonly string[];
+}
+//# sourceMappingURL=prepared-gate-run.d.ts.map

package/dist/schema/prepared-gate-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepared-gate-run.d.ts","sourceRoot":"","sources":["../../src/schema/prepared-gate-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,wGAAwG;AACxG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C"}

package/dist/schema/prepared-gate-run.js

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

package/dist/schema/quality-gate.d.ts

@@ -1,3 +1,4 @@
+import type { IVerdictCoverage } from '@shrkcrft/core';
 export declare const QUALITY_GATE_SCHEMA: "sharkcraft.quality-gate-report/v1";
 export type GateStatus = 'pass' | 'fail' | 'warn' | 'skipped';
 export interface IGateResult {
@@ -12,6 +13,14 @@ export interface IGateResult {
     details?: Readonly<Record<string, unknown>>;
     /** Suggested follow-up command(s) the human / agent can run. */
     nextCommands?: readonly string[];
+    /**
+     * What the gate examined against what it was asked to — one record per unit
+     * of work (e.g. per wiring rule, `subject` = the rule id). A gate that found
+     * nothing wrong over a record with a coverage shortfall is NOT VERIFIED, not
+     * a pass: `shrk gate` settles its exit on these through the CLI's one guard
+     * (`settleVerdict`), so a `warn` that says "not a pass" can never exit 0.
+     */
+    coverage?: readonly IVerdictCoverage[];
     /** Wall-clock duration of the gate, in ms. */
     durationMs: number;
 }

package/dist/schema/quality-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quality-gate.d.ts","sourceRoot":"","sources":["../../src/schema/quality-gate.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,EAAG,mCAA4C,CAAC;AAEhF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,gEAAgE;IAChE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC"}
+{"version":3,"file":"quality-gate.d.ts","sourceRoot":"","sources":["../../src/schema/quality-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,eAAO,MAAM,mBAAmB,EAAG,mCAA4C,CAAC;AAEhF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,gEAAgE;IAChE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvC,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/quality-gates",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "description": "SharkCraft quality gates: single aggregator that runs the code-intelligence checks (graph index, boundaries, architecture, impact summary) and emits one pass/fail report. The pre-merge gate for AI-agent-authored changes.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,15 +43,15 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.30",
-    "@shrkcrft/graph": "^0.1.0-alpha.30",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.30",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.30",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.30",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.30",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.30",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.30",
-    "@shrkcrft/inspector": "^0.1.0-alpha.30"
+    "@shrkcrft/core": "^0.1.0-alpha.31",
+    "@shrkcrft/graph": "^0.1.0-alpha.31",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.31",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.31",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.31",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.31",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.31",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.31",
+    "@shrkcrft/inspector": "^0.1.0-alpha.31"
   },
   "publishConfig": {
     "access": "public"