Code Health Debt Map

Code Health Debt Map

This page tracks cross-cutting code debt found during migration work. It is not a substitute for feature implementation. Each cleanup must either remove proven dead code, promote duplicated infrastructure into a shared helper, or move source authority out of UI-era strings and numbers.

2026-07-08 Sweep

Commands:

uv run python /root/.codex/skills/vulture-dead-code/scripts/vulture_scan.py --paths src --confidence 100
uv run tach check --dependencies --interfaces --exact
uv run tach check-external
uv run ruff check src --statistics
rg -n "^def _validate_(required|optional)_text|^def _validate_text_tuple|^def _validate_non_negative|^def _validate_positive|^def _normalize_optional_text" backend-repo/src/sanmopia_modernization/domain -g "*.py"
rg -n "^def (required_text|optional_text|required_int|optional_int|required_datetime|optional_datetime|mapping_value|text_tuple|_required_text|_optional_text|_required_int|_optional_int|_required_datetime|_optional_datetime)\b" backend-repo/src/sanmopia_modernization/adapters backend-repo/src/sanmopia_modernization/interfaces -g "*.py"
rg -n "\bLEGACY\b|\blegacy\b|source status|source_status|STATUS_FL|TYPE_CD|DANBEE|danbee|head_office|inter_branch|manager_pay|WinTheRace|win_the_race|완주|영등포" backend-repo/src/sanmopia_modernization contract-repo/packages/ts-client/src -g "*.py" -g "*.ts"

Gate results:

• Vulture confidence 100: no findings.
• Tach dependencies/interfaces/external: pass.
• Ruff: pass before targeted cleanup.
• Domain infrastructure leakage: no production import violation; current hits are domain vocabulary/docstrings/tests mentioning Supabase Storage or broadcast topics.

Measured debt:

Category	Count	Risk	Cleanup direction
Domain-local text/amount validators	38	Medium	Promote common value guards per bounded context or shared domain kernel only when semantics match.
Adapter/interface row coercion helper defs	115	High	Replace file-local required_text, optional_int, datetime, mapping, and array readers with application.platform.supabase_row.
Legacy/source vocabulary hits in backend + TS contract	628	High	Split accepted source evidence from target ubiquitous language. Source refs may stay in tests/docs/evidence fields; domain names should not encode source board/status labels.

Immediate cleanup landed in this sweep:

• application.platform.supabase_row now owns shared required_bool, optional_mapping, and required_mapping_sequence.
• Admin caregiver payout projection adapters now use the shared row coercion helper instead of local wrappers.
• Colocated tests cover the newly promoted helper behavior.
• 2026-07-09 backend naming hardening retired the source-era settlement transition provenance path in favor of settlement_board_transition_provenance, including contract payloads and source-row marker fields. Imported source evidence remains explicit, but domain/application names no longer encode source-era status labels.

Debt Classes

flowchart TD
  Scan[Code-health scan] --> Gate{Hard gate?}
  Gate -->|Vulture/Tach/Ruff fail| FixGate[Fix before feature work]
  Gate -->|pass| Pattern[Pattern audit]
  Pattern --> RowHelpers[Adapter row coercion duplication]
  Pattern --> DomainGuards[Domain validator duplication]
  Pattern --> SourceTerms[Source-era vocabulary leakage]
  RowHelpers --> SharedSupabase[Promote to application.platform.supabase_row]
  DomainGuards --> BoundedKernel[Promote only when invariant semantics match]
  SourceTerms --> EvidenceOnly[Keep source terms only in evidence/docs/tests]
  SharedSupabase --> FocusedTests[Focused colocated tests]
  BoundedKernel --> FocusedTests
  EvidenceOnly --> Checklist[Source checklist or ADR if behavior changes]

Next Cleanup Queue

1. Replace duplicated row coercion helpers in the largest Supabase adapters: supabase_product_gift_redemption.py, supabase_settlement_continuation.py, supabase_caregiver_payout_acknowledgement.py, supabase_service_use_contract_evidence_snapshot_fact_reader.py, and supabase_reservation_collaboration.py.
2. Audit domain validator duplication by bounded context. Do not create a single global validation module unless names, error semantics, and invariants are truly shared.
3. Rename source-era target vocabulary where it is not evidence-only: danbee, head_office, inter_branch, manager_pay, and win_the_race must be reviewed against the ubiquitous language map before more settlement/reporting work lands.
4. Keep generated Supabase types regenerated from the stage CLI after migrations; do not hand-patch generated schema files.