Charon/docs/plans/current_spec.md

## QA Test Failure Remediation Addendum (2026-02-19)

### Scope

- In scope: test instability fixes and UI expectation alignment for the currently failing QA gates only.
- Out of scope: feature additions, backend behavior changes unrelated to failing assertions, design refactors, and unrelated test cleanup.

### Failure Inventory (Source: `docs/reports/qa_report.md`)

1. `tests/settings/notifications.spec.ts`
  - Failing case A: provider enable/disable checkbox interaction fails (click interception/out-of-viewport).
  - Failing case B: invalid template preview assertion matches hidden text instead of visible error feedback.
2. `tests/security-enforcement/zzz-security-ui/system-security-settings.spec.ts`
  - Failing case: save success toast not visible in `should save general settings successfully`.
3. `frontend/src/pages/__tests__/Security.functional.test.tsx`
  - Failing case: expects Notifications button disabled when Cerberus is disabled, but current UI behavior keeps header action enabled.
4. Local patch preflight warning
  - `scripts/local-patch-report.sh` exits warning mode when `frontend/coverage/lcov.info` is missing, while still producing required artifacts.

### Root-Cause Hypotheses (Per Failing Test)

#### 1) `tests/settings/notifications.spec.ts`

- **Case A (enable/disable provider):**
  - Locator strategy is fragile (`checkbox` with sibling-label heuristic and fallback `first()`), so interaction can target a non-actionable/offscreen element after modal/card layout shifts.
  - `setChecked` can still fail when the selected checkbox is occluded by sticky UI layers or not in viewport; no explicit scroll/visibility stabilization is performed before toggling.
- **Case B (invalid template preview error):**
  - Assertion `getByText(/error|failed|invalid/i).first()` is broad and may resolve to hidden/static text (for example option labels or non-toast content) rather than user-visible error feedback.
  - Test does not scope to live regions, toast container, or form-level validation block, causing false target selection.

#### 2) `tests/security-enforcement/zzz-security-ui/system-security-settings.spec.ts`

- Save operation likely succeeds (API 200 observed), but toast visibility assertion is timing- and selector-sensitive.
- Current assertion mixes generic role/status and data-testid checks without first anchoring to a deterministic post-save signal (response + stable UI state), so ephemeral toast rendering window is missed in some runs.

#### 3) `frontend/src/pages/__tests__/Security.functional.test.tsx`

- Test expectation drift: spec assumes Notifications header button must be disabled when Cerberus is off.
- Current UI behavior appears to allow opening Notification settings regardless of Cerberus state (feature warning applies to enforcement controls, not necessarily header actions), making test assertion stale.

#### 4) `scripts/local-patch-report.sh` / coverage preflight

- Script behavior is by design: in missing-input mode it writes `test-results/local-patch-report.md` and `test-results/local-patch-report.json` then exits non-zero.
- QA gate interpretation is misaligned: artifact generation succeeds, but warning mode is treated as failure rather than preflight warning requiring upstream coverage generation.

### Ordered Minimal Fix Steps (Test + UI Expectation Alignment Only)

1. **Stabilize Notifications checkbox interaction**
  **Target:** `tests/settings/notifications.spec.ts`
  - Replace fallback checkbox locator with deterministic test-id or form-scoped role query tied to Enabled control only.
  - Add pre-action stabilization: ensure element is attached, visible, enabled, and scrolled into view before toggle.
  - Prefer click on associated label/control pair in modal context if native checkbox is visually wrapped.

2. **Narrow invalid-template error assertion to visible feedback channel**
  **Target:** `tests/settings/notifications.spec.ts`
  - Replace generic text matcher with scoped locator order: explicit error toast (`data-testid`/role alert), then visible form validation container.
  - Assert visibility on that scoped locator and avoid `.first()` on broad text searches.

3. **Stabilize system settings save-success verification**
  **Target:** `tests/security-enforcement/zzz-security-ui/system-security-settings.spec.ts`
  - Keep API response wait, then assert one deterministic success channel (shared toast helper or single canonical toast locator) with bounded timeout.
  - Avoid mixed fallback selectors that may match stale/inactive nodes.

