fallow 2.88.3 → 2.90.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.88.3",
+  "version": "2.90.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, 96 framework plugins.",
   "license": "MIT",
   "repository": {
@@ -83,13 +83,13 @@
     "@tanstack/intent": "0.0.41"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.88.3",
-    "@fallow-cli/darwin-x64": "2.88.3",
-    "@fallow-cli/linux-x64-gnu": "2.88.3",
-    "@fallow-cli/linux-arm64-gnu": "2.88.3",
-    "@fallow-cli/linux-x64-musl": "2.88.3",
-    "@fallow-cli/linux-arm64-musl": "2.88.3",
-    "@fallow-cli/win32-arm64-msvc": "2.88.3",
-    "@fallow-cli/win32-x64-msvc": "2.88.3"
+    "@fallow-cli/darwin-arm64": "2.90.0",
+    "@fallow-cli/darwin-x64": "2.90.0",
+    "@fallow-cli/linux-x64-gnu": "2.90.0",
+    "@fallow-cli/linux-arm64-gnu": "2.90.0",
+    "@fallow-cli/linux-x64-musl": "2.90.0",
+    "@fallow-cli/linux-arm64-musl": "2.90.0",
+    "@fallow-cli/win32-arm64-msvc": "2.90.0",
+    "@fallow-cli/win32-x64-msvc": "2.90.0"
   }
 }

package/schema.json

