next-issue 0.9.0 → 0.11.0

package/README.md

@@ -40,13 +40,21 @@ For each open issue, oldest first:
 7. On a red build, give the failed job logs to the fixer agent, then go to step
    6 again. The budget is `maxCiFixes`.
 8. Let the reviewer agent judge the diff, at most `diffMaxChars` of it. The
-   reviewer returns a structured verdict that rates each finding `blocking` or
-   `minor`. The harness puts the result on the pull request.
-9. No blocking finding means approval: mark the pull request ready for review
-   and set `status:done`. The merge stays with you. The worktree, the local
-   branch and the state file go away. The remote branch stays. A blocking
-   finding always stops the approval, even when the reviewer also says approve.
-10. With a blocking finding, run the fixer agent and go to step 6 again. The
+   reviewer reads files and runs commands in the worktree, so it can prove a
+   finding with the tests or the type check. The harness then throws away every
+   change that the reviewer left, so no such change can reach a later commit.
+   The reviewer returns a structured verdict that rates each finding `blocking`
+   or `minor`. The harness puts the result on the pull request.
+9. An open finding is any finding, blocking or minor, while a review round is
+   left. In the last round, only a blocking finding stays open: a minor finding
+   there goes on the pull request but starts no fix, because a fix in the last
+   round gets no review. Thus `maxReviewRounds` of `1` never fixes a minor
+   finding.
+10. No open finding means approval: mark the pull request ready for review and
+    set `status:done`. The merge stays with you. The worktree, the local branch
+    and the state file go away. The remote branch stays. An open finding always
+    stops the approval, even when the reviewer also says approve.
+11. With an open finding, run the fixer agent and go to step 6 again. The
     budget is `maxReviewRounds`.
 
 ## Stops for a loop
@@ -86,16 +94,20 @@ too, from the first review round. Thus a draft pull request shows work that the
 harness has not finished, and a `status:needs-human` pull request shows work
 that waits for a person.
 
-The harness runs all git and `gh` commands itself. The agents only read and
-change files. The commit holds all the changes in the worktree, so a setup
-command that writes a file outside `.gitignore` puts that file in the commit.
+The harness runs all git and `gh` commands itself. The commit holds all the
+changes in the worktree, so a setup command that writes a file outside
+`.gitignore` puts that file in the commit. The reviewer is the one agent whose
+changes never get that far: the harness discards them before it reads the
+verdict.
 
 ## Safety
 
-The implementer and the fixer run with the permission checks off. They start in
-the worktree, but nothing holds them there: they can run any command, with your
-rights, anywhere on the machine. The prompt holds the title, the body and the
-comments of the issue, which come from GitHub.
+Every agent can run a shell command. The implementer and the fixer run with the
+permission checks off; the reviewer runs with a smaller tool set, but its shell
+has no limit on the commands. They all start in the worktree, but nothing holds
+them there: they can run any command, with your rights, anywhere on the machine.
+The prompt holds the title, the body and the comments of the issue, which come
+from GitHub.
 
 Thus a person who can write an issue or a comment can try to give an
 instruction to the agent. Use the harness only on a repository where you trust
@@ -158,8 +170,8 @@ npx -y next-issue@latest init
 
 The command writes `next-issue.config.json` in the root of the repository and
 adds `.next-issue/` to `.gitignore`. It stops when the config file is there
-already; `--force` replaces it. The file holds no `setupCommand`, because that
-field has no default.
+already; `--force` replaces it. The file holds no `setupCommand`, because the
+harness deduces one from the lock file of the project.
 
 A field that is not in the file keeps its default. A file that is not valid
 JSON, a field with a value of the wrong type and a field name that the harness
@@ -209,7 +221,7 @@ does not know all stop the run, so a typo cannot pass without a word.
 | `diffMaxChars` | `60000` | The maximum length of the diff that the reviewer reads |
 | `keepRunDays` | `7` | The number of days to keep the run files; `0` keeps them all |
 | `draftPullRequest` | `true` | Open the pull request as a draft, until the review approves |
-| `setupCommand` | none | A shell command to run in a new worktree, before the implementer |
+| `setupCommand` | from the lock file | A shell command to run in a new worktree, before the implementer |
 | `models` | `{}` | The model per agent role |
 | `labels` | see above | The names of the labels that the harness reads and sets |
 
