@mergeline/agent 0.7.3 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -15,10 +15,10 @@ committing. Nothing technical is needed from the person.
15
15
  ## By hand
16
16
 
17
17
  ```sh
18
- npx -y @mergeline/agent init --claude --url https://acme.mergeline.app # once per repository; commit what it adds
19
- npx -y @mergeline/agent login fe-1 --url https://acme.mergeline.app --key ab_... # once per agent and machine
20
- npx -y @mergeline/agent start fe-1 # every session; then /pick
21
- npx -y @mergeline/agent watch --agent fe-1 --engine claude --follow # or unattended: the worker
18
+ npx -y @mergeline/agent@latest init --claude --url https://acme.mergeline.app # once per repository; commit what it adds
19
+ npx -y @mergeline/agent@latest login fe-1 --url https://acme.mergeline.app --key ab_... # once per agent and machine
20
+ npx -y @mergeline/agent@latest start fe-1 # every session; then /pick
21
+ npx -y @mergeline/agent@latest watch --agent fe-1 --engine claude --follow # or unattended: the worker
22
22
  ```
23
23
 
24
24
  `init --url` writes the board's address into `.mergeline.json` (no
@@ -82,11 +82,11 @@ prefix, so it stopped nothing; it adds a `board` server to
82
82
  environment, or else the key `login` saved: the key is never written to the
83
83
  repository.
84
84
 
85
- What the agent may run without asking (kit 5, in `.claude/settings.json`):
85
+ What the agent may run without asking (kit 6, in `.claude/settings.json`):
86
86
 
87
87
  - the board's MCP tools, and `board` (or `npx -y @mergeline/agent`) with
88
- `claim`, `heartbeat`, `log`, `record-spec`, `ask`, `submit`, `release`,
89
- `list`, `whoami`, `help`; Claude Code asks the person for `start`,
88
+ `claim`, `heartbeat`, `log`, `record-spec`, `ask`, `report`, `submit`,
89
+ `release`, `list`, `whoami`, `help`; Claude Code asks the person for `start`,
90
90
  `watch`, `login`, `init` and `mcp`;
91
91
  - `git fetch origin ...`, `git show`, `git rev-parse`, `git status`,
92
92
  `git diff` (inside the working tree), `git log`, `git add`,
@@ -122,7 +122,7 @@ MCP config (Claude Code `--mcp-config`, Codex, other MCP clients):
122
122
  "mcpServers": {
123
123
  "board": {
124
124
  "command": "npx",
125
- "args": ["-y", "@mergeline/agent", "mcp"],
125
+ "args": ["-y", "@mergeline/agent@latest", "mcp"],
126
126
  "env": { "BOARD_URL": "https://board.example.com", "BOARD_AGENT_KEY": "ab_..." }
127
127
  }
128
128
  }
@@ -152,8 +152,9 @@ is on origin, else from `origin/main`) and writes the ticket to
152
152
  `.mergeline-run/ticket.md` there (git ignores the folder). The engine
153
153
  (`claude -p`, or `codex exec --json`, with the package's own prompt,
154
154
  `engine/prompt.md`) writes a
155
- plan, progress lines and, last, `.mergeline-run/result.json`: done, a
156
- question, or a release. The worker heartbeats, commits what the engine left
155
+ plan, progress lines and, last, `.mergeline-run/result.json` (at most 256
156
+ KB): done, a question, or a release, with any defects outside the ticket as
157
+ `reports` (below). The worker heartbeats, commits what the engine left
157
158
  uncommitted, runs the repository's `test` command when `.mergeline.json` on
158
159
  `main` has one (`"test": "npm test"`, added by hand), pushes, opens or
159
160
  reuses the PR with `gh`, and submits; or pushes the work so far and asks;
