Task 10 report: System vertical

Outcome

Delivered the real System access, configuration, observability, and operations vertical from base 0117b45d74450510187f8f860ee927a193c45a3c on codex/housekeeping-complete.

Registered the exact 17 System route IDs, canonical /ase/system/* hrefs, labels, and read capabilities from migration/system.ts.
Added injected access, configuration, observability, and operations queries with forbidden, partial, and dependency-unavailable results.
Extracted redirect-free, server-only, capability-guarded mutation services from the six legacy action modules while retaining their existing permission checks and /admin revalidation behavior.
Registered 29 sensitive System commands through deterministic bootstrap, dispatcher authorization, confirmation, rate limiting, and audit. Reasons are mandatory for ACL/permission changes, global settings, alert broadcast, every RCON operation, and maintenance/global availability.
Added four query-backed server workflow page modules with loading, empty, partial, error, forbidden, and ready states.
Added the exact 17 System handlers to the global aggregate. The manifest contains real routes and deliberately keeps providers, search, inbox, and widgets empty for Task 19.

No database operation, deployment, push, pull request update, Task 11 work, /admin or /mod cutover, rank-threshold authorization, or placeholder workflow was performed. .remember/remember.md remained untracked and untouched.

TDD evidence

All Vitest commands used --coverage.enabled=false so each RED/GREEN cycle exercised only the named boundary.

Phase	Exact command	RED	GREEN
Routes	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/domains/system/routes.test.ts`	1 file failed before tests: missing `./routes`.	1 file, 3 tests passed.
Injected queries	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/domains/system/queries/system-queries.test.ts`	1 file failed before tests: missing `./access`.	1 file, 6 tests passed.
Commands and guarded service	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/domains/system/commands/system-commands.test.ts`	1 file failed before tests: missing `../services/mutations`.	1 file, 6 tests passed at the first command boundary.
Legacy alert and maintenance wrappers	`pnpm exec vitest run --coverage.enabled=false src/actions/admin-alerts.test.ts src/actions/admin-maintenance.test.ts`	1 of 7 tests failed because the existing alert mock granted `notifications.edit` instead of the canonical `admin.notifications.edit`.	2 files, 7 tests passed after correcting only the stale mock permission.
ACL wrapper extraction	`pnpm exec vitest run --coverage.enabled=false src/lib/admin/acl-management-contract.test.ts`	1 of 2 tests failed before `access.permissions.update` was present.	1 file, 2 tests passed after the wrapper delegated to the guarded service.
Workflow pages	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/domains/system/pages/system-pages.test.tsx`	1 file failed before tests: missing `./access`.	1 file, 8 tests passed.
Handler/bootstrap integration	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/route-handlers.test.ts src/features/housekeeping/foundation/commands/bootstrap.test.ts`	2 tests failed: System had 0 handlers instead of 17 and no 29-command bootstrap registration.	2 files, 3 tests passed.
Review regressions	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/domains/system/commands/system-commands.test.ts src/features/housekeeping/domains/system/services/mutations-production.test.ts src/lib/admin/acl-management-contract.test.ts`	3 files failed; 11 tests failed and 6 passed. Failures proved missing alert reason, six whitespace-only inputs accepted, three alert dependency failures swallowed, and the public/non-strict production boundary.	3 files, 17 tests passed after the minimal corrections.

The first integrated target run passed 17 files and 179 tests. pnpm typecheck then exposed four integration-only type errors (a heterogeneous test tuple, a bigint alert identifier, and result-union narrowing); the corrected run passed. The first pnpm test:housekeeping exposed exactly three obsolete foundation assertions (40 files/372 tests otherwise passed). The three directly obsolete contracts were updated with strict positive System assertions without relaxing another domain; the focused rerun passed 2 files/38 tests and the then-current full suite passed 42 files/376 tests.

Final verification

pnpm exec vitest run --coverage.enabled=false src/actions/admin-alerts.test.ts src/actions/admin-maintenance.test.ts src/lib/admin/acl-management-contract.test.ts src/features/housekeeping/domains/system/routes.test.ts src/features/housekeeping/domains/system/queries/system-queries.test.ts src/features/housekeeping/domains/system/commands/system-commands.test.ts src/features/housekeeping/domains/system/services/mutations-production.test.ts src/features/housekeeping/domains/system/pages/system-pages.test.tsx src/features/housekeeping/migration/system.test.ts src/features/housekeeping/route-handlers.test.ts src/features/housekeeping/foundation/commands/bootstrap.test.ts src/features/housekeeping/foundation/commands/registry.test.ts src/features/housekeeping/foundation/commands/dispatcher.test.ts src/features/housekeeping/foundation/commands/confirmation.test.ts src/features/housekeeping/foundation/commands/audit-envelope.test.ts src/features/housekeeping/foundation/foundation-source-contract.test.ts src/features/housekeeping/foundation/registry.test.ts 17 files, 185 tests passed.
pnpm exec vitest run --coverage.enabled=false src/lib/admin-operations-contract.test.ts src/lib/staff-smoke-contract.test.ts src/lib/admin/authorization-contract.test.ts 3 files, 97 tests passed.
pnpm test:housekeeping 43 files, 385 tests passed.
pnpm typecheck passed (tsc --noEmit).
pnpm exec biome check --formatter-enabled=false src/actions/admin-alerts.test.ts src/actions/admin-alerts.ts src/actions/admin-emulator.ts src/actions/admin-maintenance.ts src/actions/admin-settings.ts src/actions/commandocentrum.ts src/actions/permissions.ts src/features/housekeeping/domains/system src/features/housekeeping/foundation/commands/bootstrap.test.ts src/features/housekeeping/foundation/commands/bootstrap.ts src/features/housekeeping/foundation/foundation-source-contract.test.ts src/features/housekeeping/foundation/registry.test.ts src/features/housekeeping/route-handlers.test.ts src/features/housekeeping/route-handlers.ts src/lib/admin/acl-management-contract.test.ts checked 32 files; no fixes applied.
git diff --check exit 0; only expected Git autocrlf warnings.
git diff --cached --check exit 0 before staging and rerun after exact staging.
Independent read-only re-review 0 Critical, 0 Important, 0 Minor; ready verdict.

Node/pnpm emitted this non-blocking warning during pnpm gates:

[WARN] Unsupported engine: wanted: {"node":">=26.8.1 <27"} (current: {"node":"v26.7.0","pnpm":"11.24.0"})

Architectural decisions

The migration matrix remains the single source of route truth. The System route array is materialized from its exact identifiers and values, and tests assert ordered route/handler equality rather than set-only coverage.
Query factories accept narrow adapters; production adapters reuse existing ACL, settings, emulator, health, online-user, analytics, log, alert, and maintenance services. The fix round added only a strict online-roster helper beside the unchanged tolerant legacy API in ops-online-users.ts, so System can report a database outage truthfully.
systemMutationService is the only public production mutation boundary. It is server-only and repeats capability enforcement even when called by an already-guarded legacy action or an authorized dispatcher. The unguarded production adapter is module-private.
Adapter exceptions and unsuccessful RCON sends become typed DEPENDENCY_UNAVAILABLE failures. Rank-delete conflict metadata travels in the standard fieldErrors shape; the legacy wrapper reconstructs the prior human-readable ActionError, keeping the dispatcher result schema strict.
Command string schemas use a non-transforming \S check to reject whitespace-only values; normalization and trimming remain at the guarded service boundary. This preserves the foundation registry rule that command schemas contain no executable transforms.
System navigation labels use stable pages.housekeeping.routes.system.* keys. Complete source strings are present in the tested English and Italian catalogs; repository fallback remains responsible for other locales.
Foundation source-boundary changes are a narrow source-to-import allowlist for the new System integration edges. Existing forbidden directions for every other domain remain asserted.

Changed files

.superpowers/sdd/2026-08-26-housekeeping-completion/task-10-report.md
src/actions/admin-alerts.test.ts
src/actions/admin-alerts.ts
src/actions/admin-emulator.ts
src/actions/admin-maintenance.ts
src/actions/admin-settings.ts
src/actions/commandocentrum.ts
src/actions/permissions.ts
src/features/housekeeping/domains/system/commands/system-commands.test.ts
src/features/housekeeping/domains/system/commands/system-commands.ts
src/features/housekeeping/domains/system/manifest.ts
src/features/housekeeping/domains/system/pages/access.tsx
src/features/housekeeping/domains/system/pages/configuration.tsx
src/features/housekeeping/domains/system/pages/observability.tsx
src/features/housekeeping/domains/system/pages/operations.tsx
src/features/housekeeping/domains/system/pages/system-pages.test.tsx
src/features/housekeeping/domains/system/queries/access.ts
src/features/housekeeping/domains/system/queries/configuration.ts
src/features/housekeeping/domains/system/queries/observability.ts
src/features/housekeeping/domains/system/queries/operations.ts
src/features/housekeeping/domains/system/queries/system-queries.test.ts
src/features/housekeeping/domains/system/route-handlers.ts
src/features/housekeeping/domains/system/routes.test.ts
src/features/housekeeping/domains/system/routes.ts
src/features/housekeeping/domains/system/services/mutations-production.test.ts
src/features/housekeeping/domains/system/services/mutations.ts
src/features/housekeeping/foundation/commands/bootstrap.test.ts
src/features/housekeeping/foundation/commands/bootstrap.ts
src/features/housekeeping/foundation/foundation-source-contract.test.ts
src/features/housekeeping/foundation/registry.test.ts
src/features/housekeeping/route-handlers.test.ts
src/features/housekeeping/route-handlers.ts
src/lib/admin/acl-management-contract.test.ts

Official review fix round 1

The official review was addressed on exact base 3788ecd9f1a4e32e68abac5ee2dae3418cdebfb2. The three parked Minor findings were deliberately left unchanged.

Findings resolved

Housekeeping label namespace: all 17 System routes used legacy pages.admin.* keys, which the Task 9 preview layout correctly rejected. Routes now use 17 stable pages.housekeeping.routes.system.* keys, EN/IT provide non-empty source strings, and a preview-contract test builds and translates the real System navigation without broadening layout validation.
Truthful partial/outage states: access, configuration, and observability previously rendered empty before considering failed dependencies. Partial now takes precedence whenever any dependency failed. System online-user queries use a strict helper that exposes database failure; the existing tolerant fetchOpsOnlineUsers API and legacy behavior remain intact.
Rank synchronization failures: create, delete, and update no longer report success when updatepermissions returns false, and set-rank no longer reports success when RCON committed but database persistence failed. Both paths return the existing strict DEPENDENCY_UNAVAILABLE envelope with stable message keys and explicit fieldErrors describing operation, completed, and pending effects. Dispatcher audit records intent then failure, never success.
Legacy permission error parity: known rank-in-use and role-not-found conflicts retain their established ActionError text. Unknown infrastructure failures now cross the real adminAction boundary as ordinary errors and are sanitized to Internal server error; internal Housekeeping message keys are not exposed to the legacy UI.

Fix-round TDD evidence

Cycle	Exact command	RED	GREEN
Labels and runtime navigation	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/domains/system/routes.test.ts src/features/housekeeping/foundation/localization-contract.test.ts src/features/housekeeping/foundation/preview-route-contract.test.ts`	3 files failed; 4 tests failed and 66 passed. The route labels mismatched, EN/IT lacked the routes subtree, and preview layout rejected `pages.admin.hubs.tabs.permissions`.	3 files, 70 tests passed.
Partial precedence and online-user outage	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/domains/system/pages/system-pages.test.tsx src/features/housekeeping/domains/system/queries/operations-production.test.ts`	2 files failed; 4 tests failed and 9 passed. Three pages rendered empty, and the production adapter resolved a false ready zero-user state on database failure.	2 files, 13 tests passed.
Rank synchronization	`pnpm exec vitest run --coverage.enabled=false src/features/housekeeping/domains/system/services/rank-mutations-production.test.ts`	1 file failed; 4 tests failed. Create/delete/update returned success after failed permission synchronization, and set-rank lacked explicit partial-completion metadata.	1 file, 4 tests passed. The first post-production run had 3 passed and 1 test-only audit expectation failure; aligning it with the established `intent` then `failure` envelope produced the final GREEN without a further production change.
Legacy permission parity	`pnpm exec vitest run --coverage.enabled=false src/actions/permissions.test.ts`	1 file failed; 1 test failed and 2 passed. The generic infrastructure case leaked `errors.housekeeping.dependencyUnavailable`; both known business conflicts already retained their prior text.	1 file, 3 tests passed.

The combined focused rerun passed 7 files and 90 tests. The first fix-round pnpm typecheck found two test-only narrowing errors in the new rank test; after the minimal annotations, its focused test remained green and tsc --noEmit passed.

Fix-round verification

Full affected Task 10 System, action, audit, authorization, bootstrap, localization, and preview suite: 22 files, 264 tests passed.
Legacy operations, staff smoke, and authorization suite: 3 files, 97 tests passed.
pnpm test:housekeeping: 45 files, 395 tests passed.
pnpm typecheck: passed (tsc --noEmit).
Exact changed-file pnpm exec biome check --formatter-enabled=false ...: checked 17 code, test, and locale files; no fixes applied after the one mechanical import-order correction.
UTF-8 source verification confirmed the Italian Analisi attività label contains U+00E0, followed by a 3-file/70-test route-localization-preview GREEN rerun.
git diff --check and the pre-stage git diff --cached --check: exit 0; only expected Git autocrlf warnings.
Independent read-only re-review: 0 Critical, 0 Important, 0 new Minor; all four official Important findings resolved, all three parked Minors unchanged, ready-to-merge verdict.

Fix-round changed files

.superpowers/sdd/2026-08-26-housekeeping-completion/task-10-report.md
src/actions/permissions.test.ts
src/actions/permissions.ts
src/features/housekeeping/domains/system/pages/access.tsx
src/features/housekeeping/domains/system/pages/configuration.tsx
src/features/housekeeping/domains/system/pages/observability.tsx
src/features/housekeeping/domains/system/pages/system-pages.test.tsx
src/features/housekeeping/domains/system/queries/operations-production.test.ts
src/features/housekeeping/domains/system/queries/operations.ts
src/features/housekeeping/domains/system/routes.test.ts
src/features/housekeeping/domains/system/routes.ts
src/features/housekeeping/domains/system/services/mutations.ts
src/features/housekeeping/domains/system/services/rank-mutations-production.test.ts
src/features/housekeeping/foundation/localization-contract.test.ts
src/features/housekeeping/foundation/preview-route-contract.test.ts
src/lib/admin/ops-online-users.ts
src/messages/en.json
src/messages/it.json

17 KiB Raw Blame History