diff --git a/.cfgcaddy.yml b/.cfgcaddy.yml index ac4f8770..f466079d 100644 --- a/.cfgcaddy.yml +++ b/.cfgcaddy.yml @@ -67,6 +67,8 @@ links: os: "Linux Darwin" - src: .claude/hooks/cmdcrush-wrap.sh os: "Linux Darwin" + - src: .claude/hooks/pr-review-reminder.sh + os: "Linux Darwin" - src: .config/ssq-hooks os: "Linux Darwin" - src: .config/finicky/finicky.js diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 298fed5f..534081f4 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -61,7 +61,7 @@ Use the serena MCP server for complex multi-file structural edits when available - **Self-explanatory code first.** A good name or a clean structure removes the need for a comment; reach for one only after that fails. - **Why, not what.** Comment a hidden constraint, a non-obvious tradeoff, or a workaround for a specific bug — never restate what the code already says. -- **Short beats long.** One line over a paragraph. If a comment needs more than a line, the code usually needs a rename instead. +- **Short beats long.** One line over a paragraph, and never more than 5 lines or one paragraph — the same ceiling `code:review`'s Code Quality check flags as MAJOR, so writing past it just means a reviewer sends it back. If a comment covers more than one distinct rationale (root cause vs. an accepted tradeoff vs. a pointer to a test), split it or cut to the single fact a reviewer would actually ask for — don't stack every consideration into one block. - **Docstrings on entry points only.** Give a public function or module an overview when its purpose isn't obvious from its name and signature; skip it for private helpers. - **Name assumptions and limits.** If a function assumes sorted input, a bounded range, or has a known failure mode, say so once at the point of use. diff --git a/.claude/hooks/pr-review-reminder.sh b/.claude/hooks/pr-review-reminder.sh new file mode 100755 index 00000000..890e6975 --- /dev/null +++ b/.claude/hooks/pr-review-reminder.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# PreToolUse(Bash) hook: before `gh pr create|ready|merge` (including env-prefixed +# and chained forms), inject a reminder to run the full adversarial review loop. +# PreToolUse so it lands before a chained `gh pr ready && gh pr merge` completes. +# +# Hot path: runs on EVERY Bash call, so it must not spawn anything. `read` is a +# builtin and `case` early-exits on the raw hook JSON; jq/grep run only on a hit. +IFS= read -r -d '' input +case $input in + *"gh pr "*) ;; + *) exit 0 ;; +esac +cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null) +if printf '%s' "$cmd" | grep -qE 'gh pr (create|ready|merge)'; then + cat <<'JSON' +{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"MANDATORY REVIEW GATE (Tyler standing policy): you are about to open/ready/merge a PR. Before handing it to Tyler, marking it ready, or merging it you MUST run the full adversarial review loop — your own verified pass + fresh UNANCHORED reviewers across the right lenses (correctness, concurrency, domain-semantics vs the code being replaced, tests/security) + a round-2 convergence pass — and address every real finding. Bitbot + a glance is NOT enough. If this PR is docs/config-only, say so explicitly and scope the review lenses accordingly rather than skipping review."}} +JSON +fi diff --git a/.claude/skills/demo-assets/SKILL.md b/.claude/skills/demo-assets/SKILL.md new file mode 100644 index 00000000..0817300c --- /dev/null +++ b/.claude/skills/demo-assets/SKILL.md @@ -0,0 +1,115 @@ +--- +name: demo-assets +description: "Capture and share demo assets on a GitHub PR: terminal-recording GIFs (vhs) and PNG screenshots, including browser screenshots of web pages (Playwright). Use for 'screenshots for the PR', 'demo gif', 'attach images/gifs to a PR', 'show the UI change'. Hosts files on a throwaway orphan branch deleted after merge" +allowed-tools: Bash(vhs:*) Bash(ffmpeg:*) Bash(git:*) Bash(gh:*) Bash(npx:*) Bash(node:*) +--- + +# Demo assets (GIFs and screenshots) for a PR comment + +Use when a PR needs visual evidence: a CLI/TUI flow (GIF) or a UI change (PNG). Posting is outward-facing: +draft the comment, get the user's approval before `gh pr comment`, and label it agent-authored if it goes out +under the user's login. + +**Rule: never commit assets into the PR branch.** They live only on the `qa-assets/pr-` branch (step 2). + +## 1a. Record a terminal GIF + +```sh +brew install vhs # pulls ttyd; runs headless +vhs demo.tape # tape: Output demo.gif / demo.mp4 +``` + +- Open the tape with a title card (PR number, scenarios shown) so the clip is self-describing. +- vhs drops frames at large sizes. Use `Set Framerate 12` and about 1500x860; a 1700x950 render of a 70s run came out 15s. +- Keep the GIF under ~5 MB: trim waits with `Sleep` and shorten timeouts via env overrides. Ship the MP4 too. +- Check it: `ffmpeg -ss 25 -i demo.mp4 -frames:v 1 f.png`, then look at a few frames. Don't claim it's legible unseen. + +## 1b. Capture PNG screenshots + +1. **List every page, tab and state the PR changes first** (including empty, error and loading states). One + image per state; tick each off before moving on. +2. Run the app locally, preferably against synthetic/fixture data. +3. Capture with Playwright (chromium) into `/tmp//`: + +```js +// shots.js — run: npx playwright install chromium && node shots.js +const { chromium } = require('playwright'); +(async () => { + const browser = await chromium.launch(); + const page = await browser.newPage({ viewport: { width: 1500, height: 1000 } }); + const shots = [['capacity', 'http://localhost:3000/capacity', '[data-testid=chart]']]; + for (const [name, url, ready] of shots) { + await page.goto(url); + await page.waitForSelector(ready); // wait for content, not a fixed sleep + await page.addStyleTag({ content: '*,*::before,*::after{animation:none!important;transition:none!important}' }); + await page.screenshot({ path: `/tmp/pr-assets/${name}.png` }); // viewport only; fullPage only if needed + } + await browser.close(); +})(); +``` + +- **Naming:** kebab-case, `[-].png`, e.g. `capacity.png`, `capacity-empty.png`. Names become + URLs; no spaces or uppercase. +- **Size:** viewport screenshots, not full-page, unless the page's point is its length. If installed, shrink + with `oxipng -o2 *.png` or `pngquant --force --ext .png 256 *.png`. +- **Look at every image** (Read the PNG) before publishing. Don't claim it's right unseen. +- **Sensitive data:** inspect each image for real hostnames, account IDs, emails, tokens, customer names or + internal URLs in the address bar, tabs or content. Prefer fixture data; otherwise re-capture or crop. In a + public repo anyone can see these files. + +## 2. Host on a throwaway orphan branch + +An orphan branch shares no history with the PR, so the PR diff and the default branch are untouched. + +```sh +git worktree add --orphan -b qa-assets/pr- /tmp/qa-assets- # git >= 2.42 +cp /tmp/pr-assets/*.png demo.gif demo.mp4 /tmp/qa-assets-/ # whichever you have +git -C /tmp/qa-assets- add . +git -C /tmp/qa-assets- commit -m "qa assets for PR (delete after merge)" +git -C /tmp/qa-assets- push origin qa-assets/pr- +git worktree remove /tmp/qa-assets- +``` + +Embed: + +```md + +![demo](https://raw.githubusercontent.com///qa-assets/pr-/capacity.png) + +![demo](https://github.com///raw/qa-assets/pr-/capacity.png) +``` + +For a GitHub Enterprise Server host, use `https://///raw/...` (there is no +`raw.githubusercontent.com`). + +## 3. Comment template + +```md +**Screenshots (agent-captured for this PR, not the author's own words)** + +| Page | Image | +|---|---| +| Capacity, default | ![capacity](/capacity.png) | +| Capacity, empty state | ![capacity-empty](/capacity-empty.png) | + +Demo: ![demo](/demo.gif) +``` + +Post it, then open the PR and confirm every image renders inline. If not, fall back to drag-and-drop upload in +the comment box and delete the branch. + +## 4. Clean up after merge + +```sh +git push origin --delete qa-assets/pr- +``` + +## Caveats + +- **Clones fetch it.** A default `git clone`/`git fetch` downloads every branch, so the blobs ride along for + everyone until the branch is deleted and the server garbage-collects. It is not checked out by default. + `--single-branch` clones skip it. Delete promptly. +- Anyone with read access sees the files, and in a public repo anyone does. Don't capture secrets or tokens. +- Branch protection or push rules matching `qa-assets/*` can block the push. +- The private-repo and GHES embed URLs are untested here; the render check is mandatory. +- Simplest alternative that leaves nothing in the repo: drag the files into the PR comment box by hand. diff --git a/.claude/skills/playwright-skill/SKILL.md b/.claude/skills/playwright-skill/SKILL.md index 853f7b8f..7d9a209f 100644 --- a/.claude/skills/playwright-skill/SKILL.md +++ b/.claude/skills/playwright-skill/SKILL.md @@ -393,6 +393,7 @@ For comprehensive Playwright API documentation, see [API_REFERENCE.md](API_REFER - **Parameterize URLs** - Put detected/provided URL in a `TARGET_URL` constant at the top of every script - **DEFAULT: Visible browser** - Always use `headless: false` unless user explicitly asks for headless mode - **Headless mode** - Only use `headless: true` when user specifically requests "headless" or "background" execution +- **GPU acceleration** - Headed Chromium uses the GPU by default. Playwright's default headless mode (the headless shell) renders in software (SwiftShader), so for headless runs that need real GPU (WebGL, canvas, perf timing) launch with `channel: 'chromium'` (new headless) or add `args: ['--use-angle=metal', '--enable-gpu', '--ignore-gpu-blocklist']` (macOS; use `--use-angle=gl`/`vulkan` per platform). Don't pass `--disable-gpu` unless Chrome's GPU process crashes on that machine. Verify with CDP: `const { gpu } = await (await browser.newBrowserCDPSession()).send('SystemInfo.getInfo'); console.log(gpu.devices, gpu.featureStatus)` and look for `gpu_compositing: "enabled"` and a real device instead of SwiftShader (checked on Apple Silicon macOS: headed and `channel: 'chromium'` both report the Metal device; the default headless shell reports SwiftShader) - **Slow down:** Use `slowMo: 100` to make actions visible and easier to follow - **Wait strategies:** Use `waitForURL`, `waitForSelector`, `waitForLoadState` instead of fixed timeouts - **Error handling:** Always use try-catch for robust automation @@ -412,6 +413,19 @@ Ensure running from skill directory via `run.js` wrapper **Browser doesn't open:** Check `headless: false` and ensure display available +**Headed window renders only part of the page:** +A fixed `viewport` (or `setViewportSize`) larger than the actual window clips what the user sees. For +visible, user-driven sessions launch with `viewport: null` and `args: ['--start-maximized']` so the page +follows the window size (verified: switching from `viewport: { width: 1600, height: 1000 }` to this +rendered the full page). Keep explicit viewports for headless or screenshot-at-size runs. + +**Page behind SSO / login you can't script:** +Use `chromium.launchPersistentContext(profileDir, { headless: false, viewport: null, args: ['--start-maximized'] })` +with a private profile dir (`mkdir -m 700`), let the user sign in once in the window, and poll `page.url()` +until the app URL is reached before measuring. Reuse the same profile on later runs. To record traffic add +`recordHar: { path, content: 'omit' }` (keeps sizes/timings, drops bodies); the HAR still contains auth +headers, so keep it local and never print header values. + **Element not found:** Add wait: `await page.waitForSelector('.element', { timeout: 10000 })` diff --git a/.claude/skills/sdd/skills/6-verify/SKILL.md b/.claude/skills/sdd/skills/6-verify/SKILL.md index 6b68a9d1..f5f93e68 100644 --- a/.claude/skills/sdd/skills/6-verify/SKILL.md +++ b/.claude/skills/sdd/skills/6-verify/SKILL.md @@ -220,19 +220,24 @@ with the unresolved list. Do not proceed to . ### Layer 2 — Architecture & Design Quality (always two agents, regardless of technology) **Step 0: kibitzer mechanical pre-pass (optional, degrades gracefully)** - - If an MCP connection to `kibitzer` is available and the repo has a `.claude/inspect.json`: - call its `architecture_assessment` tool scoped (via `scope`) to the packages/modules - touched by the diff. If MCP isn't connected but `kibitzer` is on `PATH`, use the CLI - equivalent instead: `kibitzer run --trigger batch`. This is a mechanical - pre-pass, not a replacement for the architecture-review agent below — it covers what's - cheaply checkable (import cycles, layering violations, coupling thresholds, a Mermaid - dependency diagram via MCP, plus — if `.claude/inspect.json` declares + - `.claude/inspect.json` is NOT required — kibitzer's built-in checks (import cycles, + layering violations, coupling thresholds) run against any repo out of the box. The file + only adds optional custom rules on top (`architecture.components`/`dependency_rules`/ + `content_rules`/`naming_rules`) — treat its absence as "no custom rules," not "kibitzer + unavailable." + - If an MCP connection to `kibitzer` is available: call its `architecture_assessment` tool + scoped (via `scope`) to the packages/modules touched by the diff. If MCP isn't connected + but `kibitzer` is on `PATH`, use the CLI equivalent instead: `kibitzer run + --trigger batch`. This is a mechanical pre-pass, not a replacement for the + architecture-review agent below — it covers what's cheaply checkable (import cycles, + layering violations, coupling thresholds, a Mermaid dependency diagram via MCP, plus — + if `.claude/inspect.json` exists and declares `architecture.components`/`dependency_rules`/`content_rules`/`naming_rules` — cross-component dependency, content, and naming-convention violations), not qualitative judgment (SOLID, testability, over-engineering). - - If neither is reachable, or the repo has no `.claude/inspect.json`: skip this step - silently and proceed straight to the architecture-review agent with no pre-pass context. - Phase 6 must never fail or stall because kibitzer isn't set up. + - If kibitzer is neither MCP-connected nor on `PATH`: skip this step silently and proceed + straight to the architecture-review agent with no pre-pass context. Phase 6 must never + fail or stall because kibitzer isn't installed. - If it returns findings: pass its raw output (findings text + Mermaid diagram, if any) into the architecture-review agent's prompt below as grounding context. diff --git a/.claude/skills/ui-html-mockup/SKILL.md b/.claude/skills/ui-html-mockup/SKILL.md new file mode 100644 index 00000000..034a7d7f --- /dev/null +++ b/.claude/skills/ui-html-mockup/SKILL.md @@ -0,0 +1,60 @@ +--- +name: ui-html-mockup +description: Build a shareable single-file HTML mockup of a UI redesign from real data, with Figma-style annotations (was/now/data/ask pins), a guided tour, a full state matrix and measured accessibility probes. Use when asked to prototype, mock up or critique a view and hand it to a partner team, or when a design needs evidence rather than opinion. +--- + +# UI HTML mockup + +A mockup is a single `.html` file, no build step, that runs from `file://`, shows real (trimmed) data, and explains how it differs from the current design. Anyone can open it, click the pins or take the tour, and answer the questions in it. + +## When to use + +- Redesigning or proposing a view and you need partner feedback. +- Critiquing an existing view: the mockup is the argument. +- Not for production code. Port to the real design system afterwards; this file uses raw colours on purpose. + +## Workflow + +1. **Name the question and the baseline.** Write the one question the page must answer ("which pools need attention?"). Capture the current design from screenshots or source and record what it does, so every "Was" is verified, not remembered. +2. **Get real data, read-only.** Prefer a snapshot of the real API over invented rows. Probe the API first: list the kinds or fields it serves, fetch one object, check size limits (responses over a gateway buffer fail outright; select fields to trim). Save raw responses outside the repo. Note what the API cannot provide; those become "Not available" notes and annotation questions, not fake numbers. +3. **Trim and anonymise.** Build a compact JSON (counts, states, timestamps). Drop names, IDs, UIDs and hostnames; use `Item #3 (omitted)`. Label the page as sample data. Keep snapshots from one point in time, because a busy system drifts between fetches and pages then disagree. +4. **Start from `assets/shell.html`.** Inline `annotations.css`, `tabs.js` and `annotations.js` at the placeholders (`/* ANNOTATIONS_CSS */`, `/* TABS_JS */`, `/* ANNOTATIONS_JS */`). Add pages as functions that return HTML from the data. Compute every on-screen number from the data so pages agree. +5. **Design the whole state matrix, not just the happy path.** Loading (skeleton), empty (reason plus next action), error (the real cause plus retry), stale (banner with timestamp; do not dim, dimming breaks contrast), no access (who can grant it). A State selector in the header switches them. +6. **Annotate.** For each part that differs from the current design add an entry: `type` (New, Changed, Question), `was` (current behaviour, verified), `now`, `data` (source field), `ask` (one question for the partner team). Order a `tour` of the most important entries across pages. +7. **Make it operable.** Real ` + * + * Share links: file.html#annotations, file.html#tour, file.html#. + */ +(function(){ + const M = window.MOCKUP; let on = false, pop = null, ti = -1; + const byId = id => M.annos.find(a => a.id === id); + const pageAnnos = () => M.annos.filter(a => a.page === '*' || a.page === M.getPage()); + const cls = a => a.type.toLowerCase(); + const html = a => `
${a.type}${a.title}
Was
${a.was}
Now
${a.now}
Data
${a.data}
Ask
${a.ask}
`; + function place(){ + const layer = document.getElementById('annoLayer'); layer.innerHTML = ''; + document.getElementById('annoPanel').style.display = on ? '' : 'none'; + document.getElementById('annoBtn').setAttribute('aria-pressed', on); + if (!on) return; + const list = pageAnnos(); + document.getElementById('annoCount').textContent = `(${list.length}, collapsed by default)`; + document.getElementById('annoList').innerHTML = list.map((a,i)=>`
  • ${a.type}
  • `).join(''); + list.forEach((a,i) => { const el = document.querySelector(a.sel); if (!el || !el.offsetParent) return; + const r = el.getBoundingClientRect(), b = document.createElement('button'); + b.className = 'pin ' + cls(a); b.textContent = i+1; b.dataset.id = a.id; b.setAttribute('aria-label', `Note ${i+1}, ${a.type}: ${a.title}`); + b.style.left = (r.left + scrollX - 12) + 'px'; b.style.top = (r.top + scrollY - 12) + 'px'; b.onclick = () => open(a.id); layer.appendChild(b); }); + } + // Place a floating card beside the highlighted element (right, left, below, above), choosing the spot with least overlap. + function placeNear(card, r){ + const W = card.offsetWidth, H = card.offsetHeight, m = 12, vw = innerWidth, vh = innerHeight; + const clamp = (x,y) => ({x:Math.min(vw-W-8, Math.max(8, x)), y:Math.min(vh-H-8, Math.max(8, y))}); + const overlap = p => Math.max(0, Math.min(p.x+W, r.right+6) - Math.max(p.x, r.left-6)) * Math.max(0, Math.min(p.y+H, r.bottom+6) - Math.max(p.y, r.top-6)); + const cands = [clamp(r.right+m, r.top), clamp(r.left-m-W, r.top), clamp(r.left, r.bottom+m), clamp(r.left, r.top-m-H)]; + let best = cands[0], bo = overlap(best); for (const c of cands) { const o = overlap(c); if (o < bo) { best = c; bo = o; } if (bo === 0) break; } + Object.assign(card.style, {left:best.x+'px', top:best.y+'px', bottom:'auto', transform:'none'}); + } + function popPlace(){ if (!pop) return; const a = byId(pop), el = document.querySelector(a.sel), p = document.getElementById('annopop'), s = document.getElementById('annoSpot'); if (!el || !p) return; + const r = el.getBoundingClientRect(); s.style.cssText = `left:${r.left-4}px;top:${r.top-4}px;width:${r.width+8}px;height:${r.height+8}px`; placeNear(p, r); } + function open(id, scroll){ close(); const a = byId(id), el = document.querySelector(a.sel); if (scroll && el) { el.scrollIntoView({block:'start'}); scrollBy(0,-70); } + setTimeout(() => { const p = document.createElement('div'); p.className = 'annopop'; p.id = 'annopop'; p.setAttribute('role','dialog'); p.setAttribute('aria-label', a.title); + p.innerHTML = html(a) + ''; document.body.appendChild(p); + const s = document.createElement('div'); s.id = 'annoSpot'; s.className = 'annospot'; document.body.appendChild(s); + pop = id; popPlace(); p.querySelector('button').focus(); }, 0); } + function close(){ document.getElementById('annopop')?.remove(); document.getElementById('annoSpot')?.remove(); pop = null; } + function toggle(v){ on = v ?? !on; close(); place(); } + function step(i){ if (i < 0 || i >= M.tour.length) return end(); ti = i; const a = byId(M.tour[i]); + if (a.page !== '*' && a.page !== M.getPage()) M.go(a.page); + M.before?.[a.id]?.(); + setTimeout(() => { const el = document.querySelector(a.sel); if (el) { el.scrollIntoView({block:'start'}); scrollBy(0,-70); } setTimeout(() => draw(a, i), 30); }, 30); } + function draw(a, i){ const el = document.querySelector(a.sel), r = el ? el.getBoundingClientRect() : {left:0,top:0,right:0,bottom:0,width:0,height:0}; + const had = document.getElementById('tourcard'), focusNext = !had || had.dataset.step !== String(i); + document.getElementById('tourLayer').innerHTML = `
    + `; + placeNear(document.getElementById('tourcard'), r); if (focusNext) document.getElementById('tournext').focus(); } + function start(){ close(); M.go(Object.keys(M.pages)[0]); step(0); } + function end(){ ti = -1; document.getElementById('tourLayer').innerHTML = ''; document.getElementById('tourBtn').focus(); } + document.addEventListener('keydown', e => { if (e.key==='Escape') { ti>=0 ? end() : pop && close(); } if (ti>=0 && e.key==='ArrowRight') step(ti+1); if (ti>=0 && e.key==='ArrowLeft') step(ti-1); }); + let raf = 0; const reflow = () => { cancelAnimationFrame(raf); raf = requestAnimationFrame(() => { if (ti>=0) draw(byId(M.tour[ti]), ti); popPlace(); }); }; + addEventListener('scroll', reflow, {passive:true}); addEventListener('resize', () => { place(); reflow(); }); + Object.assign(M, { afterRender: () => setTimeout(place, 0), toggle, open, close, start, step, end }); + const h = location.hash.replace('#','').split(/[&,]/); if (h.includes('annotations')) on = true; + const pg = h.find(x => M.pages[x]); if (pg) M.go(pg); + if (h.includes('tour')) setTimeout(start, 50); +})(); diff --git a/.claude/skills/ui-html-mockup/assets/shell.html b/.claude/skills/ui-html-mockup/assets/shell.html new file mode 100644 index 00000000..c43765f3 --- /dev/null +++ b/.claude/skills/ui-html-mockup/assets/shell.html @@ -0,0 +1,67 @@ + + + + +Mockup shell + + + + +
    + +

    Product · Mockup

    + + + +
    +
    +
    + + + + diff --git a/.claude/skills/ui-html-mockup/assets/tabs.js b/.claude/skills/ui-html-mockup/assets/tabs.js new file mode 100644 index 00000000..a528c444 --- /dev/null +++ b/.claude/skills/ui-html-mockup/assets/tabs.js @@ -0,0 +1,12 @@ +/* Arrow-key navigation for any role=tablist (ARIA tabs pattern, automatic activation). + * Markup:
    + * Give each tablist an id so focus can be restored after a re-render. Page switching between top-level pages is NOT a tablist: use + *