fallow 3.35.0 → 3.37.0

package/README.md

@@ -28,7 +28,7 @@ npx fallow fix --dry-run         # Preview automatic cleanup
 
 ## Output and exit codes
 
-Add `--format json --quiet` to any command for one typed JSON document on stdout. Exit code 1 means findings, not failure; 0 is clean (or an audit pass or warn verdict); 2 is a validation or runtime error, reported as a JSON error envelope rather than a stack trace. License, coverage setup, network, and security-gate workflows use additional documented codes; read `fallow schema.exit_codes` instead of suppressing the process status.
+Add `--format json --quiet` to any command for one typed JSON document on stdout. Exit code 1 means findings, not failure; 0 means no enforced gate failed (or an audit pass or warn verdict). Bare `fallow` in a machine format exits 0 on findings unless you pass `--fail-on-issues`; 2 is a validation or runtime error, reported as a JSON error envelope rather than a stack trace. License, coverage setup, network, and security-gate workflows use additional documented codes; read `fallow schema.exit_codes` instead of suppressing the process status.
 
 Parsing the output in TypeScript? Import the typed shapes, version-pinned to the CLI you install:
 

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.35.0",
+  "version": "3.37.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -301,7 +301,7 @@
       "name": "--fail-on-issues",
       "type": "bool",
       "required": false,
-      "description": "Exit with code 1 if issues are found",
+      "description": "Exit 1 on issues, also where the default is 0: bare json, sarif, codeclimate and dupes",
       "possible_values": [
         "true",
         "false"
@@ -1289,6 +1289,16 @@
             "false"
           ]
         },
