verifying-refactors

name	verifying-refactors
description	Validates hard structural rules (no cycles, file/fn line caps, cognitive/cyclomatic complexity) and runs mutation testing on touched modules. Use when applying-refactors has completed all phases on the refactor branch.

Verifying Refactors

Overview

Verifying refactors IS proving the refactor made the codebase better by measurable rules, not vibes.

Run the same toolchain as analyzing-codebases, on the post-refactor state. Compare before/after. Every hard rule must hold or the refactor is not done. Mutation test touched modules to confirm characterization tests actually assert.

Core principle: A refactor that reduces complexity on paper but fails hard rules is a regression.

Routing

Pattern: Chain Handoff: user-confirmation Next: finalizing-refactors

Task Initialization (MANDATORY)

• Subject: [verifying-refactors] Task N: <action>

Tasks:

1. Run post-refactor toolchain
2. Check hard rules
3. Run mutation testing on touched modules
4. Produce verification report
5. Present to user

Task 1: Post-refactor toolchain

Rerun the same tools as analyzing-codebases on current (refactored) state. Save outputs to .rcc/aref-raw/{ts}-post-*.json (distinct from pre-refactor *-pre-*.json if you want to rename original outputs; else use new timestamp).

Task 2: Hard rules

Per references/hard-rules.md, check each rule. Any failure → STOP, do not proceed to mutation testing, report failure.

Rules:

• Cyclic deps count = 0
• No file > 300 lines (warning if between 250-300)
• No function > 50 lines
• Cognitive complexity max ≤ 15
• Cyclomatic complexity max ≤ 10
• Single-entry per module (barrel-at-boundary only)

Task 3: Mutation testing

Per references/mutation-testing.md. Run mutation tool ONLY on modules touched by the refactor (derived from git diff since branch point). Global mutation runs are out of scope.

Record mutation score (killed/total). Survivors >20% → flag weak-tests in report but do not block.

Task 4: Report

Write .rcc/{ts}-verification-report.md:

# Verification Report {ts}

## Hard Rules

| Rule | Before | After | Pass/Fail |
|------|--------|-------|-----------|
| Cyclic deps | 3 | 0 | PASS |
| Max file LOC | 820 | 298 | PASS |
| ...

## Mutation Testing

| Module | Mutants | Killed | Score | Flag |
|--------|---------|--------|-------|------|
| src/auth/token.ts | 48 | 41 | 85% | |
| src/auth/middleware.ts | 32 | 20 | 63% | weak-tests |

## Delta vs Pre-refactor

- Hotspot count: -3
- Duplication clusters: -2
- AGENTS.md gaps: unchanged (handled by finalizing)

## Decision

PASS / FAIL-HARD-RULES / PASS-WITH-WEAK-TESTS

Task 5: Present

Print report summary. Ask user:

• PASS → continue to finalizing-refactors
• FAIL → rollback last phase / replan failing target / abort
• WEAK-TESTS → continue / scaffold more tests / accept and continue

Red Flags - STOP

• Running mutation on whole codebase (scope is touched modules only)
• Skipping hard rules because "tests are green"
• Reporting PASS when any hard rule failed
• Using coverage % as a hard rule (research: gameable metric)

Common Rationalizations

Thought	Reality
"Coverage is 85%, skip mutation"	Coverage measures execution, not assertion. Mutation validates asserts.
"Warnings are fine, not FAIL"	Warning ≠ FAIL but IS recorded. User decides acceptance.
"Cognitive complexity 16 is close enough"	Hard rule is hard. Negotiate in plan, not in verify.

References

• references/hard-rules.md
• references/mutation-testing.md