fallow 2.98.0 → 2.100.0

package/README.md

@@ -88,6 +88,23 @@ Fallow gives AI agents structured repo truth instead of forcing them to infer ev
 
 Every issue in `--format json` carries a machine-actionable `actions` array with an `auto_fixable` flag so agents can self-correct.
 
+### MCP server
+
+Agents that speak MCP can launch the bundled `fallow-mcp` server. Installed as a devDependency, the binary lives in `node_modules/.bin/` and is not on your `PATH`, so launch it through your package manager's runner:
+
+```json
+{
+  "mcpServers": {
+    "fallow": {
+      "command": "npx",
+      "args": ["fallow-mcp"]
+    }
+  }
+}
+```
+
+Swap `npx` for `pnpm exec` / `yarn` / `bunx` to match your package manager. If `fallow-mcp` is installed globally (on your `PATH`), `"command": "fallow-mcp"` works directly. See the [MCP integration guide](https://docs.fallow.tools/integrations/mcp).
+
 ## Framework support
 
 122 built-in plugins covering Next.js, Nuxt, Remix, Qwik, SvelteKit, Gatsby, Astro, Angular, NestJS, AdonisJS, Ember, Expo Router, Vite, Webpack, Vitest, Jest, Playwright, Cypress, Storybook, ESLint, TypeScript, Tailwind, UnoCSS, Prisma, Drizzle, Convex, Turborepo, Hardhat, and many more. Auto-detected from your `package.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.98.0",
+  "version": "2.100.0",
   "description": "Deterministic codebase intelligence for TypeScript and JavaScript. Quality, risk, architecture, dependencies, duplication, and safe cleanup evidence for humans, CI, and agents. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -83,13 +83,13 @@
     "@tanstack/intent": "0.0.42"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.98.0",
-    "@fallow-cli/darwin-x64": "2.98.0",
-    "@fallow-cli/linux-x64-gnu": "2.98.0",
-    "@fallow-cli/linux-arm64-gnu": "2.98.0",
-    "@fallow-cli/linux-x64-musl": "2.98.0",
-    "@fallow-cli/linux-arm64-musl": "2.98.0",
-    "@fallow-cli/win32-arm64-msvc": "2.98.0",
-    "@fallow-cli/win32-x64-msvc": "2.98.0"
+    "@fallow-cli/darwin-arm64": "2.100.0",
+    "@fallow-cli/darwin-x64": "2.100.0",
+    "@fallow-cli/linux-x64-gnu": "2.100.0",
+    "@fallow-cli/linux-arm64-gnu": "2.100.0",
+    "@fallow-cli/linux-x64-musl": "2.100.0",
+    "@fallow-cli/linux-arm64-musl": "2.100.0",
+    "@fallow-cli/win32-arm64-msvc": "2.100.0",
+    "@fallow-cli/win32-x64-msvc": "2.100.0"
   }
 }

package/schema.json

@@ -178,6 +178,7 @@
         "coverage-gaps": "off",
         "feature-flags": "off",
         "stale-suppressions": "warn",
+        "require-suppression-reason": "off",
         "unused-catalog-entries": "warn",
         "empty-catalog-groups": "warn",
         "unresolved-catalog-references": "error",
@@ -234,7 +235,7 @@
       "default": []
     },
     "rulePacks": {
-      "description": "Paths to declarative rule-pack files (JSON or JSONC), relative to the\nproject root. Each pack declares `banned-call` / `banned-import` rules\nthat report as `policy-violation` findings. Packs are pure data: no\nproject code is executed. Invalid or missing packs fail config load.",
+      "description": "Paths to declarative rule-pack files (JSON or JSONC), relative to the\nproject root. Each pack declares `banned-call`, `banned-import`, or\n`banned-effect` rules that report as `policy-violation` findings. Packs\nare pure data: no project code is executed. Invalid or missing packs\nfail config load.",
       "type": "array",
       "items": {
         "type": "string"
@@ -1046,7 +1047,7 @@
           "default": "error"
         },
         "unused-component-props": {
-          "description": "Vue `<script setup>` `defineProps` declared prop referenced nowhere\ninside its own single-file component (neither `<script>` nor\n`<template>`). The single-file dead-input direction. Defaults to `warn`,\nnot `error`: a prop can be part of a deliberately-stable public component\nAPI, so analyzer confidence is lower; warn encodes that without failing\nCI.",
+          "description": "Vue `<script setup>` `defineProps`, Svelte 5 `$props()`, or React\ndeclared prop referenced nowhere inside its own component. The\nsingle-component dead-input direction. Defaults to `warn`, not `error`: a\nprop can be part of a deliberately-stable public component API, so\nanalyzer confidence is lower; warn encodes that without failing CI.",
           "$ref": "#/$defs/Severity",
           "default": "error"
         },
@@ -1139,6 +1140,11 @@
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
+        "require-suppression-reason": {
+          "description": "Opt-in suppression hygiene rule: when enabled, every `fallow-ignore-*`\ncomment and `@expected-unused` tag must carry a `-- <reason>` suffix.",
+          "$ref": "#/$defs/Severity",
+          "default": "off"
+        },
         "unused-catalog-entries": {
           "$ref": "#/$defs/Severity",
           "default": "warn"
@@ -1939,6 +1945,16 @@
             }
           ]
         },
+        "require-suppression-reason": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "unused-catalog-entries": {
           "anyOf": [
             {

package/skills/fallow/SKILL.md

@@ -95,6 +95,7 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | `fallow` | Run full codebase analysis: cleanup + duplication + health (default) | `--only`, `--skip`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--ci`, `--fail-on-issues`, `--group-by`, `--summary`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline`, `--score`, `--trend`, `--save-snapshot`, `--include-entry-exports` |
 | `dead-code` | Dead code analysis (`check` is an alias) | `--unused-exports`, `--changed-since`, `--changed-workspaces`, `--production`, `--file`, `--include-entry-exports`, `--stale-suppressions`, `--ci`, `--group-by`, `--summary`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline` |
 | `watch` | Watch for changes and re-run analysis | `--no-clear` |
+| `inspect` | Compose one evidence bundle for a file or exported symbol | `--file <path>`, `--symbol <file>:<export>` |
 | `fix` | Auto-remove unused exports/deps | `--dry-run`, `--yes` (required in non-TTY) |
 | `init` | Generate config file, AGENTS.md agent guide, or pre-commit hook | `--toml`, `--agents`, `--hooks`, `--branch` |
 | `hooks` | Inspect, install, or remove fallow-managed Git and agent hooks | `status`, `install --target git`, `install --target agent`, `uninstall --target git`, `uninstall --target agent` |
@@ -150,7 +151,7 @@ Run `fallow <command> --help` for the full flag list per command (see also refer
 | `boundary-violation` | `--boundary-violations` | - | `// fallow-ignore-next-line boundary-violation` | Imports crossing architecture zone boundaries. Presets: `layered`, `hexagonal`, `feature-sliced`, `bulletproof`; `autoDiscover` can create one zone per feature directory; per-rule `allowTypeOnly: [zones]` admits `import type` / `export type` crossings while still blocking value imports. Optional sections: `boundaries.coverage.requireAllFiles` reports unzoned source files (`allowUnmatched` globs exempt intentional ones), and `boundaries.calls.forbidden` bans callee patterns per zone (segment-aware and import-resolved, so `child_process.*` covers `node:child_process` named/namespace/default imports; direct callees only, zoned files only). The whole family shares the `boundary-violation` rule and suppression token (`boundary-call-violation` and `boundary-call-violations` accepted as aliases); start the rule at `warn` for a staged rollout |
 | `boundary-coverage` | - | - | `// fallow-ignore-file boundary-violation` | Source file matches no configured architecture boundary zone; Requires boundaries.coverage.requireAllFiles |
 | `boundary-call-violation` | - | - | `// fallow-ignore-next-line boundary-call-violation` | Zoned file calls a callee its zone forbids; Requires boundaries.calls.forbidden patterns |
-| `policy-violation` | `--policy-violations` | - | `// fallow-ignore-next-line policy-violation` | Calls or imports banned by a declarative rule pack (`rulePacks` config key lists standalone JSON/JSONC files of `banned-call` / `banned-import` rules; pure data, no project code executes). Findings identified as `<pack>/<rule-id>`. Default `warn` master; per-rule `severity` overrides per finding and the exit gate reads the effective severity. Invalid or missing packs fail config load with exit 2. `fallow rule-pack-schema` prints the pack JSON Schema. Use the scoped token to suppress one rule; bare `policy-violation` still covers every pack rule on the line or file. |
+| `policy-violation` | `--policy-violations` | - | `// fallow-ignore-next-line policy-violation` | Calls, imports, or catalogue-derived effects banned by a declarative rule pack (`rulePacks` config key lists standalone JSON/JSONC files of `banned-call`, `banned-import`, and `banned-effect` rules; pure data, no project code executes). Findings identified as `<pack>/<rule-id>`. Default `warn` master; per-rule `severity` overrides per finding and the exit gate reads the effective severity. Invalid or missing packs fail config load with exit 2. `fallow rule-pack-schema` prints the pack JSON Schema. Use the scoped token to suppress one rule; bare `policy-violation` still covers every pack rule on the line or file. |
 | `stale-suppression` | `--stale-suppressions` | - | - | `fallow-ignore` comments or `@expected-unused` JSDoc tags that no longer match any issue |
 | `unused-catalog-entry` | `--unused-catalog-entries` | yes | - | `pnpm-workspace.yaml` entries no workspace package.json references via `catalog:` (default `warn`) |
 | `empty-catalog-group` | `--empty-catalog-groups` | - | - | Named `catalogs.<name>:` groups in `pnpm-workspace.yaml` with no entries. Top-level `catalog:` placeholders are ignored. Default `warn`. |
@@ -172,8 +173,8 @@ Run `fallow <command> --help` for the full flag list per command (see also refer
 | `prop-drilling` | - | - | `// fallow-ignore-next-line prop-drilling` | A React/Preact prop is forwarded unchanged through 3+ pass-through components to a distant consumer; Opt-in: set rules.prop-drilling to warn or error to enable. Defaults to off. |
 | `thin-wrapper` | - | - | `// fallow-ignore-next-line thin-wrapper` | A React/Preact component whose whole body is a single spread-forwarded child render (a candidate for inlining); Opt-in: set rules.thin-wrapper to warn or error to enable. Defaults to off. |
 | `duplicate-prop-shape` | - | - | `// fallow-ignore-next-line duplicate-prop-shape` | Three or more React/Preact components across two or more files declare an identical prop-name set (a missing shared Props type); Opt-in: set rules.duplicate-prop-shape to warn or error to enable. Defaults to off. |
-| `route-collision` | - | - | - | Two or more Next.js App Router route files resolve to the same URL |
-| `dynamic-segment-name-conflict` | - | - | - | Sibling Next.js dynamic route segments use different slug names at the same position |
+| `route-collision` | - | - | `// fallow-ignore-file route-collision` | Two or more Next.js App Router route files resolve to the same URL |
+| `dynamic-segment-name-conflict` | - | - | `// fallow-ignore-file dynamic-segment-name-conflict` | Sibling Next.js dynamic route segments use different slug names at the same position |
 | `high-cyclomatic-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has high cyclomatic complexity |
 | `high-cognitive-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has high cognitive complexity |
 | `high-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function exceeds both complexity thresholds |
@@ -198,7 +199,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | Tool | Kind | License | Key params | Description |
 |---|---|---|---|---|
 | `code_execute` | composition | free | `code`, `timeout_ms`, `max_output_bytes` | Bounded read-only Code Mode for composing multiple fallow analysis calls in one JavaScript snippet. The snippet receives `{ fallow, root }`, returns JSON-serializable data, and can call read-only helpers such as `fallow.projectInfo`, `fallow.audit`, `fallow.checkHealth`, and `fallow.run(tool, params)` for the same allowlist. Mutating fix tools are not exposed. The sandbox has no filesystem, network, imports, `eval`, `Function`, `process`, `require`, `Deno`, `Bun`, or shell access. Params: `code`, optional `root`, `timeout_ms` (capped at 30000), and `max_output_bytes` (capped at 4000000). |
-| `analyze` | analysis | free | `issue_types`, `production`, `workspace`, `baseline`, `group_by`, `file` | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + re-export cycles (barrel files that form a structural loop, silently breaking re-exports) + boundary violations + rule-pack policy violations (banned calls and banned imports declared via the `rulePacks` config key) + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group |
+| `analyze` | analysis | free | `issue_types`, `production`, `workspace`, `baseline`, `group_by`, `file` | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + re-export cycles (barrel files that form a structural loop, silently breaking re-exports) + boundary violations + rule-pack policy violations (banned calls, imports, and catalogue-derived effects declared via the `rulePacks` config key) + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group |
 | `check_changed` | analysis | free | `since`, `baseline`, `fail_on_regression` | Incremental analysis of files changed since a git ref |
 | `security_candidates` | analysis | free | `gate`, `surface`, `changed_since`, `paths` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, severity, evidence, trace, optional `reachability`, blind-spot counters, and optional `unresolved_callee_diagnostics` samples for dynamic callee follow-up. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), where URL-category sinks may include `url_shape` (`fixed-origin-dynamic-path` or `dynamic-origin`), an optional `taint_flow` source-to-sink triple, and a stable `finding_id` (equal to the SARIF fingerprint) for cross-run correlation; there is no `impact` field (deciding exploitability is the agent's job). Set `surface: true` to include top-level `attack_surface[]` entries with defensive-boundary prompts for a verifier. Set `gate` to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires `changed_since`. `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow; `reachability.taint_confidence` tiers each reachable candidate as `arg-level` (sink argument traces to a same-module source read, strong) or `module-level` (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `surface`, `gate`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, untrusted-source reachability trace hops, and unresolved-callee diagnostics. See <https://docs.fallow.tools/cli/security-agent-verification> for the verifier packet and verdict recipe. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
 | `inspect_target` | analysis | free | `target`, `production` | Compose one evidence bundle for a file or exported symbol. File targets use `target: { type: "file", file }`; symbol targets use `target: { type: "symbol", file, export_name }`. Returns `kind: "inspect_target"`, normalized target identity, `trace_file`, optional `trace_export`, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, and security candidates scoped to the file. Evidence sections carry `status` and `scope`; symbol targets warn when supporting evidence is file-scoped. Supports `root`, `config`, `production`, `workspace`, `no_cache`, and `threads`; `production` applies to trace, dead-code, and health evidence only. Raise `FALLOW_TIMEOUT_SECS` for large repos. |

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

@@ -16,6 +16,7 @@ Complete command and flag specifications for all fallow CLI commands.
 - [`audit`: Changed-File Quality Gate](#audit-changed-file-quality-gate)
 - [`flags`: Feature Flag Detection](#flags-feature-flag-detection)
 - [`security`: Security Candidate Detection](#security-security-candidate-detection)
+- [`inspect`: Target Evidence Bundle](#inspect-target-evidence-bundle)
 - [`explain`: Rule Explanation](#explain-rule-explanation)
 - [`schema`: CLI Introspection](#schema-cli-introspection)
 - [`config-schema`: Config JSON Schema](#config-schema-config-json-schema)
@@ -77,7 +78,7 @@ Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#
 | `--circular-deps` | Circular dependencies |
 | `--re-export-cycles` | Re-export cycles (`kind: multi-node` for barrel files re-exporting from each other in a loop, `kind: self-loop` for a barrel re-exporting from itself). File-scoped finding; chain propagation through the loop is a no-op so imports may silently come up empty. Distinct from `--circular-deps` (runtime cycles). |
 | `--boundary-violations` | Boundary violations (imports crossing architecture zone boundaries, unzoned source files when `boundaries.coverage.requireAllFiles` is set, and forbidden calls from `boundaries.calls.forbidden`; suppression token `boundary-violation`, with `boundary-call-violation` and `boundary-call-violations` accepted as aliases for the whole family) |
-| `--policy-violations` | Rule-pack policy violations (banned calls and banned imports declared via the `rulePacks` config key) |
+| `--policy-violations` | Rule-pack policy violations (banned calls, imports, and catalogue-derived effects declared via the `rulePacks` config key) |
 | `--stale-suppressions` | Stale suppression comments or `@expected-unused` JSDoc tags |
 | `--unused-catalog-entries` | Unused pnpm catalog entries |
 | `--empty-catalog-groups` | Empty named pnpm catalog groups |
@@ -504,7 +505,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.100.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -891,7 +892,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.100.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -966,7 +967,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.100.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1066,7 +1067,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "2.98.0",
+  "version": "2.100.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1095,7 +1096,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "2.98.0",
+  "version": "2.100.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1159,6 +1160,55 @@ Every finding also carries an agent-actionable `candidate { source_kind, sink, b
 
 ---
 
+## `inspect`: Target Evidence Bundle
+
+Compose one evidence bundle before editing a file or exported symbol. This is the CLI equivalent of the MCP `inspect_target` tool.
+
+### Usage
+
+```bash
+fallow inspect --file src/api.ts --format json --quiet
+fallow inspect --symbol src/api.ts:fetchUser --format json --quiet
+```
+
+### Target Flags
+
+| Flag | Description |
+|------|-------------|
+| `--file <PATH>` | Inspect one project-relative file |
+| `--symbol <FILE:EXPORT>` | Inspect one exported symbol. Supporting dead-code, duplication, complexity, and security evidence is file-scoped in the first version |
+
+Common global flags: `--format`, `--quiet`, `--root`, `--config`, `--workspace`, `--production`, `--no-cache`, `--threads`.
+
+### JSON Output Structure
+
+```json
+{
+  "kind": "inspect_target",
+  "target": { "type": "file", "file": "src/api.ts" },
+  "identity": {
+    "file": "src/api.ts",
+    "is_reachable": true,
+    "is_entry_point": false,
+    "export_count": 3,
+    "import_count": 2,
+    "imported_by_count": 1
+  },
+  "evidence": {
+    "trace_file": { "status": "ok", "scope": "file", "data": {} },
+    "dead_code": { "status": "ok", "scope": "file", "data": {} },
+    "duplication": { "status": "ok", "scope": "project_filtered_to_file", "data": {} },
+    "complexity": { "status": "ok", "scope": "project_filtered_to_file", "data": {} },
+    "security": { "status": "ok", "scope": "file", "data": {} }
+  },
+  "warnings": []
+}
+```
+
+Each evidence section carries `status` and `scope`. Non-fatal child-analysis failures become section-level errors and warnings, so callers can still use the remaining evidence.
+
+---
+
 ## `explain`: Rule Explanation
 
 Print rule rationale, examples, fix guidance, and docs URL for one issue type without running analysis.
@@ -1645,7 +1695,7 @@ Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid
 | `human` | Colored terminal output | Interactive use |
 | `json` | Machine-readable JSON | Agent integration, CI pipelines |
 | `sarif` | Static Analysis Results Interchange Format | GitHub Code Scanning, SARIF-compatible tools |
-| `compact` | Grep-friendly: `type:path:line:name` per line | Quick filtering |
+| `compact` | Grep-friendly: one issue per line. Dupes lines include `code-duplication:path:start-end:fingerprint=dup:<id>,...` | Quick filtering |
 | `markdown` | Markdown tables | Documentation, PR comments |
 | `codeclimate` / `gitlab-codequality` | CodeClimate JSON array | GitLab Code Quality, CodeClimate-compatible tools |
 | `pr-comment-github` / `pr-comment-gitlab` | Sticky PR/MR comment markdown with HTML-comment marker for upsert | Posted by the action / template `comment.sh` scripts |
@@ -1712,7 +1762,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.100.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1872,7 +1922,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.100.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1916,11 +1966,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.100.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.98.0",
+    "version": "2.100.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -25,7 +25,7 @@
 
 
 /**
- * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator (for example `dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, `explain`, `impact`, `security`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `review-envelope`, and `review-reconcile`). Consumers should branch on `kind` instead of probing for unique field presence. `--legacy-envelope` removes only the document-root `kind` for one compatibility cycle. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array.
+ * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator (for example `dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, `explain`, `inspect_target`, `impact`, `security`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `review-envelope`, and `review-reconcile`). Consumers should branch on `kind` instead of probing for unique field presence. `--legacy-envelope` removes only the document-root `kind` for one compatibility cycle. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array.
  */
 export type FallowJsonOutput = (FallowOutput | CodeClimateOutput)
 /**
@@ -51,6 +51,8 @@ export type FallowOutput = ((AuditOutput & {
 kind: "audit"
 }) | (ExplainOutput & {
 kind: "explain"
+}) | (InspectOutput & {
+kind: "inspect_target"
 }) | (ReviewEnvelopeOutput & {
 kind: "review-envelope"
 }) | (ReviewReconcileOutput & {
@@ -75,6 +77,10 @@ kind: "impact"
 kind: "impact-cross-repo"
 }) | ((SecurityOutput | SecuritySummaryOutput) & {
 kind: "security"
+}) | (SecuritySurvivorsOutput & {
+kind: "security-survivors"
+}) | (SecurityBlindSpotsOutput & {
+kind: "security-blind-spots"
 }) | (CheckOutput & {
 kind: "dead-code"
 }) | (CombinedOutput & {
@@ -138,10 +144,12 @@ export type AuditGate = ("new-only" | "all")
  * Current per-instance flips:
  *
  * - `remove-catalog-entry` (`unused-catalog-entries`): `true` only when the
- *   finding's `hardcoded_consumers` array is empty. When a workspace
- *   package still pins a hardcoded version of the same package, `fallow fix`
- *   skips the entry to avoid breaking `pnpm install`, and the action is
- *   emitted with `auto_fixable: false`.
+ *   finding's `hardcoded_consumers` array is empty and the source is
+ *   `pnpm-workspace.yaml`. When a workspace package still pins a hardcoded
+ *   version of the same package, `fallow fix` skips the entry to avoid
+ *   breaking `pnpm install`. Bun `package.json` catalog entries are also
+ *   emitted with `auto_fixable: false` because the current fixer is
+ *   YAML-only.
  * - `remove-dependency` vs `move-dependency` (dependency findings): when the
  *   finding's `used_in_workspaces` array is non-empty, the primary action
  *   flips to `move-dependency` with `auto_fixable: false` (`fallow fix` will
@@ -172,7 +180,7 @@ export type IssueAction = (FixAction | SuppressLineAction | SuppressFileAction |
  * Discriminant string for [`FixAction`]. Kebab-case per the JSON output
  * contract.
  */
-export type FixActionType = ("remove-export" | "delete-file" | "remove-dependency" | "move-dependency" | "remove-enum-member" | "remove-class-member" | "resolve-import" | "install-dependency" | "remove-duplicate" | "move-to-dev" | "refactor-cycle" | "refactor-re-export-cycle" | "refactor-boundary" | "export-type" | "remove-catalog-entry" | "remove-empty-catalog-group" | "update-catalog-reference" | "add-catalog-entry" | "remove-catalog-reference" | "remove-dependency-override" | "fix-dependency-override" | "resolve-policy-violation" | "move-to-server-module" | "split-mixed-barrel" | "hoist-directive" | "wire-server-action" | "provide-inject" | "use-load-data" | "render-component" | "use-component-prop" | "emit-component-event" | "wire-svelte-event" | "resolve-route-collision" | "resolve-dynamic-segment-name-conflict")
+export type FixActionType = ("remove-export" | "delete-file" | "remove-dependency" | "move-dependency" | "remove-enum-member" | "remove-class-member" | "resolve-import" | "install-dependency" | "remove-duplicate" | "move-to-dev" | "refactor-cycle" | "refactor-re-export-cycle" | "refactor-boundary" | "export-type" | "remove-catalog-entry" | "remove-empty-catalog-group" | "update-catalog-reference" | "add-catalog-entry" | "remove-catalog-reference" | "remove-dependency-override" | "fix-dependency-override" | "resolve-policy-violation" | "move-to-server-module" | "split-mixed-barrel" | "hoist-directive" | "wire-server-action" | "provide-inject" | "use-load-data" | "render-component" | "use-component-prop" | "emit-component-event" | "wire-svelte-event" | "resolve-route-collision" | "resolve-dynamic-segment-name-conflict" | "add-suppression-reason" | "remove-stale-suppression")
 /**
  * Singleton discriminant for [`SuppressLineAction`].
  */
@@ -237,7 +245,7 @@ export type ReExportCycleKind = ("multi-node" | "self-loop")
 /**
  * Which rule-pack rule kind produced a [`PolicyViolation`].
  */
-export type PolicyRuleKind = ("banned-call" | "banned-import")
+export type PolicyRuleKind = ("banned-call" | "banned-import" | "banned-effect")
 /**
  * Effective severity of a single [`PolicyViolation`]. Per-rule `severity`
  * overrides the `rules."policy-violation"` master; `off` rules emit nothing,
@@ -253,6 +261,10 @@ export type SuppressionOrigin = ({
  * The issue kind token from the comment (e.g., "unused-exports"), or None for blanket.
  */
 issue_kind?: (string | null)
+/**
+ * Human-authored reason after `--`, when present.
+ */
+reason?: (string | null)
 /**
  * Whether this was a file-level suppression.
  */
@@ -272,6 +284,10 @@ type: "comment"
  * The name of the export that was tagged.
  */
 export_name: string
+/**
+ * Human-authored reason after `--`, when present.
+ */
+reason?: (string | null)
 type: "jsdoc_tag"
 })
 /**
@@ -563,6 +579,10 @@ export type RefactoringTargetActionType = ("apply-refactoring" | "suppress-line"
  * Direction of a metric's change, semantically (improving/declining/stable).
  */
 export type TrendDirection = ("improving" | "declining" | "stable")
+/**
+ * Detector status codes for framework health observability.
+ */
+export type FrameworkHealthDetectorStatus = ("active" | "disabled_by_config" | "abstained" | "not_checked")
 /**
  * Discriminant for [`CssCandidateAction::kind`].
  */
@@ -571,6 +591,17 @@ export type CssCandidateActionType = ("verify-unused" | "verify-undefined" | "co
  * Discriminant for [`UnusedAtRule::kind`].
  */
 export type UnusedAtRuleKind = ("property-registration" | "layer")
+export type InspectTargetDescriptor = ({
+file: string
+type: "file"
+} | {
+file: string
+export_name: string
+type: "symbol"
+})
+export type InspectIdentity = (InspectFileIdentity | InspectSymbolIdentity)
+export type InspectSectionStatus = ("ok" | "error")
+export type InspectEvidenceScope = ("symbol" | "file" | "project_filtered_to_file")
 /**
  * Singleton GitHub review-event marker.
  */
@@ -720,6 +751,18 @@ export type SkippedSecurityCalleeReason = ("computed-member" | "dynamic-dispatch
  * Syntactic expression shape for a skipped security callee.
  */
 export type SkippedSecurityCalleeExpressionKind = ("static-member-expression" | "computed-member-expression" | "identifier" | "other")
+/**
+ * The `fallow security survivors --format json` schema version.
+ */
+export type SecuritySurvivorsSchemaVersion = "2"
+/**
+ * Verifier verdict status accepted by `fallow security survivors`.
+ */
+export type SecurityVerifierVerdictStatus = ("survivor" | "dismissed" | "needs-human-review")
+/**
+ * The `fallow security blind-spots --format json` schema version.
+ */
+export type SecurityBlindSpotsSchemaVersion = "1"
 /**
  * Discriminator value for [`CodeClimateIssue::kind`].
  */
@@ -1021,7 +1064,8 @@ boundary_coverage_violations?: BoundaryCoverageViolationFinding[]
  */
 boundary_call_violations?: BoundaryCallViolationFinding[]
 /**
- * Banned calls and banned imports matched by declarative rule packs
+ * Banned calls, imports, and catalogue-derived effects matched by
+ * declarative rule packs
  * (`rulePacks` config). Wrapped in [`PolicyViolationFinding`] so each
  * entry carries a typed `actions` array natively. Each finding carries
  * its effective per-rule severity.
@@ -1032,24 +1076,25 @@ policy_violations?: PolicyViolationFinding[]
  */
 stale_suppressions?: StaleSuppression[]
 /**
- * Entries in pnpm-workspace.yaml's catalog: or catalogs: sections not
- * referenced by any workspace package via the catalog: protocol. Wrapped
- * in [`UnusedCatalogEntryFinding`] so each entry carries a typed
+ * Entries in package manager catalog sections not referenced by any
+ * workspace package via the catalog: protocol. Supports
+ * `pnpm-workspace.yaml` catalogs and Bun root `package.json` catalogs.
+ * Wrapped in [`UnusedCatalogEntryFinding`] so each entry carries a typed
  * `actions` array natively, with per-instance `auto_fixable` derived
- * from `hardcoded_consumers`.
+ * from `hardcoded_consumers` and the catalog source file.
  */
 unused_catalog_entries?: UnusedCatalogEntryFinding[]
 /**
- * Named groups under pnpm-workspace.yaml's catalogs: section that declare
- * no package entries. The top-level catalog: map is not reported. Wrapped
- * in [`EmptyCatalogGroupFinding`].
+ * Named groups under package manager catalogs sections that declare no
+ * package entries. The top-level catalog: map is not reported. Wrapped in
+ * [`EmptyCatalogGroupFinding`].
  */
 empty_catalog_groups?: EmptyCatalogGroupFinding[]
 /**
  * Workspace package.json references to catalogs (`catalog:` or
- * `catalog:<name>`) that do not declare the consumed package. pnpm install
- * will error until the named catalog grows to include the package or the
- * reference is switched / removed. Wrapped in
+ * `catalog:<name>`) that do not declare the consumed package. The package
+ * manager install will error until the named catalog grows to include the
+ * package or the reference is switched / removed. Wrapped in
  * [`UnresolvedCatalogReferenceFinding`] with the discriminated
  * `add-catalog-entry` / `update-catalog-reference` primary at position 0.
  */
@@ -1121,8 +1166,8 @@ route_collisions?: RouteCollisionFinding[]
  */
 dynamic_segment_name_conflicts?: DynamicSegmentNameConflictFinding[]
 /**
- * Vue `<script setup>` `defineProps` props referenced nowhere in their own
- * SFC (neither `<script>` nor `<template>`). Wrapped in
+ * Vue `<script setup>` `defineProps`, Svelte 5 `$props()`, and React props
+ * referenced nowhere in their own component. Wrapped in
  * [`UnusedComponentPropFinding`] so each entry carries a typed `actions`
  * array natively. Default severity is `warn`.
  */
@@ -1292,7 +1337,7 @@ unprovided_injects?: number
  */
 unrendered_components?: number
 /**
- * Vue `<script setup>` props referenced nowhere inside their own SFC.
+ * Vue, Svelte, or React props referenced nowhere inside their own component.
  */
 unused_component_props?: number
 /**
@@ -1365,7 +1410,8 @@ boundary_coverage_violations?: number
  */
 boundary_call_violations?: number
 /**
- * Banned calls and banned imports matched by declarative rule packs.
+ * Banned calls, imports, and catalogue-derived effects matched by
+ * declarative rule packs.
  */
 policy_violations?: number
 /**
@@ -1452,11 +1498,12 @@ type: FixActionType
  * FINDING, not per action type: the same `type` may carry
  * `auto_fixable: true` on one finding and `auto_fixable: false` on
  * another when per-instance guards in the applier discriminate (e.g.
- * `remove-catalog-entry` flips on `hardcoded_consumers`, the primary
- * dependency action flips between `remove-dependency` /
- * `move-dependency` on `used_in_workspaces`). Filter on this bool of
- * each individual action, not on `type`. See the [`IssueAction`]
- * enum-level docs for the full list of per-instance flips.
+ * `remove-catalog-entry` flips on `hardcoded_consumers` and catalog
+ * source file, the primary dependency action flips between
+ * `remove-dependency` / `move-dependency` on `used_in_workspaces`).
+ * Filter on this bool of each individual action, not on `type`. See the
+ * [`IssueAction`] enum-level docs for the full list of per-instance
+ * flips.
  */
 auto_fixable: boolean
 /**
@@ -2122,7 +2169,7 @@ introduced?: (AuditIntroduced | null)
  */
 export interface TestOnlyDependencyFinding {
 /**
- * Production dependency that is only imported by test files , consider
+ * Production dependency that is only imported by test files, consider
  * moving to devDependencies.
  */
 package_name: string
@@ -2364,12 +2411,12 @@ introduced?: (AuditIntroduced | null)
 }
 /**
  * Wire-shape envelope for a [`PolicyViolation`] finding. Carries actions for
- * replacing the banned call or import, or suppressing it with a scoped
+ * replacing the banned call, import, or effect, or suppressing it with a scoped
  * `policy-violation:<pack>/<rule-id>` token.
  */
 export interface PolicyViolationFinding {
 /**
- * The source file containing the banned call or import.
+ * The source file containing the banned call, import, or effectful usage.
  */
 path: string
 /**
@@ -2392,8 +2439,8 @@ rule_id: string
 kind: PolicyRuleKind
 /**
  * What matched: the written callee path for `banned-call` (e.g.
- * `cp.exec`), or the raw import specifier for `banned-import` (e.g.
- * `moment/locale/nl`).
+ * `cp.exec`), the raw import specifier for `banned-import` (e.g.
+ * `moment/locale/nl`), or `<effect>: <callee>` for `banned-effect`.
  */
 matched: string
 severity: PolicyViolationSeverity
@@ -2428,12 +2475,20 @@ line: number
  */
 col: number
 origin: SuppressionOrigin
+/**
+ * True when `rules.require-suppression-reason` reported a suppression
+ * comment or tag that has no reason.
+ */
+missing_reason?: boolean
+/**
+ * Suggested next steps. Always emitted.
+ */
+actions: IssueAction[]
 }
 /**
  * Wire-shape envelope for an [`UnusedCatalogEntry`] finding. Per-instance
- * `auto_fixable` flips to `false` when `hardcoded_consumers` is non-empty:
- * the entry cannot be removed safely while a workspace package still pins
- * the same package via a hardcoded version range.
+ * `auto_fixable` flips to `false` when `hardcoded_consumers` is non-empty or
+ * the source is not `pnpm-workspace.yaml`.
  */
 export interface UnusedCatalogEntryFinding {
 /**
@@ -2441,16 +2496,16 @@ export interface UnusedCatalogEntryFinding {
  */
 entry_name: string
 /**
- * Catalog group: `"default"` for the top-level `catalog:` map, or the
- * named catalog key for entries declared under `catalogs.<name>:`.
+ * Catalog group: `"default"` for the default catalog map, or the named
+ * catalog key for entries declared under `catalogs.<name>`.
  */
 catalog_name: string
 /**
- * Path to `pnpm-workspace.yaml`, relative to the analyzed root.
+ * Path to the catalog source file, relative to the analyzed root.
  */
 path: string
 /**
- * 1-based line number of the catalog entry within `pnpm-workspace.yaml`.
+ * 1-based line number of the catalog entry within the source file.
  */
 line: number
 /**
@@ -2472,20 +2527,20 @@ introduced?: (AuditIntroduced | null)
 }
 /**
  * Wire-shape envelope for an [`EmptyCatalogGroup`] finding. Carries a
- * straightforward `remove-empty-catalog-group` primary plus a YAML-comment
- * suppress.
+ * `remove-empty-catalog-group` primary. YAML-sourced findings also include a
+ * YAML-comment suppress action.
  */
 export interface EmptyCatalogGroupFinding {
 /**
- * Catalog group name declared under the top-level `catalogs:` map.
+ * Catalog group name declared under the `catalogs` map.
  */
 catalog_name: string
 /**
- * Path to `pnpm-workspace.yaml`, relative to the analyzed root.
+ * Path to the catalog source file, relative to the analyzed root.
  */
 path: string
 /**
- * 1-based line number of the empty group header within `pnpm-workspace.yaml`.
+ * 1-based line number of the empty group header within the source file.
  */
 line: number
 /**
@@ -2531,10 +2586,10 @@ path: string
  */
 line: number
 /**
- * Other catalogs (in the same `pnpm-workspace.yaml`) that DO declare this
- * package. Empty when no catalog has the package. Sorted lexicographically.
- * Lets agents and humans decide whether to switch the reference to a
- * different catalog or to add the entry to the named catalog.
+ * Other catalogs in the same catalog source that DO declare this package.
+ * Empty when no catalog has the package. Sorted lexicographically. Lets
+ * agents and humans decide whether to switch the reference to a different
+ * catalog or to add the entry to the named catalog.
  */
 available_in_catalogs?: string[]
 /**
@@ -2956,11 +3011,11 @@ introduced?: (AuditIntroduced | null)
  */
 export interface UnusedComponentPropFinding {
 /**
- * The `.vue` SFC declaring the unused prop.
+ * The component file declaring the unused prop.
  */
 path: string
 /**
- * The component name (the `.vue` file stem).
+ * The component name.
  */
 component_name: string
 /**
@@ -3900,6 +3955,11 @@ health_trend?: (HealthTrend | null)
  * back to the report root.
  */
 actions_meta?: (HealthActionsMeta | null)
+/**
+ * Optional framework-specific detector coverage. Present only when the
+ * health run already needed the dead-code analysis output.
+ */
+framework_health?: (FrameworkHealthDiagnostics | null)
 /**
  * Structural CSS analytics (specificity hotspots, `!important` density,
  * over-complex selectors, deep nesting). Present only with `--css`.
@@ -5537,6 +5597,37 @@ reason: string
  */
 scope: string
 }
+/**
+ * Framework-specific health detector coverage surfaced for agent consumers.
+ */
+export interface FrameworkHealthDiagnostics {
+/**
+ * Detected framework IDs, sorted and deduplicated.
+ */
+detected_frameworks: string[]
+/**
+ * Detector coverage for the detected frameworks.
+ */
+detectors: FrameworkHealthDetector[]
+}
+/**
+ * Status for one framework-specific health detector.
+ */
+export interface FrameworkHealthDetector {
+/**
+ * Rule or detector ID, matching fallow's stable rule names where possible.
+ */
+id: string
+/**
+ * Framework ID that made this detector relevant.
+ */
+framework: string
+status: FrameworkHealthDetectorStatus
+/**
+ * Stable reason code for non-active statuses.
+ */
+reason?: (string | null)
+}
 /**
  * Structural CSS analytics surfaced by `fallow health --css`.
  */
@@ -6330,6 +6421,45 @@ example: string
 how_to_fix: string
 docs: string
 }
+/**
+ * Envelope emitted by `fallow inspect --format json`.
+ */
+export interface InspectOutput {
+target: InspectTargetDescriptor
+identity: InspectIdentity
+evidence: InspectEvidence
+warnings: string[]
+}
+export interface InspectFileIdentity {
+file: string
+is_reachable?: unknown
+is_entry_point?: unknown
+export_count?: (number | null)
+import_count?: (number | null)
+imported_by_count?: (number | null)
+}
+export interface InspectSymbolIdentity {
+file: string
+export_name: string
+file_reachable?: unknown
+is_entry_point?: unknown
+is_used?: unknown
+reason?: unknown
+}
+export interface InspectEvidence {
+trace_file: InspectEvidenceSection
+trace_export?: (InspectEvidenceSection | null)
+dead_code: InspectEvidenceSection
+duplication: InspectEvidenceSection
+complexity: InspectEvidenceSection
+security: InspectEvidenceSection
+}
+export interface InspectEvidenceSection {
+status: InspectSectionStatus
+scope: InspectEvidenceScope
+message?: (string | null)
+data?: unknown
+}
 /**
  * Envelope emitted by `fallow --format review-github` / `review-gitlab`.
  */
@@ -6684,6 +6814,11 @@ health_trend?: (HealthTrend | null)
  * back to the report root.
  */
 actions_meta?: (HealthActionsMeta | null)
+/**
+ * Optional framework-specific detector coverage. Present only when the
+ * health run already needed the dead-code analysis output.
+ */
+framework_health?: (FrameworkHealthDiagnostics | null)
 /**
  * Structural CSS analytics (specificity hotspots, `!important` density,
  * over-complex selectors, deep nesting). Present only with `--css`.
@@ -7106,7 +7241,8 @@ boundary_coverage_violations?: BoundaryCoverageViolationFinding[]
  */
 boundary_call_violations?: BoundaryCallViolationFinding[]
 /**
- * Banned calls and banned imports matched by declarative rule packs
+ * Banned calls, imports, and catalogue-derived effects matched by
+ * declarative rule packs
  * (`rulePacks` config). Wrapped in [`PolicyViolationFinding`] so each
  * entry carries a typed `actions` array natively. Each finding carries
  * its effective per-rule severity.
@@ -7117,24 +7253,25 @@ policy_violations?: PolicyViolationFinding[]
  */
 stale_suppressions?: StaleSuppression[]
 /**
- * Entries in pnpm-workspace.yaml's catalog: or catalogs: sections not
- * referenced by any workspace package via the catalog: protocol. Wrapped
- * in [`UnusedCatalogEntryFinding`] so each entry carries a typed
+ * Entries in package manager catalog sections not referenced by any
+ * workspace package via the catalog: protocol. Supports
+ * `pnpm-workspace.yaml` catalogs and Bun root `package.json` catalogs.
+ * Wrapped in [`UnusedCatalogEntryFinding`] so each entry carries a typed
  * `actions` array natively, with per-instance `auto_fixable` derived
- * from `hardcoded_consumers`.
+ * from `hardcoded_consumers` and the catalog source file.
  */
 unused_catalog_entries?: UnusedCatalogEntryFinding[]
 /**
- * Named groups under pnpm-workspace.yaml's catalogs: section that declare
- * no package entries. The top-level catalog: map is not reported. Wrapped
- * in [`EmptyCatalogGroupFinding`].
+ * Named groups under package manager catalogs sections that declare no
+ * package entries. The top-level catalog: map is not reported. Wrapped in
+ * [`EmptyCatalogGroupFinding`].
  */
 empty_catalog_groups?: EmptyCatalogGroupFinding[]
 /**
  * Workspace package.json references to catalogs (`catalog:` or
- * `catalog:<name>`) that do not declare the consumed package. pnpm install
- * will error until the named catalog grows to include the package or the
- * reference is switched / removed. Wrapped in
+ * `catalog:<name>`) that do not declare the consumed package. The package
+ * manager install will error until the named catalog grows to include the
+ * package or the reference is switched / removed. Wrapped in
  * [`UnresolvedCatalogReferenceFinding`] with the discriminated
  * `add-catalog-entry` / `update-catalog-reference` primary at position 0.
  */
@@ -7206,8 +7343,8 @@ route_collisions?: RouteCollisionFinding[]
  */
 dynamic_segment_name_conflicts?: DynamicSegmentNameConflictFinding[]
 /**
- * Vue `<script setup>` `defineProps` props referenced nowhere in their own
- * SFC (neither `<script>` nor `<template>`). Wrapped in
+ * Vue `<script setup>` `defineProps`, Svelte 5 `$props()`, and React props
+ * referenced nowhere in their own component. Wrapped in
  * [`UnusedComponentPropFinding`] so each entry carries a typed `actions`
  * array natively. Default severity is `warn`.
  */
@@ -8162,6 +8299,123 @@ coverage_unavailable: number
 runtime_unknown: number
 not_collected: number
 }
+/**
+ * The `fallow security survivors --format json` envelope.
+ */
+export interface SecuritySurvivorsOutput {
+schema_version: SecuritySurvivorsSchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+summary: SecuritySurvivorsSummary
+/**
+ * Verifier-retained candidates keyed by finding id.
+ */
+survivors: {
+[k: string]: SecuritySurvivor
+}
+/**
+ * Ambiguous candidates keyed by finding id. These are not dismissed and are
+ * kept explicit so queues can decide whether to include them.
+ */
+needs_human_review: {
+[k: string]: SecuritySurvivor
+}
+}
+/**
+ * Aggregate counts for survivor rendering.
+ */
+export interface SecuritySurvivorsSummary {
+candidates: number
+verdicts: number
+survivors: number
+dismissed: number
+needs_human_review: number
+unverdicted: number
+}
+/**
+ * One verifier-retained candidate row.
+ */
+export interface SecuritySurvivor {
+/**
+ * Stable candidate id from `security_findings[].finding_id`.
+ */
+finding_id: string
+verdict: SecurityVerifierVerdictStatus
+/**
+ * Short verifier reason.
+ */
+reason?: (string | null)
+/**
+ * Short verifier rationale.
+ */
+rationale?: (string | null)
+/**
+ * Optional verifier-provided confidence or review priority.
+ */
+confidence?: (string | null)
+/**
+ * Optional verifier-provided impact statement.
+ */
+impact?: (string | null)
+/**
+ * Optional verifier-owned remediation direction.
+ */
+fix_direction?: (string | null)
+candidate: SecurityFinding
+}
+/**
+ * The `fallow security blind-spots --format json` envelope.
+ */
+export interface SecurityBlindSpotsOutput {
+schema_version: SecurityBlindSpotsSchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+summary: SecurityBlindSpotsSummary
+/**
+ * Grouped unresolved callee diagnostics, derived from existing samples.
+ */
+groups: SecurityBlindSpotGroup[]
+}
+/**
+ * Aggregate counts for blind-spot output.
+ */
+export interface SecurityBlindSpotsSummary {
+unresolved_edge_files: number
+unresolved_callee_sites: number
+sampled_callee_sites: number
+}
+/**
+ * One actionable blind-spot group.
+ */
+export interface SecurityBlindSpotGroup {
+reason: SkippedSecurityCalleeReason
+expression_kind: SkippedSecurityCalleeExpressionKind
+/**
+ * Count in the bounded diagnostic sample.
+ */
+sampled_count: number
+/**
+ * Top files in this bounded diagnostic sample.
+ */
+files: SecurityBlindSpotFile[]
+/**
+ * Suggested next action for this group.
+ */
+suggestion: string
+}
+/**
+ * One file inside a blind-spot group.
+ */
+export interface SecurityBlindSpotFile {
+/**
+ * Project-relative source path.
+ */
+path: string
+/**
+ * Count in the bounded diagnostic sample.
+ */
+sampled_count: number
+}
 /**
  * Bare `fallow --format json` envelope.
  */