docs(plan): refine hypermedia migration plan to 5-phase structure with shift-left tooling and AGENTS.md legacy quarantine

docs(plan): add hypermedia architecture migration plan

migration from the legacy `server/` and `ui/` directories to a domain-oriented vertical slice architecture under `src/features/`. The plan spans four phases: Core Foundation, Base Slices, Real-Time Slices, and Architectural Testing.

AGENTS.md

@@ -117,10 +117,14 @@ Management (IAM) fabric and WebAuthn Passkey authority.
      explicit, searchable domain names (`SessionPinRotator`,
      `streamGuestDrawerTelemetry`, `SessionHandoffCard`).
 5. **Deterministic Tooling Enforcement:**
-   - All code quality standards must be enforced by automated tooling
-     (`deno
-     fmt`, `deno task lint`, `deno task check`, `deno test`). Agents
-     must verify passing gates before completing tasks.
+   - All code quality and architectural standards must be enforced by automated
+     tooling (`deno fmt`, `deno task lint`, `deno task check`, `deno test`).
+     Architectural linters run as part of `deno task lint` to catch banned DOM
+     APIs or missing `data-ignore` attributes immediately.
+6. **Legacy Code Quarantine:**
+   - During migration phases, legacy `server/` and `ui/` directories are
+     strictly read-only reference. All new code, routes, queries, and fragments
+     must be authored exclusively in `src/`.
 
 ## 6. History & Context Link
 

tasks/new/2026-0827.07.jul.plan.arch.hypermedia-and-vertical-slicing-1715.md