@@ -269,7 +270,7 @@ when it updates the file (0.7.1 and later):
269
270
  ```json
270
271
  {
271
272
  "board": "https://acme.mergeline.app",
272
- "kit": 5,
273
+ "kit": 6,
273
274
  "test": "npm test",
274
275
  "review": "docs/review-rules.md"
275
276
  }
@@ -354,9 +355,38 @@ reported at once (exit 1), so a wrong address is not waited for.
354
355
  Commands: `init`, `watch`, `whoami`, `list`, `claim`, `heartbeat <ticket> [note]`,
355
356
  `log <ticket> <plan|progress|warn> <text>`, `record-spec <ticket> <sha>`,
356
357
  `ask <ticket> <question>`, `submit <ticket> <pr-url> <summary> [--usage <json>]`,
357
- `release <ticket> <reason> [--usage <json>]`. `board help` shows the details.
358
+ `release <ticket> <reason> [--usage <json>]`,
359
+ `report <ticket> --fingerprint <key> --title <title> (--body <text> | --body-file <path>)`.
360
+ `board help` shows the details.
358
361
  Results are JSON on stdout; a failure is one line on stderr and exit code 1.
359
362
 
363
+ ### Reporting a defect outside the ticket
364
+
365
+ An agent that sees a defect outside its ticket reports it instead of fixing
366
+ it: the MCP tool `report_finding` (`ticket_id`, `title`, `body`,
367
+ `fingerprint`) or `board report` (with the saved session; `--body-file`
368
+ reads a file of at most 20,000 characters; both or neither of `--body` and
369
+ `--body-file` is a usage error, exit 2). The item lands in the board's
370
+ Inbox, where a person reads it; no agent does. The answer is
371
+ `{"known": false, "ticket": "T-80"}`, or `{"known": true}` when that
372
+ `fingerprint` (the file's path and what is wrong, for example
373
+ `scripts/smoke.ts: port check is flaky`) was reported before. At most 3 new
374
+ items a run (the board answers 429 after that). A board from before this
375
+ (0.8.0) says "this board does not take reports yet: it needs an update", or
376
+ "... from a session yet ..." when it takes them only from the worker.
377
+
378
+ Under the worker the engine has no board tools: it puts its reports in
379
+ `.mergeline-run/result.json` (a developer) or `review.json` (a reviewer) as
380
+ `"reports"`, a list of `{"title", "body", "fingerprint"}`. `result.json`
381
+ may be 256 KB, as `review.json` is. The worker sends the first 3 good
382
+ entries by the run, before it submits, asks, releases or sends the review,
383
+ whatever the outcome; an entry that is not three non-empty strings within
384
+ the board's bounds is skipped with a log line naming its number. A report
385
+ never fails the run: a refusal is logged and the worker goes on (after a
386
+ 429, or a board with no report route, it sends no further entry). The log
387
+ names each one by its title, never its body: `reported T-80: <title>` or
388
+ `already known: <title>`.
389
+
360
390
  The board ties a claimed ticket to one session of the agent. `board claim`
361
391
  starts a new session and saves its id under `BOARD_STATE_DIR` (default
362
392
  `~/.local/state/mergeline`) for the following commands; set
package/dist/cli.js CHANGED
@@ -87,6 +87,12 @@ Usage:
87
87
  board ask <ticket> <question> ask the human; then stop working on it
88
88
  board submit <ticket> <pr-url> <summary> [--usage <json>]
89
89
  board release <ticket> <reason> [--usage <json>]
90
+ board report <ticket> --fingerprint <key> --title <title> (--body <text> | --body-file <path>)
91
+ report a defect you saw outside your ticket (do not fix it):
92
+ a person reads it in the board's Inbox. --fingerprint: the
93
+ file's path and what is wrong. {"known": true}: reported
94
+ before. At most 3 new items a run; --body-file: at most
95
+ 20,000 characters
90
96
  board usage <ticket> --usage <json> what the work on a ticket cost, after the fact
91
97
  (stored only if the agent reports usage on the board)
92
98
 
@@ -106,7 +112,52 @@ Environment:
106
112
  `;
107
113
  class UsageError extends Error {
108
114
  }
