fallow 3.4.2 → 3.5.0

package/README.md

@@ -20,7 +20,7 @@ Static analysis is open source. An optional runtime layer adds production execut
 npm install --save-dev fallow   # or: pnpm add -D fallow / yarn add -D fallow / bun add -d fallow
 ```
 
-Installs the `fallow` CLI plus the companion `fallow-lsp` and `fallow-mcp` binaries in your project.
+Installs the `fallow` CLI in your project, along with the `fallow-lsp` and `fallow-mcp` launchers that start the LSP and MCP servers from the same binary.
 
 The package also ships a version-matched Agent Skill under `skills/fallow`.
 For tools that need CLI and issue-surface metadata without spawning the binary,

package/bin/fallow-lsp

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
 
+// Launcher shim: the platform packages ship a single multicall `fallow`
+// binary, so `fallow-lsp` spawns `fallow lsp-server` with the same stdio,
+// signal, and exit-code forwarding as a bare `fallow` invocation.
 const { runBinary } = require('../scripts/run-binary');
-runBinary('fallow-lsp');
+runBinary('fallow', { prependArgs: ['lsp-server'] });

package/bin/fallow-mcp

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
 
+// Launcher shim: the platform packages ship a single multicall `fallow`
+// binary, so `fallow-mcp` spawns `fallow mcp-server` with the same stdio,
+// signal, and exit-code forwarding as a bare `fallow` invocation.
 const { runBinary } = require('../scripts/run-binary');
-runBinary('fallow-mcp');
+runBinary('fallow', { prependArgs: ['mcp-server'] });

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -854,6 +854,16 @@
             "true",
             "false"
           ]
+        },
+        {
+          "name": "--churn",
+          "type": "bool",
+          "required": false,
+          "description": "OPT-IN: attach target-level git churn evidence from the health hotspot subsystem. Default off to avoid git-history latency",
+          "possible_values": [
+            "true",
+            "false"
+          ]
         }
       ]
     },
@@ -6380,7 +6390,8 @@
         "cli_command": "fallow inspect --format json --quiet",
         "key_params": [
           "target",
-          "production"
+          "production",
+          "include_churn"
         ],
         "license": "free",
         "license_note": null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "Codebase intelligence for TypeScript and JavaScript. Free static analysis of code and styles, optional paid runtime intelligence (Fallow Runtime). Quality, risk, architecture, dependencies, duplication, and design-system drift for humans, CI, and the agents writing your code. Zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -87,13 +87,13 @@
     "@tanstack/intent": "0.3.2"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.4.2",
-    "@fallow-cli/darwin-x64": "3.4.2",
-    "@fallow-cli/linux-x64-gnu": "3.4.2",
-    "@fallow-cli/linux-arm64-gnu": "3.4.2",
-    "@fallow-cli/linux-x64-musl": "3.4.2",
-    "@fallow-cli/linux-arm64-musl": "3.4.2",
-    "@fallow-cli/win32-arm64-msvc": "3.4.2",
-    "@fallow-cli/win32-x64-msvc": "3.4.2"
+    "@fallow-cli/darwin-arm64": "3.5.0",
+    "@fallow-cli/darwin-x64": "3.5.0",
+    "@fallow-cli/linux-x64-gnu": "3.5.0",
+    "@fallow-cli/linux-arm64-gnu": "3.5.0",
+    "@fallow-cli/linux-x64-musl": "3.5.0",
+    "@fallow-cli/linux-arm64-musl": "3.5.0",
+    "@fallow-cli/win32-arm64-msvc": "3.5.0",
+    "@fallow-cli/win32-x64-msvc": "3.5.0"
   }
 }

package/scripts/lazy-verify.js

@@ -66,8 +66,11 @@ function emitVerifyLog(env, payload) {
 }
 
 function binaryTargetsForPlatform(platform) {
+  // Platform packages ship one binary: the multicall `fallow`. The bundled
+  // lsp/mcp launchers spawn `fallow lsp-server` / `fallow mcp-server`, so there
+  // is only one binary to sentinel-track and verify.
   const ext = platform === "win32" ? ".exe" : "";
-  return [`fallow${ext}`, `fallow-lsp${ext}`, `fallow-mcp${ext}`];
+  return [`fallow${ext}`];
 }
 
 function statMtimeMs(absPath) {

package/scripts/lazy-verify.test.js

@@ -28,7 +28,8 @@ function ext() {
 }
 
 function binaryNames() {
-  return [`fallow${ext()}`, `fallow-lsp${ext()}`, `fallow-mcp${ext()}`];
+  // Platform packages ship a single multicall `fallow` binary.
+  return [`fallow${ext()}`];
 }
 
 function computeDigestsForDir(dir) {
@@ -116,7 +117,7 @@ test("ensureVerified verifies on cache miss and writes the sentinel", (t) => {
   assert.equal(sentinel.schemaVersion, SENTINEL_SCHEMA_VERSION);
   assert.equal(sentinel.packageVersion, "2.81.0");
   assert.equal(sentinel.packageName, "@fallow-cli/test-platform");
-  assert.equal(Object.keys(sentinel.binaries).length, 3);
+  assert.equal(Object.keys(sentinel.binaries).length, 1);
 });
 
 test("ensureVerified returns cached:true on a valid sentinel", (t) => {
@@ -164,7 +165,7 @@ test("ensureVerified invalidates sentinel on mtime drift", (t) => {
   );
   assert.equal(result.ok, true);
   assert.equal(result.cached, false);
-  assert.equal(verifyCallCount, 3, "verify should rerun for all three binaries");
+  assert.equal(verifyCallCount, 1, "verify should rerun for the single binary");
 });
 
 test("ensureVerified invalidates sentinel on packageVersion drift", (t) => {
@@ -215,12 +216,6 @@ test("ensureVerified invalidates sentinel on packageName drift", (t) => {
       packageName: "@fallow-cli/wrong-name",
       binaries: {
         [`fallow${ext()}`]: { mtimeMs: fs.statSync(path.join(dir, `fallow${ext()}`)).mtimeMs },
-        [`fallow-lsp${ext()}`]: {
-          mtimeMs: fs.statSync(path.join(dir, `fallow-lsp${ext()}`)).mtimeMs,
-        },
-        [`fallow-mcp${ext()}`]: {
-          mtimeMs: fs.statSync(path.join(dir, `fallow-mcp${ext()}`)).mtimeMs,
-        },
       },
     }),
   );
@@ -266,13 +261,13 @@ test("ensureVerified invalidates sentinel on schemaVersion drift", (t) => {
 test("ensureVerified returns sig-invalid on a tampered signature", (t) => {
   _resetWarningState();
   const { privateKey, rawPub } = makeKeypair();
-  const dir = mkPlatformDir(privateKey, { corruptSigFor: `fallow-lsp${ext()}` });
+  const dir = mkPlatformDir(privateKey, { corruptSigFor: `fallow${ext()}` });
   t.after(() => cleanup(dir));
 
   const result = ensureVerified(baseInput(dir, (p) => _verifyWithKey(p, rawPub)));
   assert.equal(result.ok, false);
   assert.equal(result.code, "sig-invalid");
-  assert.match(result.binary, /fallow-lsp/);
+  assert.match(result.binary, /fallow/);
   // Sentinel must NOT have been written on failure
   assert.equal(fs.existsSync(path.join(dir, SENTINEL_FILENAME)), false);
 });

package/scripts/run-binary.js

@@ -146,7 +146,15 @@ function guardBrokenStdout() {
   });
 }
 
-function runBinary(binaryBaseName) {
+// Run the resolved platform binary. `options.prependArgs` (default none) is a
+// list of leading arguments inserted before the process argv, used by the
+// `fallow-lsp` / `fallow-mcp` launcher shims to spawn the multicall binary as
+// `fallow lsp-server` / `fallow mcp-server`. Because the platform packages ship
+// a single `fallow` binary, those shims pass `binaryBaseName = "fallow"` and
+// the subcommand via `prependArgs`; signal, exit-code, and version-line
+// handling stay identical to a bare `fallow` invocation.
+function runBinary(binaryBaseName, options = {}) {
+  const prependArgs = Array.isArray(options.prependArgs) ? options.prependArgs : [];
   guardBrokenStdout();
   const { pkg, manifestPath, platformPkgDir } = resolvePlatformPaths();
   const resolvedVersion = readResolvedVersion(manifestPath);
@@ -166,7 +174,7 @@ function runBinary(binaryBaseName) {
   }
 
   try {
-    execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+    execFileSync(binaryPath, [...prependArgs, ...process.argv.slice(2)], { stdio: "inherit" });
   } catch (e) {
     if (e.status === undefined) throw e;
     if (e.status === null) {

package/scripts/verify-binary.js

@@ -293,11 +293,15 @@ function binaryTargetsForPlatform(platformId) {
   // and tests can synthesize a Windows verify without running on Windows.
   const isWindows = typeof platformId === "string" && platformId.startsWith("win32");
   const ext = isWindows ? ".exe" : "";
-  return [
-    { binary: `fallow${ext}`, asset: `fallow-${platformId}${ext}` },
-    { binary: `fallow-lsp${ext}`, asset: `fallow-lsp-${platformId}${ext}` },
-    { binary: `fallow-mcp${ext}`, asset: `fallow-mcp-${platformId}${ext}` },
-  ];
+  // Platform packages ship ONE binary now: the multicall `fallow` (CLI + LSP +
+  // MCP in one engine). The bundled `fallow-lsp` / `fallow-mcp` launchers live
+  // in the wrapper and spawn `fallow lsp-server` / `fallow mcp-server`. The
+  // authoritative digest is the `fallowDigests.fallow` field the release
+  // pipeline embeds for every bundled package; the `asset` below is only the
+  // legacy GitHub-release fallback for pre-embedded-digest packages, which
+  // never shipped this bundled binary, so it is inert for bundled installs and
+  // fails closed (digest-mismatch) in the impossible case it is ever reached.
+  return [{ binary: `fallow${ext}`, asset: `fallow-${platformId}${ext}` }];
 }
 
 function isSkipRequested() {

package/scripts/verify-binary.test.js

@@ -243,7 +243,7 @@ function makePlatformDir(privateKey, options) {
   const opts = options || {};
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-vbtest-"));
   const ext = process.platform === "win32" ? ".exe" : "";
-  for (const base of ["fallow", "fallow-lsp", "fallow-mcp"]) {
+  for (const base of ["fallow"]) {
     const binaryPath = path.join(dir, `${base}${ext}`);
     const content = Buffer.from(`mock ${base} contents`);
     fs.writeFileSync(binaryPath, content);
@@ -349,7 +349,7 @@ test("verifyInstalled resolves a global npm install from the fallow package dire
   );
 
   const ext = process.platform === "win32" ? ".exe" : "";
-  for (const base of ["fallow", "fallow-lsp", "fallow-mcp"]) {
+  for (const base of ["fallow"]) {
     const binaryPath = path.join(platformDir, `${base}${ext}`);
     const content = Buffer.from(`global install ${base}`);
     fs.writeFileSync(binaryPath, content);
@@ -367,9 +367,9 @@ test("verifyInstalled resolves a global npm install from the fallow package dire
   assert.equal(result.version, "9.9.9");
 });
 
-test("verifyInstalled with dirOverride fails fast on the first bad signature", async (t) => {
+test("verifyInstalled with dirOverride fails on a bad signature", async (t) => {
   const { privateKey, rawPub } = makeKeypair();
-  const dir = makePlatformDir(privateKey, { corruptSigFor: "fallow-lsp" });
+  const dir = makePlatformDir(privateKey, { corruptSigFor: "fallow" });
   t.after(() => cleanup(dir));
   const result = await verifyInstalled({
     dirOverride: dir,
@@ -378,12 +378,12 @@ test("verifyInstalled with dirOverride fails fast on the first bad signature", a
   });
   assert.equal(result.ok, false);
   assert.equal(result.code, "sig-invalid");
-  assert.match(result.binary, /fallow-lsp/);
+  assert.match(result.binary, /fallow/);
 });
 
 test("verifyInstalled with dirOverride reports sig-missing when a .sig is absent", async (t) => {
   const { privateKey, rawPub } = makeKeypair();
-  const dir = makePlatformDir(privateKey, { skipSigFor: "fallow-mcp" });
+  const dir = makePlatformDir(privateKey, { skipSigFor: "fallow" });
   t.after(() => cleanup(dir));
   const result = await verifyInstalled({
     dirOverride: dir,
@@ -392,13 +392,13 @@ test("verifyInstalled with dirOverride reports sig-missing when a .sig is absent
   });
   assert.equal(result.ok, false);
   assert.equal(result.code, "sig-missing");
-  assert.match(result.binary, /fallow-mcp/);
+  assert.match(result.binary, /fallow/);
 });
 
 test("verifyInstalled threads the resolved version into the sig-missing message", async (t) => {
   const { privateKey, rawPub } = makeKeypair();
-  const preDir = makePlatformDir(privateKey, { skipSigFor: "fallow-mcp" });
-  const eraDir = makePlatformDir(privateKey, { skipSigFor: "fallow-mcp" });
+  const preDir = makePlatformDir(privateKey, { skipSigFor: "fallow" });
+  const eraDir = makePlatformDir(privateKey, { skipSigFor: "fallow" });
   t.after(() => {
     cleanup(preDir);
     cleanup(eraDir);
@@ -463,7 +463,7 @@ test("verifyInstalled honors FALLOW_SKIP_BINARY_VERIFY", async (t) => {
 function computeDigestsForDir(dir) {
   const ext = process.platform === "win32" ? ".exe" : "";
   const out = {};
-  for (const base of ["fallow", "fallow-lsp", "fallow-mcp"]) {
+  for (const base of ["fallow"]) {
     const fileName = `${base}${ext}`;
     const full = path.join(dir, fileName);
     out[fileName] =
@@ -549,7 +549,7 @@ test("verifyInstalled falls back to the provider when the embedded digest is mis
     },
   });
   assert.equal(result.ok, true);
-  assert.equal(providerCalls, 3);
+  assert.equal(providerCalls, 1);
 });
 
 test("verifyInstalled falls back to the provider when fallowDigests is partial / malformed", async (t) => {
@@ -573,8 +573,8 @@ test("verifyInstalled falls back to the provider when fallowDigests is partial /
     },
   });
   assert.equal(result.ok, true);
-  // One call per binary because all three entries fail to normalize.
-  assert.equal(providerCalls, 3);
+  // One call for the single shipped binary because its entry fails to normalize.
+  assert.equal(providerCalls, 1);
 });
 
 test("verifyInstalled returns digest-mismatch when the embedded digest disagrees with the binary", async (t) => {
@@ -587,8 +587,6 @@ test("verifyInstalled returns digest-mismatch when the embedded digest disagrees
     version: "1.0.0",
     fallowDigests: {
       [`fallow${ext}`]: "sha256:" + "a".repeat(64),
-      [`fallow-lsp${ext}`]: "sha256:" + "a".repeat(64),
-      [`fallow-mcp${ext}`]: "sha256:" + "a".repeat(64),
     },
   });
   const result = await verifyInstalled({
@@ -644,9 +642,9 @@ test("verifyInstalledSync with embedded digests returns ok end-to-end", (t) => {
   assert.equal(result.package, "<override>");
 });
 
-test("verifyInstalledSync fails fast on first bad signature", (t) => {
+test("verifyInstalledSync fails on a bad signature", (t) => {
   const { privateKey, rawPub } = makeKeypair();
-  const dir = makePlatformDir(privateKey, { corruptSigFor: "fallow-lsp" });
+  const dir = makePlatformDir(privateKey, { corruptSigFor: "fallow" });
   t.after(() => cleanup(dir));
   writeManifest(dir, {
     name: "@fallow-cli/x",
@@ -659,7 +657,7 @@ test("verifyInstalledSync fails fast on first bad signature", (t) => {
   });
   assert.equal(result.ok, false);
   assert.equal(result.code, "sig-invalid");
-  assert.match(result.binary, /fallow-lsp/);
+  assert.match(result.binary, /fallow/);
 });
 
 test("verifyInstalledSync reports digest-mismatch when bytes diverge from embedded digest", (t) => {
@@ -671,11 +669,7 @@ test("verifyInstalledSync reports digest-mismatch when bytes diverge from embedd
     version: "9.9.9",
     fallowDigests: {
       fallow: "sha256:" + "a".repeat(64),
-      "fallow-lsp": "sha256:" + "a".repeat(64),
-      "fallow-mcp": "sha256:" + "a".repeat(64),
       "fallow.exe": "sha256:" + "a".repeat(64),
-      "fallow-lsp.exe": "sha256:" + "a".repeat(64),
-      "fallow-mcp.exe": "sha256:" + "a".repeat(64),
     },
   });
   const result = verifyInstalledSync({

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

@@ -509,7 +509,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.4.2",
+  "version": "3.5.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -907,7 +907,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.4.2",
+  "version": "3.5.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -982,7 +982,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.4.2",
+  "version": "3.5.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1083,7 +1083,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1112,7 +1112,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1185,6 +1185,7 @@ Compose one evidence bundle before editing a file or exported symbol. This is th
 ```bash
 fallow inspect --file src/api.ts --format json --quiet
 fallow inspect --symbol src/api.ts:fetchUser --format json --quiet
