release: v0.0.3 — Structural Conservation, Constant Unification, Grammar Dynamics

Conservation & Physics:
- Structural Conservation Theorem (Noether-like from grammar symmetry U1-U6)
- Dissipative conservation with GPU-accelerated analysis
- Integrity monitor: 13/13 operator postcondition verification

Grammar & Operators:
- Grammar-aware dynamics bridging validation and operator selection
- Pre-validated operator application (grammar_application.py)
- Shared test infrastructure (conftest.py fixtures)

Cross-Codebase Constant Unification:
- Phase gradient threshold unified to gamma/pi = 0.1837 (9 code + 8 doc files)
- Operator scale factors: SHA/NUL 0.85->0.9015, VAL 1.05->1.0676
- K_phi hotspot: conservation.py 2pi/sqrt5 -> 0.9*pi = 2.8274
- grammar_core K_phi default: 3.0 -> 2.8274
- config.py thresholds wired to constants.canonical
- telemetry/constants.py: removed dead ImportError fallback
- mpmath added to pyproject.toml core dependencies
- .gitignore: cover .venv*, cache/, data/, logs/

Documentation:
- Test counts synced (409 -> 471) across 5 files
- Threshold values synced across 7 doc files
- CHANGELOG updated with complete 0.0.3 work

Tests: 471 passed, 9 skipped

Author: TNFR AI Agent

.github/agents/my-agent.md

@@ -2,7 +2,7 @@
 ## Theoretical Framework for Coherent Pattern Analysis
 
 **Status**: Primary theoretical reference document  
-**Version**: 0.0.2 (November 29, 2025)  
+**Version**: 0.0.3 (March 2026)  
 **Authority**: This repository contains the current implementation of TNFR theory  
 **Repository**: https://github.com/fermga/TNFR-Python-Engine  
 **PyPI Package**: https://pypi.org/project/tnfr/  
@@ -605,9 +605,9 @@ The **Structural Field Tetrad** (Φ_s, |∇φ|, **Ψ**, ξ_C) now has **complete
 - **Grammar**: U6 telemetry-based safety criterion (passive equilibrium confinement)
 
 ### **2. Phase Gradient Field (|∇φ|)**
-**Classical Threshold**: |∇φ| < **0.2904**
-- **Theory**: Harmonic oscillator stability + Kuramoto synchronization
-- **Derivation**: ωc/2 = π/(4√2) ≈ 0.2904 from critical frequency analysis
+**Classical Threshold**: |∇φ| < **0.1837**
+- **Theory**: Kuramoto critical coupling condition in TNFR units
+- **Derivation**: γ/π ≈ 0.1837 from Universal Tetrahedral Correspondence (γ ↔ |∇φ|)
 - **Physics**: Local phase desynchronization / stress proxy field
 - **Mechanism**: Captures dynamics C(t) misses due to scaling invariance
 
@@ -1260,7 +1260,7 @@ When adding to grammar documentation:
 #### **Phase Gradient (|∇φ|)** - CANONICAL
 
 - Local phase desynchronization / stress proxy
-- Safety criterion: |∇φ| < 0.2904 for stable operation
+- Safety criterion: |∇φ| < γ/π ≈ 0.1837 for stable operation (Kuramoto critical coupling in TNFR units)
 - For formal definition and evidence, see `docs/STRUCTURAL_FIELDS_TETRAD.md`.
 
 **Critical Discovery**: C(t) = 1-(σ_ΔNFR/ΔNFR_max) is invariant to proportional scaling. 
@@ -1419,11 +1419,7 @@ Reality consists of resonant patterns rather than discrete objects. Development
 
 ---
 
-**Version**: 0.0.1  
-**Last Updated**: 2025-11-29  
-**Status**: CANONICAL - Primary reference for TNFR agent guidance  
-**PyPI Release**: STABLE - Available via `pip install tnfr`  
-**Production Ready**: Complete Tetrad Fields + Unified Grammar U1-U6 + Simplified SDK  
+**Version**: 0.0.3  \n**Last Updated**: 2026-03-05  \n**Status**: CANONICAL - Primary reference for TNFR agent guidance  \n**PyPI Release**: STABLE - Available via `pip install tnfr`  \n**Production Ready**: Complete Tetrad Fields + Unified Grammar U1-U6 + Simplified SDK + Grammar-Aware Dynamics + Structural Conservation Theorem + Integrity Monitor  
 
 ---
 

