teqo/docs/TECH-DEBT.md

Tech Debt

Ledger of known engineering debt. Items large enough to be scheduled work become entries in roadmap.md (linked in the Ref column); this file tracks the full inventory so nothing is lost. Sourced initially from the 2026-07-23 engineering-standards audits.

Debt Ledger

Item	Location	Type	Risk	Effort	Priority	Status	Ref
164 unused exports + 60 unused types reported by knip (warn-level; 158 at Pass 1)	god modules, ui kit families	dead code	low	M	P2	closed 2026-07-25 (Pass 2 W4b): 0 findings; exports/types/enumMembers at error in CI; tests entered the knip graph; duplicates off (only hits were the 6 deliberate access aliases canUpdateX = canReadX)	Pass 2 W4b
knip loader noise: Error loading src/payload.config.ts (server-only guard)	knip run output	tooling noise	none (exit 0, static graph resolves)	S	P3	open
Aikido scan unusable: aikido_full_scan answers Opengrep exit code 2 for any input, including a one-line probe file, so the per-change security scan the rules mandate cannot complete. What it reported is an artifact of the failed run, not attributable to the code under review; the Aikido feed lists nothing for this repo. The shpjs devDependency added by B8 F2 is therefore SCA-unverified	Aikido MCP / local scanner	tooling outage (security gate)	medium — the gate is skipped, not passed	S	P2	open 2026-07-26 (found during B8 F2)
Missing-consent window fixture releases its exclusive lease during the observation window — readers can interleave (rare flake). Full fix: session-level advisory lock spanning delete→op→restore + updated fault-path pins	tests/helpers/testDatabaseLease.ts (withMissingInviteConsentFixture)	test-infra race	low (ms-wide window; shared leases added 2026-07-23 narrow it)	M	P2	open
users collection has no roles (all admins omnipotent)	src/collections/Users.ts	RBAC	medium (small trusted admin set)	M (schema migration)	P1 before widening /admin	closed 2026-07-27 (admin|editor; migration 20260727_032523_add_users_roles; roles-admin-payload.md)	AGENTS Known Gaps #1
Any campaign user can enumerate staff names/roles (canReadCampaignUsers)	src/utilities/access/campaignUsers.ts	info disclosure	low	S	P2	open
removeSupporterData deletes via overrideAccess: true while canDeleteSupporter is admin-only	src/app/(campaign)/campanha/actions/supporter.ts	access asymmetry (likely intentional LGPD path)	low	S	P3	open — document or align
Legacy public consent flows hardcode document IDs (consent: 2)	src/app/(frontend)/actions/submitWhatsapp.ts	correctness	medium	S	P1	closed 2026-07-25 (Pass 2 D3): resolves Consent.key = 'whatsapp-inscricao' fail-closed; migration 20260725_170000 tags the live doc (id 2, key vazio) com a chave	AGENTS Known Gaps #2
E2E suite thin (7 specs; most campaign CRUD int-only)	tests/e2e/	coverage	medium	L	P2	open
CI runs on GitHub mirror only (no Codeberg/Woodpecker pipeline)	.github/workflows/ci.yml	process	low	M	P3	open
E2E campaign journeys flake with 2 workers — root cause narrowed 2026-07-26 (B13), and it is not only latency: (a) campaignMunicipalities/campaign-pwa click the leader consent checkbox before hydration attaches the handler, and (b) the municipality fixture picks names by regex, so "Conde" also matches "Condeúba". Reproduced on a clean main tree, so it is not a B13 regression; both specs pass in isolation	tests/e2e/campaignMunicipalities.e2e.spec.ts, tests/e2e/campaign-pwa.e2e.spec.ts	test-infra	medium (masks real failures in the delivery gate)	S	P2	open — wait for an interactive-state signal instead of the element existing, and anchor fixture lookups to exact names/slugs instead of substring regex
Post listing cache holds all published posts, filters in memory	src/utilities/posts.ts	scale (fine at ~tens of posts)	low	M	P3	open — watch corpus growth
Petition generateStaticParams uses uncached getDocuments without select/depth: 0	src/utilities/documents.ts consumers	over-fetch (build-time)	low	S	P2	closed 2026-07-23 (Phase 2: getPetitionIds with depth: 0 + empty select)
Compare mode (?compare=) still queries per candidate uncached cross-request	src/utilities/municipalityMapData.ts	perf	low	M	P3	open — React cache() dedups in-request; add unstable_cache if profiling warrants
Map bundle serializes all years × scenarios (~100KB raw), +63.6 KB after B13 (competitiveRankByYear is ~57 KB of it: three years × 417 codes × {rank, candidates}, paid on every dashboard load even by the coordinator who never opens the "posição no município" scale)	municipalityMapContract.ts consumers	payload size	low — gzip crushes repeating keys to ~10KB on the wire; instant year/scale switching is a core analysis flow worth the bytes	M	P3	the 2026-07-23 deferral asked for profiling before acting; B13 supplied the number, so the trim is now scheduled as B13+ F4 (roadmap fill-in)	B13+ F4
Props→state useEffect mirrors in list controls/comboboxes	MunicipalityListExpectedVotesControl, AsyncSearchCombobox, StrictCombobox	pattern	none — reviewed 2026-07-23: guarded-equality sync is the correct "server echo vs local draft" reconciliation (A10 pattern), not derived state	—	—	closed (accepted as correct)
User-visible "Praça" copy survived the M1 rename (map panel title "Mapa das Praças", admin field descriptions, provisional Onda 0 consent texts, SupportStatusBadge summary, fallback/error strings, code comments)	rg -n 'Praça' src (~96 hits in 53 files, ~55 user-visible — 2026-07-25 audit)	copy drift	low (cosmetic; consent texts are provisional Onda 0 copies)	S	P2	open — scheduled Pass 2 W4f (consent texts stay for the legal batch)	Pass 2 W4f
Access checks re-read the actor per Local API call: getFreshCampaignUser caches in req.context, but a payload.find({ user, overrideAccess: false }) that passes no req gets a fresh context, so one /campanha/municipios render issues ~5 identical campaignUser reads on top of the layout's own pair	src/utilities/access/shared.ts + every overrideAccess: false caller	perf (round-trip fan-out)	low since the gru1 move (~2 ms each; it was ~120 ms each while functions ran in iad1)	M	P2	open — measured 2026-07-26. A React cache() layer would dedupe across requests, but it changes actor freshness inside server actions that mutate roles (reloadUnrestrictedActor), so it needs its own delivery with pins
authenticateCampaignToken reads the actor twice: Payload's JWT strategy already fetches the user document, then findByID(depth: 1) re-reads it — the second read's only unique contribution is populating avatar for the sidebar	src/utilities/campaignAuth.ts	perf (a round trip in the layout, so on every page)	low	S	P2	open — dropping it needs the avatar resolved another way, plus pins on removePrivateAuthFields and on role-downgrade freshness	RS+

