Plan Stage 5 web-channel source grouping

Author: rcarmo

docs/broad-filesystem-reorg-map-2026-03-28.md

@@ -359,6 +359,15 @@ Avoid indefinite dual-path support.
 - kept `.pi/extensions/`, `.pi/skills/`, and `.pi/agent/extensions/` stable as compatibility-sensitive convention paths
 - updated loader, build, vendor, docs, and test references to the grouped packaged-runtime layout
 
+### Stage 5 preparation update — 2026-03-28
+
+- refreshed the current `runtime/src/channels/web/` flat-root count to 73 files, so the older 56-file snapshot is no longer the planning baseline
+- captured the current grouping inventory in `docs/stage5-web-channel-grouping-inventory-2026-03-28.md`
+- prepared the execution order in `docs/stage5-web-channel-grouping-steplist-2026-03-28.md`
+- prepared an execution brief in `docs/stage5-web-channel-grouping-autoresearch-prompt-2026-03-28.md`
+- opened `workitems/20-doing/execute-stage5-web-channel-grouping.md` as the active next batch
+- current recommendation is to group the clearest semantic clusters first (`auth`, `sse`, `cards`, `media`, `theming`, `messaging`) rather than forcing the entire flat root into one move sweep
+
 ## First-batch recommendation
 
 If we start executing immediately, the best first batch is:

docs/stage5-web-channel-grouping-autoresearch-prompt-2026-03-28.md

@@ -0,0 +1,69 @@
+# Autoresearch prompt — Stage 5 web-channel source-tree grouping cleanup
+
+Use this as the execution brief for an autoresearch run working Stage 5 of the
+broad filesystem reorg.
+
+## Prompt
+
+Work the Stage 5 web-channel grouping batch from:
+
+- `workitems/20-doing/execute-stage5-web-channel-grouping.md`
+- `workitems/10-next/group-web-channel-flat-files.md`
+- `docs/stage5-web-channel-grouping-inventory-2026-03-28.md`
+- `docs/stage5-web-channel-grouping-steplist-2026-03-28.md`
+- `docs/broad-filesystem-reorg-map-2026-03-28.md`
+
+Your objective is to land a reviewable Stage 5 cleanup that:
+
+1. materially reduces the flat root under `runtime/src/channels/web/`
+2. moves the clearest semantic clusters first (`auth`, `sse`, `cards`, `media`, `theming`, `messaging`)
+3. keeps already-grouped subtrees (`http`, `handlers`, `workspace`, `terminal`, `vnc`, `remote-display`) structurally intact unless a specific move is necessary
+4. updates imports, tests, and docs consistently
+5. avoids behavior refactors beyond what path rewrites strictly require
+
+## Scope guardrails
+
+In scope:
+
+- file moves under `runtime/src/channels/web/`
+- import rewrites caused by those moves
+- matching test-path updates
+- docs/workitem path updates where needed
+
+Out of scope:
+
+- broad WebChannel behavior refactors
+- `runtime/generated/` work
+- extension/skill namespacing work
+- board/workitems path work
+- opportunistic logic rewrites inside moved services
+
+## Constraints
+
+- use `/workspace/piclaw` as the canonical repo
+- work from a clean branch based on `origin/main`
+- prefer the obvious grouping tranche first
+- stop and report if the remaining flat files require a second batch rather than forcing the whole root into one pass
+
+## Required validation order
+
+1. search for stale old web-channel paths/imports
+2. run directly affected focused tests
+3. run `bun run lint`
+4. run `bun run typecheck`
+5. run any import-boundary checks affected by the move
+
+## Expected outputs
+
+- obvious `web/` capability slices get dedicated subdirectories
+- imports/tests/docs are updated consistently
+- the flat root is materially smaller
+- Stage 5 ticket records what moved and what intentionally remained
+
+## Stop conditions
+
+Stop and report rather than widening scope if:
+
+- grouping starts to require behavior refactors rather than path rewrites
+- the remaining root files are too ambiguous for the same batch
+- validation failures indicate the work should be split into smaller child tranches

docs/stage5-web-channel-grouping-inventory-2026-03-28.md