4. **Align unit test expectation with intended UI contract**
  **Target:** `frontend/src/pages/__tests__/Security.functional.test.tsx` (+ `frontend/src/pages/Security.tsx` only if behavior contract requires it)
  - Confirm intended contract from current security page behavior and copy text semantics.
  - Minimal change path: update assertion to expected enabled state if product behavior intentionally permits Notifications action while Cerberus is disabled.
  - Alternate (only if contract requires disabled action): adjust button disabled logic in `Security.tsx` and keep existing unit expectation.
  - Choose exactly one path; do not change unrelated security-card logic.

5. **Clarify patch-preflight gate interpretation and sequencing**
  **Targets:** `docs/reports/qa_report.md` (evidence wording), optional test/runbook docs if needed
  - Record that preflight artifacts were produced in warning mode due to missing frontend coverage input.
  - Keep remediation action in validation sequence: generate frontend coverage before local-patch-report when full green gate is required.

### Validation Sequence (Return Full Gate to Green)

1. Run targeted Playwright notifications suite:
  `tests/settings/notifications.spec.ts` (Firefox project as currently gated).
2. Run targeted security UI suite:
  `tests/security-enforcement/zzz-security-ui/system-security-settings.spec.ts` (`security-tests` project).
3. Run focused frontend unit test file:
  `frontend/src/pages/__tests__/Security.functional.test.tsx`.
4. Generate frontend coverage output (`frontend/coverage/lcov.info`) via frontend coverage task/script.
5. Re-run local patch preflight and verify both artifacts exist and warning is cleared.
6. Re-run full required QA gate order for this branch:
  - Playwright targeted suites
  - Local patch preflight
  - Backend/frontend coverage gates
  - Type check
  - Pre-commit all files
  - Security scans (Trivy, Docker image scan, CodeQL Go/JS + findings gate)

### Acceptance Criteria (Addendum-Specific)

- All three failing test files pass in their targeted runs.
- No assertion relies on broad hidden-text matching for error/success feedback.
- Notifications unit assertion reflects the actual intended UI contract (test and implementation consistent).
- `test-results/local-patch-report.md` and `test-results/local-patch-report.json` are present, and preflight no longer reports missing `frontend/coverage/lcov.info`.
- No unrelated feature or architectural change is introduced.

## Notify-only PR1 Remediation Addendum (Supervisor Unblock)

Date: 2026-02-19
Status: Active addendum for PR1 unblock.
Precedence: This addendum overrides conflicting sections below for PR1 execution.

### Scope Lock

- In scope: Notify-only cutover for external notification provider dispatch, legacy provider migration completeness, and minimal QA unblock evidence.
- Out of scope: certificate flaky test work and any unrelated certificate/runtime refactors.

### Dispatch Source of Truth (Decision)

- **Selected approach: direct hard-cutover runtime logic** (not router+flags dispatch).
- Runtime authority is in:
  - `backend/internal/services/notification_service.go`
   - `supportsJSONTemplates(...)`
   - `(*NotificationService).SendExternal(...)`
   - `(*NotificationService).TestProvider(...)`
   - `legacyFallbackInvocationError(...)`
  - `backend/internal/api/routes/routes.go`
   - `notificationService := services.NewNotificationService(db)`
- `backend/internal/notifications/router.go` is non-authoritative for PR1 runtime dispatch and must not be introduced into runtime flow for this unblock.

### Legacy Provider Migration Completeness (Notify-only Runtime)

1. Add a single reconciliation pass in `backend/internal/services/notification_service.go`:
  - target function: `EnsureNotifyOnlyProviderMigration(ctx context.Context) error`
  - invoked once from route boot path after `NewNotificationService(db)` wiring.
2. Reconcile each `notification_providers` row to terminal state:
  - Supported types (`webhook`, `discord`, `slack`, `gotify`, `generic`):
    - `engine="notify_v1"`, `migration_state="migrated"`, `migration_error=""`, `last_migrated_at=now`
  - Unsupported types under notify-only (for example `telegram`):
    - `migration_state="failed"`, `migration_error="unsupported provider type in notify-only runtime"`, `enabled=false`, `last_migrated_at=now`
  - Preserve prior origin URL in `legacy_url` when mutating ambiguous/legacy rows.
3. Keep fail-closed runtime semantics:
  - `SendExternal`/`TestProvider` reject unsupported providers without legacy fallback.
4. Migration completeness gate (must be zero):
  - enabled providers where `migration_state` is empty, `pending`, or `failed`.