+fallow inspect --file src/api.ts --churn --format json --quiet
 ```
 
 ### Target Flags
@@ -1193,6 +1194,7 @@ fallow inspect --symbol src/api.ts:fetchUser --format json --quiet
 |------|-------------|
 | `--file <PATH>` | Inspect one project-relative file |
 | `--symbol <FILE:EXPORT>` | Inspect one exported symbol. Supporting dead-code, duplication, complexity, and security evidence is file-scoped in the first version |
+| `--churn` | Add target-level git churn evidence. Off by default; missing git history is reported as `unavailable` |
 
 Common global flags: `--format`, `--quiet`, `--root`, `--config`, `--workspace`, `--production`, `--no-cache`, `--threads`.
 
@@ -1215,13 +1217,14 @@ Common global flags: `--format`, `--quiet`, `--root`, `--config`, `--workspace`,
     "dead_code": { "status": "ok", "scope": "file", "data": {} },
     "duplication": { "status": "ok", "scope": "project_filtered_to_file", "data": {} },
     "complexity": { "status": "ok", "scope": "project_filtered_to_file", "data": {} },
-    "security": { "status": "ok", "scope": "file", "data": {} }
+    "security": { "status": "ok", "scope": "file", "data": {} },
+    "churn": { "status": "ok", "scope": "project_filtered_to_file", "data": {} }
   },
   "warnings": []
 }
 ```
 
