TECH_DEBT.md — updated 2026-05-13

Maintained by: ClearPoint Nexus / Technical Debt Tracker skill Provenance key: chosen = deliberate shortcut with team sign-off | discovered = found during review, audit, or incident Status key: open in-progress closed

Register

TD-001 · Synchronous file I/O in report export pipeline

| Field | Value | |---|---| | Status | open | | Provenance | chosen | | Source | PR #214 — comment: "using sync fs calls for now, async refactor deferred to post-launch" | | Introduced | 2026-03-08 | | Effort to fix | M (3–5 days) | | Risk if ignored | High — blocks event loop under concurrent exports; already surfaced in load test at 40 req/s | | Score | 8 / 10 | | Deadline | None | | Notes | Workaround in place: export queue capped at 3 concurrent jobs via semaphore |

TD-002 · JWT secret loaded from environment without rotation support

| Field | Value | |---|---| | Status | open | | Provenance | discovered | | Source | Security review 2026-04-30 — finding SR-19 | | Introduced | Unknown (pre-dates this register) | | Effort to fix | S (1–2 days) | | Risk if ignored | Critical — no path to rotate secret without full redeploy and forced logout of all sessions | | Score | 9 / 10 | | Deadline | 2026-06-01 (SOC 2 Type II audit window opens) | | Notes | AWS Secrets Manager integration already approved in architecture decision ADR-07 |

TD-003 · Invitation email template hardcoded in application layer

| Field | Value | |---|---| | Status | open | | Provenance | chosen | | Source | TODO in mailer/invite.ts:88 — "move to template service once CMS is stood up" | | Introduced | 2026-02-19 | | Effort to fix | S (1 day) | | Risk if ignored | Low — copy changes require a deploy; no security or reliability impact | | Score | 3 / 10 | | Deadline | None | | Notes | CMS integration (EP-44) still not scheduled; re-evaluate at Q3 planning |

TD-004 · UserService.findAll() loads full user rows — no pagination

| Field | Value | |---|---| | Status | in-progress | | Provenance | discovered | | Source | Incident INC-2026-041 — 12 s query timeout in production with 48 k user rows | | Introduced | Unknown | | Effort to fix | M (2–4 days) | | Risk if ignored | High — will recur as dataset grows; already caused one P2 incident | | Score | 8 / 10 | | Deadline | None | | Notes | Cursor-based pagination branch open: PR #301, review in progress |

TD-005 · Mongoose 6.x — EOL November 2026

| Field | Value | |---|---| | Status | open | | Provenance | discovered | | Source | Dependency audit 2026-05-01; upstream EOL notice | | Introduced | 2024-11-10 (dependency version pinned) | | Effort to fix | L (1–2 weeks, includes schema migration testing) | | Risk if ignored | High — no security patches after EOL; breaking changes in Mongoose 8 require migration runway | | Score | 7 / 10 | | Deadline | 2026-09-01 (target upgrade before EOL; leaves 8-week buffer) | | Notes | Mongoose 7 → 8 changelog reviewed; discriminator API change affects EventLog model |

TD-006 · React class components in Settings module (deprecated pattern)

| Field | Value | |---|---| | Status | closed | | Provenance | chosen | | Source | TODO in settings/ProfilePanel.tsx:1 | | Introduced | 2025-08-14 | | Closed | 2026-05-09 via PR #298 | | Effort to fix | S | | Risk if ignored | Low | | Score | 2 / 10 | | Notes | Converted to functional components with hooks. Closed, not removed — preserved for history. |

Weekly Delta — week ending 2026-05-13

| | Count | Items | |---|---|---| | Added | 1 | TD-005 (Mongoose EOL — discovered in dependency audit) | | Closed | 1 | TD-006 (React class components — resolved in PR #298) | | Net | 0 | Register holds steady at 5 open items |

Trend note: Two of five open items (TD-001, TD-004) have scores ≥ 8 and no assigned owner. Recommend ownership assignment before next sprint planning.

Prioritized Paydown Queue (open items, highest score first)

| Rank | ID | Title | Score | Effort | Deadline | Provenance | |---|---|---|---|---|---|---| | 1 | TD-002 | JWT secret rotation | 9 / 10 | S | 2026-06-01 ⚠️ | discovered | | 2 | TD-001 | Sync file I/O in export pipeline | 8 / 10 | M | — | chosen | | 3 | TD-004 | UserService.findAll() pagination | 8 / 10 | M | — | discovered | | 4 | TD-005 | Mongoose 6.x EOL upgrade | 7 / 10 | L | 2026-09-01 | discovered | | 5 | TD-003 | Hardcoded invite email template | 3 / 10 | S | — | chosen |

Sprint Paydown Recommendation — 2026-05-13

Stated budget: 6 engineer-days

| Recommendation | Rationale | |---|---| | ✅ Take on TD-002 (S, ~1–2 days) | Hard deadline June 1; SOC 2 window is immovable. Highest score in register. | | ✅ Take on TD-001 (M, ~3–5 days) | Remaining budget fits. Active production risk at scale. Workaround degrades user experience. | | ⏸ Defer TD-004 | PR #301 already in review — do not duplicate effort; let it land organically. | | ⏸ Defer TD-005 | Deadline is September; starting now wastes runway that should fund TD-001/002 first. | | ⏸ Defer TD-003 | Score 3 / 10. No user-facing or reliability impact. Park until CMS is scheduled. |

Budget fit: TD-002 (2d) + TD-001 (4d) = 6 days. Matches stated budget exactly. If TD-002 closes early, use slack to begin TD-004 review support.

CI Integration — Flag Debt-Adding PRs

Add to .github/workflows/ci.yml:

- name: Scan for new technical debt markers
  run: |
    NEW_MARKERS=$(git diff origin/main...HEAD -- '*.ts' '*.tsx' '*.js' | \
      grep -E '^\+.*\b(TODO|FIXME|HACK|XXX|DEBT)\b' | grep -v '^+++')
    if [ -n "$NEW_MARKERS" ]; then
      echo "⚠️  New technical debt markers detected in this PR:"
      echo "$NEW_MARKERS"
      echo ""
      echo "Please add a TECH_DEBT.md entry before merging, or annotate with:"
      echo "  # DEBT-ACCEPTED: <reason> — <owner> — <date>"
      echo "to acknowledge the debt explicitly."
      exit 1
    fi

Policy: PRs that introduce TODO, FIXME, HACK, or DEBT markers must either (a) include a new TD-NNN entry in TECH_DEBT.md, or (b) include a DEBT-ACCEPTED inline annotation with owner and date. The CI check does not block on pre-existing markers — only net-new lines in the diff.