### Ordered Remediation Tasks (Minimal, QA-first)

1. Update plan scope and precedence in `docs/plans/current_spec.md` (this addendum).
2. Lock runtime dispatch authority to direct notify-only logic in `backend/internal/services/notification_service.go`.
3. Add migration reconciliation pass in `backend/internal/services/notification_service.go` and call it from `backend/internal/api/routes/routes.go`.
4. Preserve server-managed migration fields behavior in `backend/internal/api/handlers/notification_provider_handler.go`.
5. Capture unblock evidence in `docs/reports/qa_report.md`.

### Test List (Execution Order)

1. `go test ./backend/internal/services -run 'TestNotificationService_SendExternal_NotifyOnlyBlocksLegacyFallback|TestSendExternal_UnsupportedProviderFailsClosed|TestTestProvider_NotifyOnlyRejectsUnsupportedProvider|TestTestProvider_DiscordUsesNotifyPathInPR1'`
2. `go test ./backend/internal/api/handlers -run 'TestNotificationProviderHandler_CreateIgnoresServerManagedMigrationFields|TestNotificationProviderHandler_UpdatePreservesServerManagedMigrationFields'`
3. Add/run migration completeness test:
  - `go test ./backend/internal/services -run 'TestNotificationService_EnsureNotifyOnlyProviderMigration'`
4. `npx playwright test tests/settings/notifications.spec.ts --project=firefox`
5. `bash scripts/local-patch-report.sh` (must emit `test-results/local-patch-report.md` and `test-results/local-patch-report.json`)

### Acceptance Criteria (PR1 Unblock)

1. `current_spec.md` clearly reflects Notify-only PR1 scope and excludes certificate flaky scope.
2. Exactly one backend dispatch source-of-truth is documented and used: direct hard-cutover in `NotificationService`.
3. Legacy provider migration reconciliation exists and is covered by targeted tests.
4. No enabled provider remains in non-terminal migration state under Notify-only runtime.
5. QA evidence is updated for Supervisor re-review.

## Fix Flaky Go Test: `TestCertificateHandler_List_WithCertificates`

### 1) Introduction

This specification defines a focused, low-risk plan to eliminate intermittent CI failures for:

- `backend/internal/api/handlers.TestCertificateHandler_List_WithCertificates`

while preserving production behavior in:

- `backend/internal/services/certificate_service.go`
- `backend/internal/api/handlers/certificate_handler.go`
- `backend/internal/api/routes/routes.go`

Primary objective:

- Remove nondeterministic startup concurrency in certificate service initialization that intermittently races with handler list calls under CI parallelism/race detection.

### Decision Record - 2026-02-18

**Decision:** For this targeted flaky-fix, `docs/plans/current_spec.md` is the temporary single source of truth instead of creating separate `requirements.md`, `design.md`, and `tasks.md` artifacts.

**Context:** The scope is intentionally narrow (single flaky test root-cause + deterministic validation loop), and splitting artifacts now would add process overhead without reducing delivery risk.

**Traceability mapping:**

- Requirements content is captured in Section 3 (EARS requirements).
- Design content is captured in Section 4 (technical specifications).
- Task breakdown and validation gates are captured in Section 5 (implementation plan).

**Review trigger:** If scope expands beyond the certificate flaky-fix boundary, restore full artifact split into `requirements.md`, `design.md`, and `tasks.md`.

---

### 2) Research Findings

#### 2.1 CI failure evidence

Observed in `.github/logs/ci_failure.log`:

- `WARNING: DATA RACE`
- failing test: `TestCertificateHandler_List_WithCertificates`
- conflicting access path:
  - **Write** from `(*CertificateService).SyncFromDisk` (`certificate_service.go`)
  - **Read** from `(*CertificateService).ListCertificates` (`certificate_service.go`), triggered via handler list path

#### 2.2 Existing architecture and hotspot map

**Service layer**

- File: `backend/internal/services/certificate_service.go`
- Key symbols:
  - `NewCertificateService(caddyDataDir string, db *gorm.DB) *CertificateService`
  - `SyncFromDisk() error`
  - `ListCertificates() ([]models.SSLCertificate, error)`
  - `InvalidateCache()`
  - `refreshCacheFromDB() error`

**Handler layer**

