fallow 3.26.0 → 3.28.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -7262,7 +7262,7 @@
     ]
   },
   "plugins": {
-    "count": 126,
+    "count": 127,
     "note": "Built-in framework plugins, auto-activated when their enabler dependency is present; run fallow list --plugins for the set active in a specific project",
     "names": [
       "nextjs",
@@ -7314,6 +7314,7 @@
       "rolldown",
       "rspack",
       "rsbuild",
+      "module-federation",
       "tsup",
       "tsdown",
       "pkg-utils",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "mcpName": "io.github.fallow-rs/fallow",
   "description": "Codebase intelligence for TypeScript and JavaScript. Free static analysis of code and styles, optional paid runtime intelligence (Fallow Runtime). Quality, risk, architecture, dependencies, duplication, and design-system drift for humans, CI, and the agents writing your code. Zero-config framework support.",
   "license": "MIT",
@@ -85,17 +85,17 @@
     "detect-libc": "2.1.2"
   },
   "devDependencies": {
-    "@tanstack/intent": "0.3.8"
+    "@tanstack/intent": "0.4.0"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.26.0",
-    "@fallow-cli/darwin-x64": "3.26.0",
-    "@fallow-cli/linux-x64-gnu": "3.26.0",
-    "@fallow-cli/linux-arm64-gnu": "3.26.0",
-    "@fallow-cli/linux-x64-musl": "3.26.0",
-    "@fallow-cli/linux-arm64-musl": "3.26.0",
-    "@fallow-cli/win32-arm64-msvc": "3.26.0",
-    "@fallow-cli/win32-x64-msvc": "3.26.0",
-    "fallow-type-aware": "3.26.0"
+    "@fallow-cli/darwin-arm64": "3.28.0",
+    "@fallow-cli/darwin-x64": "3.28.0",
+    "@fallow-cli/linux-x64-gnu": "3.28.0",
+    "@fallow-cli/linux-arm64-gnu": "3.28.0",
+    "@fallow-cli/linux-x64-musl": "3.28.0",
+    "@fallow-cli/linux-arm64-musl": "3.28.0",
+    "@fallow-cli/win32-arm64-msvc": "3.28.0",
+    "@fallow-cli/win32-x64-msvc": "3.28.0",
+    "fallow-type-aware": "3.28.0"
   }
 }

package/schema.json

@@ -363,7 +363,7 @@
       "default": false
     },
     "autoImports": {
-      "description": "When true, drops Nuxt convention-based entry-pattern fallbacks: component fallbacks are dropped unless nuxt.config declares components:, and composable/util fallbacks are dropped unless it declares imports:, so genuinely-unreferenced convention files surface as unused-file. Boolean, defaults to false; set it for a Nuxt project that has explicitly configured its auto-import directories. Synthesis of auto-import graph edges (resolving `<Card />` or `useUserStore()` to their convention files) happens regardless of this flag.",
+      "description": "When true, drops Nuxt convention-based entry-pattern fallbacks so genuinely-unreferenced convention files surface as unused-file. Component fallbacks are kept when nuxt.config customizes components: in a way fallow does not model, and composable/util fallbacks are kept when it customizes imports:; a config that scans no more than the Nuxt defaults (components: false, components: [], components: { dirs: [] }, components: true, imports: { scan: false }, imports: {}, imports: { dirs: [] }) is treated like the default and its fallbacks are dropped; imports: { autoImport: false } on its own is not, because it only switches the injection off while the same directories stay registered behind #imports. A nuxt.config that carries any top-level key fallow cannot read statically, a computed key, an accessor, or a spread such as { ...base, devtools: {} }, keeps both surfaces' fallbacks for that root, because the spread may hold the keys that decide. Each root is classified on its own config, so one custom nuxt.config in a monorepo does not keep every other workspace's fallbacks. Component names follow Nuxt: a component under components/global or components/islands is named after its own directory (components/global/Foo.vue is `<Foo>`), and .client, .server, .global and .island suffixes are stripped. A name imported or re-exported by hand from #components or #imports credits its convention file just like a template tag or a bare call; a namespace import names nothing and credits nothing. Boolean, defaults to false; set it for a Nuxt project that has explicitly configured its auto-import directories. Synthesis of auto-import graph edges (resolving `<Card />` or `useUserStore()` to their convention files) happens regardless of this flag.",
       "type": "boolean",
       "default": false
     },

package/skills/fallow/references/cli-reference.md

