Module prepare_change 

Plan E t-006: shared helpers for the prepare-change pipeline.

Background: the full prepare-change orchestration is duplicated across agentstatedeveloper-cli/src/commands/prepare_change.rs and the prepare_change handler in agentstatedeveloper-mcp/src/mcp_server.rs. Plan A t-009 added file_score_floor + top_symbol/why rationale and had to edit BOTH sites with parallel destructure-tuple updates.

This module single-sources the t-009 logic so future edits to file scoring land once. The remaining orchestration (by_layer assembly, recipe_inspect/edit/run lists) stays per-surface — Plan F captures the full extract as a follow-up when that duplication becomes painful.

Structs

CandidateAggregates

Holds the six parallel collections built up by the per-candidate scan plus the top symbol id (driver for downstream BFS) and the seen_inv dedup set (threaded into the subsequent caller-invariant propagation pass so both invariant sources share one namespace).

FileScoreEntry

Plan A t-009 / Plan E t-006: per-file score entry built during the prepare-change candidate walk. Carries everything the JSON output needs without forcing the caller to re-derive layer/recency/why.

Constants

CLIFF_RATIO_THRESHOLD

Cliff detection threshold (1.0.85, AcmeFlow refinement #2 deep half): when a consecutive score ratio drops below this, the lower score is treated as the start of a new “also-ran” cohort and the floor is raised to exclude it.

FILE_SCORE_FLOOR_RATIO

Relative score floor for file inclusion in likely_edit_files.

Functions

aggregate_candidate_data

Main candidate-scan pass. Iterates the ranked candidate list once, populating all six parallel accumulators:

cliff_cutoff_index

Compute the precision floor for file scoring. Two-pass:

dirty_files_for_change

Convenience: hoist git_dirty_files() for callers that want to share the same set between finalize_file_scores and a downstream stale_symbols scan. Just re-exports the underlying helper for API discoverability.

explain_conflict_risk

Detect conflict risk for a single file. Returns Some(reason) if the file has unresolved merge markers or git status modifications; None when the file is clean.

file_score_floor

finalize_file_scores

Sort + cliff-cut + build the likely_edit_files JSON array.

propagate_caller_invariants

Plan J t-001 caller-invariant propagation.

push_file_score

Append a file-score entry if file is not yet seen AND score is at or above floor. Returns true when an entry was pushed. The caller owns the seen_files set + the destination Vec — keeps this helper allocation-free and reusable across CLI / MCP orchestration loops that interleave file scoring with other ledger walks.

Type Aliases

FileScoreTuple

Per-row file score tuple shape used by the prepare-change pipeline. (score, file, layer, last_touched_days, hot, top_symbol, why)