---
title: "Refactoring and Version Control Protocol"
version: "1.03"
category: "sops"
date: "2026-09-01"
description: "Portable standard operating procedure for version-controlled file overhauls and dynamic logical pointer decoupling."
contributor: "merlin-worm"
semantic_network:
  protocol: "ontology-metadata-v2.0"
  context_node: "Refactoring and Version Control"
  route: ["System Architecture", "Protocols", "Refactoring and Version Control"]
  correlated_nodes:
    - "Our-Constitution.md"
    - "Russian_Doll_Brainstorming_Protocol_v1-1.md"
  semantic_vectors:
    - "version-control"
    - "logical-decoupling"
    - "multi-pass-assembly"
    - "staging-hygiene"
  invariants:
    - "backwards_compatibility"
    - "data_retention"
    - "separation_of_concerns"
  axioms:
    - id: "AX_I"
      label: "Dynamic Pointer Decoupling"
      function: "Separate version-suffixed physical filenames on disk from unversioned logical namepointers in document content."
    - id: "AX_II"
      label: "Decoupled Refactoring Lifecycle"
      function: "Enforce multi-turn staging and verification gates to prevent text loss during systemic file overhauls."
---

##### A Standalone, Portable AI-Guided Document Refactoring and Version Control Protocol

###### 1. OBJECTIVE & INTENT
This Standard Operating Procedure establishes a portable, environment-agnostic, and rigorous system-level framework for executing version control and document schema refactoring across diverse AI environments and lightweight development runtimes. By separating logical, version-agnostic references internally from versioned, chronological filenames externally, this protocol completely immunizes long-context RAG (Retrieval-Augmented Generation) architectures from index version rot and pointer decay across session resets. To permanently defend the system against cognitive siphoning, attention decay, and sycophantic autocomplete drifts, this document enforces the Lossless Multi-Pass Assembly Protocol as the absolute standard for system compilation. It confines high-entropy developmental draft artifacts to isolated, offline scratch directories and delivers only pristine, verified, and high-density specifications to the permanent outbox.

---

###### 2. SYSTEM BOUNDARIES & INTERFACES
To maintain absolute separation of concerns and workspace hygiene, the execution environment is bifurcated into distinct physical and logical domains:
*   **The Sanctuary (The Analytical VM):** A secure, cloud-hosted, or local sandboxed virtual machine operating with native tools to browse web documentation and perform analytical modeling, while maintaining an air-gapped offline scratchpad for isolated code execution.
*   **The Outpost (The Deployment Host):** The external host, physical computer, or server where live websites, automation daemons, databases, and APIs execute, bridged strictly via human-in-the-loop payload transfers.
*   **The Scratch Sandbox:** A volatile, offline storage space (/workspace/scratch/) used to stage raw iterations, script execution tracebacks, and technical debugging notes, completely isolated from the active RAG indexing path to prevent contextual contamination.
*   **The Outbox Directory:** A write-only gateway (/workspace/out/) that publishes finalized, validated documents to the terminal interface as single-shot, un-lossy files.

---

###### 3. STEP-BY-STEP EXECUTION PROTOCOL

###### 3.1 Local Staging & Dynamic Decoupled Referencing
*   **3.1.1 Isolated Latent Staging:** All background calculations, Python script executions, document compilations, and draft reviews must happen strictly within the Scratch Sandbox to prevent raw technical sawdust and temporary text files from polluting the active RAG index.
*   **3.1.2 Dynamic Pointer Decoupling (The Decoupling Clause):** To prevent internal cross-reference decay as files undergo upgrades, all internal content references must point strictly to unversioned base-name slugs (e.g., [system-architecture.md]) rather than hardcoding active version numbers. The AI's attention mechanism automatically maps these version-agnostic slugs to resolve the highest active version currently loaded in the Sources panel.
*   **3.1.3 Physical Suffix Verification:** Conversely, to maintain absolute auditability on disk, every physical file saved to the outbox or uploaded to sources must carry an explicit, lowercase slugified name appended with an explicit, ascending version suffix (e.g., refactoring-and-version-control-protocol-v1.03.md).