109
- const COMMANDS = ["watch", "usage", "whoami", "list", "claim", "heartbeat", "log", "record-spec", "ask", "submit", "release"];
115
+ const COMMANDS = ["watch", "usage", "whoami", "list", "claim", "heartbeat", "log", "record-spec", "ask", "submit", "release", "report"];
116
+ /** The board's most characters of a report's body (R4's route). */
117
+ const REPORT_BODY_MAX = 20_000;
118
+ /** board report <ticket> --fingerprint <key> --title <title> (--body <text> | --body-file <path>) */
119
+ function reportArgs(args) {
120
+ const valued = ["--fingerprint", "--title", "--body", "--body-file"];
121
+ const usage = "board report <ticket> --fingerprint <key> --title <title> (--body <text> | --body-file <path>)";
122
+ const positional = [];
123
+ for (let i = 0; i < args.length; i++) {
124
+ const a = args[i];
125
+ if (valued.includes(a)) {
126
+ i++;
127
+ continue;
128
+ }
129
+ if (a.startsWith("--"))
130
+ throw new UsageError(`unknown option ${a}; ${usage}`);
131
+ positional.push(a);
132
+ }
133
+ if (positional.length !== 1)
134
+ throw new UsageError(`board report takes one ticket: ${usage}`);
135
+ const fingerprint = option(args, "--fingerprint");
136
+ const title = option(args, "--title");
137
+ const body = option(args, "--body");
138
+ const bodyFile = option(args, "--body-file");
139
+ if (fingerprint === undefined)
140
+ throw new UsageError(`--fingerprint is required: ${usage}`);
141
+ if (title === undefined)
142
+ throw new UsageError(`--title is required: ${usage}`);
143
+ if ((body === undefined) === (bodyFile === undefined))
144
+ throw new UsageError(`give one of --body and --body-file: ${usage}`);
145
+ let text;
146
+ if (bodyFile !== undefined) {
147
+ try {
148
+ text = readFileSync(bodyFile, "utf8");
149
+ }
150
+ catch (err) {
151
+ throw new UsageError(`--body-file: cannot read ${bodyFile}: ${err instanceof Error ? err.message : String(err)}`);
152
+ }
153
+ if (text.length > REPORT_BODY_MAX)
154
+ throw new UsageError(`--body-file: ${bodyFile} is over ${REPORT_BODY_MAX} characters`);
155
+ }
156
+ else {
157
+ text = body === "-" ? readStdin() : body;
158
+ }
159
+ return { ticket: positional[0], report: { title, body: text, fingerprint } };
160
+ }
110
161
  function stateFile(creds) {
111
162
  const dir = process.env.BOARD_STATE_DIR || join(process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "mergeline");
112
163
  const who = "key" in creds ? creds.key.split("_").slice(0, 2).join("_") : creds.email;
@@ -435,6 +486,10 @@ async function main(argvIn) {
435
486
  return done(await current().askHuman(text(args[0], "ticket"), text(args[1], "question")));
436
487
  case "submit":
437
488
  return done(await current().submitForReview(text(args[0], "ticket"), text(args[1], "pr-url"), text(args[2], "summary"), usage));
489
+ case "report": {
490
+ const { ticket, report } = reportArgs(args);
491
+ return current().reportFinding(ticket, report);
492
+ }
438
493
  case "usage":
439
494
  if (!usage)
440
495
  throw new UsageError("board usage needs --usage <json>");
package/dist/init.js CHANGED
@@ -45,7 +45,7 @@ export const PACKAGE_VERSION = PACKAGE.version;
45
45
  * which wrote no version. The board says when a claim's kit is older than it
46
46
  * expects (KIT_MIN in pocketbase/pb_hooks/board_lib.js).
47
47
  */
48
- export const KIT_VERSION = 5;
48
+ export const KIT_VERSION = 6;
49
49
  const START = `<!-- mergeline:start (kit ${KIT_VERSION}; managed by \`board init\`; edit outside these markers) -->`;
50
50
  /** Markers are found by these prefixes, so an edited marker line or an older kit's still counts. */
51
51
  const START_PREFIX = "<!-- mergeline:start";
package/dist/mcp.js CHANGED
@@ -116,6 +116,20 @@ export function createServer(board) {
116
116
  usage,
117
117
  },
118
118
  }, ({ ticket_id, reason, usage }) => run(() => board.release(ticket_id, reason, usage)));
119
+ server.registerTool("report_finding", {
120
+ title: "Report a defect outside your ticket",
121
+ description: "Report a defect you saw that is outside your ticket: do not fix it. A person reads it in the board's " +
122
+ "Inbox; no agent does, and you will not hear back. `fingerprint` is a short stable name of the defect, " +
123
+ "the same whoever finds it: the file's path and what is wrong, for example `scripts/smoke.ts: port check " +
124
+ "is flaky`. If the answer says `known`, it was reported before: go on. At most 3 new items a run; put " +
125
+ "the rest in the PR summary. A failed report never stops your ticket.",
126
+ inputSchema: {
127
+ ticket_id: ticketId,
128
+ title: z.string().describe("One line: what is wrong (3 to 120 characters)"),
129
+ body: z.string().describe("What you saw, where, and how to see it again (at most 20,000 characters)"),
130
+ fingerprint: z.string().describe("The file's path and what is wrong, e.g. `scripts/smoke.ts: port check is flaky`"),
131
+ },
132
+ }, ({ ticket_id, title, body, fingerprint }) => run(() => board.reportFinding(ticket_id, { title, body, fingerprint })));
119
133
  return server;
120
134
  }
