@rubytech/create-maxy-code 0.1.478 → 0.1.479

package/payload/platform/docs/superpowers/plans/2026-07-20-task-1818-loop-gate-app-routes.md

@@ -0,0 +1,462 @@
+# Task 1818 — Widen the loop gate to all of `app/**` — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `scripts/check-loops-registered.mjs` scans the whole of `app/**` rather than only `app/lib/**`, so a standing server loop armed anywhere under `app/` fails the build instead of running invisibly.
+
+**Architecture:** One line changes behaviour — `SCAN_ROOTS` becomes `['server', 'app']`. That widening immediately fails the real tree on fifteen pre-existing browser timers, so the fifteen `// loop-exempt:client` markers must land in the same commit or `npm run prebuild` is broken between commits. The gate's SCOPE header currently asserts the opposite boundary and moves with the behaviour.
+
+**Tech Stack:** Node ESM script (no dependencies), vitest, TypeScript/TSX source under `platform/ui`.
+
+**Design doc:** `platform/docs/superpowers/specs/2026-07-20-task-1818-loop-gate-app-routes-design.md`
+
+## Global Constraints
+
+- All paths below are relative to `platform/ui/` inside the `maxy-code/` tree.
+- The marker convention and the closed category set are settled by Task 1814 and must not change. Valid categories are exactly `per-connection`, `demand-singleton`, `client`, `registry-primitive`.
+- Marker form is `// loop-exempt:<category> <reason>` appended to the physical line containing `setInterval(`. For a multi-line arrow body the comment goes after the opening brace, following the established form at `server/routes/public-reader.ts:257`.
+- A reason must contain at least three consecutive letters (`REASON = /[A-Za-z]{3}/`) and must state something true and specific about that timer. Repeated boilerplate across the fifteen sites is a plan failure.
+- The gate parses nothing. Do not add comment-stripping, string-awareness, or any TypeScript parsing — that is what killed its first version.
+- Do not add a `registerLoop` call. The census found no standing loop in the newly covered area; adding one would be inventing a requirement.
+- Every commit carries `Session: aad2dcb4-bc6c-4502-9ef9-e75995fb974b` and `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
+
+**Baseline, measured before any change:**
+
+```
+[check-loops-registered] ok files=284 sites=10 marked=9 allowlisted=1 (per-connection=6 demand-singleton=1 client=1 registry-primitive=1)
+```
+
+**Predicted after:** `files=393 sites=25 marked=24 allowlisted=1 (per-connection=6 demand-singleton=1 client=16 registry-primitive=1)`
+
+---
+
+## File Structure
+
+| File | Responsibility | Change |
+|---|---|---|
+| `scripts/check-loops-registered.mjs` | The gate. Walks scan roots, matches raw lines, validates markers. | Modify: `SCAN_ROOTS` constant + SCOPE header block |
+| `scripts/__tests__/check-loops-registered.test.ts` | Committed behaviour suite for the gate. | Modify: one existing case; add two; raise real-tree floors |
+| 11 source files under `app/` outside `app/lib/` | Browser components and hooks that arm timers. | Modify: append a marker comment to 15 lines |
+
+---
+
+### Task 1: Move the test surface to the new boundary
+
+The existing suite contains a case that **encodes the hole this task closes**. It proves "files outside the two scan roots are ignored" using `app/chat/page.tsx` — a file that becomes in-scope. Left alone it would fail; edited carelessly it would silently stop testing anything. It must be re-pointed at a path that is genuinely outside both roots.
+
+**Files:**
+- Modify: `scripts/__tests__/check-loops-registered.test.ts:87-91` (the mis-pointed case)
+- Modify: `scripts/__tests__/check-loops-registered.test.ts` (add two cases after line 91)
+
+**Interfaces:**
+- Consumes: `runGate(files: Record<string, string>): { code: number; out: string }` — the existing helper at line 25. It writes the given files into a temp dir and runs the gate with `--root <dir>`, returning exit code and combined stdout+stderr.
+- Produces: nothing consumed by later tasks.
+
+- [ ] **Step 1: Re-point the mis-pointed case and add the two new ones**
+
+Replace lines 87–91 of `scripts/__tests__/check-loops-registered.test.ts`:
+
+```typescript
+  it('ignores files outside the two scan roots', () => {
+    const r = runGate({ 'app/chat/page.tsx': 'setInterval(f, 1)\n' })
+    expect(r.code).toBe(0)
+    expect(r.out).toContain('sites=0')
+  })
+```
+
+with:
+
+```typescript
+  // Task 1818 re-pointed this case. It previously proved the point with
+  // `app/chat/page.tsx`, which is now IN scope — the precise hole 1818 closes.
+  // `scripts/` is outside both roots and is where the gate itself lives, so it
+  // is a stable choice that will not quietly migrate in-scope later.
+  it('ignores files outside the scan roots', () => {
+    const r = runGate({ 'scripts/some-tool.mjs': 'setInterval(f, 1)\n' })
+    expect(r.code).toBe(0)
+    expect(r.out).toContain('sites=0')
+  })
+
+  // Task 1818 — the gap 1814 left. A standing loop armed in a component or
+  // route file under `app/` but outside `app/lib/` was invisible to the gate.
+  it('fails on an unmarked setInterval under app/ outside app/lib', () => {
+    const r = runGate({ 'app/chat/page.tsx': 'setInterval(() => poll(), 1000)\n' })
+    expect(r.code).toBe(1)
+    expect(r.out).toContain('app/chat/page.tsx')
+  })
+
+  it('passes a marked client site under app/ outside app/lib', () => {
+    const r = runGate({
+      'app/Sidebar.tsx':
+        'const t = setInterval(poll, 5000) // loop-exempt:client sidebar poll in the browser\n',
+    })
+    expect(r.code).toBe(0)
+    expect(r.out).toContain('sites=1')
+    expect(r.out).toContain('client=1')
+  })
+```
+
+- [ ] **Step 2: Run the suite to verify the two new cases fail**
+
+```bash
+cd maxy-code/platform/ui && npx vitest run scripts/__tests__/check-loops-registered.test.ts
+```
+
+Expected: the re-pointed `ignores files outside the scan roots` PASSES (`scripts/` is outside both roots today and after). `fails on an unmarked setInterval under app/ outside app/lib` FAILS — the gate exits 0 because `app/chat/page.tsx` is not scanned. `passes a marked client site under app/ outside app/lib` FAILS on `expect(r.out).toContain('sites=1')`, receiving `sites=0` for the same reason.
+
+Two failures is the RED state. If either new case passes here, the scan root was already wider than the baseline and the premise of this task needs re-checking before continuing.
+
+- [ ] **Step 3: Commit the red tests**
+
+```bash
+git add maxy-code/platform/ui/scripts/__tests__/check-loops-registered.test.ts
+git commit -m "test: assert the loop gate covers app/ outside app/lib (red)
+
+Re-points the case that proved the hole using app/chat/page.tsx, which this
+task brings in scope, and adds the two cases 1818 requires.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
+Session: aad2dcb4-bc6c-4502-9ef9-e75995fb974b"
+```
+
+---
+
+### Task 2: Widen the scan root and mark the fifteen browser timers
+
+These land together. Widening alone fails the real tree on fifteen unmarked sites, which breaks `npm run prebuild` for every other sprint in the repo until the markers land.
+
+**Files:**
+- Modify: `scripts/check-loops-registered.mjs:53-60` (SCOPE header), `scripts/check-loops-registered.mjs:74-75` (`SCAN_ROOTS`)
+- Modify: `app/AdminShell.tsx:228`, `app/Sidebar.tsx:512,534,1609`, `app/activity/page.tsx:428`, `app/chat/page.tsx:700,721`, `app/chat/transcript-render.tsx:80`, `app/graph/page.tsx:1456`, `app/graph/settle-lock.ts:137`, `app/hooks/useViewMode.ts:110`, `app/hooks/useVoiceRecorder.ts:142`, `app/useAdminAuth.ts:219`, `app/useElapsedTimer.ts:29,35`
+
+**Interfaces:**
+- Consumes: nothing from Task 1.
+- Produces: the gate's counter line, whose exact predicted value Task 3 asserts.
+
+- [ ] **Step 1: Widen `SCAN_ROOTS`**
+
+Replace lines 74–75 of `scripts/check-loops-registered.mjs`:
+
+```javascript
+/** The two trees that contain server-side code. */
+const SCAN_ROOTS = ['server', 'app/lib']
+```
+
+with:
+
+```javascript
+/** `app/lib` is deliberately NOT listed alongside `app` — it is a subtree of
+ *  it, and naming both would walk it twice, doubling its contribution to the
+ *  counts printed below. Those counts are the evidence that the scan actually
+ *  read the tree, so inflating them defeats their purpose. */
+const SCAN_ROOTS = ['server', 'app']
+```
+
+- [ ] **Step 2: Rewrite the SCOPE header block**
+
+Replace lines 53–60 of `scripts/check-loops-registered.mjs`:
+
+```javascript
+// SCOPE — exact, because a gate believed to cover more than it does is worse
+// than none.
+//
+// Covers `server/**` and `app/lib/**`, excluding `__tests__`. Every standing
+// server loop in the tree lives in one of those two, including all four gateway
+// sweeps. NOT covered: the rest of `app/**`, which is Next.js route and
+// component code running in the visitor's browser, and test files, which are
+// not production loops.
+```
+
+with:
+
+```javascript
+// SCOPE — exact, because a gate believed to cover more than it does is worse
+// than none.
+//
+// Covers `server/**` and `app/**`, excluding `__tests__`. Not covered: test
+// files, which are not production loops, and everything outside those two
+// trees (`scripts/`, `e2e/`, config), which does not run in the server process.
+//
+// Task 1818 widened the second root from `app/lib` to all of `app`. 1814 had
+// scanned `app/lib` only, on a census showing every standing server loop lived
+// there. That was true and is not the point: the gate's job is what could be
+// added, not what is present. Two findings made the narrower root indefensible.
+//
+//   1. There is no route-file surface to enumerate instead. This package is a
+//      Vite SPA (ten HTML entries) plus a Hono server bundled from exactly two
+//      entries, `server/index.ts` and `server/edge.ts`. There is no Next.js and
+//      no `app/api/`, so "scan the server-executing subtrees of app/" has no
+//      subtree to name, and any list would be a list again — the property 1814
+//      removed.
+//   2. Server-reachable code outside `app/lib/` already exists.
+//      `server/routes/whatsapp-reader.ts` imports SUPPORTED_MIME_SET,
+//      MAX_FILE_BYTES and MAX_ATTACHMENTS — runtime values, not types — from
+//      `app/admin-types.ts`. It arms no timer, so nothing was hidden, but the
+//      boundary "server code stops at app/lib" was already false.
+//
+// `'use client'` is not the discriminator and cannot become one: three of the
+// eleven files under `app/` that arm a browser timer carry no such directive
+// (`chat/page.tsx`, `chat/transcript-render.tsx`, `graph/settle-lock.ts`).
+```
+
+- [ ] **Step 3: Mark all fifteen sites**
+
+Append to the end of each listed line, exactly as given. Each reason states what that specific timer does; do not substitute a shared phrase.
+
+`app/AdminShell.tsx:228`
+```typescript
+    const id = setInterval(read, 60000) // loop-exempt:client polls /api/health for the Claude auth badge in the admin shell, browser-side
+```
+
+`app/Sidebar.tsx:512`
+```typescript
+    timer = setInterval(() => { void fetchChannelConvos() }, CHANNEL_CONVO_POLL_MS) // loop-exempt:client refreshes the sidebar's channel conversation list in the browser
+```
+
+`app/Sidebar.tsx:534`
+```typescript
+      timer = setInterval(tick, SESSIONS_POLL_MS) // loop-exempt:client refreshes the sidebar's session list in the browser
+```
+
+`app/Sidebar.tsx:1609`
+```typescript
+      timer = setInterval(() => { void poll() }, SYSTEM_STATS_POLL_MS) // loop-exempt:client refreshes the sidebar's system-stats readout in the browser
+```
+
+`app/activity/page.tsx:428`
+```typescript
+    const t = setInterval(() => void load(range), 15_000) // loop-exempt:client reloads the /activity table in the browser; the loops it displays are the registered ones
+```
+
+`app/chat/page.tsx:700`
+```typescript
+    const interval = setInterval(() => { void fetchPointer() }, POINTER_POLL_MS) // loop-exempt:client polls the transcript pointer for the open chat tab
+```
+
+`app/chat/page.tsx:721`
+```typescript
+    const id = setInterval(read, 60000) // loop-exempt:client polls /api/health for the Claude auth badge on the chat page, browser-side
+```
+
+`app/chat/transcript-render.tsx:80`
+```typescript
+    const id = setInterval(() => setNow(Date.now()), 1000) // loop-exempt:client one-second render clock advancing relative timestamps in the transcript
+```
+
+`app/graph/page.tsx:1456`
+```typescript
+    const intervalId = window.setInterval(poll, POLL_MS) // loop-exempt:client polls graph layout progress in the browser; window-scoped by construction
+```
+
+`app/graph/settle-lock.ts:137`
+```typescript
+  timer = setInterval(() => { // loop-exempt:client samples vis-network node positions to freeze canvas physics once the layout is still
+```
+
+`app/hooks/useViewMode.ts:110`
+```typescript
+    pollInterval.current = setInterval(() => { // loop-exempt:client watches whether the popout window was closed, so the parent tab can restore its own view
+```
+
+`app/hooks/useVoiceRecorder.ts:142`
+```typescript
+    timerRef.current = setInterval(() => { // loop-exempt:client advances the recording elapsed-time display while the mic is open
+```
+
+`app/useAdminAuth.ts:219`
+```typescript
+    const interval = setInterval(async () => { // loop-exempt:client polls /api/health to keep the browser's auth signal current while a chat is open
+```
+
+`app/useElapsedTimer.ts:29`
+```typescript
+    sessionTickRef.current = setInterval(() => { // loop-exempt:client advances the per-session turn clock rendered in the browser
+```
+
+`app/useElapsedTimer.ts:35`
+```typescript
+    elapsedRef.current = setInterval(() => { // loop-exempt:client advances the elapsed-seconds counter rendered in the browser
+```
+
+- [ ] **Step 4: Run the gate against the real tree**
+
+```bash
+cd maxy-code/platform/ui && node scripts/check-loops-registered.mjs
+```
+
+Expected, exactly:
+
+```
+[check-loops-registered] ok files=393 sites=25 marked=24 allowlisted=1 (per-connection=6 demand-singleton=1 client=16 registry-primitive=1)
+```
+
+If it exits 1, a marker is missing or malformed — the error names the file and line. If it exits 0 but `files=` is not 393, the walk is not reading what this plan predicts; stop and re-census rather than adjusting the expected number to match.
+
+- [ ] **Step 5: Run the gate's suite**
+
+```bash
+cd maxy-code/platform/ui && npx vitest run scripts/__tests__/check-loops-registered.test.ts
+```
+
+Expected: all cases pass, including Task 1's two, which were red.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add maxy-code/platform/ui/scripts/check-loops-registered.mjs \
+        maxy-code/platform/ui/app
+git commit -m "feat: scan all of app/ in the loop gate, not just app/lib
+
+Widens SCAN_ROOTS to ['server', 'app'] and marks the fifteen pre-existing
+browser timers loop-exempt:client. Both land together: widening alone fails
+prebuild on fifteen unmarked sites.
+
+Header rewritten — it asserted the rest of app/ was Next.js route code, which
+this package has none of, and that app/lib was where server code stopped,
+which server/routes/whatsapp-reader.ts already disproves.
+
+files=284 -> 393, sites=10 -> 25, client=1 -> 16.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
+Session: aad2dcb4-bc6c-4502-9ef9-e75995fb974b"
+```
+
+---
+
+### Task 3: Prove the signal is live, then raise the real-tree floors
+
+Task 1's new cases run under `--root` against a synthetic tree. They prove the gate's *logic* handles `app/`, but they cannot prove the *real* scan root moved — a gate still hardcoded to `app/lib` internally would pass them if the fixture happened to be reachable. The task requires the gate observed failing on a real violation in the newly covered area. That is what this task does.
+
+**Files:**
+- Modify: `scripts/__tests__/check-loops-registered.test.ts:110-116` (the real-tree floors)
+- Temporarily modify then revert: `app/Sidebar.tsx`
+
+**Interfaces:**
+- Consumes: the counter line produced by Task 2.
+- Produces: nothing.
+
+- [ ] **Step 1: Mutation check — insert a real violation**
+
+Add this line at module scope in `app/Sidebar.tsx`, immediately after the final `import` statement. Module scope, not inside a component, so it is a genuine standing-loop shape rather than a mount-scoped one:
+
+```typescript
+setInterval(() => { void fetch('/api/health') }, 30000)
+```
+
+- [ ] **Step 2: Observe the gate fail on it**
+
+```bash
+cd maxy-code/platform/ui && node scripts/check-loops-registered.mjs; echo "exit=$?"
+```
+
+Expected: `exit=1`, with output naming `app/Sidebar.tsx`, the line number of the inserted statement, and `no loop-exempt marker`.
+
+**Record the exact output in the debrief.** A pass here is the whole point of the task — if the gate exits 0, the scan root did not actually move and Task 2 is not done, regardless of what the synthetic tests say.
+
+- [ ] **Step 3: Revert the mutation**
+
+```bash
+cd maxy-code/platform/ui && git checkout app/Sidebar.tsx
+node scripts/check-loops-registered.mjs; echo "exit=$?"
+```
+
+Expected: `exit=0` and the counter line back to `files=393 sites=25 marked=24 allowlisted=1`.
+
+Confirm the revert is complete before continuing:
+
+```bash
+git diff --stat -- app/Sidebar.tsx
+```
+
+Expected: no output. If `Sidebar.tsx` still differs, the marker from Task 2 was reverted along with the mutation — re-apply it.
+
+- [ ] **Step 4: Raise the real-tree floors**
+
+Replace lines 110–116 of `scripts/__tests__/check-loops-registered.test.ts`:
+
+```typescript
+  it('reports non-zero counts against the real tree, so a dead scanner is visible', () => {
+    const out = execFileSync('node', [GATE], { encoding: 'utf8' })
+    const files = Number(/files=(\d+)/.exec(out)?.[1] ?? 0)
+    const sites = Number(/sites=(\d+)/.exec(out)?.[1] ?? 0)
+    expect(files).toBeGreaterThanOrEqual(20)
+    expect(sites).toBeGreaterThanOrEqual(9)
+  })
+```
+
+with:
+
+```typescript
+  it('reports non-zero counts against the real tree, so a dead scanner is visible', () => {
+    const out = execFileSync('node', [GATE], { encoding: 'utf8' })
+    const files = Number(/files=(\d+)/.exec(out)?.[1] ?? 0)
+    const sites = Number(/sites=(\d+)/.exec(out)?.[1] ?? 0)
+    expect(files).toBeGreaterThanOrEqual(20)
+    expect(sites).toBeGreaterThanOrEqual(9)
+  })
+
+  // Task 1818 — the floors above predate the widening and would still pass with
+  // `app/` unscanned, so they cannot detect this task being reverted. These are
+  // keyed to the widened tree instead. They are floors, not equalities: source
+  // files get added routinely and an equality would fail on unrelated work.
+  // A revert to the `app/lib`-only root collapses files to ~284 and client to
+  // 1, so both of these fail, which is what they are for.
+  it('scans the whole of app/, not just app/lib', () => {
+    const out = execFileSync('node', [GATE], { encoding: 'utf8' })
+    const files = Number(/files=(\d+)/.exec(out)?.[1] ?? 0)
+    const client = Number(/client=(\d+)/.exec(out)?.[1] ?? 0)
+    expect(files).toBeGreaterThanOrEqual(380)
+    expect(client).toBeGreaterThanOrEqual(16)
+  })
+```
+
+- [ ] **Step 5: Run the full gate suite**
+
+```bash
+cd maxy-code/platform/ui && npx vitest run scripts/__tests__/check-loops-registered.test.ts
+```
+
+Expected: all cases pass, including the new floor case.
+
+- [ ] **Step 6: Run the whole prebuild gate chain**
+
+```bash
+cd maxy-code/platform/ui && npm run prebuild
+```
+
+Expected: every gate exits 0. `check-loops-registered` prints the Task 2 counter line. This confirms the widened gate has not broken any sibling gate and that the real build path is clean.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add maxy-code/platform/ui/scripts/__tests__/check-loops-registered.test.ts
+git commit -m "test: floor the loop gate's counts to the widened tree
+
+The pre-existing floors (files>=20, sites>=9) pass with app/ unscanned, so
+they cannot detect this task being reverted. Adds floors keyed to the widened
+root: files>=380, client>=16.
+
+Mutation-checked: a module-scope setInterval inserted into app/Sidebar.tsx is
+observed failing the gate at exit 1, then reverted.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
+Session: aad2dcb4-bc6c-4502-9ef9-e75995fb974b"
+```
+
+---
+
+## Verification surface
+
+Run from `maxy-code/platform/ui`.
+
+| Check | Command | Expected |
+|---|---|---|
+| Gate, real tree | `node scripts/check-loops-registered.mjs` | `files=393 sites=25 marked=24 allowlisted=1 (… client=16 …)` |
+| Gate suite | `npx vitest run scripts/__tests__/check-loops-registered.test.ts` | all pass |
+| Full prebuild chain | `npm run prebuild` | all gates exit 0 |
+| Mutation check | Task 3 Steps 1–3 | exit 1 naming `app/Sidebar.tsx`, then exit 0 after revert |
+| No behaviour change in app | `git diff -- app/` | comment-only additions; no statement altered |
+
+There is no browser verification step. This task changes a build gate and appends comments; it alters no rendered output and no runtime behaviour. `git diff -- app/` showing comment-only changes is the evidence for that claim.
+
+**Known pre-existing red, not caused by this task:** two tests in `server/lib/top-level-labels.test.ts` and `server/routes/__tests__/graph-default-topLevel.test.ts` fail on `main` and in any worktree, tracked as Task 1819. Neither imports anything this task touches. Do not attempt to fix them here.