@@ -1188,11 +1188,11 @@
       ]
     },
     "SecurityConfig": {
-      "description": "Scopes the data-driven security matcher catalogue used by `fallow security`.\nAn absent block (or both `include`/`exclude` unset) admits every category.",
+      "description": "Scopes the security categories used by `fallow security`. An absent block\nadmits every catalogue category. `hardcoded-secret` is include-required and\nonly runs when explicitly listed in `security.categories.include`.",
       "type": "object",
       "properties": {
         "categories": {
-          "description": "Include/exclude filter over catalogue category ids (e.g. `dangerous-html`).",
+          "description": "Include/exclude filter over category ids (e.g. `dangerous-html`).",
           "anyOf": [
             {
               "$ref": "#/$defs/SecurityCategories"
@@ -1206,7 +1206,7 @@
       "additionalProperties": false
     },
     "SecurityCategories": {
-      "description": "Include/exclude lists scoping the active security matcher categories. When\n`include` is set, only those categories are active; `exclude` removes\ncategories from the admitted set. Both unset admits every category.",
+      "description": "Include/exclude lists scoping the active security categories. When `include`\nis set, only those categories are active; `exclude` removes categories from\nthe admitted set. Both unset admits catalogue categories. `hardcoded-secret`\nstill requires explicit inclusion.",
       "type": "object",
       "properties": {
         "include": {
@@ -1762,7 +1762,15 @@
     "CacheConfig": {
       "type": "object",
       "properties": {
+        "dir": {
+          "description": "Directory for fallow's persistent analysis cache. Relative paths resolve\nfrom the project root.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "maxSizeMb": {
+          "description": "Maximum size of the persistent extraction cache, in megabytes.",
           "type": [
             "integer",
             "null"

package/skills/fallow/SKILL.md

@@ -75,7 +75,7 @@ cargo install fallow-cli        # build from source
 | `health` | Function complexity analysis (also covers Angular templates as synthetic `<template>` findings: external `.html` files via `templateUrl` AND inline `@Component({ template: \`...\` })` literals; suppress external with `<!-- fallow-ignore-file complexity -->` at the top of the `.html` file, suppress inline with `// fallow-ignore-next-line complexity` directly above the `@Component` decorator) | `--complexity`, `--max-cyclomatic`, `--max-cognitive`, `--max-crap`, `--top`, `--sort`, `--file-scores`, `--hotspots`, `--ownership`, `--ownership-emails`, `--targets`, `--effort`, `--score`, `--min-score`, `--since`, `--min-commits`, `--save-snapshot`, `--trend`, `--coverage-gaps`, `--coverage`, `--coverage-root`, `--runtime-coverage`, `--min-invocations-hot`, `--min-observation-volume`, `--low-traffic-threshold`, `--workspace`, `--changed-workspaces`, `--baseline`, `--save-baseline` |
 | `audit` | Combined dead-code + complexity + duplication for changed files | `--base`, `--gate`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--explain`, `--explain-skipped`, `--dead-code-baseline`, `--health-baseline`, `--dupes-baseline`, `--max-crap`, `--coverage`, `--coverage-root`, `--include-entry-exports` |
 | `flags` | Detect feature flag patterns (env vars, SDK calls, config objects) | `--top` |
-| `security` | Surface opt-in local security candidates for agent verification (not confirmed vulnerabilities). Two rule families: the graph rule `client-server-leak` (a `"use client"` file reaching a non-public `process.env` secret) and a data-driven `tainted-sink` catalogue across 9 CWE categories (dangerous-html, command-injection, code-injection, sql-injection, ssrf, path-traversal, open-redirect, weak-crypto, unsafe-deserialization). Conservative non-literal trigger; parameterized SQL not flagged. Rules default off; suppress a file with `// fallow-ignore-file security-sink`; scope categories with `security.categories`. | `--format human|json|sarif`, `--changed-since`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
+| `security` | Surface opt-in local security candidates for agent verification (not confirmed vulnerabilities). Rule families include the graph rule `client-server-leak`, a data-driven `tainted-sink` catalogue, and the include-required `hardcoded-secret` category for provider-prefix credentials and high-entropy literals assigned to secret-shaped identifiers. Most catalogue rows require non-literal input; narrowly literal-aware rows flag deterministic unsafe literals. Rules default off; suppress a file with `// fallow-ignore-file security-sink`; scope categories with `security.categories`. `hardcoded-secret` runs only when listed in `security.categories.include`. | `--format human|json|sarif`, `--changed-since`, `--file`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
 | `explain` | Explain one issue type without running analysis | `<issue-type>`, `--format json` |
 | `license` | Manage the local license JWT for continuous/cloud runtime monitoring (activate, status, refresh, deactivate) | `activate --trial --email <addr>`, `activate --from-file`, `activate --stdin`, `status`, `refresh`, `deactivate` |
 | `telemetry` | Manage opt-in, off-by-default product telemetry (never collects code, paths, or names). Agents must not enable it; only the user may | `status`, `enable`, `disable`, `inspect --example` |
@@ -118,11 +118,11 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 |------|-------------|
 | `analyze` | 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 + 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` | Incremental analysis of files changed since a git ref |
-| `security_candidates` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, evidence, and trace; verify trace and evidence before editing code. Supports `root`, `config`, `workspace`, `changed_since`, `changed_workspaces`, `no_cache`, and `threads`; inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
+| `security_candidates` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, evidence, trace, optional `reachability`, and blind-spot counters. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), 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). `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow. Verify trace, reachability context, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, or untrusted-source reachability trace hops. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
 | `find_dupes` | Code duplication detection. Set `changed_since` to scope to changed files since a git ref. Set `min_occurrences` (≥ 2, default 2) to hide pair-only clones and focus on widespread copy-paste; JSON gains `stats.clone_groups_below_min_occurrences` when the filter hides anything. Each `clone_groups[]` entry carries a stable `fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions; pass it to `trace_clone` to deep-dive that group |
 | `fix_preview` | Dry-run auto-fix preview |
 | `fix_apply` | Apply auto-fixes (destructive) |
-| `check_health` | Complexity metrics, health scores, hotspots, and refactoring targets. Optional `runtime_coverage` merges a V8 or Istanbul dump; tune it with `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), and `low_traffic_threshold` (default 0.001). When runtime evidence combines with static usage, test coverage, CRAP/complexity, ownership, or change scope, read `coverage_intelligence` for stable `fallow:coverage-intel:<hash>` recommendations. Set `group_by` to `owner`, `directory`, `package`, or `section` for per-group `vital_signs` / `health_score`; SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field |
+| `check_health` | Complexity metrics, health scores, hotspots, and refactoring targets. Set `complexity_breakdown: true` to add a per-decision-point `contributions[]` array to each complexity finding (each `else-if`, nested `if`, boolean operator, loop, `case`, etc. with its source line and cyclomatic/cognitive weight) so you can explain WHY a function scored high and pinpoint refactor targets. Optional `runtime_coverage` merges a V8 or Istanbul dump; tune it with `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), and `low_traffic_threshold` (default 0.001). When runtime evidence combines with static usage, test coverage, CRAP/complexity, ownership, or change scope, read `coverage_intelligence` for stable `fallow:coverage-intel:<hash>` recommendations. Set `group_by` to `owner`, `directory`, `package`, or `section` for per-group `vital_signs` / `health_score`; SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field |
 | `check_runtime_coverage` | Merge V8 or Istanbul runtime-coverage data into the health report. One local capture is free; continuous/cloud or multi-capture runtime monitoring is paid. Required `coverage` param (V8 dir, V8 JSON, or Istanbul `coverage-final.json`). Tuning knobs: `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), `low_traffic_threshold` (default 0.001), `max_crap` (default 30.0), `top`, `group_by`. Cloud runtime rows can expose `resolutionStatus` / `mappingQuality` on function-list JSON and `resolution_status` / `mapping_quality` in runtime-context JSON. Use `coverage_intelligence` and the confidence table below before acting on file-level runtime signals. Long dumps may exceed the 120s MCP timeout; raise `FALLOW_TIMEOUT_SECS`. Pick this over `check_health` when you have a coverage dump. |
 | `get_hot_paths` | Runtime-context slice over the same runtime coverage pipeline. Same params as `check_runtime_coverage`; read `runtime_coverage.hot_paths` for production hot paths. |
 | `get_blast_radius` | Runtime-context slice for blast-radius review. Same params as `check_runtime_coverage`; read `runtime_coverage.blast_radius` for stable `fallow:blast:<hash>` IDs, caller counts, traffic-weighted caller reach, optional cloud deploy touch counts, and low/medium/high risk bands. |
@@ -366,6 +366,8 @@ Config fields:
 - `ignoreExportsUsedInFile`: knip-compatible; suppress unused-export findings when the exported symbol is referenced inside the file that declares it. Boolean (`true` covers all kinds) or `{ "type": true, "interface": true }` object form for knip parity. Fallow groups type aliases and interfaces under the same `unused-types` issue, so both type-kind fields behave identically. References inside the export specifier itself (`export { foo }`, `export default foo`) do not count as same-file uses; those exports are still reported when no other in-file expression references the binding
 - `publicPackages`: workspace packages that are public libraries; exported API surface from these packages is not flagged as unused
 - `dynamicallyLoaded`: glob patterns for files loaded at runtime (plugin dirs, locale files); treated as always-used
+- `cache.dir`: override the persistent extraction cache directory. `FALLOW_CACHE_DIR` wins over this config field, and `--no-cache` disables caching entirely
+- `cache.maxSizeMb`: cap the serialized extraction cache size in megabytes. `FALLOW_CACHE_MAX_SIZE` wins over this config field
 - `usedClassMembers`: class method/property names that extend the built-in Angular/React lifecycle allowlist with framework-invoked names. Each entry is a plain string (global suppression) or a scoped object `{ extends?, implements?, members }` matching only classes with the given heritage. Strings can be exact names (`"agInit"`) or glob patterns (`"*"` matches every member, `"enter*"` prefix, `"*Handler"` suffix, `"on*Event"` combined). Use scoped rules for common names like `refresh` or `execute` to avoid false negatives on unrelated classes; global strings for unique names like `agInit`. Example: `["agInit", { "implements": "ICellRendererAngularComp", "members": ["refresh"] }, { "extends": "BaseCommand", "members": ["execute"] }, { "extends": "GrammarBaseListener", "members": ["enter*", "exit*"] }]`. Glob patterns that match zero members emit a `WARN` so dead allowlist entries surface. An unconstrained scoped rule (no `extends` or `implements`) is rejected at load time. Use plugin-level `usedClassMembers` in a `.fallow/plugins/*.jsonc` file for library-specific allowlists
 - `resolve.conditions`: additional package.json `exports` / `imports` condition names to honor during module resolution. Baseline conditions (`development`, `import`, `require`, `default`, `types`, `node`, plus `react-native` / `browser` under RN/Expo) are always included; user entries prepend ahead of them. Use for community conditions like `worker`, `edge-light`, `deno`, or custom bundler conditions. Example: `{ "resolve": { "conditions": ["worker", "edge-light"] } }`
 

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

@@ -40,9 +40,11 @@ Analyzes the project for unused files, exports, dependencies, types, members, an
 |------|------|---------|-------------|
 | `--format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|gitlab-codequality\|pr-comment-github\|pr-comment-gitlab\|review-github\|review-gitlab` | `human` | Output format |
 | `--quiet` | bool | `false` | Suppress progress bars and timing on stderr |
+| `-o, --output-file` | path | (none) | Write the report to a file instead of stdout, for any `--format` (no ANSI codes). Progress and a confirmation stay on stderr (suppressed by `--quiet`). Valid with dead-code/dupes/health/security/bare; composes with `--sarif-file`. |
 | `--legacy-envelope` | bool | `false` | Remove the top-level `kind` field from typed JSON roots for one migration cycle |
 | `--changed-since` | string | — | Only analyze files changed since a git ref (e.g., `main`, `HEAD~3`) |
 | `--production` | bool | `false` | Exclude test/dev files, only start/build scripts (applies to every analysis) |
+| `--no-production` | bool | `false` | Force production mode off, overriding a project config's `production: true` (applies to every analysis; conflicts with `--production`) |
 | `--production-dead-code` | bool | `false` | Per-analysis production mode for dead-code. Bare combined runs and `fallow audit` only. |
 | `--production-health` | bool | `false` | Per-analysis production mode for health. Bare combined runs and `fallow audit` only. |
 | `--production-dupes` | bool | `false` | Per-analysis production mode for duplication. Bare combined runs and `fallow audit` only. |
@@ -51,7 +53,14 @@ Analyzes the project for unused files, exports, dependencies, types, members, an
 | `--workspace` | string | — | Scope to one or more workspaces. Comma-separated values, globs (`apps/*`, `@scope/*`), and `!`-prefixed negation (`!apps/legacy`) supported. Matched against package name AND workspace path relative to repo root. |
 | `--changed-workspaces` | string (git ref) | — | Git-derived monorepo CI scoping: scope to workspaces containing any file changed since `REF` (e.g. `origin/main`). Auto-derives the workspace set from `git diff`. Mutually exclusive with `--workspace`. Missing ref is a hard error (exit 2), not silent full-scope fallback. |
 | `--include-dupes` | bool | `false` | Cross-reference with duplication findings |
+| `--dupes-mode` | enum | `config` | Override duplicate detection mode in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --mode`. |
+| `--dupes-threshold` | number | `config` | Override the duplication percentage failure threshold in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --threshold`. |
+| `--dupes-min-tokens` | number | `config` | Override the minimum token count for clone detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --min-tokens`. |
+| `--dupes-min-lines` | number | `config` | Override the minimum line count for clone detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --min-lines`. |
 | `--dupes-min-occurrences` | number | `config` | Override the minimum clone occurrences in combined mode (must be >= 2). Falls back to the config value when unset. Mirrors the standalone `dupes --min-occurrences`. |
+| `--dupes-skip-local` | bool | `config` | Only report cross-directory duplicates in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --skip-local`. |
+| `--dupes-cross-language` | bool | `config` | Enable TypeScript to JavaScript duplicate matching in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --cross-language`. |
+| `--dupes-ignore-imports` | bool | `config` | Exclude import declarations from duplicate detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --ignore-imports`. |
 | `--file` | path (multiple) | — | Scope output to specific files. Only issues in the specified files are reported. Project-wide dependency issues are suppressed. Warns on non-existent paths. Useful for lint-staged |
 | `--include-entry-exports` | bool | `false` | Report unused exports in entry files (package.json `main`/`exports`, framework pages). Catches typos like `meatdata` vs `metadata`. Global flag, also accepted on combined mode (`fallow --include-entry-exports`) and `fallow audit`. Also configurable as `includeEntryExports: true` in fallow config |
 | `--trace` | `FILE:EXPORT` | — | Trace export usage chain |
@@ -227,7 +236,7 @@ Auto-removes unused exports, dependencies, enum members, and pnpm catalog entrie
 
 ### On-disk drift protection
 
-`fallow fix` captures every parsed source file's xxh3 content hash during the in-process analysis and recomputes it at fix time. Files whose hash drifted between analysis and write (parallel editor save, CI rebase, concurrent tool) are skipped with `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "content_changed"}` in the JSON output and `Skipping <path>: file content changed since fallow check ran. Re-run fallow fix to refresh the analysis first.` on stderr (gated on non-quiet). A run with any content-changed skip exits with code 2 so CI does not treat the partial run as a clean no-op. The JSON envelope's top-level `skipped_content_changed: number` is always present and disjoint from `skipped` (which still tallies catalog / YAML guard skips only). Per-file writes are batched: each rewrite is staged to a sibling temp file, and the orchestrator promotes the batch only after every stage succeeds. A stage failure leaves every target file at its original content. Hash precondition covers source files (TS, JS, Vue, Svelte, Astro, MDX); `package.json` and `pnpm-workspace.yaml` are not in the captured hash map because the extract layer does not parse them, but the dep and catalog fixers re-parse those files at fix time as the natural safety net.
+`fallow fix` captures every parsed source file's xxh3 content hash during the in-process analysis and recomputes it at fix time. Files whose hash drifted between analysis and write (parallel editor save, CI rebase, concurrent tool) are skipped with `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "content_changed"}` in the JSON output and `Skipping <path>: file content changed since fallow dead-code ran. Re-run fallow fix to refresh the analysis first.` on stderr (gated on non-quiet). A run with any content-changed skip exits with code 2 so CI does not treat the partial run as a clean no-op. The JSON envelope's top-level `skipped_content_changed: number` is always present and disjoint from `skipped` (which still tallies catalog / YAML guard skips only). Per-file writes are batched: each rewrite is staged to a sibling temp file, and the orchestrator promotes the batch only after every stage succeeds. A stage failure leaves every target file at its original content. Hash precondition covers source files (TS, JS, Vue, Svelte, Astro, MDX); `package.json` and `pnpm-workspace.yaml` are not in the captured hash map because the extract layer does not parse them, but the dep and catalog fixers re-parse those files at fix time as the natural safety net.
 
 ### Low-confidence export removals
 
@@ -236,7 +245,7 @@ Issue #602: `fallow fix` withholds unused-export removals when the consumer may
 - **Off-graph consumer directories.** The file is under any of `__mocks__`, `__fixtures__`, `fixtures`, `e2e`, `e2e-tests`, `cypress`, `playwright`, `examples`, `evals`, `golden` (matched on any path segment). Catches Vitest mock aliases, off-workspace e2e suites, and fixture / golden harnesses. Plain `test` / `tests` / `__tests__` are deliberately NOT on the list, so genuinely-dead test helpers still auto-remove.
 - **Files with an unresolved import.** The file itself imports something fallow could not resolve, so its local usage graph is incomplete.
 
-JSON output carries `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "low_confidence_off_graph"}` (or `"low_confidence_unresolved_imports"`) plus a top-level counter `skipped_low_confidence_exports: number` (always present), disjoint from `skipped`. Unlike the drift and encoding skips this is INTENTIONAL and does NOT change the exit code; the export stays reported by `fallow check` for manual review. High-confidence exports in normal source files are removed unchanged. The AI agent should report kept exports to the user and let them decide whether the export is truly unused before removing it by hand.
+JSON output carries `{"type": "skipped", "path": "...", "skipped": true, "skip_reason": "low_confidence_off_graph"}` (or `"low_confidence_unresolved_imports"`) plus a top-level counter `skipped_low_confidence_exports: number` (always present), disjoint from `skipped`. Unlike the drift and encoding skips this is INTENTIONAL and does NOT change the exit code; the export stays reported by `fallow dead-code` for manual review. High-confidence exports in normal source files are removed unchanged. The AI agent should report kept exports to the user and let them decide whether the export is truly unused before removing it by hand.
 
 ### File encoding contract
 
@@ -287,7 +296,7 @@ fallow list --workspaces --format json --quiet
 fallow workspaces --format json --quiet  # alias of `fallow list --workspaces`
 ```
 
-The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (`undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`) with a typed payload (`error`, `pattern`, or none). The same `workspace_diagnostics[]` array is also surfaced on `fallow check --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes (omitted when empty). A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues.
+The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (`undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`) with a typed payload (`error`, `pattern`, or none). The same `workspace_diagnostics[]` array is also surfaced on `fallow dead-code --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes (omitted when empty). A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues.
 
 The `--boundaries` JSON output carries `boundaries.logical_groups[]` alongside the existing `zones[]` / `rules[]` arrays. Each logical-group entry surfaces a user-authored `autoDiscover` parent zone (which expansion otherwise flattens into per-child zones like `features/auth` / `features/billing`): `name`, `children`, `auto_discover` (verbatim user strings), `status` (`ok` / `empty` / `invalid_path`), `source_zone_index`, summed `file_count`, optional `authored_rule` (the pre-expansion `{ allow, allowTypeOnly }` keyed on the parent), optional `fallback_zone` cross-reference when the parent also kept its own `patterns` (Bulletproof case), optional `merged_from` (parent zone indices when the user declared the same parent name twice; surfaces the duplicate in JSON instead of only in `tracing::warn!`), optional `original_zone_root` (echo of the parent's `root` subtree scope for monorepo patchers), and optional `child_source_indices` (parallel to `children`, attributing each child to a specific `auto_discover` entry when multiple paths were authored). The full shape is documented in `docs/output-schema.json` under `ListBoundariesOutput`.
 
@@ -368,6 +377,7 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--top` | number | — | Only show the top N most complex functions (and file scores/hotspots/targets) |
 | `--sort` | `cyclomatic\|cognitive\|lines\|severity` | `cyclomatic` | Sort order for complexity findings |
 | `--complexity` | bool | `false` | Show only function complexity findings. When no section flags are set, all sections are shown by default. |
+| `--complexity-breakdown` | bool | `false` | Add a per-decision-point `contributions[]` array to each complexity finding in `--format json`. Each entry names the construct (`if`, `else-if`, `ternary`, boolean operator, loop, `case`, `catch`, `optional-chain`, ...) and carries its source line, the metric it adds to (`cyclomatic` or `cognitive`), its weight, and the nesting depth, so a consumer can explain WHY a function scored high. Off by default (no change to existing JSON/SARIF/markdown). Used by the VS Code inline editor breakdown and the MCP `check_health` `complexity_breakdown` param. |
 | `--file-scores` | bool | `false` | Show only per-file health scores (maintainability index, LOC, fan-in, fan-out, dead code ratio, complexity density, CRAP risk). Runs the full analysis pipeline. Sorted by risk-aware triage concern: lower maintainability index and higher CRAP risk first. When no section flags are set, all sections are shown by default. |
 | `--hotspots` | bool | `false` | Show only hotspots: files that are both complex and frequently changing. Combines git churn history with complexity data. Requires a git repository. When no section flags are set, all sections are shown by default. |
 | `--targets` | bool | `false` | Show only refactoring targets: ranked recommendations based on complexity, coupling, churn, and dead code signals. Categories: churn+complexity, circular dep, high impact, dead code, complexity, coupling. When no section flags are set, all sections are shown by default. |
@@ -376,8 +386,9 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--min-score` | number | — | Fail (exit 1) only when the health score is below this threshold. Implies `--score`. Authoritative CI quality gate: when set, complexity findings are demoted to informational and the exit code is driven solely by the score, so `--min-score 0` always exits 0. Composes with `--min-severity`. |
 | `--min-severity` | `moderate\|high\|critical` | — | Only exit with an error for findings at or above this severity. Composes with `--min-score` (the run fails if either gate trips). |
 | `--report-only` | bool | `false` | Print the score and findings but never fail CI (always exit 0). Advisory mode. Mutually exclusive with `--min-score` and `--min-severity`. |
-| `--since` | string | `6m` | Git history window for hotspot analysis. Accepts durations (`6m`, `90d`, `1y`, `2w`) or ISO dates (`2025-06-01`). |
+| `--since` | string | `6m` | Git history window for hotspot analysis. Accepts durations (`6m`, `90d`, `1y`, `2w`) or ISO dates (`2025-06-01`). Ignored when `--churn-file` is set. |
 | `--min-commits` | number | `3` | Minimum number of commits for a file to be included in hotspot ranking. |
+| `--churn-file` | string | (none) | Import change history from a `fallow-churn/v1` JSON file (`{schema, events:[{path, timestamp, author, added, deleted}]}`, one entry per changed file per commit) instead of `git log`, so `--hotspots`/`--ownership`/`--targets` work on non-git VCS (Yandex Arc, Mercurial, Perforce). Resolved relative to `--root`; wins over git. Authoritative for the window, so `--since` then only labels output. Malformed file exits 2; `audit`/`impact`/`--changed-since` still require git. |
 | `--ownership` | bool | `false` | Attach ownership signals to hotspot entries: bus factor (Avelino truck factor), contributor count, top contributor with stale-days, recent contributors (top-3), `suggested_reviewers`, declared CODEOWNERS owner, `ownership_state`, ownership drift, unowned-hotspot detection. Human output gains a project-level summary line. JSON adds `low-bus-factor`, `unowned-hotspot`, `ownership-drift` action types. Test files get a `[test]` tag. Implies `--hotspots`. Requires git. |
 | `--ownership-emails` | `raw\|handle\|anonymized\|hash` | `handle` | Privacy mode for author emails. `handle` shows the local-part only (default, with GitHub noreply unwrap and deterministic same-handle disambiguation). `anonymized` emits stable `xxh3:` pseudonyms; `hash` remains accepted as the legacy spelling. `raw` shows full addresses. Use `anonymized` in regulated environments. Implies `--ownership`. Configure default via `health.ownership.emailMode`. |
 | `--changed-since` | string | — | Only analyze files changed since a git ref |
@@ -486,7 +497,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.90.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -796,6 +807,7 @@ Audits changed files for dead code, complexity, and duplication. Returns a verdi
 | `--base` | string | auto-detect | Git ref to compare against (alias for `--changed-since`) |
 | `--gate` | `new-only\|all` | `new-only` | Which findings affect the verdict. `new-only` gates only introduced findings; `all` gates every finding in changed files and skips the extra base-snapshot attribution pass. |
 | `--production` | bool | false | Exclude test/story/dev files (applies to dead-code, health, and dupes) |
+| `--no-production` | bool | false | Force production mode off, overriding a project config's `production: true` (conflicts with `--production`) |
 | `--production-dead-code` | bool | false | Per-analysis production mode for the dead-code sub-analysis only |
 | `--production-health` | bool | false | Per-analysis production mode for the health sub-analysis only |
 | `--production-dupes` | bool | false | Per-analysis production mode for the duplication sub-analysis only |
@@ -876,7 +888,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.90.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -949,7 +961,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.90.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -964,21 +976,57 @@ Surfaces local security candidates for agent or human verification. The first ru
 
 Findings are not confirmed vulnerabilities. Use the structural trace to verify whether the value can actually reach client-bundled code. Public env conventions (`NODE_ENV`, `NEXT_PUBLIC_*`, `VITE_*`, `NUXT_PUBLIC_*`, `REACT_APP_*`, `PUBLIC_*`, `GATSBY_*`, `EXPO_PUBLIC_*`, `STORYBOOK_*`) are excluded.
 
-The second rule family is a data-driven `tainted-sink` catalogue: syntactic dangerous-sink candidates across 9 CWE categories. A candidate fires only when the relevant argument is non-literal, so a fully-literal value (`el.innerHTML = "<b>x</b>"`, `child_process.exec("ls")`) never fires; fallow prefers false-negatives over false-positives.
+The second rule family is a data-driven `tainted-sink` catalogue: syntactic dangerous-sink candidates across the catalogue categories listed below. Most rows require a non-literal argument; narrowly literal-aware rows flag deterministic unsafe literals such as wildcard `postMessage` origins, weak crypto algorithms, disabled TLS validation, and JWT algorithm issues. Fallow prefers false-negatives over false-positives.
 
 | Category | CWE | Sink |
 |----------|-----|------|
 | `dangerous-html` | 79 | `innerHTML` / `outerHTML` / `insertAdjacentHTML` / `dangerouslySetInnerHTML` |
+| `template-escape-bypass` | 79 | template-engine `SafeString(...)` wrapping a non-literal value |
 | `command-injection` | 78 | `child_process` `exec` / `execSync` / `spawn` / `spawnSync` (provenance-gated to `node:child_process`) |
 | `code-injection` | 94 | `eval` / `vm.runInNewContext` |
+| `dynamic-regex` | 1333 | `RegExp(...)` / `new RegExp(...)` with a non-literal pattern |
+| `redos-regex` | 1333 | vulnerable regex literals tested with source-backed input |
+| `resource-amplification` | 400 | source-backed size into `Array(...)` / `new Array(...)` / `Buffer.alloc*` / `String.prototype.repeat` / `padStart` / `padEnd` (directly `Math.min`-clamped sizes stay quiet) |
+| `dynamic-module-load` | 95 | dynamic `require(...)` |
 | `sql-injection` | 89 | string concat or interpolated template into `.query()` / `.execute()`, and `sql.raw(...)`. Parameterized `` sql`${x}` `` and the object form `.execute({ sql, args })` are NOT flagged |
-| `ssrf` | 918 | `fetch` / `axios` / `http(s).request` |
-| `path-traversal` | 22 | `fs.*` / `path.join` / `path.resolve` |
-| `open-redirect` | 601 | `res.redirect` |
+| `ssrf` | 918 | `fetch` / `got` / `ky` / `needle` / `request` / `axios` / `superagent` / `undici` / `http(s).request` |
+| `path-traversal` | 22 | `path.join` / `path.resolve` / `node:fs` path methods / route `sendFile` |
+| `header-injection` | 113 | response `setHeader` / `writeHead` |
+| `open-redirect` | 601 | `res.redirect` / `location.href` / `location.assign` / `window.open` |
+| `postmessage-wildcard-origin` | 346 | `postMessage(..., "*")` |
+| `tls-validation-disabled` | 295 | HTTPS/TLS options with `rejectUnauthorized: false`, plus `NODE_TLS_REJECT_UNAUTHORIZED = "0"` |
+| `cleartext-transport` | 319 | cleartext `http://` URLs in fetch-like calls and WebSocket constructors |
+| `electron-unsafe-webpreferences` | 1188 | Electron `webPreferences` with unsafe literal options |
+| `world-writable-permission` | 732 | `chmod` / `chmodSync` with world-writable modes |
+| `insecure-temp-file` | 377 | predictable temporary file paths in `fs` writes |
+| `mysql-multiple-statements` | 89 | MySQL connection options with `multipleStatements: true` |
+| `permissive-cors` | 942 | CORS wildcard origin with credentials |
+| `insecure-cookie` | 614 | cookie options missing or disabling `httpOnly` / `secure` |
+| `mass-assignment` | 915 | source-backed `Object.assign(target, source)` |
 | `weak-crypto` | 327 | runtime-selectable hash / cipher algorithm |
+| `deprecated-cipher` | 327 | `crypto.createCipher` / `createDecipher` |
+| `insecure-randomness` | 338 | `crypto.pseudoRandomBytes(...)` and token-like `Math.random()` use |
+| `jwt-alg-none` | 347 | JWT signing with algorithm `none` |
+| `jwt-verify-missing-algorithms` | 347 | `jsonwebtoken` verify calls missing an `algorithms` allowlist |
+| `unsafe-buffer-alloc` | 1188 | `Buffer.allocUnsafe` / `allocUnsafeSlow` |
 | `unsafe-deserialization` | 502 | `js-yaml` `load` / `node-serialize` |
-
-Build-config and test files are excluded from candidate generation. Both rule families default to `off` and are surfaced only by `fallow security`, never under bare `fallow` or the `audit` gate. Scope which catalogue categories run with `security.categories` include / exclude lists in config.
+| `angular-trusted-html` | 79 | Angular `bypassSecurityTrust*` |
+| `nextjs-open-redirect` | 601 | Next.js `redirect` / `permanentRedirect` |
+| `dom-document-write` | 79 | `document.write` / `document.writeln` |
+| `jquery-html` | 79 | jQuery `.html(value)` |
+| `route-send-file` | 22 | Express / Fastify / Hono route `sendFile` |
+| `webview-injection` | 94 | react-native-webview injected JavaScript |
+| `prototype-pollution` | 1321 | `__proto__` writes and recursive merge sources |
+| `zip-slip` | 22 | archive extraction destination paths |
+| `nosql-injection` | 943 | Mongo / Mongoose query object passthrough |
+| `ssti` | 1336 | template engine compile / render calls |
+| `xxe` | 611 | XML parse calls |
+| `secret-pii-log` | 532 | source-backed secrets or request PII reaching logs |
+| `hardcoded-secret` | 798 | provider-prefix credentials and high-entropy literals assigned to secret-shaped identifiers (include-required) |
+| `secret-to-network` | 201 | a non-public `process.env` / `import.meta.env` secret reaching a network call body (`fetch` / `axios` / `got` / ...) via same-identifier flow (include-required) |
+| `xpath-injection` | 643 | `xpath.select` / `select1` with a non-literal expression |
+
+Build-config and test files are excluded from candidate generation. Security rule families default to `off` and are surfaced only by `fallow security`, never under bare `fallow` or the `audit` gate. Scope which catalogue categories run with `security.categories` include / exclude lists in config. `hardcoded-secret` and `secret-to-network` are intentionally include-required and only run when listed in `security.categories.include` (`secret-to-network` is opt-in because legitimate auth is also a secret reaching a network call). Public-by-convention env vars (`NEXT_PUBLIC_`, `VITE_`, ...) are never treated as secrets.
 
 ### Flags
 
@@ -991,7 +1039,10 @@ Build-config and test files are excluded from candidate generation. Both rule fa
 | `--fail-on-issues` | bool | `false` | Exit 1 when candidates are found |
 | `--sarif-file` | path | none | Write SARIF in addition to the primary output |
 | `--changed-since` | git ref | none | Scope to candidates whose client anchor or trace hops touch changed files |
+| `--file` | path, repeatable | none | Scope output to candidates whose finding anchor or trace hop matches the selected file. The full graph is still analyzed |
 | `--diff-file` | path | none | Scope candidates to added hunks on the client anchor or import trace. Secret-source hops use file-level retention because member-access spans are not yet stored. Use `-` for stdin |
+| `--diff-stdin` | bool | `false` | Read the unified diff from stdin (equivalent to `--diff-file -`) for line-level scoping and the regression gate |
+| `--gate` | `new` | none | Fail (exit code **8**) only when the change introduces a NEW security-sink candidate in the changed lines, not on the whole candidate backlog. Requires a diff source (`--changed-since`, `--diff-file`, or `--diff-stdin`); a diff the gate cannot compute is a loud exit 2, never a green gate. Human output says `REVIEW REQUIRED` (not `FAIL`); SARIF keeps every result at `level: note` with the verdict in `run.properties.fallowGate`; `--format json` carries an additive `gate` block (`mode` / `verdict` / `new_count`) |
 | `--workspace` | string | none | Scope to selected workspace packages |
 | `--changed-workspaces` | git ref | none | Scope to workspaces changed since a git ref |
 
@@ -1001,6 +1052,9 @@ Build-config and test files are excluded from candidate generation. Both rule fa
 fallow security --format json --quiet
 fallow security --ci --sarif-file fallow-security.sarif
 git diff --unified=0 origin/main...HEAD | fallow security --diff-file -
+# Regression gate: fail (exit 8) only on candidates introduced in the changed lines
+fallow security --gate new --changed-since origin/main
+git diff --cached --unified=0 | fallow security --gate new --diff-stdin
 ```
 
 ### JSON Output Structure
@@ -1015,7 +1069,17 @@ git diff --unified=0 origin/main...HEAD | fallow security --diff-file -
 }
 ```
 
-Each finding includes `kind`, `path`, `line`, `col`, `evidence`, `trace`, and `actions`. `tainted-sink` findings additionally carry `category` (the catalogue id, e.g. `"dangerous-html"`) and `cwe`; `client-server-leak` findings omit both. `unresolved_edge_files` (client-server-leak) and `unresolved_callee_sites` (tainted-sink) are in-band blind-spot counters: a zero finding count with a non-zero counter is not a clean bill. Suppress a verified false positive with `// fallow-ignore-file security-client-server-leak` (client-server-leak) or `// fallow-ignore-file security-sink` (any tainted-sink category).
+Each finding includes `kind`, `path`, `line`, `col`, `evidence`, `trace`, `actions`, and optional `reachability`. `tainted-sink` findings additionally carry `category` (the catalogue id, e.g. `"dangerous-html"`) and `cwe`; `client-server-leak` findings omit both. `tainted-sink` findings can also include `reachability.untrusted_source_trace` when a module with a known untrusted source imports the sink module; it is ranking and triage context only, not proof that a specific value reaches the sink. `unresolved_edge_files` (client-server-leak) and `unresolved_callee_sites` (tainted-sink) are in-band blind-spot counters: a zero finding count with a non-zero counter is not a clean bill. Suppress a verified false positive with `// fallow-ignore-file security-client-server-leak` (client-server-leak) or `// fallow-ignore-file security-sink` (any tainted-sink category).
+
+Every finding also carries an agent-actionable `candidate { source_kind, sink, boundary }`, an optional `taint_flow { source, sink, path }`, and a stable `finding_id`:
+
+- `candidate.source_kind`: the untrusted-input kind that reaches the sink, as a stable catalogue id (`"http-request-input"`, `"process-env"`, `"process-argv"`, `"message-event-data"`, `"location-input"`, ...). Absent when no source matched (always absent for `client-server-leak`). Treat an unknown id as an untrusted source of unknown kind; never drop the candidate on that basis.
+- `candidate.sink`: a self-contained sink (`path`, `line`, `col`, `category`, `cwe`, `callee`), actionable without reading the rest of the finding.
+- `candidate.boundary`: `client_server` (a `"use client"` file in the trace), `cross_module` (the source reaches the sink across import hops), and optional `architecture_zone` (`from`/`to`) when the anchor also crosses a declared architecture boundary.
+- `candidate.network`: present only on `secret-to-network` (#890) candidates. `destination` is the network call's URL when it is a static literal (usually intended auth) or absent when the destination is dynamic (the higher-signal exfil case). Use it to triage exfil from intended auth without re-reading source.
+- There is no `impact` field: deciding exploitability is the verifying agent's job.
+- `taint_flow`: present only when an untrusted source is import-reachable to the sink. `path` is the compact `{ intra_module, cross_module_hops }` shape; the full ordered hops stay in `reachability.untrusted_source_trace`.
+- `finding_id`: a stable correlation id, identical across runs for the same rule/path/line and identical to the SARIF `partialFingerprints` value, for tracking a candidate across runs and joining JSON with SARIF.
 
 ---
 
@@ -1387,8 +1451,10 @@ Available on all commands:
 | `FALLOW_BIN` | Path to fallow binary (used by the MCP server). |
 | `FALLOW_TIMEOUT_SECS` | MCP server subprocess timeout in seconds (default: `120`). Increase for very large codebases. |
 | `FALLOW_EXTENDS_TIMEOUT_SECS` | Timeout for fetching remote config inheritance in seconds (default: `5`). Do not raise this for untrusted sources. |
+| `FALLOW_CACHE_DIR` | Override the persistent extraction cache directory. Wins over `cache.dir`. Useful for read-only checkouts or CI cache volumes. `--no-cache` disables this knob. |
 | `FALLOW_CACHE_MAX_SIZE` | Maximum on-disk extraction cache (`.fallow/cache.bin`) size in megabytes (default: `256`). Triggers LRU eviction when crossed. Wins over `cache.maxSizeMb` config field. Intended for CI runners with disk quotas. `--no-cache` short-circuits this knob. |
 | `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` | Max age (in days since last reuse or fresh create) of a persistent reusable `fallow audit` base-snapshot worktree cache. Older entries are reclaimed at the top of the next `fallow audit` invocation (default: `30`). Wins over `audit.cacheMaxAgeDays` config field. `0` disables the GC; invalid values silently fall back to config / default. |
+| `FALLOW_UPDATE_CHECK` | Set to `off`, `0`, `false`, `disabled`, or `no` to disable the human-TTY upgrade nudge and its background latest-version check. `DO_NOT_TRACK`, `FALLOW_TELEMETRY_DISABLED`, and CI also suppress it. |
 | `FALLOW_COMMAND` | GitLab CI: command to run (default: `dead-code`). |
 | `FALLOW_FAIL_ON_ISSUES` | GitLab CI: set to `true` to exit 1 if issues found. |
 | `FALLOW_CHANGED_SINCE` | GitLab CI: git ref for incremental analysis. Auto-detected in MR pipelines. |
@@ -1488,7 +1554,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.90.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1648,7 +1714,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.90.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1692,11 +1758,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.90.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.88.3",
+    "version": "2.90.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],
@@ -1804,6 +1870,12 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
     "ignorePatterns": ["**/*.generated.ts"]
   },
 
+  // Extraction cache settings. FALLOW_CACHE_DIR overrides cache.dir.
+  "cache": {
+    "dir": "/tmp/fallow-cache",
+    "maxSizeMb": 256
+  },
+
   // Architecture boundaries (preset, custom zones/rules, or auto-discovered feature zones)
   // Presets: "layered", "hexagonal", "feature-sliced", "bulletproof"
   // Rules accept an optional `allowTypeOnly: [zones]` list that admits type-only imports

package/types/output-contract.d.ts

@@ -61,6 +61,8 @@ kind: "coverage-setup"
 kind: "coverage-analyze"
 }) | (ListBoundariesOutput & {
 kind: "list-boundaries"
+}) | (WorkspacesOutput & {
+kind: "list-workspaces"
 }) | (HealthOutput & {
 kind: "health"
 }) | (DupesOutput & {
@@ -353,6 +355,18 @@ export type CoverageTier = ("none" | "partial" | "high")
  * Provenance of a CRAP finding's coverage signal.
  */
 export type CoverageSource = ("istanbul" | "estimated" | "estimated_component_inherited")
+/**
+ * Which complexity metric a [`ComplexityContribution`] adds to.
+ */
+export type ComplexityMetric = ("cyclomatic" | "cognitive")
+/**
+ * The syntactic construct that produced a single complexity increment.
+ *
+ * Mirrors `SonarSource` cognitive-complexity vocabulary where it overlaps.
+ * `Case` means a `case` label carrying a test; a bare `default` adds nothing
+ * to cyclomatic complexity and so produces no contribution.
+ */
+export type ComplexityContributionKind = ("if" | "else" | "else-if" | "ternary" | "logical-and" | "logical-or" | "nullish-coalescing" | "logical-assignment" | "optional-chain" | "for" | "for-in" | "for-of" | "while" | "do-while" | "switch" | "case" | "catch" | "labeled-break" | "labeled-continue")
 /**
  * Discriminant for [`HealthFindingAction::kind`]. Mirrors the action types
  * emitted by `build_health_finding_actions`. A single finding's `actions`
@@ -587,6 +601,17 @@ export type ImpactTrendDirection = ("improving" | "declining" | "stable")
  * from the main contract, mirroring `ImpactReportSchemaVersion`.
  */
 export type SecuritySchemaVersion = "1"
+/**
+ * Gate mode for `fallow security --gate <mode>` (issue #886). Tier 2 reserves
+ * the value `newly-reachable`.
+ */
+export type SecurityGateMode = "new"
+/**
+ * Gate verdict on the wire. `fail` is the CI-state token; human output renders
+ * it as "REVIEW REQUIRED" because these stay unverified candidates, never
+ * confirmed vulnerabilities.
+ */
+export type SecurityGateVerdict = ("pass" | "fail")
 /**
  * The kind of security candidate. Findings are CANDIDATES for downstream agent
  * verification, NOT verified vulnerabilities.
@@ -595,7 +620,20 @@ export type SecurityFindingKind = ("client-server-leak" | "tainted-sink")
 /**
  * The role a hop plays in a security finding's structural import trace.
  */
-export type TraceHopRole = ("client-boundary" | "intermediate" | "secret-source" | "sink")
+export type TraceHopRole = ("client-boundary" | "untrusted-source" | "intermediate" | "secret-source" | "sink")
+/**
+ * Dead-code issue kind linked to a security candidate.
+ */
+export type SecurityDeadCodeKind = ("unused-file" | "unused-export")
+/**
+ * Runtime coverage state for the function enclosing a security sink.
+ * This is production-observation evidence, not an exploitability verdict.
+ */
+export type SecurityRuntimeState = ("runtime-hot" | "runtime-cold" | "never-executed" | "low-traffic" | "coverage-unavailable" | "runtime-unknown")
+/**
+ * Defensive control family detected on a source to sink path.
+ */
+export type SecurityControlKind = ("sanitization" | "validation" | "authentication" | "authorization")
 /**
  * Discriminator value for [`CodeClimateIssue::kind`].
  */
@@ -1654,6 +1692,15 @@ line: number
  * 0-based byte column offset of the import that starts the cycle.
  */
 col: number
+/**
+ * Per-file import anchors, one entry per hop in cycle order: `edges[i]`
+ * is the import in `files[i]` pointing to `files[(i + 1) % len]`. Always
+ * the same length as `files`. Drives the per-file LSP diagnostic
+ * squiggly. `#[serde(default)]` so pre-`edges` baselines deserialize;
+ * always emitted on output but intentionally not in the schema's
+ * `required` set (see the struct doc).
+ */
+edges?: CircularDependencyEdge[]
 /**
  * Whether this cycle crosses workspace package boundaries.
  */
@@ -1669,6 +1716,34 @@ actions: IssueAction[]
  */
 introduced?: (AuditIntroduced | null)
 }
+/**
+ * One import hop in a circular dependency: the file containing the import
+ * and where that import statement sits.
+ *
+ * `edges[i]` is the import IN `path` (the hop SOURCE, equal to the cycle's
+ * `files[i]`) that points to the NEXT file in the cycle
+ * (`files[(i + 1) % files.len()]`); the target is not repeated here to keep
+ * the wire compact. Enables a per-file diagnostic squiggly anchored under
+ * the offending import rather than a single squiggly on the first file.
+ *
+ * `col` is a 0-based BYTE column, matching the cycle's top-level `col`;
+ * converting it to a UTF-16 code-unit column for LSP clients is a tracked
+ * follow-up shared with the existing field.
+ */
+export interface CircularDependencyEdge {
+/**
+ * The file containing the import (the hop SOURCE; equal to `files[i]`).
+ */
+path: string
+/**
+ * 1-based line number of the import statement pointing to the next file.
+ */
+line: number
+/**
+ * 0-based byte column offset of the import statement.
+ */
+col: number
+}
 /**
  * Wire-shape envelope for a [`ReExportCycle`] finding. Mirrors
  * [`CircularDependencyFinding`]: flattens the bare finding and carries a
@@ -2200,6 +2275,15 @@ line_count: number
  * each group in the human listing.
  */
 fingerprint: string
+/**
+ * Best-effort human-readable name for the clone: the dominant repeated
+ * identifier across the duplicated fragment (e.g. a shared `parseCsv`
+ * function). `None` when the clone has no clear dominant name (generic or
+ * tied identifiers); consumers then fall back to a file-based label. Lets
+ * editors and agents label a clone by what it is rather than an opaque
+ * ordinal.
+ */
+suggested_name?: (string | null)
 /**
  * Suggested next steps: an `extract-shared` primary and a
  * `suppress-line` secondary. Always emitted (possibly empty for
@@ -2534,6 +2618,13 @@ coverage_tier?: (CoverageTier | null)
 coverage_source?: (CoverageSource | null)
 inherited_from?: (string | null)
 component_rollup?: (ComponentRollup | null)
+/**
+ * Per-decision-point complexity breakdown explaining WHICH constructs drove
+ * the cyclomatic and cognitive scores. Populated only when the caller opts
+ * in via `health --complexity-breakdown`; empty (and omitted from JSON)
+ * otherwise so default and CI output stay lean.
+ */
+contributions?: ComplexityContribution[]
 /**
  * Machine-actionable fix and suppress hints.
  */
@@ -2553,6 +2644,36 @@ template_path: string
 template_cyclomatic: number
 template_cognitive: number
 }
+/**
+ * A single complexity increment, located at its source line/column.
+ *
+ * `weight` is the amount this construct added to `metric`; for nested
+ * cognitive increments `weight == 1 + nesting`. Consumers that render inline
+ * (the VS Code editor breakdown) group contributions by `line` and sum the
+ * weights, deferring the per-kind list to a hover.
+ */
+export interface ComplexityContribution {
+/**
+ * 1-based line number where the construct begins.
+ */
+line: number
+/**
+ * 0-based byte column where the construct begins.
+ */
+col: number
+metric: ComplexityMetric
+kind: ComplexityContributionKind
+/**
+ * The amount added to `metric` at this site (`1 + nesting` for nested
+ * cognitive increments, otherwise `1`).
+ */
+weight: number
+/**
+ * The nesting depth at the increment site (`0` when not nested). Lets a
+ * consumer explain a cognitive `+3` as "+1 base, +2 nesting".
+ */
+nesting: number
+}
 /**
  * Suggested action attached to a [`ComplexityViolation`].
  *
@@ -4073,6 +4194,46 @@ allow: string[]
  */
 allow_type_only?: string[]
 }
+/**
+ * `fallow workspaces --format json` envelope.
+ */
+export interface WorkspacesOutput {
+/**
+ * Number of workspace package entries in `workspaces`.
+ */
+workspace_count: number
+/**
+ * Workspace packages discovered from package manager and tsconfig workspace
+ * declarations. Paths are project-root-relative and use forward slashes.
+ */
+workspaces: WorkspaceInfo[]
+/**
+ * Workspace discovery diagnostics produced while reading workspace
+ * declarations. Present for compatibility with the current wire contract,
+ * even when empty.
+ */
+workspace_diagnostics: WorkspaceDiagnostic[]
+}
+/**
+ * One workspace package emitted by `fallow workspaces --format json`.
+ */
+export interface WorkspaceInfo {
+/**
+ * Package name from the workspace package.json. This is the value accepted
+ * by `--workspace <name>`.
+ */
+name: string
+/**
+ * Project-root-relative path to the workspace directory, normalized to
+ * forward slashes for cross-platform JSON consumers.
+ */
+path: string
+/**
+ * Whether the package is a generated or platform-specific dependency
+ * package rather than a hand-authored workspace.
+ */
+is_internal_dependency: boolean
+}
 /**
  * Envelope emitted by `fallow health --format json` (plus the `health` block
  * inside the combined and audit envelopes).
@@ -4696,15 +4857,27 @@ git_sha?: (string | null)
 timestamp: string
 }
 /**
- * The `fallow security --format json` envelope. `security_findings` is the
- * unique required field used for untagged narrowing in `FallowOutput`.
+ * The `fallow security --format json` envelope. `FallowOutput` discriminates it
+ * by the `kind: "security"` tag; the optional `gate` block is additive and is
+ * not part of that discrimination.
  */
 export interface SecurityOutput {
 schema_version: SecuritySchemaVersion
+/**
+ * Gate verdict, present only when `--gate <mode>` was set (issue #886).
+ * Emitted on pass too (`verdict: "pass"`, `new_count: 0`) so consumers
+ * distinguish "gate ran and passed" from "gate did not run" (absent).
+ */
+gate?: (SecurityGate | null)
 /**
  * Security candidates. Paths are project-root-relative, forward-slash.
  */
 security_findings: SecurityFinding[]
+/**
+ * Opt-in attack-surface inventory from untrusted entry points to reachable
+ * sinks. Present only when `--surface` was requested.
+ */
+attack_surface?: (SecurityAttackSurfaceEntry[] | null)
 /**
  * In-band blind spot: number of `"use client"` files whose transitive
  * import cone contains a dynamic `import()` the reachability BFS could not
@@ -4720,6 +4893,18 @@ unresolved_edge_files: number
  */
 unresolved_callee_sites: number
 }
+/**
+ * The `gate` block on `SecurityOutput`, present only when `--gate <mode>` ran.
+ * Invariant: `verdict == Fail  IFF  exit code 8  IFF  new_count > 0`.
+ */
+export interface SecurityGate {
+mode: SecurityGateMode
+verdict: SecurityGateVerdict
+/**
+ * Number of candidates introduced in the changed lines.
+ */
+new_count: number
+}
 /**
  * A local security CANDIDATE for downstream agent verification, NOT a verified
  * vulnerability. Emitted only by `fallow security`, never under bare `fallow`
@@ -4728,6 +4913,14 @@ unresolved_callee_sites: number
  * (its hops and length) is the only honest signal.
  */
 export interface SecurityFinding {
+/**
+ * Stable per-finding correlation id, identical across runs for the same
+ * rule + anchor path + line. An autonomous agent that triaged this
+ * candidate on a prior run uses it to correlate the candidate after a
+ * rebase. Equal to the SARIF `partialFingerprints` value for the same
+ * finding (one shared helper computes both).
+ */
+finding_id: string
 kind: SecurityFindingKind
 /**
  * The catalogue category id (e.g. `"dangerous-html"`). `None` for
@@ -4781,12 +4974,37 @@ trace: TraceHop[]
  */
 actions: IssueAction[]
 /**
- * Graph-derived reachability ranking signal (issue #860). `None` until the
- * post-detection ranking pass fills it; additive on the wire (skipped when
- * absent). Drives the order findings are emitted in: candidates reachable
- * from a runtime entry point with a wider blast radius sort first.
+ * Dead-code cross-link when the same sink candidate sits in code fallow also
+ * reports as removable. Agents should verify the dead-code finding and delete
+ * the code instead of hardening the sink when deletion is safe.
+ */
+dead_code?: (SecurityDeadCodeContext | null)
+/**
+ * Graph-derived reachability ranking signal (issues #860 and #885). `None`
+ * until the post-detection ranking pass fills it; additive on the wire
+ * (skipped when absent). Drives the order findings are emitted in:
+ * runtime-reachable candidates sort first, followed by source-backed and
+ * source-reachable candidates, then wider blast radius.
  */
 reachability?: (SecurityReachability | null)
+candidate: SecurityCandidate
+/**
+ * Source-to-sink taint-flow triple, present only when an untrusted source
+ * is import-reachable to this sink. Absent (skipped) otherwise.
+ */
+taint_flow?: (SecurityTaintFlow | null)
+/**
+ * Production runtime coverage context for the function enclosing this
+ * security sink. Present only when `fallow security --runtime-coverage`
+ * runs and the candidate is a `tainted-sink`.
+ */
+runtime?: (SecurityRuntimeContext | null)
+/**
+ * Internal projection used by `fallow security --surface`. The CLI strips
+ * this from per-finding JSON and promotes it to the top-level
+ * `attack_surface` field only when requested.
+ */
+attack_surface?: (SecurityAttackSurfaceEntry | null)
 }
 /**
  * One hop in a security finding's structural trace. Stored as an absolute path
@@ -4810,11 +5028,31 @@ line: number
 col: number
 role: TraceHopRole
 }
+/**
+ * Dead-code cross-link attached to a security candidate when fallow's dead-code
+ * pass reports the same anchor as removable code.
+ */
+export interface SecurityDeadCodeContext {
+kind: SecurityDeadCodeKind
+/**
+ * Unused export name when `kind` is `unused-export`.
+ */
+export_name?: (string | null)
+/**
+ * Dead-code finding line when available.
+ */
+line?: (number | null)
+/**
+ * Agent-facing guidance for deciding between deletion and hardening.
+ */
+guidance: string
+}
 /**
  * Graph-derived reachability ranking signal for a security candidate. Computed
- * from the EXISTING module graph (runtime reachability + reverse-dep fan-in)
- * after detection, never proven exploitable. Used to surface candidates that
- * sit on a request/runtime-reachable surface above isolated helpers or scripts.
+ * from the existing module graph after detection, never proven exploitable.
+ * Used to surface candidates that sit on a request/runtime-reachable surface,
+ * receive same-module source evidence, or are import-reachable from an
+ * untrusted-source module above isolated helpers or scripts.
  *
  * This is a relative-ordering signal, NOT a `confidence` or `signal_strength`
  * score: fallow does not prove the path is exploitable.
@@ -4827,6 +5065,23 @@ export interface SecurityReachability {
  * only from test entry points does not count.
  */
 reachable_from_entry: boolean
+/**
+ * Whether the anchor module is reachable over value imports from a module
+ * that reads a known untrusted input source. Module-level only: this does
+ * not prove a specific source value reaches the sink argument.
+ */
+reachable_from_untrusted_source?: boolean
+/**
+ * Number of value-import hops from the untrusted-source module to the sink
+ * module when `reachable_from_untrusted_source` is true.
+ */
+untrusted_source_hop_count?: (number | null)
+/**
+ * Module-level import path from the untrusted-source module to the sink
+ * anchor. Empty when no source module reaches this candidate. The path is a
+ * ranking explanation, not a value-flow proof.
+ */
+untrusted_source_trace?: TraceHop[]
 /**
  * Number of distinct modules that transitively depend on the anchor module
  * (fan-in via the graph's reverse-dependency index). A higher value means a
@@ -4841,6 +5096,256 @@ blast_radius: number
  */
 crosses_boundary: boolean
 }
+/**
+ * An agent-actionable candidate record on a [`SecurityFinding`]. fallow fills
+ * `source_kind`, `sink`, and `boundary`. The exploitability IMPACT is
+ * deliberately NOT a field: deciding severity / exploitability is the consuming
+ * agent's job, not fallow's, and a perpetually-null `impact` key would only
+ * train consumers to ignore it. The agent reads this record, then writes its
+ * own impact verdict downstream.
+ */
+export interface SecurityCandidate {
+/**
+ * The kind of untrusted input that reaches the sink, as a stable catalogue
+ * source id (`"http-request-input"`, `"process-env"`, `"process-argv"`,
+ * `"message-event-data"`, `"location-input"`, ...). `None`/absent when no
+ * untrusted source was matched (always `None` for `client-server-leak`).
+ * This is an OPEN string set, driven by the data-driven source catalogue; a
+ * consumer should treat an unknown id as "untrusted source of unknown kind"
+ * and never drop the candidate on that basis.
+ */
+source_kind?: (string | null)
+sink: SecurityCandidateSink
+boundary: SecurityCandidateBoundary
+/**
+ * Network-destination context, present only on `secret-to-network` (#890)
+ * candidates: the host the secret-bearing call targets, so an agent can
+ * triage exfil from intended auth. Absent for every other category.
+ */
+network?: (SecurityNetworkContext | null)
+}
+/**
+ * The sink slot of a [`SecurityCandidate`]: a self-contained description of the
+ * matched sink site. Echoes the finding's own span (`path`/`line`/`col`) plus
+ * the catalogue `category`/`cwe` and the captured `callee`, so an agent can act
+ * on `candidate.sink` in isolation (e.g. after fanning a finding out to a
+ * sub-agent) without reading the parent finding.
+ */
+export interface SecurityCandidateSink {
+/**
+ * File of the sink site. Absolute internally; JSON strips the project root
+ * via `serde_path::serialize`.
+ */
+path: string
+/**
+ * 1-based line of the sink site.
+ */
+line: number
+/**
+ * 0-based byte column of the sink site.
+ */
+col: number
+/**
+ * Catalogue category id of the sink (e.g. `"dangerous-html"`). `None` for
+ * `client-server-leak`.
+ */
+category?: (string | null)
+/**
+ * CWE number declared by the catalogue entry. `None` for
+ * `client-server-leak`; never fabricated beyond the catalogue's value.
+ */
+cwe?: (number | null)
+/**
+ * The sink callee (the dangerous function or member path, e.g.
+ * `"el.innerHTML"`, `"child_process.exec"`) captured by the catalogue match.
+ * `None` for `client-server-leak` and matches that name no callee.
+ */
+callee?: (string | null)
+}
+/**
+ * The boundary slot of a [`SecurityCandidate`]: which structural boundaries the
+ * candidate's flow crosses. A flow that crosses a client/server or module
+ * boundary is a stronger review target than a self-contained one; the boundary
+ * is fallow's structural signal over a pure source-sink match.
+ *
+ * Two further boundary kinds are RESERVED for a follow-up and are deliberately
+ * absent here rather than emitted as always-false: `export_visibility` (is the
+ * sink on a publicly-exported symbol?) and a package boundary (does the flow
+ * cross an npm-package edge?). Both need new graph derivation that does not
+ * exist today; emitting them as `false` would misreport "we checked and it does
+ * not cross" when fallow has not checked at all.
+ */
+export interface SecurityCandidateBoundary {
+/**
+ * Whether the finding crosses a client/server boundary (a `"use client"`
+ * file appears in the trace). True only for `client-server-leak` today;
+ * `tainted-sink` candidates carry no client/server marker.
+ */
+client_server: boolean
+/**
+ * Whether an untrusted source reaches the sink across one or more
+ * value-import (module) hops. Derived from the reachability hop count.
+ */
+cross_module: boolean
+/**
+ * The architecture-zone crossing when the anchor participates in a declared
+ * boundary-rule violation in the same run. `None` when it crosses no
+ * declared zone boundary.
+ */
+architecture_zone?: (SecurityZoneCrossing | null)
+}
+/**
+ * A declared architecture-zone crossing, recovered by correlating a finding's
+ * anchor against the run's architecture-boundary violations.
+ */
+export interface SecurityZoneCrossing {
+/**
+ * Zone the importing side belongs to.
+ */
+from: string
+/**
+ * Zone the imported side belongs to.
+ */
+to: string
+}
+/**
+ * Network-destination context for a `secret-to-network` candidate (#890): where
+ * the secret-bearing network call sends its data. Present only on
+ * network-category candidates. A consuming agent uses it to triage exfil
+ * (dynamic / untrusted destination) from intended auth (a literal provider
+ * host) without re-reading source.
+ */
+export interface SecurityNetworkContext {
+/**
+ * The network call's destination as a static URL string literal, or absent
+ * when the destination is DYNAMIC (not a literal). A dynamic destination is
+ * the higher-signal exfil case; a literal provider host is usually intended
+ * auth.
+ */
+destination?: (string | null)
+}
+/**
+ * A source-to-sink taint-flow triple, emitted only when an untrusted source is
+ * import-reachable to the sink (`reachability.reachable_from_untrusted_source`).
+ * The `{ source, sink, path }` shape matches the model agent SAST tooling
+ * expects (cf. Semgrep `taint_source` / `taint_sink`, SARIF `threadFlows`).
+ */
+export interface SecurityTaintFlow {
+source: TaintEndpoint
+sink: TaintEndpoint
+path: TaintPath
+}
+/**
+ * One endpoint (source or sink node) of a [`SecurityTaintFlow`].
+ */
+export interface TaintEndpoint {
+/**
+ * File of the endpoint. Absolute internally; JSON strips the project root.
+ */
+path: string
+/**
+ * 1-based line of the endpoint.
+ */
+line: number
+/**
+ * 0-based byte column of the endpoint.
+ */
+col: number
+}
+/**
+ * Compact taint-flow path shape. The ordered per-hop trace is NOT duplicated
+ * here: it lives on [`SecurityReachability::untrusted_source_trace`]. This
+ * carries only the flow's structural summary (intra-module flow plus the
+ * cross-module hop count) so consumers do not parse two copies of the hops.
+ */
+export interface TaintPath {
+/**
+ * Whether the source and sink sit in the same module (no import hop between
+ * them); the source-to-sink association is intra-module.
+ */
+intra_module: boolean
+/**
+ * Number of value-import hops from the untrusted-source module to the sink
+ * module. Zero for an intra-module flow.
+ */
+cross_module_hops: number
+}
+/**
+ * Runtime coverage context attached to a security candidate when
+ * `fallow security --runtime-coverage` is supplied.
+ */
+export interface SecurityRuntimeContext {
+state: SecurityRuntimeState
+/**
+ * Enclosing function name from static extraction.
+ */
+function: string
+/**
+ * 1-based line where the enclosing function starts.
+ */
+line: number
+/**
+ * Observed invocation count when the runtime report provides it.
+ */
+invocations?: (number | null)
+/**
+ * Runtime coverage stable function id, when available.
+ */
+stable_id?: (string | null)
+/**
+ * Short candidate-framed explanation of the runtime evidence.
+ */
+evidence?: (string | null)
+}
+/**
+ * One untrusted entry to reachable sink path for `fallow security --surface`.
+ */
+export interface SecurityAttackSurfaceEntry {
+source: TaintEndpoint
+sink: SecurityCandidateSink
+/**
+ * Ordered source to sink path. Same shape as the reachability trace so
+ * consumers can reuse existing path handling.
+ */
+path: TraceHop[]
+defensive_boundary: SecurityDefensiveBoundary
+}
+/**
+ * Agent-facing defensive-boundary verification context for one surface path.
+ */
+export interface SecurityDefensiveBoundary {
+/**
+ * Known controls detected along this path.
+ */
+controls: SecurityDefensiveControl[]
+/**
+ * Verification question for the consuming agent. It is a prompt, not a
+ * missing-guard verdict.
+ */
+verification_prompt: string
+}
+/**
+ * Defensive control found on an attack-surface path.
+ */
+export interface SecurityDefensiveControl {
+kind: SecurityControlKind
+/**
+ * File of the control site. Absolute internally; JSON strips the project root.
+ */
+path: string
+/**
+ * 1-based line of the control site.
+ */
+line: number
+/**
+ * 0-based byte column of the control site.
+ */
+col: number
+/**
+ * Flattened callee path or a stable synthetic guard name.
+ */
+callee: string
+}
 /**
  * Bare `fallow --format json` envelope.
  */