post-change-refactor

Purpose: Local wrap-up gate required by execute-plan / /gsd-execute-phase (see .cursor/rules/gsd-coexistence.mdc). Structure-only: no new behavior.

Output: Refactored tree + ## REFACTOR COMPLETE, or an impact report + ## REFACTOR JIDOKA STOP. Do not commit — the caller commits after success (and pushes when closing a slice).

Scope is concept-bounded, not file-bounded. A candidate must be triggered by an issue introduced, exposed, or materially aggravated by the current change or highly related code. Such code represents the same concept, duplicates the same knowledge, or must change to leave it coherent. Dependency adjacency alone is neither required nor sufficient.

Find the smallest complete set of representations, callers, tests, fixtures, and configuration needed for coherence, including untouched code when needed. Every edit must serve that candidate; do not initiate nearby cleanup.

Discover scope:

git status
git diff
git diff --cached

Whitespace hygiene: scripts/check_diff_whitespace.sh (not raw git diff --check) — excludes generated API artifacts under packages/generated/donut-backend-api/** and open_api_docs.yaml.

Git does not use the Nix prefix. All other repo tooling does: CURSOR_DEV=true nix develop -c …

Plan justification (decision boundary): Keep code justified by the current change or the immediate next slice in the active plan (.planning/phases/*/, .planning/quick/*/). Anything justified only by a later slice, or by "we might need it later", is speculative — remove it. No plan → justification comes only from the current change. The immediate next slice may justify retaining code, but does not independently trigger unrelated refactoring.

Subsystem boundary: Backend production code, frontend production code, CLI, MCP server, and database schema are separate subsystems. Tests, E2E, fixtures, generated artifacts, and configuration following one production seam do not alone create a crossing. Existing behavior work spanning subsystems also does not trigger the gate; the refactoring itself must require coordinated production edits across boundaries.

Optional caller context (when spawned from execute-plan):

• Plan path and current slice text (for the immediate-next-slice justification boundary)

Invokers: execute-plan (fresh sub-agent before commit), bug-fixing, test-optimization, or on-demand developer request.

<preflight_gate name="discover_scope"> Run the git discovery commands above. If there is no uncommitted change, report empty scope and emit ## REFACTOR COMPLETE with no edits. </preflight_gate>

<preflight_gate name="map_concept_impact"> Before editing, perform a fast read-only pass over every check. For each candidate, record:

1. The triggering issue and its connection to the current change.
2. The minimum concept-bounded edit set needed for coherent completion.
3. The production subsystems that edit set would touch.

Use references as navigation, not automatic scope. Do not inventory general repository cleanup. </preflight_gate>

<preflight_gate name="cross_subsystem_jidoka"> If a candidate requires production refactoring in more than one subsystem, stop before editing unless the human explicitly authorized that named concept and those subsystems. Generic "clean up" or "refactor" requests do not qualify.

Return the <output> Jidoka report; do not enter the edit/test pass or substitute a partial refactoring. If discovered while editing, stop before the first cross-subsystem edit and leave no partial candidate: reverse only this agent's edits for that candidate, never pre-existing user changes. </preflight_gate>

After the gates, decide first: if map_concept_impact recorded no edit candidates (and the cross-subsystem gate did not stop), skip the edit steps and confirm_related_tests; report "none — already clean" and emit ## REFACTOR COMPLETE. Do not run related tests as a pre-triage gate.