@vyuhlabs/dxkit 2.13.3 → 2.15.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-06-22
+
+### Fixed — ref-based guardrail no longer false-blocks on `secret-hmac`
+
+In ref-based mode (the default for public repos), dxkit mints a locator-less
+`secret-hmac` companion alongside each located `secret` for cross-file
+relocation matching. On a fresh or shallow checkout the two sides of the diff
+can derive different salts, so the companions never match and read as net-new —
+a **false block**, even though the located `secret` twins match correctly.
+`secret-hmac` now joins `duplication` and `test-gap` in the set of kinds
+excluded from the ref-based diff (they can't be gathered comparably across a
+detached worktree). The located `secret` kind still gates net-new credentials;
+only the redundant companion is dropped. **Committed modes are unaffected.**
+
+### Added — opt-in `--incremental` for `guardrail check`
+
+`vyuh-dxkit guardrail check --incremental` scopes the gather to the analyzers
+the active policy can actually block on (reusing the loop Stop-gate's
+`scopeForPolicy`) and, in ref-based mode, scopes semgrep to the changed files
+on both sides. Same verdict, far less work — the check scales with PR size
+rather than repo size. **Opt-in and verdict-preserving:** without the flag,
+behavior is byte-identical to 2.14; it falls back to a full scan whenever the
+changed set can't be computed completely. The CLI flag exposes what the loop
+Stop-gate already did internally, so a ref-based CI guardrail (or a hosted
+PR-gate) can run the fast path too.
+
+### Changed — positioning: two pillars (context + gate)
+
+- README hero, package description, and `--help` tagline now lead with both
+  pillars: **"a deterministic stop condition and code-graph context layer for
+  AI coding agents."** The README opening + "What dxkit does" foreground the
+  code graph (callers, callees, blast radius) the agent uses *while making a
+  change*, then the deterministic stop-gate that blocks net-new regressions
+  *before it exits* — so the graph is no longer undersold as a footnote.
+
+## [2.14.0] - 2026-06-22
+
+### Changed — the loop Stop-gate gathers far less work per stop
+
+After 2.13.3 made the gate cache-aware, two further optimizations cut what an
+unattended loop's `security-only` Stop-gate actually scans on every stop.
+Both are **opt-in** (only the loop Stop-gate enables them) and **verdict-
+preserving** — CI `baseline check`, `createBaseline`, and the `health` report
+are byte-identical and still render every warning. End-to-end on a 3,748-file
+repo with a realistic 2-file loop diff (separate processes), the security-only
+gather dropped from **42.8s → 11.3s (74%)** while still blocking the same
+net-new finding with identical blocking pairs.
+
+- **Preset-scoped gather.** A guardrail can only block on the finding kinds its
+  policy escalates, so a `security-only` posture no longer runs the analyzers
+  that feed only non-blockable kinds (jscpd, lint, coverage, cloc, test-gaps,
+  graphify, licenses). The scope is derived declaratively from the policy
+  (`scopeForPolicy`): a `full-debt` posture, CI, and `health` all resolve to
+  the full scan. A scoped result is partial by construction and never enters
+  the shared `AnalysisResult` cache. (~42.8s → 24.0s.)
+- **Incremental file-scoped scanning.** The current side's semgrep now scans
+  only the files that changed vs the baseline commit. Sound because semgrep is
+  intraprocedural — a net-new code finding can only appear in a file the diff
+  touched. The changed-file set is computed completely or falls back to a full
+  scan on any uncertainty (base unreachable, not a git repo), so a scan can
+  only ever over-cover, never under-cover. The ref/baseline side stays full.
+  (~24.0s → 11.3s.)
+
+Both behaviors are confined to the loop Stop-gate; nothing about the CI
+guardrail or the standalone reports changes.
+
 ## [2.13.3] - 2026-06-22
 
 ### Fixed — the loop Stop-gate no longer pays a full re-scan on every stop

package/README.md

@@ -1,11 +1,16 @@
 # dxkit
 
-**A deterministic Stop-gate for autonomous coding loops.**
+**A deterministic stop condition and code-graph context layer for AI coding agents.**
 