+        {
+          "name": "--resume",
+          "type": "bool",
+          "required": false,
+          "description": "Continue an interrupted or partial run: reuse the killed and confirmed survived mutants in its journal and run only the others. A journal of other inputs exits 2",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
         {
           "name": "paths",
           "type": "string",
@@ -4536,9 +4546,11 @@
       "sarif_rule_ids": [
         "fallow/thin-wrapper"
       ],
-      "codeclimate_check_names": null,
+      "codeclimate_check_names": [
+        "fallow/thin-wrapper"
+      ],
       "ts_alias": null,
-      "counts_in_total": false,
+      "counts_in_total": true,
       "fixable": false,
       "suppressible": true,
       "suppress_comment": "// fallow-ignore-next-line thin-wrapper",
@@ -4570,9 +4582,11 @@
       "sarif_rule_ids": [
         "fallow/duplicate-prop-shape"
       ],
-      "codeclimate_check_names": null,
+      "codeclimate_check_names": [
+        "fallow/duplicate-prop-shape"
+      ],
       "ts_alias": null,
-      "counts_in_total": false,
+      "counts_in_total": true,
       "fixable": false,
       "suppressible": true,
       "suppress_comment": "// fallow-ignore-next-line duplicate-prop-shape",
@@ -6995,8 +7009,8 @@
     "github-summary"
   ],
   "exit_codes": {
-    "0": "Success (no error-severity issues found)",
-    "1": "Error-severity issues found (per rules config, or --fail-on-issues promotes warn to error)",
+    "0": "Success: no enforced gate failed. Bare fallow in a machine format (json, sarif, codeclimate, the GitHub formats, the comment and review formats) does not enforce findings without --fail-on-issues, so it exits 0 on findings. Read gate_outcomes: status \"fail\" with enforced false is a failing gate that did not set the exit code",
+    "1": "An enforced gate failed, for example error-severity findings (per rules config, or --fail-on-issues promotes warn to error). This is an analysis result, not a tool failure",
     "2": "Error (invalid config, invalid input, etc.). When --format json is active, errors are emitted as structured JSON on stdout: {\"error\": true, \"message\": \"...\", \"exit_code\": 2}",
     "3": "Requested resource unavailable: config --path found no config, or a license is missing, invalid, or beyond its offline hard-fail window",
     "4": "Runtime coverage sidecar is unavailable, unverifiable, protocol-incompatible, or terminated unexpectedly",
@@ -7034,6 +7048,7 @@
     "FALLOW_MAX_FILE_SIZE": "Per-file size ceiling in megabytes for source discovery (default 5; 0 = no limit). CLI --max-file-size flag overrides this.",
     "FALLOW_TYPE_AWARE": "Enable or disable TypeScript semantic (type-aware) analysis for the run (true/false/1/0/yes/no/on/off). Precedence: --type-aware/--no-type-aware CLI flags, then FALLOW_TYPE_AWARE, then the audit.typeAware config field, then typeAware.enabled.",
     "FALLOW_TYPE_AWARE_TIMEOUT_SECS": "Wall clock in seconds allowed for one TypeScript semantic sidecar request (default 120; unset, 0, or a non-numeric value keeps the default). Raise it for very large TypeScript programs, where a semantic query scans the whole program.",
+    "FALLOW_TYPE_AWARE_BACKEND": "Experimental. Type-checker backend for the TypeScript semantic sidecar: typescript-go (default) or tsrs. The tsrs backend needs the exact pinned tsrs npm package where fallow-type-aware can resolve it. An unknown value makes the type-aware pass unavailable.",
     "FALLOW_TYPE_AWARE_BIN": "Trusted executable override for the TypeScript semantic refinement sidecar used by dead-code --type-aware. Relative paths resolve from the caller's working directory before --root is applied; project node_modules and PATH are intentionally not searched. Default: sibling of the active Fallow executable.",
     "FALLOW_AUDIT_BASE": "Pins the fallow audit comparison base ref when no --base/--changed-since is passed (e.g. upstream/main).",
     "FALLOW_AUDIT_CACHE_MAX_AGE_DAYS": "GC threshold in days for reusable audit base-snapshot caches (default 30; 0 disables the sweep).",
@@ -8280,7 +8295,7 @@
     ]
   },
   "plugins": {
-    "count": 148,
+    "count": 149,
     "note": "Built-in framework plugins, auto-activated when their enabler dependency is present; run fallow list --plugins for the set active in a specific project",
     "names": [
       "nextjs",
@@ -8421,6 +8436,7 @@
       "nodemon",
       "pm2",
       "dependency-cruiser",
+      "dotenv",
       "wuchale",
       "varlock",
       "pnpm",

package/issue-registry.json

@@ -1939,9 +1939,11 @@
       "sarif_rule_ids": [
         "fallow/thin-wrapper"
       ],
-      "codeclimate_check_names": null,
+      "codeclimate_check_names": [
+        "fallow/thin-wrapper"
+      ],
       "ts_alias": null,
-      "counts_in_total": false,
+      "counts_in_total": true,
       "fixable": false,
       "suppressible": true,
       "suppress_comment": "// fallow-ignore-next-line thin-wrapper",
@@ -1973,9 +1975,11 @@
       "sarif_rule_ids": [
         "fallow/duplicate-prop-shape"
       ],
-      "codeclimate_check_names": null,
+      "codeclimate_check_names": [
+        "fallow/duplicate-prop-shape"
+      ],
       "ts_alias": null,
-      "counts_in_total": false,
+      "counts_in_total": true,
       "fixable": false,
       "suppressible": true,
       "suppress_comment": "// fallow-ignore-next-line duplicate-prop-shape",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.35.0",
+  "version": "3.37.0",
   "mcpName": "io.github.fallow-rs/fallow",
   "description": "Codebase intelligence for TypeScript and JavaScript: health, complexity, duplication, architecture, styling drift, and unused code from one graph. CLI, LSP, and MCP server. Zero config for over 100 frameworks.",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "./scripts/*": "./scripts/*",
     "./skills/*": "./skills/*",
     "./schema.json": "./schema.json",
+    "./rule-pack-schema.json": "./rule-pack-schema.json",
     "./capabilities.json": "./capabilities.json",
     "./issue-registry.json": "./issue-registry.json"
   },
@@ -67,11 +68,13 @@
   "files": [
     "bin",
     "scripts",
+    "!scripts/*.test.js",
     "skills",
     "!skills/_artifacts",
     "types",
     "README.md",
     "schema.json",
+    "rule-pack-schema.json",
     "capabilities.json",
     "issue-registry.json"
   ],
@@ -86,17 +89,17 @@
     "detect-libc": "2.1.2"
   },
   "devDependencies": {
-    "@tanstack/intent": "0.5.5"
+    "@tanstack/intent": "0.5.6"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.35.0",
-    "@fallow-cli/darwin-x64": "3.35.0",
-    "@fallow-cli/linux-x64-gnu": "3.35.0",
-    "@fallow-cli/linux-arm64-gnu": "3.35.0",
-    "@fallow-cli/linux-x64-musl": "3.35.0",
-    "@fallow-cli/linux-arm64-musl": "3.35.0",
-    "@fallow-cli/win32-arm64-msvc": "3.35.0",
-    "@fallow-cli/win32-x64-msvc": "3.35.0",
-    "fallow-type-aware": "3.35.0"
+    "@fallow-cli/darwin-arm64": "3.37.0",
+    "@fallow-cli/darwin-x64": "3.37.0",
+    "@fallow-cli/linux-x64-gnu": "3.37.0",
+    "@fallow-cli/linux-arm64-gnu": "3.37.0",
+    "@fallow-cli/linux-x64-musl": "3.37.0",
+    "@fallow-cli/linux-arm64-musl": "3.37.0",
+    "@fallow-cli/win32-arm64-msvc": "3.37.0",
+    "@fallow-cli/win32-x64-msvc": "3.37.0",
+    "fallow-type-aware": "3.37.0"
   }
 }

