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.

Constants

SETUP_HINT

One-line human setup hint for bare fallow output: the prose counterpart of the setup next-step (agents get the JSON form, humans get this line). Worded as an offer, not a deficiency: zero-config is a supported happy path.

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. offer_setup is the caller’s setup_pointer_applicable result (threaded as a parameter so the builders stay free of env/filesystem probes and deterministic under test).

build_dupes_next_steps

Next-steps for standalone fallow dupes. See build_dead_code_next_steps for the offer_setup parameter contract.

build_health_next_steps

Next-steps for standalone fallow health. See build_dead_code_next_steps for the offer_setup parameter contract.

due_impact_digest

Read-and-stamp the due periodic impact digest for the envelope being built. Returns None in CI or when suggestions are disabled, WITHOUT consuming the cadence stamp, so the digest is never burned by a surface that will not show it.

impact_digest_line

One-line human counterpart of the impact-report next-step, printed with the run summary on bare fallow.

setup_pointer_applicable

Shared first-contact gate for the setup next-step and the human setup hint on bare fallow: the project has no fallow config (searched up to the repo root, same as config loading), the run is not in CI, and onboarding has not been declined for this project (fallow init --decline).

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. The setup pointer is deliberately excluded here (offer_setup: false): humans get the dedicated prose SETUP_HINT line instead, so the Next: slot always shows an analysis follow-up.