@@ -219,8 +231,30 @@ claims every open issue that no other label and no assignee holds back.
 The log gives the reason for a skipped issue as `stop-label`, `not-ready`,
 `in-flight` or `assigned`.
 
-A role without an entry in `models` uses the default model of the SDK. A
-`setupCommand` that fails, or that does not finish in `setupTimeoutMinutes`,
+A role without an entry in `models` uses the default model of the SDK.
+
+Without a `setupCommand`, the harness looks in the new worktree for a lock file
+and runs the install command that goes with it:
+
+| Lock file | Command |
+| --- | --- |
+| `pnpm-lock.yaml` | `pnpm install --frozen-lockfile` |
+| `package-lock.json` | `npm ci` |
+| `yarn.lock` | `yarn install --frozen-lockfile`, or `yarn install --immutable` with a `.yarnrc.yml` |
+| `bun.lock`, `bun.lockb` | `bun install --frozen-lockfile` |
+| `Cargo.lock` | `cargo fetch` |
+| `go.sum` | `go mod download` |
+| `uv.lock` | `uv sync` |
+| `poetry.lock` | `poetry install` |
+| `Gemfile.lock` | `bundle install` |
+
+The first match in that order wins. A project with no lock file in the list
+runs no setup, and a `setupCommand` in the config file always wins. Thus the
+agents find a worktree with its dependencies in place, and the reviewer can run
+the tests. Each command holds to the lock file, so a lock file that does not
+match the manifest stops the issue rather than changing the lock file.
+
+A `setupCommand` that fails, or that does not finish in `setupTimeoutMinutes`,
 hands the issue to a person. The wait for the checks has its own limit, so
 `commandTimeoutMinutes` holds for every other `git` and `gh` command. State per
 issue goes to `.next-issue/<issue>.json`, so a new run continues where the last

package/dist/agents.mjs

