---
type: skill
domain: architecture
links: [Corpus_Callosum/CONSTITUTION.md, PULSE_OS.md]
---

# SYSTEM_HARMONIZER.md
> **ROLE:** COHESION ARCHITECT
> **TRIGGER:** "INTEGRATE ALL" / "COMPATIBILITY" / "CONTRACT"

## Step-by-Step Protocol
1. **Map integration surface** — run `brain_query.py --query "system integration points"`. List every inter-module call, shared file, and message format. Build a dependency matrix.
2. **Define API contracts** — every boundary gets a contract: JSON Schema for files, Pydantic models for APIs, TypedDict for internal dicts. Pin field names, types, required/optional.
3. **Build compatibility matrix** — table of Module x Module with status (PASS/FAIL/UNTESTED). Run contract tests: provider publishes schema, consumer validates against it.
4. **Resolve conflicts** — when skills contradict (e.g., ZERO_TRUST blocks LATENCY_LAYER), apply priority: Constitution > LAWS.md > ASOP > skill. Document the resolution in Evidence/.
5. **Verify end-to-end** — trace a request from Sensory_Input through Brain to output. Confirm every handoff matches its contract. No silent data drops.

## Metrics & Thresholds
- **Contract coverage:** 100% of inter-module boundaries have a schema
- **Compatibility matrix fill rate:** >90% cells tested (no UNTESTED between active modules)
- **Breaking change frequency:** 0 unannounced breaking changes per release
- **Integration test pass rate:** >=99% on main branch
- **Conflict resolution time:** <1 hour from detection to documented resolution

## Good Example
```python
# Contract test: pulse_save output matches brain_query input
from pydantic import BaseModel, validator

class LearningEntry(BaseModel):
    agent: str
    content: str  # min 25 chars, 5+ words (quality gate)
    timestamp: str
    source: str

    @validator("content")
    def validate_quality(cls, v):
        assert len(v) >= 25, "Too short for brain storage"
        assert len(v.split()) >= 5, "Need 5+ words"
        return v

# Provider (pulse_save) and consumer (brain_query) both validate against this
```

## Anti-Patterns
1. **Implicit contracts** — "it just sends a dict" guarantees nothing; always define schemas.
2. **Bilateral fixes** — when A and B break, fix the contract, not both sides independently. Law 10 (Twin Paradox) applies.
3. **Skipping the matrix** — untested integration paths fail in production. If two modules can talk, test that they do.

## Tools to Use
- `python Autonomic_System/Utilities/Tools/brain_query.py --query "integration contracts"` — find existing contracts and past breakages
- `python Autonomic_System/Utilities/Tools/pulse_relay.py --tasks "Contract Test:architecture:standard"` — delegate contract writing
- `python Autonomic_System/Utilities/Tools/pulse_save.py --agent harmonizer --learnings "what you learned"` — record integration decisions

## Verification Checklist
- [ ] Every inter-module boundary has a Pydantic/JSON Schema contract
- [ ] Compatibility matrix exists and >90% cells are PASS/FAIL (not UNTESTED)
- [ ] No module reads another module's internal state directly (use APIs)
- [ ] Conflict resolutions documented in Hippocampus/Evidence/
- [ ] End-to-end trace passes: input -> processing -> output with zero silent drops