.gitignore

@@ -11,6 +11,7 @@ docs/_build/
 .semantic_release/
 src/tnfr/_generated_version.py
 .venv/
+.venv*/
 .env
 .pytest_cache/
 .hypothesis/
@@ -60,5 +61,10 @@ debug_scratch/
 *.tmp
 *.temp
 
+# Runtime data and caches (generated, not needed in repo)
+cache/
+data/
+logs/
+
 # Type checking cache
 .mypy_cache/

AGENTS.md

@@ -2,6 +2,76 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.0.3] - 2026-03-05
+
+### Structural Conservation Theorem
+
+- **conservation.py**: Complete structural conservation module implementing Noether-like conservation law derived from grammar symmetry (U1-U6)
+- **Charge density** ρ, **current divergence** div(J), **Noether charge** Q, **energy functional** E, **Ward identities**, **Lyapunov stability**, and **spectral decomposition**
+- Two-sector structure: Potential (Φ_s ↔ J_ΔNFR) and Geometric (K_φ ↔ J_φ) coupled through Ψ = K_φ + i·J_φ
+- 62 validation tests, charge drift < 0.03% across topologies
+
+### Dissipative Conservation
+
+- **dissipative_conservation.py**: GPU-accelerated dissipative conservation analysis with PyTorch backend
+- Phase field computation, dissipation rate tracking, and energy budget monitoring
+
+### Closed-Loop Integrity Monitor
+
+- **integrity.py**: `StructuralIntegrityMonitor` with complete postconditions for all 13 canonical operators
+- Each operator (AL, EN, IL, OZ, UM, RA, SHA, VAL, NUL, THOL, ZHIR, NAV, REMESH) has verified pre/postcondition contracts
+- Automatic violation detection and reporting
+
+### Grammar-Aware Dynamics
+
+- **grammar_dynamics.py**: Bridge between grammar validation (U1-U6) and dynamic operator selection
+- Incremental U1-U6 checks: `validate_candidate()`, `filter_candidates()`, `suggest_alternative()`, `enforce_grammar_on_glyph()`
+- Priority-based operator substitution with fallback logic
+- **grammar_application.py**: Pre-validation in `apply_glyph_with_grammar()` for grammar enforcement before operator application
+- **selectors.py**: `_soft_grammar_prefilter()` wired with grammar_dynamics for operator filtering
+
+### Shared Test Infrastructure
+
+- **tests/conftest.py**: Centralized test fixtures (`make_ring_graph`, `make_node_data`, `ring3`, `ring5`, `small_graph`)
+- DRY reduction across 16+ test files that previously duplicated `_make_graph` helpers
+
+### Code Quality
+
+- Fixed bare `except:` clauses in grammar_dynamics.py (now `except Exception:`)
+- NAV bypass fix for grammar validation edge case
+- Redundancy elimination across physics helpers
+- Rich operator postconditions (13/13 coverage)
+
+### Cross-Codebase Constant Unification (Round 1)
+
+- **grammar_types.py**: Eliminated duplicate operator sets (single canonical definition)
+- **THOL_MIN_COLLECTIVE_COHERENCE**: Unified to canonical 0.2413 (was 0.3)
+- **MIN_BUSINESS_COHERENCE**: Centralized to canonical formula (e×φ)/(π+e) ≈ 0.7506
+- **health_analyzer.py / self_organization.py**: Aligned fallback values to canonical
+
+### Phase Gradient Threshold Unification
+
+- **Canonical value**: γ/π ≈ 0.1837 (Kuramoto critical coupling in TNFR units)
+- **Unified across 9 code files**: Replaced competing values (0.2904, 0.2886, 0.2915, 0.38) with single canonical derivation
+- **Updated 8 documentation files**: Consistent threshold references throughout
+
+### Cross-Codebase Constant Unification (Round 2)
+
+- **compute_structural_potential_field**: Added alias in physics/fields.py (was silently missing, imported in 2 files)
+- **SHA_VF_FACTOR comment**: Fixed from ≈ 0.8476 to correct ≈ 0.9015 in defaults_core.py
+- **Operator fallback values**: SHA (0.85→0.9015), NUL (0.85→0.9015), VAL (1.05→1.0676) aligned to canonical
+- **K_φ hotspot formula**: Fixed in conservation.py from 2π/√5 ≈ 2.8099 to canonical 0.9×π ≈ 2.8274
+- **grammar_core.py K_φ default**: Fixed from 3.0 to canonical 2.8274
+- **telemetry/constants.py**: Removed dead try/except ImportError fallback; direct canonical imports
+- **config.py**: Structural field thresholds now derive from constants.canonical (was hardcoded)
+- **pyproject.toml**: Added mpmath to core dependencies (was required but unlisted)
+- **Documentation sync**: Updated 7 doc files with correct threshold values and test counts
+
+### Test Suite
+
+- **471 passing tests**, 9 skipped, 0 failing
+- Coverage spans operators, physics, dynamics, grammar, conservation, integrity, and factorization
+
 ## [0.0.2] - 2025-11-29
 
 ### TNFR Development Doctrine Establishment