@@ -446,7 +446,7 @@ Human output groups paths under "Shared with your team (commit these)" and "Loca
 {
   "kind": "agent-install",
   "schema_version": 1,
-  "fallow_version": "3.26.0",
+  "fallow_version": "3.28.0",
   "root": "/abs/path",
   "mode": "install",
   "dry_run": false,
@@ -650,7 +650,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.26.0",
+  "version": "3.28.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -1053,7 +1053,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.26.0",
+  "version": "3.28.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -1130,7 +1130,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.26.0",
+  "version": "3.28.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1231,7 +1231,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1260,7 +1260,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -2030,7 +2030,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.26.0",
+  "version": "3.28.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2190,7 +2190,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.26.0",
+  "version": "3.28.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2234,11 +2234,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.26.0",
+  "version": "3.28.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.26.0",
+    "version": "3.28.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],
@@ -2376,8 +2376,10 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
   // Resolve framework convention auto-imports (Nuxt components) as graph edges.
   // Edges for `<Card001 />`-style template tags are always synthesized; setting
   // this to true also drops the Nuxt component entry patterns so an
-  // unreferenced component is reported as unused-file. Kept conservative: a
-  // `components:` key in nuxt.config keeps the entry patterns. Default false.
+  // unreferenced component is reported as unused-file. Kept conservative: an
+  // unmodelled `components:` or `imports:` config keeps the entry patterns, but
+  // a config that switches the scan off (`components: { dirs: [] }`,
+  // `imports: { scan: false }`) is treated like the default. Default false.
   "autoImports": false,
 
   // Production mode

package/types/output-contract.d.ts

@@ -135,6 +135,16 @@ export type ElapsedMs = number
  * Value of `audit.gate`: which findings drive the `fallow audit` verdict.
  */
 export type AuditGate = ("new-only" | "all")
+/**
+ * What a gate concluded on this run.
+ *
+ * Four-valued rather than a boolean because audit's verdict has a warn tier
+ * (`crates/cli/src/cli_report.rs` maps it onto three conclusions) and because
+ * a gate can stand down without passing. Widening a published boolean later
+ * would retype a required field and bump every carrying envelope, so the width
+ * is decided here.
+ */
+export type GateStatus = ("pass" | "warn" | "fail" | "skipped")
 /**
  * Analysis mode stored with baselines, snapshots, audit sides, and impact data.
  */
@@ -402,6 +412,30 @@ export type DependencyOverrideSource = ("pnpm-workspace.yaml" | "package.json")
  * surfacing them statically catches the issue first.
  */
 export type DependencyOverrideMisconfigReason = ("unparsable-key" | "empty-value")
+/**
+ * Which advisory a loaded baseline earned on this run.
+ *
+ * Mirrors `fallow_engine::baseline::BaselineStalenessWarning` so a consumer can
+ * render the same distinction the stderr warning makes, instead of inferring it
+ * from counts.
+ */
+export type BaselineStalenessAdvisory = ("none" | "zero-overlap" | "partial")
+/**
+ * One channel that narrowed a run to part of the project.
+ *
+ * Serialized as kebab-case inside `scope_reasons` and published as an OPEN
+ * set, the same tolerate-unknown contract `gate_outcomes` keys carry: a name
+ * this build does not emit means "some narrowing", not an error.
+ *
+ * Which names a command can emit differs per command, because the three
+ * narrowing predicates see different state. `dead-code` reads the flags
+ * themselves and can name every channel. `dupes` and `health` see an already
+ * resolved changed-file set and report `changed-files`, because at that point
+ * the flag that produced it is gone. `health` reports `workspace` for both
+ * `--workspace` and `--changed-workspaces` for the same reason. A consumer
+ * must therefore not assume a given command emits a given name.
+ */
+export type ScopeReason = ("diff" | "changed-since" | "changed-files" | "workspace" | "changed-workspaces" | "scope" | "file" | "issue-type-filter" | "production")
 /**
  * Status of a regression-check pass.
  */
@@ -410,6 +444,29 @@ export type RegressionStatus = ("pass" | "exceeded" | "skipped")
  * Interpretation of [`RegressionResult::tolerance`].
  */
 export type RegressionToleranceKind = ("absolute" | "percentage")
+/**
+ * What became of one request on this run.
+ *
+ * Two-valued today. The value set is OPEN so a later `partial` needs no bump,
+ * and it is deliberately not added now: nothing emits it, and a permanently
+ * unused value reads as a measurement nobody takes.
+ */
+export type RequestStatus = ("applied" | "not-applied")
+/**
+ * What a request governs, and therefore what its failure means.
+ *
+ * Published on every entry so a consumer selects on the class rather than on
+ * a name list. Without it the one sentence a consumer can write for the whole
+ * object ("the report is wider than requested") is false for any request that
+ * does not narrow, which is how a failed `--sarif-file` write came to be
+ * reported as an unscoped run. A request name added later carries its own
+ * class, so a consumer written today keeps saying the right thing about it.
+ *
+ * The value set is OPEN, like the names and the statuses: read a class this
+ * build does not recognise as "some request", not as an error, and do not read
+ * it as `scope`.
+ */
+export type RequestEffect = ("scope" | "artifact")
 /**
  * A diagnostic about a workspace-discovery candidate.
  *
@@ -428,6 +485,25 @@ path: string
  * with a next-step hint.
  */
 message: string
+/**
+ * True when this diagnostic reports a run whose RESULTS are degraded:
+ * something the user installed, wrote, or expected did not reach the
+ * analysis. Projected from [`WorkspaceDiagnosticKind::warns_on_stderr`],
+ * which is the same classification that decides whether the CLI prints a
+ * stderr line, so a CI log built from this field and a local non-quiet run
+ * say the same thing.
+ *
+ * Omitted when false, which is what keeps every clean run byte-identical.
+ * The two unconfigured-check kinds answer false on purpose: they fire in
+ * the product's default state on every project that never opted into
+ * boundaries or rule packs, so warning on them would warn forever. So does
+ * `excluded-by-default-ignore`, which is designed behavior on generated
+ * output; the alarm for that case is `no-source-files-analyzed`.
+ *
+ * Read this instead of hardcoding a kind allowlist: a degrading kind added
+ * in a later release then reaches an unchanged consumer.
+ */
+degrades_analysis?: boolean
 } & WorkspaceDiagnostic1)
 export type WorkspaceDiagnostic1 = ({
 kind: "undeclared-workspace"
@@ -525,6 +601,105 @@ file_count: number
  */
 directory_count: number
 kind: "excluded-by-default-ignore"
+} | {
+/**
+ * Candidate source files the built-in ignore patterns removed from
+ * this walk, summed across every pattern. `0` when the walk found no
+ * candidate to exclude in the first place.
+ */
+excluded_file_count: number
+kind: "no-source-files-analyzed"
+} | {
+/**
+ * Scoring error text.
+ */
+error: string
+kind: "file-scores-unavailable"
+} | {
+/**
+ * Which input stopped it, as a kebab-case token: `not-a-repository`,
+ * `invalid-since` or `churn-file-unreadable`. The set is open.
+ *
+ * The cause decides the remedy, which is why it is on the wire: a run
+ * outside a repository is fixed by running fallow inside one, a
+ * malformed `--since` by respelling the flag, and a churn file that
+ * changed under the run by rerunning it. A consumer reading only the
+ * kind would offer the first remedy for all three.
+ */
+cause: string
+kind: "hotspots-skipped"
+} | {
+/**
+ * `true` when the run also asked for ownership attribution, which a
+ * shallow clone skews further by inflating single-author dominance.
+ */
+ownership_requested: boolean
+kind: "shallow-clone"
+} | {
+kind: "unpinned-clock"
+} | {
+/**
+ * Which input failed, as a kebab-case token: `invalid-bot-pattern` or
+ * `codeowners-parse-failed`. The set is open.
+ */
+cause: string
+/**
+ * Underlying error text.
+ */
+error: string
+kind: "ownership-unavailable"
+} | {
+/**
+ * Filesystem or JSON error text.
+ */
+error: string
+kind: "trend-snapshot-unreadable"
+} | {
+/**
+ * The plugin that read the config, as it labels itself:
+ * `module-federation` for a standalone `module-federation.config.*`,
+ * or the bundler plugin (`webpack`, `rspack`, `rsbuild`, `vite`) that
+ * read the same options inline from its own config.
+ */
+plugin: string
+/**
+ * The config key that was present and not fully readable (`exposes`,
+ * `remotes`). The set is open.
+ */
+key: string
+/**
+ * Why it could not be read, as a kebab-case token:
+ * `not-object-literal`, `array-form`, `spread` or
+ * `unreadable-entries`. The set is open.
+ *
+ * The reason decides the remedy, which is why it is on the wire: a
+ * value that is not an object literal is fixed by writing one, while
+ * unreadable entries are fixed by naming those entries in the config
+ * option the message points at.
+ */
+reason: string
+kind: "plugin-config-unreadable"
+} | {
+/**
+ * The plugin that read the config, as it labels itself (`nuxt`).
+ */
+plugin: string
+/**
+ * The config key whose effect is not modeled (`components`,
+ * `imports`). The set is open.
+ */
+key: string
+/**
+ * Why the effect is not modeled, as a kebab-case token:
+ * `key-effect-not-modeled` when the key's own value is the reason,
+ * `config-property-unreadable` when a top-level property of the same
+ * config file could not be read statically, so no surface in it can
+ * be classified at all. The set is open.
+ */
+reason: string
+kind: "plugin-effect-not-modeled"
+} | {
+kind: "coverage-auto-detected"
 })
 /**
  * Discriminant for [`CloneGroupAction::kind`]. Mirrors the action types
@@ -1311,6 +1486,16 @@ elapsed_ms: ElapsedMs
 base_snapshot_skipped?: (boolean | null)
 summary: AuditSummary
 attribution: AuditAttribution
+/**
+ * Every gate this run ARMED, keyed by name, absent when it armed none.
+ * Each entry is the same rule that decides the exit code, so a CI
+ * integration reads the verdict instead of guessing from a process status
+ * it usually cannot see. A gate fails the build when `status` is `fail`
+ * AND `enforced` is true. Armed, not evaluated: fallow's default severity
+ * rules fail a run with no flag at all, so an absent object means "no gate
+ * was asked for", never "nothing failed". See [`crate::GateOutcomes`].
+ */
+gate_outcomes?: (GateOutcomes | null)
 /**
  * `_meta` block with metric / rule definitions, when `--explain` was
  * passed.
@@ -1393,6 +1578,78 @@ styling_introduced: number
 styling_inherited: number
 duplication_demoted: number
 }
+/**
+ * Every gate a run ARMED, keyed by name.
+ *
+ * Armed, not evaluated: a gate is armed by a flag or by config, never merely
+ * because the rule behind it exists. Fallow's default severity rules fail a
+ * run with no flag at all, so a `dead-code` run can exit 1 carrying no object
+ * whatsoever. Read an absent object as "no gate was asked for", never as
+ * "nothing failed".
+ *
+ * Absent from an envelope whenever it is empty, so a run that armed no gate is
+ * byte-identical to one produced before this object existed. An empty object
+ * is never emitted: it would assert that gates were armed and none tripped,
+ * which is a different and false claim.
+ *
+ * The names this build can emit are `error-severity-findings`, `regression`,
+ * `stale-baseline`, `duplication-threshold`, `health-min-score`,
+ * `health-min-severity`, `health-findings`, `health-coverage-gaps`,
+ * `health-runtime-coverage`, `security`, `security-advisory`, `audit-verdict`
+ * and `type-aware-require`. The set is OPEN: a name a consumer does not
+ * recognise means "some gate", not an error.
+ */
+export interface GateOutcomes {
+[k: string]: GateOutcome
+}
+/**
+ * One gate's verdict on one run.
+ *
+ * `status` and `enforced` answer different questions and legitimately
+ * disagree. `status` is what the rule concluded; `enforced` is whether a
+ * `fail` from this gate would make the run exit non-zero. A
+ * `health --report-only` run is an explicit request never to fail, so a
+ * failing gate there reports `status: fail` with `enforced: false`, and a
+ * stale-baseline verdict published without `--fail-on-stale-baseline` reports
+ * the same pair.
+ *
+ * **A gate fails the build when `status` is `fail` AND `enforced` is true.**
+ * Neither member decides it alone: `enforced` is true on every armed gate,
+ * including the ones that passed, so gating on it by itself fails every run
+ * that armed anything. Read `status` on its own to decide what to say, and
+ * remember that `warn` and `skipped` are neither a pass nor a failure.
+ */
+export interface GateOutcome {
+status: GateStatus
+/**
+ * True when a `fail` from this gate makes the run exit non-zero. False
+ * when the verdict is published for information only, because the gate was
+ * never armed or because the run was told never to fail.
+ */
+enforced: boolean
+/**
+ * The measured value the gate compared, when there is one: the duplication
+ * percentage, the health score, or the number of findings at or above the
+ * severity floor. Whole numbers are carried as JSON numbers, so a count of
+ * three reads as `3.0`. Absent for gates that compare no number.
+ */
+observed?: (number | null)
+/**
+ * The configured limit `observed` was compared against, when there is one.
+ * Absent for gates that compare no number.
+ */
+threshold?: (number | null)
+/**
+ * How the limit was spelled, for a gate whose `threshold` number does not
+ * carry its own unit. `health-min-severity` sets it to the severity floor
+ * (`moderate`, `high` or `critical`); `regression` sets it to the
+ * tolerance as the user wrote it (`"50%"` or `"5"`), because `threshold`
+ * there is the allowance in issues and the percentage would otherwise be
+ * unrecoverable on the grouped envelope, which carries no `regression`
+ * object. Absent for gates whose numbers speak for themselves.
+ */
+threshold_label?: (string | null)
+}
 /**
  * Metric and rule definitions emitted under `_meta` when `--explain` is
  * passed (always present in MCP responses). Helps AI agents and CI systems
@@ -2670,10 +2927,39 @@ baseline_deltas?: (BaselineDeltas | null)
  * Which baseline snapshot was matched, in baseline runs.
  */
 baseline?: (BaselineMatch | null)