-Each evidence section carries `status` and `scope`. Non-fatal child-analysis failures become section-level errors and warnings, so callers can still use the remaining evidence.
+Each evidence section carries `status` and `scope`. The optional churn section can report `ok`, `unavailable`, or `error`. Non-fatal analysis failures become section-level errors and warnings, so callers can still use the remaining evidence.
 
 ---
 
@@ -1798,7 +1801,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 
 ## CI Integration
 
-- **GitHub Actions**: `uses: fallow-rs/fallow@v2` - supports SARIF upload to Code Scanning, inline PR annotations (`annotations: true`), PR comments, all commands. Annotations use workflow commands (no Advanced Security required); limit with `max-annotations` (default 50). Set `score: true` to compute health score and enable the health delta header in PR comments
+- **GitHub Actions**: `uses: fallow-rs/fallow@v3` - supports SARIF upload to Code Scanning, inline PR annotations (`annotations: true`), PR comments, all commands. Annotations use workflow commands (no Advanced Security required); limit with `max-annotations` (default 50). Set `score: true` to compute health score and enable the health delta header in PR comments
 - **GitLab CI**: include `ci/gitlab-ci.yml` template and extend `.fallow` - generates Code Quality reports via `--format codeclimate` / `--format gitlab-codequality` (inline MR annotations), rich MR comments, code review comments, all commands. Use `fallow ci-template gitlab --vendor` when runners cannot reach `raw.githubusercontent.com`; commit the generated `ci/` and `action/` files and use GitLab's local include syntax. Variables use `FALLOW_` prefix (e.g., `FALLOW_COMMAND`, `FALLOW_FAIL_ON_ISSUES`). Set `FALLOW_SCORE: "true"` to compute health score; `FALLOW_TREND: "true"` to compare against saved snapshots
 - **Any CI**: `npx fallow --ci` - equivalent to `--format sarif --fail-on-issues --quiet`
 
