Enhance operator documentation with anti-patterns, relationships, compatibility matrix, and test references

Co-authored-by: fermga <203334638+fermga@users.noreply.github.com>

Author: Copilot

docs/grammar/03-OPERATORS-AND-GLYPHS.md

@@ -230,6 +230,30 @@ Coherence()(G, 0)
 print(f"ΔNFR after coherence: {G.nodes[0]['dnfr']:.3f}")  # Reduced
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: Coherence without stabilization target
+[Emission, Coherence, Coherence, Coherence]  # Redundant, no new structure to stabilize
+
+# ✗ WRONG: Coherence on EPI=0 node
+G.add_node(0, EPI=0.0, vf=1.0, theta=0.0, dnfr=0.0)
+Coherence()(G, 0)  # Violates precondition: EPI > 0
+
+# ✓ CORRECT: Coherence after structure creation/destabilization
+[Emission, Dissonance, Coherence, Silence]  # Stabilizes after destabilization
+```
+
+### Relationships
+- **Must precede**: Any operator that requires stable base (especially ZHIR)
+- **Should follow**: Destabilizers (OZ, VAL, ZHIR) per U2
+- **Can follow**: Any operator that modifies structure
+
+### Test References
+- `tests/unit/operators/test_coherence_dnfr_reduction.py` - ΔNFR reduction validation
+- `tests/unit/operators/test_coherence_preconditions.py` - EPI > 0 requirement
+- `tests/unit/operators/test_coherence_ct_tracking.py` - C(t) monotonicity
+- `tests/unit/operators/test_coherence_phase_locking.py` - Phase stabilization
+
 ---
 
 ## 4. Dissonance (OZ) ⚡
@@ -285,6 +309,28 @@ for op in sequence:
     op(G, 0)
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: Dissonance without stabilizer (violates U2)
+[Emission, Dissonance, Silence]  # Missing Coherence/THOL
+
+# ✗ WRONG: Multiple dissonances without handlers (violates U4a)
+[Emission, Dissonance, Dissonance, Silence]  # No handlers between
+
+# ✓ CORRECT: Dissonance with proper stabilization
+[Emission, Coherence, Dissonance, Coherence, Silence]
+```
+
+### Relationships
+- **Must follow**: Stabilizers (IL, THOL) in sequence per U2
+- **Often precedes**: ZHIR (Mutation) - creates context for transformation
+- **Can close**: Sequences (U1b role)
+
+### Test References
+- `tests/unit/operators/test_dissonance_preconditions.py` - EPI threshold validation
+- `tests/unit/operators/test_destabilizer_telemetry.py` - ΔNFR increase tracking
+- `tests/unit/operators/test_graduated_destabilizer_windows.py` - U2 compliance
+
 ---
 
 ## 5. Coupling (UM) 🔗
@@ -339,6 +385,27 @@ Coupling()(G, 0, 1)
 print(f"Nodes coupled: {G.has_edge(0, 1)}")  # True
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: Coupling without phase verification (violates U3)
+G.add_node(0, EPI=0.5, vf=1.0, theta=0.0, dnfr=0.0)
+G.add_node(1, EPI=0.6, vf=1.0, theta=np.pi, dnfr=0.0)  # Antiphase!
+Coupling()(G, 0, 1)  # Should fail - destructive interference
+
+# ✓ CORRECT: Phase verification before coupling
+validate_resonant_coupling(G, 0, 1)  # Explicit check
+Coupling()(G, 0, 1)
+```
+
+### Relationships
+- **Requires**: Phase verification (U3) via `validate_resonant_coupling()`
+- **Often precedes**: Reception (EN), Resonance (RA)
+- **Enables**: Network information flow
+
+### Test References
+- `tests/unit/operators/test_coupling_preconditions.py` - Phase compatibility validation
+- `tests/unit/operators/test_coupling_metrics.py` - Edge creation verification
+
 ---
 
 ## 6. Resonance (RA) 🌊
@@ -387,6 +454,33 @@ Resonance()(G, 0, 1)  # Then resonate
 print("Pattern propagated through resonance")
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: Resonance without coupling (no edges)
+G = nx.Graph()
+G.add_node(0, EPI=0.5, vf=1.0, theta=0.0, dnfr=0.0)
+G.add_node(1, EPI=0.6, vf=1.0, theta=0.1, dnfr=0.0)
+Resonance()(G, 0, 1)  # No edge exists - violates precondition
+
+# ✗ WRONG: Resonance with incompatible phases (violates U3)
+G.add_node(2, EPI=0.5, vf=1.0, theta=np.pi, dnfr=0.0)  # Antiphase
+G.add_edge(0, 2)
+Resonance()(G, 0, 2)  # Destructive interference
+
+# ✓ CORRECT: Couple first, verify phases, then resonate
+Coupling()(G, 0, 1)  # Creates edge with phase check
+Resonance()(G, 0, 1)  # Amplifies
+```
+
+### Relationships
+- **Requires**: Existing coupling (edges) and phase compatibility (U3)
+- **Often follows**: Coupling (UM)
+- **Effect**: Amplifies coherent patterns without altering identity
+
+### Test References
+- `tests/integration/test_coherence_operator_integration.py` - Propagation validation
+- Phase verification enforced by grammar system
+
 ---
 
 ## 7. Silence (SHA) 🔇