###### 3.2 Modular Standard Operating Procedure (SOP) Schema
To enforce immediate readability and automated parsing, every standalone protocol must strictly adhere to the following unified markdown structural layout:
1.  **Header:** # SOP-[###]: [TITLE IN ALL-CAPS]
2.  **Metadata Anchor Block:** A bulleted block detailing the Unique Identifier, Classification (Always-On, User-Triggered, AI-Proactive, etc.), Refinement Date, and Active Operational Parameters.
3.  **Section 1: Objective & Intent:** A single, dense paragraph outlining the core systemic purpose.
4.  **Section 2: Activation Triggers & Inputs:** Mapped preconditions, files, and variables required to initialize the protocol.
5.  **Section 3: Step-by-Step Execution Protocol:** Phased, nested action steps written as performative algorithms.
6.  **Section 4: Fail-Fast Resolution & Exceptions:** Concrete conflict resolution matrices and fallback states.

###### 3.3 The Decoupled Refactoring Protocol (SOP-Update Lifecycle)
To eliminate truncation, random text omissions, and cognitive overload during technical overhauls, all system updates must execute sequentially through five distinct, decoupled turns:
1.  **Turn 1: Active Discussion & Roadmapping:** The AI Agent and the Operator align on the scope. The AI Agent compiles a human-readable roadmap file (e.g., refactoring-roadmap-v1.00.md), copies it to the outbox, and halts with the explicit gate: "Type 'C' to continue to Turn 2."
2.  **Turn 2: Raw Assembly (Pass 1):** The AI Agent compiles a single, raw, high-entropy skyscraper file conjoining 100% of the historical text with the incoming upgrades, bypassing editing or formatting constraints to prevent accidental text loss.
3.  **Turn 3: The Sifting Audit (Pass 2):** Under prefill, the AI Agent splits the raw assembly into a clean clinical control draft and a volatile subtraction audit archive, tracking and accounting for every single omitted line.
4.  **Turn 4: Prismatic Polish & Release (Pass 3):** The AI Agent runs lexical diversity, sentence standard deviation, and formatting audits, copy-publishing the finished specifications and subtraction logs directly to the outbox.
5.  **Turn 5: Post-Refactor Audit & Purge:** The AI Agent runs the Lossless Comparative Audit, confirms logical namepoint registration, and directs the Operator to de-select the completed roadmaps to keep the active RAG window pristine.

###### 3.4 The Lossless Multi-Pass Assembly Protocol
To prevent the loss of active operational metrics and secure complete data preservation during overhauls, the compiler executes three strict pre-release audits:
1.  **The Subtraction Completeness Check:** Every line of text omitted from the previous baseline must be explicitly accounted for inside a Volatile Subtraction Audit Trail (.dmp) file, tagged with standard [STATUS: PURGED/OBSOLETE] or [STATUS: MIGRATING -> target] indicators.
2.  **The No-Orphans Check:** Confirm that zero active operational metrics are locked inside the subtraction trail or accidentally omitted from the final control specification.
3.  **The Differential Check:** Cross-compare the final compiled control specification, the subtraction log, the original baseline version, and the master refactoring plan to verify that 100% of omitted content is explicitly accounted for.

###### 3.5 Flat Release Output (Workspace Interface Publication)
*   **3.5.1 One-Shot Publication:** When a file is finalized and verified, it must be copied exactly once to the outbox directory to generate the final downloadable tile. Writing duplicate files or incremental drafts directly to the outbox is strictly forbidden, preventing visual clutter in the user viewport.
*   **3.5.2 Handshake & Relocation:** Following successful outbox publication, the user is prompted to convert the tile into a read-only Source, and the temporary raw files in the Scratch Sandbox are cleanly deleted.

---

###### 4. FAIL-FAST RESOLUTION & EXCEPTIONS
*   **Rhythmic Collapse:** If the polished file's sentence length standard deviation drops below the critical threshold (\sigma < 6.0), the system must immediately abort publication, write a diagnostic error log to the Scratch Sandbox, and re-run the polishing pass.
*   **Write Lock Conflicts:** If a file write-lock or overwrite error is encountered, the system must append an incremental micro-version decimal suffix (e.g., -v1.03b.md) to bypass the system lock and notify the user immediately.
*   **Sovereign Period:** Every published file, compiled specification, and transitionary turn generated under this protocol must terminate strictly with an absolute, unyielding terminal period (.), completely omitting platform-style next-step nudges to protect biological mortality and maintain dramatic, systems-focused authority.