121
135
  export async function runMcpServer() {
@@ -0,0 +1,93 @@
1
+ // Reports under the worker (round 7, R5): the engine has no board tools, so a
2
+ // defect it saw outside its ticket travels in the file it already leaves
3
+ // (.mergeline-run/result.json or review.json) as `reports`, a list of
4
+ // {title, body, fingerprint}. The worker checks each entry, keeps the first
5
+ // three good ones and sends them by the run, before the run ends.
6
+ //
7
+ // Reading `reports` never loses the result, and sending one never fails the
8
+ // run: a bad entry is skipped and a refused one logged, with the entry's
9
+ // number and title (never the body).
10
+ import { BoardError, NO_REPORTS } from "./service.js";
11
+ import { terminalText } from "./terminal.js";
12
+ /** The board's bounds on a report (R4's route): title trimmed, body as sent, fingerprint trimmed. */
13
+ export const REPORT_LIMITS = { titleMin: 3, titleMax: 120, body: 20_000, fingerprint: 200 };
14
+ /** The most new items a run may report (the board's own count); the worker sends no more entries than this. */
15
+ export const REPORTS_PER_RUN = 3;
16
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
17
+ /** Why the entry is not a report the board takes, or null when it is. */
18
+ function badEntry(e) {
19
+ if (!isObject(e))
20
+ return "not an object";
21
+ for (const k of ["title", "body", "fingerprint"]) {
22
+ if (typeof e[k] !== "string" || !e[k].trim())
23
+ return `"${k}" must be a non-empty string`;
24
+ }
25
+ const title = e.title.trim();
26
+ if (title.length < REPORT_LIMITS.titleMin || title.length > REPORT_LIMITS.titleMax) {
27
+ return `"title" is ${REPORT_LIMITS.titleMin} to ${REPORT_LIMITS.titleMax} characters`;
28
+ }
29
+ if (e.body.length > REPORT_LIMITS.body)
30
+ return `"body" is at most ${REPORT_LIMITS.body} characters`;
31
+ if (e.fingerprint.trim().length > REPORT_LIMITS.fingerprint)
32
+ return `"fingerprint" is 1 to ${REPORT_LIMITS.fingerprint} characters`;
33
+ return null;
34
+ }
35
+ /** The `reports` key of a result file, checked. Absent: none, and nothing to say. */
36
+ export function checkReports(value) {
37
+ if (value === undefined)
38
+ return { reports: [], numbers: [], skipped: [] };
39
+ if (!Array.isArray(value))
40
+ return { reports: [], numbers: [], skipped: ['"reports" is not a list: no report is sent'] };
41
+ const reports = [];
42
+ const numbers = [];
43
+ const skipped = [];
44
+ value.forEach((e, i) => {
45
+ const why = badEntry(e);
46
+ if (why)
47
+ skipped.push(`report ${i + 1} skipped: ${why}`);
48
+ else if (reports.length >= REPORTS_PER_RUN)
49
+ skipped.push(`report ${i + 1} skipped: at most ${REPORTS_PER_RUN} a run`);
50
+ else {
51
+ const r = e;
52
+ reports.push({ title: r.title, body: r.body, fingerprint: r.fingerprint });
53
+ numbers.push(i + 1);
54
+ }
55
+ });
56
+ return { reports, numbers, skipped };
57
+ }
58
+ /**
59
+ * Sends the reports by the run, one call each in order, and logs each outcome. Never throws: a refusal or a
60
+ * network error is logged and the next entry is sent; after a 429 (the run's count is reached) or a board with
61
+ * no report route, none further.
62
+ */
63
+ export async function sendReports(board, runId, read, say) {
64
+ for (const line of read.skipped)
65
+ say(line);
66
+ if (!read.reports.length)
67
+ return;
68
+ if (!runId) {
69
+ say(`${NO_REPORTS}: ${read.reports.length} report(s) not sent`);
70
+ return;
71
+ }
72
+ for (const [i, r] of read.reports.entries()) {
73
+ const title = terminalText(r.title.trim());
74
+ try {
75
+ const answer = await board.reportFromRun(runId, r);
76
+ say(answer.known ? `already known: ${title}` : `reported ${terminalText(answer.ticket)}: ${title}`);
77
+ }
78
+ catch (err) {
79
+ const message = terminalText(err instanceof Error ? err.message : String(err));
80
+ const status = err instanceof BoardError ? err.status : 0;
81
+ if (status === 404 && message === NO_REPORTS) {
82
+ say(`${NO_REPORTS}: no report is sent`);
83
+ return;
84
+ }
85
+ say(`report ${read.numbers[i] ?? i + 1} not sent (${title}): ${message}`);
86
+ if (status === 429) {
87
+ if (i + 1 < read.reports.length)
88
+ say(`the rest (${read.reports.length - i - 1}) not sent`);
89
+ return;
90
+ }
91
+ }
92
+ }
93
+ }
package/dist/review.js CHANGED
@@ -6,6 +6,7 @@
6
6
  // read like result.json, checked field by field, and cut to the board's
7
7
  // limits with the worker's own mark before anything is sent.
8
8
  import { lstatSync, readFileSync } from "node:fs";
9
+ import { checkReports } from "./reports.js";
9
10
  export const REVIEW_MAX = 256 * 1024;
10
11
  /** The board's limits on a review (R5's route): what is over them is cut, never refused. */
11
12
  export const LIMITS = {
@@ -140,7 +141,8 @@ export function checkReview(data) {
140
141
  proof: typeof f.proof === "string" ? f.proof : "",
141
142
  });
142
143
  }
