@descryy/mcp 0.5.0 → 0.7.0

package/dist/tools/pr-analysis.js

@@ -30,8 +30,8 @@
  * times in one reply. `indexPrAnalysisNodes` collapses that: the lists name
  * ids, `nodes` holds each node once. Tool version 2.0.0 for it.
  */
-import { changedFiles, changeRisk, NODE_BUDGETS, nodesInFiles, withProminence } from "@descryy/core";
-import { answer, briefNode, optionalEnum, optionalInteger, optionalString, requiredString, } from "./kit.js";
+import { changedFiles, changeRisk, NODE_BUDGETS, nodesInFiles, withProminence, workingTreeChangedFiles, } from "@descryy/core";
+import { answer, briefNode, optionalEnum, optionalInteger, descryOwnState, optionalString, ToolInputError, } from "./kit.js";
 /**
  * Collapse three overlapping node lists into one map plus three id lists.
  *
@@ -64,9 +64,24 @@ const SCHEMA = {
         base: {
             type: "string",
             description: "The branch or commit this change is measured against, e.g. \"main\" or \"origin/main\". " +
-                "Required — there is no defensible default, and guessing one silently changes the diff.",
+                "Required unless \"workingTree\" is given — there is no defensible default, and guessing " +
+                "one silently changes the diff.",
         },
         head: { type: "string", description: "The tip being reviewed. Default HEAD." },
+        workingTree: {
+            type: "string",
+            enum: ["unstaged", "staged", "all"],
+            description: "Review the change as it stands in the working tree rather than between two refs — the " +
+                "change about to be committed, including files git has never seen. \"all\" is staged and " +
+                "unstaged together. Mutually exclusive with \"base\", and never inferred: the two answer " +
+                "different questions, so the caller declares which one they are asking. Which ran is " +
+                "stated in the reply.",
+        },
+        includeUntracked: {
+            type: "boolean",
+            description: "With \"workingTree\", include files git has never seen. On by default — a new file " +
+                "written and not yet added is part of the change about to be committed.",
+        },
         trigger: {
             type: "string",
             enum: [...TRIGGERS],
@@ -74,26 +89,60 @@ const SCHEMA = {
         },
         limit: { type: "integer", minimum: 1, description: "Cap on nodes per list. Default 50." },
     },
-    required: ["base"],
     additionalProperties: false,
 };
 async function run(args, ctx) {
-    // Required rather than defaulted: there is no defensible default base, and
-    // guessing one would silently change which diff the whole answer describes.
-    const base = requiredString(args, "base");
-    const head = optionalString(args, "head") ?? "HEAD";
+    // One of the two questions has to be chosen, and neither has a defensible
+    // default: guessing would silently change which change set the whole answer
+    // describes. This tool's own reasoning is that the diff is what defines a
+    // change to review — a working tree *is* a diff, it is simply not a
+    // ref-to-ref one, so accepting it completes that principle rather than
+    // bending it. Which one ran is stated in the reply.
+    const workingTree = optionalString(args, "workingTree");
+    const includeUntracked = args["includeUntracked"] !== false;
+    const baseArg = optionalString(args, "base");
+    if (workingTree === undefined && baseArg === undefined) {
+        throw new ToolInputError('Give either "base" (a ref range) or "workingTree" (the change as it stands, uncommitted). ' +
+            "There is no defensible default, and guessing one silently changes which change set the " +
+            "answer describes.");
+    }
+    if (workingTree !== undefined && baseArg !== undefined) {
+        throw new ToolInputError('"base" and "workingTree" are mutually exclusive — they are two different questions. Ask one.');
+    }
+    if (workingTree !== undefined && !["unstaged", "staged", "all"].includes(workingTree)) {
+        throw new ToolInputError(`"workingTree" must be "unstaged", "staged" or "all" — got "${workingTree}".`);
+    }
+    const scope = (workingTree ?? "all");
+    const mode = baseArg === undefined ? "working-tree" : "range";
+    const base = baseArg ?? null;
+    const head = base === null ? null : optionalString(args, "head") ?? "HEAD";
+    const subject = base === null ? `the working tree (${scope})` : `${base}...${head}`;
+    /** Carried into every one of the four reply shapes, so none can omit it. */
+    const identity = {
+        mode,
+        base,
+        head,
+        ...(base === null ? { workingTree: { scope, includeUntracked } } : {}),
+    };
     const trigger = optionalEnum(args, "trigger", TRIGGERS) ?? "pr";
     const limit = optionalInteger(args, "limit", 1) ?? 50;
     const session = ctx.session;
     const stamp = session.provider().baseStamp();
