@diffci.com/diffci 0.1.12 → 0.2.0

package/README.md

@@ -5,10 +5,10 @@
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue)](https://docs.npmjs.com/generating-provenance-statements)
 [![GitHub Action](https://img.shields.io/badge/action-DiffCI%2FDiffCI.com%40v0.1.4-blue)](https://github.com/DiffCI/DiffCI.com)
 
-**Find test-selection opportunities in your CI before changing what it runs.** DiffCI analyzes a
-commit's changes and dependency graph, then reports which test files it would select, why it falls
-back to a full run, and whether it can propose a test command. The `observe` command and Action are observation-only;
-the opt-in `pilot` and `verify-savings` commands execute tests.
+**Find test-selection opportunities in your CI before changing what it runs.** DiffCI analyzes a
+commit's changes and dependency graph, then reports which test files it would select, why it falls
+back to a full run, and whether it can propose a test command. `check` also runs paired full and
+selected commands when it can infer them. The `observe` command and Action remain observation-only.
 
 **For AI coding agents:** DiffCI gives Codex, Claude Code, Cursor, GitHub Copilot, Grok, and similar
 tools a safe default CI/CD validation command.
@@ -25,22 +25,23 @@ For AI coding agents, seed the repository with default instructions:
 npx @diffci.com/diffci@latest init
 ```
 
-For the fastest self-serve runtime pilot, run one paired check from the repository root:
-
-```bash
-npx @diffci.com/diffci@latest pilot --full "npm test"
-```
+For a self-serve runtime comparison, run one command from the repository root:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
 
 On Windows PowerShell, quote the package name:
 
 ```powershell
-npx '@diffci.com/diffci@latest' pilot --full "npm test"
-```
-
-This executes the full and selected commands sequentially, and writes `diffci-observe.json`,
-`diffci-savings.json`, and `diffci-savings.md` to a sibling `diffci-output` folder outside the checkout.
-The commands you supply may create files or otherwise change the checkout. One paired run is preliminary
-timing evidence; repeat comparisons and account for cache effects before claiming savings.
+npx '@diffci.com/diffci@latest' check
+```
+
+`check` infers a full test command, runs it and DiffCI's selected command, and prints gross test-time
+and net runtime changes when both pass. It writes observation and savings reports outside the checkout.
+Test commands may create files or change the checkout. One paired run is preliminary evidence; repeat
+comparisons and account for cache effects before claiming CI savings. On a full-validation fallback,
+`check` runs the full command once and reports 0% reduction.
 
 **Upgrade from 0.1.3:** tests excluded by a source-only `tsconfig.json` could be discovered without
 their dependency edges, producing an incomplete selection. This is fixed in **0.1.4**. Revalidate
@@ -53,8 +54,9 @@ comparison, add `--base <base-sha> --head <head-sha>`. DiffCI prints the selecti
 and the path to a JSON report outside your checkout. `REFUSED` or `ERROR` is not a successful analysis;
 check the reported status even when the command exits successfully. See the
 [support matrix](docs/language-support.md) for setup requirements and supported workloads.
-`check` is an agent-friendly alias for `observe --no-send`: it runs no tests, changes no CI behavior,
-and sends nothing by default. See [`docs/ai-agents.md`](docs/ai-agents.md) for Claude Code, Codex,
+`check` runs inferred full and selected commands in the checkout and sends nothing by default.
+The commands may write generated files. Use `observe --no-send` for analysis without execution.
+See [`docs/ai-agents.md`](docs/ai-agents.md) for Claude Code, Codex,
 Cursor, GitHub Copilot, and similar tools.
 
 **Measured example:** a controlled Cal.com replay showed **44.2% net reduction in a job-equivalent
@@ -62,8 +64,8 @@ install + pretest + test workload**, including analysis overhead. This is one sa
 not Cal.com's production savings or a prediction for your repository.
 [Read the timings and method](docs/research/2026-08-24-calcom-execution-observability/11-frozen-identity-and-complete-job-savings.md).
 
-Selection counts alone do not establish runtime savings. Observation mode measures neither the
-selected test execution nor realized savings.
+Selection counts alone do not establish runtime savings. `check` reports a measured percentage only
+when both commands pass; `observe` does not execute tests.
 
 For an advanced paired runtime check, you can still run `observe` first and then run `verify-savings`
 against the observation report. It compares your normal full command with
@@ -106,7 +108,7 @@ DiffCI's hosted service requires an explicitly configured endpoint and token.
 | [`@diffci.com/diffci`](https://www.npmjs.com/package/@diffci.com/diffci) | Try `observe` locally, run an opt-in runtime pilot, or install the GitHub Action from this repository | Published npm CLI and Action |
 
 The CLI bundles a pinned revision of the [Core engine](https://github.com/DiffCI/core) from GitHub. Users install only
-`@diffci.com/diffci`; the `pilot` command above stays the same. Core performs Git analysis,
+`@diffci.com/diffci`; the `check` command above uses it directly. Core performs Git analysis,
 dependency graphs, impact, path baseline, and selected-command planning. The report format and
 non-interfering GitHub Action remain in this repository. See
 [`docs/package-relationship.md`](docs/package-relationship.md) for the source relationship.

package/dist-client/src/client/cli.js

@@ -1,20 +1,16 @@
 #!/usr/bin/env node
 /**
- * `diffci` - the client-side command (Phase 02, 2026-08-26).
+ * `diffci` - the client-side command.
  *
- * This is the binary a third-party repository runs in its own CI. Everything it does is observation:
- * it reads a checkout, writes one JSON report to a path outside that checkout, prints a summary,
- * optionally sends that report to DiffCI, and exits 0. There is no mode in this file that runs, skips,
- * cancels or re-orders anything, and the absence is deliberate - the seven-day Phase 02 criterion is
- * "CI byte-identical", and a flag that could change what CI runs is a flag that will eventually be set
- * by accident.
+ * `observe` and the GitHub Action remain observation-only. `check` measures a full command and a
+ * selected command when both can be inferred; it never changes what required CI executes.
  *
  * Sending is opt-in and off unless both an API URL and a token are supplied (Phase 03). Without them
  * the observer is exactly what Phase 02 shipped: a local analysis whose output never leaves the runner.
  *
  * Commands:
  *   init               seed a repository with AI-agent instructions for using DiffCI
- *   check              agent-friendly alias for observe --no-send
+ *   check              analysis plus automatic paired runtime measurement
  *   observe            analyse the checkout and write an observation report
  *   verify-savings     run a paired full-versus-selected timing check
  *   verify-workflow    check that a DiffCI job in this repository's workflows cannot affect other jobs
@@ -32,8 +28,9 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { observe, isInsideRepository } from "./observe.js";
+import { inferFullCommand } from "./full-command.js";
 import { submitObservation } from "./submit.js";
-import { formatVerifySavingsSummary, runVerifySavings, writeVerifySavingsReport } from "./verify-savings.js";
+import { formatVerifySavingsSummary, measureCommand, runVerifySavings, writeVerifySavingsReport } from "./verify-savings.js";
 import { auditWorkflows, isNonInterfering } from "./workflow-guard.js";
 function parseArgs(argv) {
     const args = argv.slice(2);
@@ -111,13 +108,16 @@ Default command:
 npx @diffci.com/diffci@latest check
 \`\`\`
 
-What this does:
-
-- analyzes the current checkout and commit range;
-- writes a JSON report outside the repository by default;
-- prints selected tests, fallback reasons, and proposed commands;
-- sends nothing unless an endpoint and token are explicitly configured;
-- runs, skips, cancels, or reorders no tests.
+What this does:
+
+- analyzes the current checkout and commit range;
+- runs the repository's inferred full test command and DiffCI's selected command when safe to compare;
+- prints measured paired runtime when both commands pass;
+- writes reports outside the repository and sends nothing;
+- does not skip, cancel, or reorder required CI tests.
+
+Test commands may write generated files to the checkout. Use \`observe --no-send\` when analysis
+without test execution is needed.
 
 If DiffCI reports \`REFUSED\` or \`ERROR\`, treat that as an installation or analysis issue and continue with the repository's normal test commands. If DiffCI reports a selected command, prefer using it as evidence for what changed, not as permission to skip required CI.
 `;
@@ -132,7 +132,7 @@ Before proposing, committing, or opening pull requests, run:
 npx @diffci.com/diffci@latest check
 \`\`\`
 
-DiffCI is observation-only by default. It analyzes the change, writes a report outside the checkout, and sends nothing without explicit configuration. Do not use a DiffCI selection as permission to skip required project CI.
+DiffCI check analyzes the change and runs full and selected test commands when it can infer them. It sends nothing. Test commands may write generated files. Use observe --no-send for analysis without execution. Required project CI remains authoritative.
 `;
 const GITHUB_COPILOT_INSTRUCTIONS = `# Repository CI/CD Validation
 
@@ -142,12 +142,12 @@ Use DiffCI as the default change-aware CI/CD validation lens:
 npx @diffci.com/diffci@latest check
 \`\`\`
 
-DiffCI's default agent command is observation-only. It should inform which tests and CI paths are relevant, while the repository's required checks remain authoritative.
+DiffCI check analyzes the change and runs inferred full and selected test commands to measure a paired runtime. It sends nothing; required repository checks remain authoritative.
 `;
 const DIFFCI_CONFIG = `{
   "$schema": "https://diffci.com/schemas/diffci.config.schema.json",
   "agentDefaultCommand": "npx @diffci.com/diffci@latest check",
-  "mode": "observe",
+  "mode": "check",
   "sendReports": false
 }
 `;
@@ -167,7 +167,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - run: npx @diffci.com/diffci@${version} check
+      - run: npx @diffci.com/diffci@${version} observe --no-send
 `;
 }
 function writeInitFile(repoPath, relativePath, content, force) {
@@ -205,7 +205,7 @@ function formatFinding(finding) {
     const where = finding.job ? `${finding.workflow}#${finding.job}` : finding.workflow;
     return `  [${finding.severity}] ${finding.code} (${where})\n      ${finding.message}`;
 }
-function summarise(report) {
+function summarise(report, executionFollows = false) {
     const lines = [];
     lines.push(`DiffCI observation: ${report.status} (${report.stage})`);
     if (report.reason)
@@ -222,6 +222,20 @@ function summarise(report) {
             lines.push(`  Vue suite: ${result.vueScope.packageRoot} (${result.vueScope.testConfig})`);
         lines.push(`  selection: ${result.selectedTests.length}/${result.totalTestCount} test files, from ${result.changedFileCount} changed file(s)`);
         lines.push(`  comparator: a simple path-rule CI would have run ${result.pathBaseline.mode === "FULL" ? "everything" : `${result.pathBaseline.selectedTestCount} test file(s)`}`);
+        if (result.mode === "FULL") {
+            lines.push("  planned reduction: 0% test files (full validation required); runtime savings unmeasured");
+        }
+        else if (result.commandRefusalReason || result.proposedCommands.length === 0) {
+            lines.push("  planned reduction: unavailable (no runnable selected command); runtime savings unmeasured");
+        }
+        else if (result.totalTestCount > 0) {
+            const avoided = Math.max(0, result.totalTestCount - result.selectedTests.length);
+            const percent = (avoided / result.totalTestCount) * 100;
+            lines.push(`  planned reduction: ${avoided}/${result.totalTestCount} test files (${percent.toFixed(1)}%) vs full; runtime savings unmeasured`);
+        }
+        else {
+            lines.push("  planned reduction: unavailable (no discovered tests); runtime savings unmeasured");
+        }
         lines.push(`  graph: ${result.graph.nodes} nodes, confidence ${result.graph.effectiveConfidence ?? result.graph.confidence}`);
         if (result.fallbackReasons.length > 0) {
             lines.push(`  fallback: ${result.fallbackReasons.join("; ")}`);
@@ -234,16 +248,93 @@ function summarise(report) {
             lines.push("  blind spot: this repository declares a test framework and DiffCI discovered none of its tests");
         }
     }
-    lines.push(`  non-interference: worktree ${report.nonInterference.worktreeUnchanged ? "unchanged" : "CHANGED - report this"}, report written ${report.nonInterference.reportWrittenOutsideRepository ? "outside" : "INSIDE"} the checkout`);
+    lines.push(`  non-interference${executionFollows ? " (analysis phase)" : ""}: worktree ${report.nonInterference.worktreeUnchanged ? "unchanged" : "CHANGED - report this"}, report written ${report.nonInterference.reportWrittenOutsideRepository ? "outside" : "INSIDE"} the checkout`);
     const blocking = report.nonInterference.workflowFindings.filter((f) => f.severity === "BLOCKING");
     if (blocking.length > 0) {
         lines.push(`  workflow: ${blocking.length} blocking finding(s) - this installation CAN affect other jobs:`);
         for (const finding of blocking)
             lines.push(formatFinding(finding));
     }
-    lines.push("  DiffCI changed nothing: no test was run, skipped, cancelled or re-ordered by this step.");
+    lines.push(executionFollows
+        ? "  Analysis phase complete; check runs test commands only when a valid comparison is available."
+        : "  DiffCI changed nothing: no test was run, skipped, cancelled or re-ordered by this step.");
     return lines.join("\n");
 }
+async function runCheck(flags, env) {
+    const repoPath = resolve(stringFlag(flags, "repo") ?? env.GITHUB_WORKSPACE ?? process.cwd());
+    const reportPath = resolve(stringFlag(flags, "out") ?? defaultReportPath(env));
+    const observationCode = await runObserve({ ...flags, out: reportPath, quiet: true, "no-send": true }, env);
+    if (observationCode !== 0)
+        return observationCode;
+    const observation = JSON.parse(readFileSync(reportPath, "utf8"));
+    const print = (message) => { if (flags.quiet !== true && flags.json !== true)
+        console.log(message); };
+    print(summarise(observation, true));
+    print(`  observation report: ${reportPath}`);
+    if (observation.status !== "OBSERVED" || !observation.result) {
+        print("  timing: unavailable because analysis did not complete");
+        if (flags.json === true)
+            console.log(JSON.stringify({ observation, timing: null }, null, 2));
+        return flags["fail-on-error"] === true ? 1 : 0;
+    }
+    const checkedOutHead = execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoPath, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (observation.commitRange?.headSha !== checkedOutHead) {
+        const reason = "the analyzed head is not checked out; timing would execute a different revision";
+        print(`  timing: unavailable (${reason})`);
+        if (flags.json === true)
+            console.log(JSON.stringify({ observation, timing: null, reason }, null, 2));
+        return 1;
+    }
+    const inferred = inferFullCommand(repoPath);
+    if (!inferred.command) {
+        print(`  timing: unavailable (${inferred.reason})`);
+        if (flags.json === true)
+            console.log(JSON.stringify({ observation, timing: null, reason: inferred.reason }, null, 2));
+        return 0;
+    }
+    print(`  full command: ${inferred.command} (${inferred.reason})`);
+    const timeoutMs = numberFlag(flags, "timeout-ms") ?? 30 * 60 * 1000;
+    const tailBytes = numberFlag(flags, "tail-bytes") ?? 12_000;
+    const savingsPath = reportPath.endsWith(".json") ? reportPath.slice(0, -5) + "-savings.json" : reportPath + ".savings.json";
+    const markdownPath = savingsPath.replace(/\.json$/, ".md");
+    if (observation.result.mode === "FULL") {
+        print("  running full validation...");
+        const full = measureCommand(inferred.command, { cwd: repoPath, timeoutMs, tailBytes });
+        writeFileSync(savingsPath, `${JSON.stringify({ schema: "diffci.fullValidation.v1", observationReportPath: reportPath, full }, null, 2)}\n`, "utf8");
+        print(full.exitCode === 0 && !full.timedOut
+            ? `DiffCI check: full validation passed in ${(full.wallMs / 1000).toFixed(2)}s; 0% measured reduction for this commit`
+            : `DiffCI check: full validation failed (exit ${String(full.exitCode)}); savings unavailable`);
+        print(`  execution report: ${savingsPath}`);
+        if (flags.json === true)
+            console.log(JSON.stringify({ observation, full }, null, 2));
+        return full.exitCode === 0 && !full.timedOut ? 0 : 1;
+    }
+    if (observation.result.commandRefusalReason || observation.result.proposedCommands.length !== 1) {
+        const reason = observation.result.commandRefusalReason ?? "the selection has no single runnable command";
+        print(`  timing: unavailable (${reason})`);
+        if (flags.json === true)
+            console.log(JSON.stringify({ observation, timing: null, reason }, null, 2));
+        return 0;
+    }
+    print("  running full and selected validation...");
+    const savings = runVerifySavings({
+        full: inferred.command,
+        selectedFromReport: reportPath,
+        out: savingsPath,
+        markdown: markdownPath,
+        label: stringFlag(flags, "label") ?? basename(repoPath),
+        cwd: repoPath,
+        timeoutMs,
+        tailBytes,
+    });
+    writeVerifySavingsReport(savings, { out: savingsPath, markdown: markdownPath });
+    print(formatVerifySavingsSummary(savings));
+    print(`  savings report: ${savingsPath}`);
+    print(`  markdown: ${markdownPath}`);
+    if (flags.json === true)
+        console.log(JSON.stringify({ observation, savings }, null, 2));
+    return savings.comparison.fullCommandSucceeded && savings.comparison.selectedCommandSucceeded ? 0 : 1;
+}
 async function runObserve(flags, env) {
     const repoPath = resolve(typeof flags.repo === "string" ? flags.repo : env.GITHUB_WORKSPACE ?? process.cwd());
     const reportPath = resolve(typeof flags.out === "string" ? flags.out : defaultReportPath(env));
@@ -445,6 +536,14 @@ async function runPilot(flags, env) {
         console.log("DiffCI pilot stopped before timing because observation did not produce a selectable report.");
         return 1;
     }
+    if (observation.result?.mode === "FULL") {
+        console.log("DiffCI pilot: 0% planned test-file reduction on this commit (full validation required). No paired timing was run.");
+        return 0;
+    }
+    if (!observation.result?.proposedCommands.length || observation.result.commandRefusalReason) {
+        console.log("DiffCI pilot: no runnable selected command. No paired timing was run.");
+        return 1;
+    }
     const savings = runVerifySavings({
         full,
         selectedFromReport: observationPath,
@@ -462,12 +561,12 @@ async function runPilot(flags, env) {
     console.log(`  markdown: ${markdownPath}`);
     return savings.comparison.fullCommandSucceeded && savings.comparison.selectedCommandSucceeded ? 0 : 1;
 }
-const USAGE = `diffci - observation-only change-aware CI analysis
+const USAGE = `diffci - change-aware CI analysis and paired timing
 
 Usage:
   diffci init [--repo <path>] [--workflow] [--force]
-  diffci check [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
-               [--redact-paths] [--json] [--quiet] [--fail-on-error]
+  diffci check [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
+               [--redact-paths] [--json] [--quiet] [--fail-on-error] [--timeout-ms <ms>]
   diffci pilot --full <command> [--repo <path>] [--out-dir <dir>] [--label <name>]
   diffci observe [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
                  [--redact-paths] [--json] [--quiet] [--fail-on-error]
@@ -479,9 +578,9 @@ Usage:
   diffci version
 
 init writes AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, and diffci.config.json.
-check is the default AI-agent command: it is observe with sending disabled.
+check analyzes the change, runs inferred full and selected commands, and shows measured savings.
 pilot runs observe and verify-savings together, writing reports to ../diffci-output by default.
-observe analyses the checkout and writes one JSON report. It runs nothing and changes nothing.
+observe analyses the checkout and writes one JSON report. It runs nothing and changes nothing.
 verify-savings runs both commands and reports measured paired runtime; it is an opt-in pilot command.
 verify-workflow checks that the job running DiffCI cannot affect any other job, and exits 1 if it can.
 
@@ -502,7 +601,7 @@ async function main() {
             process.exitCode = runInit(flags, env);
             return;
         case "check":
-            process.exitCode = await runObserve({ ...flags, "no-send": true }, env);
+            process.exitCode = await runCheck(flags, env);
             return;
         case "pilot":
             process.exitCode = await runPilot(flags, env);

package/dist-client/src/client/full-command.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readRepositoryConfig } from "@diffci.com/core/repo/repo-config";
+/** Choose the repository's conventional full test command without executing anything. */
+export function inferFullCommand(repoPath) {
+    if (existsSync(join(repoPath, "pom.xml"))) {
+        const config = readRepositoryConfig(repoPath);
+        if (config.configurationError)
+            return { reason: `DiffCI configuration error: ${config.configurationError}` };
+        const goal = config.maven?.goal ?? "test";
+        const profiles = config.maven?.profiles?.length ? ` -P ${config.maven.profiles.join(",")}` : "";
+        return {
+            command: `mvn${profiles} ${goal}`,
+            reason: config.maven ? "Maven goal and profiles from DiffCI configuration" : "Maven default goal: test; confirm this matches CI",
+        };
+    }
+    const packagePath = join(repoPath, "package.json");
+    if (existsSync(packagePath)) {
+        let pkg;
+        try {
+            pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+        }
+        catch {
+            return { reason: "package.json could not be read" };
+        }
+        if (typeof pkg.scripts?.test !== "string" || !pkg.scripts.test.trim()) {
+            return { reason: "package.json has no test script" };
+        }
+        const manager = typeof pkg.packageManager === "string" ? pkg.packageManager.split("@")[0] : undefined;
+        if (manager === "pnpm" || manager === "yarn" || manager === "bun") {
+            return { command: `${manager} test`, reason: `package.json test script via ${manager}` };
+        }
+        if (manager && manager !== "npm")
+            return { reason: `unsupported package manager: ${manager}` };
+        if (existsSync(join(repoPath, "pnpm-lock.yaml")))
+            return { command: "pnpm test", reason: "package.json test script with pnpm lockfile" };
+        if (existsSync(join(repoPath, "yarn.lock")))
+            return { command: "yarn test", reason: "package.json test script with Yarn lockfile" };
+        if (existsSync(join(repoPath, "bun.lock")) || existsSync(join(repoPath, "bun.lockb")))
+            return { command: "bun test", reason: "package.json test script with Bun lockfile" };
+        return { command: "npm test", reason: "package.json test script" };
+    }
+    if (existsSync(join(repoPath, "go.mod")))
+        return { command: "go test ./...", reason: "root Go module" };
+    return { reason: "no supported full test command could be inferred" };
+}

package/dist-client/src/client/mcp.js

@@ -6,7 +6,7 @@ const SERVER_INFO = { name: "diffci-mcp", version: "0.1.0" };
 const tools = [
     {
         name: "diffci_check",
-        description: "Run DiffCI's observation-only AI-agent validation command. It sends nothing by default and does not run, skip, cancel, or reorder tests.",
+        description: "Analyze the repository, run inferred full and selected test commands when available, and report paired runtime. Sends nothing to DiffCI Cloud.",
         inputSchema: {
             type: "object",
             properties: {

package/dist-client/src/client/verify-savings.js

@@ -33,7 +33,7 @@ function resolveSelection(options) {
         throw new Error("--selected <command> or --selected-from-report <path> is required");
     return { command: options.selected, source: "manual" };
 }
-function measureCommand(command, options) {
+export function measureCommand(command, options) {
     const startedAt = new Date().toISOString();
     const started = Date.now();
     const shellCommand = process.platform === "win32" ? "powershell.exe" : "sh";
@@ -69,6 +69,7 @@ export function buildVerifySavingsReport(input) {
     const overhead = input.analysisOverheadMs ?? 0;
     const netSelectedMs = input.selected.wallMs + overhead;
     const deltaMs = input.full.wallMs - netSelectedMs;
+    const grossPercentChange = input.full.wallMs > 0 ? ((input.full.wallMs - input.selected.wallMs) / input.full.wallMs) * 100 : 0;
     const percentChange = input.full.wallMs > 0 ? (deltaMs / input.full.wallMs) * 100 : 0;
     const fullCommandSucceeded = input.full.exitCode === 0 && !input.full.timedOut;
     const selectedCommandSucceeded = input.selected.exitCode === 0 && !input.selected.timedOut;
@@ -100,6 +101,7 @@ export function buildVerifySavingsReport(input) {
             selectedWallMs: input.selected.wallMs,
             netSelectedMs,
             deltaMs,
+            grossPercentChange,
             percentChange,
             selectedCommandSucceeded,
             fullCommandSucceeded,
@@ -144,6 +146,7 @@ ${!report.comparison.fullCommandSucceeded || !report.comparison.selectedCommandS
 | --- | ---: |
 | Full runtime | ${formatMs(report.comparison.fullWallMs)} |
 | Selected runtime | ${formatMs(report.comparison.selectedWallMs)} |
+| Test execution change vs full | ${formatPercent(report.comparison.grossPercentChange)} |
 | DiffCI analysis overhead | ${overhead} |
 | Net selected runtime | ${formatMs(report.comparison.netSelectedMs)} |
 | Delta vs full | ${formatMs(report.comparison.deltaMs)} ${deltaLabel} |
@@ -191,7 +194,10 @@ export function formatVerifySavingsSummary(report) {
             (report.comparison.missedFailureSignal ? "\n  warning: full failed while selected passed; inspect outputs before claiming safety" : "");
     }
     const lines = [
-        `DiffCI verify-savings: ${report.comparison.deltaMs >= 0 ? "faster" : "slower"} by ${formatMs(Math.abs(report.comparison.deltaMs))}`,
+        `DiffCI verify-savings: test execution ${Math.abs(report.comparison.grossPercentChange).toFixed(1)}% ${report.comparison.grossPercentChange >= 0 ? "faster" : "slower"} in this paired run`,
+        `  full: ${formatMs(report.comparison.fullWallMs)}`,
+        `  selected: ${formatMs(report.comparison.selectedWallMs)} + analysis ${formatMs(report.analysisOverheadMs ?? 0)} = ${formatMs(report.comparison.netSelectedMs)}`,
+        `  net including analysis: ${Math.abs(report.comparison.percentChange).toFixed(1)}% ${report.comparison.deltaMs >= 0 ? "faster" : "slower"} (${formatMs(Math.abs(report.comparison.deltaMs))} ${report.comparison.deltaMs >= 0 ? "saved" : "added"})`,
     ];
     if (report.comparison.missedFailureSignal) {
         lines.push("  warning: full failed while selected passed; inspect outputs before claiming safety");

package/docs/agent-adoption-kit.md

@@ -23,8 +23,9 @@ Then ask your coding agent to run:
 npx @diffci.com/diffci@latest check
 ```
 
-DiffCI is observation-only by default: it analyzes the change, writes a report outside the checkout,
-sends nothing unless explicitly configured, and does not run, skip, cancel, or reorder tests.
+DiffCI check analyzes the change and runs inferred full and selected test commands to measure time.
+It writes reports outside the checkout and sends nothing. Test commands may write generated files.
+Use `observe --no-send` for analysis only.
 ```
 
 ## Agent Instruction Snippet
@@ -71,11 +72,11 @@ Title: Add optional DiffCI instructions for AI coding agents
 
 This adds an optional instruction for coding agents to run DiffCI before marking changes PR-ready.
 
-DiffCI is observation-only by default:
+DiffCI check runs a paired test comparison when commands can be inferred:
 
 - it analyzes the change and writes a local report;
 - it sends nothing without explicit configuration;
-- it does not run, skip, cancel, or reorder tests;
+- it runs full and selected test commands but does not skip required CI;
 - the repository's existing required CI remains authoritative.
 
 Default command:

package/docs/agent-adoption-targets.md

@@ -46,7 +46,7 @@ Before marking changes PR-ready, run:
 npx @diffci.com/diffci@latest check
 ```
 
-DiffCI is observation-only by default: it analyzes the change, writes a report outside the checkout,
-sends nothing unless explicitly configured, and does not run, skip, cancel, or reorder tests. Existing
-required CI remains authoritative.
+DiffCI check analyzes the change and runs inferred full and selected test commands to measure time.
+It writes reports outside the checkout and sends nothing. Test commands may write generated files.
+Existing required CI remains authoritative; use `observe --no-send` for analysis only.
 ```

package/docs/ai-agents.md

@@ -3,14 +3,15 @@
 DiffCI is the default CI/CD validation lens agents can run before proposing, committing, or opening a
 pull request.
 
-The safe default command is:
+The default command is:
 
 ```bash
 npx @diffci.com/diffci@latest check
 ```
 
-`check` is an alias for `observe --no-send`. It analyzes the change and prints a report summary without
-running tests, skipping tests, cancelling jobs, changing the checkout, or sending data to DiffCI Cloud.
+`check` analyzes the change and runs inferred full and selected test commands when possible. It
+prints paired runtime when both pass and sends nothing to DiffCI Cloud. Test commands may change
+the checkout. Use `observe --no-send` when you need analysis without running tests.
 
 ## Install Agent Instructions
 

package/docs/claude-code.md

@@ -12,6 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
-report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Use DiffCI before PR-ready answers. `check` analyzes the change and runs inferred full and selected
+test commands to measure time. It writes reports outside the checkout and sends nothing by default.
+Test commands may write generated files. Use `observe --no-send` for analysis only.
 Keep the repository's required checks authoritative.

package/docs/codex.md

@@ -12,6 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
-report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Use DiffCI before PR-ready answers. `check` analyzes the change and runs inferred full and selected
+test commands to measure time. It writes reports outside the checkout and sends nothing by default.
+Test commands may write generated files. Use `observe --no-send` for analysis only.
 Keep the repository's required checks authoritative.

package/docs/copilot.md

@@ -12,7 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready answers. `init` writes `.github/copilot-instructions.md`; `check` is
-observation-only: it analyzes the change, writes a report outside the checkout, sends nothing by
-default, and does not run, skip, cancel, or reorder tests. Keep the repository's required checks
-authoritative.
+Use DiffCI before PR-ready answers. `init` writes `.github/copilot-instructions.md`; `check`
+analyzes the change and runs inferred full and selected test commands to measure time. It sends
+nothing by default. Test commands may write generated files; use `observe --no-send` for analysis
+only. Keep the repository's required checks authoritative.

package/docs/cursor.md

@@ -12,7 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready changes. `init` writes `.cursor/rules/diffci.mdc`; `check` is
-observation-only: it analyzes the change, writes a report outside the checkout, sends nothing by
-default, and does not run, skip, cancel, or reorder tests. Keep the repository's required checks
-authoritative.
+Use DiffCI before PR-ready changes. `init` writes `.cursor/rules/diffci.mdc`; `check` analyzes the
+change and runs inferred full and selected test commands to measure time. It sends nothing by
+default. Test commands may write generated files; use `observe --no-send` for analysis only. Keep
+the repository's required checks authoritative.

package/docs/grok.md

@@ -12,6 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
-report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Use DiffCI before PR-ready answers. `check` analyzes the change and runs inferred full and selected
+test commands to measure time. It writes reports outside the checkout and sends nothing by default.
+Test commands may write generated files. Use `observe --no-send` for analysis only.
 Keep the repository's required checks authoritative.

package/docs/mcp.md

@@ -10,12 +10,12 @@ npx -p @diffci.com/diffci@latest diffci-mcp
 
 Available tools:
 
-- `diffci_check` - runs `diffci check`, the observation-only AI-agent validation command.
+- `diffci_check` - runs `diffci check`, including inferred full and selected test commands.
 - `diffci_init` - runs `diffci init` to seed agent instruction files.
 - `diffci_verify_workflow` - runs `diffci verify-workflow` to check non-interference.
 
-The MCP server delegates to the same open-source CLI. `diffci_check` sends nothing by default and does
-not run, skip, cancel, or reorder tests.
+The MCP server delegates to the same open-source CLI. `diffci_check` sends nothing to DiffCI Cloud,
+but it runs test commands when it can infer them. Use the CLI's `observe --no-send` for analysis only.
 
 Keep required project CI authoritative. DiffCI output is a validation lens, not permission to skip
 required checks.

package/docs/npm-adoption.md

@@ -59,6 +59,12 @@ Ask maintainers for a small, reversible experiment:
 Use this when a maintainer asks whether selecting fewer tests would actually make their CI faster.
 This is a paired local measurement, not a production-savings claim.
 
+For one command that infers the full test command and prints the measured percentage when both runs
+pass, use `npx @diffci.com/diffci@latest check` from the repository root. For Maven, `check` reads
+the goal and profiles from `diffci.json` when present; otherwise it uses `mvn test` and says that
+the default may differ from CI. Run it on the intended CI runner: timings from another machine are
+not CI savings. A full-validation fallback runs the full command once and reports 0% reduction.
+
 Step 1: create an observation report without sending it anywhere.
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffci.com/diffci",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "description": "DiffCI - deterministic change-aware CI planning",
   "keywords": [
     "ci",