fix(housekeeping): preserve audit reasons and completed effects

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

@@ -0,0 +1,45 @@
+# 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.