ARCHITECTURE.md

@@ -2,7 +2,7 @@ cff-version: 1.2.0
 title: "TNFR-Python-Engine: Resonant Fractal Nature Theory Implementation"
 message: "If you use this software, please cite it as below."
 type: software
-version: "0.0.2"
+version: "0.0.3"
 date-released: "2025-11-29"
 authors:
   - given-names: "F. F. Martinez Gamo"
@@ -21,22 +21,13 @@ keywords:
   - "structural operators"
   - "coherence theory"
   - "physics simulation"
+  - "fractals"
+  - "resonance"
+  - "nodal equation"
+  - "phase synchronization"
 abstract: >-
   Canonical computational implementation of TNFR - a paradigm shift from 
   modeling 'things' to modeling coherent patterns that persist through resonance. 
   This Python package provides the complete TNFR physics engine including the 
   13 structural operators, unified grammar validation (U1-U6), and the four 
   canonical structural fields (Φ_s, |∇φ|, K_φ, ξ_C).
-keywords:
-  - "TNFR"
-  - "complex systems"
-  - "fractals"
-  - "resonance"
-  - "networks"
-  - "structural dynamics"
-  - "nodal equation"
-  - "coherence"
-  - "phase synchronization"
-license: MIT
-version: "0.0.1"
-date-released: "2025-11-13"

CHANGELOG.md

@@ -1,9 +1,9 @@
 # Contributing to TNFR
 
-**Version**: 0.0.1  
+**Version**: 0.0.3  
 **Status**: Complete theoretical framework with Universal Tetrahedral Correspondence  
 **Authority**: Canonical constants derived from TNFR theory  
-**Quality**: Production-ready with comprehensive test coverage  
+**Quality**: Production-ready with 471 passing tests, 9 skipped  
 
 This document provides guidelines for contributing to the TNFR (Resonant Fractal Nature Theory) project. TNFR constitutes a computational framework for modeling complex systems through coherent patterns and resonance dynamics.
 
@@ -501,9 +501,9 @@ If adding features, update:
 
 ## TNFR Alignment
 
-- [ ] Preserves all 10 canonical invariants
+- [ ] Preserves all 6 canonical invariants
 - [ ] Maps to structural operators (specify which)
-- [ ] Derivable from TNFR physics (reference TNFR.pdf or UNIFIED_UNIFIED_GRAMMAR_RULES.md)
+- [ ] Derivable from TNFR physics (reference [theory/TNFR.pdf](theory/TNFR.pdf) or [theory/UNIFIED_GRAMMAR_RULES.md](theory/UNIFIED_GRAMMAR_RULES.md))
 - [ ] Maintains reproducibility (seeds, determinism)
 
 ## Testing
