Technical Debt Management Policy

Purpose

This policy establishes a systematic approach to identifying, tracking, prioritising, and remediating technical debt across Maelstrom AI’s codebases. Technical debt management is important for:

• Code Quality. Maintaining high code quality standards over time
• Security. Identifying and addressing security-related shortcuts
• Privacy. Tracking privacy-impacting technical decisions
• Maintainability. Ensuring long-term system sustainability
• Compliance. Meeting ISO 27001 UC-164 (Technical Debt Management) requirements

Status: Active (effective Q2 2025) Owner: Engineering Team Review Frequency: Quarterly Next Review: 2026-11-21

Policy Statement

Maelstrom AI will maintain a formal technical debt register to track all known technical debt items, prioritise them based on risk and business value, and systematically remediate them through quarterly debt reduction sprints and continuous improvement practices.

Technical debt is defined as: Suboptimal code, architecture, or implementation decisions that provide short-term benefits but create long-term costs in terms of maintainability, security, performance, or compliance.

Debt Categories

All technical debt items must be classified into one of the following categories:

1. Security Debt

Definition: Security vulnerabilities, outdated dependencies with known CVEs, weak cryptographic implementations, or security shortcuts.

Examples:

• Vulnerable dependencies flagged by Dependabot
• Missing security controls (e.g., rate limiting)
• Hardcoded credentials or secrets in non-production code
• Weak authentication mechanisms
• Missing input validation

Priority: HIGHEST (Security debt is prioritised above all other categories)

SLA:

• CRITICAL: 7 days
• HIGH: 30 days
• MEDIUM: 90 days
• LOW: Next quarterly sprint

2. Privacy Debt

Definition: Privacy-impacting shortcuts, incomplete consent flows, excessive data collection, or privacy control gaps.

Examples:

• Missing privacy notices
• Incomplete DSAR (Data Subject Access Request) handling
• Over-collection of personal data
• Missing data retention enforcement
• Privacy controls not fully implemented

Priority: HIGH (Privacy debt impacts regulatory compliance)

SLA:

• CRITICAL: 14 days
• HIGH: 60 days
• MEDIUM: 90 days
• LOW: Next quarterly sprint

3. Code Quality Debt

Definition: Code complexity, duplication, test coverage gaps, linter warnings, or architectural inconsistencies.

Examples:

• Complex functions flagged by Clippy (cognitive_complexity warnings)
• Duplicated code across modules
• Missing unit tests or low test coverage
• ESLint/TSLint warnings
• Deprecated API usage
• TODO/FIXME comments in production code
• Poor naming conventions or lack of documentation

Priority: MEDIUM (Impacts maintainability and developer velocity)

SLA:

• HIGH: 90 days
• MEDIUM: Next quarterly sprint
• LOW: Opportunistic (Boy Scout Rule)

4. Performance Debt

Definition: Known performance inefficiencies, missing caching, N+1 queries, or resource optimisation opportunities.

Examples:

• Inefficient database queries
• Missing caching layers
• Unoptimized cryptographic operations
• Large bundle sizes in frontend applications
• Memory leaks or excessive allocations

Priority: MEDIUM (Unless customer-impacting, then HIGH)

SLA:

• HIGH: 90 days
• MEDIUM: Next quarterly sprint
• LOW: Opportunistic

5. Documentation Debt

Definition: Missing documentation, outdated guides, incomplete API documentation, or unclear code comments.

Examples:

• Missing README files
• Outdated architecture diagrams
• Incomplete API documentation
• Missing deployment guides
• Undocumented configuration options

Priority: LOW (Unless blocking other work, then MEDIUM)

SLA:

• MEDIUM: Next quarterly sprint
• LOW: Opportunistic

Debt Tracking

Tool: GitHub Issues & Projects

Maelstrom AI uses GitHub Issues across all repositories to track technical debt, organised via GitHub Projects for cross-repository visibility.

Labels

All debt items must be tagged with appropriate labels:

Primary Labels (Required):

• tech-debt - All technical debt items
• security-debt - Security category
• privacy-debt - Privacy category
• code-quality-debt - Code quality category
• performance-debt - Performance category
• documentation-debt - Documentation category

Priority Labels (Required):

• priority: critical - Immediate action required (security/privacy)
• priority: high - Address within SLA
• priority: medium - Schedule for quarterly sprint
• priority: low - Opportunistic remediation