-Coding agents keep editing until they decide to stop. Tests and linters catch
-broken code, but they do not know whether the agent made the repo worse than
-the baseline. So loops can quietly ship new secrets, untested paths, and other
-detector-backed regressions, then report success.
+Autonomous coding loops face two control problems: orienting in the code while
+they make a change, and deciding whether that change made the repository worse
+before they stop.
+
+dxkit addresses both. While the agent works, it provides a code graph of
+callers, callees, blast radius, and the files a change touches. Then, when the
+agent tries to stop, dxkit baselines existing findings, reruns trusted checks,
+and blocks only net-new detector-backed regressions with a concrete repair
+reason.
 
 In our loop benchmark, vanilla Claude Code-style loops stopped with net-new
 debt in **11 of 16 runs**. A prompt that told the agent to self-check still
@@ -20,9 +25,10 @@ finding, and the agent repaired before stopping clean.
 
 dxkit does not reinvent detection. It runs trusted open source scanners
 (gitleaks, Semgrep, OSV, npm audit, and more), and it can ingest results from
-Snyk and CodeQL. What it adds is the piece those tools were not built for: a
-deterministic check, on every stop, of whether this change introduced a new
-finding compared with a baseline.
+Snyk and CodeQL. What dxkit adds is the agent-loop layer around those tools: a
+per-stop, baseline-relative verdict of whether this change introduced a new
+finding, returned to the agent with the exact repair reason while the loop is
+still warm.
 
 ```bash
 npm init @vyuhlabs/dxkit -- --claude-loop --yes   # install dxkit + register the Claude Code Stop hook
@@ -30,12 +36,12 @@ npx vyuh-dxkit baseline create                    # grandfather today's findings
 npx vyuh-dxkit loop doctor                         # verify the gate is wired
 ```
 
-The gate runs locally with no model: same input, same verdict, in seconds.
+The stop verdict has no model in the path: same input, same verdict.
 Existing debt stays grandfathered; only net-new regressions block. Want to
 watch the flow first, on a sandbox dxkit creates? See the
