Module suggestions 

Command-level next_steps[] builder.

Computes a small list of read-only, runnable follow-up commands from a run’s findings, surfaced at the JSON root (and as a one-line human Next: hint). The purpose is 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, both enforced by the tests in this module and by the next_step constructor’s debug assertions:

1. Read-only. A step NEVER suggests fallow fix or any mutating command.
2. Runnable, placeholder-free. Every command runs as-is; it never contains an angle-bracket placeholder. Finding-derived values come from a real, deterministically-selected finding; values that cannot be made concrete (a coverage path) are dropped from v1 rather than shipped as a placeholder, and an unresolvable git ref omits its step entirely.

Functions

build_audit_next_steps

Next-steps for fallow audit. No audit-changed (audit IS the changed scope) and no scope-workspaces (audit already gates the change). The check tuple carries the changed-file analysis results plus the project root so the trace anchor is made root-relative the same way every other surface does it (in-memory finding paths are absolute; the wire form is relative).

build_combined_next_steps

Aggregated next-steps for bare fallow (combined). Candidates are pushed in priority order, then capped. trace-unused-export leads because it is the highest-value verification path; scope-workspaces is boosted above the trace-clone / complexity tier so big-repo runs that trigger everything still surface the rare monorepo-scoping capability instead of always dropping it under the cap. audit-changed is last (broadly applicable, least specific).

build_dead_code_next_steps

Next-steps for standalone fallow dead-code.

build_dupes_next_steps

Next-steps for standalone fallow dupes.

build_health_next_steps

Next-steps for standalone fallow health.

suggestions_enabled

FALLOW_SUGGESTIONS=off (or 0/false/no/disabled) disables next-steps entirely. Default on. This is the documented escape hatch for CI consumers that snapshot-diff raw --format json output; it reaches the spawned-CLI and MCP surfaces without a CLI flag.

top_combined_next_step

The single highest-priority next-step for the human Next: line, computed from the same candidates and ordering as the combined JSON array so a human and an agent on the same run never see a contradictory top step.