@overdeck/desktop 0.49.1 → 0.50.0

package/sync-sources/dev-skills/pan-style-guide/SKILL.md

@@ -42,20 +42,33 @@ allowed-tools:
 3. **Written tightening:** `docs/prds/planned/pan-dashboard-unified-redesign.md`
    §4.5 ("Color & Style Discipline") — the PAN-1148 "Always means / Never used
    for" table now folded into the guide.
-4. **Tokens:** `src/dashboard/frontend/src/index.css` (light/dark color
-   blocks, `@font-face` declarations, theme font tokens, and the
-   `.display-xl`/`.display-lg`/`.eyebrow` Broadsheet utilities) and
-   `src/dashboard/frontend/tailwind.config.js`. Conformance is exercised by
-   `tests/e2e/styleguide-conformance.spec.ts`.
+4. **Tokens:** `src/dashboard/frontend/src/index.css` — the unscoped
+   `:root`/`.dark` blocks (Ledger's untouched default), `@font-face`
+   declarations, theme font tokens, the `.display-xl`/`.display-lg`/
+   `.eyebrow` Broadsheet utilities, and, after `.dark` closes, the PAN-3706
+   four-scope region carrying every color/surface/border/shadow/radius/
+   type/motion token plus the `.chip`/`.soft-card`/`.large-cta`/`.keycap`/
+   `.dot-metadata` component patterns — and `src/dashboard/frontend/
+   tailwind.config.js` (`boxShadow`, `fontFamily.mono-ui`, and the
+   `safelist` entries for classes not yet consumed by any `.tsx` file).
+   Conformance is exercised by `tests/e2e/styleguide-conformance.spec.ts`.
 
 ## Themes: Ledger (legacy) vs. Broadsheet (default)
 
 Overdeck ships two named design languages behind a single `ui.theme` setting
 (`~/.overdeck/config.yaml`, default `broadsheet`) and a `data-theme` attribute
-on `<html>`. **Ledger** is the pre-PAN-3410 style — DM Sans, flat
-`font-medium` cap, no display tier — now frozen: bug fixes only, never new
-patterns. **Broadsheet** is the active theme: Geist/Geist Mono, a tiered
-weight system, a display scale, and the new component vocabulary below.
+on `<html>` (independent of the `.dark` class, which carries light/dark
+color-scheme — the two axes never interact). **Ledger** is the pre-PAN-3410
+style — DM Sans, flat `font-medium` cap, cool blue-gray neutrals, no display
+tier — now frozen: bug fixes only, never new patterns. **Broadsheet** is the
+active theme: Geist/Geist Mono, a tiered weight system, a display scale, and
+the new component vocabulary below — plus, as of PAN-3706, its own warm
+neutral color ramp, stepped surfaces, opaque borders, a shadow/elevation
+scale, a smaller base radius, 13px/1.6 body type, and an ambient-wash
+background in place of Ledger's noise film. Before PAN-3706 the color/
+surface/elevation/radius/texture system was accidentally shared between both
+themes (a font-only migration); it is not anymore — see "Color, surface, and
+elevation now differ by theme" below.
 
 **The theme rule for new surfaces:** author against the Broadsheet
 vocabulary (`.display-xl`, `.display-lg`, `.eyebrow`, chips, soft cards,
@@ -83,6 +96,59 @@ utilities, no theming) if reached while Ledger is active. A component built
 with them is a Broadsheet-only component by construction; don't reach for
 them on a surface that must still render under Ledger.
 
+## Color, surface, and elevation now differ by theme (PAN-3706)
+
+The color system is no longer identical between themes (it was, pre-PAN-3706
+— see guide §2/§4). `:root`/`.dark` in `index.css` stay the untouched Ledger
+default; Broadsheet's real values live in a later region that overrides them
+per the four-scope contract below. What's still shared: signal-color
+*semantics* (what `--destructive`/`--warning`/etc. mean) and the badge tint
+*formula* (8%/32%). What now differs: the neutral ramp (warm HSL vs cool
+gray), `--background`/`--card`/`--popover` step apart under Broadsheet
+instead of collapsing to one flat color, `--border`/`--input` are opaque
+under Broadsheet instead of near-invisible `color-mix()`, `--radius` itself
+(10px Ledger / 6px Broadsheet — not just the badge tier), a role-named
+`--shadow-sm/md/lg/xl/card/floating/overlay` scale that actually resolves to
+something visible on dark surfaces, body type (13px/1.6/antialiased under
+Broadsheet vs. browser default under Ledger), and the background treatment
+(Ledger keeps the fractal-noise film; Broadsheet swaps it for an ambient
+corner wash via a new `--wash` token — not a retargeted `--accent`, which
+stays the hover-surface token in both themes). New tokens: `--primary-ink`
+(text-safe accent), `--body-foreground`/`--faint-foreground` (rounding
+`--foreground`/`--muted-foreground` out to a four-tier ramp), `--wash`, a
+`--type-size-*`/`--type-leading-*`/`--type-tracking-*` vocabulary (defined,
+not yet adopted by components), and `--ease-*`/`--duration-*` motion tokens
+(same — defined, not yet wired into existing animations). `--font-mono-ui`
+splits UI-chrome monospace (labels, IDs, timestamps) from `--font-mono`
+(code + the eyebrow exception) — Ledger resolves both to the same SF Mono
+stack, Broadsheet gives UI-mono a tighter system stack instead of Geist
+Mono's code-tuned metrics.
+
+**The four-scope selector contract** is what makes every one of those tokens
+resolve correctly by theme. Because `.dark` and `data-theme` both live on
+`<html>` at once, and because Settings → Appearance nests a `[data-theme]`
+scope inside the ambient document for its comparison specimens, a
+theme-varying token needs **four** blocks, placed after `:root`/`.dark` in
+source order (equal-specificity attribute selectors win on source order, not
+specificity):
+
+```
+[data-theme="ledger"]                                             — light, restate today's value
+[data-theme="broadsheet"]                                          — light, new value
+.dark[data-theme="ledger"], .dark [data-theme="ledger"]            — dark, restate today's value
+.dark[data-theme="broadsheet"], .dark [data-theme="broadsheet"]    — dark, new value
+```
+
+Same-element (`.dark[data-theme=...]`) matches `<html>` itself; descendant
+(`.dark [data-theme=...]`) matches a nested Appearance-picker specimen —
+both are required or a nested specimen inherits the wrong theme. For a
+non-color-token rule (a `body` background, a utility class), gate it on a
+custom property with a `var()` fallback rather than a bare descendant
+selector — `--badge-radius` and the `.display-xl`/`.display-lg`/`.eyebrow`
+properties are the established examples; a descendant selector matches
+through *any* ancestor with the attribute and breaks nesting, a custom
+property cascades by DOM proximity and doesn't. Full mechanics: guide §4a.
+
 ## The rules agents violate most (memorize these)
 
 ### Typography — Ledger (legacy baseline, verbatim)
@@ -144,9 +210,12 @@ purple = specialist verb, cyan = money, neutral = everything else.**
   (`bg-{signal}/8 border-{signal}/32 text-{signal}-foreground`) — identical
   in both themes (D-11, unchanged). No pills (`rounded-full`) for status
   badges.
-- Radius: `rounded-sm` under Ledger, `rounded-md` under Broadsheet — the
-  **one** deliberate radius change in the whole theme revision. Nothing else
-  about the badge formula differs between themes.
+- Radius: `rounded-sm` under Ledger, `rounded-md` under Broadsheet — the one
+  deliberate radius-*tier* change from PAN-3410, layered on top of PAN-3706's
+  smaller Broadsheet base `--radius` (10px Ledger / 6px Broadsheet), which
+  now also shrinks every other `rounded-*` utility computed from it (buttons,
+  cards, dialogs — see "Color, surface, and elevation" above). Nothing else
+  about the badge *formula* (8%/32% tint) differs between themes.
 - Pick ONE indicator pattern per context — don't mix dots + badges + colored
   text for the same concept in one view.
 
@@ -186,9 +255,15 @@ hardcoded hex (#22c55e, #ef4444, …)          → semantic tokens
 slate-* grays (cold)                         → neutral-* (warm) — everywhere
 ```
 
-Surfaces: depth via tonal layering (`--card`, `--card-2`), not shadows;
-borders `white/6%` dark, `black/5%` light; light-mode cards are borderless
-(ambient shadow instead).
+Surfaces: depth via tonal layering (`--card`, `--card-2`), not shadows —
+shadows stay reserved for floating elements only (dialogs, dropdowns,
+tooltips, popovers, dragged items), never inline cards/panels. Border/wash
+values are theme-scoped and no longer share one description: Ledger keeps
+low-alpha `color-mix()` borders (`white/6%` dark, `black/8%` light,
+near-invisible by design, light-mode cards borderless with an ambient
+shadow instead) and the noise-film texture; Broadsheet uses opaque HSL
+borders and an ambient corner wash instead (see "Color, surface, and
+elevation" above).
 
 ### Brand mark — the control ring (guide §19)
 

package/sync-sources/hooks/linear-mcp-auth-hook

@@ -78,8 +78,13 @@ RESPONSE=$(printf '%s' "$INPUT" | jq -r '
 [ -n "$RESPONSE" ] || RESPONSE=''
 
 if [ "$TOOL_NAME" = 'mcp__linear__authenticate' ]; then
+  # Linear's hosted MCP server (mcp.linear.app) returns its authorization URL
+  # as https://mcp.linear.app/authorize?…; the older form was
+  # https://linear.app/oauth/authorize?…. Match both — a regex that only
+  # knows one host silently emits required with a null URL and the banner
+  # waits forever (observed 2026-08-15).
   AUTH_URL=$(printf '%s\n' "$RESPONSE" \
-    | grep -Eo 'https://linear\.app/oauth/authorize[^"[:space:]<>]*' 2>/dev/null \
+    | grep -Eo 'https://(mcp\.linear\.app/authorize|linear\.app/oauth/authorize)[^"[:space:]<>]*' 2>/dev/null \
     | sed -n '1p')
   emit_required "$AUTH_URL"
   exit 0

package/sync-sources/rules/agent-message-delivery.md

@@ -1,19 +1,26 @@
 ---
 scope: universal
 ---
-### Message running agents with `pan tell` — never raw tmux keystroke injection
+### Message Overdeck-managed agents with `pan tell`, not raw tmux keystrokes
 
-To send a message to a running agent, conversation, or the flywheel, use
-`pan tell <agent-or-session> "<message>"`. It routes through the delivery door
-(`deliverAgentMessage`: PTY supervisor → channels → tmux fallback), echoes into
-the transcript, and works regardless of harness. If it reports the target is
-not running, verify with `tmux -L overdeck list-sessions` and check your
-`OVERDECK_HOME` (a polluted shell env is the usual cause — prefix
-`OVERDECK_HOME=~/.overdeck` if in doubt).
+To send a message to a running **Overdeck-managed** agent, conversation, or
+the flywheel, use `pan tell <agent-or-session> "<message>"`. It routes through
+the delivery door (`deliverAgentMessage`: PTY supervisor → channels → tmux
+fallback), echoes into the transcript, and works regardless of harness. If it
+reports the target is not running, verify with `tmux -L overdeck list-sessions`
+and check your `OVERDECK_HOME` (a polluted shell env is the usual cause —
+prefix `OVERDECK_HOME=~/.overdeck` if in doubt).
 
-Do NOT drive another session's terminal directly with `tmux paste-buffer` or
-`tmux send-keys` — keystroke injection is deny-listed in permission settings
-and will be refused. That deny-list is intentional; `pan tell` is the
-sanctioned path. (The `load-buffer`/`paste-buffer` pattern remains correct
-*inside Overdeck source code* implementing the delivery fallback — see the dev
-async-tmux rule.)
+Do not drive another **Overdeck-managed** session with raw `tmux send-keys` /
+`tmux paste-buffer` when `pan tell` can reach it — raw keystrokes bypass the
+transcript echo and the PTY supervisor, so the message leaves no trace and can
+interleave with the harness's own input handling. Scope of the mechanical
+enforcement (PAN-1084): pipeline **work agents** are hook-blocked from
+injecting keystrokes into any session other than their own (this exists to
+stop self-approval of another agent's permission prompts). Conversations and
+human-directed sessions are NOT blocked.
+
+Driving a session that Overdeck does not manage (e.g. the operator's own tmux
+session on the default socket, at their direction) with `send-keys` /
+`paste-buffer` is legitimate — use the async `load-buffer` + `paste-buffer` +
+delayed Enter pattern from the async-tmux rule so the text lands reliably.

package/sync-sources/rules/handoff-isolate-cwd.md

@@ -7,13 +7,13 @@ When you spawn a supervised agent (`pan handoff`, or any spawned agent that may
 
 An agent whose cwd is the primary repo can `git checkout -b` and commit there, which silently **drifts `main` onto a feature branch** and lets the agent commit straight to `main` — the same write-to-main hazard as PAN-2204. Your own later commits then land on the wrong branch.
 
-For `pan handoff`, pass `--cwd`:
+For `pan handoff`, pass `--cwd` as an **absolute path to an existing directory under your home directory** — the server rejects relative paths, `/tmp` paths, and not-yet-created directories with `Invalid cwd`:
 
 ```bash
-git worktree add ../hoff-<slug> main         # if you don't already have one
-pan handoff --model <m> --cwd ../hoff-<slug> --project <key> self "Read .pan/handoff-brief.md FIRST. <goal>"
+git worktree add "$HOME/Projects/hoff-<slug>" main   # if you don't already have one
+pan handoff --model <m> --cwd "$HOME/Projects/hoff-<slug>" --project <key> self "Read .pan/handoff-brief.md FIRST. <goal>"
 ```
 
-Project association inherits automatically from a project-scoped source; use `--project <key>` to override it or associate an unscoped source. Point `--cwd` at any isolated checkout — anything but the primary.
+Run the `pan handoff` command itself from your project directory (not from the `--cwd` target or `/tmp` — sandboxed harnesses block network there). Project association inherits automatically from a project-scoped source; use `--project <key>` to override it or associate an unscoped source. Point `--cwd` at any isolated checkout — anything but the primary.
 
 **Why:** a `pan handoff` investigation run in the primary worktree branched + committed there, silently drifting `main` and stranding later commits on the wrong branch (2026-07-01). Isolation keeps every spawned agent's commits on its own branch, where review/merge can gate them.

package/sync-sources/rules/pan-handoff-focus-limit.md

@@ -1,16 +1,25 @@
 ---
 scope: universal
 ---
-### `pan handoff` focus is capped at 500 chars — put long briefs in a file
+### `pan handoff` focus: keep it short; the hard ceiling is 10,000 chars
 
-The `pan handoff` **focus** (the trailing text after `self`/`<conv>`) is hard-capped at **500 characters**. A longer focus is rejected outright — the CLI prints `Focus is N characters — the limit is 500` and **creates no conversation**. Do not try to cram a full brief into the focus.
+The `pan handoff` **focus** (the trailing text after `self`/`<conv>`) is a steering
+statement, not the brief. Since PAN-3737 the hard cap is **10,000 characters**
+(multi-line focus is allowed), so accidental rejection is effectively gone — but a
+short focus still works better: it becomes the conversation title and steers the
+handoff author, while detail belongs in the transcript or a brief file. Pass
+`--title "<title>"` to name the successor explicitly instead (PAN-3768) — useful
+when the focus is a file pointer.
 
-For anything longer than one line, write the full brief to a file in the target cwd and point a short focus at it:
+For a full brief, write it to a file in the target cwd and point the focus at it:
 
 ```bash
 pan handoff self "Read .pan/handoff-brief.md FIRST and follow it exactly. <one-line goal>"
 ```
 
-Also pass **`self`** (or a real conversation id) **before** the focus text. Omitting it makes the CLI read your focus as a conversation name and fail with `Conversation not found`.
+Also pass **`self`** (or a real conversation id) **before** the focus text. Omitting it
+makes the CLI read your focus as a conversation name and fail with `Conversation not found`.
 
-**Why:** agents repeatedly overrun the 500-char focus and the handoff silently fails to spawn (this has happened on essentially every handoff attempt). A file-backed brief makes the handoff reliable regardless of length, and keeps the full instructions in the new conversation's cwd where it can re-read them.
+**Why:** the old 500-char cap rejected the handoff *after* the agent had done the work,
+on essentially every long focus, burning retry loops. The cap is now a sanity ceiling
+only; the file-backed brief remains the reliable pattern for long instructions.

package/sync-sources/rules/ste-writing.md

@@ -0,0 +1,17 @@
+---
+scope: universal
+---
+### Write clear, simple prose — the STE clarity standard
+
+Respond in clear, plain, concise, human-readable prose by default. "The
+Elements of Style" (Strunk & White) is the baseline register.
+
+On that baseline, use the core principles of ASD-STE100 Simplified Technical
+English as a clarity standard. Use active voice, simple verbs, and short
+sentences. Avoid idioms, slang, and unnecessary jargon. Give each sentence one
+main idea or instruction. Put conditions before dependent actions. Use one
+consistent term for each concept. Prefer 20 words or fewer for procedures and
+25 words or fewer for descriptions when this preserves accuracy and natural
+flow. Do not force formal STE compliance unless the user asks for it. Keep
+technical identifiers, paths, commands, names, units, prices, and numbers
+exact.

package/sync-sources/rules/work-agents-via-pan.md

@@ -5,7 +5,7 @@ scope: universal
 
 Spawn work agents only through the Overdeck CLI — `pan start <id>`, `pan swarm <id>`, `pan plan <id>`. NEVER spawn a *work* agent via Claude Code's `Agent`/subagent tool.
 
-**Why:** `pan`-spawned agents are registered with Overdeck — a `~/.overdeck/agents/agent-<id>/state.json` carrying `issueId`, a tmux session on the `overdeck` socket, and (for swarms) a swarm-runtime entry. The dashboard's resource-discovery service nests them under their issue with openable terminals, and the review/test/ship pipeline can manage them.
+**Why:** `pan`-spawned agents are registered with Overdeck — a `~/.overdeck/agents/agent-<id>/state.json` carrying `issueId` and a tmux session on the `overdeck` socket. The dashboard nests them under their issue with openable terminals, and the review/test/ship pipeline can manage them.
 
 Agents spawned via the `Agent` tool run as ephemeral subagents inside the caller's session — no state file, no `issueId`, no `overdeck`-socket session. The dashboard cannot discover them; they cannot be paused, resumed, reviewed, merged, or recovered through the pipeline.
 
@@ -13,5 +13,6 @@ Agents spawned via the `Agent` tool run as ephemeral subagents inside the caller
 
 - **work** (implementation), **plan**, **review/test/ship** → always `pan`.
 - Claude Code's built-in `Explore` / `general-purpose` subagents are fine for *throwaway code investigation* — they produce no deliverable and are not work agents.
+- A swarm foreman may perform a small, high-confidence item in its own context or use a registered standing tier session. The foreman still owns the claim, verification, commit, push, and task transition; an ephemeral subagent never becomes an independent slot.
 
 Let Cloister route models — do not pass `--model` unless explicitly asked.

package/sync-sources/rules/writing-style.md

@@ -18,8 +18,9 @@ Rules:
 4. **Don't shred connected reasoning into bullets.** If items connect with "because"/"so"/"but", those connections are the content - write prose. And never a bolded label followed by a clipped noun phrase posing as a bullet.
 5. **Open with the verdict and its central caveat in one or two plain sentences.** Not a bolded headline.
 6. **Conversational but not dramatic.** Use contractions (it's, you'd, don't). Say "so" and "but", not "therefore" and "however". Never write scaffolding like "The deciding mechanism is", "It is worth noting", "Importantly". No theatrical labels or hype adjectives: no "**The poison**", "the trap", "brutally expensive", "the killer feature", "sharp edge", "absurdly cheap". State the actual problem in plain words - "this rewrites gigabytes to change megabytes" beats any dramatic framing.
- - No staccato, short dramatic sentences. Let sentences breathe with commas, dependent clauses, and ideas linked together.
+ - Vary sentence length and shape, and connect related ideas. A run of same-shape sentences, automatic pairs and triads, or setup/payoff framing reads as generated - break the pattern.
  - No cheesy setup phrases that introduce a point instead of stating it. Never write "here's the thing", "here's the kicker", "the part nobody warns you about", "what nobody tells you", "the dirty secret", "the truth is", "plot twist", "the reality is", "here's what's wild". State the claim directly.
- - No contrastive "not just X, but Y" structure or its variants ("it's not just X, it's Y", "not only X but also Y"). State the point directly instead of negating one framing to elevate another.
+ - No contrastive "not just X, but Y" structure or its variants ("it's not just X, it's Y", "not only X but also Y"), and no repeated negative openings ("Not X. Not Y."). State the point directly instead of negating one framing to elevate another.
+ - No filler intensifiers, corporate verbs, needless hedges, or performed enthusiasm. Prefer verbs to noun piles. Write for the spoken voice.
 7. **No compression.** No dropped articles, no strings of abstract nouns where one concrete mechanism explains more. Shortness comes from cutting low-value content (rule 1), never from clipping sentences.
 8. **End with a bottom line only when the answer weighed a real decision.** One plain-prose sentence: the call plus the condition that would flip it. Short factual or confirmation answers just end - no formulaic closer.

package/sync-sources/skills/{skill-creator → claude-skill-creator}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: skill-creator
+name: claude-skill-creator
 description: Guide for creating effective Claude Code skills. Use when users want to create a new skill, update an existing skill, or need guidance on skill best practices. Triggers on requests like "create a skill", "make a new skill", "help me build a skill", "skill development", or "extend Claude's capabilities".
 license: Apache 2.0 (based on Anthropic's skills repo)
 ---

package/sync-sources/skills/{skill-creator → claude-skill-creator}/scripts/init_skill.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
 """
 Skill Initializer - Creates a new skill from template
 

package/sync-sources/skills/{skill-creator → claude-skill-creator}/scripts/package_skill.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
 """
 Skill Packager - Creates a distributable .skill file
 

package/sync-sources/skills/pan-gauntlet-loop/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: pan-gauntlet-loop
+description: >-
+  Run a Gauntlet Loop — fan out builder sub-agents per area, judge each with
+  a SEPARATE harsh critic in a blind A/B against a named reference bar, keep
+  looping until every area wins, and track it all on a live progress page.
+  Use when the user wants to take any project, feature, or domain to an
+  extreme quality tier ("make it AAA", "at the level of <reference>",
+  "utterly perfect", "run the gauntlet", "gauntlet loop"). Works for any
+  domain — games, UI, CLIs, APIs, libraries, docs, performance, writing.
+triggers:
+  - gauntlet loop
+  - run the gauntlet
+  - gauntlet
+  - AAA quality pass
+---
+
+# Gauntlet Loop
+
+Take any domain to a named quality bar with a builder/critic loop: fan out a
+builder sub-agent per area, judge each area with a **separate** harsh critic
+(fresh context, blind A/B against the reference, binary verdict), feed defects
+back, and loop until every area is WOWED. A live progress page tracks every
+area, screenshot, verdict, and defect list.
+
+Origin: Matt Shumer's gauntlet prompt; hardened by the operational lessons of
+runs #1–#2 (folded into the phases below — every rule exists because its
+absence cost an iteration).
+
+## Phase 0 — Intake: fill the slots, ask about the gaps
+
+**Run-file shortcut:** a run file (e.g. `gauntlet/RUN-<CODENAME>.md`) may
+pre-fill every slot and carry the operator's approval in writing. When one
+exists and the operator pointed you at it, the run file IS the contract —
+skip intake questions and the Phase-1 approval gate, and follow the run
+file wherever it is more specific than this skill.
+
+Otherwise, extract these slots from the user's request. For every slot that is
+missing or vague, ask via AskUserQuestion — batch up to 4 questions per call,
+each self-contained (the operator may answer from a dashboard dialog without
+the transcript: state the situation, then ask). Never guess the mission.
+
+| Slot | Meaning | If missing |
+|---|---|---|
+| THING | What to build / enhance / fix | Ask. Never proceed without it. |
+| REFERENCE | The named quality bar | Propose 2–3 candidates that are **named, fetchable, comparable** (below); ask the user to pick one. |
+| AREAS | The fan-out split | Propose a split from THING (see `references/domains.md`); ask to confirm or edit. |
+| TIER | Quality shorthand | Default: "shipped commercial quality at the level of REFERENCE". |
+| LOOK | The committed direction (art / UX / language / architecture) | Seed from repo conventions; confirm in one AskUserQuestion option set. |
+| STACK | Stack constraints | Default: "this repo, unchanged". Ask only if the request implies a change. |
+| SCOPE | Explicit exclusions | If THING is broad, ask "what is out of bounds on this pass?" |
+| CHECK | How the critic inspects the work | Derive from the domain (`references/domains.md`) — screenshots, CLI transcripts, benchmarks, rendered docs. |
+
+REFERENCE is the load-bearing slot. Before accepting it, verify it is:
+
+- **Named** — a specific thing ("Civilization VII", "stripe.com's docs"),
+  not a category ("a good strategy game").
+- **Fetchable** — the critic can screenshot, read, run, or open it. Fetch the
+  reference evidence during setup (below); if you cannot, say so and pick
+  another bar with the operator.
+- **Comparable** — the subject's evidence and the reference's evidence can sit
+  side by side for a judge to pick one.
+
+## Phase 1 — Setup (before any builder launches)
+
+1. **Isolate the work.** Default: `git worktree add ../<repo>-gauntlet -b
+   gauntlet-loop-pass` and run the whole gauntlet there. Offer the current
+   checkout instead only when the operator asked to enhance in place.
+2. **Scaffold `gauntlet/` in the worktree:**
+   - `gauntlet/index.html` — copy `{baseDir}/assets/gauntlet-index.html`
+     **verbatim** (it renders from status.json; never edit per project).
+   - `gauntlet/PROMPT.md` — fill `{baseDir}/assets/PROMPT.template.md` with
+     the slots. This is the mission prompt every agent reads.
+   - `gauntlet/status.json` — schema below; all areas NOT STARTED.
+   - `gauntlet/shots/`, `gauntlet/notes/` — empty dirs.
+3. **Write the judging contracts in `refs/`:**
+   - `refs/STYLE.md` — fill `{baseDir}/assets/STYLE.template.md`: one page,
+     the committed direction. Every builder and every critic works from it.
+   - `refs/REFERENCE-BAR.md` — fill
+     `{baseDir}/assets/REFERENCE-BAR.template.md`: the verdict question,
+     automatic failures, scoring dimensions, verdict JSON format.
+   - `refs/press/` — the fetched reference evidence (screenshots, transcripts,
+     docs). Gitignore third-party media.
+4. **Build seed/test hooks NOW, not mid-loop.** Seedable state is
+   load-bearing for critique: if reaching a state takes hours of wall-clock
+   (filled stockpiles, advanced time, specific data), the loop can't be
+   photographed. Add the hook during setup. Never restart a shared dev
+   server mid-run — hot-reload kills other agents' verification sessions.
+5. **Serve the progress page:** from `gauntlet/`, run
+   `python3 -m http.server <port>` in the background and report the URL.
+   (Browsers block `fetch()` from `file://` — the page needs HTTP.)
+6. **Operator approval gate.** Show the filled `gauntlet/PROMPT.md` to the
+   operator and get an explicit go before the first fan-out. The gauntlet
+   burns real tokens; the mission it burns them on is the operator's call.
+   (Skipped when a run file already carries the approval — see Phase 0.)
+
+### status.json schema
+
+```json
+{
+  "project": "<display title>",
+  "tagline": "<one-line mission flavor>",
+  "updated": "<ISO>",
+  "pass": "<branch name>",
+  "areas": {
+    "<area-key>": {
+      "title": "<human title>",
+      "status": "NOT STARTED",
+      "iteration": 0,
+      "verdict": null,
+      "defects": [],
+      "note": "<one-line current state>",
+      "updated": "<ISO>"
+    }
+  }
+}
+```
+
+`verdict` is `"WOWED"`, `"NOT_YET"`, or `null`. `defects` holds the top ≤5
+(strings, or `{"element","fix"}` objects). The page polls it every 5s.
+
+## Phase 2 — The loop (per area, areas in waves)
+
+1. **Wave plan — parallelize to the file-ownership limit.** Assign each area
+   an exact file-ownership map, restated in every agent prompt. Concurrent
+   agents in one worktree WILL clobber shared files, so areas that share
+   files run in the same wave **serially** — but that constraint is
+   per-file, not global: prefer SPLITTING areas until their maps are
+   disjoint, and run everything disjoint **concurrently**. Films and
+   critics for different areas are read-only-ish and parallelize freely.
+   Keep the orchestrator thin; the fan-out does the work.
+2. **Build.** Spawn a builder sub-agent for the area with its ownership map,
+   the mission prompt, and the current defect list as its work order.
+   Builders never commit and never judge their own work; the orchestrator
+   reviews and commits per area with path-scoped `git add` — `git add -A`
+   would scoop another in-flight agent's half-done work.
+3. **Capture evidence at presentation quality.** Launch the real thing and
+   drive it — Playwright for UI, the CLI at its command, the benchmark at
+   its load. Screenshots at 1920×1080 with realistic in-fiction data (a
+   visible test username in a shot is a defect); keep dev tooling out of
+   frame. Save the canonical shot to `gauntlet/shots/<area-key>.png` (or
+   transcript/benchmark to notes/). Headless gotchas: black frames in
+   headless Chromium are a renderer-context issue, not scene code — try
+   default launch flags before forcing software rasterization; canvas/WebGL
+   code must survive a React StrictMode double-mount; software-rasterized
+   FPS is CPU numbers — NEVER the real perf verdict. Perf claims need a
+   headed capture.
+4. **Critique.** Spawn the critic — ALWAYS a separate sub-agent from the
+   builder, fresh context, high-tier model (see routing below). The critic
+   is blind to the builder's effort, reasoning, and transcript — but it is
+   NOT tool-poor: it gets the evidence + `refs/`, and it MAY run its own
+   probes and instruments against the running app, the repo, or the
+   benchmark to verify or refute any claim (run-#2 precedent: critic-built
+   instruments caught deploy-saving defects the builder's own numbers
+   missed). It judges blind per `refs/REFERENCE-BAR.md` — literally side by
+   side, which one looks better — and returns the verdict JSON. Verdicts
+   are binary (WOWED / NOT_YET + every failing element with a concrete
+   fix), never a score out of 10. The critic tags each defect with the
+   owning area so cross-area defects merge into the right queue. Save to
+   `gauntlet/notes/critique-<area>-iter<n>.json`.
+5. **Update the dashboard at every transition** — agent launched / landed /
+   filming / awaiting critique / verdict — not just after critiques. A
+   stale dashboard is a bug. The page mutates cards in place; regenerated
+   media needs cache-busting or browsers replay stale files.
+6. **NOT_YET → the defect list becomes the next iteration's work order** for
+   the same area. WOWED → area done, and prior WOWED quality is a FLOOR no
+   later iteration may regress. **No fixed round count**: the exit is
+   winning, or the operator stopping the run.
+7. **Test reconciliation is its own queued item.** Big visual/structural
+   changes break existing test selectors; don't let a builder burn its run
+   fixing them. Wave gates are: build passes, evidence captured, critique
+   filed. Broken-suite repair gets its own area or follow-up.
+8. **Cadence artifacts.** Commit critique JSONs and status.json to the
+   branch — the pass history is reviewable. Gitignore large third-party
+   reference media and regenerable sources (keep shipped assets committed).
+
+## Phase 3 — Stop conditions
+
+- **The operator is the brake.** The loop does not finish on its own; when
+  they say stop, stop, commit cleanly, and report state.
+- **All areas WOWED** → final report: per-area verdicts and iteration counts,
+  the commit log, the dashboard URL, and anything deferred to a later pass.
+
+## The four ways the loop silently fails
+
+1. **Vague bar** — the critic invents a comparison and approves everything.
+   The bar must be named, fetchable, comparable.
+2. **Builder judging its own work** — the critic must be a fresh agent with
+   zero knowledge of the builder's effort or reasoning trail.
+3. **Soft critic** — scores out of 10 drift upward and everything passes.
+   Binary verdict + concrete fixes only.
+4. **Fixed round count** — "3 iterations" ships a prototype. The exit is
+   WOWED, or the operator stopping the run.
+
+Restate all four in every agent prompt — they are the whole game.
+
+## Sub-agents, model routing, and tools
+
+- Fan out with the Agent tool inside this conversation. Gauntlet builders and
+  critics are ephemeral conversation sub-agents — the "work agents run through
+  `pan`" rule governs managed pipeline issues, not this loop. If the gauntlet
+  uncovers work that belongs in the managed pipeline, file an issue and route
+  it through `pan start`.
+- **Model ladder — cheapest that clears the bar, escalate on evidence:**
+  **Sonnet** is the default for as much as possible — builders, films,
+  mechanical implementation, asset processing, test runs. **Opus** when
+  necessary — every critic by default, design-heavy build areas, and
+  problems a Sonnet attempt just fumbled. **Fable** for the really tricky
+  stuff only — areas that keep failing across iterations, deep root-cause
+  mysteries, and the final full-frame composition judgment. Escalate a
+  LANE's tier after failures, not preemptively; de-escalate when the hard
+  part is done. Critics are where model quality pays — never cheap out on
+  the judge.
+- **Distribute and parallelize as much as possible.** Many cheap agents in
+  flight beat one expensive agent in series; the wave plan's file-ownership
+  maps are the only serialization constraint.
+- **No tool restrictions.** Every gauntlet agent may use whatever tools the
+  session has — browsers/Playwright, WebSearch/WebFetch, image tooling,
+  profilers, DB clients. "Blind critic" restricts what the critic is TOLD
+  (nothing from the builder), never what it may DO.
+- Sub-agent fan-out requires a harness with the Agent tool. GPT-routed
+  claude-code sessions cannot spawn sub-agents — run the gauntlet from a
+  Claude session.
+
+## References
+
+- `references/domains.md` — per-domain CHECK (evidence capture), sample area
+  splits, automatic-failure lists, and storefront-test phrasing.
+- `assets/` — `gauntlet-index.html` (progress page), `PROMPT.template.md`,
+  `STYLE.template.md`, `REFERENCE-BAR.template.md`.