@@ -0,0 +1,171 @@
+# Stage 5 web-channel grouping inventory — 2026-03-28
+
+## Purpose
+
+Capture the current `runtime/src/channels/web/` surface so Stage 5 of the broad
+filesystem reorg can work from current counts instead of the older 56-file
+snapshot.
+
+## Current structure
+
+Measured on 2026-03-28:
+
+- `runtime/src/channels/web/` — **73 flat files**
+- `runtime/src/channels/web/http/` — **21 files**
+- `runtime/src/channels/web/handlers/` — **5 files**
+- `runtime/src/channels/web/workspace/` — **9 files**
+- `runtime/src/channels/web/terminal/` — **1 file**
+- `runtime/src/channels/web/vnc/` — **1 file**
+- `runtime/src/channels/web/remote-display/` — **1 file**
+
+This means the existing `group-web-channel-flat-files` ticket is still valid,
+but its older 56-file number is stale.
+
+## Stable existing grouped areas
+
+Already-grouped subtrees that should remain conceptually separate from the flat
+root cleanup:
+
+- `http/`
+- `handlers/`
+- `workspace/`
+- `terminal/`
+- `vnc/`
+- `remote-display/`
+
+Stage 5 is primarily about shrinking the remaining flat root surface.
+
+## Candidate grouping clusters from the flat root
+
+### 1. `auth/`
+
+Likely auth-focused files:
+
+- `auth-endpoints.ts`
+- `auth-gateway.ts`
+- `auth-runtime.ts`
+- `auth.ts`
+- `login-command.ts`
+- `totp-auth.ts`
+- `webauthn-auth.ts`
+- `webauthn-enrol-page.ts`
+
+Why this cluster is attractive:
+
+- semantically cohesive
+- path intent is obvious
+- mostly pure import-rewrite risk
+
+### 2. `sse/`
+
+Likely SSE/event-stream files:
+
+- `sse.ts`
+- `sse-hub.ts`
+- `agent-events.ts`
+- `session-broadcast-service.ts`
+
+Why this cluster is attractive:
+
+- clear event-stream boundary
+- low ambiguity relative to other root files
+
+### 3. `cards/`
+
+Likely adaptive-card / interaction files:
+
+- `adaptive-card-actions.ts`
+- `adaptive-card-side-prompt-service.ts`
+- `interaction-service.ts`
+
+Why this cluster is attractive:
+
+- already reads like a focused capability slice
+- aligns with the broad reorg map’s earlier `cards/` direction
+
+### 4. `media/`
+
+Likely media/preview files:
+
+- `avatar-service.ts`
+- `link-previews.ts`
+- `media-service.ts`
+
+Why this cluster is attractive:
+
+- focused capability surface
+- low naming ambiguity
+
+### 5. `theming/`
+
+Likely theme/UI bridge files:
+
+- `ui-bridge.ts`
+- `ui-theme-commands.ts`
+- `ui-theme-data.ts`
+
+Why this cluster is attractive:
+
+- small, coherent grouping
+- clearly not part of auth/messaging/workspace
+
+### 6. `messaging/`
+
+Likely message-flow files:
+
+- `agent-message-entry-service.ts`
+- `agent-message-service.ts`
+- `agent-message-store.ts`
+- `message-store.ts`
+- `message-write-flows.ts`
+- `message-processing-storage-service.ts`
+- `peer-message-service.ts`
+
+Why this cluster is attractive:
+
+- high semantic cohesion
+- likely to pay off quickly in navigation clarity
+
+## High-ambiguity remainder after the obvious clusters
+
+After the clusters above, the remaining flat files are more mixed and likely
+need a second pass or narrower child batches. These likely include:
+
+- control-plane / session orchestration
+- follow-up / queue / special wrapper services
+- channel endpoint context helpers
+- request routing adjuncts that are not already under `http/`
+- runtime lifecycle glue that still belongs at the web root
+
+Stage 5 should assume the obvious clusters can land first without requiring the
+entire remainder to move in one shot.
+
+## Recommended Stage 5 posture
+
+### Safe first tranche
+
+Prefer moving these first:
+
+- `auth/`
+- `sse/`
+- `cards/`
+- `media/`
+- `theming/`
+- `messaging/`
+
+### Deliberate second tranche
+
+Re-evaluate the remaining root files after the first tranche lands, then decide
+whether additional directories are justified.
+
+## Success signal for Stage 5
+
+A good Stage 5 landing should materially reduce the flat root count and leave
+`runtime/src/channels/web/` easier to scan, even if the final root count is
+reached in more than one commit.
+
+## Related files
+
+- `docs/broad-filesystem-reorg-map-2026-03-28.md`
+- `workitems/10-next/group-web-channel-flat-files.md`
+- `workitems/20-doing/plan-broad-filesystem-reorg-from-audit.md`