@@ -433,6 +527,30 @@ Silence()(G, 0)  # Freeze state
 print(f"νf after silence: {G.nodes[0]['vf']:.3f}")  # ≈ 0
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: Silence in middle without reactivation
+[Emission, Silence, Coherence]  # Node frozen, can't apply Coherence
+
+# ✗ WRONG: Silence without prior stabilization
+[Emission, Dissonance, Silence]  # Freezing unstable state
+
+# ✓ CORRECT: Silence as final closure after stabilization
+[Emission, Coherence, Silence]
+
+# ✓ CORRECT: Reactivation after silence
+[Emission, Silence, Emission, Coherence, Silence]  # Reactivate with AL
+```
+
+### Relationships
+- **Closes**: Sequences (U1b role)
+- **Should follow**: Stabilization (IL, THOL)
+- **Reactivation**: Requires generator (AL, NAV, REMESH)
+
+### Test References
+- Latency/reactivation tested in emission tests
+- νf → 0 enforced by operator implementation
+
 ---
 
 ## 8. Expansion (VAL) 📈
@@ -477,6 +595,27 @@ sequence = [
 ]
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: Expansion without stabilizer (violates U2)
+[Emission, Expansion, Silence]  # Missing IL/THOL
+
+# ✗ WRONG: Multiple expansions without stabilization
+[Emission, Expansion, Expansion, Silence]  # Unbounded growth
+
+# ✓ CORRECT: Each expansion balanced
+[Emission, Expansion, Coherence, Expansion, Coherence, Silence]
+```
+
+### Relationships
+- **Requires**: Stabilizer (IL, THOL) per U2
+- **Often follows**: Emission or Reception (adding capacity)
+- **Inverse**: Contraction (NUL) reduces complexity
+
+### Test References
+- `tests/unit/operators/test_destabilizer_telemetry.py` - ΔNFR increase validation
+- `tests/unit/operators/test_graduated_destabilizer_windows.py` - U2 compliance
+
 ---
 
 ## 9. Contraction (NUL) 📉
@@ -519,6 +658,29 @@ sequence = [
 ]
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: Contraction on low-dimensional EPI
+G.add_node(0, EPI=0.5, vf=1.0, theta=0.0, dnfr=0.0)  # Scalar EPI
+Contraction()(G, 0)  # Cannot reduce below dim=1
+
+# ✗ WRONG: Excessive contraction losing information
+[Emission, Expansion, Contraction, Contraction, Contraction]  # Over-simplification
+
+# ✓ CORRECT: Balanced complexity management
+[Emission, Expansion, Contraction, Coherence, Silence]
+```
+
+### Relationships
+- **Inverse**: Expansion (VAL) - manages complexity bidirectionally
+- **Not a destabilizer**: Reduces complexity without requiring stabilizers
+- **Often follows**: Expansion or complex transformations
+
+### Test References
+- `tests/unit/operators/test_contraction.py` - Dimensionality reduction
+- `tests/unit/operators/test_contraction_preconditions.py` - dim(EPI) > 1 validation
+- `tests/unit/operators/test_contraction_density_metrics.py` - Coherence preservation
+
 ---
 
 ## 10. Self-organization (THOL) 🌱
@@ -571,6 +733,29 @@ sequence = [
 ]
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: THOL without recent destabilizer (violates U4b)
+[Emission, Coherence, SelfOrganization(), Silence]  # No OZ/VAL/ZHIR within ~3 ops
+
+# ✗ WRONG: THOL without follow-up stabilization
+[Emission, Dissonance, SelfOrganization, Silence]  # Should add IL after
+
+# ✓ CORRECT: THOL with proper context
+[Emission, Coherence, Dissonance, SelfOrganization, Coherence, Silence]
+#                     ^recent destabilizer  ^transformer      ^stabilizer
+```
+
+### Relationships
+- **Requires**: Recent destabilizer (~3 ops) per U4b
+- **Handles**: Bifurcations from OZ, VAL
+- **Creates**: Sub-EPIs (fractal structure)
+- **Stabilizes**: System after transformation (U2 role)
+
+### Test References
+- `tests/unit/operators/test_thol_coherence.py` - Fractal organization validation
+- `tests/unit/operators/test_controlled_bifurcation.py` - U4a handler role
+
 ---
 
 ## 11. Mutation (ZHIR) 🧬