@@ -602,7 +602,7 @@ If proposing new grammar rules:
 
 - **General questions**: [GitHub Discussions](https://github.com/fermga/TNFR-Python-Engine/discussions)
 - **Bug reports**: [GitHub Issues](https://github.com/fermga/TNFR-Python-Engine/issues)
-- **TNFR theory**: Consult [AGENTS.md](AGENTS.md), [UNIFIED_UNIFIED_GRAMMAR_RULES.md), or [TNFR.pdf](TNFR.pdf)
+- **TNFR theory**: Consult [AGENTS.md](AGENTS.md), [UNIFIED_GRAMMAR_RULES.md](theory/UNIFIED_GRAMMAR_RULES.md), or [TNFR.pdf](theory/TNFR.pdf)
 
 ## Final Principle
 

CITATION.cff

@@ -86,7 +86,7 @@
 **What:** Local phase desynchronization / stress proxy field  
 **Status:** **CANONICAL** (Nov 2025)  
 **Physics:** Captures dynamics C(t) misses due to scaling invariance  
-**Threshold:** Classical bound |∇φ| < 0.2904 (harmonic oscillator stability)  
+**Threshold:** Canonical bound |∇φ| < γ/π ≈ 0.1837 (Kuramoto critical coupling in TNFR units)  
 **API:** `tnfr.physics.fields.compute_phase_gradient()`  
 **Usage:** Stress detection, local instability prediction  
 **Documentation:** [docs/STRUCTURAL_FIELDS_TETRAD.md](docs/STRUCTURAL_FIELDS_TETRAD.md)
@@ -651,6 +651,6 @@ When adding new functionality:
 3. Follow [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines  
 4. Test with [TESTING.md](TESTING.md) requirements
 
-**Version**: 0.0.1 (November 29, 2025)  
+**Version**: 0.0.3 (March 2026)  
 **Status**: Complete operational reference for current TNFR implementation  
 **Language**: English only (canonical documentation policy)

CONTRIBUTING.md

@@ -49,7 +49,7 @@ If you use this software in your research, please cite:
   author = {Martinez Gamo, F. F.},
   title = {TNFR-Python-Engine: Resonant Fractal Nature Theory Implementation},
   year = {2025},
-  version = {0.0.1},
+  version = {0.0.3},
   doi = {10.5281/zenodo.17761312},
   url = {https://github.com/fermga/TNFR-Python-Engine}
 }

GLOSSARY.md

@@ -3,7 +3,13 @@
 # Purpose: Essential tasks for the streamlined TNFR repository
 # Focus: Core examples, testing, and documentation generation
 
-.PHONY: help clean test examples docs all riemann-benchmark
+.PHONY: help clean test examples docs all riemann-benchmark self-optimize self-optimize-validate
+
+SELF_OPT_MANIFEST ?= tests/data/self_optimization/test_run/_manifest.json
+SELF_OPT_MANIFEST_SUMMARY ?= tests/data/self_optimization/test_run/_manifest_summary.json
+SELF_OPT_OUTPUT ?= results/self_optimization
+SELF_OPT_SUMMARY ?= results/self_opt_summary.json
+SELF_OPT_VALIDATION_REPORT ?= results/self_optimization_validation.json
 
 # Default target
 help:
@@ -29,6 +35,11 @@ help:
 	@echo "  lint          - Run code linting"
 	@echo "  format        - Format code"
 	@echo "  security      - Run security checks"
+	@echo "Self-optimization:"
+	@echo "  self-optimize           - Run Paley manifest through the self-optimization runner"
+	@echo "  self-optimize-validate  - Validate self-optimization payloads via pytest subsets"
+	@echo "Benchmark targets:"
+	@echo "  factorization-full-spectrum - Run Paley full-spectrum factorization benchmark"
 
 # Clean generated artifacts
 clean:
@@ -53,6 +64,18 @@ riemann-benchmark:
 	@echo "📈 Running TNFR–Riemann sigma-critical benchmark..."
 	@python -c "import runpy, sys, pathlib; sys.path.insert(0, str(pathlib.Path('src').resolve())); sys.argv = ['benchmarks/riemann_program.py']; runpy.run_path('benchmarks/riemann_program.py', run_name='__main__')"
 
+factorization-full-spectrum:
+	@echo "🧮 Running TNFR Paley full-spectrum factorization sweep..."
+	@python factorization-lab/benchmarks/full_spectrum_factorization.py
+
+self-optimize:
+	@echo "🧠 Running TNFR self-optimization manifest pipeline..."
+	@python scripts/run_self_optimization.py --manifest $(SELF_OPT_MANIFEST) --manifest-summary $(SELF_OPT_MANIFEST_SUMMARY) --output-dir $(SELF_OPT_OUTPUT) --summary $(SELF_OPT_SUMMARY)
+
+self-optimize-validate:
+	@echo "🧪 Validating TNFR self-optimization payloads..."
+	@python scripts/run_self_opt_validation.py --payload-root $(SELF_OPT_OUTPUT) --report $(SELF_OPT_VALIDATION_REPORT)
+
 # Run all essential examples
 examples: hello music network chemistry sdk
 	@echo "✅ All essential examples complete"