EpicNext-Cms/docs/superpowers/specs/2026-08-30-housekeeping-stepwise-rebuild-design.md

Housekeeping Stepwise Rebuild Design

Date: 2026-08-30 Status: Approved section by section in conversation; awaiting review of this written specification Delivery branch: codex/housekeeping-rebuild-stepwise Stable production surface: /admin Preview surface: /ase-next Final surface after a separately approved cutover: /ase

Purpose

Rebuild the EpicNext CMS Housekeeping as a complete, reliable operator product rather than a new shell around incomplete or generic pages. The rebuild covers routing, navigation, content, data presentation, filters, actions, permissions, feedback, error handling, accessibility, responsive behavior, tests, and operational usefulness.

Work proceeds in complete vertical slices. The existing /admin remains the stable administration surface until every retained workflow has a verified replacement and the final cutover receives explicit approval.

Relationship to the earlier Housekeeping work

The master domain architecture from 2026-08-24-housekeeping-modernization-design.md remains useful: one capability-adaptive Housekeeping, six functional domains, server-side authorization, real domain services, derived operational work, and an atomic final cutover.

This specification supersedes 2026-08-26-housekeeping-completion-design.md for delivery strategy, recovery policy, content quality, route verification, review gates, and cutover readiness. The implementation merged through PR #52 and subsequently reverted is not accepted as functional or visual evidence merely because it compiled or passed its former tests.

Reusable foundations and services from the reverted branch may be recovered only after focused review and regression tests. Its pages, generic content compositions, migration claims, and route cutover are not recovered wholesale.

Problem statement

The reverted implementation had two product-level failures:

1. Primary domain links such as /ase/people, /ase/content, /ase/economy, /ase/hotel, and /ase/system were generated by navigation but had no registered page handler. The dispatcher therefore called notFound() for every primary domain entry.
2. Passing parity and build checks did not demonstrate that operator-facing content was complete, useful, visually acceptable, or functionally equivalent to the working administration surface.

The deeper issue was verification by structure rather than by operator outcome. A route counted as migrated when it had a declared destination and handler, even if the menu could not reach it or its content did not deliver the former workflow at acceptable quality.

Approved product principles

1. Function before cutover. Nothing replaces a working legacy workflow until the replacement works independently.
2. Real content only. Pages use real data, real actions, and workflow-specific copy. Placeholder panels, decorative statistics, fake forms, and generic command forms do not count as delivery.
3. Improve wherever evidence supports it. Every workflow is reviewed for content, information hierarchy, filters, actions, feedback, performance, safety, and usability instead of being copied mechanically.
4. No useful-function loss. A legacy capability may be retained, improved, merged into a clearer workflow, or explicitly removed only when it is genuinely obsolete. Every decision records the old source and new destination.
5. Complete vertical slices. A domain is implemented and reviewed end to end before the next domain becomes the primary focus.
6. Stable production during construction. /admin remains available; the new work lives behind the non-production /ase-next preview.
7. Evidence over file counts. Completion is measured through navigability, real data, successful actions, authorization, audit, visual review, and workflow comparison.

Scope

The program covers the complete administration inventory represented by the existing migration matrix and the currently working /admin and /mod responsibilities. The functional domains remain:

1. Foundation, routing, access, and shared page behavior.
2. People, community, moderation, and support.
3. Content and engagement.
4. Economy and catalog.
5. Hotel and world operations.
6. System, access, and observability.
7. Operations workspace and cross-domain composition.
8. Final atomic cutover.

Public CMS and game-client redesign remain outside this program. Existing specialized engines are not rewritten solely for uniformity; they are integrated behind reliable page and service contracts.

Delivery architecture

Stable baseline

Development starts from the post-revert main, not from the reverted feature head. This preserves the functioning legacy administration surface and the known production rollback state.

All work is performed in the canonical checkout on codex/housekeeping-rebuild-stepwise. No Git worktrees are used.

Preview isolation

The rebuild is exposed at /ase-next only in approved development and test contexts. Production operators continue using /admin. The preview gate must default to closed, must not depend on client-side hiding, and must use the same authenticated capability source as the final product.

Selective recovery