package/rule-pack-schema.json

@@ -0,0 +1,264 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "RulePackDef",
+  "description": "A declarative rule pack loaded from a standalone JSON or JSONC file listed\nin the `rulePacks` config key.\n\nRule packs are pure data: loading a pack never executes project code. They\nencode project-specific policy (banned calls, banned imports, and\ncatalogue-backed banned effects) evaluated over fallow's static extraction\ndata, reporting as `policy-violation`\nfindings.\n\n```jsonc\n{\n  \"$schema\": \"https://raw.githubusercontent.com/fallow-rs/fallow/main/rule-pack-schema.json\",\n  \"version\": 1,\n  \"name\": \"team-policy\",\n  \"description\": \"House rules for the platform team\",\n  \"rules\": [\n    {\n      \"id\": \"no-child-process\",\n      \"kind\": \"banned-call\",\n      \"callees\": [\"child_process.*\"],\n      \"message\": \"Use the sandboxed runner instead.\",\n      \"severity\": \"error\"\n    },\n    {\n      \"id\": \"no-network\",\n      \"kind\": \"banned-effect\",\n      \"effects\": [\"network\"],\n      \"message\": \"Keep this package side-effect free.\"\n    },\n    {\n      \"id\": \"no-moment\",\n      \"kind\": \"banned-import\",\n      \"specifiers\": [\"moment\"],\n      \"message\": \"Use date-fns.\"\n    }\n  ]\n}\n```",
+  "type": "object",
+  "properties": {
+    "version": {
+      "description": "Pack format version. Must be `1`; the field exists so future rule\nkinds can be added without breaking older fallow builds silently.",
+      "type": "integer",
+      "format": "uint32",
+      "minimum": 0
+    },
+    "name": {
+      "description": "Pack name, unique across all loaded packs. Must use only ASCII\nletters, digits, `.`, `_`, and `-` so `\"<pack>/<id>\"` is unambiguous in\noutput, baselines, and scoped suppression comments.",
+      "type": "string"
+    },
+    "description": {
+      "description": "Optional human description of the pack's intent.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "rules": {
+      "description": "The policy rules this pack enforces. Must be non-empty: an empty pack\nwould silently enforce nothing.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/RulePackRule"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "name",
+    "rules"
+  ],
+  "$defs": {
+    "RulePackRule": {
+      "description": "One declarative policy rule inside a rule pack.\n\n`callees` applies only to `banned-call` rules; `specifiers` and\n`ignoreTypeOnly` apply only to `banned-import` rules; `effects` applies\nonly to `banned-effect` rules; `exports` applies only to `banned-export`\nrules. `allowedFiles` and `proofKinds` apply only to `gdp-proof-producer`\nrules. `zones` can scope any rule kind to files classified into one of the\nnamed boundary zones. Setting a field on the wrong kind is a load error\n(fail loud, never silently ignore policy).",
+      "type": "object",
+      "properties": {
+        "id": {
+          "description": "Rule id, unique within the pack. Must use only ASCII letters, digits,\n`.`, `_`, and `-` so `\"<pack>/<id>\"` is unambiguous in output,\nbaselines, and scoped suppression comments.",
+          "type": "string"
+        },
+        "kind": {
+          "description": "Which check this rule performs.",
+          "$ref": "#/$defs/RulePackRuleKind"
+        },
+        "callees": {
+          "description": "Callee patterns to ban (`banned-call` only). Matching is segment-aware\nand import-resolved, identical to `boundaries.calls.forbidden`:\n`child_process.*` covers `import { exec } from \"node:child_process\"`,\nthe bare specifier, and namespace/default imports; `fetch` matches only\nthe global `fetch`; a leading `*.member` matches any object.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "specifiers": {
+          "description": "Import specifiers to ban (`banned-import` only). Matched segment-aware\nagainst the RAW specifier: `moment` covers `moment` and\n`moment/locale/nl` but not `moment-timezone`. A trailing `/*` form,\nsuch as `@org/ui/*`, matches subpaths only (`@org/ui/internal`) and\nnot the package root (`@org/ui`). Aliased or rewritten specifiers\n(e.g. `npm:moment`) are not matched.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "effects": {
+          "description": "Effect classes to ban (`banned-effect` only). Effects are derived from\n`security_matchers.toml` catalogue rows and matched against captured\ncall sites after import-resolution canonicalization.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/EffectKind"
+          }
+        },
+        "exports": {
+          "description": "Export names to ban (`banned-export` only). `\"default\"` matches the\ndefault export; any other entry matches an exported name exactly; a\nsingle trailing `*` makes it a prefix match (`internal*`). No other\nglob syntax is supported. Re-exports are out of scope for this rule.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "allowedFiles": {
+          "description": "Project-root-relative globs allowed to call `@gdp-ts/core.defineProof`\n(`gdp-proof-producer` only). At least one pattern is required.\nA single `*` stays within one path segment; use `**` to match across directories.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "proofKinds": {
+          "description": "Exact literal proof labels checked by a `gdp-proof-producer` rule.\nEmpty or absent checks every recognized factory call, including calls\nwith dynamic labels. A nonempty list checks only static string labels.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "ignoreTypeOnly": {
+          "description": "When `true`, type-only imports (`import type ...` and type-only\nre-exports) are ignored by `banned-import`; type-only exports are\nignored by `banned-export`. Defaults to `false`: type-only sites are\nflagged too.",
+          "type": "boolean"
+        },
+        "files": {
+          "description": "Optional include globs (project-root-relative). Empty or absent means\nthe rule applies to every analyzed file.\nA single `*` stays within one path segment; use `**` to match across directories.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "exclude": {
+          "description": "Optional exclude globs (project-root-relative), applied after `files`.\nA single `*` stays within one path segment; use `**` to match across directories.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "zones": {
+          "description": "Optional boundary zones this rule applies to. Empty or absent means the\nrule applies regardless of zone; non-empty values require matching\nconfigured boundaries and combine with `files`/`exclude` as AND.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "message": {
+          "description": "Author-provided message naming the sanctioned alternative. Rendered\nnext to each finding.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "severity": {
+          "description": "Per-rule severity overriding the `rules.\"policy-violation\"` master.\n`off` disables this rule. When the master itself is `off`, the whole\nevaluator is disabled and per-rule severity cannot resurrect it.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind"
+      ]
+    },
+    "RulePackRuleKind": {
+      "description": "Which check a rule-pack rule performs.",
+      "oneOf": [
+        {
+          "description": "Ban call sites whose callee path matches one of `callees`.",
+          "type": "string",
+          "const": "banned-call"
+        },
+        {
+          "description": "Ban imports and re-exports whose raw specifier matches one of\n`specifiers`.",
+          "type": "string",
+          "const": "banned-import"
+        },
+        {
+          "description": "Ban call sites whose catalogue-derived effect matches one of `effects`.",
+          "type": "string",
+          "const": "banned-effect"
+        },
+        {
+          "description": "Ban exported names that match one of `exports`.",
+          "type": "string",
+          "const": "banned-export"
+        },
+        {
+          "description": "Restrict gdp-ts proof factory calls to explicitly allowed modules.",
+          "type": "string",
+          "const": "gdp-proof-producer"
+        }
+      ]
+    },
+    "EffectKind": {
+      "description": "Internal side-effect taxonomy derived from security catalogue rows.",
+      "oneOf": [
+        {
+          "description": "No observable side effect.",
+          "type": "string",
+          "const": "pure"
+        },
+        {
+          "description": "Structured-data read/query evaluation (XML external entities, XPath).",
+          "type": "string",
+          "const": "read"
+        },
+        {
+          "description": "In-memory state mutation (mass assignment, prototype pollution).",
+          "type": "string",
+          "const": "write"
+        },
+        {
+          "description": "Network I/O (HTTP clients, request-forgery sinks).",
+          "type": "string",
+          "const": "network"
+        },
+        {
+          "description": "Filesystem access (path traversal, file permission changes).",
+          "type": "string",
+          "const": "storage"
+        },
+        {
+          "description": "In-process code evaluation (`eval`, `Function`, string timers).",
+          "type": "string",
+          "const": "process"
+        },
+        {
+          "description": "OS shell command execution.",
+          "type": "string",
+          "const": "shell"
+        },
+        {
+          "description": "Cryptographic primitives (weak algorithm or key usage).",
+          "type": "string",
+          "const": "crypto"
+        },
+        {
+          "description": "Random-number generation in security-sensitive contexts.",
+          "type": "string",
+          "const": "randomness"
+        },
+        {
+          "description": "DOM injection (`innerHTML`-style XSS sinks).",
+          "type": "string",
+          "const": "dom"
+        },
+        {
+          "description": "Database query execution (SQL/NoSQL injection sinks).",
+          "type": "string",
+          "const": "database"
+        },
+        {
+          "description": "Callback invoked by a framework rather than a direct effect.",
+          "type": "string",
+          "const": "framework-callback"
+        },
+        {
+          "description": "Effect the catalogue cannot classify.",
+          "type": "string",
+          "const": "unknown"
+        }
+      ]
+    },
+    "Severity": {
+      "description": "Severity level for rules.\n\nControls whether an issue type sets a non-zero exit code (`error`), is\nreported without an effect on the exit code (`warn`), or is suppressed\nentirely (`off`). `--fail-on-issues` promotes `warn` to `error`. The\ndead-code count gate of the GitHub Action counts `warn` findings unless its\n`fail-on-issues` input is `false`.",
+      "oneOf": [
+        {
+          "description": "Report and set a non-zero exit code.",
+          "type": "string",
+          "const": "error"
+        },
+        {
+          "description": "Report without an effect on the exit code.",
+          "type": "string",
+          "const": "warn"
+        },
+        {
+          "description": "Don't detect or report.",
+          "type": "string",
+          "const": "off"
+        }
+      ]
+    }
+  }
+}

