# 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.

**Delivery status:** Tasks 1 and 2 were implemented and verified in `555bc75f`. Commerce locking followed in `4b88c695`, voucher reservation in `8e54cdbc`, and legacy room convergence in `184052fb` / `d0190bc1`. The remaining complete-product work is tracked in `2026-09-05-housekeeping-functional-parity.md`; these checkpoints do not mean backend or UI completion.

**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.