@@ -1833,7 +1836,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.4.2",
+  "version": "3.5.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1993,7 +1996,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.4.2",
+  "version": "3.5.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2037,11 +2040,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.4.2",
+  "version": "3.5.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.4.2",
+    "version": "3.5.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/skills/fallow/references/mcp.md

@@ -15,7 +15,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `analyze` | analysis | free | `fallow dead-code --format json --quiet` | `issue_types`, `production`, `workspace`, `baseline`, `group_by`, `file` | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + re-export cycles (barrel files that form a structural loop, silently breaking re-exports) + boundary violations + rule-pack policy violations (banned calls, imports, and catalogue-derived effects declared via the `rulePacks` config key) + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group |
 | `check_changed` | analysis | free | `fallow dead-code --changed-since <ref> --format json --quiet` | `since`, `baseline`, `fail_on_regression` | Incremental analysis of files changed since a git ref |
 | `security_candidates` | analysis | free | `fallow security --format json --quiet` | `gate`, `surface`, `changed_since`, `paths` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, severity, evidence, trace, optional `reachability`, blind-spot counters, and optional `unresolved_callee_diagnostics` samples for dynamic callee follow-up. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), where URL-category sinks may include `url_shape` (`fixed-origin-dynamic-path` or `dynamic-origin`), an optional `taint_flow` source-to-sink triple, and a stable `finding_id` (equal to the SARIF fingerprint) for cross-run correlation; there is no `impact` field (deciding exploitability is the agent's job). Set `surface: true` to include top-level `attack_surface[]` entries with defensive-boundary prompts for a verifier. Set `gate` to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires `changed_since`. `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow; `reachability.taint_confidence` tiers each reachable candidate as `arg-level` (sink argument traces to a same-module source read, strong) or `module-level` (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `surface`, `gate`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, untrusted-source reachability trace hops, and unresolved-callee diagnostics. See <https://docs.fallow.tools/cli/security-agent-verification> for the verifier packet and verdict recipe. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
-| `inspect_target` | analysis | free | `fallow inspect --format json --quiet` | `target`, `production` | Compose one evidence bundle for a file or exported symbol. File targets use `target: { type: "file", file }`; symbol targets use `target: { type: "symbol", file, export_name }`. Returns `kind: "inspect_target"`, normalized target identity, `trace_file`, optional `trace_export`, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, and security candidates scoped to the file. Evidence sections carry `status` and `scope`; symbol targets warn when supporting evidence is file-scoped. Supports `root`, `config`, `production`, `workspace`, `no_cache`, and `threads`; `production` applies to trace, dead-code, and health evidence only. Raise `FALLOW_TIMEOUT_SECS` for large repos. |
+| `inspect_target` | analysis | free | `fallow inspect --format json --quiet` | `target`, `production`, `include_churn` | Compose one evidence bundle for a file or exported symbol. File targets use `target: { type: "file", file }`; symbol targets use `target: { type: "symbol", file, export_name }`. Returns `kind: "inspect_target"`, normalized target identity, `trace_file`, optional `trace_export`, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, and security candidates scoped to the file. Set `include_churn: true` to add target-level git churn from the health hotspot subsystem. Churn is off by default, and unavailable git history or analysis failures remain explicit section states. Evidence sections carry `status` and `scope`; symbol targets warn when supporting evidence is file-scoped. Supports `root`, `config`, `production`, `workspace`, `include_churn`, `no_cache`, and `threads`; `production` applies to trace, dead-code, and health evidence only. Raise `FALLOW_TIMEOUT_SECS` for large repos. |
 | `guard` | introspection | free | `fallow guard <file> --format json --quiet` | `files` | Report the architecture rules that apply to given files before editing them: boundary zone, allowed import zones, forbidden calls, and rule-pack policies |
 | `find_dupes` | analysis | free | `fallow dupes --format json --quiet` | `mode`, `min_tokens`, `min_occurrences`, `top`, `threshold` | 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 |
 | `check_health` | analysis | free | `fallow health --format json --quiet` | `score`, `css`, `file_scores`, `hotspots`, `targets`, `coverage`, `runtime_coverage`, `max_crap`, `group_by` | 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 |

package/skills/fallow/references/patterns.md

@@ -111,7 +111,7 @@ Parse the JSON to list specific files and exports that became unused.
 ### GitHub Actions: Using the Official Action
 
 ```yaml
-- uses: fallow-rs/fallow@v2
+- uses: fallow-rs/fallow@v3
   with:
     command: dead-code
     fail-on-issues: true
@@ -123,7 +123,7 @@ Parse the JSON to list specific files and exports that became unused.
 Fail a PR only when it introduces new security candidates (or makes existing ones newly reachable). Gated failures exit with code 8; the `issues` output counts only matching gate candidates. PR comment and review renderers skip security envelopes.
 
 ```yaml
-- uses: fallow-rs/fallow@v2
+- uses: fallow-rs/fallow@v3
   with:
     command: security
     security-gate: new   # or newly-reachable (needs a base ref via changed-since or PR auto-scoping)
@@ -134,7 +134,7 @@ GitLab equivalent: `FALLOW_COMMAND: "security"` with `FALLOW_SECURITY_GATE: "new
 ### GitHub Actions: With Health Score
 
 ```yaml
-- uses: fallow-rs/fallow@v2
+- uses: fallow-rs/fallow@v3
   with:
     score: true
     changed-since: main
@@ -145,7 +145,7 @@ Computes a health score (0-100 with letter grade) in combined mode and enables t
 ### GitHub Actions: Severity-Aware PR Quality Gate (Audit)
 
 ```yaml
-- uses: fallow-rs/fallow@v2
+- uses: fallow-rs/fallow@v3
   with:
     command: audit
     gate: new-only        # default; fails only on findings introduced by this PR
@@ -157,7 +157,7 @@ Runs `fallow audit` to combine dead-code + complexity + duplication scoped to ch
 The action exposes `outputs.verdict` (`pass`/`warn`/`fail`) and `outputs.gate` for downstream conditionals; `outputs.issues` holds the introduced count under `gate: new-only` and the total count under `gate: all`.
 
 ```yaml
-- uses: fallow-rs/fallow@v2
+- uses: fallow-rs/fallow@v3
   id: fallow
   with:
     command: audit
@@ -174,7 +174,7 @@ Three additional outputs surface silent failures in the action's PR comment / re
 The official action supports inline PR annotations via GitHub workflow commands. This does not require Advanced Security (unlike SARIF upload) and works on any GitHub plan.
 
 ```yaml
-- uses: fallow-rs/fallow@v2
+- uses: fallow-rs/fallow@v3
   with:
     command: dead-code
     changed-since: main

package/types/output-contract.d.ts

@@ -24,9 +24,9 @@
 
 
 /**
- * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator. Current kind values: `audit`, `explain`, `inspect_target`, `trace`, `review-envelope`, `review-reconcile`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `list-workspaces`, `health`, `dupes`, `dead-code-grouped`, `impact`, `impact-cross-repo`, `security`, `security-survivors`, `security-blind-spots`, `dead-code`, `combined`, `feature-flags`, `audit-brief`, `decision-surface`, `review-walkthrough-guide`, `review-walkthrough-validation`, `suppression-inventory`. Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array.
+ * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator. Current kind values: `audit`, `explain`, `inspect_target`, `trace`, `review-envelope`, `review-reconcile`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `list-workspaces`, `health`, `dupes`, `dead-code-grouped`, `impact`, `impact-cross-repo`, `security`, `security-survivors`, `security-blind-spots`, `dead-code`, `combined`, `feature-flags`, `audit-brief`, `decision-surface`, `review-walkthrough-guide`, `review-walkthrough-validation`, `suppression-inventory`. Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array. `ErrorOutput` is the `--format json` failure document, emitted on stdout with a non-zero exit; it carries no `kind` and is discriminated by the `error: true` field.
  */
-export type FallowJsonOutput = (FallowOutput | CodeClimateOutput)
+export type FallowJsonOutput = (FallowOutput | CodeClimateOutput | ErrorOutput)
 /**
  * Typed root of every fallow JSON envelope shape that serializes as a JSON
  * object and participates in the documented `FallowOutput` contract. The
@@ -86,7 +86,7 @@ kind: "dead-code"
 kind: "combined"
 }) | (FeatureFlagsOutput & {
 kind: "feature-flags"
-}) | (ReviewBriefOutput & {
+}) | (ReviewBriefWireOutput & {
 kind: "audit-brief"
 }) | (DecisionSurfaceOutput & {
 kind: "decision-surface"
@@ -651,7 +651,7 @@ export_name: string
 type: "symbol"
 })
 export type InspectIdentity = (InspectFileIdentity | InspectSymbolIdentity)
-export type InspectSectionStatus = ("ok" | "error")
+export type InspectSectionStatus = ("ok" | "unavailable" | "error")
 export type InspectEvidenceScope = ("symbol" | "file" | "project_filtered_to_file")
 /**
  * Best-effort classification of why a callee did not resolve to an edge.
@@ -835,6 +835,12 @@ export type FeatureFlagActionType = ("investigate-flag" | "suppress-line")
  * Serializes as the integer `REVIEW_BRIEF_SCHEMA_VERSION`.
  */
 export type ReviewBriefSchemaVersion = number
+/**
+ * The exactly-three shippable decision categories (the SOLID-3). No cut category
+ * (abstraction / deletion / convention / irreversibility) is representable: this
+ * enum is the structural guarantee that confirmed-noise categories never ship.
+ */
+export type DecisionCategory = ("coupling-boundary" | "public-api-contract" | "dependency")
 /**
  * Coarse risk classification for a changeset, a pure function of the change
  * size (file count plus, once threaded, net lines).
@@ -864,12 +870,6 @@ export type ConfidenceFlag = ("dynamic-dispatch" | "re-export-indirection")
  * The category of a single weakening signal.
  */
 export type WeakeningKind = ("test-weakened" | "threshold-lowered" | "suppression-added" | "security-check-removed")
-/**
- * The exactly-three shippable decision categories (the SOLID-3). No cut category
- * (abstraction / deletion / convention / irreversibility) is representable: this
- * enum is the structural guarantee that confirmed-noise categories never ship.
- */
-export type DecisionCategory = ("coupling-boundary" | "public-api-contract" | "dependency")
 /**
  * Independently-versioned wire-version newtype. Serializes as the integer
  * [`DECISION_SURFACE_SCHEMA_VERSION`].
@@ -7206,6 +7206,11 @@ duplication: InspectEvidenceSection
 complexity: InspectEvidenceSection
 security: InspectEvidenceSection
 impact_closure: InspectEvidenceSection
+/**
+ * OPT-IN target-level git churn. Omitted unless historical evidence was
+ * explicitly requested by the caller.
+ */
+churn?: (InspectEvidenceSection | null)
 /**
  * OPT-IN symbol-level call chain. Present only when `--symbol-chain` was
  * requested AND the target is a SYMBOL (best-effort, syntactic, OFF the
@@ -9347,10 +9352,22 @@ dead_export_count: number
 dead_exports: string[]
 }
 /**
- * `_meta.feature_flags` details emitted with `--explain`.
+ * Optional `_meta` block for [`FeatureFlagsOutput`]. Both fields are optional
+ * because the two contributors are independent: `feature_flags` details are
+ * present only with `--explain`, and `telemetry` is injected post-pass by
+ * [`attach_telemetry_meta`] whenever an analysis run id is available (which is
+ * the default path). Mirrors `Meta` / `CombinedMeta`, which also model
+ * `telemetry` as an optional, never-required property.
  */
 export interface FeatureFlagsMeta {
-feature_flags: FeatureFlagsMetaDetails
+/**
+ * Feature-flag detection explanations, emitted only with `--explain`.
+ */
+feature_flags?: (FeatureFlagsMetaDetails | null)
+/**
+ * Local telemetry correlation metadata for agent follow-up runs.
+ */
+telemetry?: (TelemetryMeta | null)
 }
 /**
  * Feature flag explanatory metadata.
@@ -9378,21 +9395,48 @@ medium: string
 low: string
 }
 /**
- * The full `fallow audit --brief --format json` envelope. Carries the
- * informational verdict, the triage and graph-facts orientation stages, plus
- * the reused "subtract" section (the same dead-code / duplication / complexity
- * payload `fallow audit --format json` emits).
+ * Complete `fallow audit --brief --format json` wire envelope.
+ *
+ * This is distinct from [`ReviewBriefOutput`], which is the reusable review
+ * digest embedded in walkthrough output. The wire envelope also carries audit
+ * metadata, optional telemetry, and the subtract-style analysis subreports.
  */
-export interface ReviewBriefOutput {
+export interface ReviewBriefWireOutput {
 schema_version: ReviewBriefSchemaVersion
-/**
- * Fallow CLI version that produced this output.
- */
-version: string
+version: ToolVersion
 /**
  * Command discriminator singleton: always `"audit-brief"`.
  */
 command: string
+verdict: AuditVerdict
+/**
+ * Number of changed files in the audit scope.
+ */
+changed_files_count: number
+/**
+ * Base ref used to determine the changeset.
+ */
+base_ref: string
+/**
+ * Human-readable description of the resolved base, when available.
+ */
+base_description?: (string | null)
+/**
+ * Head commit SHA, when available.
+ */
+head_sha?: (string | null)
+elapsed_ms: ElapsedMs
+/**
+ * Whether base-snapshot analysis was skipped for this run.
+ */
+base_snapshot_skipped?: (boolean | null)
+summary: AuditSummary
+attribution: AuditAttribution
+/**
+ * Optional metric definitions and local telemetry correlation metadata.
+ */
+_meta?: (Meta | null)
+decisions: DecisionSurface
 triage: DiffTriage
 graph_facts: GraphFacts
 partition: PartitionFacts
@@ -9400,20 +9444,130 @@ impact_closure: ImpactClosureFacts
 focus: FocusMap
 deltas: ReviewDeltas
 /**
- * 6.F, headline: reviewer-private weakening signals (tests
- * removed/skipped, thresholds lowered, suppressions added, security steps
- * removed). Advisory, never gates, never auto-posted.
+ * Reviewer-private weakening signals.
  */
 weakening: WeakeningSignal[]
 routing: RoutingFacts
-decisions: DecisionSurface
+/**
+ * Dead-code findings scoped to the audit changeset.
+ */
+dead_code?: (CheckOutput | null)
+/**
+ * Duplication findings scoped to the audit changeset.
+ */
+duplication?: (DupesReportPayload | null)
+/**
+ * Complexity findings scoped to the audit changeset.
+ */
+complexity?: (HealthReport | null)
+}
+/**
+ * The ranked, capped decision surface plus the set of signal_ids the
+ * deterministic layer emitted (the anti-hallucination allowlist).
+ */
+export interface DecisionSurface {
+/**
+ * Ranked decisions, highest consequence first.
+ */
+decisions: Decision[]
+/**
+ * Present when more than the cap were extracted.
+ */
+truncated?: (TruncationNote | null)
+/**
+ * Every signal_id the deterministic layer emitted, INCLUDING those whose
+ * decision was collapsed below the cap or suppressed. The anti-hallucination
+ * allowlist: an agent decision whose id is absent is rejected.
+ */
+emitted_signal_ids: string[]
+}
+/**
+ * One consequential structural decision, framed as a judgment question for a
+ * human with taste, anchored to a fallow-emitted signal.
+ */
+export interface Decision {
+/**
+ * Deterministic anchor to the fallow-emitted candidate this decision frames.
+ * `accept_signal_id` rejects any id not in the emitted set.
+ */
+signal_id: string
+category: DecisionCategory
+/**
+ * The decision framed as a judgment question for the human.
+ */
+question: string
+/**
+ * Root-relative file the decision is anchored at.
+ */
+anchor_file: string
+/**
+ * 1-based anchor line, when the underlying signal carries one (0 = file head).
+ */
+anchor_line: number
+/**
+ * The raw fallow-emitted candidate key the `signal_id` hashes.
+ */
+signal_key: string
+/**
+ * The `signal_id` this decision WOULD have had before any rename in this
+ * change (the anchor file's pre-rename path). Present only when the anchor was
+ * renamed. A review-memory layer carries a dismissal across a `git mv`: if
+ * `previous_signal_id` was dismissed in an earlier PR, treat this decision as
+ * dismissed too. Keeps `signal_id` itself exact + deterministic.
+ */
+previous_signal_id?: (string | null)
+/**
+ * Blast radius: count of modules affected beyond the diff by this decision.
+ */
+blast: number
+/**
+ * `blast * reversibility_weight`: the rank key (sorted descending).
+ */
+consequence: number
+/**
+ * The routed expert(s) to ask, from ownership routing. Empty when no
+ * ownership signal is available for the anchor file.
+ */
+expert: string[]
+/**
+ * Whether the anchor file's only qualified owner is one person.
+ */
+bus_factor_one?: boolean
+/**
+ * Honest per-decision count: in-repo modules OUTSIDE the diff that already
+ * depend on this decision's anchor. This is the DISPLAY number (taste
+ * ownership: the human reads reversibility from the count itself), distinct
+ * from `blast` (the project-wide proxy used only for ranking). Never a door
+ * label. Internal-only by construction, so it cannot see a published library's
+ * external consumers; the public-API trade-off clause names that risk in prose.
+ */
+internal_consumer_count: number
+/**
+ * The named structural sacrifice this change makes, stated as a fact, never a
+ * recommendation (e.g. "Couples `app` to `infra`; 4 in-repo modules already
+ * depend on this anchor."). A sibling fact to `question`; it never tells the
+ * human what to choose.
+ */
+tradeoff: string
+}
+/**
+ * A note for decisions collapsed below the cap.
+ */
+export interface TruncationNote {
+/**
+ * How many decisions were collapsed below the cap.
+ */
+collapsed: number
+/**
+ * Human-readable collapse reason.
+ */
+reason: string
 }
 /**
  * Stage 0 of the brief: triage facts derived purely from the diff size.
  *
- * `hunks` and `net_lines` are `None` in v1: the file-level audit does not yet
- * thread a `DiffIndex` (from `report/ci/diff_filter.rs`). They populate later,
- * on `--diff-file` / `--diff-stdin`, without a schema bump.
+ * `hunks` and `net_lines` are populated when the caller supplies parsed diff
+ * evidence. They remain absent when no diff is available.
  */
 export interface DiffTriage {
 /**
@@ -9421,11 +9575,11 @@ export interface DiffTriage {
  */
 files: number
 /**
- * Number of diff hunks. `None` in v1 (no diff index threaded yet).
+ * Number of diff hunks, or `None` when no diff evidence was supplied.
  */
 hunks?: (number | null)
 /**
- * Net added-minus-removed lines. `None` in v1 (no diff index threaded yet).
+ * Net added-minus-removed lines, or `None` without diff evidence.
  */
 net_lines?: (number | null)
 risk_class: RiskClass
@@ -9437,18 +9591,20 @@ review_effort: ReviewEffort
  * `boundaries_touched` is derived from the run's boundary-violation zones;
  * `reachable_from` is populated by the impact closure (the affected-not-shown
  * set: modules the changed code is reachable from / affects, none in the diff).
- * `exports_added` / `api_width_delta` stay honestly stubbed (`0`) until the
- * export-surface delta lands. The fields are present and correctly typed so
- * values fill in later without a schema bump.
+ * `exports_added` and `api_width_delta` both report the exports-aware public API
+ * widening count. Removed exports are not represented in this widening-only
+ * signal.
  */
 export interface GraphFacts {
 /**
- * Number of exports added by the changeset. Stubbed to `0` in v1.
+ * Number of public API exports added by the changeset. Zero means the
+ * changeset adds no public API exports.
  */
 exports_added: number
 /**
- * Change in public API width (added minus removed exports). Stubbed to `0`
- * in v1.
+ * Widening-only public API delta, currently equal to `exports_added`.
+ * Removed exports are not represented, so zero means no public API exports
+ * were added.
  */
 api_width_delta: number
 /**
@@ -9696,108 +9852,6 @@ expert: string[]
  */
 bus_factor_one?: boolean
 }
-/**
- * The ranked, capped decision surface plus the set of signal_ids the
- * deterministic layer emitted (the anti-hallucination allowlist).
- */
-export interface DecisionSurface {
-/**
- * Ranked decisions, highest consequence first.
- */
-decisions: Decision[]
-/**
- * Present when more than the cap were extracted.
- */
-truncated?: (TruncationNote | null)
-/**
- * Every signal_id the deterministic layer emitted, INCLUDING those whose
- * decision was collapsed below the cap or suppressed. The anti-hallucination
- * allowlist: an agent decision whose id is absent is rejected.
- */
-emitted_signal_ids: string[]
-}
-/**
- * One consequential structural decision, framed as a judgment question for a
- * human with taste, anchored to a fallow-emitted signal.
- */
-export interface Decision {
-/**
- * Deterministic anchor to the fallow-emitted candidate this decision frames.
- * `accept_signal_id` rejects any id not in the emitted set.
- */
-signal_id: string
-category: DecisionCategory
-/**
- * The decision framed as a judgment question for the human.
- */
-question: string
-/**
- * Root-relative file the decision is anchored at.
- */
-anchor_file: string
-/**
- * 1-based anchor line, when the underlying signal carries one (0 = file head).
- */
-anchor_line: number
-/**
- * The raw fallow-emitted candidate key the `signal_id` hashes.
- */
-signal_key: string
-/**
- * The `signal_id` this decision WOULD have had before any rename in this
- * change (the anchor file's pre-rename path). Present only when the anchor was
- * renamed. A review-memory layer carries a dismissal across a `git mv`: if
- * `previous_signal_id` was dismissed in an earlier PR, treat this decision as
- * dismissed too. Keeps `signal_id` itself exact + deterministic.
- */
-previous_signal_id?: (string | null)
-/**
- * Blast radius: count of modules affected beyond the diff by this decision.
- */
-blast: number
-/**
- * `blast * reversibility_weight`: the rank key (sorted descending).
- */
-consequence: number
-/**
- * The routed expert(s) to ask, from ownership routing. Empty when no
- * ownership signal is available for the anchor file.
- */
-expert: string[]
-/**
- * Whether the anchor file's only qualified owner is one person.
- */
-bus_factor_one?: boolean
-/**
- * Honest per-decision count: in-repo modules OUTSIDE the diff that already
- * depend on this decision's anchor. This is the DISPLAY number (taste
- * ownership: the human reads reversibility from the count itself), distinct
- * from `blast` (the project-wide proxy used only for ranking). Never a door
- * label. Internal-only by construction, so it cannot see a published library's
- * external consumers; the public-API trade-off clause names that risk in prose.
- */
-internal_consumer_count: number
-/**
- * The named structural sacrifice this change makes, stated as a fact, never a
- * recommendation (e.g. "Couples `app` to `infra`; 4 in-repo modules already
- * depend on this anchor."). A sibling fact to `question`; it never tells the
- * human what to choose.
- */
-tradeoff: string
-}
-/**
- * A note for decisions collapsed below the cap.
- */
-export interface TruncationNote {
-/**
- * How many decisions were collapsed below the cap.
- */
-collapsed: number
-/**
- * Human-readable collapse reason.
- */
-reason: string
-}
 /**
  * The separable `decision-surface` envelope: the single call that puts taste-
  * decisions in front of a human, callable WITHOUT the full pipeline (the
@@ -9954,6 +10008,37 @@ agent_schema: AgentSchema
  */
 injection_note: string
 }
+/**
+ * The full `fallow audit --brief --format json` envelope. Carries the
+ * informational verdict, the triage and graph-facts orientation stages, plus
+ * the reused "subtract" section (the same dead-code / duplication / complexity
+ * payload `fallow audit --format json` emits).
+ */
+export interface ReviewBriefOutput {
+schema_version: ReviewBriefSchemaVersion
+/**
+ * Fallow CLI version that produced this output.
+ */
+version: string
+/**
+ * Command discriminator singleton: always `"audit-brief"`.
+ */
+command: string
+triage: DiffTriage
+graph_facts: GraphFacts
+partition: PartitionFacts
+impact_closure: ImpactClosureFacts
+focus: FocusMap
+deltas: ReviewDeltas
+/**
+ * 6.F, headline: reviewer-private weakening signals (tests
+ * removed/skipped, thresholds lowered, suppressions added, security steps
+ * removed). Advisory, never gates, never auto-posted.
+ */
+weakening: WeakeningSignal[]
+routing: RoutingFacts
+decisions: DecisionSurface
+}
 /**
  * The review direction artifact: the order to review in, the coherent units,
  * and per-unit concern lens + out-of-diff + expert. A minimal projection of the
@@ -10301,6 +10386,29 @@ export interface CodeClimateLines {
  */
 begin: number
 }
+/**
+ * Structured JSON error emitted on stdout when `--format json` is active and a
+ * command fails. It carries no `kind` discriminator: it is distinguished from
+ * the kind-tagged success envelopes by the required `error: true` field, and is
+ * a document-root branch alongside `FallowOutput` and `CodeClimateOutput` in
+ * `docs/output-schema.json`. Agents that pass `--format json` and observe a
+ * non-zero exit code parse this shape from stdout.
+ */
+export interface ErrorOutput {
+/**
+ * Always `true`. The discriminator that separates an error document from a
+ * success envelope (which instead carries a `kind`).
+ */
+error: boolean
+/**
+ * Human-readable error message.
+ */
+message: string
+/**
+ * The process exit code the CLI returns alongside this document.
+ */
+exit_code: number
+}
 
 /**
  * Inner complexity-violation payload, flattened into `HealthFinding`