- File: `backend/internal/api/handlers/certificate_handler.go`
- Key symbols:
  - `func (h *CertificateHandler) List(c *gin.Context)`
  - `func (h *CertificateHandler) Upload(c *gin.Context)`
  - `func (h *CertificateHandler) Delete(c *gin.Context)`

**Route wiring**

- File: `backend/internal/api/routes/routes.go`
- Key symbol usage:
  - `services.NewCertificateService(caddyDataDir, db)`

**Tests and setup patterns**

- Files:
  - `backend/internal/api/handlers/certificate_handler_coverage_test.go`
  - `backend/internal/api/handlers/certificate_handler_test.go`
  - `backend/internal/api/handlers/certificate_handler_security_test.go`
  - `backend/internal/services/certificate_service_test.go`
  - `backend/internal/api/handlers/testdb.go`
- Findings:
  - many handler tests instantiate the real constructor directly.
  - one test already includes a timing workaround (`time.Sleep`) due to startup race behavior.
  - service tests already use a helper pattern that avoids constructor-side async startup, which validates the architectural direction for deterministic initialization in tests.

#### 2.3 Root cause summary

Two explicit root-cause branches are tracked for this flaky area:

- **Branch A — constructor startup race:** `NewCertificateService` starts async state mutation (`SyncFromDisk`) immediately, while handler-driven reads (`ListCertificates`) may execute concurrently. This matches CI race output in `.github/logs/ci_failure.log` for `TestCertificateHandler_List_WithCertificates`.
- **Branch B — DB schema/setup ordering drift in tests:** some test paths reach service queries before deterministic schema setup is complete, producing intermittent setup-order failures such as `no such table: ssl_certificates` and `no such table: proxy_hosts`.

Plan intent: address both branches together in one tight PR by making constructor behavior deterministic and enforcing migration/setup ordering in certificate handler test setup.

---

### 3) EARS Requirements (Source of Truth)

#### 3.1 Ubiquitous requirements

- THE SYSTEM SHALL construct `CertificateService` in a deterministic initialization state before first handler read in tests.
- THE SYSTEM SHALL provide race-free access to certificate cache state during list operations.

#### 3.2 Event-driven requirements

- WHEN `NewCertificateService` returns, THE SYSTEM SHALL guarantee that any required first-read synchronization state is consistent for immediate `ListCertificates` calls.
- WHEN `CertificateHandler.List` is called, THE SYSTEM SHALL return data or a deterministic error without concurrency side effects caused by service startup.
- WHEN certificate handler tests initialize database state, THE SYSTEM SHALL complete required schema setup for certificate-related tables before service/handler execution.

#### 3.3 Unwanted-behavior requirements

- IF CI executes tests with race detector or parallel scheduling, THEN THE SYSTEM SHALL NOT produce data races between service initialization and list reads.
- IF startup synchronization fails, THEN THE SYSTEM SHALL surface explicit errors and preserve handler-level HTTP error behavior.
- IF test setup ordering is incorrect, THEN THE SYSTEM SHALL fail fast in setup with explicit diagnostics instead of deferred `no such table` runtime query failures.

#### 3.4 Optional requirements

- WHERE test-only construction paths are needed, THE SYSTEM SHALL use explicit test helpers/options instead of sleeps or timing assumptions.

---

### 4) Technical Specifications

#### 4.1 Service design changes

Primary design target (preferred):

1. Update `NewCertificateService` to remove nondeterministic startup behavior at construction boundary.
2. Ensure `SyncFromDisk` / cache state transition is serialized relative to early `ListCertificates` usage.
3. Keep existing mutex discipline explicit and auditable (single writer, safe readers).
4. Enforce deterministic DB setup ordering in certificate handler tests through shared setup helper behavior (migrate/setup before constructor and request execution).

Design constraints:

- No public API break for callers in `routes.go`.
- No broad refactor of certificate business logic.
- Keep behavior compatible with current handler response contracts.

#### 4.2 Handler and route impact

- `certificate_handler.go` should require no contract changes.
- `routes.go` keeps existing construction call shape unless a minimally invasive constructor option path is required.

#### 4.3 Data flow (target state)

1. Route wiring constructs certificate service.
2. Service enters stable initialized state before first list read path.
3. Handler `List` requests certificate data.
4. Service reads synchronized cache/DB state.
5. Handler responds `200` with deterministic payload or explicit `500` error.