-[walkthrough](#see-it-without-touching-your-repo).
+[fixture gate](#run-a-local-fixture-gate).
 
-[Read the benchmark](docs/benchmarks.md) · [Try it on your repo](#try-it-on-your-repo)
+[Read the benchmark](docs/benchmarks.md) · [Try it on your repo](#try-it-on-your-repo) · [Run the fixture gate](#run-a-local-fixture-gate)
 
 <p>
   <a href="https://www.npmjs.com/package/@vyuhlabs/dxkit"><img alt="npm" src="https://img.shields.io/npm/v/@vyuhlabs/dxkit"></a>
@@ -48,23 +54,27 @@ watch the flow first, on a sandbox dxkit creates? See the
 
 ## The problem: loops do not know when they made things worse
 
-An autonomous loop runs until the agent decides it is done. The only checks in
-that loop today are tests and linters, and those catch broken code, not
-regressed code. There is no notion of "worse than the baseline." So an agent
-can add a feature, leave a new untested path or a hardcoded credential behind,
-run the tests, see green, and declare success.
+An autonomous loop runs until the agent decides it is done. The common checks in
+that loop (tests, linters, scanners, CI-style commands) usually answer whether
+something is broken or flagged. They do not, by themselves, maintain a
+brownfield baseline and answer the loop-level question: did this change
+introduce something net-new? So an agent can add a feature, leave a new untested
+path or a hardcoded credential behind, run the tests, see green, and declare
+success.
 
 In our benchmark this happened in most vanilla runs, and telling the agent to
 check its own work only helped a little.
 
 ## What dxkit does
 
-1. **Baseline today's debt.** `baseline create` records every current finding,
-   so pre-existing issues are grandfathered and never block.
-2. **Run a deterministic Stop-gate on every stop.** A Claude Code Stop hook
-   re-runs the guardrail against that baseline. Same input gives the same
-   verdict, in seconds, offline, with no model in the loop.
-3. **Feed net-new findings back to the agent.** If the change introduced a
+1. **Build a structural code graph.** dxkit gives the agent callers, callees,
+   blast radius, and relevant files so it can orient before editing.
+2. **Baseline today's debt.** `baseline create` records current findings, so
+   pre-existing issues are grandfathered and never block.
+3. **Run a deterministic Stop-gate on every stop.** A Claude Code Stop hook
+   reruns the guardrail against that baseline. Same input gives the same
+   verdict; no model decides whether the gate passes.
+4. **Feed net-new findings back to the agent.** If the change introduced a
    finding, the gate blocks the stop and hands the agent the exact finding to
    fix: do not refresh the baseline, do not touch unrelated debt, fix what this
    branch introduced. The loop stops only when clean.
@@ -78,11 +88,27 @@ Use dxkit if you let coding agents:
 - touch brownfield repos that already carry debt,
 - or work where "new debt" matters more than "all debt."
 
+## What dxkit is, and is not
+
+**It is a deterministic verification layer.** It baselines today's findings,
+fingerprints them across churn, and blocks only net-new regressions.
+
+**It is not a scanner replacement.** It runs and ingests scanners (gitleaks,
+Semgrep, CodeQL, Snyk, SARIF) and makes their findings enforceable. It does not
+claim to find more bugs than they do.
+
+**It is not an LLM judge.** No model decides whether the gate passes. The model
+can repair findings. The gate itself is deterministic, and the prompt does not
+grow as the baseline grows.
+
+**It is not a guarantee of safe code.** It blocks detector-backed net-new
+findings it can observe. You still need tests, review, scanners, and judgment.
+
 ## Built on tools you already trust
 
 dxkit is an orchestration and enforcement layer, not another scanner. It runs
 established open source tools and treats their output as one stream. Which tools
-run depends on the languages in your repo — dxkit covers **8 ecosystems**
+run depends on the languages in your repo. dxkit covers **8 ecosystems**
 (TypeScript / JavaScript, Python, Go, Rust, C# / .NET, Java, Kotlin, Ruby).
 
 Universal, on every repo:
@@ -92,8 +118,8 @@ Universal, on every repo:
 - dependency advisories: OSV.dev
 - size, duplication, and the code graph: cloc, jscpd, graphify
 
-Per language, dxkit adds that ecosystem's own linter and audit tool — for
-example npm audit + ESLint (JS / TS), pip-audit + ruff (Python), govulncheck +
+Per language, dxkit adds that ecosystem's own linter and audit tool. For
+example, npm audit + ESLint (JS / TS), pip-audit + ruff (Python), govulncheck +
 golangci-lint (Go), cargo-audit + clippy (Rust), `dotnet list --vulnerable`
 (C#), osv-scanner + PMD (Java), osv-scanner + detekt (Kotlin), and
 bundler-audit + RuboCop (Ruby). The full per-language matrix is in **Per-pack
@@ -114,7 +140,7 @@ and inside the agent loop.
 ## Try it on your repo
 
 The Stop hook runs dxkit on every stop, so install dxkit into the repo. This
-one command adds it as a devDependency and registers the hook additively — your
+one command adds it as a devDependency and registers the hook additively, so your
 existing `.claude` settings are preserved:
 
 ```bash
@@ -128,9 +154,9 @@ npx vyuh-dxkit loop ledger summarize  # afterwards: blocked vs allowed, repaired
 When the agent tries to stop, dxkit runs the net-new gate against the baseline.
 Existing findings are grandfathered; only findings this change introduced block.
 
-## See it without touching your repo
+## Run a local fixture gate
 
-Want the flow first, on a sandbox dxkit creates?
+Want to see the Stop-gate before installing dxkit into your repo?
 
 ```bash
 npx -y @vyuhlabs/dxkit@latest demo loop-guardrail
@@ -141,7 +167,7 @@ net-new secret → BLOCK → repair → CLEAN, then it tears the fixture down. N
 key and no Claude Code, and your own repo is never touched. It needs gitleaks
 installed and takes about 20 seconds; without gitleaks it shows a clearly
 labelled illustration instead. (It does a one-time `npx` download, so it is not
-fully offline — the gate itself is.)
+fully offline, though the gate itself is.)
 
 ### Presets: what blocks the loop
 
@@ -192,11 +218,26 @@ ships, the graph bounds how the loop works.
 Three independent benchmark results, one theme: dxkit makes agent work more
 predictable.
 
-| Layer                      | What it bounds                       | Observed result                                                                                                  |
-| -------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| **Stop-gate**              | unsafe final state                   | vanilla loops escaped **11/16** times, prompt-only checklist escaped **9/16**, dxkit escaped **0/16**            |
-| **Deterministic identity** | false "net-new" findings under churn | **100% catch / 0% false-block** on seeded gate tests; **0 false net-new** on tested line shifts and renames      |
-| **Graph context**          | large-repo exploration tails         | median roughly tied, but large-repo mean tokens **30% lower**, worst case **57% lower**, variance roughly halved |
+| Layer                      | What it bounds                       | Observed result                                                                                                                     |
+| -------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Stop-gate**              | net-new detector-backed debt         | vanilla loops escaped **11/16** times, prompt-only checklist escaped **9/16**, dxkit escaped **0/16**                               |
+| **Deterministic identity** | false "net-new" findings under churn | caught **all 3** seeded regressions with **0/2** false blocks on clean edits; **0 false net-new** on tested line shifts and renames |
+| **Graph context**          | large-repo exploration tails         | median roughly tied, but large-repo mean tokens **30% lower**, worst case **57% lower**, variance roughly halved                    |
+
+**Deferral has a re-orientation cost.** A fourth arm of the
+loop-safety study measured the "detect on CI, fix later" model: on the test-gap
+task, deferring a net-new finding to a cold session cost **~49% more in
+equivalent cost** and **~51% more turns** than repairing it inside the warm loop,
+because the cold fixer has to re-orient in a context it no longer holds. (The
+secret-task premium pointed the same way but was weak (mean +19%, median
+slightly negative), so we lean on the robust test-gap result.) So the gate is not
+just safer than deferring, it is plausibly cheaper too.
+
+**And the gate is fast enough to run on every stop.** dxkit 2.14.0 scopes the
+Stop-gate scan to the active preset's blockable finding kinds and re-scans only
+the changed files, reusing cached results for everything unchanged. The verdict
+is identical to a full scan; the cost is seconds per stop, not minutes, even on
+large repositories.
 
 > **Benchmark caveats:** the loop-safety study uses controlled synthetic tasks
 > plus real-repo validation, detector-backed findings, and Sonnet runs. It is
@@ -207,22 +248,6 @@ predictable.
 Full methodology, reproducibility notes, artifact status, and caveats are in
 **[docs/benchmarks.md](docs/benchmarks.md)**.
 
-## What dxkit is, and is not
-
-**It is a deterministic verification layer.** It baselines today's findings,
-fingerprints them across churn, and blocks only net-new regressions.
-
-**It is not a scanner replacement.** It runs and ingests scanners (gitleaks,
-Semgrep, CodeQL, Snyk, SARIF) and makes their findings enforceable. It does not
-claim to find more bugs than they do.
-
-**It is not an LLM judge.** No model decides whether the gate passes. The model
-can repair findings. The gate itself is deterministic, and the prompt does not
-grow as the baseline grows.
-
-**It is not a guarantee of safe code.** It blocks detector-backed net-new
-findings it can observe. You still need tests, review, scanners, and judgment.
-
 ## Why not just Snyk, SonarQube, or CodeQL?
 
 Use them. dxkit can ingest their findings. The difference is tempo and control,
@@ -233,7 +258,7 @@ every time the agent tries to declare done.
 | Loop Stop-gate need                                         | dxkit | Cloud or CI scanners                   |
 | ----------------------------------------------------------- | ----- | -------------------------------------- |
 | Runs locally on every stop, in seconds                      | yes   | usually CI or cloud cadence            |
-| Can run without network or auth                             | yes   | usually requires network or auth       |
+| Deterministic verdict, no model in the gate                 | yes   | varies (some add an LLM judge)         |
 | Grandfathers existing debt                                  | yes   | tool-dependent                         |
 | Feeds the exact block reason back to the warm agent session | yes   | usually a human-facing dashboard or PR |
 
@@ -266,7 +291,7 @@ cloc, jscpd, graphify).
 | Ruby                    | `Gemfile`, `*.rb`           | RuboCop, bundler-audit                    |
 
 <details>
-<summary><strong>Per-pack capabilities</strong> — coverage import, import-graph, severity tiers (click to expand)</summary>
+<summary><strong>Per-pack capabilities</strong>: coverage import, import-graph, severity tiers (click to expand)</summary>
 
 | Language | Detection                             | Coverage import     | Import-graph                                 | Native tools                        | Lint severity tiers    | Vuln severity tiers                           |
 | -------- | ------------------------------------- | ------------------- | -------------------------------------------- | ----------------------------------- | ---------------------- | --------------------------------------------- |
@@ -293,10 +318,9 @@ so it does not inflate the Code Quality score.
 
 ## Reproduce the deterministic tier
 
-The deterministic results — the net-new gate decision and the finding-identity
-matcher — reproduce offline, so you do not have to trust our numbers. This is
-separate from the agentic benchmark, which requires running real agent sessions.
-The harnesses live in `benchmarks/`:
+The deterministic results (the net-new gate decision and the finding-identity
+matcher) reproduce offline with no API key, so you do not have to trust our
+numbers. These harnesses live in `benchmarks/`:
 
 ```bash
 node benchmarks/bench-guardrail.mjs config.json        # block/allow on seeded findings
@@ -304,8 +328,11 @@ node benchmarks/bench-netnew-isolation.mjs config.json # net-new isolation under
 node benchmarks/bench-matcher.mjs config.json          # false net-new on line shifts + renames
 ```
 
-See `benchmarks/README.md` to point them at a repo, and the full methodology,
-caveats, and artifact status in **[docs/benchmarks.md](docs/benchmarks.md)**.
+See `benchmarks/README.md` to point them at a repo. The agent-driven harnesses
+(loop safety, cost of deferral, gate-vs-LLM, and the graph-context sessions) need
+a model subscription or API key and are published under `benchmarks/agentic/`.
+Full methodology, the per-study reports, caveats, and repro steps:
+**[docs/benchmarks.md](docs/benchmarks.md)**.
 
 ## Credits
 

package/dist/analyzers/cache.d.ts

@@ -73,6 +73,15 @@ export interface ReadOrBuildOptions {
     /** Override the wall-clock used for `builtAt`. Tests use this to
      *  produce deterministic timestamps. Defaults to `new Date()`. */
     now?: () => Date;
+    /**
+     * This build is a SCOPED/partial gather (some analyzers skipped — see
+     * `GatherScope`). Its `AnalysisResult` is incomplete, so it must never
+     * enter the shared cache where a later FULL consumer (`health`) could
+     * read it as if complete. Set by the loop guardrail path; skips both the
+     * in-memory and on-disk cache for read AND write. The build still runs;
+     * only persistence is bypassed.
+     */
+    partial?: boolean;
 }
 /**
  * Resolve provenance fields needed to compute the cache key. Reads

package/dist/analyzers/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/analyzers/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAMH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAqB5B;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;uCAEmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;kBAEc;IACd,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAExD;sEACkE;IAClE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAOD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAUjE;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,qBAAqB,CAAC;IAC7B,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC3B,GAAG,OAAO,CAAC,cAAc,CAAC,CAgD1B;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/analyzers/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAMH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAqB5B;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;uCAEmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;kBAEc;IACd,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,kBAAkB,CAAC;IAExD;sEACkE;IAClE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAEjB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAOD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAUjE;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,qBAAqB,CAAC;IAC7B,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC3B,GAAG,OAAO,CAAC,cAAc,CAAC,CAyC1B;AA2BD,iEAAiE;AACjE,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/analyzers/cache.js

@@ -129,6 +129,13 @@ async function readOrBuildAnalysisResult(args) {
     const provenance = (opts.resolveProvenance ?? resolveProvenance)(cwd);
     const cacheDir = opts.cacheDir ?? path.join(provenance.cwd, CACHE_SUBDIR);
     const cacheKey = buildCacheKey(provenance);
+    // A scoped/partial gather must bypass the shared cache entirely — neither
+    // read (a full entry would mask the requested scope, but more importantly
+    // the inverse is the hazard) nor write (a partial result must never be
+    // served to a later full consumer). Build straight through.
+    if (opts.partial) {
+        return buildResult(cwd, build, provenance, opts.now);
+    }
     // In-memory short-circuit. Same provenance, same process: one rebuild.
     if (!opts.rescan) {
         const cached = inMemoryCache.get(cacheKey);
@@ -144,21 +151,7 @@ async function readOrBuildAnalysisResult(args) {
             if (fromDisk)
                 return fromDisk;
         }
-        // Build, stamp provenance, persist (when clean).
-        const body = await build(cwd);
-        const now = (opts.now ?? (() => new Date()))();
-        const result = {
-            ...body,
-            commitSha: provenance.commitSha,
-            branch: provenance.branch,
-            cwd: provenance.cwd,
-            builtAt: now.toISOString(),
-            dxkitVersion: provenance.dxkitVersion,
-            schemaVersion: analysis_result_1.ANALYSIS_RESULT_SCHEMA_VERSION,
-            ignoreFileMtime: provenance.ignoreFileMtime,
-            inputsDigest: provenance.inputsDigest,
-            workingTreeDirty: provenance.workingTreeDirty,
-        };
+        const result = await buildResult(cwd, build, provenance, opts.now);
         if (!provenance.workingTreeDirty) {
             writeDiskCache(cacheDir, result);
         }
@@ -170,6 +163,25 @@ async function readOrBuildAnalysisResult(args) {
     promise.catch(() => inMemoryCache.delete(cacheKey));
     return promise;
 }
+/** Build + stamp provenance into a complete `AnalysisResult`. No caching —
+ *  callers decide whether to persist. Shared by the cached and partial
+ *  (scope-bypass) paths so they produce byte-identical result envelopes. */
+async function buildResult(cwd, build, provenance, now) {
+    const body = await build(cwd);
+    const stamp = (now ?? (() => new Date()))();
+    return {
+        ...body,
+        commitSha: provenance.commitSha,
+        branch: provenance.branch,
+        cwd: provenance.cwd,
+        builtAt: stamp.toISOString(),
+        dxkitVersion: provenance.dxkitVersion,
+        schemaVersion: analysis_result_1.ANALYSIS_RESULT_SCHEMA_VERSION,
+        ignoreFileMtime: provenance.ignoreFileMtime,
+        inputsDigest: provenance.inputsDigest,
+        workingTreeDirty: provenance.workingTreeDirty,
+    };
+}
 /** Test seam — drop in-memory dedup state between test cases. */
 function clearInMemoryCache() {
     inMemoryCache.clear();

package/dist/analyzers/cache.js.map

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

package/dist/analyzers/health.d.ts

@@ -1,11 +1,30 @@
 import { HealthMetrics, HealthReport } from './types';
 import type { AnalysisResult, AnalysisResultBody } from '../analysis-result';
+import { type GatherScope } from '../baseline/gather-scope';
 /** Default values for all HealthMetrics fields. */
 export declare function defaultMetrics(): HealthMetrics;
 /** Options for analyzeHealth. */
 export interface AnalyzeHealthOptions {
     /** Print per-tool timing to stderr. */
     verbose?: boolean;
+    /**
+     * Restrict the gather to the analyzers a scope needs. Defaults to
+     * `FULL_SCOPE` (every analyzer), so the `health` report and CI guardrail
+     * are unaffected. The loop Stop-gate passes a policy-derived scope so a
+     * `security-only` posture skips the analyzers it can never block on (see
+     * `src/baseline/gather-scope.ts`). A scoped result is partial by
+     * construction and is never written to the shared `AnalysisResult` cache.
+     */
+    scope?: GatherScope;
+    /**
+     * Incremental scanning (opt 3): when set, semgrep scans ONLY these
+     * project-relative changed files instead of the whole tree. Sound for a
+     * net-new gate because semgrep is intraprocedural — a net-new code
+     * finding can only appear in a changed file. Like `scope`, this makes the
+     * result partial (it never enters the shared cache). Only the loop
+     * Stop-gate sets it; CI / `health` leave it undefined (full scan).
+     */
+    incrementalFiles?: ReadonlyArray<string>;
 }
 /**
  * Run a full health analysis on a repository, returning both the summary

package/dist/analyzers/health.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/analyzers/health.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAoB,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAgC7E,mDAAmD;AACnD,wBAAgB,cAAc,IAAI,aAAa,CAiD9C;AAED,iCAAiC;AACjC,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC,CAE3D;AAED,kDAAkD;AAClD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,YAAY,CAAC,CAEvB;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAwG7B;AAsBD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CA0BzE"}
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/analyzers/health.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAoB,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAgC7E,OAAO,EAAE,KAAK,WAAW,EAAc,MAAM,0BAA0B,CAAC;AAExE,mDAAmD;AACnD,wBAAgB,cAAc,IAAI,aAAa,CAiD9C;AAED,iCAAiC;AACjC,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC,CAE3D;AAED,kDAAkD;AAClD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,YAAY,CAAC,CAEvB;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAiH7B;AAsBD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CA0BzE"}