+/**
+ * This run's view of the loaded baseline, present only in baseline runs.
+ * Carries the staleness counts, the advisory verdict and `gate_trips`, the
+ * same boolean `--fail-on-stale-baseline` exits on, so a CI integration
+ * reads one field instead of restating the rule. Read `change_scoped`
+ * before dividing `matched_entries` by `baseline_entries`: a narrowed run
+ * can report `matched_entries: 0` on a healthy baseline.
+ */
+baseline_staleness?: (BaselineStaleness | null)
 /**
  * Regression verdict against the baseline, in `--fail-on-regression` runs.
  */
 regression?: (RegressionResult | null)
+/**
+ * Every gate this run ARMED, keyed by name, absent when it armed none.
+ * Each entry is the same rule that decides the exit code, so a CI
+ * integration reads the verdict instead of guessing from a process status
+ * it usually cannot see. A gate fails the build when `status` is `fail`
+ * AND `enforced` is true. Armed, not evaluated: fallow's default severity
+ * rules fail a run with no flag at all, so an absent object means "no gate
+ * was asked for", never "nothing failed". See [`crate::GateOutcomes`].
+ */
+gate_outcomes?: (GateOutcomes | null)
+/**
+ * Every narrowing or shaping request this run RECEIVED, keyed by name,
+ * absent when it was asked for nothing. An entry whose `status` is not
+ * `applied` means the run could not do what it was asked and reported
+ * something WIDER instead, so what follows is a valid report of a scope
+ * nobody requested. Honoured requests are published too, with
+ * `status: "applied"`, so an absent object means "nothing was asked for",
+ * never "nothing failed". See [`crate::RequestOutcomes`].
+ */
+request_outcomes?: (RequestOutcomes | null)
 /**
  * `_meta` block with docs and rule definitions, when `--explain` was
  * passed.
@@ -2692,10 +2978,12 @@ _meta?: (Meta | null)
  *   `source-parse-degraded`;
  * - dead-code analysis, from the dependency-catalog and override
  *   detectors: `malformed-pnpm-workspace-yaml`,
- *   `bun-lockb-override-resolution-skipped`.
+ *   `bun-lockb-override-resolution-skipped`;
+ * - framework plugins, while they read their own build configs:
+ *   `plugin-config-unreadable`, `plugin-effect-not-modeled`.
  *
- * Analysis-stage kinds therefore reach only the envelopes whose run
- * includes a dead-code analyze pass, never a standalone
+ * Analysis-stage and plugin-stage kinds therefore reach only the envelopes
+ * whose run includes a dead-code analyze pass, never a standalone
  * `fallow dupes --format json`. `path` is project-root-relative with
  * forward slashes; the array is omitted when empty. The same list is
  * repeated on each top-level command's envelope so single-command
@@ -5092,6 +5380,126 @@ entries: number
  */
 matched: number
 }
