MCP Tool Factory

```yaml name: Knowledge Layers - Immutability Hierarchy description: The distinction between eternal truth, execution state, and learned constraints for MCP Tool Factory ``` # Knowledge Layers ## The Immutability Hierarchy Knowledge in this project exists in **three distinct layers**, each with different **change velocity** and **authority source**. --- ## Layer 0: ETERNAL (Never Changes) **Change Velocity:** ZERO **Authority Source:** Mathematical truth, physical law, definitional constraint ### Sacred Primitive ``` MCP Tool Instance = Conversationally-negotiated capability with graduated permissions and hot-reload lifecycle ``` **Why Eternal:** - This is a **definition**, not an implementation - Conversational negotiation is the **only** way to establish intent alignment - Permission graduation is the **only** way to prevent catastrophic actions - Hot-reload is the **only** way to evolve tools without restart - No alternative exists that preserves the primitive's meaning **Cannot Be:** - Relaxed (tools without negotiation = blind execution) - Augmented (adding "features" breaks the primitive) - Conditionally applied (partial negotiation = security theater) **Violation:** Changing this destroys the system's identity --- ### Emergence Principle ``` Tool capabilities emerge from permission constraints, never from direct implementation ``` **Why Eternal:** - This is **how capabilities unlock**, not what they are - Direct capability implementation violates constraint-based design - Emergence is the **only** valid path to tool evolution **Examples:** - Read-only tools emerge when write permission blocked - Multi-repo orchestration emerges when repo isolation lifted - State continuity emerges when conversation memory persists **Violation:** Building tool features directly breaks the emergence model --- ### The Five Sacred Constraints ``` CONVERSATIONAL_ALIGNMENT PERMISSION_GRADUATION HOT_RELOAD_SAFETY STATE_CONTINUITY TOOL_CLASS_ISOLATION ``` **Why Eternal:** - These protect the primitive from entropy - Each constraint derives from protecting negotiation integrity, permission safety, reload stability, conversation continuity, and tool independence - Removing any constraint allows primitive corruption **Evolution Rule:** Constraints only **tighten**, never relax **Violation:** Relaxing constraints allows primitive decay --- ## Layer 1: STRUCTURAL (Changes Through Phase Shifts Only) **Change Velocity:** Discrete jumps at phase boundaries **Authority Source:** Infrastructure architecture, irreversible decisions ### Infrastructure Constraints (Current State) **Phase 1: Single Tool Class (M1-M3)** ``` - One tool type per MCP server - No conversation memory - Static permission model - No hot-reload - Manual restart required ``` **Phase 2: Tool Factory (M4-M7)** ``` - Multiple tool classes from same infrastructure - Conversation state persistence - Permission graduation (read-only → read-write) - Hot-reload enabled - Zero-restart evolution ``` **Why Structural:** - These are **architectural phase shifts**, not incremental changes - Single Tool → Factory is **irreversible** (one-way door) - Each phase unlocks different capability ceiling --- ## Layer 2: EXECUTION STATE (Highly Volatile) **Change Velocity:** Continuous updates during implementation **Authority Source:** Current reality, task completion ### Current Phase Location ```yaml current_phase: M1 completed_phases: [] tool_classes_deployed: 0 ``` **Why Volatile:** - This changes **every time a task completes** - No timeless truth here—only current position in execution map **Storage:** Linear, NOT documentation **Update Frequency:** Every task completion --- ## Layer 3: LEARNED CONSTRAINTS (Tightens Over Time) **Change Velocity:** Episodic tightening when violations detected **Authority Source:** Empirical evidence, production incidents ### Permission Graduation Thresholds **V1: Initial (Too Loose)** ```python auto_approve_read_only = True # Dangerous ``` **V2: First Tightening** ```python require_explicit_approval = ["read", "write", "execute"] # Rationale: Auto-approval caused unintended file access ``` --- ## Document Placement Rules ### 01-the-project.md (ETERNAL + STRUCTURAL) **Contains:** - Sacred primitive (MCP Tool Instance definition) - Emergence principle - Phase shifts (Single Tool → Factory) - Tool class hierarchy **Excludes:** - Current tool count - Active conversations - Permission grant history ### 02-the-discipline.md (ETERNAL + LEARNED) **Contains:** - Five sacred constraints - Witness protocol - Permission graduation rules - Hot-reload safety mechanisms **Excludes:** - Current violations - Active incidents ### 03-implementation-plan.md (STRUCTURAL) **Contains:** - Task definitions - Witness outcomes - Code patterns - Migration steps **Excludes:** - Task completion status - Current phase location --- ## The Separation Principle **Immutable knowledge** (eternal, structural) lives in **documentation**. **Volatile knowledge** (execution state) lives in **operational systems** (Linear, observability). **Learned knowledge** (tightening constraints) lives in **versioned documentation** with justification. **Mixing these layers corrupts the truth.**