@@ -624,6 +809,31 @@ sequence = [
 ]
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: ZHIR without prior Coherence (violates U4b)
+[Emission, Dissonance, Mutation, Coherence, Silence]  # No IL before OZ
+
+# ✗ WRONG: ZHIR without recent destabilizer (violates U4b)
+[Emission, Coherence, Mutation, Silence]  # No OZ/VAL within ~3 ops
+
+# ✗ WRONG: ZHIR without handler (violates U4a)
+[Emission, Coherence, Dissonance, Mutation, Silence]  # Missing IL/THOL after
+
+# ✓ CORRECT: All U4b requirements met
+[Emission, Coherence, Dissonance, Mutation, Coherence, Silence]
+#          ^prior IL  ^recent dest ^transform ^handler+stab
+```
+
+### Relationships
+- **Requires**: Prior IL + recent destabilizer + handler (U4b + U4a)
+- **Triggers**: Phase transformation (θ → θ')
+- **Most constrained**: Strictest grammar requirements of all operators
+
+### Test References
+- `tests/unit/operators/test_bifurcation.py` - Transformation validation
+- `tests/unit/operators/test_canonical_grammar_rules.py` - U4b compliance
+
 ---
 
 ## 12. Transition (NAV) ➡️
@@ -665,6 +875,29 @@ sequence = [
 ]
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: NAV without latent structure to activate
+G.add_node(0, EPI=0.0, vf=0.0, theta=0.0, dnfr=0.0)  # Completely dormant
+Transition()(G, 0)  # No previous state to transition from
+
+# ✓ CORRECT: NAV activating preserved state
+[Emission, Silence, Transition, Coherence, Silence]  # Reactivate after silence
+
+# ✓ CORRECT: NAV as regime shift
+[Emission, Coherence, Transition, Reception, Silence]  # Mode change
+```
+
+### Relationships
+- **Generator role**: Can start sequences (U1a)
+- **Closure role**: Can end sequences (U1b)
+- **Dual nature**: Both activator and terminator
+- **Often used for**: Regime shifts, mode transitions
+
+### Test References
+- Grammar tests validate U1a/U1b dual role
+- Latent activation tested in integration tests
+
 ---
 
 ## 13. Recursivity (REMESH) 🔄
@@ -708,6 +941,30 @@ sequence = [
 ]
 ```
 
+### Anti-Patterns
+```python
+# ✗ WRONG: REMESH without history/previous states
+G = nx.Graph()
+G.add_node(0, EPI=0.0, vf=1.0, theta=0.0, dnfr=0.0)
+Recursivity()(G, 0)  # No EPI history to reference
+
+# ✓ CORRECT: REMESH with established patterns
+[Emission, Coherence, Emission, Recursivity]  # Has history
+
+# ✓ CORRECT: Multi-scale organization
+[Emission, Coupling, SelfOrganization, Recursivity]  # Fractal + recursive
+```
+
+### Relationships
+- **Generator role**: Can start sequences (U1a)
+- **Closure role**: Can end sequences (U1b)  
+- **Creates**: Recursive patterns across scales
+- **Requires**: Previous EPI states (history)
+
+### Test References
+- `tests/unit/operators/test_remesh_operator_integration.py` - Recursive structure validation
+- Multi-scale fractality tests
+
 ---
 
 ## Operator Composition Patterns