package/schema.json

@@ -357,6 +357,13 @@
       },
       "default": []
     },
+    "markupExtensions": {
+      "description": "An array of file extensions, without the leading dot, for server-side template files whose text counts as CSS class references for the `unreferenced-css-class` finding of `fallow health --css`. These files are read as text only: they do not join source discovery or the module graph, so they never become unused files and their imports are not followed. Templates are more lenient than Markdown: the whole text of a template file counts as a dynamic class reference, so any class-like word in it counts as used, also a common word such as `hidden` or `title` in prose or a template tag. A Markdown file joins the reference text only when it has dynamic class syntax. The extensions `liquid`, `njk`, `hbs`, `handlebars`, `twig`, and `blade.php` are always read; set this (e.g. `[\"tpl\", \"erb\"]`) for other template languages. An extension matches the end of a file name, ignoring case, so `blade.php` matches `welcome.blade.php`. Values may contain only letters, digits, `.`, `-`, and `_`. A value whose last segment is a script, stylesheet, data or asset extension (`js`, `ts`, `css`, `json`, `svg`, `xml`, `map`, and similar, so also `module.css` or `d.ts`), or a compound value that ends in a markup extension that fallow already reads (`page.html`), is a config error. The walk uses the ignore files of source discovery (`.gitignore`, `.ignore`), skips `ignorePatterns`, `health.ignore`, `node_modules`, `vendor`, and build output directories, reads only regular files, and skips files over the `--max-file-size` limit. In `extends`, a child list replaces the parent list.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "overrides": {
       "description": "An ordered list of per-file rule-severity overrides: each entry re-severities specific analysis rules for files its globs match, layered on top of the top-level `rules` defaults. Set to relax or tighten rules for a subset of paths (e.g. downgrade unused-exports to warn under a generated directory); each entry has `files` (glob-pattern array) and `rules` (a partial per-rule severity map of error/warn/off). Entries apply in list order and a file matched by several entries takes every matching entry's overrides (later entries win on conflict); inter-file rules (duplicate-exports, circular-dependencies, re-export-cycle) have no effect in an override (fallow warns during analysis and points to the right mechanism: top-level `ignoreExports` for duplicate-exports, a file-level `// fallow-ignore-file` comment for the others). A single `*` stays within one path segment; use `**` to match across directories.",
       "type": "array",
@@ -416,7 +423,7 @@
       "default": false
     },
     "failOnParseError": {
-      "description": "When true, the run fails with exit code 1 if fallow could not parse a source file cleanly (a `source-parse-degraded` entry in `workspace_diagnostics[]`), and the `parse-error` entry of `gate_outcomes` names each such file. Boolean, defaults to false, so a file the parser rejects only warns. Applies to `fallow dead-code`, `fallow health`, `fallow audit` and the bare `fallow` run; the CLI flag `--fail-on-parse-error` arms the same gate for one run. Older fallow versions reject this key as unknown, so pair it with `minimumVersion` set to the release that added it.",
+      "description": "When true, the run fails with exit code 1 if fallow could not parse a source file cleanly (a `source-parse-degraded` or `source-nesting-too-deep` entry in `workspace_diagnostics[]`), and the `parse-error` entry of `gate_outcomes` names each such file. Boolean, defaults to false, so a file the parser rejects only warns. Applies to `fallow dead-code`, `fallow health`, `fallow audit` and the bare `fallow` run; the CLI flag `--fail-on-parse-error` arms the same gate for one run. Older fallow versions reject this key as unknown, so pair it with `minimumVersion` set to the release that added it.",
       "type": "boolean",
       "default": false
     },