Earlier code is classified before reuse:

• Recover: a focused foundation or service is behaviorally sound, has a clear boundary, and gains a regression test in the new branch.
• Rewrite: the responsibility is valid but its route, content, interaction, state model, or service boundary is inadequate.
• Replace with existing legacy service: the earlier implementation duplicated or weakened already reliable behavior.
• Discard: the code is placeholder-like, generic, unreachable, misleading, or unnecessary.

No bulk restoration of the reverted src/features/housekeeping tree and no mass cherry-pick of vertical commits is permitted. Recovery happens at the responsibility level.

Vertical delivery order

Phase 1: Foundation and routing

• Restore a gated /ase-next composition surface without changing /admin.
• Establish a registry contract connecting domains, concrete routes, handlers, capabilities, labels, and navigation.
• Make every primary domain entry resolve to a concrete accessible landing route.
• Add explicit unauthenticated, forbidden, missing, loading, empty, partial, conflict, and unexpected-error semantics.
• Establish workflow inventory and comparison evidence used by every later vertical.

Phase 2: People

• Users and linked accounts.
• Online users, communities, and guilds.
• Applications, staff, and teams.
• Moderation overview, actions, CFH, bans, IP, VPN, and word filtering.
• Tickets, help tickets, templates, and support workflows.

Phase 3: Content

• Articles, media, photos, banners, advertising, events, polls, help content, tags, prefixes, writable boxes, email content, branding, and localization.

Phase 4: Economy

• Catalog, items, Builder Club, maintenance, shop, marketplace, transactions, vouchers, subscriptions, rare values, badges, achievements, sounds, and calendar rewards.

Phase 5: Hotel

• Rooms, room furni, navigator content, radio, runtime asset operations, imports, and Studio tools.

Phase 6: System

• Permissions, access management, settings, emulator configuration, analytics, logs, DevOps, alerts, command center, and maintenance.

Phase 7: Operations

• Capability-derived operational home.
• Global navigation/entity search and safe commands.
• Derived inbox, recent work, favorites, mandatory summaries, and optional widgets.
• Cross-domain actions link to or invoke the owning domain without duplicating mutation logic.

Phase 8: Cutover

• Execute only after all vertical gates and final whole-product review pass.
• Requires explicit user approval separate from approval of any individual vertical.
• Publishes /ase, updates all internal administration links, and removes old route surfaces atomically.
• Retains a release-level rollback path and uses only backward-compatible data migrations before cutover.

Route and navigation contract

Concrete landing destinations

Every visible domain has at least one concrete accessible route with a registered handler. Navigation does not link to a manifest namespace that has no page.

For a capability context:

1. inaccessible routes are removed;
2. domains with no accessible routes are removed;
3. a domain rail link targets its declared accessible landing route;
4. a bare domain URL such as /ase-next/people redirects server-side to the same accessible landing route;
5. if no route is available, direct access returns a clear forbidden result rather than a fabricated missing-page result.

Operations may own the exact root /ase-next because it has a real root handler.

Registry invariants

Automated contracts reject:

• a navigation href that the route matcher cannot resolve;
• a matched route without a handler;
• a handler without a registered route;
• a domain without a valid landing destination;
• a domain displayed with zero accessible routes;
• duplicate domain, route, handler, command, provider, inbox, or widget IDs;
• invalid ownership or localization keys;
• links outside the preview/final canonical namespace;
• a retained migration row without a reachable implementation and functional evidence.

Response semantics

• Missing session: redirect to login.
• Authenticated operator without permission: render a dedicated 403 experience.
• Unknown route or entity: render a genuine 404 experience.
• Known route with unavailable dependency: preserve the shell and unaffected content, then render an actionable partial or dependency error.

Authorization remains server-enforced at query and mutation boundaries. Visible navigation never grants access.

Content and interaction standard

Operator questions

Every page must quickly answer:

1. What am I looking at?
2. What needs attention?
3. What can I do next?

Page content is designed around the operator's task rather than around the database schema or the desire to fill a dashboard grid.

Required content review

Each workflow receives a written audit covering:

