Chapter 11 – Automated Refactoring Under Guards

The candidate improved one structural property without regressing the required behavior or metric floor. Nothing has merged, and the floor has not moved.

Automated refactoring is governable when the workflow may propose a behavior-preserving structural change but cannot redefine behavior, weaken measurement, lower the protected floor, or admit itself.

Fix the Measurement Before Mutation

The activated refactor Mission pins the base revision and the material controls needed to compare baseline and candidate. Its bindings identify:

• the measurement implementation and protocol used for both baseline and candidate;
• the current protected minimum, or Ratchet floor;
• the dependency closure whose behavior could be affected.

The same implementation and protocol, both outside candidate authority, must observe the baseline and candidate. Candidate-controlled package scripts, test configuration, benchmark settings, or thresholds cannot redefine what “unchanged” means.

The record must identify what was measured and how, and preserve the source revision, protocol, tools, environment, raw observations, comparison rule, and floor revision.

Preflight verifies only that the already-authorized Mission identity and its bound protocol, base, affected closure, baseline, and floor revision remain present, intact, and executable. It may not repeat policy review, remeasure the baseline, or select, replace, change, or rebind a dependency. A missing, altered, or unusable dependency ends the run as blocked only when the result names the external repair or decision needed for a new linked run; otherwise it ends failed. In either case, the Run Record is sealed. The workflow never treats uncertainty as a pass.

The normal starting point is a green base. A policy may permit a precisely enumerated known-failure set, but the candidate must introduce no new or changed failure. “The branch was already red” is not a waiver.

Declare the Equivalence Boundary

“No behavior change” means no change to the observations that adopted intent declares stable. Depending on the system, those observations may include return values, errors, persisted state, external calls, event order, idempotency, timing, performance, logging, or telemetry.

Internal representation remains unconstrained unless another Map makes it observable. A changed public schema, exception contract, event sequence, or data effect is a behavior migration and belongs in a different Mission.

Guard Sufficiency

No test suite is universally comprehensive. Evidence must match the behavior boundary, mutation scope, and consequence:

When guards are weak, strengthen them in a separate Mission first. Adopt and protect the new contract or check before activating the refactor. The same candidate cannot author the only oracle that approves its change.

Mutation testing may help determine whether a check detects small semantic changes. When used, a fixed mutation protocol should serve as eligibility evidence for a refactor class, not as a universal per-candidate ritual. A surviving mutant supports a guard-strengthening proposal; it does not widen the current Mission.

Produce a Refactor Within the Boundary

A refactor changes structure while preserving behavior declared by the Map. Suitable transformations include:

• remove one unused private symbol;
• rename one private symbol with a language-aware tool;
• extract or inline one function without changing its contract;
• simplify one expression under an explicit equivalence check;
• apply one approved formatter or codemod to an allowlisted region.

The Mission must also state why the change should exist: remove a named finding, reduce a declared complexity measure, or complete a specific structural transformation. Non-regression alone does not justify churn.

Dependency upgrades, security patches, migrations, public-interface changes, and architectural changes are not refactors for governance purposes. They may use the same workflow architecture, but they need different authority, checks, approvals, and recovery.

The candidate runs inside Chapter 10’s complete effect boundary. An ordinary refactor has no authority over protected checks, floor state, CI, credentials, deployment, databases, production configuration, or admission.

Validate Under Protected Acceptance Rules

The protected boundary applies to acceptance authority, not to where every check is authored or invoked. The workflow may create, run, and record checks under a declared protocol, but the candidate cannot rewrite their decisive meaning. The Mission’s bound validation plan answers five questions:

When recorded with provenance, candidate-supplied tests and results are evidence. By themselves, they neither independently corroborate the candidate nor replace the protected acceptance basis. A declared protocol may validate new tests as Chapter 3 describes. A candidate that edits its floor, required test harness, required configuration, or any required check outside authorized effects fails validation even when its own commands report success.

Affected checks follow dependency closure, not only changed paths. Shared contracts and transitive consumers may need validation even when the diff is local.

Noisy Measurements

A noisy required metric has three check results: pass, fail, or inconclusive. Its bound validation plan fixes the sampling protocol, aggregation rule, tolerance, retry budget, and inconclusive result. For performance-like observations, that protocol also fixes the warmup and environment class.

An inconclusive result may permit another declared sample batch for the same candidate. Exhausting that budget without a decision ends as failed. It ends as blocked only when progress requires a named external repair or decision.

Protected Non-Regression

A Ratchet is a protected non-regression rule measured by one fixed protocol. It may require zero contract violations, non-increasing lint or type failures, a bounded performance distribution, or no undeclared API expansion.

Coverage and test count are weak universal floors because their denominators and semantics change. They are suitable only where the protocol and governed property make the comparison meaningful.

The floor, protocol, comparator, and advancement mechanism belong to the Protected Control Plane. The active refactor may read them but cannot modify them. Lowering a floor or changing its protocol requires a separate Governance Mission and separate Adoption before the change becomes authoritative.

A Ratchet lets an organization automate repeated improvement without letting automated work erase prior gains by lowering the baseline. Delegation can deepen only while a floor measured outside candidate authority continues to hold.

Admit and Advance the Floor Together

Following the lifecycle established in Chapters 5 and 10, the Mission Gate revalidates the candidate and its sealed Run Record against the current base, dependency closure, protocol, and floor.

For a ratcheted candidate, current-base Admission and floor advancement form one transactional transition. An Admission service whose authority is separate from the candidate producer revalidates the expected base, floor revision, candidate identity, and measured result, then commits the admitted state and new floor together. If either write fails, neither commits: the candidate remains unadmitted, the prior floor remains authoritative, and a retry requires current-state revalidation. If another Admission has already changed the base or floor, the transaction aborts and the candidate must be measured again. A conforming Ratchet therefore cannot expose a state in which Admission succeeded but its required floor advancement failed.

Before Admission, revert discards a candidate workspace after required evidence is preserved. After Admission, rollback is a new transition with authority and evidence appropriate to the affected surface. The two are not interchangeable.

For a multi-step extract-rename-move sequence, keep intermediate work inside one isolated candidate and compare the final result with the original base. If an intermediate state must become Terrain, produce it through a separately activated child Mission and submit its supported proposal to separate Admission.

This is the bounded form of structural self-modification. The workflow may propose an improvement, but its structural gain, behavior boundary, effects, non-regression floor, and eventual Admission remain checkable outside candidate authority.