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.