Summary
Add per-area debt budgets / SLOs so teams can cap how much debt a directory or package is allowed to carry and gate CI when an area regresses past its budget.
Motivation
Baselines freeze all current debt globally; quality gates apply repo-wide severity policy. Neither lets a team say "the new src/payments module must stay under 20 issues" or "src/legacy may not get worse." Per-area budgets give teams a burn-down target and protect freshly-cleaned areas from backsliding.
Proposed behavior
- New config block:
{
"budgets": {
"src/payments": { "maxIssues": 20, "maxHigh": 0 },
"src/legacy": { "maxIssues": 250 }
}
}
- During scan, aggregate issues per matching path glob and compare against the budget.
- A budget breach fails the gate (respecting existing
--gate / exit-code policy) with a clear per-area message and remaining headroom.
debtlens scan --budget-report prints a per-area table (used / budget / headroom) without failing.
Implementation surface
- Extend
src/config/schema.ts, src/config/loadConfig.ts, src/config/validateConfig.ts, and src/config/mergeConfig.ts for the budgets block; reuse src/config/workspaces.ts glob matching.
- New
src/core/budgets.ts to evaluate budgets against ScanResult; integrate with src/core/gatePresets.ts / src/core/severity.ts exit-code policy.
- Reporter support for the budget table.
- Schema drift test (
tests/config/schema.test.ts) + budget evaluation tests.
Acceptance criteria
Difficulty: medium.
Summary
Add per-area debt budgets / SLOs so teams can cap how much debt a directory or package is allowed to carry and gate CI when an area regresses past its budget.
Motivation
Baselines freeze all current debt globally; quality gates apply repo-wide severity policy. Neither lets a team say "the new
src/paymentsmodule must stay under 20 issues" or "src/legacymay not get worse." Per-area budgets give teams a burn-down target and protect freshly-cleaned areas from backsliding.Proposed behavior
{ "budgets": { "src/payments": { "maxIssues": 20, "maxHigh": 0 }, "src/legacy": { "maxIssues": 250 } } }--gate/ exit-code policy) with a clear per-area message and remaining headroom.debtlens scan --budget-reportprints a per-area table (used / budget / headroom) without failing.Implementation surface
src/config/schema.ts,src/config/loadConfig.ts,src/config/validateConfig.ts, andsrc/config/mergeConfig.tsfor thebudgetsblock; reusesrc/config/workspaces.tsglob matching.src/core/budgets.tsto evaluate budgets againstScanResult; integrate withsrc/core/gatePresets.ts/src/core/severity.tsexit-code policy.tests/config/schema.test.ts) + budget evaluation tests.Acceptance criteria
budgetsvalidated by schema and merged with documented precedence.--budget-reportis non-failing.npm run test:allpasses.Difficulty: medium.