lastlight 0.7.5 → 0.7.7

package/skills/pr-review/SKILL.md

@@ -1,36 +1,42 @@
 ---
 name: pr-review
 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
+version: 7.0.0
 tags: [github, review, code-quality]
 ---
 
 # PR Review
 
-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.
+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.
+
+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
 
@@ -66,33 +72,77 @@ git diff --stat origin/<baseRef>...HEAD    # churn
 git diff origin/<baseRef>...HEAD           # the patch
 ```
 
-### 4. Assess and submit
+### 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: 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.
-
-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.
-
-Then write the review:
-
-- One or two sentences on what the PR does.
-- 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.
+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",
+  "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 what
-survived the gate.
+Write **only these content fields** — `skip?` / `summary` / `event` /
+`findings[]`. The follow-up step already knows the PR number, base ref, head
+SHA and diff from the harness's own context and the checkout, so you do **not**
+record any of that metadata (that reliance was a footgun — omit it).
+
+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`.
+- 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 and every finding
+carries `path` + `line`. The first-class `post-review` action then posts the
+review — anchoring each finding to its diff line, demoting any off-diff finding
+to the body, and logging how many landed inline vs in the body. If the file is
+missing after a real review (not a `skip`), that step **fails the run** loudly
+rather than posting nothing.

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

@@ -0,0 +1,89 @@
+# 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 first-class `post-review` action
+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 (git failure), **all** findings go into the
+  body — the review still posts, so nothing is lost.
+
+You write only the review **content** — `skip?` / `summary` / `event` /
+`findings[]`. The PR number, base ref, head SHA and diff come from the harness's
+own run context and the checkout, so you do **not** record any of that metadata.
+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 action 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. |
+| `findings` | array | yes | The surviving Critical/Important findings (may be empty). |
+
+## 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",
+  "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",
+  "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

@@ -16,6 +16,27 @@ phases:
     # 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 (content only: skip? / summary / event / findings[]) to
+    # .lastlight/pr-review/findings.json. The first-class `post-review` action
+    # below reads that file and posts one formal review.
     skills: [pr-review, code-review]
     model: "{{models.review}}"
     variant: "{{variants.review}}"
+
+  # First-class, in-process submission (type: post-review → PhaseExecutor.
+  # runPostReview). Reads the agent's findings.json for the review *content*
+  # (skip? / summary / event / findings[]) and supplies everything else from
+  # the harness itself — PR number (run context), base ref (baseBranch), head
+  # SHA + diff (the pre-cloned checkout) — so the AI never hand-copies metadata.
+  # It anchors each finding to a changed line, demotes off-diff findings to the
+  # body (GitHub 422s on off-diff lines), and posts ONE review via GitHubClient
+  # (App auth in prod; token + githubApiBaseUrl against the eval mock). A
+  # genuine failure — missing findings after a real review, or a GitHub error
+  # that survives the body-only retry — FAILS this phase visibly; a legitimate
+  # `skip` succeeds without posting. Idempotent on resume (no-op if a bot review
+  # already exists on the head SHA).
+  - name: post-review
+    label: Post inline review
+    type: post-review