Charon/docs/plans/current_spec.md

PR #666 Patch Coverage Recovery Spec (Approval-Ready)

Date: 2026-02-16 Owner: Planning Agent Status: Draft for Supervisor approval (single coherent plan)

1) Scope Decision (Unified)

In Scope

• Backend unit-test additions only, targeting changed patch lines in backend handlers/services/utils.
• Minimum-risk posture: prioritize test-only additions in files already touched by PR #666 before opening any new test surface.
• Coverage validation using current backend coverage task/script.

Out of Scope

• E2E/Playwright, integration, frontend, Docker, and security scan remediation.

E2E Decision for this task

• E2E is explicitly out-of-scope for this patch-coverage remediation.
• Rationale: target metric is Codecov patch lines on backend changes; E2E adds runtime risk/cycle time without direct line-level patch closure.

Scope Reconciliation with Current Implementation (PR #666)

Confirmed already touched backend test files:

• backend/internal/api/handlers/import_handler_test.go
• backend/internal/api/handlers/settings_handler_helpers_test.go
• backend/internal/api/handlers/emergency_handler_test.go
• backend/internal/services/backup_service_test.go
• backend/internal/api/handlers/backup_handler_test.go
• backend/internal/api/handlers/system_permissions_handler_test.go
• backend/internal/api/handlers/notification_provider_handler_validation_test.go

Optional/deferred (not yet touched in current remediation pass):

• backend/internal/util/permissions_test.go
• backend/internal/services/notification_service_json_test.go
• backend/internal/services/backup_service_rehydrate_test.go
• backend/internal/api/handlers/security_handler_coverage_test.go

2) Single Source of Truth for Success

Authoritative success metric:

• Codecov PR patch status (lines) is the source of truth for this task.

Relationship to codecov.yml:

• coverage.status.patch.default.target: 100% and required: false means patch status is advisory in CI.
• For this plan, we set an internal quality gate: patch lines >= 85% (minimum), preferred >= 87% buffer.
• Local script output (go tool cover) remains diagnostic; pass/fail is decided by Codecov patch lines after upload.

3) Feasibility Math and Coverage-Line Budget

Given baseline:

• Patch coverage = 60.84011%
• Missing patch lines = 578

Derived totals:

• Let total patch lines = T
• 578 = T * (1 - 0.6084011) => T ≈ 1476
• Currently covered lines C0 = 1476 - 578 = 898

Required for >=85%:

• C85 = ceil(0.85 * 1476) = 1255
• Additional covered lines required: 1255 - 898 = 357

Budget by phase (line-coverage gain target):

Phase	Target line gain	Cumulative gain target	Stop/Go threshold
Phase 1	+220	+220	Stop if <+170; re-scope before Phase 2
Phase 2	+100	+320	Stop if <+70; activate residual plan
Phase 3 (residual closure)	+45	+365	Must reach >=+357 total

Notes:

• Planned total gain +365 gives +8 lines safety over minimum +357.
• If patch denominator changes due to rebase/new touched lines, recompute budget before continuing.

4) Target Files/Functions (Concise, Specific)

Primary hotspots (Phase 1 focus, aligned to touched tests first):

• backend/internal/api/handlers/system_permissions_handler.go
  • RepairPermissions, repairPath, normalizePath, pathHasSymlink, isWithinAllowlist, mapRepairErrorCode
• backend/internal/services/backup_service.go
  • RestoreBackup, extractDatabaseFromBackup, unzipWithSkip, RehydrateLiveDatabase, GetAvailableSpace
• backend/internal/api/handlers/settings_handler.go
  • UpdateSetting, PatchConfig, validateAdminWhitelist, syncAdminWhitelistWithDB
• backend/internal/api/handlers/import_handler.go
  • GetStatus, Upload, Commit, Cancel, safeJoin
• backend/internal/api/handlers/backup_handler.go
  • Restore, isSQLiteTransientRehydrateError
• backend/internal/api/handlers/emergency_handler.go
  • SecurityReset, disableAllSecurityModules, upsertSettingWithRetry
• backend/internal/api/handlers/notification_provider_handler.go
  • isProviderValidationError, provider validation branches

Secondary hotspots (Phase 2 focus, optional/deferred expansion):