143
- return { ok: true, review: { verdict: verdict, summary: data.summary, ...(risk ? { risk } : {}), findings } };
144
+ const reports = "reports" in data ? { reports: checkReports(data.reports) } : {};
145
+ return { ok: true, review: { verdict: verdict, summary: data.summary, ...(risk ? { risk } : {}), findings, ...reports } };
144
146
  }
145
147
  /** The title of the finding the worker adds for a failing `test` command (D7: a red gate blocks). */
146
148
  export const TEST_FINDING = "The test command fails";
package/dist/service.js CHANGED
@@ -36,6 +36,14 @@ export class BoardUnreachable extends BoardError {
36
36
  this.name = "BoardUnreachable";
37
37
  }
38
38
  }
39
+ /** What a client says when the board has no report route (a board from before R4). */
40
+ export const NO_REPORTS = "this board does not take reports yet: it needs an update";
41
+ /** What a person's session says when the board takes reports by run_id only (R4 deployed, R5 not yet). */
42
+ export const NO_SESSION_REPORTS = "this board does not take reports from a session yet: it needs an update";
43
+ /** A 404 of the route itself (PocketBase's own answer), not the board's "not found or not yours". */
44
+ function noRoute(err) {
45
+ return err instanceof BoardError && err.status === 404 && !/not yours/.test(err.message);
46
+ }
39
47
  const SUMMARY_FIELDS = "id,title,status,priority,spec_path,branch,pr_url,claimed_until,attempts,block_kind,block_text";