Smell Inventory

Smell	Location	Refactoring	Status
God module: RBAC for every collection in one file (964 lines, ~80 exports)	src/utilities/campaignAccess.ts	split per domain under src/utilities/access/	done 2026-07-23 (14 domain modules; campaignAccess.ts kept as re-export surface)
God module: ~71 exports of electoral math	src/lib/electionInsights.ts	split by concern when next touched	done 2026-07-25 (Pass 2 W4a): module DELETED; survivors in electionFormat.ts + voteTrend.ts
Multi-feature action bag: CRUD + CSV import pipeline + LGPD in one file (722 lines)	src/app/(campaign)/campanha/actions/supporter.ts	split CRUD vs import	done 2026-07-23 (supporterImport.ts)
Clone twins: create/update/staff-assert/unique-conflict skeleton	actions/organization.ts ↔ actions/stateDeputy.ts	extract shared factory	done 2026-07-23 (runStaffEntityMutation in campaignEntityActions.ts)
14 near-identical formActions.ts try/catch→mapError→redirect/return ladders	src/app/(campaign)/campanha/**/formActions.ts	shared form-action wrapper	partially done — C8 F4 (2026-07-21/23) unified the municipality staff wrappers + 4 */nova ladders on runCampaignRedirectFormAction; 10 ladders written since remain hand-rolled (844 lines: assessores, planos, apoiadores ×2, demandas/[slug], liderancas/[id], organizacoes/[slug], dobradinhas/[slug], municipios editar, convite) — done 2026-07-25 (Pass 2 W4d): runCampaignFormAction + 13 ações migradas; exceções documentadas em comentário (planos, apoiadores/[id], convite login)
Flat 80+-file src/utilities/ junk drawer; lib/ vs utilities/ boundary undocumented	src/utilities/, src/lib/	document convention + move misfiled modules	done 2026-07-23 (convention in .cursor/rules/engineering-standards.mdc; RefreshRouteOnSave moved to components/)
Praça→Município rename leftovers in identifiers (PLAZA_MAP_YEARS, ACCESSIBLE_PLAZA_IDS_CONTEXT_KEY, …)	map/list utilities	finish rename	done 2026-07-23
Props→state useEffect mirrors	MunicipalityListExpectedVotesControl, comboboxes	key-remount or fully controlled	closed 2026-07-23 (accepted as correct — see Debt Ledger row)
Detail-page RSCs mixing loading + tab UI + forms (300+ lines)	municipios/[slug]/page.tsx, planos/[slug]/page.tsx	extract tab loaders/sections	done 2026-07-25 (Pass 2 W4c): tabs em MunicipalityDetailTabs.tsx / ActionPlanOverviewTab.tsx; gêmeos de tab dedupados em detailTabUi.ts
God module: list URL + filters + sort + labels + freshness in one file (765 lines, 59 exports)	src/utilities/municipalityUi.ts	split along url/filters/sort/labels/freshness seams	done 2026-07-25 (Pass 2 W1-D1): municipalityListUrl / municipalityListFilters / municipalityLabels / municipalitySignal
components/campaign/ flat with 106 files; utilities/ flat with 92	src/components/campaign/, src/utilities/	within-layer domain subfolders	components done 2026-07-25 (Pass 2 W2, 15 domínios); utilities/ deferred with trigger: a domain gaining its 3rd new module in a month gets its subfolder