• operator and purpose;
• legacy route and current behavior;
• data sources and freshness;
• useful information currently present;
• missing, duplicated, misleading, or low-value information;
• filters, sorting, pagination, and search requirements;
• safe and sensitive actions;
• validation, confirmation, reason, feedback, and undo/rollback behavior;
• authorization and audit requirements;
• empty, loading, partial, error, forbidden, and success states;
• desktop and mobile/tablet usability;
• performance risks and query boundaries;
• migration decision and canonical destination.

Shared structure without generic content

The foundation may provide semantic page regions, state primitives, confirmation patterns, tables, filters, pagination, and feedback components. It must not manufacture domain copy, fake metrics, generic form fields, or placeholder workflows.

Domain pages own their information hierarchy and use shared components only where behavior is genuinely common.

Copy quality

• Titles name the actual operator task.
• Descriptions clarify scope or consequences instead of repeating the title.
• Labels use domain language already understood by operators.
• Empty states distinguish no records from no filter matches and lack of access.
• Error messages explain the recoverable next action.
• Sensitive confirmations state the target, consequence, and required reason.
• Success messages confirm the resulting state, not merely that a button was clicked.

People vertical design

Users

The user list supports real search and useful filtering, including fields supported reliably by the live schema such as identity, rank, status, ban state, and activity. Columns prioritize operator decisions and remain configurable only where configuration adds value.

The user detail presents identity, current status, rank, currencies, activity, sanctions, linked-account evidence, badges, rooms, and relevant audit history through focused sections. It avoids a wall of unrelated cards. Permitted actions are contextual, capability-checked, confirmed according to risk, and followed by visible state refresh.

Linked accounts

Signals such as shared identifiers or network history are shown as evidence, not as automatic proof of wrongdoing. The UI explains why accounts are related, what data is unavailable, and which moderation actions remain independent decisions.

Community and staff

Online, guild, application, team, and staff views expose the data and actions necessary for their actual workflows. Application and team pages show state, relevant decision context, and permitted next actions instead of static summaries.

Moderation

The moderation overview is an operational entry point, not a decorative dashboard. CFH, ticket, ban, and action surfaces show priority, age, status, target context, evidence, and the next permitted action.

Ban, IP, VPN, word-filter, and moderation actions make actor, target, reason, duration, evidence, and outcome explicit. Forged or unauthorized mutations remain blocked by the server even when the UI hides them.

Support

Ticket and help-ticket queues provide operational filters and clear state. Detail pages keep conversation, user context, status, and response/closure actions together where practical. Templates assist the operator without silently replacing authored responses.

Data and service boundaries

• App Router files bind parameters and compose pages only.
• Domain query services produce page-specific read models and remain server-side.
• Domain commands accept validated typed input and return typed outcomes.
• Existing reliable legacy services are adapted rather than copied.
• Pages do not own SQL, transaction policy, capability rules, or audit serialization.
• Queries return only data the capability context permits.
• Mutations revalidate session, capability, target state, and input immediately before execution.
• Database mutation and audit evidence share one transaction whenever they use the same datastore boundary.
• External or file operations persist audit intent before execution and final outcome afterward when required by risk.
• Long-running operations expose progress and partial/failure outcomes rather than pretending to complete synchronously.

Error model

The stable error categories are:

• UNAUTHENTICATED;
• FORBIDDEN;
• VALIDATION;
• NOT_FOUND;
• CONFLICT;
• RATE_LIMITED;
• DEPENDENCY_UNAVAILABLE;
• TIMEOUT;
• INTERNAL.

Validation errors are attached to the relevant control. Conflicts explain that state changed and offer reload or comparison. Partial provider failure preserves successful content. Unexpected errors are sanitized for the operator, logged once, and correlated by an identifier safe to share with support.

Authorization and audit

• Effective ACL permissions, not hardcoded rank thresholds, authorize behavior.
• Rank is informative and may influence defaults only.
• Page loaders, queries, commands, and underlying mutation services enforce their own relevant boundaries.
• Sensitive operations require a reason when their workflow contract says so.
• Denied, failed, and partially completed sensitive attempts produce appropriate audit evidence.
• Audit payloads redact secrets and do not log unnecessary search terms or private result payloads.
• Capability loss invalidates stored shortcuts, favorites, and optional content on the next reconciliation.