+/**
+ * One run's machine-readable view of a loaded baseline.
+ *
+ * `stale` and `gate_trips` answer different questions and legitimately
+ * disagree. `stale` mirrors the unasked-for stderr advisory, which stays silent
+ * below a quarter of the baseline and on a run that produced no findings at
+ * all, because a cleaned project and a rotted baseline look identical from
+ * there. `gate_trips` mirrors the opt-in `--fail-on-stale-baseline` rule, which
+ * a repository asks for precisely to catch those cases, so it fires on any
+ * stale entry. A rotted baseline on a cleaned project reports
+ * `stale: false` with `gate_trips: true`; that is the contract, not a defect.
+ *
+ * `change_scoped` is the member a consumer must read before dividing
+ * `matched_entries` by `baseline_entries`. A run narrowed to part of the
+ * project compares a whole-project baseline against a slice of it and can
+ * report `matched_entries: 0` while the baseline is perfectly healthy, so both
+ * `stale` and `gate_trips` are false there by construction. The remedy for a
+ * tripped gate is always the same: re-save the baseline from a whole-project
+ * run with `--save-baseline`.
+ */
+export interface BaselineStaleness {
+/**
+ * Entries carried by the loaded baseline file. On health these are the
+ * complexity and CRAP finding entries; runtime-coverage suppressions and
+ * refactoring target keys carried by the same file are not counted.
+ */
+baseline_entries: number
+/**
+ * Entries that matched a current finding on this run and were filtered out
+ * of the report. On health this includes entries matched through a
+ * followed file move.
+ */
+matched_entries: number
+/**
+ * Entries that matched no current finding on this run:
+ * `baseline_entries - matched_entries`.
+ */
+stale_entries: number
+/**
+ * Findings this run produced before the baseline filtered them. Zero means
+ * there was nothing to compare, either because the project is clean or
+ * because the scope was empty, which is why `stale` stays false there even
+ * when every entry went unmatched.
+ */
+current_findings: number
+/**
+ * True when this run analyzed only part of the project, so a whole-project
+ * baseline matches less of it for reasons that are not rot. The channels
+ * differ per command and include a diff, a base ref, `--changed-since`,
+ * `--workspace`, `--changed-workspaces`, `--scope`, `--file`, an
+ * issue-type filter, and production mode. Both `stale` and `gate_trips`
+ * are false whenever this is true. `scope_reasons` names the channels
+ * that fired.
+ */
+change_scoped: boolean
+/**
+ * True exactly when the advisory stderr warning fired: not change-scoped,
+ * at least one current finding before baseline filtering, and either
+ * nothing matched or `stale_entries` reached a quarter of
+ * `baseline_entries`.
+ */
+stale: boolean
+warning: BaselineStalenessAdvisory
+/**
+ * True exactly when `unrecognised_format` is true, or
+ * `!change_scoped && baseline_entries > 0 && matched_entries < baseline_entries`.
+ * That is the rule `--fail-on-stale-baseline` applies. Deliberately
+ * stricter than `stale`: any unmatched entry counts, and so does a file
+ * this command could not read as its own, which protects nothing at all.
+ * The second half is suppressed by `change_scoped` and the first is not:
+ * which command wrote a file does not depend on how much of the project
+ * the run looked at.
+ *
+ * It describes the baseline, not the run's exit code: `health
+ * --report-only` is an explicit request never to fail, so that run exits 0
+ * and says so on stderr while still reporting `gate_trips: true` here, and
+ * `fallow audit` never judges a baseline at all, so its
+ * `gate_outcomes["stale-baseline"]` stands down beside a section that
+ * reports `true`.
+ */
+gate_trips: boolean
+/**
+ * Entries that matched only by following a file move. Only `health` can
+ * follow one, in its identity baseline mode; `dead-code` and `dupes` match
+ * entries by fingerprint and never classify one as moved, so they report
+ * `0`. Always `0` in health's count mode too.
+ */
+moved_entries: number
+/**
+ * True when the loaded file is not a baseline of the command that read it:
+ * it names another command in its top-level `kind`, or it names none and
+ * carries no key this command's own format writes. Read this, not
+ * `baseline_entries == 0`, before telling anyone their baseline is the
+ * wrong file: a baseline saved from a project that had nothing to record
+ * is legitimately empty and is not a mistake.
+ *
+ * Present only when true, so an envelope from a run that loaded its own
+ * baseline is unchanged. All three commands set it, including `dead-code`,
+ * which classifies the file before its required fields could reject it.
+ * A file with no `kind` is the reading a baseline saved before that member
+ * existed gets, which is why the keys remain the fallback.
+ */
+unrecognised_format?: boolean
+/**
+ * Which channels narrowed this run, present and non-empty exactly when
+ * `change_scoped` is true. Both members are derived from one function, so
+ * the boolean and the array cannot disagree.
+ *
+ * Read it to decide whether the narrowing is removable: a run narrowed
+ * only by `diff`, `changed-since`, `changed-files`, `scope`, `file` or
+ * `issue-type-filter` can be repeated unscoped to judge the baseline,
+ * while `production`, `workspace` and `changed-workspaces` are the
+ * caller's own choice about what to analyze and an unscoped repeat would
+ * contradict it.
+ *
+ * The name set is OPEN and the names a command can emit differ per
+ * command; see [`ScopeReason`].
+ */
+scope_reasons?: ScopeReason[]
+}
 /**
  * Result of regression detection (`--fail-on-regression`). Compares current
  * issue counts against a baseline from config or an explicit file.
@@ -5128,6 +5536,102 @@ exceeded: boolean
  */
 reason?: (string | null)
 }
