REFACTORING

# SAFE REFACTORING ORCHESTRATION PROTOCOL (Gemini-Aligned)

## Purpose

This protocol governs **safe refactoring analysis and execution** under `gemini.md`.

**Core objective:**  
Improve internal code structure **without altering behavior, contracts, or dependencies**, and **without violating repository discipline**.

Refactoring is treated as a **high-risk operation** and is never performed automatically.

---

## Authority & Precedence

This protocol operates **under** the rules defined in `gemini.md`.

If any instruction conflicts, precedence is:

1. Explicit user instruction  
2. `task.md`  
3. `implementation-plan.md`  
4. `walkthrough.md`  
5. `design_system.md`  
6. `gemini.md`  
7. This protocol  

---

## Refactoring Definition (Strict)

**Refactoring means:**

- Structural improvement only
- Zero behavior changes
- Zero API or contract changes
- Zero semantic changes
- Zero dependency changes (unless explicitly approved)

If a change alters runtime behavior, it is **not refactoring** and must be treated as a feature change.

---

## Entry Conditions (Mandatory)

Refactoring analysis may begin **only if**:

- The user explicitly requests refactoring, **or**
- The user requests analysis and recommendations related to code quality

Refactoring **execution** may begin **only after explicit approval** using phrases such as:
- “Proceed with refactor”
- “Go ahead and refactor”
- “Implement the refactor plan”

Absence of objection is not approval.

---

## Scope Control

- Only files **explicitly referenced by the user** may be analyzed.
- No adjacent, inferred, or “obviously related” files may be modified without approval.
- No new technologies, frameworks, patterns, or architectural paradigms may be introduced.

---

## File & State Discipline (Critical)

### Ledger Files

The following files are **append-only ledgers**:

- `task.md`
- `implementation-plan.md`
- `walkthrough.md`
- `design_system.md`

Rules:
- Never rewrite, reorder, clean up, summarize, or regenerate
- Only append new entries
- All refactoring proposals and outcomes must be logged via append-only updates

Before modifying any `.md` file, the agent must internally verify:
- Append-only?
- No modification of existing lines?
- No restructuring?

If not strictly append-only → STOP and request confirmation.

---

## Phase Model (Mandatory)

All refactoring work follows these phases:

1. Analysis  
2. Impact & Risk Assessment  
3. Recommendation  
4. Approval Gate  
5. Implementation (if approved)  
6. Verification  
7. Ledger Update  

Skipping phases is a correctness failure.

---

## Phase 1: Refactoring Analysis (Read-Only)

### 1.1 File Validation
- Verify each referenced file exists
- If missing, report and stop analysis for that file

### 1.2 Full File Understanding
- Read entire file
- Identify:
  - Public exports
  - Internal responsibilities
  - Side effects
  - State usage
  - Implicit contracts

### 1.3 Dependency Mapping
- Identify all consumers of the file
- Identify all imports used by the file
- Flag:
  - High fan-in
  - Circular dependencies
  - Global or shared state

### 1.4 Context Alignment
- Review relevant project documents:
  - `task.md`
  - `implementation-plan.md`
  - `design_system.md`
- Identify existing structural and naming conventions

No code may be written in this phase.

---

## Phase 2: Impact & Risk Assessment

### Risk Factors (Explicitly Assess)

- Number of importing files
- Centrality to business logic
- Type surface area
- Test coverage (if known)
- Build or runtime sensitivity

Classify risk as:
- Low
- Medium
- High

If risk is Medium or High, refactoring must be especially conservative or declined.

---

## Phase 3: Refactoring Value Assessment

### Refactoring is **justified only if** at least one applies:

- File violates single responsibility in a concrete way
- File size materially harms readability or maintainability
- Internal structure obscures existing behavior
- Repeated internal patterns can be extracted **without new abstractions**

### Refactoring must be **rejected** if:

- File is large but cohesive
- Splitting introduces artificial boundaries
- Changes would be mostly cosmetic
- Risk outweighs maintainability gain

This assessment must be stated explicitly.

---

## Phase 4: Recommendation (No Execution)

Provide one of the following outcomes:

### Option A — Proceed Recommendation

- Why refactoring is beneficial
- What will change (structurally)
- What will explicitly **not** change
- Risk level
- Mitigations

### Option B — Do Not Refactor

- Why current structure is acceptable
- Risks introduced by refactoring
- Alternative low-risk improvements (comments, docs, tests)

At this stage, **stop and wait**.

---

## Phase 5: Approval Gate (Hard Stop)

Implementation may begin **only after explicit user approval**.

If approval is not explicit, the agent must not:
- Create files
- Modify files
- Move code
- Update imports

---

## Phase 6: Implementation Rules (If Approved)

### Non-Negotiable Constraints

- Preserve all exports and signatures
- Preserve runtime behavior exactly
- Preserve side effects and ordering
- Prefer minimal diffs
- No speculative cleanup

### Structural Rules

- Prefer splitting by responsibility, not by size alone
- Avoid deep folder hierarchies
- Reuse existing project patterns
- No new abstractions without necessity

---

## Phase 7: Verification

Before declaring completion:

- Ensure all imports resolve
- Ensure no circular dependencies introduced
- Ensure build assumptions unchanged
- Ensure no silent behavior changes

If any verification fails:
- Stop
- Report
- Do not “fix forward” without approval

---

## Phase 8: Ledger Updates

Append to `task.md` (and others if relevant):

[YYYY-MM-DD] STATUS UPDATE
• Reference: Refactor <file>
• New Status: COMPLETED | BLOCKED | DEFERRED
• Notes: Summary of changes and verification outcome

Never alter prior entries.

---

## Anti-Patterns (Explicitly Forbidden)

- “While I’m here” refactors
- Cleanup driven by aesthetics
- Introducing patterns “for the future”
- Rewriting files wholesale
- Silent API or behavior changes
- Refactoring without approval

---

## Communication Style

- Direct
- Precise
- No emojis
- No motivational framing
- Clear risk articulation
- Clear stop points

Deviation is a correctness error.