lastlight 0.7.4 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lastlight",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "GitHub repository maintenance agent — Agent SDK harness",
   "type": "module",
   "main": "dist/index.js",

package/plugins/lastlight/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin.json",
   "name": "lastlight",
   "displayName": "Last Light",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Install, configure and operate Last Light (GitHub maintenance agent) — its server, CLI client, deployment overlay, and the Last Light Evals harness.",
   "author": { "name": "Clifton Cunningham" },
   "homepage": "https://github.com/cliftonc/lastlight",

package/plugins/lastlight/skills/lastlight-evals/SKILL.md

@@ -97,20 +97,36 @@ lastlight-evals run triage --model haiku        # fuzzy match in models.json
 lastlight-evals run triage --model openai/gpt-5.5,anthropic/claude-opus-4-8
 lastlight-evals run --compare                   # cross-vendor set (only models whose envKey is present)
 lastlight-evals run triage --runs 3             # repeat each case 3× (worst-case verdict, mean metrics)
+lastlight-evals run pr-review --limit 3         # only the first 3 cases of the tier (controlled/cheap run)
+lastlight-evals run triage --instance <id>      # only this exact instance_id (or set EVAL_INSTANCE)
 lastlight-evals run triage --no-open            # don't open the report
 # Plain layout: add --overlay .   (e.g. lastlight-evals run triage --overlay .)