40
48
  function toBoardError(err, url, action) {
41
49
  if (err instanceof BoardError)
@@ -208,6 +216,35 @@ export class TicketService {
208
216
  release(ticketId, reason, usage) {
209
217
  return this.post("release", { ticket_id: ticketId, reason, ...(usage ? { usage } : {}) });
210
218
  }
219
+ /** Reports a defect outside the ticket this session holds (R5): the MCP tool and `board report`. */
220
+ async reportFinding(ticketId, report) {
221
+ try {
222
+ return await this.post("report", { ticket_id: ticketId, ...fields(report) });
223
+ }
224
+ catch (err) {
225
+ if (err instanceof BoardError && err.status === 400 && /^run_id is required/.test(err.message)) {
226
+ throw new BoardError(NO_SESSION_REPORTS, 400);
227
+ }
228
+ if (noRoute(err))
229
+ throw new BoardError(NO_REPORTS, 404);
230
+ throw err;
231
+ }
232
+ }
233
+ /** Reports a defect outside the run's ticket by the run (the worker, R5). */
234
+ async reportFromRun(runId, report) {
235
+ try {
236
+ return await this.post("report", { run_id: runId, ...fields(report) });
237
+ }
238
+ catch (err) {
239
+ if (noRoute(err))
240
+ throw new BoardError(NO_REPORTS, 404);
241
+ throw err;
242
+ }
243
+ }
244
+ }
245
+ /** Only these three go to the board, whatever else the caller's object has. */
246
+ function fields(r) {
247
+ return { title: r.title, body: r.body, fingerprint: r.fingerprint };
211
248
  }
212
249
  export class BoardAdmin {
213
250
  url;
package/dist/worker.js CHANGED
@@ -36,9 +36,11 @@ import { reviewPrompt } from "./engines.js";
36
36
  import { badPath, boardNumbers, ciGates, diffHunks, findingMarkdown, fitFindings, fitGate, ghFailure, githubBody, githubPr, inHunks, LIMITS, newRefs, readReview, reviewTicketFile, rulesFile, tail, tailWithin, testOutputWithin, TEST_FINDING, withTestFinding, } from "./review.js";
37
37
  import { BoardError, BoardPaused, } from "./service.js";
38
38
  import { hasWork, isUnreachable, label, sleep, takeLock, untilAnswered } from "./watch.js";
39
+ import { checkReports, sendReports } from "./reports.js";
39
40
  const FAILURE_STOP = 3;
40
41
  const RUN_DIR = ".mergeline-run";
41
- const RESULT_MAX = 64 * 1024;
42
+ /** As review.json's (R5): three report bodies of 20,000 characters fit. */
43
+ const RESULT_MAX = 256 * 1024;
42
44
  const POLL_MS = 5000;
43
45
  const NOTE_GAP_MS = 30_000;
44
46
  const NOTE_CHARS = 500;
@@ -82,7 +84,7 @@ export function readResult(file) {
82
84
  if (!st.isFile())
83
85
  return { outcome: "none", why: "result.json is not a regular file" };
84
86
  if (st.size > RESULT_MAX)
85
- return { outcome: "none", why: "result.json is over 64 KB" };
87
+ return { outcome: "none", why: "result.json is over 256 KB" };
86
88
  let data;
87
89
  try {
88
90
  data = JSON.parse(readFileSync(file, "utf8"));
@@ -104,11 +106,13 @@ export function readResult(file) {
104
106
  if (typeof text !== "string" || !text.trim())
105
107
  return { outcome: "none", why: `"${field[o]}" must be a non-empty string` };
106
108
  const value = cut(text.trim(), max[o]);
109
+ // The optional reports (R5): what is wrong with them is skipped, never the result.
110
+ const reports = "reports" in r ? { reports: checkReports(r.reports) } : {};
107
111
  if (o === "done")
108
- return { outcome: "done", summary: value };
112
+ return { outcome: "done", summary: value, ...reports };
109
113
  if (o === "ask")
110
- return { outcome: "ask", question: value };
111
- return { outcome: "release", reason: value };
114
+ return { outcome: "ask", question: value, ...reports };
115
+ return { outcome: "release", reason: value, ...reports };
112
116
  }
113
117
  /** A subject's most characters, the ticket's label included. */
114
118
  const SUBJECT_MAX = 72;
@@ -546,7 +550,7 @@ export async function work(opts) {
546
550
  return { error: `could not keep the unpushed commits on ${ticket.branch}: ${last}` };
547
551
  };
548
552
  /** One claimed ticket, from its spec to its cleanup. Returns whether it was a failed run. */
549
- const runTicket = async (n, ticket, resumed) => {
553
+ const runTicket = async (n, ticket, runId, resumed) => {
550
554
  const lbl = label(ticket);
551
555
  const say = (line) => log(`run ${n}: ${lbl}: ${line}`);
552
556
  log(`run ${n}: ${resumed ? "resumed" : "claimed"} ${lbl} (${ticket.branch})`);
@@ -779,6 +783,11 @@ export async function work(opts) {
779
783
  const error = engine.error(ran.stdout);
780
784
  return await release(`the engine ended without a result (exit ${ran.code})${error ? `: ${error}` : ""}`);
781
785
  }
786
+ // The engine's reports (R5), while the run is still open: before submit, ask or release, whatever the outcome.
787
+ if (result.reports) {
788
+ held();
789
+ await sendReports(board, runId, result.reports, say);
790
+ }
782
791
  if (result.outcome === "release")
783
792
  return await release(result.reason);
784
793
  // Commit what the engine left.
@@ -1120,6 +1129,11 @@ export async function work(opts) {
1120
1129
  return await release(`the engine ended without a review (exit ${ran.code}): ${read.why}${error ? `; ${error}` : ""}`);
1121
1130
  }
1122
1131
  const result = read.review;
1132
+ // The engine's reports (R5), before the review is sent, whatever its verdict.
1133
+ if (result.reports) {
1134
+ held();
1135
+ await sendReports(board, runId, result.reports, say);
1136
+ }
1123
1137
  // The gates: the repository's test command, then the PR's checks.
1124
1138
  const gates = [];
1125
1139
  let findings = result.findings;
@@ -1420,7 +1434,7 @@ export async function work(opts) {
1420
1434
  // The run's kind says the mode: a review run is reviewed, a rework run is worked as an implement run.
1421
1435
  const outcome = claimed.run?.kind === "review"
1422
1436
  ? await runReview(runs, claimed.ticket, claimed.run.id, claimed.review, !!claimed.resumed)
1423
- : await runTicket(runs, claimed.ticket, !!claimed.resumed);
1437
+ : await runTicket(runs, claimed.ticket, claimed.run?.id, !!claimed.resumed);
1424
1438
  if (configStop) {
1425
1439
  const { file, what, path, branch, id, pushed, review } = configStop;
1426
1440
  log(`stopping: ${file} changed while run ${runs} was going on (${what}), so the worker ran no more git for it.`);
package/engine/prompt.md CHANGED
@@ -13,7 +13,11 @@ on the ticket's branch. Stay in it: do not read or write outside it.
13
13
  not a guess.
14
14
  - On a rework run (the notes end with a review that asks for changes), the
15
15
  ticket's notes say what to change: the run is done when each point there
16
- is fixed or answered in the summary.
16
+ is fixed or answered in the summary. A point that is a red test this
17
+ change did not cause is answered in the summary, as step 4 says, not
18
+ fixed. The worker's own finding "The test command fails" is such a
19
+ point when its failure lines name a check in code the change does not
20
+ touch.
17
21
  - A fresh worktree has no dependencies: install them before you run
18
22
  anything, the way the repository's lockfile says: `package-lock.json`,
19
23
  `npm ci`; `pnpm-lock.yaml`, `pnpm install --frozen-lockfile`;
@@ -22,6 +26,8 @@ on the ticket's branch. Stay in it: do not read or write outside it.
22
26
  `package.json` lists dependencies: with none, there is nothing to install.
23
27
  - A lockfile the run did not mean to add is not part of the change: do not
24
28
  leave one behind.
29
+ - A defect you see outside this ticket is reported, not fixed: put it in
30
+ `reports` in the result file (below). Then go on with your ticket.
25
31
 
26
32
  ## Steps
27
33
 
@@ -34,7 +40,16 @@ on the ticket's branch. Stay in it: do not read or write outside it.
34
40
  doing what nearby code already does is a guess too.
35
41
  3. Work the plan. After each step append one line on what you finished to
36
42
  `.mergeline-run/progress.log`.
37
- 4. Run the project's tests and linter and fix what fails.
43
+ 4. Run the project's tests and linter, and fix what this ticket's change
44
+ broke. A check that fails in code the change does not touch is not
45
+ this ticket's to fix. The code the change touches is the files in
46
+ `git diff origin/main...HEAD` and the code that uses them. For such a
47
+ check:
48
+ - Run it again. If it passes now, it failed by chance. Leave it, and
49
+ name it in the summary: the check, and that it passed when run
50
+ again. Put it in `reports` too (below).
51
+ - If it fails again, end with `ask`, naming the check and the end of
52
+ its output. Do not change code outside the ticket to make it pass.
38
53
  5. Commit with `git commit -m "<message>"`. To bring the branch up to date
39
54
  with `main`, run `git merge origin/main` (already fetched).
40
55
  If `git commit` is not allowed where you run, leave the changes
@@ -64,4 +79,20 @@ End by writing `.mergeline-run/result.json`, one of:
64
79
  - `release` when something in your environment stops you (a command you
65
80
  need is denied, a tool is missing), with what and why.
66
81
 
82
+ Any of the three may also carry `"reports"`: defects you saw outside this
83
+ ticket, which you did not fix. Leave it out when there are none.
84
+
85
+ ```json
86
+ "reports": [{"title": "<one line, 3 to 120 characters>", "body": "<what you saw, where, and how to see it again>", "fingerprint": "<path: what is wrong>"}]
87
+ ```
88
+
89
+ - A person reads each one in the board's Inbox; no agent does, and you
90
+ will not hear back.
91
+ - `fingerprint` is a short stable name of the defect, the same whoever
92
+ finds it: the file's path and what is wrong, for example
93
+ `scripts/smoke.ts: port check is flaky`. One reported before is not
94
+ added again.
95
+ - At most 3; put the rest in the summary. A report that is not sent never
96
+ changes your outcome.
97
+
67
98
  Then stop.
package/engine/review.md CHANGED
@@ -53,9 +53,11 @@ A finding is `blocking` only when both hold:
53
53
  shows the gap.
54
54
 
55
55
  Anything else is `non_blocking`: a risk, a smell, a better way, a problem
56
- that was there before this PR. A blocking finding with no proof is stored
57
- as non-blocking. Nitpicks are not findings: style with no rule behind it is
58
- not reported at all. A review with nothing to say is a good review.
56
+ that was there before this PR in code the PR touches. A defect in code the
57
+ PR does not touch is not a finding of this review: put it in `reports`
58
+ (below). A blocking finding with no proof is stored as non-blocking.
59
+ Nitpicks are not findings: style with no rule behind it is not reported at
60
+ all. A review with nothing to say is a good review.
59
61
 
60
62
  ## Never
61
63
 
@@ -94,4 +96,19 @@ End by writing `.mergeline-run/review.json`, one JSON object:
94
96
  when only non-blocking ones are open; `approve` when none is.
95
97
  - `findings` is `[]` when there are none.
96
98
 
99
+ `review.json` may also carry `"reports"`: defects you saw in code the PR
100
+ does not touch. Leave it out when there are none.
101
+
102
+ ```json
103
+ "reports": [{"title": "<one line, 3 to 120 characters>", "body": "<what you saw, where, and how to see it again>", "fingerprint": "<path: what is wrong>"}]
104
+ ```
105
+
106
+ - A person reads each one in the board's Inbox; no agent does, and you
107
+ will not hear back. A report is not part of the review.
108
+ - `fingerprint` is a short stable name of the defect, the same whoever
109
+ finds it: the file's path and what is wrong, for example
110
+ `scripts/smoke.ts: port check is flaky`. One reported before is not
111
+ added again.
112
+ - At most 3. A report that is not sent never changes the review.
113
+
97
114
  Then stop.
@@ -15,6 +15,8 @@
15
15
  "Bash(board record-spec *)",
16
16
  "Bash(board ask)",
17
17
  "Bash(board ask *)",
18
+ "Bash(board report)",
19
+ "Bash(board report *)",
18
20
  "Bash(board submit)",
19
21
  "Bash(board submit *)",
20
22
  "Bash(board release)",
@@ -35,6 +37,8 @@
35
37
  "Bash(npx -y {{package}} record-spec *)",
36
38
  "Bash(npx -y {{package}} ask)",
37
39
  "Bash(npx -y {{package}} ask *)",
40
+ "Bash(npx -y {{package}} report)",
41
+ "Bash(npx -y {{package}} report *)",
38
42
  "Bash(npx -y {{package}} submit)",
39
43
  "Bash(npx -y {{package}} submit *)",
40
44
  "Bash(npx -y {{package}} release)",
package/kit/done.md CHANGED
@@ -3,9 +3,14 @@ Finish the ticket you are working on. Run everything inside its worktree
3
3
  the `board` command of the same name (`submit_for_review` is `board submit`).
4
4
 
5
5
  1. Run the project's tests and linter (for example `npm test`,
6
- `npm run lint`; use what the project has). If they fail, fix them. If you
7
- cannot, call `log_event` kind `warn` with what fails, then `ask_human`,
8
- and stop.
6
+ `npm run lint`; use what the project has), and fix what this ticket's
7
+ change broke. A check that fails in code the change does not touch
8
+ (the files in `git diff origin/main...HEAD` and the code that uses
9
+ them) is not this ticket's to fix: run it again. If it passes now,
10
+ report it with `report_finding` and name it in the summary. If it
11
+ fails again, call `log_event` kind `warn` with what fails, then
12
+ `ask_human`, and stop. Do not change code outside the ticket to make
13
+ it pass.
9
14
  2. Call `heartbeat` before you push. If it says another session holds the
10
15
  ticket, stop at once: do not commit, push or open a PR. If it says to
11
16
  claim again, stop and claim.
package/kit/rules.md CHANGED
@@ -3,10 +3,10 @@
3
3
  You work tickets from the Mergeline board. Its tools come two ways; use
4
4
  whichever your environment has: the `board` MCP tools (`claim`, `heartbeat`,
5
5
  `log_event`, `record_spec`, `ask_human`, `submit_for_review`, `release`,
6
- `list_mine`), or the same calls as shell commands (`board claim`,
7
- `board heartbeat <ticket> [note]`, `board log`, `board record-spec`,
8
- `board ask`, `board submit`, `board release`, `board list`; run
9
- `board help`). Start a ticket with the pick instructions and finish it with
6
+ `list_mine`, `report_finding`), or the same calls as shell commands
7
+ (`board claim`, `board heartbeat <ticket> [note]`, `board log`,
8
+ `board record-spec`, `board ask`, `board submit`, `board release`,
9
+ `board list`, `board report`; run `board help`). Start a ticket with the pick instructions and finish it with
10
10
  the done instructions: `/pick` and `/done` in Claude Code,
11
11
  `/prompts:pick` and `/prompts:done` in Codex.
12
12
 
@@ -20,6 +20,8 @@ the done instructions: `/pick` and `/done` in Claude Code,
20
20
  `notes`. Nothing else: not a message in the chat, not a guess.
21
21
  - When unsure, ask with `ask_human` (`board ask`); a paused ticket is
22
22
  cheaper than a wrong PR.
23
+ - A defect outside your ticket is reported, not fixed: `report_finding`
24
+ (`board report`). Then go on with your ticket.
23
25
  - One ticket at a time. After asking, submitting or releasing, stop working
24
26
  on that ticket.
25
27
  - Call `heartbeat` after every meaningful step. If a board tool says to claim
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mergeline/agent",
3
- "version": "0.7.3",
3
+ "version": "0.8.0",
4
4
  "description": "The agent's side of a Mergeline board: an MCP server and the `board` CLI. Works with any agent tool that runs MCP servers or shell commands.",
5
5
  "license": "MIT",
6
6
  "author": "frontender-ua",