Definition of done for a vertical

A vertical is complete only when all of the following are true:

1. Every legacy workflow in scope has a reviewed migration decision and canonical destination.
2. Every retained useful function is available or intentionally improved in the new vertical.
3. Every exposed page uses real data and real actions; no placeholder or generic workflow remains.
4. Navigation, direct URLs, route matching, handlers, and landing behavior are consistent.
5. Permission-allowed and permission-denied paths are tested at page, query, and command boundaries.
6. Loading, empty, partial, validation, conflict, dependency, forbidden, missing, success, and unexpected-error states are covered where applicable.
7. Sensitive operations have confirmation, reason, server validation, result feedback, and audit behavior appropriate to their risk.
8. Desktop and mobile/tablet layouts are visually inspected for every page and shared state.
9. The vertical passes targeted tests, cumulative Housekeeping tests, full project tests, typecheck, formatting/lint gates, and production build.
10. A functional comparison records what was retained, improved, merged, or removed and why.
11. The user reviews the vertical before work advances to the next primary domain.

Testing strategy

TDD cycle

Every behavioral change begins with a failing test that demonstrates the missing or broken operator outcome. The smallest implementation makes it pass, then the design is cleaned up while the test remains green.

Contract tests

• Registry and navigation reachability.
• Domain landing resolution for representative capability sets.
• Route-handler bijection.
• Capability filtering and direct-access denial semantics.
• Migration inventory destination reachability.
• Localization and source-boundary contracts.

Domain tests

• Query read models with representative, empty, partial, and failure data.
• Commands with allowed, denied, invalid, conflicting, failed, and successful outcomes.
• Transaction and audit behavior for sensitive mutations.
• Page rendering and interaction for the workflow's meaningful states.

Integration and smoke tests

• Authenticated preview entry and primary domain navigation.
• Every generated visible href returns the expected route instead of 404.
• Representative read and mutation flows for each capability profile.
• /admin remains functional throughout construction.
• /ase remains unavailable until final cutover.

Visual verification

Every page and shared state is reviewed at desktop and mobile/tablet widths using representative real or deterministic development data. Review covers hierarchy, density, wrapping, overflow, focus, keyboard navigation, actionable feedback, and whether the content helps the operator complete the task.

Screenshots and review notes are stored as vertical evidence. A page is not visually approved solely because it uses the shared theme tokens.

Branch and pull-request workflow

• All rebuild work remains on codex/housekeeping-rebuild-stepwise.
• A draft pull request targets main and is updated after each reviewed checkpoint.
• Commits remain responsibility-focused and preserve a readable red-green history where practical.
• The draft PR description records completed verticals, current gates, known limitations, and rollback posture.
• The PR is not marked ready and the cutover is not added merely because an individual vertical is green.
• The old reverted branch remains historical evidence; it is not force-updated or treated as the new delivery branch.

Cutover and rollback

The final cutover receives a dedicated review covering all routes, authenticated capability profiles, mutations, visual states, build output, CI, deployment, and live health.

Before merge:

• the full legacy inventory has no unresolved useful workflow;
• every generated administration link is reachable;
• /ase is tested as the final namespace;
• legacy removal is confined to the final cutover change;
• only additive, backward-compatible migrations are present;
• the previous application release can operate against the resulting schema.

After merge, success requires completed deployment plus a live /api/health response. Operator-facing smoke checks must cover the final domain landing routes. A green build alone is insufficient.

Rollback redeploys the last stable application release. Destructive schema cleanup is a later project and is not part of this cutover.

Success criteria

The rebuild is successful when:

• all retained administration responsibilities work through the new Housekeeping;
• every visible link and direct canonical route resolves correctly;
• each page contains useful, workflow-specific content and actions;
• no placeholder, generic imitation, or decorative-only operational page remains;
• authorization, validation, audit, errors, partial failure, and feedback behave consistently;
• the new experience is demonstrably better without losing useful legacy function;
• every vertical has functional and visual approval evidence;
• /admin remains stable until the explicitly approved atomic cutover;
• deployment, health, and final operator-route smoke checks pass after merge.