#### 4.4 Error handling matrix

| Scenario | Expected behavior | Validation |
|---|---|---|
| Startup sync succeeds | List path returns stable data | handler list tests pass repeatedly |
| Startup sync fails | Error bubbles predictably to handler | HTTP 500 tests remain deterministic |
| Empty store | 200 + empty list (or existing contract shape) | existing empty-list tests pass |
| Concurrent test execution | No race detector findings in certificate tests | `go test -race` targeted suite |
| Test DB setup ordering incomplete | setup fails immediately with explicit setup error; no deferred query-time table errors | dedicated setup-ordering test + repeated run threshold |

#### 4.5 API and schema impact

- API endpoints: **no external contract changes**.
- Request/response schema: **unchanged** for certificate list/upload/delete.
- Database schema: **no migrations required**.

---

### 5) Implementation Plan (Phased)

## Phase 1: Playwright / UI-UX Baseline (Gate)

Although this fix is backend-test focused, follow test protocol gate:

- Reuse healthy E2E environment when possible; rebuild only if runtime image inputs changed.
- Use exact task/suite gate:
  - task ID `shell: Test: E2E Playwright (FireFox) - Core: Certificates`
  - suite path executed by the task: `tests/core/certificates.spec.ts`
- If rebuild is required by test protocol, run task ID `shell: Docker: Rebuild E2E Environment` before Playwright.

Deliverables:

- passing targeted Playwright suite for certificate list interactions
- archived output in standard test artifacts

## Phase 2: Backend Service Stabilization

Scope:

- `backend/internal/services/certificate_service.go`

Tasks:

1. Make constructor initialization deterministic at first-use boundary.
2. Remove startup timing dependence that allows early `ListCertificates` to overlap with constructor-initiated sync mutation.
3. Preserve current cache invalidation and DB refresh semantics.
4. Keep lock lifecycle simple and reviewable.

Complexity: **Medium** (single component, concurrency-sensitive)

## Phase 3: Backend Test Hardening

Scope:

- `backend/internal/api/handlers/certificate_handler_coverage_test.go`
- `backend/internal/api/handlers/certificate_handler_test.go`
- `backend/internal/api/handlers/certificate_handler_security_test.go`
- optional shared test helpers:
  - `backend/internal/api/handlers/testdb.go`

Tasks:

1. Remove sleep-based or timing-dependent assumptions.
2. Standardize deterministic service setup helper for handler tests.
3. Ensure flaky case (`TestCertificateHandler_List_WithCertificates`) is fully deterministic.
4. Preserve assertion intent and API-level behavior checks.
5. Add explicit setup-ordering validation in tests to guarantee required schema migration/setup completes before handler/service invocation.

Complexity: **Medium** (many callsites, low logic risk)

## Phase 4: Integration & Validation

Tasks:

1. Run reproducible stability stress loop for the known flaky case via task ID `shell: Test: Backend Flaky - Certificate List Stability Loop`.
  - **Task command payload:**
    - `mkdir -p test-results/flaky && cd /projects/Charon && go test ./backend/internal/api/handlers -run '^TestCertificateHandler_List_WithCertificates$' -count=100 -shuffle=on -parallel=8 -json 2>&1 | tee test-results/flaky/cert-list-stability.jsonl`
  - **Artifactized logging requirement:** persist `test-results/flaky/cert-list-stability.jsonl` for reproducibility and CI comparison.
  - **Pass threshold:** `100/100` successful runs, zero failures.
2. Run race-mode stress for the same path via task ID `shell: Test: Backend Flaky - Certificate List Race Loop`.
  - **Task command payload:**
    - `mkdir -p test-results/flaky && cd /projects/Charon && go test -race ./backend/internal/api/handlers -run '^TestCertificateHandler_List_WithCertificates$' -count=30 -shuffle=on -parallel=8 -json 2>&1 | tee test-results/flaky/cert-list-race.jsonl`
  - **Artifactized logging requirement:** persist `test-results/flaky/cert-list-race.jsonl`.
  - **Pass threshold:** exit code `0` and zero `WARNING: DATA RACE` occurrences.