+/**
+ * Every narrowing or shaping request a run RECEIVED, keyed by name.
+ *
+ * Received, not failed: a request the run honoured is published with
+ * `status: "applied"`, so a consumer can say "scoped to the change"
+ * positively. Read an absent object as "nothing was asked for", never as
+ * "nothing failed".
+ *
+ * Absent from an envelope whenever it is empty, so a run that was asked for
+ * nothing is byte-identical to one produced before this object existed. An
+ * empty object is never emitted: it would assert that something was asked and
+ * all of it applied, which is a different and false claim.
+ *
+ * The names this build can emit are `changed-since`, `diff-filter` and
+ * `sarif-file`. The reasons are `git-missing`, `not-a-repository`,
+ * `git-failed` and `invalid-ref` for `changed-since`, `oversize`,
+ * `unreadable`, `not-utf8`, `foreign-namespace` and `ambiguous-base` for
+ * `diff-filter`, and `directory-create-failed`, `write-failed` and
+ * `serialize-failed` for `sarif-file`. Every set is OPEN: a name a consumer
+ * does not recognise means "some request", not an error.
+ *
+ * `sarif-file` reports a SECONDARY artifact rather than the scope of the
+ * report it travels in, and it is in the same object for the same reason the
+ * others are: the run was asked to do something and did something else, and
+ * nothing in the primary report says so. Which of the two an entry is, every
+ * entry says for itself: `affects` is `scope` for the narrowing requests and
+ * `artifact` for this one. Select on it. A consumer that instead assumes the
+ * whole object narrows the report tells its reader an unwritten SARIF file
+ * widened the analysis, which is what `affects` exists to prevent.
+ *
+ * `scope_size` is emitted for `diff-filter` only today, in added lines. A
+ * consumer reads the unit off the name, so a name that starts measuring its
+ * own scope in a later release needs no change here.
+ *
+ * `invalid-ref` is reachable only through the programmatic API. The
+ * `--changed-since` flag validates its value before a run starts and fails
+ * with exit 2 and an error document, which is the right side to err on: a
+ * malformed ref is invalid input rather than a report of the wrong scope.
+ */
+export interface RequestOutcomes {
+[k: string]: RequestOutcome
+}
+/**
+ * One request's fate on one run.
+ *
+ * `reason` and `message` are present exactly when `status` is not `applied`,
+ * and absent otherwise, so a consumer that only wants to know whether a
+ * report is scoped reads `status` alone.
+ */
+export interface RequestOutcome {
+status: RequestStatus
+affects: RequestEffect
+/**
+ * What was asked, as the user spelled it: the git ref for
+ * `changed-since`, the diff source label (`--diff-file pr.diff`,
+ * `--diff-stdin`, `$FALLOW_DIFF_FILE build/pr.diff`) for `diff-filter`,
+ * the target path for `sarif-file`. Echoed rather than normalised, so a
+ * consumer must not join it to the project root the way it joins every
+ * other path-shaped field.
+ */
+requested: string
+/**
+ * How much this request left in scope, in the request's own unit, when the
+ * run applied it AND measured that scope. Absent otherwise, including on
+ * every unapplied entry: a request that stood down narrowed nothing, so a
+ * number there would describe a scope nobody applied.
+ *
+ * The unit belongs to the name. `diff-filter` counts added lines, which is
+ * what its filter keeps a finding for. Read the unit off the name the entry
+ * is keyed under, never across names, and read an absent member as "not
+ * measured" rather than as zero.
+ *
+ * The count is what the run INDEXED rather than the true total:
+ * `diff-filter` indexes at most one million added lines and reports that
+ * cap for a larger diff, so read any non-zero value as a lower bound.
+ *
+ * `0` is the case this member exists for: a request that applied over an
+ * EMPTY scope. Every finding then filters out and the report reads clean,
+ * so a consumer that sees no findings beside `scope_size: 0` learns that
+ * nothing was analyzable rather than that the code is clean.
+ */
+scope_size?: (number | null)
+/**
+ * Why the request was not applied, as a kebab-case token. Present exactly
+ * when `status` is not `applied`. The set is open per request name; the
+ * names this build can emit are listed on [`RequestOutcomes`].
+ */
+reason?: (string | null)
+/**
+ * One sentence naming what was asked, what happened instead, and the next
+ * step. Byte-identical to the stderr line for the same case, so a
+ * consumer that renders this never contradicts a log a human read.
+ * Present exactly when `status` is not `applied`.
+ */
+message?: (string | null)
+}
 /**
  * A read-only follow-up command fallow surfaces from the current findings,
  * emitted as the top-level `next_steps` array on each command's JSON envelope.
@@ -6040,51 +6544,7 @@ severity_moderate_count: number
 /**
  * Baseline staleness data, present only when a baseline was loaded.
  */
