# 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.
# ANTIGRAVITY GLOBAL RULES
Run a read-only, static-first analysis across a multi-repository software ecosystem and generate architecture maps, service catalogs, business-flow documentation, security findings, CI/CD insights, code metrics, and cross-repository traceability.
