# 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//first-principles.md └── domains//.md └── languages/.md └── examples/.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.