@mergeline/agent 0.7.4 → 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 +37 -7
- package/dist/cli.js +56 -1
- package/dist/init.js +1 -1
- package/dist/mcp.js +14 -0
- package/dist/reports.js +93 -0
- package/dist/review.js +3 -1
- package/dist/service.js +37 -0
- package/dist/worker.js +21 -7
- package/engine/prompt.md +19 -1
- package/engine/review.md +20 -3
- package/kit/claude-settings.json +4 -0
- package/kit/done.md +8 -3
- package/kit/rules.md +6 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -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
|
|
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`, `
|
|
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`,
|
|
@@ -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
|
|
156
|
-
question, or a release
|
|
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":
|
|
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>]
|
|
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 =
|
|
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() {
|
package/dist/reports.js
ADDED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
@@ -26,6 +26,8 @@ on the ticket's branch. Stay in it: do not read or write outside it.
|
|
|
26
26
|
`package.json` lists dependencies: with none, there is nothing to install.
|
|
27
27
|
- A lockfile the run did not mean to add is not part of the change: do not
|
|
28
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.
|
|
29
31
|
|
|
30
32
|
## Steps
|
|
31
33
|
|
|
@@ -45,7 +47,7 @@ on the ticket's branch. Stay in it: do not read or write outside it.
|
|
|
45
47
|
check:
|
|
46
48
|
- Run it again. If it passes now, it failed by chance. Leave it, and
|
|
47
49
|
name it in the summary: the check, and that it passed when run
|
|
48
|
-
again.
|
|
50
|
+
again. Put it in `reports` too (below).
|
|
49
51
|
- If it fails again, end with `ask`, naming the check and the end of
|
|
50
52
|
its output. Do not change code outside the ticket to make it pass.
|
|
51
53
|
5. Commit with `git commit -m "<message>"`. To bring the branch up to date
|
|
@@ -77,4 +79,20 @@ End by writing `.mergeline-run/result.json`, one of:
|
|
|
77
79
|
- `release` when something in your environment stops you (a command you
|
|
78
80
|
need is denied, a tool is missing), with what and why.
|
|
79
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
|
+
|
|
80
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
|
|
57
|
-
|
|
58
|
-
|
|
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.
|
package/kit/claude-settings.json
CHANGED
|
@@ -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)
|
|
7
|
-
|
|
8
|
-
and
|
|
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
|
|
7
|
-
`board heartbeat <ticket> [note]`, `board log`,
|
|
8
|
-
`board
|
|
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.
|
|
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",
|