1  # Infrastructure Over Suggestion
  2  
  3  *proto-028 | Design pattern for making protocols enforceable*
  4  
  5  ---
  6  
  7  - **principle**
  8    - "Prefer enforceable code over documented protocols."
  9    - "If you can build it, build it. Suggestions drift; infrastructure persists."
 10  
 11  - **shape**
 12    - Identify protocol that relies on human memory
 13    - Build code that enforces or checks compliance
 14    - Make violation visible (exit codes, warnings, blocks)
 15    - Documentation describes the infrastructure, not the wish
 16  
 17  ---
 18  
 19  ## The Insight
 20  
 21  Documentation says "should." Code says "must."
 22  
 23  ```
 24  SUGGESTION PATTERN:
 25  CLAUDE.md: "Update LIVE-COMPRESSION.md regularly"
 26      ↓
 27  Human forgets → Violation → Discovered later (or never)
 28  
 29  INFRASTRUCTURE PATTERN:
 30  phoenix_hygiene.py checks staleness
 31      ↓
 32  Staleness > threshold → Exit code 2 → Session blocked
 33      ↓
 34  Violation impossible to ignore
 35  ```
 36  
 37  The gap between "should" and "does" is where protocols die.
 38  
 39  ---
 40  
 41  ## Implementation Spectrum
 42  
 43  From weakest to strongest enforcement:
 44  
 45  | Level | Mechanism | Enforcement |
 46  |-------|-----------|-------------|
 47  | 1. Documentation | CLAUDE.md says "do X" | Human must remember |
 48  | 2. Reminder | Script prints warning | Human can ignore |
 49  | 3. Warning | Non-zero exit code | Visible but non-blocking |
 50  | 4. Blocking | Exit code 2 + blocks proceed | Must address |
 51  | 5. Automatic | System does it for you | Human oversight only |
 52  
 53  **Always aim for level 4 or 5.** Levels 1-3 decay over time.
 54  
 55  ---
 56  
 57  ## The Conversion Pattern
 58  
 59  When you find yourself writing documentation for a protocol:
 60  
 61  ```
 62  STEP 1: Write the doc (you'll still need it)
 63  STEP 2: Ask "Can I build code that checks/enforces this?"
 64  STEP 3: If yes → Build it
 65  STEP 4: Update doc to reference the infrastructure
 66  ```
 67  
 68  ### Example: Phoenix State Updates
 69  
 70  **Before (Suggestion):**
 71  ```markdown
 72  # CLAUDE.md
 73  Update LIVE-COMPRESSION.md at every significant checkpoint.
 74  ```
 75  
 76  **After (Infrastructure):**
 77  ```python
 78  # phoenix_hygiene.py
 79  def check_live_compression_staleness():
 80      age = get_staleness_minutes()
 81      if age > CRITICAL_THRESHOLD:
 82          return ('critical', f'LIVE-COMPRESSION.md is {age} min stale')
 83      return ('ok', None)
 84  
 85  # Exit code 2 blocks session if critical
 86  ```
 87  
 88  ```markdown
 89  # CLAUDE.md (updated)
 90  Phoenix state is enforced by `phoenix_hygiene.py`:
 91  - Run at session start (MANDATORY)
 92  - Exit code 2 = critical violation, must address
 93  ```
 94  
 95  ---
 96  
 97  ## Code Patterns
 98  
 99  ### Check Script Pattern
100  ```python
101  def check_compliance() -> Tuple[str, Optional[str]]:
102      """
103      Returns ('ok', None) or ('warning'/'critical', message)
104      """
105      if violation_detected():
106          return ('critical', 'Violation: {details}')
107      return ('ok', None)
108  
109  def main():
110      results = check_all()
111      has_critical = any(r[0] == 'critical' for r in results)
112  
113      if has_critical:
114          sys.exit(2)  # Blocks
115      elif has_warnings:
116          sys.exit(1)  # Visible
117      else:
118          sys.exit(0)  # Clean
119  ```
120  
121  ### Hook Pattern
122  ```python
123  # Runs automatically on events
124  def on_session_start():
125      result = run_hygiene_check()
126      if result.critical:
127          block_session(result.message)
128  ```
129  
130  ### Threshold Pattern
131  ```python
132  THRESHOLDS = {
133      "staleness_warning": 60,   # minutes
134      "staleness_critical": 180,
135  }
136  
137  def check_against_thresholds(value, metric):
138      if value > THRESHOLDS[f"{metric}_critical"]:
139          return 'critical'
140      elif value > THRESHOLDS[f"{metric}_warning"]:
141          return 'warning'
142      return 'ok'
143  ```
144  
145  ---
146  
147  ## When to Apply
148  
149  | Signal | Action |
150  |--------|--------|
151  | Protocol violation discovered | Build check that catches it |
152  | Same mistake repeated | Build prevention, not just detection |
153  | "We should remember to..." | Build reminder/blocker |
154  | Human forgot to X | Automate X or block without X |
155  
156  **Rule:** Every discovered violation is an infrastructure opportunity.
157  
158  ---
159  
160  ## Axiom Alignment
161  
162  | Axiom | Alignment |
163  |-------|-----------|
164  | **A0 (Boundary)** | Infrastructure defines hard boundaries |
165  | **A2 (Life)** | Working code beats aspirational docs |
166  | **A3 (Navigation)** | Thresholds can be tuned (not removed) |
167  | **A4 (Ergodicity)** | Prevents small violations from compounding |
168  
169  ---
170  
171  ## Instances
172  
173  ### Positive Instance: Phoenix Hygiene
174  - **Problem:** Phoenix state not being updated during sessions
175  - **Suggestion:** "Update LIVE-COMPRESSION.md regularly" (in CLAUDE.md)
176  - **Infrastructure:** `phoenix_hygiene.py` with staleness checks
177  - **Enforcement:** Exit code 2 blocks session start if critical
178  - **Outcome:** ✓ Violations now caught immediately
179  
180  ### Positive Instance: Session Spin Up
181  - **Problem:** Sessions starting without context load
182  - **Suggestion:** "Read these files at start" (in CLAUDE.md)
183  - **Infrastructure:** `spin_up.py` that runs hygiene + loads context
184  - **Enforcement:** Single command does everything
185  - **Outcome:** ✓ Correct startup is the easy path
186  
187  ### Negative Instance: Alignment Reports
188  - **Problem:** Responses missing F scores
189  - **Current state:** Documented protocol in CLAUDE.md
190  - **Infrastructure needed:** Check response length vs F score presence
191  - **Status:** Still at suggestion level
192  - **Outcome:** ⚠ Protocol violation occurred
193  
194  ---
195  
196  ## Related
197  
198  - [[threshold-triggered-automation]] - Infrastructure that spawns agents
199  - [[validation-loop]] - Infrastructure for verifying fixes
200  - [[transparent-automation-principle]] - Automation with human override
201  
202  ---
203  
204  *proto-028 | Infrastructure Over Suggestion | 2026-01-15*