lastlight 0.7.4 → 0.7.6

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,33 +1,42 @@
 ---
 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: 6.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 — 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.
+You do **not** post the review yourself. You write your findings to a JSON file
+(`.lastlight/pr-review/findings.json`) and a deterministic follow-up step posts
+one formal review, anchoring each finding to its diff line as an inline comment
+(§4).
+
+This skill is the PR-specific procedure. It uses the **code-review** skill for
+the precision bar and what-to-check rubric.
 
 ## Workspace
 
-The harness pre-clones the PR's head ref into a `<repo>/` **subdirectory** of
-your cwd (the cwd holds `AGENTS.md`; the repo is one level deeper). `ls -la` —
-if you see `<repo>/.git/`, `cd <repo>` and use git directly. To refresh:
+The harness pre-clones the PR's head ref and drops you **inside the checkout** —
+your cwd **is** the repo (`ls -la` shows `.git/` directly; `AGENTS.md` is the
+sibling one level up at `../`). Use `git`/`read`/`grep` from here. To refresh:
 `git fetch origin <branch> --depth 50 && git reset --hard FETCH_HEAD`. If the
-pre-clone is missing, `git clone https://github.com/{{owner}}/{{repo}}.git {{repo}}`.
+checkout is somehow missing, `git clone https://github.com/{{owner}}/{{repo}}.git .`.
 
 **Read code from this local checkout, never the API.** Use `git`/`read`/`grep`
 on disk for the diff and file contents. Do **not** call
 `github_get_pull_request_diff`, `github_list_pull_request_files`, or
 `github_get_file_contents` — the API patch is a large redundant payload that
 re-bloats context every turn. The `github_*` tools are for *API* operations only
-(metadata, comments, posting the review).
+(reading metadata + prior comments in §1–2). You never post the review via a
+tool — you write the findings file and the follow-up step posts it.
 
 ## Procedure
 