-    ctx.progress(`Diffing ${base}...${head}`);
+    ctx.progress(`Diffing ${subject}`);
     let files;
     try {
-        files = await changedFiles(session.repoPath, base, head);
+        files =
+            base === null
+                ? await workingTreeChangedFiles(session.repoPath, {
+                    scope,
+                    includeUntracked,
+                    exclude: descryOwnState(session.config.graph),
+                })
+                : await changedFiles(session.repoPath, base, head);
     }
     catch (error) {
         return answer({
-            headline: `Could not diff ${base}...${head}.`,
+            headline: `Could not diff ${subject}.`,
             state: "refused",
             nameLevel: true,
             resolutionFloor: 0,
@@ -102,16 +151,18 @@ async function run(args, ctx) {
             irSchemaVersion: stamp.irSchemaVersion,
             commitSpread: stamp.commitSpread,
             notes: [
-                `git rejected the range: ${error.message.trim()}. Check that "${base}" exists ` +
-                    "locally — a shallow clone or a missing fetch is the usual cause.",
+                (base === null
+                    ? `git rejected the working-tree read: ${error.message.trim()}.`
+                    : `git rejected the range: ${error.message.trim()}. Check that "${base}" ` +
+                        "exists locally — a shallow clone or a missing fetch is the usual cause."),
             ],
-            data: { base, head, files: [] },
+            data: { ...identity, files: [] },
         });
     }
     const notes = [];
     if (files.length === 0) {
         return answer({
-            headline: `${base}...${head} changes no files.`,
+            headline: `${subject} changes no files.`,
             nameLevel: true,
             // 0, not 4. Every other branch of this tool already stamps 0 for the same
             // reason `get_git_diff` does — a live git read is not a graph-traversal
@@ -124,7 +175,7 @@ async function run(args, ctx) {
             irSchemaVersion: stamp.irSchemaVersion,
             commitSpread: stamp.commitSpread,
             notes: ["An empty diff is a real answer: there is nothing to assess."],
-            data: { base, head, files: [], nodes: {}, affected: [], untested: [], tests: [] },
+            data: { ...identity, files: [], nodes: {}, affected: [], untested: [], tests: [] },
         });
     }
     ctx.progress(`Resolving ${files.length} changed file(s)`, 1, 3);
@@ -137,7 +188,7 @@ async function run(args, ctx) {
     }
     if (nodes.length === 0) {
         return answer({
-            headline: `None of the ${files.length} changed file(s) are in the graph.`,
+            headline: `None of the ${files.length} file(s) changed in ${subject} are in the graph.`,
             state: "refused",
             nameLevel: true,
             resolutionFloor: 0,
@@ -150,7 +201,7 @@ async function run(args, ctx) {
                 "No blast radius was computed. Run analyze first; if it has already run, its disclosures " +
                     "name the languages and paths it could not read.",
             ],
-            data: { base, head, files, missing, nodes: {}, affected: [], untested: [], tests: [] },
+            data: { ...identity, files, missing, nodes: {}, affected: [], untested: [], tests: [] },
         });
     }
     ctx.progress(`Assessing ${nodes.length} changed symbol(s)`, 2, 3);
@@ -173,8 +224,7 @@ async function run(args, ctx) {
         result: {
             ...risk,
             data: {
-                base,
-                head,
+                ...identity,
                 files,
                 missing,
                 changedSymbols: nodes.length,
@@ -187,9 +237,9 @@ async function run(args, ctx) {
         },
         ...(affected.length === 0 ? { state: "empty" } : {}),
         nameLevel: true,
-        headline: `${nodes.length} changed symbol(s) across ${files.length} file(s) affect ${affected.length} ` +
-            `other node(s). ${risk.data.tests.length} test(s) cover part of that; ${untested.length} ` +
-            "affected node(s) have no covering test in the graph.",
+        headline: `Across ${subject}: ${nodes.length} changed symbol(s) in ${files.length} file(s) affect ` +
+            `${affected.length} other node(s). ${risk.data.tests.length} test(s) cover part of that; ` +
+            `${untested.length} affected node(s) have no covering test in the graph.`,
     };
 }
 export const prAnalysisTool = {

package/dist/tools/pr-analysis.js.map

@@ -1 +1 @@
-{"version":3,"file":"pr-analysis.js","sourceRoot":"","sources":["../../src/tools/pr-analysis.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pr-analysis.js","sourceRoot":"","sources":["../../src/tools/pr-analysis.ts"],"names":[],"mappings":"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"}

package/dist/tools/pre-push.d.ts

@@ -38,12 +38,28 @@
  *
  * ## Blocking versus informational
  *
- * `blockingTotal` counts `contracts` and `validate` findings only. Those are
- * claims that something is *wrong*. `scope` and `pr_analysis` answer "what does
- * this change touch" — real, useful, and not a defect, so counting them would
- * make every change with a blast radius look like a failure. `descry check`
- * exits non-zero on `blockingTotal`, which is why the line has to be drawn
- * here rather than left to the caller.
+ * `blockingTotal` counts `contracts` and `validate` findings only, and — since
+ * UAT round 3, Suggestion 6 — only the ones each tool's own `claim` field
+ * marks a `defect`. `scope` and `pr_analysis` answer "what does this change
+ * touch" — real, useful, and not a defect, so counting them would make every
+ * change with a blast radius look like a failure. A `lead` (`ROUTE_NOT_CALLED`,
+ * `SET_BUT_UNDOCUMENTED`) is worth a look but is not provable from the graph
+ * alone, so it is counted separately in `leadTotal` rather than folded into
+ * the number a git hook branches on. `descry check` exits non-zero on
+ * `blockingTotal`, which is why the line has to be drawn here rather than
+ * left to the caller.
+ *
+ * ## Scoped to what you are pushing
+ *
+ * UAT round 3, B11. `contracts` did not receive the `files` this tool was
+ * called with, so `blockingTotal` counted the repository's entire standing
+ * backlog rather than the change being pushed — 15 pre-existing
+ * `ROUTE_NOT_CALLED` findings for unrelated paths, on a push touching three
+ * unrelated files. `contracts` now takes the same `files` this tool was
+ * given (it already accepted `paths`, a different axis — a URL template
+ * substring, not a source file), so both blocking sources answer about the
+ * files in front of the developer. `validate` already took `files`; only the
+ * threading into `contracts` was missing.
  *
  * ## Class and tier
  *
@@ -60,18 +76,87 @@ export interface PrePushSection {
     readonly total: number;
     /** The top few, in the order that source reported them. */
     readonly shown: readonly unknown[];
-    /** True when this source's findings count toward `blockingTotal`. */
-    readonly blocking: boolean;
+    /**
+     * True when this source is **the kind that claims something is wrong** —
+     * a property of the source, not of what it found this time.
+     *
+     * **It was called `blocking`, sitting beside a `blockingTotal` that means the
+     * other thing.** `contracts` can be `blocking: true` with `total: 0`, and
+     * `validate` `blocking: true` with ten leads and a `blockingTotal` of zero,
+     * so the obvious consumer arithmetic — sum `total` over the blocking
+     * sections — is wrong in both directions. This tool's own test suite made
+     * exactly that mistake and passed, because the fixture happened to produce no
+     * leads.
+     *
+     * The name now says which question it answers. The other question — *did this
+     * section find anything that blocks?* — is `defects > 0`, and there is no
+     * longer a field whose name suggests it answers both.
+     */
+    readonly claimsFaults: boolean;
+    /** Of `total`, how many assert a fault. Zero for a source that claims none. */
+    readonly defects: number;
+    /** Of `total`, how many are worth a look without asserting one. */
+    readonly leads: number;
     /** This source's own headline, kept verbatim. */
     readonly headline: string;
 }
+/**
+ * Which change set the coverage section actually described.
+ *
+ * `pr_analysis` derives its own file list from `base...head` and takes none,
+ * deliberately. Three constituents therefore describe the files passed and one
+ * describes the branch's committed diff, and in a real run those were 2 files
+ * and 25. Both answers were right; presented side by side under one headline
+ * they read as one answer about one change.
+ *
+ * The disclosure explaining that has always been in the reply. It sat below a
+ * headline and a section total that both read as though they described the
+ * files passed, which is the wrong order for the most common working moment:
+ * before a commit, when the git-derived half can see none of the work.
+ */
+export interface PrePushCoverage {
+    /** The ref-to-ref diff `pr_analysis` answered about. */
+    readonly describes: string;
+    /** Files passed that the base diff does not contain — whatever the reason. */
+    readonly filesOutsideDiff: readonly string[];
+    /**
+     * Of those, the ones git reports as modified, staged or untracked.
+     *
+     * Separated because "not in the diff" has two causes and only one is about
+     * timing: uncommitted work the developer can commit, versus a file they named
+     * that this branch never touched.
+     */
+    readonly uncommitted: readonly string[];
+}
 export interface PrePushData {
     readonly files: readonly string[];
     readonly sections: readonly PrePushSection[];
-    /** Contract and environment findings only — see the module header on why scope is not counted. */
+    /**
+     * Contract and environment findings that **assert a fault**.
+     *
+     * The doctrine that keeps `scope` and `pr_analysis` out of this number is the
+     * same one that keeps a lead out of it: a change with a large blast radius is
+     * not a broken change, and neither is a route no code in this graph calls.
+     * Both constituents already knew which of their findings claimed a fault —
+     * `validate` in a field, `contracts` in the prose of the finding itself — and
+     * this composite flattened them into one count a git hook exits on.
+     *
+     * "15 blocking findings" and "1 defect, 15 leads" are different sentences and
+     * only one is worth acting on. A check that cries wolf is worse than no
+     * check, because it also discredits the real findings underneath it.
+     */
     readonly blockingTotal: number;
+    /** Findings worth a look that assert nothing. Reported, never exited on. */
+    readonly leadTotal: number;
     /** The node budget actually applied to the traversing constituents. */
     readonly nodeBudget: number;
+    /**
+     * What the coverage section was about, when one ran.
+     *
+     * `null` when no base ref was given: `pr_analysis` is skipped entirely then,
+     * and a caveat about a section that did not run is a caveat about nothing.
+     */
+    readonly coverage: PrePushCoverage | null;
 }
 export declare const prePushTool: ToolDefinition;
 //# sourceMappingURL=pre-push.d.ts.map

package/dist/tools/pre-push.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pre-push.d.ts","sourceRoot":"","sources":["../../src/tools/pre-push.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAKH,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAuClB,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAE/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAgND,eAAO,MAAM,WAAW,EAAE,cAezB,CAAC"}
+{"version":3,"file":"pre-push.d.ts","sourceRoot":"","sources":["../../src/tools/pre-push.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAKH,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAuClB,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAE/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAC3C;AAoTD,eAAO,MAAM,WAAW,EAAE,cAiBzB,CAAC"}

package/dist/tools/pre-push.js

@@ -38,19 +38,35 @@
  *
  * ## Blocking versus informational
  *
- * `blockingTotal` counts `contracts` and `validate` findings only. Those are
- * claims that something is *wrong*. `scope` and `pr_analysis` answer "what does
- * this change touch" — real, useful, and not a defect, so counting them would
- * make every change with a blast radius look like a failure. `descry check`
- * exits non-zero on `blockingTotal`, which is why the line has to be drawn
- * here rather than left to the caller.
+ * `blockingTotal` counts `contracts` and `validate` findings only, and — since
+ * UAT round 3, Suggestion 6 — only the ones each tool's own `claim` field
+ * marks a `defect`. `scope` and `pr_analysis` answer "what does this change
+ * touch" — real, useful, and not a defect, so counting them would make every
+ * change with a blast radius look like a failure. A `lead` (`ROUTE_NOT_CALLED`,
+ * `SET_BUT_UNDOCUMENTED`) is worth a look but is not provable from the graph
+ * alone, so it is counted separately in `leadTotal` rather than folded into
+ * the number a git hook branches on. `descry check` exits non-zero on
+ * `blockingTotal`, which is why the line has to be drawn here rather than
+ * left to the caller.
+ *
+ * ## Scoped to what you are pushing
+ *
+ * UAT round 3, B11. `contracts` did not receive the `files` this tool was
+ * called with, so `blockingTotal` counted the repository's entire standing
+ * backlog rather than the change being pushed — 15 pre-existing
+ * `ROUTE_NOT_CALLED` findings for unrelated paths, on a push touching three
+ * unrelated files. `contracts` now takes the same `files` this tool was
+ * given (it already accepted `paths`, a different axis — a URL template
+ * substring, not a source file), so both blocking sources answer about the
+ * files in front of the developer. `validate` already took `files`; only the
+ * threading into `contracts` was missing.
  *
  * ## Class and tier
  *
  * `read` — it runs four read tools and writes nothing. `evidence` — it reports
  * what those four found and draws no conclusion of its own.
  */
-import { NODE_BUDGETS } from "@descryy/core";
+import { NODE_BUDGETS, uncommittedAmong } from "@descryy/core";
 import { contractsTool } from "./contracts.js";
 import { answer, optionalInteger, optionalString, optionalStringArray, } from "./kit.js";
 import { prAnalysisTool } from "./pr-analysis.js";
@@ -97,8 +113,44 @@ function listOf(data, key) {
     const value = data[key];
     return Array.isArray(value) ? value : [];
 }
+/**
+ * A finding's own claim, defaulting to `defect` when it carries none.
+ *
+ * The default is deliberate and it is the safe direction: a source that has not
+ * yet been taught the distinction has its findings counted as fault claims, so
+ * adding a check can never silently stop blocking a push. The opposite default
+ * would turn every un-migrated source into a source of leads overnight.
+ */
+function claimOf(item) {
+    return typeof item === "object" &&
+        item !== null &&
+        item["claim"] === "lead"
+        ? "lead"
+        : "defect";
+}
+/**
+ * The leading clause, when the coverage section is about a different change set.
+ *
+ * **First, not in a footnote.** This mismatch has always been disclosed, and
+ * the disclosure sat underneath a headline and a section total that both read
+ * as if they described the files passed. A reader who stops at the headline —
+ * which is what a headline is for — got a confident sentence about the wrong
+ * work. Ordering is the whole fix.
+ *
+ * Empty when it does not apply, because a caveat printed on every run is one a
+ * reader learns to skip past on the run where it matters.
+ */
+function coverageWarning(files, coverage) {
+    if (coverage === null || coverage.uncommitted.length === 0)
+        return "";
+    const n = coverage.uncommitted.length;
+    return (`${n} of ${files.length} file(s) are uncommitted, so the pr_analysis section describes ` +
+        `committed work only (${coverage.describes}) and not them. ` +
+        "The other three sections describe the files you passed. ");
+}
 async function run(args, ctx) {
     const files = optionalStringArray(args, "files") ?? [];
+    let coverage = null;
     const perSource = optionalInteger(args, "perSource", 1) ?? PER_SOURCE;
     const baseRef = optionalString(args, "base");
     const base = ctx.session.provider().baseStamp();
@@ -110,9 +162,10 @@ async function run(args, ctx) {
         "Sources are NOT ranked against each other. Whether a contract mismatch outranks an unset " +
             "environment variable is a judgement Descry has no model for, so each source contributes its " +
             "own top few and the totals say what they were selected from.",
-        "blockingTotal counts contracts and validate findings only. scope and pr_analysis answer what a " +
-            "change touches, which is not a defect — counting them would make every change with a blast " +
-            "radius look like a failure.",
+        "blockingTotal counts contracts and validate findings claimed as defects only — see claim on " +
+            "each finding. scope and pr_analysis answer what a change touches, which is not a defect, and " +
+            "a lead (worth a look, not provable from the graph alone) is counted separately in leadTotal " +
+            "rather than folded into the number a hook branches on.",
     ];
     if (files.length === 0) {
         return answer({
@@ -125,7 +178,7 @@ async function run(args, ctx) {
             irSchemaVersion: base.irSchemaVersion,
             commitSpread: base.commitSpread,
             notes,
-            data: { files: [], sections: [], blockingTotal: 0, nodeBudget },
+            data: { files: [], sections: [], blockingTotal: 0, leadTotal: 0, nodeBudget, coverage: null },
         });
     }
     // Sequential rather than concurrent, deliberately: these share one SQLite
@@ -138,7 +191,7 @@ async function run(args, ctx) {
     // three that were not -- the same leaked-default failure this repository's
     // own UAT caught on a refusal path.
     const floors = [];
-    const runOne = async (source, tool, toolArgs, pick, blocking) => {
+    const runOne = async (source, tool, toolArgs, pick, claimsFaults, claimOf = () => "defect") => {
         ctx.progress(`Running ${source}`);
         let sub;
         try {
@@ -153,23 +206,32 @@ async function run(args, ctx) {
                 state: "failed",
                 total: 0,
                 shown: [],
-                blocking,
+                claimsFaults,
+                defects: 0,
+                leads: 0,
                 headline: `${source} failed: ${error instanceof Error ? error.message : String(error)}`,
             });
-            return;
+            return null;
         }
         floors.push(sub.resolutionFloor);
         const items = pick(sub.data);
+        // A source that does not claim anything is wrong contributes to neither
+        // count, whatever it found — the split is about fault claims, and `scope`
+        // makes none.
+        const leads = claimsFaults ? items.filter((item) => claimOf(item) === "lead").length : 0;
         sections.push({
             source,
             state: sub.state,
             total: items.length,
             shown: items.slice(0, perSource),
-            blocking,
+            claimsFaults,
+            defects: claimsFaults ? items.length - leads : 0,
+            leads,
             headline: sub.headline,
         });
         for (const note of sub.notes)
             collectedNotes.push(`${source}: ${note}`);
+        return sub;
     };
     await runOne("scope", scopeTool, { files, trigger: "pre-push" }, (data) => listOf(data, "affected"), false);
     if (baseRef === undefined) {
@@ -182,7 +244,9 @@ async function run(args, ctx) {
             state: "refused",
             total: 0,
             shown: [],
-            blocking: false,
+            claimsFaults: false,
+            defects: 0,
+            leads: 0,
             headline: "pr_analysis needs a base ref to diff against and has no default. Pass \"base\" to include it.",
         });
     }
@@ -197,16 +261,52 @@ async function run(args, ctx) {
             `${baseRef}...HEAD), not from the files given here: it takes no file list, deliberately, ` +
             "because the diff is what defines a change to review. So its section may describe a wider " +
             "or narrower set of files than the other three, which use the list you passed.");
-        await runOne("pr_analysis", prAnalysisTool, { base: baseRef, trigger: "pre-push" }, (data) => listOf(data, "untested"), false);
+        const pr = await runOne("pr_analysis", prAnalysisTool, { base: baseRef, trigger: "pre-push" }, (data) => listOf(data, "untested"), false);
+        if (pr !== null) {
+            // The comparison is against the list `pr_analysis` itself reports, not a
+            // second diff computed here. Two git calls answering the same question
+            // is how they come to disagree.
+            const inDiff = new Set(listOf(pr.data, "files").filter((f) => typeof f === "string"));
+            const outside = files.filter((file) => !inDiff.has(file));
+            // A failure here must not take the other three constituents with it —
+            // the rule this file already states for a constituent, applied to the
+            // caveat about one. Without the classification the reply still reports
+            // which files the coverage section did not describe; it just cannot say
+            // that the reason was timing.
+            let uncommitted = [];
+            try {
+                uncommitted = await uncommittedAmong(ctx.session.repoPath, outside);
+            }
+            catch (error) {
+                if (outside.length > 0) {
+                    notes.push(`${outside.length} file(s) you passed are not in ${baseRef}...HEAD, and git could ` +
+                        `not be asked whether that is because they are uncommitted: ` +
+                        `${error.message.trim()}. They are listed in coverage.filesOutsideDiff.`);
+                }
+            }
+            coverage = {
+                describes: `${baseRef}...HEAD`,
+                filesOutsideDiff: outside,
+                uncommitted,
+            };
+        }
     }
     await runOne("contracts", contractsTool, 
-    // pathsOnly is what the pre-push tier means for a tool with no traversal to
-    // budget — see the module header.
-    { pathsOnly: true }, (data) => listOf(data, "findings"), true);
-    await runOne("validate", validateTool, { files, maxFindings: VALIDATE_MAX_FINDINGS }, (data) => listOf(data, "findings"), true);
-    const blockingTotal = sections
-        .filter((section) => section.blocking)
-        .reduce((sum, section) => sum + section.total, 0);
+    // budget — see the module header. `files` is UAT round 3, B11: without it,
+    // contracts compared the whole graph and this section's total was the
+    // repository's standing backlog, not the change being pushed.
+    { pathsOnly: true, files }, 
+    // shapeMismatches is always empty under pathsOnly, but folded in anyway
+    // rather than assumed empty — a future call that drops pathsOnly should
+    // not silently under-count defects here.
+    (data) => [...listOf(data, "findings"), ...listOf(data, "shapeMismatches")], true, claimOf);
+    await runOne("validate", validateTool, { files, maxFindings: VALIDATE_MAX_FINDINGS }, (data) => listOf(data, "findings"), true, claimOf);
+    // Each section already reports 0/0 for both when it does not claim faults
+    // (`claimsFaults: false`), so summing `defects`/`leads` across every section
+    // needs no separate filter — the split already happened when the section was
+    // built.
+    const blockingTotal = sections.reduce((sum, section) => sum + section.defects, 0);
+    const leadTotal = sections.reduce((sum, section) => sum + section.leads, 0);
     const failed = sections.filter((section) => section.state === "failed");
     if (failed.length > 0) {
         notes.push(`${failed.length} of 4 constituent(s) failed and contributed nothing: ` +
@@ -214,15 +314,18 @@ async function run(args, ctx) {
             "reply is not.");
     }
     return answer({
-        headline: blockingTotal === 0
-            ? `No contract or environment findings across ${files.length} changed file(s).`
-            : `${blockingTotal} blocking finding(s) across ${files.length} changed file(s) — see the ` +
-                "contracts and validate sections.",
+        headline: coverageWarning(files, coverage) +
+            (blockingTotal === 0 && leadTotal === 0
+                ? `No contract or environment findings across ${files.length} changed file(s).`
+                : `${blockingTotal} defect(s) and ${leadTotal} lead(s) across ${files.length} changed ` +
+                    "file(s) — only the defects assert that something is wrong. See the contracts and " +
+                    "validate sections."),
         // `empty` is earned here: all four ran against a real graph and found
-        // nothing blocking. A constituent that refused makes that untrue, so the
-        // state follows the weakest link rather than the happy path.
-        state: failed.length > 0 ? "failed" : blockingTotal > 0 ? "ok" : "empty",
-        data: { files, sections, blockingTotal, nodeBudget },
+        // nothing at all, blocking or not. A constituent that refused makes that
+        // untrue, so the state follows the weakest link rather than the happy
+        // path — and a lead is still something found, so it is `ok`, not `empty`.
+        state: failed.length > 0 ? "failed" : blockingTotal + leadTotal > 0 ? "ok" : "empty",
+        data: { files, sections, blockingTotal, leadTotal, nodeBudget, coverage },
         resolutionFloor: (floors.length === 0 ? 0 : Math.min(...floors)),
         nameLevel: true,
         commitSha: base.commitSha,
@@ -242,8 +345,10 @@ export const prePushTool = {
         "returns one short envelope: what your change touches, what it touches that has no test, which " +
         "API contracts break, and which environment claims do not hold. Each source contributes its own " +
         "top few — they are deliberately not ranked against each other, because Descry has no model for " +
-        "whether a contract mismatch outranks an unset variable. blockingTotal counts only the two " +
-        "sources that report defects, and is what a git hook should branch on.",
+        "whether a contract mismatch outranks an unset variable. Both are scoped to the files you pass, " +
+        "not the repository's whole backlog. blockingTotal counts only defects (provable from the graph " +
+        "alone) from the two sources that report them, and is what a git hook should branch on; leads " +
+        "(worth a look, not provable alone) are counted separately in leadTotal.",
     inputSchema: SCHEMA,
     run,
 };