friction_detection:
  rule: "Before 'fixing' any quirk, verify it is not an undocumented business rule"
  action: "Document in .loki/healing/friction-map.json"
  classification:
    business_rule: "Keep and document. Gate 10 blocks removal."
    true_bug: "Fix with characterization test proving the fix."
    unknown: "Keep until classified. NEVER remove unknown friction."

{
  "frictions": [
    {
      "id": "friction-001",
      "location": "src/billing/invoice.py:234",
      "behavior": "Sleep 2s before committing transaction",
      "classification": "business_rule|true_bug|unknown",
      "evidence": "Prevents race condition with external payment gateway callback",
      "discovered_by": "archaeology_scan",
      "timestamp": "2026-01-25T10:00:00Z",
      "safe_to_remove": false
    }
  ]
}

characterization_testing:
  feathers_recipe:
    1: "Use a piece of code in a test harness"
    2: "Write an assertion that you KNOW will fail"
    3: "Let the failure tell you what the actual behavior is"
    4: "Change the test so that it expects the behavior the code produces"
    5: "Repeat -- the test now documents the actual behavior"

  key_distinction: |
    Characterization tests capture WHAT THE CODE DOES.
    Unit tests verify WHAT THE CODE SHOULD DO.
    When these differ, the characterization test wins during healing --
    because users depend on actual behavior, not intended behavior.

  seemann_2025: |
    "A characterization test is a falsifiable experiment. The implied
    hypothesis is that the test will fail. If it does not fail, you've
    falsified the prediction." (Mark Seemann, Nov 2025)

strangler_fig:
  steps:
    1: "Identify system boundaries (not arbitrary c