@@ -63,28 +72,75 @@ git diff --stat origin/<baseRef>...HEAD    # churn
 git diff origin/<baseRef>...HEAD           # the patch
 ```
 
-### 4. Verify by building
-
-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.
-
-### 5. Assess and submit
-
-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:
-
-- 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.
-- For a complex PR, an impact note (affected paths, regression risks).
-- An overall assessment, and thanks to the contributor.
+### 4. Assess and write your findings
+
+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: keep **only Critical and Important**
+findings, each anchored to a `path:line` with a one-line concrete impact (what
+breaks, for which input or caller). Drop Suggestions and Nits.
+
+Before writing anything, 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
+findings — that is a good review, not a lazy one.
+
+**Do not call `github_create_pull_request_review` (or any review-submitting
+tool).** Write your findings to `.lastlight/pr-review/findings.json` instead. A
+deterministic follow-up step reads that file and posts one formal review with
+your findings as inline comments anchored to the diff. The full contract with
+worked examples is in [references/findings-schema.md](references/findings-schema.md);
+the shape is:
+
+```json
+{
+  "skip": false,
+  "summary": "One or two sentences on what the PR does + overall assessment.",
+  "event": "COMMENT",
+  "base_ref": "main",
+  "head_sha": "<PR head SHA>",
+  "findings": [
+    {
+      "path": "src/foo.ts",
+      "line": 42,
+      "side": "RIGHT",
+      "severity": "Critical",
+      "title": "Short label for the finding",
+      "body": "Concrete impact — what breaks, for which input or caller.",
+      "suggestion": "exact replacement text for the anchored line(s)"
+    }
+  ]
+}
+```
 
-Submit with `github_create_pull_request_review` (a **formal** review, not a plain
-issue comment), event `APPROVE` / `REQUEST_CHANGES` / `COMMENT` to match.
+Rules:
+- **Anchor precisely.** `path` must match the diff path exactly; `line`/`side`
+  must point at a line that appears in the diff (added/context → `side: RIGHT`;
+  removed/context → `side: LEFT`). A finding whose line isn't in the diff is
+  demoted to the summary body, so get the anchor right. Use optional `start_line`
+  (same side) for a multi-line range.
+- `severity` is `Critical` or `Important` only.
+- `suggestion` is optional — include it only when a concrete one-to-few-line fix
+  is obvious. It must be the exact replacement text for the anchored line(s),
+  nothing else; GitHub renders it as an applyable suggestion.
+- `event` is `APPROVE` / `REQUEST_CHANGES` / `COMMENT`, matching what survived
+  the gate. A clean PR is an `APPROVE` with an empty `findings` array and a short
+  `summary`.
+- `base_ref` and `head_sha` come from the `github_get_pull_request` call in §1 —
+  no extra API call. They are **mandatory**: without them the follow-up step
+  can't compute the diff and demotes every finding to the body.
+- Create the dir and keep the file out of git first:
+  `mkdir -p .lastlight/pr-review && echo '.lastlight/' >> .git/info/exclude`.
+
+**Stop / skip:** if a stop condition in §1 holds (bot-authored, merged, already
+reviewed at the current head SHA), write `{"skip": true, "summary": "<reason>"}`
+and stop — the follow-up step then posts nothing.
 
 ## Verification
 
-Confirm the review posted by checking the PR's reviews list.
+Confirm `.lastlight/pr-review/findings.json` is valid JSON, has `base_ref` +
+`head_sha`, and every finding carries `path` + `line`. The deterministic
+follow-up step posts the review and logs how many findings landed inline vs in
+the body.

package/skills/pr-review/references/findings-schema.md

@@ -0,0 +1,95 @@
+# PR review findings schema
+
+The `pr-review` skill writes its findings to `.lastlight/pr-review/findings.json`
+(relative to the repo checkout — your cwd). The deterministic `post-review`
+workflow phase reads this file and posts **one** formal GitHub review:
+
+- Each finding whose `line`/`side` anchors to a line that appears in the PR diff
+  becomes an **inline comment** on that exact line.
+- Any finding whose anchor isn't in the diff is **demoted** into the review body
+  under an "Additional findings" heading (GitHub rejects comments off the diff).
+- If the diff can't be computed (missing `base_ref`, git failure), **all**
+  findings go into the body — the review still posts, so nothing is lost.
+
+You never call `github_create_pull_request_review` yourself. Writing this file is
+how you submit.
+
+## Top-level object
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `skip` | boolean | no | `true` → you decided not to review (bot-authored / merged / already reviewed at head). The follow-up step posts nothing. |
+| `summary` | string | yes | One or two sentences on what the PR does + your overall assessment. Becomes the review body. |
+| `event` | string | yes | `APPROVE` \| `REQUEST_CHANGES` \| `COMMENT`. A clean PR is `APPROVE` with an empty `findings` array. |
+| `base_ref` | string | yes | The PR base branch (e.g. `main`), from the `github_get_pull_request` call. Used to compute the diff for anchoring. |
+| `head_sha` | string | yes | The PR head SHA, from the same call. Pins the review to the reviewed commit. |
+| `findings` | array | yes | The surviving Critical/Important findings (may be empty). |
+
+`base_ref` and `head_sha` are mandatory — without them the follow-up step can't
+compute the diff and demotes every finding to the body.
+
+## Finding object
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `path` | string | yes | Repo-relative file path, matching the diff path exactly. |
+| `line` | number | yes | Line number on `side` that the comment anchors to. Must appear in the diff. |
+| `side` | string | no | `RIGHT` (added/context line — default) or `LEFT` (removed/context line). |
+| `start_line` | number | no | Start of a multi-line range (same `side` as `line`). |
+| `severity` | string | yes | `Critical` or `Important` only. |
+| `title` | string | yes | Short label for the finding. |
+| `body` | string | yes | Concrete impact — what breaks, for which input or caller. |
+| `suggestion` | string | no | Exact replacement text for the anchored line(s). Rendered as an applyable ```suggestion block. Include only when a concrete one-to-few-line fix is obvious. |
+
+## Example — findings with an inline suggestion
+
+```json
+{
+  "skip": false,
+  "summary": "Adds a `--config` flag to the CLI and threads it into the connect path. Solid overall; one crash on the default path and one missing-await.",
+  "event": "REQUEST_CHANGES",
+  "base_ref": "main",
+  "head_sha": "9f3c1a2b7d4e5f60112233445566778899aabbcc",
+  "findings": [
+    {
+      "path": "src/cli.ts",
+      "line": 42,
+      "side": "RIGHT",
+      "severity": "Critical",
+      "title": "Null deref when --config is omitted",
+      "body": "`cfg.host` is undefined when no config file is passed, so every default-path invocation throws before connecting.",
+      "suggestion": "const host = cfg.host ?? DEFAULT_HOST;"
+    },
+    {
+      "path": "src/connect.ts",
+      "line": 88,
+      "side": "RIGHT",
+      "severity": "Important",
+      "title": "Missing await on disconnect()",
+      "body": "`disconnect()` returns a promise that's never awaited, so the socket can leak if the caller exits immediately after."
+    }
+  ]
+}
+```
+
+## Example — clean PR (approve, no findings)
+
+```json
+{
+  "skip": false,
+  "summary": "Small, well-tested refactor of the retry helper. No correctness or regression concerns.",
+  "event": "APPROVE",
+  "base_ref": "main",
+  "head_sha": "1122334455667788990011223344556677889900",
+  "findings": []
+}
+```
+
+## Example — skip (already reviewed this SHA)
+
+```json
+{
+  "skip": true,
+  "summary": "A last-light[bot] review already exists on the current head SHA; nothing new to add."
+}
+```