@@ -538,13 +545,13 @@
           "description": "Plugin detected if this package is in dependencies.",
           "type": "object",
           "properties": {
-            "package": {
-              "description": "Exact package name looked up in the project's declared dependencies.",
-              "type": "string"
-            },
             "type": {
               "type": "string",
               "const": "dependency"
+            },
+            "package": {
+              "description": "Exact package name looked up in the project's declared dependencies.",
+              "type": "string"
             }
           },
           "required": [
@@ -556,13 +563,13 @@
           "description": "Plugin detected if this file pattern matches.",
           "type": "object",
           "properties": {
-            "pattern": {
-              "description": "Project-root-relative glob; the plugin activates when any\ndiscovered file matches it. Validated at load like other user\nglobs (no absolute paths or `..` segments).\nA single `*` stays within one path segment; use `**` to match across directories.",
-              "type": "string"
-            },
             "type": {
               "type": "string",
               "const": "fileExists"
+            },
+            "pattern": {
+              "description": "Project-root-relative glob; the plugin activates when any\ndiscovered file matches it. Validated at load like other user\nglobs (no absolute paths or `..` segments).\nA single `*` stays within one path segment; use `**` to match across directories.",
+              "type": "string"
             }
           },
           "required": [
@@ -574,16 +581,16 @@
           "description": "All conditions must be true.",
           "type": "object",
           "properties": {
+            "type": {
+              "type": "string",
+              "const": "all"
+            },
             "conditions": {
               "description": "Sub-conditions combined with logical AND.",
               "type": "array",
               "items": {
                 "$ref": "#/$defs/PluginDetection"
               }
-            },
-            "type": {
-              "type": "string",
-              "const": "all"
             }
           },
           "required": [
@@ -595,16 +602,16 @@
           "description": "Any condition must be true.",
           "type": "object",
           "properties": {
+            "type": {
+              "type": "string",
+              "const": "any"
+            },
             "conditions": {
               "description": "Sub-conditions combined with logical OR.",
               "type": "array",
               "items": {
                 "$ref": "#/$defs/PluginDetection"
               }
-            },
-            "type": {
-              "type": "string",
-              "const": "any"
             }
           },
           "required": [
@@ -1269,6 +1276,10 @@
           "maximum": 65535,
           "default": 20
         },
+        "cyclomaticPolicy": {
+          "description": "How the cyclomatic gate counts complexity (default: `standard`).\n`literal-membership` counts a chain of strict equality checks of one\nidentifier against primitive literals (`kind === \"a\" || kind === \"b\"`)\nas one predicate. The policy applies to the `maxCyclomatic` gate and\nto every CRAP score, so the `maxCrap` gate reads the same value.\nFindings then report the standard value as `standard_cyclomatic`. The\nhealth score, complexity density, and hotspots keep the standard\ncount. Older fallow versions reject this key as unknown, so pair it\nwith `minimumVersion`.",
+          "$ref": "#/$defs/CyclomaticPolicy"
+        },
         "maxCognitive": {
           "description": "Maximum allowed cognitive complexity per function (default: 15).\nFunctions exceeding this threshold are reported. Governs findings\nonly, never the health score.",
           "type": "integer",
@@ -1362,6 +1373,21 @@
       },
       "additionalProperties": false
     },
+    "CyclomaticPolicy": {
+      "description": "How `fallow health` counts cyclomatic complexity for its gates.\n\nThe policy changes the cyclomatic value that the `maxCyclomatic` gate reads\nand the cyclomatic value in every CRAP score. It does not change the health\nscore, the complexity density, or the hotspot ranking: those keep the\nstandard count so that grades stay comparable across projects.",
+      "oneOf": [
+        {
+          "description": "Count every decision point, `&&`, `||`, and `??` operator (`McCabe`).",
+          "type": "string",
+          "const": "standard"
+        },
+        {
+          "description": "Count a literal membership chain as one predicate. A chain such as\n`kind === \"a\" || kind === \"b\" || kind === \"c\"` adds no cyclomatic\nincrements for its `||` operators. Only strict equality checks of one\nidentifier against string, number, bigint, boolean, or `null` literals\nqualify. Member access, calls, mixed operators, and different operands\nkeep the standard count.",
+          "type": "string",
+          "const": "literal-membership"
+        }
+      ]
+    },
     "HealthThresholdOverride": {
       "description": "Per-file or per-function health threshold override.",
       "type": "object",

package/skills/fallow/SKILL.md

@@ -42,7 +42,7 @@ cargo install fallow-cli   # build from source
 
 ## Agent Rules
 1. **Always use `--format json --quiet`** for machine-readable output and parse stdout as JSON. Compact JSON is the default; never depend on whitespace or add `--pretty` in agent pipelines. Keep stderr separate so diagnostics remain visible; never merge it into the JSON stream with `2>&1`.
-2. **Preserve and interpret the exit status.** Codes 0 and 1 are successful analysis outcomes: 0 is clean and 1 means findings. Treat every other code according to `fallow schema.exit_codes`. Do not force a successful status, because that hides validation, license, setup, network, and security-gate outcomes.
+2. **Preserve and interpret the exit status.** Codes 0 and 1 are successful analysis outcomes. 0 means no enforced gate failed, and 1 means an enforced gate failed: findings, not a tool failure. Bare `fallow` in a machine format exits 0 on findings unless you pass `--fail-on-issues`. To gate, pass `--fail-on-issues`, run `fallow dead-code` or `fallow audit`, or read `gate_outcomes`: `status: "fail"` with `enforced: false` is a failing gate that did not set the exit code. Treat every other code according to `fallow schema.exit_codes`. Do not force a successful status, because that hides validation, license, setup, network, and security-gate outcomes.
 3. **Use `--explain`** to include a `_meta` object in JSON output with metric definitions, ranges, and interpretation hints. In human format, `--explain` prints a `Description:` line under each section header.
 4. **Use the root `kind` field** to identify typed JSON envelopes (`dead-code`, `dead-code-grouped`, `architecture`, `architecture-grouped`, `health`, `dupes`, `combined`, `audit`, etc.).
 5. **Use issue type filters** (`--unused-exports`, `--unused-files`, etc.) to limit output scope
@@ -375,7 +375,7 @@ fallow hooks install --target git   # pre-commit gate; --branch <ref> sets the f
 
 ## Exit Codes
 
-Codes 0 and 1 are successful analysis outcomes: 0 is clean and 1 means findings. Read `fallow schema.exit_codes` for validation, resource, runtime, network, security-gate, and upload failures instead of maintaining another copied table.
+Codes 0 and 1 are successful analysis outcomes. 0 means no enforced gate failed, and 1 means an enforced gate failed: findings, not a tool failure. Bare `fallow` in a machine format exits 0 on findings unless you pass `--fail-on-issues`. To gate, pass `--fail-on-issues`, run `fallow dead-code` or `fallow audit`, or read `gate_outcomes`: `status: "fail"` with `enforced: false` is a failing gate that did not set the exit code. Read `fallow schema.exit_codes` for validation, resource, runtime, network, security-gate, and upload failures instead of maintaining another copied table.
 
 When `--format json` is active and exit code is 2, errors are emitted as JSON on stdout:
 ```json