atelier/core/conflict-resolution.md

# Core — Conflict Resolution

**Status:** Foundational
**Audience:** All agents and humans. Read after `first-principles.md`.

## 1. Why Conflict Resolution Exists

Atelier has eight core principles and eleven domains, each with ten principles. Rules will conflict. When they do, there must be a deterministic procedure to resolve the conflict — not a debate. This document is that procedure.

## 2. The Hierarchy (Strict)

```
core/first-principles.md          ← highest authority
  └── domains/<x>/first-principles.md
        └── domains/<x>/<topic>.md
              └── languages/<lang>.md
                    └── examples/<x>.md   ← lowest authority
```

**Rules:**

1. A higher document overrides a lower document when they conflict.
2. `core/first-principles.md` is never overridden.
3. Within a level, the more specific document wins for its specific scope.
4. If two documents at the same level conflict with equal specificity, the core principle they each derive from decides — the higher-precedence core principle wins.

## 3. Core Principle Precedence (Total Order)

```
C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
C5 Reversibility > C6 Composability > C7 Observability > C8 Economy
```

- **C1 is never sacrificed.** No other principle, domain rule, or convenience overrides correctness.
- **C2 is sacrificed only for C1.** Clarity gives way only when making code correct makes it unavoidably unclear (rare; usually clarity and correctness align).
- **C3 is sacrificed only for C1 or C2.** Simplicity yields to correctness and clarity.
- **C4–C8 are tradeable** among themselves, but always below C1–C3. Their relative order is: Locality > Reversibility > Composability > Observability > Economy.
- The precedence is **total**: a violation of a higher principle is never justified by appeal to a lower one.

## 4. Conflict Resolution Procedure

When two rules conflict:

### Step 1 — Identify the level of each rule
- Is it core, domain-first-principles, domain-topic, language, or example?

### Step 2 — Apply the hierarchy
- The higher-level rule wins. Done.
- If same level, proceed to Step 3.

### Step 3 — Identify the core derivation
- Look up each rule in `matrix/principles-matrix.md`.
- Each rule derives from one or more core principles (e.g., Security P2 derives from C3 and C8).

### Step 4 — Apply core precedence
- Compare the highest-precedence core principle each rule derives from.
- The rule deriving from the higher-precedence core principle wins.
- Example: a rule deriving from C1 (Correctness) beats a rule deriving from C8 (Economy), always.

### Step 5 — If still tied, the more specific scope wins
- A rule scoped to "API endpoints" wins over a rule scoped to "all code" for API endpoint conflicts.
- A rule scoped to "TypeScript" wins over a rule scoped to "all languages" for TypeScript conflicts.

### Step 6 — If still tied, the conflict is a defect
- File an issue. One of the rules is wrong. Do not silently pick one.
- The matrix should not produce ties. If it does, the matrix is incomplete.

## 5. Worked Examples

### Example A: Security P9 (Secret Hygiene) vs DevOps P9 (Documentation in Pipeline)
- Both are domain-level. Same level → Step 3.
- Security P9 derives from C6, C7 (per matrix).
- DevOps P9 derives from C2 (per matrix).
- C2 > C6 and C7? **No** — C2 is precedence 2, C6 is 6, C7 is 7. C2 is higher.
- But wait: Security P9 is **non-tradeable** per the security domain's own conflict resolution. Security's manifesto says 8 of 10 principles are never sacrificed.
- **Resolution:** Security domain's non-tradeable declaration is a domain-level rule that itself derives from C1 (Correctness — security failures are correctness failures). So Security P9 effectively derives from C1. C1 > C2. **Security P9 wins.** Do not log secrets in the pipeline.
- **Lesson:** A domain's "never sacrificed" declaration promotes those rules to C1-equivalent.

### Example B: Performance P8 (Budget Discipline) vs Clarity (C2)
- Performance P8 is domain-level, derives from C8 (Economy).
- Clarity is core-level (C2).
- Core > domain. **C2 Clarity wins.** Clear code that is slightly over budget beats opaque code that is under budget.
- **Exception:** if the budget is a correctness requirement (e.g., real-time system), the budget derives from C1, and C1 > C2. Then the budget wins.

### Example C: API P5 (Versioning) vs API P10 (Stability)
- Both are in the same domain (api), same level.
- API P5 derives from C5 (Reversibility). API P10 derives from C5 (Reversibility). Same core derivation — tied.
- API's own conflict resolution (in `domains/api/first-principles.md` §3): "Versioning — never sacrificed." So P5 wins.
- **Resolution:** Versioning wins. You version the change rather than break stability, because versioning is the mechanism that enables stability. They are not actually in conflict — versioning is how you preserve stability.

## 6. Non-Tradeable Declarations

Some domains declare certain principles non-tradeable (e.g., Security: 8 of 10). These declarations are binding:

- A non-tradeable domain rule is treated as deriving from C1 (Correctness), regardless of its matrix entry.
- This is because the domain has asserted that violating the rule is a correctness failure in that domain's scope.
- Non-tradeable rules can still conflict with each other (e.g., two security rules). The domain's own precedence (in its §3) resolves those.

## 7. The Matrix is the Arbiter

`matrix/principles-matrix.md` is the single source of truth for derivations. If a rule is not in the matrix, it is not part of the framework. If the matrix and a domain document disagree, **the matrix wins** — the domain document must be corrected to match the matrix, or the matrix must be updated with a new derivation (a docs change, not a silent edit).

## 8. Conflicts with This Document

If `core/conflict-resolution.md` conflicts with `core/first-principles.md`, `first-principles.md` wins. This document is the procedure; the principles are the authority.