package/workflows/pr-review.yaml

@@ -13,8 +13,155 @@ 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.
+    #
+    # The agent does NOT submit the review itself — it writes structured
+    # findings to .lastlight/pr-review/findings.json (the "reference"). The
+    # deterministic `post-review` phase below reads that file and posts one
+    # formal review with the findings as line-anchored inline comments.
+    skills: [pr-review, code-review]
     model: "{{models.review}}"
     variant: "{{variants.review}}"
+
+  # Deterministic submission step: read the agent's findings.json and post ONE
+  # formal PR review, anchoring each finding to its diff line where possible and
+  # demoting off-diff findings to the summary body (GitHub 422s on off-diff
+  # lines). Terminal + always exits 0 — a posting hiccup must not fail an
+  # otherwise-good review (errors go to stderr, captured in the session log).
+  # owner/repo come from the template context; pr_number/base_ref/head_sha come
+  # from findings.json (the agent recorded them from github_get_pull_request).
+  # GITHUB_TOKEN is the run's minted review-write token; in evals the harness
+  # injects GITHUB_API_URL pointing at the mock so the review lands there.
+  - name: post-review
+    label: Post inline review
+    type: script
+    runtime: js
+    timeout_seconds: 120
+    script: |
+      import { readFileSync } from "node:fs";
+      import { execFileSync } from "node:child_process";
+
+      const api = (process.env.GITHUB_API_URL || "https://api.github.com").replace(/\/+$/, "");
+      const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
+      const owner = "{{owner}}";
+      const repo = "{{repo}}";
+      const log = (m) => process.stderr.write("[post-review] " + m + "\n");
+
+      let doc;
+      try {
+        doc = JSON.parse(readFileSync(".lastlight/pr-review/findings.json", "utf8"));
+      } catch (e) {
+        log("no readable findings.json (" + e.message + "); nothing to post");
+        process.exit(0);
+      }
+      if (doc.skip) { log("skip: " + (doc.summary || "agent skipped review")); process.exit(0); }
+
+      const prNumber = doc.pr_number;
+      const baseRef = doc.base_ref;
+      const headSha = doc.head_sha;
+      const findings = Array.isArray(doc.findings) ? doc.findings : [];
+      if (!prNumber) { log("findings.json missing pr_number; cannot post"); process.exit(0); }
+
+      // path -> Set of "SIDE:line". "+"/context are RIGHT:newLine; "-"/context
+      // are LEFT:oldLine. Mirrors GitHub's three-dot PR diff anchoring.
+      function parseDiff(diff) {
+        const map = new Map();
+        let path = null, right = 0, left = 0, inHunk = false;
+        for (const line of diff.split("\n")) {
+          if (line.startsWith("+++ ")) {
+            const p = line.slice(4).replace(/^b\//, "");
+            path = p === "/dev/null" ? null : p;
+            if (path && !map.has(path)) map.set(path, new Set());
+            inHunk = false;
+          } else if (line.startsWith("@@")) {
+            const m = /@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+            if (m) { left = parseInt(m[1], 10); right = parseInt(m[2], 10); inHunk = true; }
+          } else if (inHunk && path) {
+            const set = map.get(path);
+            if (line.startsWith("+")) { set.add("RIGHT:" + right); right++; }
+            else if (line.startsWith("-")) { set.add("LEFT:" + left); left++; }
+            else if (line.startsWith(" ")) { set.add("RIGHT:" + right); set.add("LEFT:" + left); right++; left++; }
+            else if (line.startsWith("\\")) { /* "" */ }
+            else { inHunk = false; }
+          }
+        }
+        return map;
+      }
+
+      // Commentable line set from the local checkout. Failure → null → demote all
+      // to the body (the review still posts; the judge/human still sees findings).
+      let commentable = null;
+      if (baseRef) {
+        try {
+          try { execFileSync("git", ["fetch", "origin", baseRef, "--depth", "50"], { stdio: "ignore" }); } catch {}
+          const diff = execFileSync("git", ["diff", "origin/" + baseRef + "...HEAD"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+          commentable = parseDiff(diff);
+        } catch (e) {
+          log("git diff failed (" + e.message + "); demoting all findings to the body");
+        }
+      }
+
+      const anchored = (f) => {
+        if (!commentable) return false;
+        const side = f.side === "LEFT" ? "LEFT" : "RIGHT";
+        const set = commentable.get(f.path);
+        if (!set || !set.has(side + ":" + f.line)) return false;
+        if (f.start_line && !set.has(side + ":" + f.start_line)) return false;
+        return true;
+      };
+
+      const inline = [], demoted = [];
+      for (const f of findings) {
+        if (f && f.path && f.line && anchored(f)) inline.push(f);
+        else if (f) demoted.push(f);
+      }
+
+      const FENCE = "```";
+      const commentBody = (f) => {
+        let b = "**[" + (f.severity || "Important") + "] " + (f.title || "") + "**\n\n" + (f.body || "");
+        if (f.suggestion) b += "\n\n" + FENCE + "suggestion\n" + f.suggestion + "\n" + FENCE;
+        return b;
+      };
+      const renderDemoted = (list) => list.length
+        ? "\n\n### Additional findings\n" + list.map((f) =>
+            "- **[" + (f.severity || "Important") + "] " + (f.title || "") + "** (" + f.path + ":" + f.line + ") — " + (f.body || "")).join("\n")
+        : "";
+      const buildComments = (list) => list.map((f) => {
+        const side = f.side === "LEFT" ? "LEFT" : "RIGHT";
+        const c = { path: f.path, line: f.line, side, body: commentBody(f) };
+        if (f.start_line) { c.start_line = f.start_line; c.start_side = side; }
+        return c;
+      });
+
+      const event = doc.event || (findings.length === 0 ? "APPROVE" : "COMMENT");
+      async function postReview(comments, extraBody) {
+        const payload = { body: (doc.summary || "") + (extraBody || ""), event, comments };
+        if (headSha) payload.commit_id = headSha;
+        return fetch(api + "/repos/" + owner + "/" + repo + "/pulls/" + prNumber + "/reviews", {
+          method: "POST",
+          headers: {
+            "Authorization": "Bearer " + token,
+            "Accept": "application/vnd.github+json",
+            "Content-Type": "application/json",
+            "User-Agent": "last-light",
+            "X-GitHub-Api-Version": "2022-11-28",
+          },
+          body: JSON.stringify(payload),
+        });
+      }
+
+      let res = await postReview(buildComments(inline), renderDemoted(demoted));
+      if (!res.ok) {
+        const t = await res.text().catch(() => "");
+        log("inline review POST failed (" + res.status + "): " + t.slice(0, 300) + "; retrying body-only");
+        res = await postReview([], renderDemoted([...inline, ...demoted]));
+        if (!res.ok) {
+          const t2 = await res.text().catch(() => "");
+          log("body-only review POST also failed (" + res.status + "): " + t2.slice(0, 300));
+          process.exit(0);
+        }
+      }
+      log("posted review: " + inline.length + " inline, " + demoted.length + " in body, event=" + event);
+      process.exit(0);

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.)?