3. Run setup-ordering validation loop via task ID `shell: Test: Backend Flaky - Certificate DB Setup Ordering Loop`.
  - **Task command payload:**
    - `mkdir -p test-results/flaky && cd /projects/Charon && go test ./backend/internal/api/handlers -run '^TestCertificateHandler_DBSetupOrdering' -count=50 -shuffle=on -parallel=8 -json 2>&1 | tee test-results/flaky/cert-db-setup-ordering.jsonl`
  - **Pass threshold:** `50/50` successful runs and zero `no such table: ssl_certificates|proxy_hosts` messages from positive-path setup runs.
4. Run focused certificate handler regression suite via task ID `shell: Test: Backend Flaky - Certificate Handler Focused Regression`.
  - **Task command payload:**
    - `mkdir -p test-results/flaky && cd /projects/Charon && go test ./backend/internal/api/handlers -run '^TestCertificateHandler_' -count=1 -json 2>&1 | tee test-results/flaky/cert-handler-regression.jsonl`
  - **Pass threshold:** all selected tests pass in one clean run.
5. Execute patch-coverage preflight via existing project task ID `shell: Test: Local Patch Report`.
  - **Task command payload:** `bash scripts/local-patch-report.sh`
  - **Pass threshold:** both artifacts exist: `test-results/local-patch-report.md` and `test-results/local-patch-report.json`.

Task definition status for Phase 4 gates:

- Existing task ID in `.vscode/tasks.json`:
  - `shell: Test: Local Patch Report`
- New task IDs to add in `.vscode/tasks.json` with the exact command payloads above:
  - `shell: Test: Backend Flaky - Certificate List Stability Loop`
  - `shell: Test: Backend Flaky - Certificate List Race Loop`
  - `shell: Test: Backend Flaky - Certificate DB Setup Ordering Loop`
  - `shell: Test: Backend Flaky - Certificate Handler Focused Regression`

Complexity: **Low-Medium**

## Phase 5: Documentation & Operational Hygiene

Tasks:

1. Update `docs/plans/current_spec.md` (this file) if implementation details evolve.
2. Record final decision outcomes and any deferred cleanup tasks.
3. Defer unrelated repository config hygiene (`.gitignore`, `codecov.yml`, `.dockerignore`, `Dockerfile`) unless a direct causal link to this flaky test is proven during implementation.

Complexity: **Low**

---

### 6) PR Slicing Strategy

### Decision

**Primary decision: single PR** for this fix.

Why:

- Scope is tightly coupled (constructor semantics + related tests).
- Minimizes context switching and user review requests.
- Reduces risk of partially landed concurrency behavior.

### Trigger reasons to split into multiple PRs

Split only if one or more occur:

- Constructor change causes wider runtime behavior concerns requiring staged rollout.
- Test hardening touches many unrelated test modules beyond certificate handlers.
- Validation reveals additional root-cause branches outside certificate service/test setup ordering.

### Ordered fallback slices (if split is required)

#### PR-1: Service Determinism Core

Scope:

- `backend/internal/services/certificate_service.go`

Dependencies:

- none

Acceptance criteria:

- service constructor/list path no longer exhibits startup race in targeted race tests
- no public API break at route wiring callsite

Rollback/contingency:

- revert constructor change only; preserve tests unchanged for quick recovery

#### PR-2: Handler Test Determinism

Scope:

- `backend/internal/api/handlers/certificate_handler_coverage_test.go`
- `backend/internal/api/handlers/certificate_handler_test.go`
- `backend/internal/api/handlers/certificate_handler_security_test.go`
- optional helper consolidation in `backend/internal/api/handlers/testdb.go`

Dependencies:

- PR-1 merged (preferred)

Acceptance criteria:

- `TestCertificateHandler_List_WithCertificates` stable across repeated CI-style runs
- no `time.Sleep` timing guard required for constructor race avoidance

Rollback/contingency:

- revert only test refactor while keeping stable service change

---

### 7) Acceptance Criteria (Definition of Done)

