@diffci.com/diffci 0.1.3 → 0.1.5

package/README.md

@@ -2,30 +2,73 @@
 
 [![npm version](https://img.shields.io/npm/v/@diffci.com/diffci.svg)](https://www.npmjs.com/package/@diffci.com/diffci)
 [![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%40v1-blue)](https://github.com/DiffCI/DiffCI.com)
+[![GitHub Action](https://img.shields.io/badge/action-DiffCI%2FDiffCI.com%40v0.1.4-blue)](https://github.com/DiffCI/DiffCI.com)
 
-DiffCI is a deterministic, change-aware CI planner: given a commit or PR, it builds a real TypeScript
-dependency graph, computes what's actually reachable from the changed files, and proposes which CI
-tasks/tests could safely be skipped - without ever modifying production CI behavior itself. Every mode
-this repository currently implements is observe-and-compare only; nothing here can cancel, skip, or block
-a real CI run.
+**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 CLI and Action are observation-only.
 
-Try it in shadow mode:
+From an existing repository checkout, with Node.js 22.5+ and Git installed:
 
 ```bash
-npx @diffci.com/diffci@latest observe
-npx @diffci.com/diffci@latest verify-workflow
+npx @diffci.com/diffci@latest observe --no-send
 ```
 
-Or install it as a non-blocking GitHub Action:
+**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
+affected observations before using them as opportunity evidence; see the
+[historical validation](docs/evidence/growth-history-01/README.md) and
+[release qualification](docs/evidence/release-0.1.4/README.md).
+
+The local default compares `HEAD` with its first parent; both commits must be available. For a specific
+comparison, add `--base <base-sha> --head <head-sha>`. DiffCI prints the selection, fallback reasons,
+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.
+
+**Measured example:** a controlled Cal.com replay showed **44.2% net reduction in a job-equivalent
+install + pretest + test workload**, including analysis overhead. This is one sandbox comparison,
+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.
+
+For a self-serve paired runtime check, run `observe` first and then run `verify-savings` against the
+observation report. It compares your normal full command with
+DiffCI's proposed selected command and writes JSON plus Markdown evidence; see
+[`docs/npm-adoption.md`](docs/npm-adoption.md#self-serve-runtime-pilot).
+
+## Observe in GitHub Actions
+
+Save this as `.github/workflows/diffci.yml` to add a dedicated, non-blocking observation job:
 
 ```yaml
-- uses: DiffCI/DiffCI.com@v1
+name: DiffCI observation
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  diffci:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: DiffCI/DiffCI.com@dee4f7b938a7720d077c1124ef2ea050aa2625d6
 ```
 
-The promise is deliberately narrow: DiffCI observes your CI and reports what it would have selected.
-It does not skip tests, cancel jobs, change required checks, or send reports anywhere unless you
-explicitly configure an endpoint and token.
+Then check the workflow locally with `npx @diffci.com/diffci@latest verify-workflow`. Keep the observer
+out of required checks and other jobs' `needs` lists. The Action adds a job summary and a
+`diffci-observation` artifact to the run; it does not alter which tests your other jobs execute.
+The example pins release `v0.1.4` to its full commit SHA for reproducibility.
+
+The CLI sends no report with `--no-send`. The Action uploads a GitHub artifact by default; sending to
+DiffCI's hosted service requires an explicitly configured endpoint and token.
+[Installation details](docs/distribution.md) · [Seven-day pilot](docs/shadow-pilot-runbook.md)
+
+## Project background
 
 **This repository moved out of the [DentalPresence.in](https://github.com/adityankale190895/DentalPresence.in)
 monorepo** (previously `diffci/` there) into its own repo on 2026-08-21, once the project outgrew being a
@@ -136,7 +179,7 @@ npm run research:sandbox:deploy
 DiffCI is intended to be installable as infrastructure, not only as a hosted shadow experiment:
 
 ```yaml
-- uses: DiffCI/DiffCI.com@v1
+- uses: DiffCI/DiffCI.com@dee4f7b938a7720d077c1124ef2ea050aa2625d6
 ```
 
 ```bash

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

@@ -14,6 +14,7 @@
  *
  * Commands:
  *   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
  *   version            print the observer version
  *
@@ -30,6 +31,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { observe, isInsideRepository } from "./observe.js";
 import { submitObservation } from "./submit.js";
+import { formatVerifySavingsSummary, runVerifySavings, writeVerifySavingsReport } from "./verify-savings.js";
 import { auditWorkflows, isNonInterfering } from "./workflow-guard.js";
 function parseArgs(argv) {
     const args = argv.slice(2);
@@ -234,16 +236,70 @@ function runVerifyWorkflow(flags, env) {
     console.log("\nBlocking findings above: as written, this installation CAN change what the rest of CI does.");
     return 1;
 }
+function stringFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+function numberFlag(flags, name) {
+    const value = stringFlag(flags, name);
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        throw new Error(`--${name} must be a non-negative number`);
+    return parsed;
+}
+function parseVerifySavingsOptions(flags, env) {
+    const full = stringFlag(flags, "full");
+    const selected = stringFlag(flags, "selected");
+    const selectedFromReport = stringFlag(flags, "selected-from-report");
+    const out = stringFlag(flags, "out");
+    if (!full)
+        throw new Error("--full <command> is required");
+    if (!selected && !selectedFromReport)
+        throw new Error("--selected <command> or --selected-from-report <path> is required");
+    if (selected && selectedFromReport)
+        throw new Error("pass only one of --selected or --selected-from-report");
+    if (!out)
+        throw new Error("--out <path> is required");
+    const markdown = stringFlag(flags, "markdown");
+    return {
+        full,
+        selected,
+        selectedFromReport: selectedFromReport ? resolve(selectedFromReport) : undefined,
+        out: resolve(out),
+        markdown: markdown ? resolve(markdown) : undefined,
+        label: stringFlag(flags, "label"),
+        cwd: resolve(stringFlag(flags, "repo") ?? env.GITHUB_WORKSPACE ?? process.cwd()),
+        timeoutMs: numberFlag(flags, "timeout-ms") ?? 30 * 60 * 1000,
+        analysisOverheadMs: numberFlag(flags, "analysis-overhead-ms"),
+        tailBytes: numberFlag(flags, "tail-bytes") ?? 12_000,
+    };
+}
+function runVerifySavingsCommand(flags, env) {
+    const options = parseVerifySavingsOptions(flags, env);
+    const report = runVerifySavings(options);
+    writeVerifySavingsReport(report, { out: options.out, markdown: options.markdown });
+    console.log(formatVerifySavingsSummary(report));
+    console.log(`  report: ${options.out}`);
+    if (options.markdown)
+        console.log(`  markdown: ${options.markdown}`);
+    return report.comparison.fullCommandSucceeded && report.comparison.selectedCommandSucceeded ? 0 : 1;
+}
 const USAGE = `diffci - observation-only change-aware CI analysis
 
 Usage:
   diffci observe [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
                  [--redact-paths] [--json] [--quiet] [--fail-on-error]
                  [--api-url <url> --api-token <token>] [--no-send]
+  diffci verify-savings --repo <path> --full <command>
+                         (--selected <command> | --selected-from-report <file>)
+                         --out <file> [--markdown <file>] [--label <name>]
   diffci verify-workflow [--repo <path>]
   diffci version
 
 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.
 
 The report is sent only when both --api-url and --api-token are given (or DIFFCI_API_URL and
@@ -262,6 +318,9 @@ async function main() {
         case "observe":
             process.exitCode = await runObserve(flags, env);
             return;
+        case "verify-savings":
+            process.exitCode = runVerifySavingsCommand(flags, env);
+            return;
         case "verify-workflow":
             process.exitCode = runVerifyWorkflow(flags, env);
             return;

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

@@ -0,0 +1,193 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+function tail(value, bytes) {
+    if (Buffer.byteLength(value, "utf8") <= bytes)
+        return value;
+    return value.slice(-bytes);
+}
+function readSelectionFromObservation(path) {
+    const absolutePath = resolve(path);
+    const parsed = JSON.parse(readFileSync(absolutePath, "utf8"));
+    if (parsed.status !== "OBSERVED")
+        throw new Error(`--selected-from-report requires an OBSERVED report; got ${String(parsed.status)}`);
+    const command = Array.isArray(parsed.result?.proposedCommands) && typeof parsed.result.proposedCommands[0] === "string"
+        ? parsed.result.proposedCommands[0]
+        : undefined;
+    if (!command)
+        throw new Error("--selected-from-report did not contain result.proposedCommands[0]");
+    const selectedTests = Array.isArray(parsed.result?.selectedTests) ? parsed.result.selectedTests : undefined;
+    return {
+        command,
+        source: "diffci-observation",
+        observationReportPath: absolutePath,
+        selectedTestCount: selectedTests?.length,
+        totalTestCount: typeof parsed.result?.totalTestCount === "number" ? parsed.result.totalTestCount : undefined,
+        analysisOverheadMs: typeof parsed.timings?.totalMs === "number" ? parsed.timings.totalMs : undefined,
+    };
+}
+function resolveSelection(options) {
+    if (options.selectedFromReport)
+        return readSelectionFromObservation(options.selectedFromReport);
+    if (!options.selected)
+        throw new Error("--selected <command> or --selected-from-report <path> is required");
+    return { command: options.selected, source: "manual" };
+}
+function measureCommand(command, options) {
+    const startedAt = new Date().toISOString();
+    const started = Date.now();
+    const shellCommand = process.platform === "win32" ? "powershell.exe" : "sh";
+    const shellArgv = process.platform === "win32" ? ["-NoProfile", "-NonInteractive", "-Command", command] : ["-c", command];
+    const result = spawnSync(shellCommand, shellArgv, {
+        cwd: options.cwd,
+        encoding: "utf8",
+        timeout: options.timeoutMs,
+        maxBuffer: 256 * 1024 * 1024,
+        shell: false,
+        env: {
+            ...process.env,
+            CI: "1",
+            FORCE_COLOR: "0",
+            COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
+            npm_config_yes: "true",
+        },
+    });
+    const finishedAt = new Date().toISOString();
+    return {
+        command,
+        exitCode: result.status,
+        signal: result.signal ?? null,
+        timedOut: result.error?.code === "ETIMEDOUT",
+        startedAt,
+        finishedAt,
+        wallMs: Date.now() - started,
+        stdoutTail: tail(result.stdout ?? "", options.tailBytes),
+        stderrTail: tail(result.stderr ?? "", options.tailBytes),
+    };
+}
+export function buildVerifySavingsReport(input) {
+    const overhead = input.analysisOverheadMs ?? 0;
+    const netSelectedMs = input.selected.wallMs + overhead;
+    const deltaMs = input.full.wallMs - netSelectedMs;
+    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;
+    const missedFailureSignal = !fullCommandSucceeded && selectedCommandSucceeded;
+    const notes = [
+        "This is paired runtime evidence, not a production-savings claim.",
+        "Full and selected commands were run sequentially in the same checkout.",
+        input.analysisOverheadMs === undefined
+            ? "No analysis overhead was provided, so net selected runtime equals selected command runtime."
+            : "Net selected runtime includes DiffCI analysis overhead.",
+    ];
+    if (missedFailureSignal)
+        notes.push("Full failed while selected passed; inspect outputs before treating the selection as safe.");
+    return {
+        schema: "diffci.verifySavings.v1",
+        producedAt: input.producedAt ?? new Date().toISOString(),
+        label: input.label,
+        cwd: input.cwd,
+        timeoutMs: input.timeoutMs,
+        analysisOverheadMs: input.analysisOverheadMs,
+        selectionSource: input.selection.source,
+        observationReportPath: input.selection.observationReportPath,
+        selectedTestCount: input.selection.selectedTestCount,
+        totalTestCount: input.selection.totalTestCount,
+        full: input.full,
+        selected: input.selected,
+        comparison: {
+            fullWallMs: input.full.wallMs,
+            selectedWallMs: input.selected.wallMs,
+            netSelectedMs,
+            deltaMs,
+            percentChange,
+            selectedCommandSucceeded,
+            fullCommandSucceeded,
+            missedFailureSignal,
+        },
+        notes,
+    };
+}
+function formatMs(ms) {
+    if (Math.abs(ms) < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+}
+function formatPercent(value) {
+    return `${value >= 0 ? "+" : ""}${value.toFixed(1)}%`;
+}
+export function renderVerifySavingsMarkdown(report) {
+    const deltaLabel = report.comparison.deltaMs >= 0 ? "faster" : "slower";
+    const overhead = report.analysisOverheadMs === undefined ? "not provided" : formatMs(report.analysisOverheadMs);
+    const title = report.label ? `# DiffCI Verify Savings: ${report.label}` : "# DiffCI Verify Savings";
+    const warning = report.comparison.missedFailureSignal
+        ? "\n> WARNING: Full failed while selected passed. Do not treat this selected command as safe until the full-run failure is understood.\n"
+        : "";
+    const selectionCounts = report.selectedTestCount !== undefined && report.totalTestCount !== undefined
+        ? `\nSelected tests: ${report.selectedTestCount} of ${report.totalTestCount}\n`
+        : "";
+    return `${title}
+
+Produced at: ${report.producedAt}
+Repository label: ${report.label ?? "not provided"}
+Selection source: ${report.selectionSource}
+${selectionCounts}${warning}
+
+This report compares a full command with a selected command on the same checkout. It is measured pilot evidence, not a production-savings claim.
+
+## Result
+
+| Measure | Value |
+| --- | ---: |
+| Full runtime | ${formatMs(report.comparison.fullWallMs)} |
+| Selected runtime | ${formatMs(report.comparison.selectedWallMs)} |
+| DiffCI analysis overhead | ${overhead} |
+| Net selected runtime | ${formatMs(report.comparison.netSelectedMs)} |
+| Delta vs full | ${formatMs(report.comparison.deltaMs)} ${deltaLabel} |
+| Percent change vs full | ${formatPercent(report.comparison.percentChange)} |
+
+## Commands
+
+| Arm | Exit | Timed out | Command |
+| --- | ---: | --- | --- |
+| Full | ${report.full.exitCode ?? "signal"} | ${report.full.timedOut ? "yes" : "no"} | \`${report.full.command.replaceAll("|", "\\|")}\` |
+| Selected | ${report.selected.exitCode ?? "signal"} | ${report.selected.timedOut ? "yes" : "no"} | \`${report.selected.command.replaceAll("|", "\\|")}\` |
+
+## Interpretation Notes
+
+${report.notes.map((note) => `- ${note}`).join("\n")}
+`;
+}
+function writeText(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, value, "utf8");
+}
+export function runVerifySavings(options) {
+    const selection = resolveSelection(options);
+    const analysisOverheadMs = options.analysisOverheadMs ?? selection.analysisOverheadMs;
+    const full = measureCommand(options.full, options);
+    const selected = measureCommand(selection.command, options);
+    return buildVerifySavingsReport({
+        label: options.label,
+        cwd: options.cwd,
+        timeoutMs: options.timeoutMs,
+        analysisOverheadMs,
+        selection,
+        full,
+        selected,
+    });
+}
+export function writeVerifySavingsReport(report, paths) {
+    writeText(paths.out, `${JSON.stringify(report, null, 2)}\n`);
+    if (paths.markdown)
+        writeText(paths.markdown, renderVerifySavingsMarkdown(report));
+}
+export function formatVerifySavingsSummary(report) {
+    const lines = [
+        `DiffCI verify-savings: ${report.comparison.deltaMs >= 0 ? "faster" : "slower"} by ${formatMs(Math.abs(report.comparison.deltaMs))}`,
+    ];
+    if (report.comparison.missedFailureSignal) {
+        lines.push("  warning: full failed while selected passed; inspect outputs before claiming safety");
+    }
+    return lines.join("\n");
+}

package/dist-client/src/client/workflow-guard.js

@@ -101,6 +101,10 @@ function commandText(run) {
     return run
         .split("\n")
         .map((line) => line.replace(/(^|\s)#.*$/, "$1").replace(/[a-z][a-z0-9+.-]*:\/\/\S+/gi, " "))
+        // A literal npm registry tag removal neither installs nor invokes the observer. Match the
+        // entire line, with only a literal `|| true` allowed, so appended observer commands and shell
+        // substitutions still take the conservative inspection path. Other script lines remain intact.
+        .filter((line) => !/^\s*npm(?:\.cmd)?\s+dist-tag\s+(?:rm|remove)\s+@?[\w./-]+\s+[\w.-]+(?:\s*\|\|\s*true)?\s*$/.test(line))
         .join("\n");
 }
 /**

package/dist-client/src/repo/graph.js

@@ -551,7 +551,13 @@ export async function buildDependencyGraph(options = {}) {
     const entryPointPaths = new Set(profile.entryPoints.map((e) => e.path));
     const vueSources = contributions.some((item) => item.id === "vue")
         ? files.filter((file) => /\.[cm]?[jt]sx?$/.test(file)).map((file) => join(repoPath, file)) : [];
-    let { program, options: compilerOptions, resolvedViaProjectReferences } = createProgram(repoPath, profile.sourceRoots, vueSources);
+    // Compiler include/exclude controls typechecking, not the runner's test universe. Parse every
+    // discovered JS/TS test so source changes can reach tests outside the compiler's root files.
+    // Adding those tests only as leaf nodes silently loses their dependency edges (ky, 2026-09-19).
+    const testSources = profile.testFilePaths
+        .filter((file) => /\.[cm]?[jt]sx?$/.test(file))
+        .map((file) => join(repoPath, file));
+    let { program, options: compilerOptions, resolvedViaProjectReferences } = createProgram(repoPath, profile.sourceRoots, [...vueSources, ...testSources]);
     let moduleResolutionCache = ts.createModuleResolutionCache(repoPath, (x) => x, compilerOptions);
     const sourceFiles = program
         .getSourceFiles()
@@ -690,21 +696,8 @@ export async function buildDependencyGraph(options = {}) {
         adapterBlockers.push("Unresolved Vue dependencies require full validation");
     }
     profile.adapterBlockers = [...adapterBlockers];
-    // Nested-package test visibility (2026-08-24, biomejs/biome finding): `internalSourcePaths` above is
-    // strictly the TS PROGRAM's own file list (createProgram()'s `include`/nested-tsconfig-merged
-    // fileNames) - so a package whose own tsconfig deliberately excludes its test directory (a real,
-    // common pattern; confirmed verbatim on biome: `packages/@biomejs/js-api/tsconfig.json` has
-    // `"exclude": ["./tests", "./dist"], "include": ["./src"]`) NEVER contributes those files to the
-    // program, so they never became graph nodes and `totalTestsInGraph` stayed 0 even though
-    // `profile.testFilePaths` (the separate, tsconfig-agnostic glob walk in analyzer.ts's discoverTests())
-    // already found them correctly. Source-ROOT discovery itself was already correct (the 2026-08-21
-    // zod/trpc fallback already lists `packages`/`crates` as roots for exactly this monorepo shape) - the
-    // gap was narrower: the graph never incorporated what that walk found. Fix: union in any test file
-    // discoverTests() found that the TS program's own file list missed, as an ADDITIONAL leaf node
-    // (isTest true; no import edges - we have no real resolution info for a file the type-checker was
-    // never asked to see, so dependency-graph traversal through it is honestly absent, not guessed at).
-    // This does NOT add Rust visibility of any kind - testFilePaths only ever contains files already
-    // matched by the JS/TS test-file patterns; a `.rs` test is never in it and stays "unknown" as before.
+    // Keep adapter-provided test identities visible as well. JS/TS tests are parsed above; their
+    // imports must not be replaced by disconnected leaf nodes merely because tsconfig excludes them.
     for (const testPath of profile.testFilePaths) {
         if (!internalSourcePaths.has(testPath) && !assetPaths.has(testPath))
             internalSourcePaths.add(testPath);

package/docs/distribution.md

@@ -7,6 +7,45 @@ The product model is open core. The npm CLI and basic GitHub Action are the open
 DiffCI Cloud adds hosted history, organization dashboards, policies, managed operations, and support.
 See [`open-core-packaging.md`](open-core-packaging.md).
 
+## Channel strategy
+
+Reviewed 2026-09-19. These channels have different jobs in the same adoption path:
+
+| Channel | Role for DiffCI | Next step |
+| --- | --- | --- |
+| npm | Developer discovery and local evaluation of `@diffci.com/diffci` | Lead with `observe`, a sample report, and the observation-only contract. |
+| GitHub Action | Repeatable CI adoption | Use the dedicated, non-blocking job below and verify the workflow before a pilot. |
+| GitHub Marketplace | CI-specific discovery of the same Action | Confirm listing status and release requirements, then publish or improve its installation instructions. |
+| Tidelift | Potential package maintenance assurance and maintainer income | Pursue package acceptance using the existing submission packet; do not present support as active. |
+| Commercial DiffCI | Paid hosted history, analytics, team workflows, and managed operations | Validate demand with design partners and distinguish available services from future acceleration capabilities. |
+
+The Action is the integration; Marketplace is a discovery channel for that integration. GitHub documents
+Marketplace publication as a release-based process, so having `action.yml` alone does not establish
+that a listing is live. See [GitHub's publishing requirements](https://docs.github.com/en/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace).
+
+Prioritize npm and Action activation, then Marketplace discovery. Keep Tidelift outreach in parallel
+without making adoption dependent on acceptance or expected payments. Defer PyPI, Cargo, and Homebrew
+until user demand and a maintained installation experience justify each additional surface.
+
+Measure successful first reports, repositories with repeat observations, completed pilot reviews,
+and qualified commercial interest. Downloads and listing views alone do not demonstrate adoption.
+Use voluntary pilot feedback or explicitly configured hosted reporting for these measurements;
+local observation does not imply permission to collect telemetry.
+
+Suggested positioning:
+
+> Install DiffCI through npm or GitHub Actions to inspect what your CI could avoid running while
+> leaving CI execution unchanged. Explore hosted reports and shared history with the DiffCI team.
+
+Acceleration and managed infrastructure remain product directions unless a specific capability is
+available and validated. Potential savings in shadow reports are not realized customer savings.
+
+Tidelift's published payment policy allows individuals, for-profit organizations, and nonprofits to
+receive payments with a signed agreement. A nonprofit recipient is therefore not inherently required.
+Payment depends on factors including subscriber usage and package importance; this does not establish
+DiffCI's eligibility, acceptance, or income. See [Tidelift's payment policy](https://support.tidelift.com/hc/en-us/articles/4406294816916-How-we-pay-lifters)
+and the [DiffCI submission packet](tidelift-submission.md).
+
 ## GitHub App
 
 The DiffCI Shadow GitHub App is the lowest-friction research and design-partner path. It receives
@@ -29,10 +68,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: DiffCI/DiffCI.com@v1
+      - uses: DiffCI/DiffCI.com@dee4f7b938a7720d077c1124ef2ea050aa2625d6
 ```
 
-For the strongest supply-chain posture, pin the Action to a full commit SHA. `npx @diffci.com/diffci@latest verify-workflow`
+The example pins release `v0.1.4` to its full commit SHA. `npx @diffci.com/diffci@latest verify-workflow`
 checks that the job is dedicated, read-only, not required by other jobs, and unable to alter the rest
 of CI.
 

package/docs/npm-adoption.md

@@ -0,0 +1,121 @@
+# Promoting the DiffCI npm Package
+
+DiffCI's npm package should be promoted as a low-risk CI observer:
+
+> DiffCI observes your CI and reports which tests it would have selected, without skipping, cancelling,
+> or changing any job.
+
+## Install
+
+Use the npm CLI when someone wants to try DiffCI locally or inside an existing CI step:
+
+```bash
+npx @diffci.com/diffci@latest observe
+npx @diffci.com/diffci@latest verify-workflow
+```
+
+Use the GitHub Action when someone wants the normal non-blocking CI installation:
+
+```yaml
+jobs:
+  diffci:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: DiffCI/DiffCI.com@dee4f7b938a7720d077c1124ef2ea050aa2625d6
+```
+
+## Outreach Copy
+
+Short version:
+
+> I built DiffCI as an observation-only CI dependency. It looks at a PR diff and reports which tests it
+> would have selected, but it never skips, cancels, or changes CI. You can run it with
+> `npx @diffci.com/diffci@latest observe` or as a non-blocking GitHub Action. I am looking for OSS
+> repos willing to run it in shadow mode for a week.
+
+Issue/PR version:
+
+> Would you be open to running DiffCI in shadow mode for a week? It adds one non-blocking job that
+> observes each PR/push and writes a report artifact. It does not alter required checks, skip tests,
+> cancel jobs, or send data anywhere unless you explicitly configure an endpoint/token.
+
+## Pilot Ask
+
+Ask maintainers for a small, reversible experiment:
+
+- Run one non-blocking DiffCI job for seven days.
+- Keep all existing CI behavior unchanged.
+- Share the report artifacts or a summary of whether DiffCI found avoidable test work.
+- Remove the job at any time if it is noisy, slow, or unhelpful.
+
+## Self-Serve Runtime Pilot
+
+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.
+
+Step 1: create an observation report without sending it anywhere.
+
+```bash
+npx @diffci.com/diffci@latest observe --no-send --out ./diffci-observation.json
+```
+
+Step 2: run the paired pilot.
+
+```bash
+npx @diffci.com/diffci@latest verify-savings \
+  --label owner/repo \
+  --repo /path/to/their/repo \
+  --full "npm test" \
+  --selected-from-report /path/to/their/repo/diffci-observation.json \
+  --out ./diffci-verify-savings.json \
+  --markdown ./diffci-verify-savings.md
+```
+
+What the report means:
+
+- Full runtime is measured from `--full`.
+- Selected runtime is measured from DiffCI's proposed command in the observation report.
+- DiffCI analysis overhead is imported from `timings.totalMs` in the observation report unless
+  `--analysis-overhead-ms` is provided.
+- Net selected runtime is selected runtime plus analysis overhead.
+- If the full command fails while the selected command passes, the report is a safety warning, not a
+  savings result.
+
+If the proposed command needs adjustment for the repository's runner, pass the selected command
+manually:
+
+```bash
+npx @diffci.com/diffci@latest verify-savings \
+  --label owner/repo \
+  --repo /path/to/their/repo \
+  --full "pnpm test" \
+  --selected "pnpm test packages/a/src/a.test.ts packages/b/src/b.test.ts" \
+  --analysis-overhead-ms 1200 \
+  --out ./diffci-verify-savings.json \
+  --markdown ./diffci-verify-savings.md
+```
+
+Common command shapes:
+
+```bash
+--full "npm test"
+--full "pnpm test"
+--full "yarn test"
+--selected "npx vitest run path/to/file.test.ts"
+--selected "npx jest path/to/file.test.ts"
+--selected "node --test path/to/file.test.mjs"
+```
+
+## Trust Points
+
+- Published as `@diffci.com/diffci` on npm.
+- Stable `latest` release is signed with npm provenance.
+- The package boundary is checked by `npm run check:oss-boundary`.
+- The default observer writes a local report and sends nothing without both `DIFFCI_API_URL` and
+  `DIFFCI_TOKEN`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffci.com/diffci",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "DiffCI - deterministic change-aware CI planning",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -23,6 +23,7 @@
     "dist-client/src/repo",
     "README.md",
     "docs/distribution.md",
+    "docs/npm-adoption.md",
     "docs/language-support.md",
     "SECURITY.md",
     "SUPPORT.md",
@@ -78,6 +79,7 @@
     "validation:status": "tsx scripts/diffci-validation-cli.ts status",
     "validation:collect": "tsx scripts/diffci-validation-cli.ts collect",
     "dogfood:compare": "tsx scripts/dogfood-compare.ts",
+    "verify:savings-pilot": "tsx scripts/verify-savings-pilot.ts",
     "test:calibration": "tsx --test \"tests/scripts/harness-calibration.test.ts\" \"tests/scripts/compute-usage.test.ts\"",
     "agent:equivalence": "tsx scripts/agent-equivalence.ts",
     "dogfood:economics": "tsx scripts/dogfood-economics.ts",