@@ -0,0 +1,116 @@
+# TASK METADATA
+
+- **Target Files:** `src/core/`, `src/features/`, `src/shared/`,
+  `src/tests/arch/`, `server/` (legacy), `ui/` (legacy). Note: `sdk/` and
+  `spire_ffi/` must remain independent top-level root modules.
+- **Core Objective:** Execute a multi-phase, non-overlapping architectural
+  transition to a Datastar-driven Hypermedia paradigm and Vertical Feature
+  Slicing.
+- **Dependencies:** `docs/HYPERMEDIA_ARCHITECTURE_BLUEPRINT.md`, `AGENTS.md`.
+- **Additional Important Notes:** The code does not need to maintain
+  backwards-compatible bridges for legacy vanilla scripts during intermediate
+  phases; optimize for a clean, uncompromised vertical slice architecture in
+  `src/`.
+
+---
+
+## Architectural Considerations & Risks
+
+- **Risks:**
+  - Moving from a separated `server/` and `ui/` structure to co-located
+    `src/features/` will require extensive routing and import refactoring.
+  - Dropping legacy imperative DOM scripts in favor of Datastar requires strict
+    adherence to `data-ignore` for WebAuthn micro-scripts so the DOM diffing
+    engine doesn't wipe critical ceremony state.
+  - Converting SSE streams to the typed adapter (`core/sse_adapter.ts`) might
+    break existing real-time UI components if payload formats are mismatched.
+- **Alternatives:**
+  - Instead of moving to `src/`, we could restructure within `server/`. However,
+    adopting `src/features/` enforces a clean break from the legacy horizontally
+    sliced architecture and clearly demarcates the new vertical hypermedia
+    standard.
+
+## Proposed Implementation
+
+### Phase 1: Core Foundation, Tooling & Safety Guards
+
+Establish the authoritative infrastructure, transport toolkit, and invariant
+guards inside `src/core/`.
+
+1. Create `src/core/` directory.
+2. Migrate and adapt foundational integrations from `server/` (strictly
+   read-only reference):
+   - `db.ts`: PostgreSQL connection pool and queries.
+   - `valkey.ts`: Valkey connection and Pub/Sub broker.
+   - `spire_ffi.ts`: Rust SPIFFE/mTLS FFI bindings.
+3. Implement `auth_guards.ts` (enforcing max 16KB payload cap, rate limiting,
+   and CSRF/Origin checks).
+4. Implement `content_negotiation.ts` to route between Datastar HTML, CLI/JSON
+   clients, and shell strings.
+5. Implement `sse_adapter.ts` for typed Datastar SSE streaming helper logic.
+6. Implement `error_fragments.tsx` for standardized error toast and field-error
+   JSX morph fragments.
+7. Setup `src/main.ts` with `serveStatic` for `/public/datastar-v1.x.js`.
+8. Add `deno task lint:arch` in `scripts/lint_arch.ts` (blocking
+   `document.getElementById` and unescaped HTML) and integrate into `deno.json`.
+
+### Phase 2: Base Vertical Slices & Shared UI
+
+Migrate domain-agnostic presentation atoms and standard CRUD-style feature
+slices.
+
+1. Create `src/shared/ui/` with distinctive fragment names (`LayoutFragment`,
+   `NavbarFragment`, `ToastFragment`, `DrawerShellFragment`,
+   `PillGroupFragment`, `AccordionFragment`).
+2. Create `src/features/auth/` and migrate `/login`, `/register`, and
+   `/recovery`. Extract WebAuthn ceremony scripts into `webauthn.ts` with
+   explicit `data-ignore` attributes.
+3. Create `src/features/admin/` and migrate admin routes, SQL queries, and
+   fragments (`AdminUserTableFragment`, `AdminAppCardFragment`,
+   `RoleModalFragment`).
+4. Add pure JSX unit tests: `auth.test.ts` and `admin.test.ts`.
+
+### Phase 3: Real-Time Slices & Script Elimination
+
+Migrate complex, interactive features and eliminate legacy imperative scripts in
+favor of targeted SSE and Datastar morphs.
+
+1. Create `src/features/events/`:
+   - Migrate event routing, queries, and JSX fragments
+     (`EventCockpitDeckFragment`, `WorkshopPassDrawerFragment`,
+     `GuestDrawerAttendeesFragment`).
+   - Implement `stream.ts` using `src/core/sse_adapter.ts` for live seat
+     counters bound to Valkey Pub/Sub.
+2. Create `src/features/sessions/`:
+   - Migrate routing, queries, and fragments (`SessionTableFragment`,
+     `SessionHandoffCardFragment`, `DirectPassDrawerFragment`).
+   - Eliminate legacy `SessionsScript.tsx` completely, replacing interactive
+     flows with Datastar reactive attributes (`data-on-click`, `data-patch`).
+3. Add pure JSX unit tests: `events.test.ts` and `sessions.test.ts`.
+
+### Phase 4: Persistent Architectural Test Suite
+
+Implement the invariant test harness defined in the blueprint to prevent
+regression.
+
+1. Create `src/tests/arch/`.
+2. Implement `transport_efficiency.test.ts` (asserts routine mutations return
+   `text/html` in <2ms).
+3. Implement `sse_lifecycle.test.ts` (asserts connection limits, draining, and
+   memory stability for 100+ concurrent live listeners).
+4. Implement `proxy_buffering.test.ts` (asserts `X-Accel-Buffering: no` is
+   emitted).
+5. Implement `error_fragment.test.ts` (asserts 4xx/5xx responses yield valid JSX
+   morph fragments for `#status-banner`).
+6. Implement `content_negotiation.test.ts` (asserts proper dual-mode REST vs
+   Datastar handling) and `xss_fuzzing.test.ts` (fuzzes fragment rendering).
+
+### Phase 5: Legacy Deprecation & Final Cleanup
+
+Execute cleanup only after Phase 4 architectural tests and existing test suites
+pass 100%.
+
+1. Safely delete legacy `server/` and `ui/` directories.
+2. Perform dead-code cleanup and dependency verification.
+3. Verify all gates: `deno fmt`, `deno task lint`, `deno task check`, and
+   `deno test -A --no-check`.