fallow 2.92.1 → 2.94.0

package/skills/fallow/references/node-bindings.md

@@ -0,0 +1,21 @@
+# Node.js Bindings
+
+When embedding fallow inside a Node.js process (editor extensions, long-running servers, custom tooling), prefer the NAPI bindings over spawning the CLI. Same analysis engine, same JSON envelopes, no subprocess or JSON parsing overhead.
+
+```bash
+npm install @fallow-cli/fallow-node
+```
+
+```ts
+import { detectDeadCode, detectDuplication, computeHealth } from '@fallow-cli/fallow-node';
+
+const deadCode = await detectDeadCode({ root: process.cwd(), explain: true });
+const dupes = await detectDuplication({ root: process.cwd(), mode: 'mild', minTokens: 30 });
+const health = await computeHealth({ root: process.cwd(), score: true, ownershipEmails: 'handle' });
+```
+
+Six async functions: `detectDeadCode`, `detectCircularDependencies`, `detectBoundaryViolations`, `detectDuplication`, `computeComplexity`, `computeHealth`. Each returns the same JSON envelope the CLI emits for `--format json`. Rejected promises throw a `FallowNodeError` with `message`, `exitCode`, and optional `code`, `help`, `context` fields that mirror the CLI's structured error surface.
+
+Enum-like fields take lowercase CLI-style literals (`"mild"`, `"cyclomatic"`, `"handle"`, `"low"`). Write-path commands (`fix`, `init`, `hooks install`, `hooks uninstall`, `license activate`, `coverage setup`) are not exposed; use the CLI for those.
+
+See <https://docs.fallow.tools/integrations/node-bindings> for the full field reference.

package/skills/fallow/references/patterns.md

@@ -723,7 +723,7 @@ Use this when Claude Code is allowed to run Git commands in a repository that al
 The pattern is a local agent gate, not a Git hook. Claude Code intercepts its own `Bash` tool calls before execution. When Claude tries `git commit` or `git push`, the hook runs:
 
 ```bash
-fallow audit --format json --quiet --explain
+fallow audit --format json --quiet --explain --gate-marker agent
 ```
 
 Behavior:
@@ -777,14 +777,14 @@ Prefer `fallow hooks install --target agent` to install this file. The script is
 Behavior you can rely on:
 - Runs only when the intercepted command matches `git commit` or `git push`; otherwise exits 0.
 - Resolves `fallow` from PATH first, then `npx --no-install fallow` as a fallback. Skips with a stderr notice if neither is available or if `jq` is missing.
-- Enforces a version floor via `FALLOW_GATE_MIN_VERSION` (default `2.46.0`). Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
-- Runs `fallow audit --format json --quiet --explain` and, on verdict=`fail`, writes the full JSON envelope to stderr preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable.
+- Enforces a version floor via `FALLOW_GATE_MIN_VERSION` (default `2.85.0`). Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
+- Runs `fallow audit --format json --quiet --explain --gate-marker agent` and, on verdict=`fail`, writes the full JSON envelope to stderr preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable. The gate marker lets local Impact record blocked-then-cleared agent gate events when Impact is enabled.
 - On runtime error (`{"error": true, ...}`) or unexpected non-zero exit, fails open with a one-line stderr notice; warn verdicts pass through silently.
 
 Codex fallback (add to repo root `AGENTS.md`):
 
 ```md
-Before any `git commit` or `git push`, run `fallow audit --format json --quiet --explain`. If the verdict is `fail`, fix the reported findings before retrying. Treat JSON runtime errors like `{ "error": true, ... }` as non-blocking.
+Before any `git commit` or `git push`, run `fallow audit --format json --quiet --explain --gate-marker agent`. If the verdict is `fail`, fix the reported findings before retrying. Treat JSON runtime errors like `{ "error": true, ... }` as non-blocking.
 ```
 
 Keep `fallow audit` in CI alongside this local gate. The hook only runs for Claude Code, not for human pushes or other agents, so it is a reinforcement layer rather than a replacement for server-side enforcement.

package/types/output-contract.d.ts

@@ -732,6 +732,11 @@ _meta?: (Meta | null)
 dead_code?: (CheckOutput | null)
 duplication?: (DupesReportPayload | null)
 complexity?: (HealthReport | null)
+/**
+ * Read-only follow-up commands computed from this run's findings. See
+ * [`CheckOutput::next_steps`] for the contract.
+ */
+next_steps?: NextStep[]
 }
 /**
  * Per-category summary counts for the audit result.
@@ -1031,6 +1036,15 @@ baseline?: (BaselineMatch | null)
 regression?: (RegressionResult | null)
 _meta?: (Meta | null)
 workspace_diagnostics?: WorkspaceDiagnostic[]
+/**
+ * Read-only follow-up commands computed from this run's findings, emitted
+ * at the JSON root so an agent acting on the output is pointed at fallow's
+ * adjacent verification capabilities (trace, complexity breakdown, audit,
+ * workspace scoping). Each command is runnable as-is and never mutating;
+ * see [`NextStep`] for both contracts. Omitted when empty or when
+ * `FALLOW_SUGGESTIONS=off`; does NOT contribute to `total_issues`.
+ */
+next_steps?: NextStep[]
 }
 /**
  * Entry-point detection summary embedded in `CheckOutput` and the combined
@@ -2446,6 +2460,53 @@ exceeded: boolean
  */
 reason?: (string | null)
 }