-baseline_staleness?: (HealthBaselineStaleness | null)
-}
-/**
- * Staleness of a loaded health baseline.
- *
- * Reports how many saved complexity and CRAP finding entries still matched a
- * current finding on this run, so consumers can see a rotting baseline before
- * it degrades to zero overlap. Runtime-coverage suppressions and refactoring
- * target keys carried by the same baseline are not counted here. Present in
- * the summary only when a baseline was loaded.
- */
-export interface HealthBaselineStaleness {
-/**
- * Complexity and CRAP finding entries carried by the loaded baseline.
- */
-baseline_entries: number
-/**
- * Entries that matched a current finding in the active baseline mode,
- * including entries matched through a followed file move.
- */
-matched_entries: number
-/**
- * Entries that matched no current finding on this run.
- */
-stale_entries: number
-/**
- * Entries that matched only by following a file move in identity mode.
- * Always zero in count mode.
- */
-moved_entries: number
-/**
- * True when this run analyzed a subset of the project (changed-file,
- * diff, or workspace scoping, or production mode, which drops test, story
- * and dev files), so the baseline was compared against a narrowed finding
- * set and staleness cannot be judged. `stale` is always false on scoped
- * runs.
- */
-change_scoped: boolean
-/**
- * True exactly when the run was not change-scoped, at least one current
- * finding existed before baseline filtering, and `stale_entries` reached
- * a quarter of `baseline_entries`. Mirrors the human warning so machine
- * consumers do not have to reimplement the threshold.
- */
-stale: boolean
+baseline_staleness?: (BaselineStaleness | null)
 }
 /**
  * Report entry describing whether a threshold override is active, stale, or
@@ -10835,6 +11295,26 @@ grouped_by?: (GroupByMode | null)
  * Per-bucket recomputed metrics; present only in grouped output.
  */
 groups?: (HealthGroup[] | null)