• backend/internal/api/handlers/security_handler.go (GetStatus, latestConfigApplyState)
• backend/internal/util/permissions.go (CheckPathPermissions, MapSaveErrorCode, MapDiagnosticErrorCode)
• backend/internal/services/notification_service.go (sendJSONPayload, TestProvider, RenderTemplate)

5) Execution Phases with Strict Stop/Go and De-Scoping Rules

Phase 0 - Baseline Lock

Actions:

• Run Test: Backend with Coverage task (.github/skills/scripts/skill-runner.sh test-backend-coverage).
• Record baseline patch lines from Codecov PR view and local artifact backend/coverage.txt.

Go gate:

• Baseline captured and denominator confirmed.

Stop gate:

• If patch denominator changed by >5% from 1476, pause and recompute budgets before coding.

Phase 1 - High-yield branch closure

Actions:

• Extend existing tests only in:
  • backend/internal/api/handlers/system_permissions_handler_test.go
  • backend/internal/services/backup_service_test.go
  • backend/internal/api/handlers/backup_handler_test.go
  • backend/internal/api/handlers/emergency_handler_test.go
  • backend/internal/api/handlers/settings_handler_helpers_test.go
  • backend/internal/api/handlers/import_handler_test.go
  • backend/internal/api/handlers/notification_provider_handler_validation_test.go

Go gate:

• Achieve >= +170 covered patch lines and no failing backend tests.

Stop gate:

• If < +170, do not proceed; re-scope to only highest delta-per-test functions.

Phase 2 - Secondary branch fill

Actions:

• Extend tests in:
  • backend/internal/api/handlers/security_handler_coverage_test.go
  • backend/internal/util/permissions_test.go
  • backend/internal/services/backup_service_rehydrate_test.go
  • backend/internal/services/notification_service_json_test.go

Go gate:

• Additional >= +70 covered patch lines in this phase.

Stop gate:

• If < +70, skip low-yield areas and move directly to residual-line closure.

Phase 3 - Residual-line closure (minimum-risk)

Actions:

• Work only uncovered/partial lines still shown in Codecov patch details.
• Add narrow table-driven tests to existing files; no new harness/framework.

Go gate:

• Reach total >= +357 covered lines and patch >=85%.

Stop gate:

• If a residual branch requires production refactor, de-scope it and log as follow-up.

Global de-scope rules (all phases)

• No production code changes unless a test proves a correctness bug.
• No new test framework, no integration/E2E expansion, no unrelated cleanup.
• No edits outside targeted backend test and directly related helper files.

6) Current Tasks/Scripts (Deprecated references removed)

Use these current commands/tasks only:

• Backend coverage (preferred): Test: Backend with Coverage
  • command: .github/skills/scripts/skill-runner.sh test-backend-coverage
• Equivalent direct script: bash scripts/go-test-coverage.sh
• Optional backend unit quick check: Test: Backend Unit Tests
  • command: .github/skills/scripts/skill-runner.sh test-backend-unit

Deprecated tasks are explicitly out-of-plan (for this work):

• Security: CodeQL Go Scan (DEPRECATED)
• Security: CodeQL JS Scan (DEPRECATED)

7) Residual Uncovered Lines Handling (Beyond hotspot table)

After each phase, run a residual triage loop:

1. Export remaining uncovered/partial patch lines from Codecov patch detail.
2. Classify each residual line into one of:
   • validation/error mapping
   • permission/role guard
   • fallback/retry
   • low-value defensive log/telemetry
3. Apply closure rule:
   • First three classes: add targeted tests in existing suite.
   • Last class: close only if deterministic and cheap; otherwise de-scope with rationale.
4. Maintain a residual ledger in the PR description:
   • line(s), owning function, planned test, status (closed/de-scoped), reason.

Exit condition:

• No unclassified residual lines remain.
• Any de-scoped residual lines have explicit follow-up items.

8) Acceptance Criteria (Unified)

1. One coherent plan only (this document), no conflicting statuses.
2. E2E explicitly out-of-scope for this patch-coverage task.
3. Success is measured by Codecov patch lines; local statement output is diagnostic only.
4. Feasibility math and phase budgets remain explicit and tracked against actual deltas.
5. All phase stop/go gates enforced; de-scope rules followed.
6. Only current tasks/scripts are referenced.
7. Residual uncovered lines are either closed with tests or formally de-scoped with follow-up.
8. Scope remains reconciled with touched files first; deferred files are only pulled in if phase gates require expansion.