EpicNext-Cms/docs/superpowers/plans/2026-09-05-housekeeping-backend-integrity.md

Housekeeping Backend Integrity Implementation Plan

For agentic workers: Use superpowers:executing-plans task-by-task. Keep checkpoints independently verifiable.

Goal: Complete the approved backend review, starting with reproducible audit and external-completion defects.

Architecture: Retain the six domain services and production adapters. Follow every operation from its public entrypoint through authorization, validation, storage, external effects and audit. Route coverage is not functional completion.

Tech Stack: TypeScript, Drizzle/MySQL, Vitest, Next.js, pnpm.

Spec: Backend scope approved in conversation on 2026-09-05: complete operations, permissions, validation, transactions, concurrency, audit and partial outcomes; preserve UI and production routing.

Global constraints

• Work in the canonical checkout on codex/housekeeping-rebuild-stepwise; no worktrees.
• Preserve untracked local files and existing administration routes.
• Keep PR 53 draft and update English and Dutch evidence after each verified push.
• No production writes or deployment. Missing local services block live acceptance, not implementation.

Task 1: Preserve reasons through service and production audit

Files: Content and Economy services/mutations.ts, services/mutations-production.ts; new src/features/housekeeping/backend-audit-integrity.test.ts.

Interfaces: optional normalized reason in mutation context; existing AuditEntry.reason at persistence.

• Exercise real service plus production adapter with captured audit writes. For database and external operations assert entry.reason === "Remove obsolete resource" from a whitespace-padded invocation.
• Run pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/backend-audit-integrity.test.ts; verify missing reason fails.
• Normalize once at the service boundary, conditionally include the reason in the adapter context, persist in every adapter audit outcome.
• Repeat focused tests, including absent reasons and audit-failure outcomes.

Task 2: Preserve completed Hotel external effects when audit fails

Files: Hotel services/mutations-production.ts and its existing test.

Interfaces: existing HotelMutationSnapshot.completion, with status: "partial", external: "completed", audit: "unavailable".

• Execute room.runtime with successful effect but failing success-audit writer; assert resolved snapshot with partial completion and no failure audit.
• Verify failure against current production adapter.
• Separate external-execution errors from completion-audit errors. Preserve intent-before-effect and original external failure semantics.
• Test failed intent prevents execution and failed failure-audit does not replace the original exception.
• Run focused suites, typecheck, scoped Biome, full suite and review the diff; commit exact paths and push with normal hooks.

Subsequent independently verified blocks

These are open audit scope, not completed tasks: Economy marketplace/voucher concurrency; operation-level parity and validation across Content, Economy, Hotel, People, System and Operations; all corresponding API and legacy entrypoints. Each block requires concrete findings, regression tests and its own implementation steps before changes. Do not mark the whole backend complete from Tasks 1-2.