Sprout / Wrap Register

Host	Sprouted/Wrapped	Notes
(none yet)

Adopted Conventions

• Zero lint warnings. pnpm lint runs with --max-warnings=0; deliberate placeholders use a _ prefix (argsIgnorePattern).
• as never is banned (ESLint no-restricted-syntax). Production code uses typed helpers (e.g. hookFilledCreateData for hook-completed create data); tests use stub<T>(partial) which keeps property-level checking. A justified eslint-disable-next-line is the only escape hatch.
• Dead code is deleted, not commented. knip runs in CI (files/dependencies at error level). After any change: pnpm exec knip and remove what died.
• Collections always declare access explicitly. Payload's default ("any authenticated user") is treated as a bug — see payloadAdminOnly.
• Generated migration signatures are exempt from unused-args linting (src/migrations/** override); never hand-edit migration content for lint cosmetics.
• Shared consent fixture rows are leased, never owned in integration tests (tests/helpers/testDatabaseLease.ts); deleting them steals from parallel spec files.

Debt Budget & Broken-Windows Policy

• New warnings/as never/unused exports fail or get ledgered the same day — no untracked // TODOs.
• Each delivery that runs /simplify registers surviving debts here or in docs/plans/escala-dry-pos-*.md (existing convention), whichever the item's size warrants.