Skip to main content

Lowercase Migration Disaster Audit

Date: 2026-02-13 Author: Claude (Opus 4.6) Status: RESOLVED - All recoverable files restored Severity: Critical (data loss affecting 589 files)

Executive Summary​

The "Complete lowercase-kebab-case migration" commit (7daa77d6) deleted 822 important files from the repository but only created 78 new lowercase replacements. This left 589 files truly missing (no lowercase version exists on disk). The root cause is macOS case-insensitive filesystem (APFS) where ADR-067-time-controlled-licensing.md and adr-067-time-controlled-licensing.md resolve to the same file, causing git mv operations to silently delete content.

Recovery: 497 files were successfully restored from git history with zero failures.

Incident Details​

Commit Information​

  • Commit: 7daa77d6
  • Message: refactor(AM): Complete lowercase-kebab-case migration
  • Date: ~January 2026
  • Scope: Renamed files to lowercase-kebab-case across the entire repository

Root Cause: macOS Case-Insensitive Filesystem​

On macOS APFS (the default filesystem), file paths are case-insensitive but case-preserving. This means:

ADR-067-time-controlled-licensing.md  ← same file on disk
adr-067-time-controlled-licensing.md  ← same file on disk

When the migration script attempted:

git mv ADR-067-time-controlled-licensing.md adr-067-time-controlled-licensing.md

Git saw this as a rename (delete old + create new), but the filesystem saw it as a no-op (same file). The result was that Git recorded the deletion of the uppercase name, but the "new" lowercase file was already the same inode. When subsequent operations or resets occurred, the file was lost.

Scope of Loss​

CategoryFiles DeletedLowercase ReplacementsTruly Missing
coditect-core-standards/32230
internal/architecture/adrs/872364
docs/ (various)~200~50~150
internal/ (non-ADR)~300~3~297
config/, tools/, scripts/~200~0~48
Total822~78~589

Critical Files Lost​

Standards (30 files):

  • CODITECT-STANDARD-TRACK-NOMENCLATURE.md — Referenced in CLAUDE.md
  • CODITECT-STANDARD-ADR.md — ADR authoring standard
  • CODITECT-STANDARD-SDD.md — Software Design Document standard
  • CODITECT-STANDARD-TDD.md — Technical Design Document standard
  • CODITECT-STANDARD-DOCUMENTATION.md — Documentation standard
  • CODITECT-STANDARD-FACTUAL-GROUNDING.md — Factual grounding standard
  • CODITECT-STANDARD-CICD.md — CI/CD standard
  • CODITECT-STANDARD-UI-UX.md — UI/UX standard
  • All 8 HOW-TO guides for creating agents, commands, hooks, scripts, workflows

ADRs (64 files):

  • ADR-001 through ADR-017 (core architecture series)
  • ADR-067 — Time-Controlled Licensing (847 lines, comprehensive licensing architecture)
  • ADR-CX-*, ADR-CXQ-* — Context extraction/query series
  • ADR-LMS-* — Learning Management System series
  • ADR-100 through ADR-120 — Modern architecture decisions
  • Cloud platform ADRs (ADR-009 through ADR-017)

Recovery Process​

Phase 1: Discovery (ADR-067)​

  • User noticed ADR-067 was referenced in the onboarding script but didn't exist
  • git log --all --oneline --grep="ADR-067" found creation commit ebbc64a4 and deletion in 7daa77d6
  • Recovered: git show "7daa77d6^:internal/architecture/adrs/ADR-067-time-controlled-licensing.md"

Phase 2: Standards Recovery (30 files)​

  • git show 7daa77d6 --diff-filter=D --name-only | grep coditect-core-standards
  • Cross-referenced with disk: 30 of 32 truly missing
  • Batch recovery using git show "7daa77d6^:<path>"

Phase 3: ADR Recovery (64 files)​

  • Same methodology for internal/architecture/adrs/
  • 64 of 87 deleted ADRs had no replacement on disk
  • All recovered from parent commit

Phase 4: Full Batch Recovery (497 total)​

  • Comprehensive sweep of ALL 822 deleted files
  • Case-insensitive dedup against existing disk files
  • 497 files confirmed missing and successfully restored
  • 0 failures during recovery