+/**
+ * Every gate this run ARMED, keyed by name, absent when it armed none.
+ * Each entry is the same rule that decides the exit code, so a CI
+ * integration reads the verdict instead of guessing from a process status
+ * it usually cannot see. A gate fails the build when `status` is `fail`
+ * AND `enforced` is true. Armed, not evaluated: fallow's default severity
+ * rules fail a run with no flag at all, so an absent object means "no gate
+ * was asked for", never "nothing failed". See [`crate::GateOutcomes`].
+ */
+gate_outcomes?: (GateOutcomes | null)
+/**
+ * Every narrowing or shaping request this run RECEIVED, keyed by name,
+ * absent when it was asked for nothing. An entry whose `status` is not
+ * `applied` means the run could not do what it was asked and reported
+ * something WIDER instead, so what follows is a valid report of a scope
+ * nobody requested. Honoured requests are published too, with
+ * `status: "applied"`, so an absent object means "nothing was asked for",
+ * never "nothing failed". See [`crate::RequestOutcomes`].
+ */
+request_outcomes?: (RequestOutcomes | null)
 /**
  * `_meta` block with metric definitions, when `--explain` was passed.
  */
@@ -11009,6 +11489,35 @@ total_issues?: (number | null)
  * Grouped findings; present only in grouped output.
  */
 groups?: (DuplicationGroup[] | null)
+/**
+ * This run's view of the loaded baseline, present only in baseline runs.
+ * Carries the staleness counts, the advisory verdict and `gate_trips`, the
+ * same boolean `--fail-on-stale-baseline` exits on, so a CI integration
+ * reads one field instead of restating the rule. Read `change_scoped`
+ * before dividing `matched_entries` by `baseline_entries`: a narrowed run
+ * can report `matched_entries: 0` on a healthy baseline.
+ */
+baseline_staleness?: (BaselineStaleness | null)
+/**
+ * Every gate this run ARMED, keyed by name, absent when it armed none.
+ * Each entry is the same rule that decides the exit code, so a CI
+ * integration reads the verdict instead of guessing from a process status
+ * it usually cannot see. A gate fails the build when `status` is `fail`
+ * AND `enforced` is true. Armed, not evaluated: fallow's default severity
+ * rules fail a run with no flag at all, so an absent object means "no gate
+ * was asked for", never "nothing failed". See [`crate::GateOutcomes`].
+ */
+gate_outcomes?: (GateOutcomes | null)
+/**
+ * Every narrowing or shaping request this run RECEIVED, keyed by name,
+ * absent when it was asked for nothing. An entry whose `status` is not
+ * `applied` means the run could not do what it was asked and reported
+ * something WIDER instead, so what follows is a valid report of a scope
+ * nobody requested. Honoured requests are published too, with
+ * `status: "applied"`, so an absent object means "nothing was asked for",
+ * never "nothing failed". See [`crate::RequestOutcomes`].
+ */
+request_outcomes?: (RequestOutcomes | null)
 /**
  * `_meta` block with metric / rule definitions, emitted when `--explain`
  * is passed (always present in MCP responses).
@@ -11167,6 +11676,35 @@ total_issues: number
  * One bucket per resolver key.
  */
 groups: CheckGroupedEntry[]
+/**
+ * This run's view of the loaded baseline, present only in baseline runs.
+ * Carries the staleness counts, the advisory verdict and `gate_trips`, the
+ * same boolean `--fail-on-stale-baseline` exits on, so a CI integration
+ * reads one field instead of restating the rule. Read `change_scoped`
+ * before dividing `matched_entries` by `baseline_entries`: a narrowed run
+ * can report `matched_entries: 0` on a healthy baseline.
+ */
+baseline_staleness?: (BaselineStaleness | null)
+/**
+ * Every gate this run ARMED, keyed by name, absent when it armed none.
+ * Each entry is the same rule that decides the exit code, so a CI
+ * integration reads the verdict instead of guessing from a process status
+ * it usually cannot see. A gate fails the build when `status` is `fail`
+ * AND `enforced` is true. Armed, not evaluated: fallow's default severity
+ * rules fail a run with no flag at all, so an absent object means "no gate
+ * was asked for", never "nothing failed". See [`crate::GateOutcomes`].
+ */
+gate_outcomes?: (GateOutcomes | null)
+/**
+ * Every narrowing or shaping request this run RECEIVED, keyed by name,
+ * absent when it was asked for nothing. An entry whose `status` is not
+ * `applied` means the run could not do what it was asked and reported
+ * something WIDER instead, so what follows is a valid report of a scope
+ * nobody requested. Honoured requests are published too, with
+ * `status: "applied"`, so an absent object means "nothing was asked for",
+ * never "nothing failed". See [`crate::RequestOutcomes`].
+ */
+request_outcomes?: (RequestOutcomes | null)
 /**
  * `_meta` block with docs and rule definitions, when `--explain` was
  * passed.
@@ -11836,6 +12374,26 @@ schema_version: SecuritySchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
 config: SecurityOutputConfig
+/**
+ * Every gate this run ARMED, keyed by name, absent when it armed none.
+ * Each entry is the same rule that decides the exit code, so a CI
+ * integration reads the verdict instead of guessing from a process status
+ * it usually cannot see. A gate fails the build when `status` is `fail`
+ * AND `enforced` is true. Armed, not evaluated: fallow's default severity
+ * rules fail a run with no flag at all, so an absent object means "no gate
+ * was asked for", never "nothing failed". See [`crate::GateOutcomes`].
+ */
+gate_outcomes?: (GateOutcomes | null)
+/**
+ * Every narrowing or shaping request this run RECEIVED, keyed by name,
+ * absent when it was asked for nothing. An entry whose `status` is not
+ * `applied` means the run could not do what it was asked and reported
+ * something WIDER instead, so what follows is a valid report of a scope
+ * nobody requested. Honoured requests are published too, with
+ * `status: "applied"`, so an absent object means "nothing was asked for",
+ * never "nothing failed". See [`crate::RequestOutcomes`].
+ */
+request_outcomes?: (RequestOutcomes | null)
 /**
  * Security-specific rule and field metadata, emitted with `--explain`.
  */