Effort Labels (Required):

• effort: small - < 4 hours
• effort: medium - 4-16 hours (0.5-2 days)
• effort: large - 16+ hours (2+ days)

Status Labels (Automatic via GitHub Projects):

• status: backlog - Identified but not scheduled
• status: planned - Scheduled for upcoming sprint
• status: in-progress - Currently being worked on
• status: blocked - Blocked by external dependency

Issue Template

All technical debt issues must use the following template:

## Debt Description
[Clear description of the technical debt]

## Category
- [ ] Security Debt
- [ ] Privacy Debt
- [ ] Code Quality Debt
- [ ] Performance Debt
- [ ] Documentation Debt

## Impact
- **Risk**: [Security/Privacy/Maintainability/Performance impact]
- **Affected Components**: [List components/files]
- **User Impact**: [Customer-facing impact, if any]

## Current Workaround
[How we're currently handling this, if applicable]

## Proposed Solution
[Recommended approach to remediate]

## Effort Estimate
- [ ] Small (< 4 hours)
- [ ] Medium (4-16 hours)
- [ ] Large (16+ hours)

## Priority Justification
[Why this priority level?]

## Related Issues
[Links to related issues, gap items, or risks]

## Compliance Impact
[ISO 27001, GDPR, or other compliance impacts]

Debt Prioritisation

Technical debt is prioritised using a Risk-Effort Matrix:

Priority Scoring Formula

Priority Score = (Risk Score × 10) - (Effort Score × 2)

Where:

• Risk Score. 1 (Low) to 5 (Critical)
• Effort Score. 1 (Small) to 5 (Large)

Risk Scoring Criteria

Effort Scoring Criteria

Prioritisation Examples

Debt Remediation Process

1. Quarterly Debt Reduction Sprints

Cadence: 1 week per quarter (4 sprints per year)

Timing: Last week of each quarter (March, June, September, December)

Goal: Reduce debt inventory by 20% per sprint (focusing on highest-priority items)

Sprint Planning:

1. Review debt register (all items)
2. Re-prioritise based on current risk surface
3. Select items totaling ~40 engineering hours (1 week for team)
4. Assign owners
5. Track completion during sprint
6. Retrospective at end of sprint

Success Metrics:

• Items completed vs. planned
• Total debt inventory trend (should decrease)
• High-priority debt count (target: < 10 items)
• Debt age (avoid items > 180 days)

2. Boy Scout Rule (Continuous Improvement)

Principle: “Leave code better than you found it”

Application:

• When working on any code, fix nearby low-priority debt
• Address TODO/FIXME comments encountered during development
• Refactor small code smells immediately (< 30 minutes)
• Update documentation when making changes

Guidelines:

• Don’t let Boy Scout Rule block feature delivery
• Limit to 10-15% of feature development time
• Focus on LOW and MEDIUM priority items
• Document what you fixed in PR description

3. Security & Privacy Debt: Immediate Action

Critical Security/Privacy Debt:

• Must be addressed immediately (within SLA)
• Bypass normal sprint planning
• Escalate to Security Lead and ISMS Owner
• May require emergency deployment

Process:

1. Identify critical security/privacy debt
2. Create incident ticket (reference in debt issue)
3. Assign to Security Lead or senior developer
4. Fix and deploy within SLA
5. Post-mortem: Why did this debt exist? How to prevent?

Debt Limits

To prevent excessive debt accumulation, Maelstrom AI enforces the following limits:

Hard Limits (Cannot Exceed)

Soft Limits (Warning Thresholds)

Enforcement

1. Automated Alerts. GitHub Actions to flag limit violations
2. Monthly Review. Engineering team reviews debt metrics
3. Quarterly Review. ISMS Owner reviews with management

Metrics and Reporting

Key Metrics

1. Total Debt Count: Total number of open debt issues
2. Debt by Category: Count per category (Security, Privacy, Code Quality, Performance, Documentation)
3. Debt by Priority: Count per priority level (Critical, High, Medium, Low)
4. Debt Age: Average age of debt items, median age, max age
5. Debt Velocity: New debt created vs. debt resolved (weekly/monthly)
6. Debt Remediation Rate: % of debt items resolved per quarter

Monthly Debt Report

Audience: Engineering Team Frequency: Monthly (first Monday of each month) Format: GitHub Project dashboard + Signal summary

Contents:

• Total debt count (trend chart)
• Debt by category and priority (breakdown)
• Oldest debt items (> 90 days)
• Debt resolved last month
• Upcoming quarterly sprint preview

Quarterly Debt Review

Audience: ISMS Owner + Engineering Team Frequency: Quarterly (end of quarter) Format: Management review document

Contents:

• Quarterly debt sprint retrospective
• Debt trend analysis (quarter-over-quarter)
• Root cause analysis (why is debt created?)
• Process improvements
• Debt forecast for next quarter

Current Technical Debt Register

(This section is populated from codebase analysis as of Q4 2025)

HIGH Priority Debt

DEBT-001: Automated KV Data Backups (GAP-H006)

• Category. Security Debt
• Priority. HIGH
• Effort. Medium (16 hours)
• Risk. Data loss of signing keys, config, audit logs
• Status. Complete (January 2025)
• Description. Cloudflare KV namespaces backed up automatically by provii-backup cron job exporting to R2 storage.
• Affected Components. provii-verifier, provii-issuer (KV namespaces), provii-backup
• Resolution. Implemented as a Cloudflare Worker cron job (provii-backup) that exports KV namespaces to R2 storage on a scheduled basis
• Compliance Impact. ISO 27001:2022 A.8.13 (Information backup), UC-062, UC-168
• Related. Risk RISK-2025-M005

MEDIUM Priority Debt

DEBT-002: JWT Session Token Re-implementation

• Category. Code Quality Debt
• Priority. MEDIUM
• Effort. Medium (12 hours)
• Risk. Session management relies on workaround implementation
• Status. Backlog
• Description. JWT session tokens disabled due to WASM compatibility issues. Currently using HMAC-based tokens as workaround.
• Location. provii-issuer/worker/src/session.rs:21-24
• Affected Components. provii-issuer (session management)
• Proposed Solution. Re-implement using WASM-compatible JWT library or formalize custom HMAC token approach
• Compliance Impact. None (workaround is secure)
• Code Reference:

// NOTE: JWT session token functionality has been temporarily disabled due to WASM compatibility
// issues with the `jsonwebtoken` crate in Cloudflare Workers environment.
//
// TODO: Re-implement using a WASM-compatible JWT library or custom HMAC-based tokens

DEBT-003: Tamper-Proof Audit Log DO Integration

• Category. Security Debt
• Priority. MEDIUM
• Effort. Medium (8 hours)
• Risk. Audit log features not fully integrated with Durable Objects
• Status. Backlog
• Description. Tamper-proof audit logging implemented but not integrated with AuditLogDO for persistence.
• Location. provii-verifier/src/security/tamper_proof_audit.rs:111, 192, 208, 223
• Affected Components. provii-verifier (audit logging)
• Proposed Solution. Integrate tamper-proof audit module with AuditLogDO for persistent storage
• Compliance Impact. ISO 27001 A.8.15 (Logging), UC-046
• Code Reference:

// TODO: Integrate with AuditLogDO when needed
// TODO: Implement when DO integration is ready

DEBT-004: Retention DO Alarm Scheduling Compatibility

• Category. Code Quality Debt
• Priority. MEDIUM
• Effort. Small (4 hours)
• Risk. Automatic retention cleanup relies on manual cron triggers instead of DO alarms
• Status. Backlog
• Description. Durable Object alarm scheduling disabled due to ScheduledTime API compatibility issues. Using Cloudflare Cron Triggers as workaround.
• Location. provii-verifier/src/durable_objects/retention_do.rs:99, 108, 146, 167, 176
• Affected Components. provii-verifier (data retention)
• Proposed Solution. Update to latest Workers API or document Cron Trigger approach as permanent solution
• Compliance Impact. None (Cron Triggers are reliable alternative)
• Code Reference:

// NOTE: Alarm rescheduling is commented out due to ScheduledTime API compatibility
// NOTE: Automatic scheduling via DO Alarms is disabled. Use Cloudflare Cron Triggers instead.

LOW Priority Debt

DEBT-005: CODEOWNERS Files Missing

• Category. Code Quality Debt
• Priority. LOW
• Effort. Trivial (1 hour)
• Risk. Code review ownership not enforced via CODEOWNERS
• Status. Planned (Q1 2026 - GAP-L007)
• Description. No CODEOWNERS files in repositories to automatically assign reviewers.
• Affected Components. All repositories
• Proposed Solution. Add CODEOWNERS file to each repository with appropriate ownership mappings
• Compliance Impact. None (compensating controls exist)

DEBT-006: Accessibility Test Stubs

• Category. Code Quality Debt
• Priority. LOW
• Effort. Large (40+ hours)
• Risk. Accessibility testing incomplete
• Status. Backlog
• Description. Accessibility tests in the Provii mobile wallet (client) repository have TODO stubs but no implementation.
• Location. provii/android/app/src/androidTest/java/com/provii/wallet/accessibility/HeadingHierarchyTest.kt (30+ TODO items)
• Affected Components. Provii mobile wallet (client) repository under the MaelstromAI GitHub enterprise (Android accessibility)
• Proposed Solution. Implement accessibility test cases or remove stub file
• Compliance Impact. None (manual accessibility testing conducted)

DEBT-007: Credential Selection UI

• Category. Code Quality Debt
• Priority. LOW
• Effort. Medium (16 hours)
• Risk. User experience gap when multiple credentials available
• Status. Backlog
• Description. iOS wallet SDK has TODO for credential selection UI when multiple credentials match.
• Location. provii/ios/ProviiWallet/ProviiWallet/SDK/WalletSDKBridge.swift:248
• Affected Components. Provii mobile wallet (client) repository under the MaelstromAI GitHub enterprise (iOS wallet)
• Proposed Solution. Implement credential selection UI or document single-credential assumption
• Compliance Impact. None
• Code Reference:

// TODO: Show credential selection UI

DEBT-008: Test Credential Signing Integration

• Category. Code Quality Debt
• Priority. LOW
• Effort. Small (4 hours)
• Risk. Test tooling incomplete
• Status. Backlog
• Description. Test credential tool has TODO for calling sandbox issuer API.
• Location. provii-crypto/tools/test-credentials/src/main.rs:195
• Affected Components. provii-crypto (testing tools)
• Proposed Solution. Integrate with sandbox issuer API or document manual signing process
• Compliance Impact. None (developer tooling only)
• Code Reference:

// TODO: Call sandbox issuer API to sign the commitment

DEBT-009: Sapling ECC Gadget Naming

• Category. Documentation Debt
• Priority. LOW
• Effort. Trivial (15 minutes)
• Risk. Cryptographic code naming inconsistency
• Status. Backlog
• Description. Cryptographic gadget function has TODO to rename for clarity.
• Location. provii-crypto/crypto-circuit-age/src/gadgets/sapling_ecc.rs:44
• Affected Components. provii-crypto (cryptography)
• Proposed Solution. Rename function to lookup3_uv for consistency
• Compliance Impact. None
• Code Reference:

// TODO: rename to lookup3_uv

Debt Identification Process

Sources of Technical Debt

1. Code Comments: TODO, FIXME, HACK, XXX, NOTE, OPTIMIZE, BUG comments
2. Security Scanners: Dependabot, cargo audit, Trivy, Snyk
3. Code Quality Tools: Clippy (Rust), ESLint (TypeScript), SonarQube
4. Code Reviews: Reviewer-identified shortcuts or compromises
5. Gap Analysis: Compliance gap items (e.g., GAP-H006, GAP-M012)
6. Incident Post-Mortems: Root cause analysis findings
7. Refactoring Opportunities: Discovered during feature development

Debt Logging Workflow

1. Identify: Developer or tool identifies technical debt
2. Document: Create GitHub Issue using template
3. Classify: Assign category, priority, and effort labels
4. Link: Reference in code comment (if applicable)
5. Track: Add to GitHub Project board
6. Review: Engineering team reviews monthly
7. Remediate: Address via quarterly sprint or Boy Scout Rule

Integration with Existing Processes

Code Quality Tools

Maelstrom AI already uses the following tools (no changes required):

• Rust. Clippy (linter), cargo audit (security)
• TypeScript. ESLint (linter), npm audit (security)
• Dependencies. Dependabot (automated PRs for vulnerable dependencies)
• CI/CD. Automated checks on all PRs

Integration: Security and code quality issues flagged by these tools should be logged as technical debt if not immediately resolved.

GitHub Workflow

Existing Workflow: Code review, branch protection, automated checks

New Workflow Additions:

1. PR Template: Add section: “Does this PR introduce technical debt? If yes, link to debt issue.”
2. Label Automation: GitHub Actions to auto-label debt issues based on keywords
3. Debt Dashboard: GitHub Project to visualize debt across all repositories

Change Management

Technical debt remediation follows the same change management process as feature development:

1. Planning: Document solution in debt issue
2. Approval: Review by code owner or Security Lead (for HIGH/CRITICAL debt)
3. Implementation: Follow secure development lifecycle (SLSA Level 3)
4. Testing: Unit tests, integration tests, security testing
5. Deployment: Standard deployment process (canary, gradual rollout)
6. Validation: Verify debt item resolved, close issue

Reference: Change Management Policy

Roles and Responsibilities

Compliance Mapping

This policy satisfies the following compliance requirements:

Related Documents:

• Gap Analysis - GAP-M012
• Change Management
• Change Management

Review and Maintenance

Document Review

• Frequency. Quarterly (alongside debt sprint retrospective)
• Owner. Engineering Team
• Approval. ISMS Owner
• Next Review. 2026-11-21

Policy Updates

This policy will be updated when:

• Debt limits are adjusted
• New debt categories are added
• Tools or processes change
• Compliance requirements change

Debt Register Updates

The current debt register (above) will be updated:

• Monthly. Add newly identified debt items
• Quarterly. Remove resolved debt items, update priorities
• Annually. Archive resolved debt items to historical register

Related Documents

1. Gap Analysis - Source of gap-related debt items
2. Change Management - Debt remediation process and SDLC integration
3. Risk Register - Risk-based prioritisation

Appendix A: GitHub Labels Setup

To implement this policy, create the following labels in all repositories:

Primary Debt Labels

# Create in all repositories
gh label create "tech-debt" --color "fbca04" --description "Technical debt item"
gh label create "security-debt" --color "d73a4a" --description "Security-related technical debt"
gh label create "privacy-debt" --color "d93f0b" --description "Privacy-related technical debt"
gh label create "code-quality-debt" --color "0e8a16" --description "Code quality technical debt"
gh label create "performance-debt" --color "1d76db" --description "Performance-related technical debt"
gh label create "documentation-debt" --color "0075ca" --description "Documentation technical debt"

Priority Labels

gh label create "priority: critical" --color "b60205" --description "Immediate action required"
gh label create "priority: high" --color "d93f0b" --description "Address within SLA"
gh label create "priority: medium" --color "fbca04" --description "Schedule for quarterly sprint"
gh label create "priority: low" --color "0e8a16" --description "Opportunistic remediation"

Effort Labels

gh label create "effort: small" --color "c2e0c6" --description "< 4 hours"
gh label create "effort: medium" --color "fef2c0" --description "4-16 hours (0.5-2 days)"
gh label create "effort: large" --color "f9d0c4" --description "16+ hours (2+ days)"

Appendix B: Debt Issue Template

Save as .github/ISSUE_TEMPLATE/technical-debt.md in all repositories:

---
name: Technical Debt
about: Track technical debt item
title: '[DEBT] '
labels: tech-debt
assignees: ''
---

## Debt Description
<!-- Clear description of the technical debt -->

## Category
- [ ] Security Debt
- [ ] Privacy Debt
- [ ] Code Quality Debt
- [ ] Performance Debt
- [ ] Documentation Debt

## Impact
- **Risk**: <!-- Security/Privacy/Maintainability/Performance impact -->
- **Affected Components**: <!-- List components/files -->
- **User Impact**: <!-- Customer-facing impact, if any -->

## Current Workaround
<!-- How we're currently handling this, if applicable -->

## Proposed Solution
<!-- Recommended approach to remediate -->

## Effort Estimate
- [ ] Small (< 4 hours)
- [ ] Medium (4-16 hours)
- [ ] Large (16+ hours)

## Priority Justification
<!-- Why this priority level? -->

## Code References
<!-- File paths and line numbers -->

## Related Issues
<!-- Links to related issues, gap items, or risks -->

## Compliance Impact
<!-- ISO 27001, GDPR, or other compliance impacts -->

Document Information