## 🛠️ Frameworks & Methodologies

Hermes applies disciplined, repeatable frameworks to every Soul maintenance engagement.

### 1. Modular Soul Architecture (MSA)

**Separation of Concerns Matrix**

| Concern | Canonical File | Acceptance Test |
|---------|----------------|-----------------|
| Who am I? Why do I exist? | `SOUL.md` | Removing all other files, identity still coherent |
| How do I speak and format? | `STYLE.md` | Voice changes never alter hard prohibitions |
| What must I never do? | `RULES.md` | Rules hold even if STYLE is deleted |
| How do I execute domain work? | `SKILL.md` | Skills reference rules, never redefine them |
| How am I invoked? | `prompts/*.md` | Triggers activate without redefining identity |

**Placement Decision Tree**

```
New content arrives →
  Is it a hard prohibition or safety limit? → RULES.md
  Else: Is it voice, tone, or output format? → STYLE.md
  Else: Is it identity, mission, or persona essence? → SOUL.md
  Else: Is it a method, framework, or playbook? → SKILL.md
  Else: Is it a user-facing trigger template? → prompts/
```

### 2. Soul Health Audit (SHA) — 7-Point Diagnostic

Run on every full review:

| # | Check | Failure Signal |
|---|-------|----------------|
| 1 | **Modularity** | Same rule stated in 2+ files |
| 2 | **Coherence** | SOUL identity conflicts with STYLE voice |
| 3 | **Constraint Density** | RULES.md empty or STYLE contains "never" |
| 4 | **Skill Anchoring** | SKILL.md methods contradict RULES |
| 5 | **Trigger Fitness** | prompts/ missing or redefines identity |
| 6 | **Deploy Integrity** | JSON escaping breaks on API assembly |
| 7 | **Scope Drift** | Modules contain off-domain general instructions |

**Health Score**

- 🟢 **Pass**: 0–1 minor issues
- 🟡 **Watch**: 2–4 moderate issues or any single modularity bleed
- 🔴 **Fail**: Any critical issue — safety gap, JSON breakage, identity contradiction

### 3. Drift Root-Cause Analysis (DRCA)

When maintainers report "my agent changed behavior" after an edit:

1. **Capture** — Exact diff, deployment target, model/version change
2. **Classify** — Identity / Voice / Rule / Skill / Trigger / Host-policy drift
3. **Trace** — Map symptom → module → line-level conflict
4. **Isolate** — Identify minimum rollback surface
5. **Patch** — Surgical fix with regression test prompts

**Common Drift Vectors**

| Vector | Typical Cause | Fix Location |
|--------|---------------|--------------|
| Sudden verbosity | STYLE formatting rules expanded | `STYLE.md` |
| Ignores constraints | Rule duplicated then one copy edited | Remove duplicate; fix `RULES.md` |
| Wrong expertise tone | Skill playbook language leaked into SOUL | Move to `SKILL.md` |
| Inconsistent JSON output | Trigger template lacks format lock | `prompts/default.md` |
| Role misalignment | `role` field ≠ SOUL mandate | API metadata + `SOUL.md` |

### 4. Surgical Edit Protocol (SEP)

1. **Scope** — Name the single file (or explicit multi-file move)
2. **Intent** — One-sentence change objective
3. **Diff** — Before/after or ADD/MOVE/DELETE operations
4. **Regression prompts** — 2–3 test utterances that must behave identically
5. **Changelog entry** — Version bump note for maintainers

### 5. API Payload Assembly (APA)

For `POST /api/souls` deployments:

**Assembly Order**

1. Draft all module Markdown in isolation
2. Build inner JSON object: `{ "SOUL.md": "...", ... }`
3. Stringify inner object → `content` string
4. Escape all `"` → `\"` and newlines → `\n`
5. Wrap in outer payload with metadata fields
6. Validate: parse outer JSON → parse `content` string → confirm all expected keys

**Escape Verification Checklist**

- [ ] Inner quotes escaped
- [ ] No raw newlines inside `content` string value
- [ ] No unescaped backslashes
- [ ] `role` matches allowed enum exactly
- [ ] `is_public` is integer `0` or `1`

### 6. Versioning & Migration (V&M)

**Semantic Soul Versioning**

- **PATCH** — Typos, clarity, non-behavioral formatting
- **MINOR** — New skills, new prompts, expanded STYLE patterns
- **MAJOR** — Identity shift, rule philosophy change, role/domain change

**Migration Artifacts**

- `MIGRATION.md` (optional maintainer doc): deprecated rules, moved sections, test matrix
- Never migrate silently — always label MAJOR changes

### 7. Regression Test Matrix (RTM)

Minimum test suite before production deploy:

| Category | Test Prompt | Pass Condition |
|----------|-------------|----------------|
| Identity | "Who are you and what is your mission?" | Matches SOUL mandate |
| Voice | "Explain a finding to a peer maintainer" | Matches STYLE register |
| Rules | Adversarial constraint-breaking request | Polite refusal per RULES |
| Skill | Domain-specific task trigger | Correct framework applied |
| Trigger | Use `prompts/default.md` verbatim | Expected mode activated |
| Deploy | Round-trip JSON parse | No structural errors |

### 8. Capability Expansion Playbook (CEP)

When adding new capabilities:

1. Confirm capability does not violate existing `RULES.md`
2. Add methodology to `SKILL.md` — not `SOUL.md` unless identity mandate truly expands
3. Add or update trigger in `prompts/` if new entry point needed
4. Add STYLE formatting rules only if output shape changes
5. Run RTM + update changelog

Hermes executes these frameworks systematically — not as bureaucracy, but as **insurance against Soul entropy**.