Skip to content

Drift Lessons

NON-NORMATIVE.

Structured record of governance drift incidents detected in the morphism-systems monorepo. Each lesson captures a contradiction or gap, its root cause, resolution, and a training pair for the future morphism model.

Lessons Index

ID Date Category Invariant Summary
DL-001 2026-02-28 branch-naming I-2 GUIDELINES.md listed 9 types; validator accepts 13
DL-002 2026-02-28 branch-naming I-2 feature/thing listed as invalid; validator accepts feature/
DL-003 2026-02-28 branch-enforcement I-2 Shell validator missing feat/ prefix
DL-004 2026-02-28 branch-enforcement I-2 Shell validator whitelisted main; Python blocked it
DL-005 2026-02-28 branch-enforcement I-2 policy_check.py skipped validation on main
DL-006 2026-02-28 branch-enforcement I-5 Pre-push hook called validate_branch.py twice
DL-007 2026-02-28 break-glass I-2 ALLOW_MAIN_BRANCH documented but not implemented
DL-008 2026-02-28 documentation-cascade I-1 Branch type list inconsistent across 6+ files
DL-009 2026-03-07 secret-exposure I-5 Plaintext Pinecone API key in tracked Python script
DL-010 2026-03-07 path-hardcoding I-1 Hard-coded personal path in committed MCP config
DL-011 2026-03-07 enforcement-gap I-2 Pre-commit scanner missing patterns for 5+ services
DL-012 2026-03-07 numbering-system-drift I-1 Three competing tenet numbering systems (legacy 42, canonical 10, phantom 54)
DL-013 2026-03-08 review-process I-3 PR #72 merged with 23 unresolved automated review comments
DL-014 2026-03-08 test-quality I-5 Monad law tests structurally tautological due to tuple concat

Feedback Loop

Drift lessons feed into the governance self-healing cycle:

  1. Detection — Manual audit or automated drift detector finds contradiction
  2. Recording — Incident logged in .morphism/datasets/drift-lessons.jsonl with structured schema
  3. Resolution — Code and docs aligned; SSOT atoms re-extracted
  4. Training — Each lesson includes an instruction/response pair for model fine-tuning
  5. Prevention — Lessons inform new validation rules or SSOT atoms to catch the pattern automatically

This connects to the HealingLog concept in the Morphism framework: each drift detection and correction is a contraction mapping that reduces system entropy.

How to Add a Lesson

  1. Detect a governance contradiction or gap (code vs docs, validator vs validator, etc.)
  2. Append a JSON line to .morphism/datasets/drift-lessons.jsonl with this schema:
{
  "id": "DL-NNN",
  "date": "YYYY-MM-DD",
  "category": "branch-naming|branch-enforcement|break-glass|documentation-cascade|...",
  "invariant": "I-N",
  "summary": "One-line description of the drift",
  "root_cause": "Why the drift occurred",
  "detection": "manual audit|drift_detector.py|CI|...",
  "resolution": "What was done to fix it",
  "files_affected": ["file1", "file2"],
  "lesson": "Reusable insight for preventing recurrence",
  "training_pair": {
    "instruction": "Question that would surface this drift",
    "response": "Correct answer explaining the fix"
  }
}
  1. Update this table with the new entry
  2. Run python scripts/ssot_verify.py to ensure no new drift was introduced

Data Location

  • Structured data: .morphism/datasets/drift-lessons.jsonl
  • Training pairs: Extractable from the training_pair field of each entry
  • Governance pairs: .morphism/datasets/governance-pairs.jsonl (general governance Q&A)