Recovery Command Pattern​

git show "7daa77d6^:<original-path>" > "<restore-path>"

Prevention Recommendations​

1. Never Run Bulk Rename on macOS Without Two-Step​

# WRONG: Direct rename on case-insensitive FS
git mv FILE.md file.md  # Silently fails

# RIGHT: Two-step via temp name
git mv FILE.md FILE.md.tmp
git mv FILE.md.tmp file.md

2. Verify Rename Results​

After any bulk rename operation:

# Count files before and after
git diff --stat HEAD~1 | tail -1
# Should show "N files changed" with equal insertions/deletions

3. Use Linux for Case-Sensitive Operations​

Run case-sensitive file operations in a Linux container or VM where the filesystem is case-sensitive, then commit from there.

4. Pre-Migration Backup​

Before any bulk file operation:

git tag pre-migration-backup

5. Post-Migration Verification Script​

# Verify all deleted files have lowercase replacements
git show <commit> --diff-filter=D --name-only | while read f; do
    lower=$(echo "$f" | tr 'A-Z' 'a-z')
    [ ! -f "$lower" ] && echo "MISSING: $f"
done
  • ADR-100: CODITECT Master Index System (also affected by nomenclature corruption)
  • ADR-182: File Integrity Registry (post-incident protection)
  • Memory note: MEMORY.md → "File Operations Safety (Lesson Learned 2026-01-30)"
  • Migration safety agent: agents/migration-safety-specialist.md

Appendix: File Categories Recovered​

Standards (30 files)​

coditect-core-standards/AGENTIC-COMMUNICATION-STANDARD.md
coditect-core-standards/CLAUDE-MD-STANDARD.md
coditect-core-standards/CODITECT-STANDARD-ADR.md
coditect-core-standards/CODITECT-STANDARD-AGENT-SKILLS-FRAMEWORK.md
coditect-core-standards/CODITECT-STANDARD-CICD.md
coditect-core-standards/CODITECT-STANDARD-DESIGN-TOKENS.md
coditect-core-standards/CODITECT-STANDARD-DOCUMENTATION.md
coditect-core-standards/CODITECT-STANDARD-FACTUAL-GROUNDING.md
coditect-core-standards/CODITECT-STANDARD-PRODUCTION-FOLDERS-BACKEND.md
coditect-core-standards/CODITECT-STANDARD-PRODUCTION-FOLDERS-UNIVERSAL.md
coditect-core-standards/CODITECT-STANDARD-SDD.md
coditect-core-standards/CODITECT-STANDARD-SUBMODULE-SETUP.md
coditect-core-standards/CODITECT-STANDARD-TASK-ID-PROTOCOL.md
coditect-core-standards/CODITECT-STANDARD-TDD.md
coditect-core-standards/CODITECT-STANDARD-TRACK-NOMENCLATURE.md
coditect-core-standards/CODITECT-STANDARD-UI-UX.md
coditect-core-standards/CODITECT-STANDARD-USE-CASE.md
coditect-core-standards/CODITECT-STANDARD-WORK-ITEMS.md
coditect-core-standards/FRONTMATTER-STANDARD.md
coditect-core-standards/GAP-ANALYSIS.md
coditect-core-standards/HOW-TO-CREATE-NEW-AGENT.md
coditect-core-standards/HOW-TO-CREATE-NEW-COMMAND.md
coditect-core-standards/HOW-TO-CREATE-NEW-HOOK.md
coditect-core-standards/HOW-TO-CREATE-NEW-SCRIPT.md
coditect-core-standards/HOW-TO-CREATE-NEW-WORKFLOW.md
coditect-core-standards/INDEX.md
coditect-core-standards/PRODUCTION-READINESS-CHECKLIST.md
coditect-core-standards/QUALITY-ASSURANCE-STANDARD.md
coditect-core-standards/SKILL-QUALITY-STANDARD.md
coditect-core-standards/VERSIONING-SCHEME.md

Audit completed 2026-02-13 | Recovery: 497/497 files (100%) | Failures: 0