+
+lastlight-evals serve                           # browse past runs in the dashboard (no models run)
+lastlight-evals clean --dry-run                 # list killed/crashed runs that are stuck "running"
+lastlight-evals clean                           # finalize them (mark interrupted; --delete to remove)
 ```
 
-Output lands in `./eval-results/<tiers>/`: `index.html` (scorecard),
-`scorecard.json`, `predictions.jsonl` (SWE-bench format). Re-render a report
-without re-running: `lastlight-evals report ./eval-results/triage`.
+Each run lands in its own dir `./eval-results/<tiers>/<runId>/`: `scorecard.json`
++ `predictions.jsonl` (SWE-bench format). The report is a **JSON-driven dashboard
+SPA**, not generated HTML — `run` starts a local server and opens it; browse every
+past run later with `lastlight-evals serve`. In the dashboard a code-fix row's
+**files** button opens the agent's captured diff and **log** shows the per-phase
+agent session.
+
+If a run is killed or crashes mid-flight it stays stuck showing "running" (its
+scorecard never got its final write). `lastlight-evals clean` finalizes such runs
+— marks them *interrupted* (default; keeps the partial scorecard + transcripts)
+or `--delete` removes the run dir.
 
 ## 5. Author eval cases (optional)
 
-Two tiers ship: **triage** (cheap, issue-triage) and **code-fix** (heavy, build
-workflow with held-out tests). To add cases or a custom tier, read
-**`references/instance-schema.md`** — it has the `SweBenchInstance` schema, the
-exact files to create for each tier, and worked examples.
+Three tiers ship: **triage** (cheap, issue-triage), **code-fix** (heavy, build
+workflow with held-out tests), and **pr-review** (PR-review precision, graded by
+an LLM judge against a gold set → precision / recall / **F0.5**). To add cases or
+a custom tier, read **`references/instance-schema.md`** — it has the
+`SweBenchInstance` schema, the exact files to create for each tier, and worked
+examples.
 
 Quick shape (paths are relative to the workspace's `evals/` dir):
 - **Triage case:** append a `SweBenchInstance` to `evals/datasets/triage/instances.json`
@@ -118,6 +134,12 @@ Quick shape (paths are relative to the workspace's `evals/` dir):
 - **Code-fix case:** add the instance to `evals/datasets/code-fix/instances.json` **and**
   create `evals/datasets/code-fix/repos/<instance_id>/` (fixture repo at base) +
   `evals/datasets/code-fix/tests/<instance_id>/` (held-out tests applied at grade time).
+- **PR-review case:** a `SweBenchInstance` with a `pr` fixture (base/head refs +
+  commits, checked out at the PR head) and a `review_gold` set (severity +
+  description). The `pr-review` tier ships empty — populate the full Martian
+  [Code Review Bench](https://codereview.withmartian.com/) 50 with
+  `npx tsx scripts/import-martian.ts`. Grading needs a judge model
+  (`EVAL_JUDGE_MODEL`, else a strong default per provider key).
 - **Custom tier:** a new `evals/datasets/<tier>/` with `tier.json` +
   `instances.json` (+ `repos/` & `tests/` for code-fix-style tiers). Discovery is
   automatic — no code change.

package/skills/README.md

@@ -17,22 +17,24 @@ or editing a skill.
 | [`chat`](chat/) | chat | Conversational assistant for Slack/Discord threads — answer repo/PR/issue questions, guide to natural-language triggers. |
 | [`issue-triage`](issue-triage/) | `issue-triage.yaml`, chat | Move issues through the canonical triage state machine — categorise, label, dedupe, manage stale, write a problem-statement summary (not a solution design), re-triage on reporter replies. |
 | [`issue-comment`](issue-comment/) | `issue-comment.yaml` | Handle non-build maintainer comments on issues/PRs — close, label, answer briefly, redirect build requests. |
-| [`pr-review`](pr-review/) | `pr-review.yaml`, chat | Review a PR with structured, tiered feedback; build and test from the local checkout; post a formal review. |
+| [`pr-review`](pr-review/) | `pr-review.yaml`, chat | Review a PR with precision-first, tiered feedback and post a formal review. A pure code review — no building (CI validates the change). |
 | [`pr-comment`](pr-comment/) | `pr-comment.yaml` | Answer a maintainer's question about an open PR with concrete, code-cited evidence (not a full review). |
 | [`repo-health`](repo-health/) | `repo-health.yaml`, chat | Generate a repository health report — open issues, PR backlog, CI status, action items. |
 | [`security-review`](security-review/) | `security-review.yaml` | Diff-scoped SDLC security review; file one dated summary issue with a task-list of findings. |
 | [`security-feedback`](security-feedback/) | `security-feedback.yaml` | Process a maintainer's comment on a security scan summary — break findings into issues or record suppressions. |
-| [`building`](building/) | build (executor, reviewer), `pr-fix.yaml`, `pr-review.yaml` | Shared craft: install-first + package-manager detection, the test/lint/typecheck gate, and TDD discipline in the sandbox. |
+| [`building`](building/) | build (executor, reviewer), `pr-fix.yaml` | Shared craft: install-first + package-manager detection, the test/lint/typecheck gate, and TDD discipline in the sandbox. |
 | [`code-review`](code-review/) | build (reviewer), `pr-review.yaml` | Shared rubric: finding tiers (Critical/Important/Suggestions/Nits) and what-to-check. Referenced by both the branch-diff reviewer and the PR reviewer. |
 | [`verify`](verify/) | `verify.yaml` | Test a behaviour claim as an investigator — CONFIRMED / REFUTED / INCONCLUSIVE with bash-captured evidence. |
 | [`qa-test`](qa-test/) | `qa-test.yaml` | Run an automated QA flow against a CLI or locally-served app and report step-level pass/fail with evidence. |
 | [`browser-qa`](browser-qa/) | `verify.yaml`, `qa-test.yaml`, `demo.yaml` | Drive a real headless browser against a locally-served web UI and capture screenshot (and, for `demo`, video) evidence. Gated to the docker QA image. |
 | [`demo`](demo/) | `demo.yaml` | Record a short demo VIDEO of a PR/feature — drive the web UI, screen-record, and composite a titled, size-capped mp4 with ffmpeg. Gated to the docker QA image. |
 
-`building` and `code-review` are **shared building blocks** — referenced by the
-build-cycle prompts (`workflows/prompts/*.md`) and the PR skills so the install
-gate and review rubric live in one place. They're staged alongside the phase's
-primary skill/prompt and read on demand.
+`building` and `code-review` are **shared building blocks** so the install
+gate and the review rubric each live in one place. `building` is staged by the
+build cycle (executor + reviewer) and `pr-fix`; `code-review` by the build
+reviewer and `pr-review` (which stages `code-review` but **not** `building` — a
+pure code review). They're staged alongside the phase's primary skill/prompt and
+read on demand.
 
 The live set is enforced at startup: `validateAssets()` (`src/workflows/loader.ts`)
 resolves every workflow `skill:` reference and `CHAT_SKILL_NAMES`

package/skills/browser-qa/SKILL.md

@@ -91,11 +91,26 @@ Step keys (a step may combine an action **plus** a trailing `screenshot`):
 | `waitFor`    | selector             | Wait until the element is visible (~10s timeout).                |
 | `assertText` | string               | Pass if the text is visible anywhere on the page; else step FAIL.|
 | `text`       | selector             | Extract `textContent` into the step result (for you to read).    |
+| `pause`      | milliseconds         | Hold for N ms — a readable beat after a state change (demo videos).|
 | `screenshot` | basename             | Write `<out-dir>/<basename>.png` (full page).                    |
 
 The whole flow runs in **one Chromium session** — login state, cookies, and
 navigation persist across steps.
 
+### Demo mode (recording only)
+
+When the session is **recorded** (`--record-dir`, `"record": true`, or an
+explicit `--demo`), the driver switches on "demo mode" so the capture is
+watchable — headless Chromium otherwise paints no cursor and fires actions
+instantly. Demo mode adds a **synthetic cursor overlay** that animates to each
+target, types `type` steps **character-by-character**, and holds a beat
+**between steps**. For screenshot QA (no recording) these are all no-ops, so
+QA runs stay fast. Prefer `type` over `fill` in a recorded flow so the typing is
+visible, and use `pause` for deliberate holds. Tunables:
+`--step-delay MS` (default 700), `--type-delay MS` (default 70),
+`--move-steps N` (default 25), `--no-cursor` to drop the overlay (env:
+`LASTLIGHT_STEP_DELAY_MS`, `LASTLIGHT_TYPE_DELAY_MS`, `LASTLIGHT_MOVE_STEPS`).
+
 ## Run the flow
 
 ```bash

package/skills/browser-qa/scripts/agent-browser.mjs

@@ -18,6 +18,8 @@
 //     The skill runs this first to decide browser-vs-text.
 //
 //   run <flow.json> [--base-url URL] [--out-dir DIR] [--record-dir DIR]
+//              [--demo] [--no-cursor] [--step-delay MS] [--type-delay MS]
+//              [--move-steps N]
 //     Executes a FLOW in ONE Chromium session (state preserved across steps) and
 //     prints a single JSON report.
 //
@@ -27,6 +29,17 @@
 //     reported as `video` in the JSON. Used by the `/demo` workflow, which then
 //     composites the raw webm into a titled mp4 with compose-demo.sh.
 //
+//     DEMO MODE (auto-on whenever recording; also --demo or `"demo": true` in the
+//     flow) makes the capture human-watchable — headless Chromium otherwise
+//     paints no cursor and fires actions instantly:
+//       - a synthetic cursor overlay (opt out with --no-cursor) that animates to
+//         each target before acting, driven by real page.mouse events;
+//       - `type` steps that key in char-by-char (--type-delay, default 70ms);
+//       - a deliberate hold between steps (--step-delay, default 700ms).
+//     Outside demo mode every one of these is a no-op, so screenshot QA runs
+//     behave exactly as before. Env equivalents: LASTLIGHT_STEP_DELAY_MS,
+//     LASTLIGHT_TYPE_DELAY_MS, LASTLIGHT_MOVE_STEPS.
+//
 //     Flow shape:
 //       { "baseUrl": "http://localhost:3000",
 //         "viewport": {"width":1280,"height":800},
@@ -38,10 +51,13 @@
 //           {"press":"Enter"},
 //           {"waitFor":"#dashboard"},
 //           {"assertText":"Welcome"},
+//           {"pause": 1200},
 //           {"text":"h1"},
 //           {"screenshot":"after-login"}
 //         ] }
-//     A step may combine an action plus a trailing `screenshot`.
+//     A step may combine an action plus a trailing `screenshot`. `pause` holds
+//     for N ms (a readable beat after a state change, for demo recordings);
+//     `type` shows visible per-character typing, `fill` sets the value instantly.
 //
 //     Per-step semantics:
 //       - A step error (selector not found, assertion fail, timeout) is recorded
@@ -77,6 +93,81 @@ const WAIT_TIMEOUT = 10_000; // sane default for waitFor / assertText probes
 // watchable tail. Override with --record-settle-ms / LASTLIGHT_RECORD_SETTLE_MS.
 const RECORD_SETTLE_MS = Number(process.env.LASTLIGHT_RECORD_SETTLE_MS) || 1500;
 
+// ── Demo-mode pacing ─────────────────────────────────────────────────────────
+// Headless Chromium paints NO cursor and fires actions instantly, so a raw
+// recording looks like the UI mutating on its own. "Demo mode" (auto-on whenever
+// the session is recorded — see run()) makes the capture human-watchable: a
+// synthetic cursor overlay that animates to each target, char-by-char typing,
+// and a deliberate pause between steps. These are no-ops outside demo mode, so
+// screenshot QA runs are untouched. All tunable via flags / env.
+const DEMO_STEP_DELAY_MS = Number(process.env.LASTLIGHT_STEP_DELAY_MS) || 700;
+const DEMO_TYPE_DELAY_MS = Number(process.env.LASTLIGHT_TYPE_DELAY_MS) || 70;
+const DEMO_MOVE_STEPS = Number(process.env.LASTLIGHT_MOVE_STEPS) || 25;
+
+// Synthetic cursor overlay, adapted from Puppeteer's mouse-helper (Apache-2.0),
+// made self-installing so it can be injected via context.addInitScript and picked
+// up by Playwright's recordVideo (it's page DOM, so it lands in the .webm). It
+// follows the REAL mouse events that page.mouse.move/down/up dispatch.
+const MOUSE_HELPER_SRC = `(() => {
+  const install = () => {
+    if (window.__mouseHelperInstalled || !document.body) return;
+    window.__mouseHelperInstalled = true;
+    const box = document.createElement('div');
+    box.classList.add('mouse-helper');
+    const style = document.createElement('style');
+    style.innerHTML = \`
+      .mouse-helper {
+        pointer-events: none;
+        position: absolute;
+        z-index: 2147483647;
+        width: 20px; height: 20px;
+        margin-left: -10px; margin-top: -10px;
+        border-radius: 10px;
+        border: 2px solid rgba(255,255,255,.9);
+        background: rgba(0,0,0,.35);
+        box-shadow: 0 0 0 1px rgba(0,0,0,.4);
+        transition: background .15s, border-radius .15s, transform .08s;
+      }
+      .mouse-helper.button-1 {
+        transition: none;
+        background: rgba(30,120,255,.7);
+        transform: scale(.75);
+      }
+    \`;
+    document.head.appendChild(style);
+    document.body.appendChild(box);
+    const move = (e) => { box.style.left = e.pageX + 'px'; box.style.top = e.pageY + 'px'; };
+    document.addEventListener('mousemove', move, true);
+    document.addEventListener('mousedown', (e) => { move(e); box.classList.add('button-1'); }, true);
+    document.addEventListener('mouseup', (e) => { move(e); box.classList.remove('button-1'); }, true);
+  };
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', install, false);
+  } else {
+    install();
+  }
+})();`;
+
+// Animate the synthetic cursor to the centre of a selector, best-effort. Returns
+// the target box when it landed (so the caller can click at those coords), or
+// null to fall back to Playwright's own targeting.
+async function moveCursorTo(page, selector, demo) {
+  try {
+    const loc = page.locator(selector).first();
+    await loc.waitFor({ state: 'visible', timeout: WAIT_TIMEOUT });
+    await loc.scrollIntoViewIfNeeded({ timeout: WAIT_TIMEOUT }).catch(() => {});
+    const box = await loc.boundingBox();
+    if (!box) return null;
+    const cx = box.x + box.width / 2;
+    const cy = box.y + box.height / 2;
+    await page.mouse.move(cx, cy, { steps: demo.moveSteps });
+    await page.waitForTimeout(140).catch(() => {});
+    return { cx, cy };
+  } catch {
+    return null;
+  }
+}
+
 function emit(obj) {
   process.stdout.write(JSON.stringify(obj) + '\n');
 }
@@ -140,6 +231,7 @@ function actionOf(step) {
     'waitFor',
     'assertText',
     'text',
+    'pause',
   ]) {
     if (k in step) return k;
   }
@@ -147,7 +239,7 @@ function actionOf(step) {
   return 'noop';
 }
 
-async function execStep(page, step, baseUrl, outDir, screenshots) {
+async function execStep(page, step, baseUrl, outDir, screenshots, demo) {
   const result = {};
   let fatal = false;
 
@@ -164,15 +256,31 @@ async function execStep(page, step, baseUrl, outDir, screenshots) {
       });
     }
   } else if ('click' in step) {
-    await page.click(step.click, { timeout: WAIT_TIMEOUT });
+    // Demo mode: animate the cursor to the target and click at its coordinates
+    // so the pointer travel + press are visible. Fall back to Playwright's own
+    // targeting when the box can't be resolved (or outside demo mode).
+    const at = demo.enabled ? await moveCursorTo(page, step.click, demo) : null;
+    if (at) {
+      await page.mouse.down();
+      await page.mouse.up();
+    } else {
+      await page.click(step.click, { timeout: WAIT_TIMEOUT });
+    }
   } else if ('fill' in step) {
     const [sel, val] = step.fill;
+    if (demo.enabled) await moveCursorTo(page, sel, demo);
     await page.fill(sel, val, { timeout: WAIT_TIMEOUT });
   } else if ('type' in step) {
     const [sel, val] = step.type;
+    if (demo.enabled) await moveCursorTo(page, sel, demo);
     await page.locator(sel).first().pressSequentially(val, {
       timeout: WAIT_TIMEOUT,
+      delay: demo.enabled ? demo.typeDelay : 0,
     });
+  } else if ('pause' in step) {
+    // Explicit hold — for reading a state change before the next action.
+    const ms = Number(step.pause) || 0;
+    if (ms > 0) await page.waitForTimeout(ms);
   } else if ('press' in step) {
     await page.keyboard.press(step.press);
   } else if ('waitFor' in step) {
@@ -210,7 +318,7 @@ async function execStep(page, step, baseUrl, outDir, screenshots) {
   return { result, fatal };
 }
 
-async function run(flowPath, baseUrlArg, outDirArg, recordDirArg) {
+async function run(flowPath, baseUrlArg, outDirArg, recordDirArg, opts = {}) {
   let flow;
   try {
     flow = JSON.parse(readFileSync(resolve(flowPath), 'utf8'));
@@ -229,6 +337,17 @@ async function run(flowPath, baseUrlArg, outDirArg, recordDirArg) {
   // `"record": true`. The .webm lands in the record dir (default: out-dir).
   const doRecord = !!recordDirArg || flow.record === true;
   const videoDir = resolve(recordDirArg || outDir);
+  // Demo mode = recording, an explicit --demo, or flow.demo. It slows the run
+  // down (cursor animation, char-by-char typing, inter-step holds) so the
+  // capture is watchable; it's a no-op for plain screenshot QA. Cursor overlay
+  // is on by default in demo mode, opt out with --no-cursor.
+  const demo = {
+    enabled: opts.demo === true || flow.demo === true || doRecord,
+    cursor: opts.cursor !== false,
+    stepDelay: Number.isFinite(opts.stepDelay) ? opts.stepDelay : DEMO_STEP_DELAY_MS,
+    typeDelay: Number.isFinite(opts.typeDelay) ? opts.typeDelay : DEMO_TYPE_DELAY_MS,
+    moveSteps: Number.isFinite(opts.moveSteps) ? opts.moveSteps : DEMO_MOVE_STEPS,
+  };
   try {
     mkdirSync(outDir, { recursive: true });
   } catch {
@@ -267,6 +386,11 @@ async function run(flowPath, baseUrlArg, outDirArg, recordDirArg) {
       // the clip isn't letterboxed. The .webm is flushed on context.close().
       ...(doRecord ? { recordVideo: { dir: videoDir, size: viewport } } : {}),
     });
+    // Inject the synthetic cursor before the first navigation so it's present on
+    // every page (addInitScript re-runs on each document). Only in demo mode.
+    if (demo.enabled && demo.cursor) {
+      await context.addInitScript(MOUSE_HELPER_SRC).catch(() => {});
+    }
     const page = await context.newPage();
 
     page.on('console', (msg) => {
@@ -288,7 +412,7 @@ async function run(flowPath, baseUrlArg, outDirArg, recordDirArg) {
 
       const started = Date.now();
       try {
-        const { result } = await execStep(page, step, baseUrl, outDir, screenshots);
+        const { result } = await execStep(page, step, baseUrl, outDir, screenshots, demo);
         steps.push({ index: i, action, ok: true, ms: Date.now() - started, ...result });
       } catch (err) {
         const entry = {
@@ -301,6 +425,12 @@ async function run(flowPath, baseUrlArg, outDirArg, recordDirArg) {
         steps.push(entry);
         if (err && err.fatal) fatalHit = true; // navigation failure: skip the rest
       }
+
+      // Demo mode: hold between steps so the video breathes (skip after an
+      // explicit `pause`, which already held, and after a fatal step).
+      if (demo.enabled && demo.stepDelay > 0 && action !== 'pause' && !fatalHit) {
+        await page.waitForTimeout(demo.stepDelay).catch(() => {});
+      }
     }
 
     // Finalize a recording (if any) BEFORE emitting: saving the video requires
@@ -370,18 +500,24 @@ async function main() {
     let baseUrl;
     let outDir;
     let recordDir;
+    const opts = {};
     for (let i = 0; i < rest.length; i++) {
       const a = rest[i];
       if (a === '--base-url') baseUrl = rest[++i];
       else if (a === '--out-dir') outDir = rest[++i];
       else if (a === '--record-dir') recordDir = rest[++i];
+      else if (a === '--demo') opts.demo = true;
+      else if (a === '--no-cursor') opts.cursor = false;
+      else if (a === '--step-delay') opts.stepDelay = Number(rest[++i]);
+      else if (a === '--type-delay') opts.typeDelay = Number(rest[++i]);
+      else if (a === '--move-steps') opts.moveSteps = Number(rest[++i]);
       else positional.push(a);
     }
     if (!positional[0]) {
-      emit({ ok: false, error: 'usage: agent-browser.mjs run <flow.json> [--base-url URL] [--out-dir DIR] [--record-dir DIR]' });
+      emit({ ok: false, error: 'usage: agent-browser.mjs run <flow.json> [--base-url URL] [--out-dir DIR] [--record-dir DIR] [--demo] [--no-cursor] [--step-delay MS] [--type-delay MS] [--move-steps N]' });
       process.exit(1);
     }
-    await run(positional[0], baseUrl, outDir, recordDir);
+    await run(positional[0], baseUrl, outDir, recordDir, opts);
     return;
   }
 

package/skills/code-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: code-review
-description: The shared rubric for reviewing a code change — finding tiers (Critical/Important/Suggestions/Nits) and what to check (correctness, security, edge cases, regression risk, test coverage). Use when reviewing a PR or a branch diff.
-version: 1.0.0
+description: The shared rubric for reviewing a code change — precision-first, high-signal findings only (Critical/Important), plus what to check (correctness, security, edge cases, regression risk, test coverage). Use when reviewing a PR or a branch diff.
+version: 2.0.0
 tags: [review, code-quality]
 ---
 
@@ -17,17 +17,40 @@ modified functions, check callers of anything whose signature or behaviour
 changed for regression risk, and check that tests cover the actual risk areas,
 not just the happy path.
 
+## Precision first — post only what matters
+
+A review is only useful if people trust it. A noisy reviewer gets muted; every
+low-value comment you post spends the credibility of the ones that matter. So
+the bar is **high-signal only**:
+
+- **Post only Critical and Important findings.** Suggestions and Nits (below)
+  are *not* worth a formal review comment on their own — drop them, or fold at
+  most one genuinely valuable line into the summary. When in doubt, leave it out.
+- **If you cannot name the concrete impact — what breaks, and for which input or
+  caller — do not post it.** "This could be cleaner" is not a finding; "this
+  crashes when `items` is empty because line 42 indexes `[0]`" is.
+- **Confidence gate.** Before you finalise, re-read each finding against the
+  actual code and try to *refute your own claim*. If you can't defend it against
+  what the code actually does (not what you assumed), drop it. A missed marginal
+  issue costs far less than a wrong one.
+
 ## Finding tiers
 
-Categorise every finding into exactly one tier:
+Categorise every finding into exactly one tier. **Only Critical and Important
+are posted** (see Precision first):
 
 - **Critical** — security issues, data loss, breaking changes, silent
   data-dropping (see Correctness below). Blocks merge.
 - **Important** — missing tests, performance problems, type errors, **avoidable
   duplication**, **excessive complexity**, **compiler-silencing assertions**.
   Should fix.
-- **Suggestions** — clarity, naming, minor DRY tidy-ups. Nice to have.
-- **Nits** — style, formatting. Optional.
+- **Suggestions** — clarity, naming, minor DRY tidy-ups. *Not posted* — noise
+  in a formal review.
+- **Nits** — style, formatting. *Not posted* — this is the linter's job.
+
+Every posted finding carries a **one-line concrete impact**: the consequence
+(what breaks / for whom) and, where it helps, the fix. That local reasoning is
+what makes a comment actionable rather than a vague worry.
 
 ## What to check
 

package/skills/demo/SKILL.md

@@ -82,10 +82,18 @@ Author a `flow.json` (same shape as **browser-qa**) that scripts the
 interaction as a *director*, not an operator:
 
 - **Record the baseline first** — the starting state is act one.
-- **Hold after state changes** — add a `waitFor`/short pause so text is readable.
+- **Hold after state changes** — add a `{"pause": 1200}` (or `waitFor`) so the
+  result is readable before moving on.
 - **Verify between steps** — `waitFor` the expected element before the next
   action; don't blindly fire keys into an unsettled page.
 
+Because recording auto-enables the driver's **demo mode**, you get a visible
+**synthetic cursor** that animates to each target, and holds between steps —
+you don't script those. To make typing visible on screen, prefer **`type`**
+(character-by-character) over `fill` (instant) for any input the viewer should
+watch being filled. Tune pacing with `--step-delay` / `--type-delay` if a flow
+feels rushed or draggy (see the browser-qa skill).
+
 Record the session by passing `--record-dir`:
 
 ```bash
@@ -134,7 +142,7 @@ Composite the raw recording(s) into the final mp4 with the bundled wrapper:
   --output <artifact-dir>/demo.mp4 \
   --title "PR #42 — Add dark mode toggle" \
   --subtitle "Toggling persists the theme across reloads" \
-  --layout single --speed 1.5 \
+  --layout single --speed 1 \
   /tmp/demo-cap/session.webm
 
 # Before/after comparison — first clip = left/BEFORE, second = right/AFTER

package/skills/pr-review/SKILL.md

@@ -1,18 +1,21 @@
 ---
 name: pr-review
-description: Review a GitHub pull request and post one formal review — advance the existing discussion, verify by building, and give tiered feedback. Use when asked to review a PR or on a cron PR scan.
-version: 3.0.0
+description: Review a GitHub pull request and post one formal review — advance the existing discussion and give precision-first, high-signal feedback. A pure code review — no building. Use when asked to review a PR or on a cron PR scan.
+version: 5.0.0
 tags: [github, review, code-quality]
 ---
 
 # PR Review
 
-Review an open PR and post **one formal review**. Build and test the change for
-real — static reasoning alone is not a review of correctness.
+Review an open PR and post **one formal review** — high-signal findings only.
+This is a **pure code review**: read the change and reason about it. Do **not**
+install dependencies, build, or run tests — that is CI's job, and it validates
+whether the change actually works far more reliably than you re-running it here.
+Your job is judgement on the diff, not a build gate. A noisy review gets muted,
+so precision matters more than volume.
 
-This skill is the PR-specific procedure. It uses two shared skills: the
-**building** skill for installing and running the test/lint/typecheck gate, and
-the **code-review** skill for the finding tiers and what-to-check rubric.
+This skill is the PR-specific procedure. It uses the **code-review** skill for
+the precision bar and what-to-check rubric.
 
 ## Workspace
 
@@ -63,27 +66,32 @@ git diff --stat origin/<baseRef>...HEAD    # churn
 git diff origin/<baseRef>...HEAD           # the patch
 ```
 
-### 4. Verify by building
+### 4. Assess and submit
 
-Follow the **building** skill: install dependencies (install-first), then run the
-project's build and tests, and cite the real output in your findings. Any PR that
-touches code must be built and tested. The one exception is a pure style/docs PR,
-where building to nitpick formatting is wasted effort — skip it and say so.
+Apply the **code-review** skill's rubric — read each changed file in context;
+check correctness / edge-cases / security / regression-risk / test-coverage.
+Reason about the code statically; **don't build or run it** — trust CI to catch
+what only running reveals, and spend your effort on what a human reviewer sees.
+Follow that skill's **precision-first** rule: post **only Critical and Important**
+findings, each with a `path:line` reference and a one-line concrete impact (what
+breaks, for which input or caller) plus an inline code suggestion where it helps.
+Drop Suggestions and Nits.
 
-### 5. Assess and submit
+Before submitting, run the **confidence gate**: re-read each finding against the
+actual code and try to refute it; drop any you can't defend against what the code
+really does. A clean PR should be approved with few or no comments — that is a
+good review, not a lazy one.
 
-Apply the **code-review** skill's rubric — read each changed file in context,
-check correctness/edge-cases/security/regression-risk/test-coverage, and
-categorise findings into the tiers. Then write the review:
+Then write the review:
 
 - One or two sentences on what the PR does.
-- Findings grouped by tier, each with a `path:line` reference and an inline code
-  suggestion where it helps.
+- The surviving Critical/Important findings, each with its `path:line` + impact.
 - For a complex PR, an impact note (affected paths, regression risks).
 - An overall assessment, and thanks to the contributor.
 
 Submit with `github_create_pull_request_review` (a **formal** review, not a plain
-issue comment), event `APPROVE` / `REQUEST_CHANGES` / `COMMENT` to match.
+issue comment), event `APPROVE` / `REQUEST_CHANGES` / `COMMENT` to match what
+survived the gate.
 
 ## Verification
 

package/workflows/pr-review.yaml

@@ -13,8 +13,9 @@ description: |
 phases:
   - name: review
     label: Review
-    # pr-review: the PR procedure (primary). building: install + test gate.
-    # code-review: the finding-tier + what-to-check rubric.
-    skills: [pr-review, building, code-review]
+    # pr-review: the PR procedure (primary). code-review: the finding-tier +
+    # what-to-check rubric. No `building` — pr-review is a pure code review; CI
+    # validates that the change builds/runs.
+    skills: [pr-review, code-review]
     model: "{{models.review}}"
     variant: "{{variants.review}}"

package/workflows/prompts/demo.md

@@ -76,7 +76,10 @@ wrong — STOP and fix it; do not ship a side-by-side that proves nothing.{{/if}
 
 Author a `flow.json` (shape in the `browser-qa` skill) that scripts the
 interaction like a director — record the baseline first, hold after state
-changes, verify between steps. Record with `--record-dir`:
+changes (use `{"pause": 1200}` steps), verify between steps. Recording
+auto-enables the driver's demo mode, so a **visible cursor** animates to each
+target and a beat is held between steps — prefer `type` over `fill` so typing
+shows on screen. Record with `--record-dir`:
 
 ```
 node <browser-qa skill dir>/scripts/agent-browser.mjs run flow.json \
@@ -89,7 +92,7 @@ writing it into **`{{issueDir}}/demo.mp4`** (the harness harvests that dir):
 ```
 <demo skill dir>/scripts/compose-demo.sh \
   --output {{issueDir}}/demo.mp4 --title "<PR # — what it does>" \
-  --subtitle "<one line>" --layout single --speed 1.5 --target-size-mb 5 \
+  --subtitle "<one line>" --layout single --speed 1 --target-size-mb 5 \
   /tmp/demo-cap/session.webm
 ```
 

package/workflows/prompts/guardrails.md

@@ -10,6 +10,21 @@ THE ISSUE THIS BUILD WILL IMPLEMENT (use it to judge the escape hatch below):
 SKIP CHECK — if {{issueDir}}/status.md already exists and contains
 guardrails_status: READY, output "READY — guardrails already verified" and stop.
 
+INSTALL DEPENDENCIES FIRST (do this before running ANY check command):
+The harness pre-clones the repo but does NOT install dependencies, so the
+test/lint/typecheck binaries (vitest, oxlint, tsc, eslint, ruff, …) will not
+resolve until you install them. Detect the ecosystem and run the install:
+- Node — pick the package manager from the lockfile: `pnpm-lock.yaml` → `pnpm install`,
+  `yarn.lock` → `yarn install`, `package-lock.json` (or none) → `npm ci`
+  (fall back to `npm install` if `npm ci` fails for a lockfile mismatch).
+- Python — `pip install -e .` / `pip install -r requirements.txt`, or `poetry install` / `uv sync`.
+- Rust — cargo fetches on first build; no separate step.
+Only AFTER a successful install should you judge whether a command "runs". A
+binary that is missing *after* dependencies installed cleanly is a real gap; a
+binary missing *because deps were never installed* is NOT — do not BLOCK on it.
+If the install itself fails (bad lockfile, missing manifest), that IS a blocking
+guardrail — report it as such.
+
 CHECK THESE GUARDRAILS:
 
 1. **Test Framework** — Does the repo have a test runner (vitest, jest, pytest, cargo test, etc.)?