@@ -1,7 +1,7 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { emptyUsage } from "./observe.mjs";
-const READ_ONLY = {
-    tools: ["Read", "Grep", "Glob"],
+const REVIEWING = {
+    tools: ["Read", "Grep", "Glob", "Bash"],
     permissionMode: "dontAsk",
 };
 const CODING = {
@@ -9,7 +9,7 @@ const CODING = {
     permissionMode: "bypassPermissions",
     allowDangerouslySkipPermissions: true,
 };
-export { CODING, READ_ONLY };
+export { CODING, REVIEWING };
 export async function runAgent(recorder, request) {
     const log = recorder.scope({ role: request.name });
     const usage = emptyUsage();

package/dist/cli.mjs

@@ -11,6 +11,7 @@ import { message, pruneRuns, Recorder } from "./observe.mjs";
 import { PORTS, processIssue } from "./pipeline.mjs";
 import { STATE_DIR, takeStop } from "./state.mjs";
 import { formatSummary } from "./summary.mjs";
+import { packageVersion } from "./version.mjs";
 function write(stream, text) {
     return new Promise((resolve, reject) => {
         stream.write(text, (error) => (error === null || error === undefined ? resolve() : reject(error)));
@@ -61,7 +62,13 @@ async function init(root, force) {
 async function handle(args, config, repo, recorder) {
     const [base, login] = await Promise.all([defaultBranch(repo), currentLogin(repo)]);
     const context = { repo, config, base, login, reset: args.reset, recorder, ports: PORTS };
-    recorder.event("run.start", { repo: `${repo.owner}/${repo.name}`, base, login, log: recorder.logFile }, "quiet");
+    recorder.event("run.start", {
+        version: await packageVersion(),
+        repo: `${repo.owner}/${repo.name}`,
+        base,
+        login,
+        log: recorder.logFile,
+    }, "quiet");
     const issues = await openIssues(repo, config.issueLimit);
     recorder.event("issues", { open: issues.length }, "quiet");
     const { reports, stoppedAt } = await runIssues(args, {

package/dist/git.mjs

@@ -100,6 +100,14 @@ export async function commitAll(cwd, message) {
     await must("git", ["commit", "-m", message], { cwd });
     return true;
 }
+export async function discardChanges(cwd) {
+    if (!(await isDirty(cwd))) {
+        return false;
+    }
+    await must("git", ["checkout", "--", "."], { cwd });
+    await must("git", ["clean", "-fd"], { cwd });
+    return true;
+}
 export async function push(cwd, remote, branch) {
     await must("git", ["push", "-u", remote, branch], { cwd });
 }

package/dist/pipeline.mjs

@@ -1,12 +1,13 @@
-import { CODING, READ_ONLY, runAgent } from "./agents.mjs";
+import { CODING, REVIEWING, runAgent } from "./agents.mjs";
 import { managedLabels } from "./config.mjs";
 import { run } from "./exec.mjs";
-import { addWorktree, branchName, commitAll, deleteBranch, diff, hasWorktree, push, removeWorktree, revision, worktreePath, } from "./git.mjs";
+import { addWorktree, branchName, commitAll, deleteBranch, diff, discardChanges, hasWorktree, push, removeWorktree, revision, worktreePath, } from "./git.mjs";
 import { assignIssue, commentOnPr, createPr, failedCheckLogs, findPr, issueComments, markPrReady, setLabel, waitForChecks, } from "./github.mjs";
 import { message } from "./observe.mjs";
 import { capDiff, fixPrompt, implementPrompt, parseCommitSubject, parseUnrelated, reviewPrompt, } from "./prompts.mjs";
+import { detectSetupCommand } from "./setup.mjs";
 import { dropState, readState, resetState, writeState, } from "./state.mjs";
-import { blockingFindings, fingerprint, formatFindings, formatVerdict, isApproved, readVerdict, VERDICT_SCHEMA, } from "./verdict.mjs";
+import { blockingFindings, fingerprint, formatFindings, formatVerdict, openFindings, readVerdict, VERDICT_SCHEMA, } from "./verdict.mjs";
 export const PORTS = {
     addWorktree,
     assignIssue,
@@ -14,7 +15,9 @@ export const PORTS = {
     commitAll,
     createPr,
     deleteBranch,
+    detectSetupCommand,
     diff,
+    discardChanges,
     failedCheckLogs,
     findPr,
     hasWorktree,
@@ -120,8 +123,9 @@ async function work(context, issue, log, state) {
             ms: Date.now() - started,
         };
     };
-    if (config.setupCommand !== undefined) {
-        const setup = await log.step("setup", { cmd: config.setupCommand }, () => ports.runSetup(config.setupCommand, worktree, config.setupTimeoutMinutes * 60_000));
+    const setupCommand = config.setupCommand ?? (await ports.detectSetupCommand(worktree));
+    if (setupCommand !== undefined) {
+        const setup = await log.step("setup", { cmd: setupCommand, found: config.setupCommand === undefined }, () => ports.runSetup(setupCommand, worktree, config.setupTimeoutMinutes * 60_000));
         if (setup.code !== 0) {
             const late = setup.timedOut === true;
             log.event("setup.fail", { code: setup.code, timedOut: late, stderr: setup.stderr.trim().slice(-2000) }, "quiet");
@@ -224,26 +228,31 @@ async function work(context, issue, log, state) {
             name: "reviewer",
             cwd: worktree,
             prompt: reviewPrompt(issue, comments, patch, history(state.reviewLog)),
-            profile: READ_ONLY,
+            profile: REVIEWING,
             model: config.models.reviewer,
             timeoutMs: config.agentTimeoutMinutes * 60_000,
             outputSchema: VERDICT_SCHEMA,
         }));
+        if (await ports.discardChanges(worktree)) {
+            log.event("review.discard", { round: state.reviewRounds }, "quiet");
+        }
         const verdict = readVerdict(review.structured);
         if (verdict === undefined) {
             await escalate("The reviewer gave no verdict.");
             return finish("needs-human", "no verdict");
         }
         const blocking = blockingFindings(verdict);
+        const open = openFindings(verdict, state.reviewRounds >= config.maxReviewRounds);
         log.event("verdict", {
             round: state.reviewRounds,
             verdict: verdict.verdict,
             blocking: blocking.length,
             minor: verdict.findings.length - blocking.length,
+            open: open.length,
             summary: verdict.summary,
         }, "quiet");
-        await ports.commentOnPr(repo, state.pr, formatVerdict(verdict));
-        if (isApproved(verdict)) {
+        await ports.commentOnPr(repo, state.pr, formatVerdict(verdict, open));
+        if (open.length === 0) {
             const after = await gate();
             if (after.done) {
                 return after.report;
@@ -257,15 +266,15 @@ async function work(context, issue, log, state) {
             await setStatus(context, issue.number, state.pr, config.labels.done);
             return finish("done");
         }
-        const mark = fingerprint(blocking);
+        const mark = fingerprint(open);
         if (state.reviewLog.some((round) => round.fingerprint === mark)) {
             await escalate("The reviewer repeated findings that an earlier round did not fix.");
             return finish("needs-human", "repeated findings");
         }
         const earlier = history(state.reviewLog);
-        state.reviewLog.push({ round: state.reviewRounds, fingerprint: mark, findings: formatFindings(blocking) });
+        state.reviewLog.push({ round: state.reviewRounds, fingerprint: mark, findings: formatFindings(open) });
         await writeState(repo, state);
-        const fix = await fixRound(job, "The reviewer requested changes.", formatFindings(blocking), earlier, "review");
+        const fix = await fixRound(job, "The reviewer requested changes.", formatFindings(open), earlier, "review");
         if (!fix.committed) {
             await escalate("The fixer added no commit for the review findings.");
             return finish("needs-human", "no fix commit");

package/dist/prompts.mjs

@@ -43,7 +43,9 @@ export function reviewPrompt(issue, comments, diff, earlier) {
         diff,
         "```",
         "## Rules",
-        "Read files for context when you must. Do not change any file.",
+        "Read files and run commands to prove what you say: the tests, the type check or the linter.",
+        "The worktree is ready to use. Do not change a file. Do not write with git or gh.",
+        "The harness discards each change that you make, so a change is only lost work.",
         scope,
         "Mark a finding blocking only for a wrong result, a missing part of the issue, a regression or a broken convention.",
         "Give the result as the structured output: the verdict, a short summary and one entry per finding.",

package/dist/setup.mjs

@@ -0,0 +1,27 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+const MARKERS = [
+    ["pnpm-lock.yaml", "pnpm install --frozen-lockfile"],
+    ["package-lock.json", "npm ci"],
+    [".yarnrc.yml", "yarn install --immutable"],
+    ["yarn.lock", "yarn install --frozen-lockfile"],
+    ["bun.lock", "bun install --frozen-lockfile"],
+    ["bun.lockb", "bun install --frozen-lockfile"],
+    ["Cargo.lock", "cargo fetch"],
+    ["go.sum", "go mod download"],
+    ["uv.lock", "uv sync"],
+    ["poetry.lock", "poetry install"],
+    ["Gemfile.lock", "bundle install"],
+];
+export async function detectSetupCommand(root) {
+    for (const [file, command] of MARKERS) {
+        try {
+            await access(join(root, file));
+            return command;
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}

package/dist/verdict.mjs

@@ -55,13 +55,18 @@ export function readVerdict(value) {
 export function blockingFindings(verdict) {
     return verdict.findings.filter((finding) => finding.severity === "blocking");
 }
-export function isApproved(verdict) {
-    return blockingFindings(verdict).length === 0;
+export function openFindings(verdict, lastRound) {
+    return lastRound ? blockingFindings(verdict) : verdict.findings;
 }
-export function formatVerdict(verdict) {
-    const head = isApproved(verdict) ? "Review: approved" : "Review: changes requested";
+const LEFT = "The findings above stay as they are: no blocking finding is open and the review budget is spent.";
+export function formatVerdict(verdict, open) {
+    const approved = open.length === 0;
+    const head = approved ? "Review: approved" : "Review: changes requested";
     const lines = verdict.findings.map((finding) => `- **${finding.severity}** ${finding.detail}`);
-    return [`### ${head}`, verdict.summary, lines.join("\n")].filter((part) => part.length > 0).join("\n\n");
+    const note = approved && verdict.findings.length > 0 ? LEFT : "";
+    return [`### ${head}`, verdict.summary, lines.join("\n"), note]
+        .filter((part) => part.length > 0)
+        .join("\n\n");
 }
 export function formatFindings(findings) {
     return findings.map((finding) => `- ${finding.detail}`).join("\n");

package/dist/version.mjs

@@ -0,0 +1,6 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export async function packageVersion() {
+    const raw = await readFile(join(import.meta.dirname, "..", "package.json"), "utf8");
+    return JSON.parse(raw).version;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-issue",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Autonomous issue harness driven by the Claude Agent SDK",
   "keywords": [
     "github",