+/**
+ * A read-only follow-up command fallow surfaces from the current findings,
+ * emitted as the top-level `next_steps` array on each command's JSON envelope.
+ *
+ * `next_steps` exists to point agents and humans sideways to fallow's adjacent
+ * verification capabilities (trace, complexity breakdown, audit, workspace
+ * scoping) that telemetry shows agents rarely discover, because they act on the
+ * output in front of them rather than on reference docs.
+ *
+ * ## Two hard contracts
+ *
+ * 1. **Read-only.** A `next_step` NEVER suggests `fallow fix` or any mutating
+ *    command. Fallow surfaces evidence and verification paths; deciding and
+ *    applying the remediation is the agent's job.
+ * 2. **Runnable, placeholder-free.** `command` is always runnable as-is. It
+ *    never contains an angle-bracket placeholder (`<...>`); finding-derived
+ *    values are filled in from a real, deterministically-selected finding, and
+ *    any environment- or user-specific value that cannot be made concrete lives
+ *    in `reason` instead. An agent can copy `command` and run it without edits.
+ *
+ * Both contracts are enforced by unit tests in
+ * `crates/cli/src/report/suggestions.rs`.
+ *
+ * Note: a SEPARATE, unrelated `next_steps` field exists on the
+ * `coverage setup` envelope (`CoverageSetupOutput.next_steps`) as a plain
+ * `Vec<String>` of human onboarding steps. Consumers that read multiple
+ * envelope kinds must route on the envelope's `kind` before interpreting a
+ * `next_steps` field: on analysis envelopes it is `Vec<NextStep>` objects, on
+ * `coverage setup` it is `Vec<String>`.
+ */
+export interface NextStep {
+/**
+ * Stable kebab-case key for machine dispatch and de-duplication
+ * (for example `"trace-unused-export"`). Identity is stable across runs;
+ * the `command` and `reason` strings may vary with the findings.
+ */
+id: string
+/**
+ * A runnable, read-only command string. Placeholder-free by contract.
+ */
+command: string
+/**
+ * One short phrase explaining why this helps. Carries any value that
+ * cannot be made concrete in `command`.
+ */
+reason: string
+}
 /**
  * Wire-shape payload for `fallow dupes --format json` (the body that
  * flattens into [`crate::output_envelope::DupesOutput`] and is also
@@ -4623,6 +4684,11 @@ grouped_by?: (GroupByMode | null)
 groups?: (HealthGroup[] | null)
 _meta?: (Meta | null)
 workspace_diagnostics?: WorkspaceDiagnostic[]
+/**
+ * Read-only follow-up commands computed from this run's findings. See
+ * [`CheckOutput::next_steps`] for the contract.
+ */
+next_steps?: NextStep[]
 }
 /**
  * A health report scoped to a single group.
@@ -4766,6 +4832,11 @@ _meta?: (Meta | null)
  * a separate top-level field.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
+/**
+ * Read-only follow-up commands computed from this run's findings. See
+ * [`CheckOutput::next_steps`] for the contract.
+ */
+next_steps?: NextStep[]
 }
 /**
  * A single grouped duplication bucket. Per-group `stats` are dedup-aware and
@@ -4880,6 +4951,11 @@ grouped_by: GroupByMode
 total_issues: number
 groups: CheckGroupedEntry[]
 _meta?: (Meta | null)
+/**
+ * Read-only follow-up commands computed from the full (ungrouped) findings.
+ * See [`CheckOutput::next_steps`] for the contract.
+ */
+next_steps?: NextStep[]
 }
 /**
  * Single resolver bucket inside `CheckGroupedOutput`. Carries the group's
@@ -5129,6 +5205,18 @@ recent_resolved: ResolutionEvent[]
  * "resolution tracking starts from your next run" instead of a bare zero.
  */
 attribution_active: boolean
+/**
+ * Whether the local agent onboarding prompt has been explicitly declined.
+ * Stored under `.fallow/` so agents can avoid cross-session nags.
+ */
+onboarding_declined: boolean
+/**
+ * Whether the user ever made an explicit enable/disable decision for
+ * Impact tracking. `enabled: false` with `explicit_decision: false` means
+ * "never asked"; with `true` it means "asked and declined". Agents use
+ * this to offer the impact opt-in exactly once per project.
+ */
+explicit_decision: boolean
 }
 /**
  * Per-category issue counts captured at a recorded run.
@@ -5866,6 +5954,11 @@ _meta?: (CombinedMeta | null)
 check?: (CheckOutput | null)
 dupes?: (DupesReportPayload | null)
 health?: (HealthReport | null)
+/**
+ * Read-only follow-up commands aggregated across the combined run's
+ * findings. See [`CheckOutput::next_steps`] for the contract.
+ */
+next_steps?: NextStep[]
 }
 export interface CombinedMeta {
 check?: (Meta | null)