@@ -12459,6 +13017,26 @@ schema_version: SecuritySchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
 config: SecurityOutputConfig
+/**
+ * Every gate this run ARMED, keyed by name, absent when it armed none.
+ * Each entry is the same rule that decides the exit code, so a CI
+ * integration reads the verdict instead of guessing from a process status
+ * it usually cannot see. A gate fails the build when `status` is `fail`
+ * AND `enforced` is true. Armed, not evaluated: fallow's default severity
+ * rules fail a run with no flag at all, so an absent object means "no gate
+ * was asked for", never "nothing failed". See [`crate::GateOutcomes`].
+ */
+gate_outcomes?: (GateOutcomes | null)
+/**
+ * Every narrowing or shaping request this run RECEIVED, keyed by name,
+ * absent when it was asked for nothing. An entry whose `status` is not
+ * `applied` means the run could not do what it was asked and reported
+ * something WIDER instead, so what follows is a valid report of a scope
+ * nobody requested. Honoured requests are published too, with
+ * `status: "applied"`, so an absent object means "nothing was asked for",
+ * never "nothing failed". See [`crate::RequestOutcomes`].
+ */
+request_outcomes?: (RequestOutcomes | null)
 /**
  * Security-specific rule and field metadata, emitted with `--explain`.
  */
@@ -12742,6 +13320,26 @@ export interface CombinedOutput {
 schema_version: CombinedSchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
+/**
+ * Every gate this run ARMED, keyed by name, absent when it armed none.
+ * Each entry is the same rule that decides the exit code, so a CI
+ * integration reads the verdict instead of guessing from a process status
+ * it usually cannot see. A gate fails the build when `status` is `fail`
+ * AND `enforced` is true. Armed, not evaluated: fallow's default severity
+ * rules fail a run with no flag at all, so an absent object means "no gate
+ * was asked for", never "nothing failed". See [`crate::GateOutcomes`].
+ */
+gate_outcomes?: (GateOutcomes | null)
+/**
+ * Every narrowing or shaping request this run RECEIVED, keyed by name,
+ * absent when it was asked for nothing. An entry whose `status` is not
+ * `applied` means the run could not do what it was asked and reported
+ * something WIDER instead, so what follows is a valid report of a scope
+ * nobody requested. Honoured requests are published too, with
+ * `status: "applied"`, so an absent object means "nothing was asked for",
+ * never "nothing failed". See [`crate::RequestOutcomes`].
+ */
+request_outcomes?: (RequestOutcomes | null)
 /**
  * Per-section `_meta` blocks, when `--explain` was passed.
  */
@@ -12801,6 +13399,22 @@ export interface FeatureFlagsOutput {
 schema_version: FeatureFlagsSchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
+/**
+ * What the run was asked to narrow and whether it did. See
+ * [`crate::RequestOutcomes`] for the full contract.
+ *
+ * `fallow flags` accepts `--changed-since`, and an unresolvable ref widens
+ * the scan to the whole project rather than failing the run. Until this
+ * member existed the only account of that was a stderr line, which `--quiet`
+ * removes, so a flag inventory read as scoped to the change could silently
+ * be the whole project's (issue #2734).
+ *
+ * The command applies no diff filter, so the object carries the
+ * `changed-since` entry only. Omitted when the run was asked for nothing,
+ * which keeps a scan that passed no narrowing flag byte-identical and moves
+ * no `schema_version`.
+ */
+request_outcomes?: (RequestOutcomes | null)
 /**
  * Detected feature-flag findings.
  */
@@ -14137,6 +14751,22 @@ invalid_value?: (string | null)
  */
 export interface SuppressionInventoryOutput {
 schema_version: SuppressionInventorySchemaVersion
+/**
+ * What the run was asked to narrow and whether it did. See
+ * [`crate::RequestOutcomes`] for the full contract.
+ *
+ * `fallow suppressions` accepts `--changed-since`, and an unresolvable ref
+ * widens the inventory to the whole project rather than failing the run.
+ * Until this member existed the only account of that was a stderr line,
+ * which `--quiet` removes, so an inventory read as scoped to the change
+ * could silently be the whole project's (issue #2734).
+ *
+ * The command applies no diff filter, so the object carries the
+ * `changed-since` entry only. Omitted when the run was asked for nothing,
+ * which keeps an inventory that passed no narrowing flag byte-identical and
+ * leaves `schema_version` at `1`.
+ */
+request_outcomes?: (RequestOutcomes | null)
 summary: SuppressionInventorySummary
 /**
  * Per-file suppression listings, sorted by path then line.
@@ -15283,3 +15913,8 @@ export type UnusedDependency = UnusedDependencyFinding | UnusedDevDependencyFind
  * this alias; new code should narrow on the specific wrapper variant.
  */
 export type UnusedMember = UnusedClassMemberFinding | UnusedEnumMemberFinding | UnusedStoreMemberFinding;
+
+/**
+ * @deprecated Renamed to BaselineStaleness in 3.27.0, when dead-code and dupes started carrying the same shape. The members are unchanged.
+ */
+export type HealthBaselineStaleness = BaselineStaleness;