1. Stability gate: task ID `shell: Test: Backend Flaky - Certificate List Stability Loop` passes `100/100`.
2. Race gate: task ID `shell: Test: Backend Flaky - Certificate List Race Loop` passes with zero race reports.
3. Setup-ordering gate: task ID `shell: Test: Backend Flaky - Certificate DB Setup Ordering Loop` passes `50/50`, with no `no such table: ssl_certificates|proxy_hosts` in positive-path setup runs.
4. Regression gate: task ID `shell: Test: Backend Flaky - Certificate Handler Focused Regression` passes.
5. Playwright baseline gate is completed via task ID `shell: Test: E2E Playwright (FireFox) - Core: Certificates` (suite: `tests/core/certificates.spec.ts`), with task ID `shell: Docker: Rebuild E2E Environment` run first only when rebuild criteria are met.
6. Patch coverage preflight task ID `shell: Test: Local Patch Report` generates `test-results/local-patch-report.md` and `test-results/local-patch-report.json`.
7. Scope gate: no changes to `.gitignore`, `codecov.yml`, `.dockerignore`, or `Dockerfile` unless directly required to fix this flaky test.
8. Reproducibility gate: stress-loop outputs are artifactized under `test-results/flaky/` and retained in PR evidence (`cert-list-stability.jsonl`, `cert-list-race.jsonl`, `cert-db-setup-ordering.jsonl`, `cert-handler-regression.jsonl`).
9. If any validation fails, failure evidence and explicit follow-up tasks are recorded before completion.

---

### 8) Risks and Mitigations

| Risk | Impact | Mitigation |
|---|---|---|
| Constructor behavior change impacts startup timing | medium | keep API stable; run targeted route/handler regression tests |
| Over-fixing spreads beyond certificate scope | medium | constrain edits to service + certificate tests only |
| DB setup-ordering fixes accidentally mask true migration problems | medium | fail fast during setup with explicit diagnostics and dedicated setup-ordering tests |
| Hidden race persists in adjacent tests | medium | run repeated/race-targeted suite; expand only if evidence requires |
| Out-of-scope config churn creates review noise | low | explicitly defer unrelated config hygiene from this PR |

---

### 9) Handoff

After this plan is approved:

1. Delegate execution to Supervisor/implementation agent with this spec as the source of truth.
2. Execute phases in order with validation gates between phases.
3. Keep PR scope narrow and deterministic; prefer single PR unless split triggers are hit.
  - Migration failures emit structured logs and increment migration-failure counters.
  - Legacy path execution attempts increment explicit counters and write warning/error logs.

## 10) Critical Risks and Mitigations

| Risk | Impact | Mitigation |
|---|---|---|
| Legacy provider records fail conversion under Notify-only runtime | Notification send failures for affected providers | Transactional migration, explicit `migration_state`/`migration_error`, actionable errors, focused migration tests |
| Hidden fallback assumptions still exist in tests/code | False confidence and production drift | Sentinel-based tests that fail on fallback invocation; remove fallback wiring |
| Rollout outage without fallback safety net | Increased short-term operational risk | Smaller PR slices, strict preflight E2E/tests/scans, fast revert procedure |
| UI/API contract mismatch during canonicalization | Broken settings UX | Canonical endpoint tests across backend/frontend/E2E |
| Silent regression in legacy-path blocking instrumentation | Fallback attempts occur without operational visibility, delaying incident response | Add explicit legacy-attempt counters/logs to DoD, dashboard alert thresholds, and validation step that asserts non-zero logging on injected fallback-attempt test path |

## 11) Handoff

After approval, delegate execution to the `Supervisor` agent with this file as the single active plan baseline.
  - Migration failures emit structured logs and increment migration-failure counters.
  - Legacy path execution attempts increment explicit counters and write warning/error logs.

## 10) Critical Risks and Mitigations

| Risk | Impact | Mitigation |
|---|---|---|
| Legacy provider records fail conversion under Notify-only runtime | Notification send failures for affected providers | Transactional migration, explicit `migration_state`/`migration_error`, actionable errors, focused migration tests |
| Hidden fallback assumptions still exist in tests/code | False confidence and production drift | Sentinel-based tests that fail on fallback invocation; remove fallback wiring |
| Rollout outage without fallback safety net | Increased short-term operational risk | Smaller PR slices, strict preflight E2E/tests/scans, fast revert procedure |
| UI/API contract mismatch during canonicalization | Broken settings UX | Canonical endpoint tests across backend/frontend/E2E |
| Silent regression in legacy-path blocking instrumentation | Fallback attempts occur without operational visibility, delaying incident response | Add explicit legacy-attempt counters/logs to DoD, dashboard alert thresholds, and validation step that asserts non-zero logging on injected fallback-attempt test path |

## 11) Handoff

After approval, delegate execution to the `Supervisor` agent with this file as the single active plan baseline.