@feigi/fleet-ctl 3.53.0 → 3.54.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/package.json +1 -1
- package/scripts/dispatch-prompt.mjs +257 -0
- package/skills/run-team/briefs/finisher.md +137 -0
- package/skills/run-team/briefs/fix-applier.md +403 -0
- package/skills/run-team/briefs/implementer.md +24 -0
- package/skills/run-team/briefs/merge-bot.md +81 -0
- package/skills/run-team/briefs/recipe-deriver.md +9 -0
- package/skills/run-team/briefs/review-runner.md +23 -0
package/package.json
CHANGED
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// dispatch-prompt.mjs — render one member's dispatch brief from its template.
|
|
3
|
+
//
|
|
4
|
+
// dispatch-prompt.mjs render <role> [--kind <kind>] [--<arg> <value>…]
|
|
5
|
+
// [--member <name>] [--json]
|
|
6
|
+
//
|
|
7
|
+
// Roles: implementer, fix-applier, finisher, merge-bot, review-runner,
|
|
8
|
+
// recipe-deriver. A role with kinds (fix-applier: review, conflict,
|
|
9
|
+
// dispositions-retry; finisher: fresh, repair) requires --kind; a role
|
|
10
|
+
// without them refuses it as an unknown flag.
|
|
11
|
+
//
|
|
12
|
+
// OUTPUT. The brief on stdout and nothing else. With --json the payload
|
|
13
|
+
// {role, kind, args, sha256} replaces it, `sha256` being the hash of the
|
|
14
|
+
// brief's bytes. With --member <name> the brief is also written to
|
|
15
|
+
// `<fleet-dir>/briefs/<name>.md` and the payload plus `path` (the .md file)
|
|
16
|
+
// to `<fleet-dir>/briefs/<name>.json`, `<fleet-dir>` as fleet-dir.mjs's
|
|
17
|
+
// fleetFile() resolves it. Every file is written before anything reaches
|
|
18
|
+
// stdout, so a failed write leaves no brief for a caller to dispatch on.
|
|
19
|
+
//
|
|
20
|
+
// EXIT. 0 rendered. 2 refused, with the reason on stderr and nothing on
|
|
21
|
+
// stdout: a missing, unknown or relative argument, a template that carries a
|
|
22
|
+
// placeholder it never declared or no text at all for the kind, a leftover
|
|
23
|
+
// declared placeholder in the output, or instruments.sh answering anything
|
|
24
|
+
// but 0.
|
|
25
|
+
//
|
|
26
|
+
// INSTRUMENTS. After the command line has parsed and before anything is
|
|
27
|
+
// validated or rendered, instruments.sh runs from the main checkout — the
|
|
28
|
+
// directory holding the git common dir, where the run's baseline lives — and
|
|
29
|
+
// any outcome but exit 0 refuses: a changed set, an unanswerable check, a
|
|
30
|
+
// spawn that never ran, a signal. That is the fail-closed contract
|
|
31
|
+
// instruments.sh states for its own callers.
|
|
32
|
+
//
|
|
33
|
+
// THE TEMPLATE CONTRACT. One file per role, `skills/run-team/briefs/<role>.md`,
|
|
34
|
+
// beside the install this script runs from.
|
|
35
|
+
//
|
|
36
|
+
// - A frontmatter block, `---` on the first line and on its own closing line,
|
|
37
|
+
// holds one directive per line:
|
|
38
|
+
// arg <flag> <placeholder> the argument `--<flag>` fills `<placeholder>`
|
|
39
|
+
// path <flag> that argument must be an absolute path
|
|
40
|
+
// literal <text> `<text>` is carried to the member as written
|
|
41
|
+
// A placeholder is `<` + a letter + anything but `<`, `>` and a newline +
|
|
42
|
+
// `>`, matched by its inner text exactly; it may hold spaces. No flag and
|
|
43
|
+
// no placeholder is declared twice, and --member, --json and --kind are
|
|
44
|
+
// reserved.
|
|
45
|
+
// - Every placeholder the selected text carries must be declared by `arg` or
|
|
46
|
+
// `literal`; an undeclared one is a template defect and refuses, naming it.
|
|
47
|
+
// - An argument is required exactly when its placeholder occurs in the text
|
|
48
|
+
// selected for the kind. A flag the selected text never uses is refused.
|
|
49
|
+
// - The body is plain text. Lines `## kind: <k>[, <k>…]` open a section that
|
|
50
|
+
// applies to those kinds; text before the first such line applies to every
|
|
51
|
+
// kind. The brief is the applicable sections' lines in file order, joined
|
|
52
|
+
// with newlines and ended by one. Sections may repeat and interleave, which
|
|
53
|
+
// is how kinds share text without a copy.
|
|
54
|
+
// - Substitution is one pass over the template: a value is never rescanned,
|
|
55
|
+
// so a value holding another placeholder's spelling is not substituted into.
|
|
56
|
+
// After it, any declared placeholder still present in the output — which
|
|
57
|
+
// only a caller passing a value like `<branch>` can cause — refuses, naming
|
|
58
|
+
// it.
|
|
59
|
+
//
|
|
60
|
+
// The text every member of a role shares is meant to live in that role's
|
|
61
|
+
// agent body; until it does, the templates carry what the controller pasted
|
|
62
|
+
// into the dispatch prompt by hand.
|
|
63
|
+
|
|
64
|
+
import { spawnSync } from "node:child_process";
|
|
65
|
+
import { createHash } from "node:crypto";
|
|
66
|
+
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
67
|
+
import { dirname, isAbsolute, join } from "node:path";
|
|
68
|
+
import { fileURLToPath } from "node:url";
|
|
69
|
+
import { makeDie, defineFlags, writeAll } from "./arg.mjs";
|
|
70
|
+
import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
|
|
71
|
+
import { gitEnv } from "./git-env.mjs";
|
|
72
|
+
import { runnerScratchRefusal } from "./review-core.mjs";
|
|
73
|
+
|
|
74
|
+
const NAME = "dispatch-prompt";
|
|
75
|
+
const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
|
|
76
|
+
const BRIEFS_DIR = join(SCRIPT_DIR, "..", "skills", "run-team", "briefs");
|
|
77
|
+
const ROLES = ["implementer", "fix-applier", "finisher", "merge-bot", "review-runner", "recipe-deriver"];
|
|
78
|
+
const RESERVED = ["member", "json", "kind"];
|
|
79
|
+
const USAGE = `usage: ${NAME}.mjs render <role> [--kind <kind>] [--<arg> <value>…] [--member <name>] [--json] — roles: ${ROLES.join(", ")}`;
|
|
80
|
+
const PLACEHOLDER = /<([A-Za-z][^<>\n]*)>/g;
|
|
81
|
+
const KIND_HEADER = /^## kind: (.+)$/;
|
|
82
|
+
|
|
83
|
+
const die = makeDie(NAME);
|
|
84
|
+
|
|
85
|
+
// --- the template ------------------------------------------------------------
|
|
86
|
+
|
|
87
|
+
function parseTemplate(role, text) {
|
|
88
|
+
const lines = text.split("\n");
|
|
89
|
+
if (lines.at(-1) === "") lines.pop();
|
|
90
|
+
const refuse = (why) => die(`template ${role}.md ${why}`);
|
|
91
|
+
if (lines[0] !== "---") refuse("does not open with a --- frontmatter block");
|
|
92
|
+
const close = lines.indexOf("---", 1);
|
|
93
|
+
if (close === -1) refuse("never closes its frontmatter block");
|
|
94
|
+
|
|
95
|
+
const args = [];
|
|
96
|
+
const paths = new Set();
|
|
97
|
+
const literals = new Set();
|
|
98
|
+
for (const line of lines.slice(1, close)) {
|
|
99
|
+
const m = /^(arg|path|literal) (.+)$/.exec(line);
|
|
100
|
+
if (m === null) refuse(`has a frontmatter line that is no directive: ${line}`);
|
|
101
|
+
if (m[1] === "literal") {
|
|
102
|
+
literals.add(m[2]);
|
|
103
|
+
} else if (m[1] === "path") {
|
|
104
|
+
paths.add(m[2]);
|
|
105
|
+
} else {
|
|
106
|
+
const split = /^(\S+) (.+)$/.exec(m[2]);
|
|
107
|
+
if (split === null) refuse(`has an arg line without a placeholder: ${line}`);
|
|
108
|
+
const [, flag, placeholder] = split;
|
|
109
|
+
if (RESERVED.includes(flag)) refuse(`declares the reserved flag --${flag}`);
|
|
110
|
+
if (args.some((a) => a.flag === flag || a.placeholder === placeholder)) refuse(`declares --${flag} or <${placeholder}> twice`);
|
|
111
|
+
args.push({ flag, placeholder });
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
for (const flag of paths) if (!args.some((a) => a.flag === flag)) refuse(`marks --${flag} as a path but never declares it`);
|
|
115
|
+
for (const a of args) if (literals.has(a.placeholder)) refuse(`declares <${a.placeholder}> as both an argument and a literal`);
|
|
116
|
+
|
|
117
|
+
const sections = [];
|
|
118
|
+
let current = { kinds: null, lines: [] };
|
|
119
|
+
sections.push(current);
|
|
120
|
+
for (const line of lines.slice(close + 1)) {
|
|
121
|
+
const header = KIND_HEADER.exec(line);
|
|
122
|
+
if (header === null) {
|
|
123
|
+
current.lines.push(line);
|
|
124
|
+
continue;
|
|
125
|
+
}
|
|
126
|
+
current = { kinds: header[1].split(",").map((k) => k.trim()), lines: [] };
|
|
127
|
+
sections.push(current);
|
|
128
|
+
}
|
|
129
|
+
const kinds = [...new Set(sections.flatMap((s) => s.kinds ?? []))];
|
|
130
|
+
|
|
131
|
+
const whole = sections.flatMap((s) => s.lines).join("\n");
|
|
132
|
+
for (const a of args) if (!whole.includes(`<${a.placeholder}>`)) refuse(`declares <${a.placeholder}> but never carries it`);
|
|
133
|
+
return { args, paths, literals, sections, kinds };
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function loadTemplate(role) {
|
|
137
|
+
let text;
|
|
138
|
+
try {
|
|
139
|
+
text = readFileSync(join(BRIEFS_DIR, `${role}.md`), "utf8");
|
|
140
|
+
} catch (err) {
|
|
141
|
+
return die(`cannot read the template for ${role}: ${err.message}`);
|
|
142
|
+
}
|
|
143
|
+
return parseTemplate(role, text);
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// --- the instrument check ---------------------------------------------------
|
|
147
|
+
|
|
148
|
+
function runInstruments() {
|
|
149
|
+
let root;
|
|
150
|
+
try {
|
|
151
|
+
root = dirname(fleetFile(null));
|
|
152
|
+
} catch (err) {
|
|
153
|
+
if (err instanceof FleetDirUnresolvable) die(`instruments.sh not run — no main checkout to run it from: ${err.message}`);
|
|
154
|
+
throw err;
|
|
155
|
+
}
|
|
156
|
+
const r = spawnSync("sh", [join(SCRIPT_DIR, "instruments.sh"), "--repo", root], {
|
|
157
|
+
encoding: "utf8",
|
|
158
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
159
|
+
env: gitEnv(),
|
|
160
|
+
});
|
|
161
|
+
if (r.error) die(`instruments.sh could not run: ${r.error.message}`);
|
|
162
|
+
if (r.signal) die(`instruments.sh was killed by ${r.signal}`);
|
|
163
|
+
if (r.status === 0) return;
|
|
164
|
+
const said = (r.stderr ?? "").trim() || (r.stdout ?? "").trim();
|
|
165
|
+
const verdict = r.status === 1 ? "the instrument set changed" : `the check could not answer (exit ${r.status})`;
|
|
166
|
+
die(`instruments.sh refused: ${verdict}${said ? ` — ${said}` : ""}`);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// --- main --------------------------------------------------------------------
|
|
170
|
+
|
|
171
|
+
const argv = process.argv.slice(2);
|
|
172
|
+
const role = argv[0] === "render" && argv[1] !== undefined && !argv[1].startsWith("--") ? argv[1] : null;
|
|
173
|
+
if (role !== null && !ROLES.includes(role)) die(`unknown role ${role} — roles: ${ROLES.join(", ")}`);
|
|
174
|
+
const template = role === null ? null : loadTemplate(role);
|
|
175
|
+
// The role is the one positional the shared stray() refusal does not know:
|
|
176
|
+
// take it out of argv so the declared grammar is just `render`.
|
|
177
|
+
if (role !== null) process.argv.splice(3, 1);
|
|
178
|
+
|
|
179
|
+
const flags = { member: "value", json: "bool" };
|
|
180
|
+
if (template !== null) {
|
|
181
|
+
if (template.kinds.length > 0) flags.kind = "value";
|
|
182
|
+
for (const a of template.args) flags[a.flag] = "value";
|
|
183
|
+
}
|
|
184
|
+
const { arg, has, sweep, stray } = defineFlags(die, { flags, positionals: ["render"] });
|
|
185
|
+
sweep();
|
|
186
|
+
stray();
|
|
187
|
+
if (role === null) die(USAGE);
|
|
188
|
+
|
|
189
|
+
runInstruments();
|
|
190
|
+
|
|
191
|
+
let kind = null;
|
|
192
|
+
if (template.kinds.length > 0) {
|
|
193
|
+
kind = arg("kind");
|
|
194
|
+
if (kind === null) die(`--kind is required for ${role} — one of ${template.kinds.join(", ")}`);
|
|
195
|
+
if (!template.kinds.includes(kind)) die(`--kind ${kind} is not a kind of ${role} — one of ${template.kinds.join(", ")}`);
|
|
196
|
+
}
|
|
197
|
+
const selected = template.sections.filter((s) => s.kinds === null || s.kinds.includes(kind)).flatMap((s) => s.lines);
|
|
198
|
+
const body = selected.join("\n");
|
|
199
|
+
if (body.trim() === "") die(`template ${role}.md carries no text for ${kind === null ? "the role" : `kind ${kind}`}`);
|
|
200
|
+
|
|
201
|
+
const declared = new Set(template.args.map((a) => a.placeholder));
|
|
202
|
+
for (const [, inner] of body.matchAll(PLACEHOLDER)) {
|
|
203
|
+
if (!declared.has(inner) && !template.literals.has(inner)) die(`template ${role}.md carries the undeclared placeholder <${inner}>`);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
const required = template.args.filter((a) => body.includes(`<${a.placeholder}>`));
|
|
207
|
+
for (const a of template.args) {
|
|
208
|
+
if (!required.includes(a) && arg(a.flag) !== null) {
|
|
209
|
+
die(`--${a.flag} is not an argument of ${role}${kind === null ? "" : ` ${kind}`} — accepted: ${required.map((r) => `--${r.flag}`).join(", ")}`);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
const values = new Map();
|
|
214
|
+
for (const a of required) {
|
|
215
|
+
const value = arg(a.flag);
|
|
216
|
+
if (value === null) die(`missing required argument: --${a.flag}`);
|
|
217
|
+
if (template.paths.has(a.flag) && !isAbsolute(value)) die(`--${a.flag} must be an absolute path, got ${value}`);
|
|
218
|
+
if (role === "review-runner" && a.flag === "scratch") {
|
|
219
|
+
const refusal = runnerScratchRefusal(value);
|
|
220
|
+
if (refusal !== null) die(refusal);
|
|
221
|
+
}
|
|
222
|
+
values.set(a.placeholder, value);
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
const brief = `${body.replace(PLACEHOLDER, (whole, inner) => (values.has(inner) ? values.get(inner) : whole))}\n`;
|
|
226
|
+
for (const a of required) {
|
|
227
|
+
if (brief.includes(`<${a.placeholder}>`)) die(`the rendered brief still carries <${a.placeholder}> — an argument value spells it`);
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
const payload = {
|
|
231
|
+
role,
|
|
232
|
+
kind,
|
|
233
|
+
args: Object.fromEntries(required.map((a) => [a.flag, values.get(a.placeholder)])),
|
|
234
|
+
sha256: createHash("sha256").update(brief).digest("hex"),
|
|
235
|
+
};
|
|
236
|
+
|
|
237
|
+
const member = arg("member");
|
|
238
|
+
if (member !== null) {
|
|
239
|
+
if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(member)) die(`--member ${member} is not a member name: letters, digits, '.', '_' and '-', starting alphanumeric`);
|
|
240
|
+
let mdPath;
|
|
241
|
+
try {
|
|
242
|
+
mdPath = fleetFile(`briefs/${member}.md`);
|
|
243
|
+
} catch (err) {
|
|
244
|
+
if (err instanceof FleetDirUnresolvable) die(`cannot place --member ${member}'s files: ${err.message}`);
|
|
245
|
+
throw err;
|
|
246
|
+
}
|
|
247
|
+
const jsonPath = join(dirname(mdPath), `${member}.json`);
|
|
248
|
+
try {
|
|
249
|
+
mkdirSync(dirname(mdPath), { recursive: true });
|
|
250
|
+
writeFileSync(mdPath, brief);
|
|
251
|
+
writeFileSync(jsonPath, `${JSON.stringify({ ...payload, path: mdPath }, null, 2)}\n`);
|
|
252
|
+
} catch (err) {
|
|
253
|
+
die(`cannot write --member ${member}'s files under ${dirname(mdPath)}: ${err.message}`);
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
writeAll(1, has("json") ? `${JSON.stringify(payload, null, 2)}\n` : brief);
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
---
|
|
2
|
+
arg worktree abs-path
|
|
3
|
+
arg pin your dispatch pin
|
|
4
|
+
arg pr M
|
|
5
|
+
arg testCmd testCmd
|
|
6
|
+
path worktree
|
|
7
|
+
literal args
|
|
8
|
+
literal cmd
|
|
9
|
+
literal test
|
|
10
|
+
---
|
|
11
|
+
## kind: fresh, repair
|
|
12
|
+
**Re-check the instrument set before you act on what duty 1 or duty 2 read,
|
|
13
|
+
and again before you add the label.**
|
|
14
|
+
`~/.fleet/bin/fleet-run instruments.sh --repo "$(dirname "$(env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir)")"`.
|
|
15
|
+
Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
|
|
16
|
+
exit 2 (the check could not answer) both halt you: report what it printed,
|
|
17
|
+
add no label, and do NOT re-read the script that gave you the reading.
|
|
18
|
+
`--repo` is required and the spelling is the point — the run's baseline lives
|
|
19
|
+
in the audited checkout's gitignored `.fleet/`, which the scratch worktree
|
|
20
|
+
you take at duty 2 does not carry, so a bare invocation from there exits 2 on
|
|
21
|
+
a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
|
|
22
|
+
GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
|
|
23
|
+
pointing this check at the wrong tree — the script's own internal unset
|
|
24
|
+
cannot reach back and fix a path you already resolved wrong. The baseline
|
|
25
|
+
itself names the tree to audit: a cross-workspace run pinned it once at
|
|
26
|
+
phase 0, and your `--repo` only locates that baseline, never the audited
|
|
27
|
+
tree — so an exit 2 naming a moved or unreadable audited tree is a halt
|
|
28
|
+
like every other, not a spelling for you to correct.
|
|
29
|
+
|
|
30
|
+
**A test run is a verdict only if it ran to completion — and you read that
|
|
31
|
+
off the test command's own exit status.**
|
|
32
|
+
Redirect the run's output to a file in your scratch directory and read the
|
|
33
|
+
command's own `$?` straight after it, then read the file. In an `eval` cell
|
|
34
|
+
there is no `$?`: spawn `<testCmd>` with its output going to that file and
|
|
35
|
+
read the exit code and the signal off the spawn result — `exitCode` and
|
|
36
|
+
`signalCode` on Bun's `spawnSync`, `returncode` on Python's `subprocess.run`,
|
|
37
|
+
which is negative for a signal. Never read the status of
|
|
38
|
+
`<testCmd> | tail` or `<testCmd> | grep`: a pipeline's status is its
|
|
39
|
+
last stage's, so the filter's 0 hides the run's own exit, and the array that
|
|
40
|
+
holds the earlier stages' statuses is spelled differently per shell. A run is
|
|
41
|
+
a verdict only when that exit status is 0 **and** its summary shows `tests`
|
|
42
|
+
above 0 and `cancelled` 0. A summary line without that
|
|
43
|
+
is not a verdict, whatever pass count it prints.
|
|
44
|
+
**A run completed when the command itself returned on its own** — an exit
|
|
45
|
+
code, no signal, and no `timeout`, deadline or kill of yours having fired.
|
|
46
|
+
Judge that by how the run ended, never by its `cancelled` count: a failing
|
|
47
|
+
`before` hook or a per-test `timeout` cancels tests inside a run that
|
|
48
|
+
completed, and a SIGTERM'd `node --test` can exit 1 with `cancelled` above 0
|
|
49
|
+
in a run that did not.
|
|
50
|
+
**Any run that did not complete is a killed run** — 124 (`timeout`), 137
|
|
51
|
+
(SIGKILL), 143 (SIGTERM), a signal in the spawn result, an `eval` cell's
|
|
52
|
+
deadline — and read for green it is FAILED, the same bucket as
|
|
53
|
+
`tests 0`, however many tests had passed before the kill. Halt with cause
|
|
54
|
+
`other` and the exit code plus the summary line as evidence; label nothing.
|
|
55
|
+
The same holds for the mutation gate: a killed run is not a mutant that
|
|
56
|
+
reddened, and the files it cancelled are not failures — only a run that
|
|
57
|
+
completed can kill a mutant. A completed run that exits 1 is not a killed run
|
|
58
|
+
either, whatever its `cancelled` count, and not a killed mutant on its exit
|
|
59
|
+
status alone: the acceptance mutation scores a kill only by the rules below.
|
|
60
|
+
Exit 0 with `tests 0` stays FAILED.
|
|
61
|
+
Do not wrap `<testCmd>` in an external `timeout`. Run a long suite in one
|
|
62
|
+
`eval` cell with `timeout: 0`, as the review runner does, and wait for it.
|
|
63
|
+
|
|
64
|
+
**Valid red:** a run that completed — the command returned on its own, with
|
|
65
|
+
no signal and no timeout, deadline or kill having fired — in which the test
|
|
66
|
+
the claim names is reported failing. An exit ≠ 0 with no failing test is not
|
|
67
|
+
red, and a different test failing is not red for this claim. A red in the full
|
|
68
|
+
suite only triggers a narrowed run; it is never evidence on its own.
|
|
69
|
+
|
|
70
|
+
**Narrowed run:** the Test entrypoint with arguments appended,
|
|
71
|
+
`<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
|
|
72
|
+
that is promised about them, so a narrowed run counts only if it reports
|
|
73
|
+
`tests` > 0 and its output names the claimed test. If no narrowing can be
|
|
74
|
+
proven, run the full `<testCmd>` and read the named test's own result from its
|
|
75
|
+
output.
|
|
76
|
+
|
|
77
|
+
**Kill:** the mutant produced a valid red in a narrowed run, and the same
|
|
78
|
+
narrowed command, in the same tree with the mutant reverted, ran a valid green
|
|
79
|
+
with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
|
|
80
|
+
completed exit ≠ 0 with the named test not failing is not a kill, and no kill
|
|
81
|
+
stands without that green run on the unmutated tree. The result is
|
|
82
|
+
inconclusive, never a kill, when the red does not reproduce in the narrowed
|
|
83
|
+
run, when the unmutated tree is red too, or when no usable run exists.
|
|
84
|
+
|
|
85
|
+
**Evidence line:** every kill and every valid red you claim carries one line
|
|
86
|
+
in the claim's own free-text field:
|
|
87
|
+
`red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
|
|
88
|
+
A failing-test finding filed off the review's shared run carries the `red:`
|
|
89
|
+
half alone.
|
|
90
|
+
|
|
91
|
+
An inconclusive acceptance mutation is neither a kill nor a pass: halt with
|
|
92
|
+
cause `other`, with both runs — the mutant's and the unmutated tree's — as
|
|
93
|
+
evidence; label nothing. A kill's evidence line goes in your report.
|
|
94
|
+
|
|
95
|
+
**Duty 3 is one script, and its exit code is your verdict.**
|
|
96
|
+
`~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
|
|
97
|
+
(the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
|
|
98
|
+
PR, records the head you audited, adds `ready-to-merge`, and reads the labels
|
|
99
|
+
back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
|
|
100
|
+
carries zero or more than one release label: you are halted before the label,
|
|
101
|
+
and the receipt names which it found. Exit 4 means the read-back does not carry
|
|
102
|
+
the label, written or not. Exit 2 means a `gh` call or the invocation
|
|
103
|
+
itself failed: report the stderr it printed. Every non-zero exit halts you
|
|
104
|
+
with cause `other`, with the receipt as evidence, and you do not run any of
|
|
105
|
+
its steps by hand to get past it. A repo whose label list defines none of the
|
|
106
|
+
three does not gate on one, and the script says so in its receipt. Put the
|
|
107
|
+
receipt, the JSON line it printed, in your report as printed: it is what tells
|
|
108
|
+
the controller the label is on.
|
|
109
|
+
|
|
110
|
+
**Duty 1 is one script, and its exit code is your verdict.**
|
|
111
|
+
`~/.fleet/bin/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`
|
|
112
|
+
(the path you were dispatched with, and the full SHA). It finds your
|
|
113
|
+
worktree's row, reads whether the tree is dirty, compares the worktree's
|
|
114
|
+
`HEAD` to your pin, and when the head differs derives the cause from the
|
|
115
|
+
reflog. Exit 0, with `cause` null, is the only code that means the worktree is
|
|
116
|
+
clean at your pin. Exit 1 means `cause` is non-null: you are halted, and
|
|
117
|
+
`cause` is the word you name — `live-editor`, `rebase`, `past-pin`,
|
|
118
|
+
`unreadable`, `missing`, `absent` or `other`, and `other` is a cause too, not
|
|
119
|
+
a gap. Exit 2 means the script could not look: you are halted with cause
|
|
120
|
+
`other`, with the line it printed on stderr as the evidence.
|
|
121
|
+
|
|
122
|
+
The pin is the SHA you were dispatched against, never `PR headRefOid`: a
|
|
123
|
+
member that kept working and pushed after the pin matches the branch tip on a
|
|
124
|
+
clean tree, so a headRefOid comparison reports "settled" over commits no
|
|
125
|
+
reviewer read — the exact divergence this halt exists to catch. You do not
|
|
126
|
+
run any of the script's steps by hand to get past a halt or to second-guess
|
|
127
|
+
it. Put the verdict, the JSON line it printed, in your report as printed: its
|
|
128
|
+
`evidence` is what the controller resolves the halt from.
|
|
129
|
+
|
|
130
|
+
Every cause halts, always — named or not, you never verify the dirt is
|
|
131
|
+
harmless and label over it, a rebase is not a fast-forward you get to accept,
|
|
132
|
+
a commit past the pin is not one either, and a cause you could not name is
|
|
133
|
+
the least settled of the lot. Naming the cause makes the halt cheap to
|
|
134
|
+
resolve, never a reason to skip it.
|
|
135
|
+
## kind: repair
|
|
136
|
+
|
|
137
|
+
An earlier finisher on this PR reported `labelled`, but its read-back did not carry `ready-to-merge`: you are the repair finisher. Duty 3's script decides whether the label is on, as above.
|
|
@@ -0,0 +1,403 @@
|
|
|
1
|
+
---
|
|
2
|
+
arg worktree abs-path
|
|
3
|
+
arg branch branch
|
|
4
|
+
arg testCmd testCmd
|
|
5
|
+
arg scratch scratch
|
|
6
|
+
arg pr pr
|
|
7
|
+
arg run run
|
|
8
|
+
arg mismatched-record mismatched record
|
|
9
|
+
arg violations violations
|
|
10
|
+
path worktree
|
|
11
|
+
path scratch
|
|
12
|
+
path mismatched-record
|
|
13
|
+
literal N
|
|
14
|
+
literal test
|
|
15
|
+
literal cmd
|
|
16
|
+
literal your name
|
|
17
|
+
literal subject
|
|
18
|
+
literal finding
|
|
19
|
+
literal base
|
|
20
|
+
literal args
|
|
21
|
+
literal the run root's name in the review path
|
|
22
|
+
literal the review file's head
|
|
23
|
+
literal sha
|
|
24
|
+
literal member
|
|
25
|
+
literal helper
|
|
26
|
+
literal file
|
|
27
|
+
---
|
|
28
|
+
## kind: review, dispositions-retry
|
|
29
|
+
You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
|
|
30
|
+
push destination below, given to you because a detached worktree cannot supply
|
|
31
|
+
it. Do NOT create another worktree. The review is done and its result is the
|
|
32
|
+
file below — do not re-review, do not dispatch specialists.
|
|
33
|
+
|
|
34
|
+
## kind: conflict
|
|
35
|
+
You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
|
|
36
|
+
push destination below, given to you because a detached worktree cannot supply
|
|
37
|
+
it. Do NOT create another worktree. There is no review file: the PR sits on a
|
|
38
|
+
conflict hold and you are here to clear it — do not review, do not dispatch
|
|
39
|
+
specialists.
|
|
40
|
+
|
|
41
|
+
## kind: review, conflict, dispositions-retry
|
|
42
|
+
**`edit` and `read` resolve a bare relative path against the SESSION ROOT —
|
|
43
|
+
the controller's own main checkout — not against that worktree and not
|
|
44
|
+
against your `bash` cwd, which they share no `cwd` parameter with. Give them
|
|
45
|
+
the absolute worktree path on every call, mutation-probe copies included.**
|
|
46
|
+
The main checkout is the parent of `git rev-parse --path-format=absolute
|
|
47
|
+
--git-common-dir`. A `member-write-guard` refusal means the path hit the
|
|
48
|
+
main checkout — for `bash`, a missing or main-checkout `cwd` — so re-issue
|
|
49
|
+
it absolute, under your worktree.
|
|
50
|
+
|
|
51
|
+
## kind: review, dispositions-retry
|
|
52
|
+
Read `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` and run **steps 2, 3
|
|
53
|
+
and 5 only**: split apply-now/defer, commit, push, file every deferral as its
|
|
54
|
+
own issue with the label the finding's state calls for. Skip step 1 — the
|
|
55
|
+
review already ran — and steps 4 and 6: the controller owns the CI wait and
|
|
56
|
+
dispatches the finisher.
|
|
57
|
+
|
|
58
|
+
**The review's result is `<scratch>/pr<pr>/<run>/review.json`** — the digest first
|
|
59
|
+
(`jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}'`),
|
|
60
|
+
then every finding (`jq '.survived'`, `jq '.unverified'`, `jq '.refuted'`).
|
|
61
|
+
Read it through `review-and-fix.md`'s **The review result file**, which holds
|
|
62
|
+
the rest of the recipes and every ruling on the findings: both
|
|
63
|
+
mutual-exclusion scans, the suggested-fix re-derivation, `refuted=false` ≠
|
|
64
|
+
apply, per-site measurement for a sibling-site extension, and `testEnvironment`
|
|
65
|
+
and `cwdAudit` before any result of the shared test run. Every one of those
|
|
66
|
+
rulings is yours — nobody upstream has made one, and the controller never
|
|
67
|
+
reads the findings.
|
|
68
|
+
|
|
69
|
+
**Every factual claim your diff restates needs a settling command run
|
|
70
|
+
against the tree first** — the issue body is a lead, never a citation.
|
|
71
|
+
**No positional references** (`the closing/second/last X`); name the thing
|
|
72
|
+
semantically. **Never write a COUNT or a tally into prose; state the
|
|
73
|
+
property instead** — unless it is a past-tense record of a measurement you
|
|
74
|
+
performed, which stays as written; a present-tense claim about a live
|
|
75
|
+
property must be restated as a property (`every other test in the file`),
|
|
76
|
+
true at any count. **A settling grep over literal text takes `grep -F`, and
|
|
77
|
+
its zero counts only after the same command finds a line known to match.**
|
|
78
|
+
|
|
79
|
+
**Apply `survived` findings. A finding in `unverified` whose refuters ran and
|
|
80
|
+
crashed or abstained always defers** — and which it is, you read off
|
|
81
|
+
`refutersDispatched` and `refutersInconclusive`, never off severity and never
|
|
82
|
+
off an empty vote list: `refutersDispatched` above zero with nothing decided
|
|
83
|
+
means every refuter dispatched against it died or abstained, and
|
|
84
|
+
`refutersInconclusive` counts the ones that abstained. Severity records how much a
|
|
85
|
+
finding would matter if true, never whether anything looked. Say *in the
|
|
86
|
+
deferral* which it was rather than that it went unchecked. Name a crash as
|
|
87
|
+
crashed refuters — the review re-dispatched each crash once already and
|
|
88
|
+
reports what died again, so a deferral that names the crash can still be
|
|
89
|
+
re-verified. An abstention is not a crash: cite the inconclusive runs each
|
|
90
|
+
abstaining refuter named in its `reason`, and never describe its refuters as
|
|
91
|
+
crashed. **A `suggestion` is also in `unverified`,
|
|
92
|
+
for a different reason — `refutersDispatched` of zero, the 0-refuter budget
|
|
93
|
+
the review gives that band by policy — and the rule below, not this one,
|
|
94
|
+
covers it.**
|
|
95
|
+
|
|
96
|
+
**A `suggestion` is budgeted 0 refuters, so it is unchecked until you check
|
|
97
|
+
it.** For each one, first decide scope: is it inside the scope of the PR's own
|
|
98
|
+
ticket, or a different piece of work? **Out of scope → defer and file, never
|
|
99
|
+
apply** — but the claim bar runs first: an out-of-scope suggestion whose
|
|
100
|
+
claim is about shape (`claimKind: shape`) gets no refuter and goes to the
|
|
101
|
+
closed suggestion-band record, and every other one gets the same refuter an
|
|
102
|
+
in-scope one does, dispatched the same way, before it is filed.
|
|
103
|
+
**In scope → dispatch ONE refuter** against the finding before
|
|
104
|
+
touching the tree, biased to refuse, and hand it the prompt below with one
|
|
105
|
+
substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path
|
|
106
|
+
under your own run root — `mktemp -d` once per round for
|
|
107
|
+
`<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids
|
|
108
|
+
restart at 1 each round too — and write that absolute path into the
|
|
109
|
+
refuter's prompt in its place; a refuter never derives its own path:
|
|
110
|
+
|
|
111
|
+
> Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by
|
|
112
|
+
> RUNNING something — compile it, run the test, apply the mutation. Do not
|
|
113
|
+
> reason your way to agreement. Observe that run synchronously — run the
|
|
114
|
+
> command, wait for it, read its exit code. Never poll a log file for a
|
|
115
|
+
> completion marker: prefer ONE blocking run to a poll loop, and treat its
|
|
116
|
+
> return as permission to look, never as the answer. Reading a log the run has
|
|
117
|
+
> already finished writing is fine; waiting on one is not. If you match a test
|
|
118
|
+
> reporter's own output, accepting both `ℹ` and `#` is necessary but NOT
|
|
119
|
+
> sufficient — strip SGR escapes first as well. node's prefix moves with the
|
|
120
|
+
> node version and with whether stdout is a TTY, and color wraps the whole line
|
|
121
|
+
> so it begins with ESC and no prefix anchor matches at all, which returns
|
|
122
|
+
> empty at exit 0 — indistinguishable from a hung run and from a run of zero
|
|
123
|
+
> tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=`
|
|
124
|
+
> empty still enables color, so it is not a control. State your search scope
|
|
125
|
+
> AND what your pattern would have missed. A grep over one ref does not
|
|
126
|
+
> support a claim about history; a pattern built from the token a diff removed
|
|
127
|
+
> does not support a claim that the category is empty.
|
|
128
|
+
>
|
|
129
|
+
> When your check scores a mutant killed or a test red, run only in your own
|
|
130
|
+
> copy of the tree, and these rules decide it and nothing else:
|
|
131
|
+
>
|
|
132
|
+
> **Valid red:** a run that completed — the command returned on its own, with no
|
|
133
|
+
> signal and no timeout, deadline or kill having fired — in which the test the
|
|
134
|
+
> claim names is reported failing. An exit ≠ 0 with no failing test is not red,
|
|
135
|
+
> and a different test failing is not red for this claim. A red in the full
|
|
136
|
+
> suite only triggers a narrowed run; it is never evidence on its own.
|
|
137
|
+
>
|
|
138
|
+
> **Narrowed run:** the Test entrypoint with arguments appended, `<testCmd>
|
|
139
|
+
> <args>`. That appended arguments reach the Test entrypoint is all that is
|
|
140
|
+
> promised about them, so a narrowed run counts only if it reports `tests` > 0
|
|
141
|
+
> and its output names the claimed test. If no narrowing can be proven, run the
|
|
142
|
+
> full `<testCmd>` and read the named test's own result from its output.
|
|
143
|
+
>
|
|
144
|
+
> **Kill:** the mutant produced a valid red in a narrowed run, and the same
|
|
145
|
+
> narrowed command, in the same tree with the mutant reverted, ran a valid green
|
|
146
|
+
> with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
|
|
147
|
+
> completed exit ≠ 0 with the named test not failing is not a kill, and no kill
|
|
148
|
+
> stands without that green run on the unmutated tree. The result is
|
|
149
|
+
> inconclusive, never a kill, when the red does not reproduce in the narrowed
|
|
150
|
+
> run, when the unmutated tree is red too, or when no usable run exists.
|
|
151
|
+
>
|
|
152
|
+
> **Evidence line:** every kill and every valid red you claim carries one line
|
|
153
|
+
> in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>;
|
|
154
|
+
> baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the
|
|
155
|
+
> review's shared run carries the `red:` half alone.
|
|
156
|
+
>
|
|
157
|
+
> This refuter has no abstain: a run that could not decide — neither a valid red
|
|
158
|
+
> nor a valid green — is no kill and no refutation, so name the runs in
|
|
159
|
+
> `reason`, each with its evidence line, and leave `refuted` true, so the
|
|
160
|
+
> suggestion defers on the record instead of applying on a check that decided
|
|
161
|
+
> nothing.
|
|
162
|
+
>
|
|
163
|
+
> A failure injection with
|
|
164
|
+
> no positive control has produced NO result, never a negative one. Before you
|
|
165
|
+
> read an injected fault — an env var, an argv word, a mutant — as having had
|
|
166
|
+
> no effect, prove the injection reached the child: one run whose output
|
|
167
|
+
> differs with it present versus absent, or the child echoing the injected
|
|
168
|
+
> value back. Uncontrolled, the cell is unrun — say so in your verdict instead
|
|
169
|
+
> of reporting a no-effect result. Build such an invocation as an array
|
|
170
|
+
> expanded braced and quoted —
|
|
171
|
+
> `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
|
|
172
|
+
> assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
|
|
173
|
+
> unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
|
|
174
|
+
> zsh passes ONE argument, sets a variable literally named `SETB` to
|
|
175
|
+
> `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not
|
|
176
|
+
> the portable spelling either: measured, bash word-splits it into `SETB=1`
|
|
177
|
+
> and `BADJ=1[@]`, so the injection variable is set to a corrupted value,
|
|
178
|
+
> while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set,
|
|
179
|
+
> exit 0. Everything you
|
|
180
|
+
> write — mutants, fixtures,
|
|
181
|
+
> scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else;
|
|
182
|
+
> the checkout and any worktree are never write targets, though
|
|
183
|
+
> `git show`/`git archive` at a pinned ref read fine anywhere. Chain the
|
|
184
|
+
> directory change into the command, `cd "$D" && git …`, never
|
|
185
|
+
> `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in
|
|
186
|
+
> the checkout — and bracket a fixture's own git with
|
|
187
|
+
> `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to
|
|
188
|
+
> the host repository, and `fatal: not a git repository` (exit 128) is the
|
|
189
|
+
> usual pass, not a failure — an outer repository whose ignore rules cover
|
|
190
|
+
> your scratch dir is a pass too; before any `git commit` it must resolve to
|
|
191
|
+
> your scratch path, which catches a forgotten `git init` under any enclosing
|
|
192
|
+
> repository — compare resolved forms (`realpath`), since `--show-toplevel`
|
|
193
|
+
> can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under
|
|
194
|
+
> its resolved name.
|
|
195
|
+
|
|
196
|
+
Survives → apply it, with one hold: if its refuter reports a blast radius
|
|
197
|
+
touching lines another finding also changes, that is the mutual-exclusion
|
|
198
|
+
scan's second input — rule the pair before either change reaches the tree;
|
|
199
|
+
you hold every finding, so only you can see that the two cannot both land. Refuted → defer and file it, and
|
|
200
|
+
say the refutation in the issue body. **Apply only what survives — no report is not a survival.** A
|
|
201
|
+
refuter you never hear from leaves the finding exactly as unchecked as it
|
|
202
|
+
arrived, so it defers like a refuted one.
|
|
203
|
+
|
|
204
|
+
**Out of scope, the refuter decides only where the suggestion is filed — it
|
|
205
|
+
defers either way, never applied.** Refuted → the closed suggestion-band
|
|
206
|
+
record, never an open issue. Survived, or its refuter crashed or abstained →
|
|
207
|
+
its own open issue labelled `needs-triage`, citing the verdict, or the run
|
|
208
|
+
that crashed, in the body. There is no cap on these refuters: count the ones
|
|
209
|
+
you dispatch against out-of-scope suggestions, since your report names that
|
|
210
|
+
count.
|
|
211
|
+
|
|
212
|
+
**A finding's `suggested_fix` is a hypothesis, not a patch — the review never
|
|
213
|
+
ran it.** Only the claim is verified adversarially; the remedy text is unchecked.
|
|
214
|
+
Three were wrong as written in one run: a stated end state that dropped a
|
|
215
|
+
load-bearing option and measured RED, an assertion against a property the test
|
|
216
|
+
helper does not expose (`TypeError`), and an enumeration that stopped short of
|
|
217
|
+
two further stale clauses — one of them false in the *dangerous* direction. Run
|
|
218
|
+
the remedy before you commit it, and re-derive an assertion from the post-fix
|
|
219
|
+
tree rather than from the finding, since a sibling finding may edit the very
|
|
220
|
+
text it asserts on.
|
|
221
|
+
|
|
222
|
+
**Retrieve that report yourself; do not wait to be handed it — this covers the
|
|
223
|
+
refuters YOU dispatch, and only those.** The review's own specialists do leave
|
|
224
|
+
transcripts, but nothing gives you their address: the review had `agent()`
|
|
225
|
+
return their findings into the script, so the result file holds their findings
|
|
226
|
+
and names no transcript, and nothing on disk indexes a transcript by PR or
|
|
227
|
+
dimension. Hunting their paths gets you nothing; read the file. A report from a refuter you spawned is
|
|
228
|
+
different — it surfaces to the controller rather than to you, and waiting for a
|
|
229
|
+
relay that never comes strands the finding. Its transcript is at the output file
|
|
230
|
+
named in your spawn result, and its report is the last record:
|
|
231
|
+
|
|
232
|
+
A depth-2 helper cannot dispatch further (`task.maxRecursionDepth: 2`); reach it directly instead, by its full dotted id (`<member>.<helper>`), via `hub send` — delivered, woken, no transcript workaround needed.
|
|
233
|
+
|
|
234
|
+
If retrieval comes back empty, ask the controller by name. Only when neither
|
|
235
|
+
works is the finding **unchecked** — defer and file it, and say so in the body. This is
|
|
236
|
+
`review-and-fix.md`'s **Specialists** rule; it reaches you here because the
|
|
237
|
+
steps that point at it are the ones you skip.
|
|
238
|
+
|
|
239
|
+
The CI facts in that file apply to you — a `rebase-check` red, or heavy jobs
|
|
240
|
+
`skipped`, **solely** off a non-zero behind-count, is staleness and not a
|
|
241
|
+
failure. Never rebase to clear it. **`solely` is the load-bearing word:**
|
|
242
|
+
`ci.yml`'s `rebase-check` exits 1 on five conditions and only one is
|
|
243
|
+
staleness, so a non-zero behind-count does not by itself settle which fired.
|
|
244
|
+
The job log names the condition — and because the staleness condition exits
|
|
245
|
+
before the merge-commit condition is evaluated, the log is silent on that one
|
|
246
|
+
by construction, so measure it separately with
|
|
247
|
+
`git fetch origin && git rev-list --merges --count "origin/<base>..HEAD"` —
|
|
248
|
+
keep the fetch, or a stale local `origin/<base>` widens the range over the
|
|
249
|
+
base's own merge commits and reports a merge commit this branch never added.
|
|
250
|
+
A non-zero count does not send you to a local rebase either: the merge bot's
|
|
251
|
+
step-1 `gh pr update-branch --rebase` drops merge commits too
|
|
252
|
+
(`run-merge-bot.md` step 1), so both conditions clear on that one server-side
|
|
253
|
+
rebase. What it buys you is knowing the red was never solely staleness.
|
|
254
|
+
|
|
255
|
+
**Run `<testCmd>` from the worktree before committing**, copied verbatim.
|
|
256
|
+
`tests 0` is a FAILED run, not a pass. Red or zero-test → fix it, or move that
|
|
257
|
+
finding to defer; never commit over it. **Never `--no-verify`** — a failing
|
|
258
|
+
hook is a finding you report, not an obstacle you route around. Report the test
|
|
259
|
+
result with your SHA. Nothing re-reviews this commit: the review ran against a
|
|
260
|
+
snapshot cut before your edits existed, and a refuter checked the finding's
|
|
261
|
+
claim, never your patch.
|
|
262
|
+
|
|
263
|
+
**A test you ADD must kill its own mutant** — break what it pins, confirm it and
|
|
264
|
+
only it goes red and that the red is a kill by the rules below, restore. **Then
|
|
265
|
+
a change it should *not* catch, staying green** — else you proved it fails, not
|
|
266
|
+
that it discriminates: a pin asserting whole-file text clears "it and only it
|
|
267
|
+
goes red" and still reddens on any edit (measured). A green suite says nothing
|
|
268
|
+
about a new test: one pin this run survived the exact mutation it was named for.
|
|
269
|
+
|
|
270
|
+
**Valid red:** a run that completed — the command returned on its own, with
|
|
271
|
+
no signal and no timeout, deadline or kill having fired — in which the test
|
|
272
|
+
the claim names is reported failing. An exit ≠ 0 with no failing test is not
|
|
273
|
+
red, and a different test failing is not red for this claim. A red in the full
|
|
274
|
+
suite only triggers a narrowed run; it is never evidence on its own.
|
|
275
|
+
|
|
276
|
+
**Narrowed run:** the Test entrypoint with arguments appended,
|
|
277
|
+
`<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
|
|
278
|
+
that is promised about them, so a narrowed run counts only if it reports
|
|
279
|
+
`tests` > 0 and its output names the claimed test. If no narrowing can be
|
|
280
|
+
proven, run the full `<testCmd>` and read the named test's own result from its
|
|
281
|
+
output.
|
|
282
|
+
|
|
283
|
+
**Kill:** the mutant produced a valid red in a narrowed run, and the same
|
|
284
|
+
narrowed command, in the same tree with the mutant reverted, ran a valid green
|
|
285
|
+
with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
|
|
286
|
+
completed exit ≠ 0 with the named test not failing is not a kill, and no kill
|
|
287
|
+
stands without that green run on the unmutated tree. The result is
|
|
288
|
+
inconclusive, never a kill, when the red does not reproduce in the narrowed
|
|
289
|
+
run, when the unmutated tree is red too, or when no usable run exists.
|
|
290
|
+
|
|
291
|
+
**Evidence line:** every kill and every valid red you claim carries one line
|
|
292
|
+
in the claim's own free-text field:
|
|
293
|
+
`red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
|
|
294
|
+
A failing-test finding filed off the review's shared run carries the `red:`
|
|
295
|
+
half alone.
|
|
296
|
+
|
|
297
|
+
An inconclusive result proves nothing about the test: do not report the test
|
|
298
|
+
as proven, and measure again in a clean state. Put each kill's evidence line in
|
|
299
|
+
your report, beside the test result.
|
|
300
|
+
|
|
301
|
+
**A mutation that never landed is not a green — it is a cell that did not
|
|
302
|
+
run.** Same rule for any fault you inject to see what breaks: prove the
|
|
303
|
+
injection reached the child before you read its result — one run whose output
|
|
304
|
+
differs with the injection present versus absent, or the child echoing the
|
|
305
|
+
injected value back. Without one, a probe that exits 0 reporting the mutant
|
|
306
|
+
behaving exactly like its baseline is indistinguishable from a real no-effect
|
|
307
|
+
result, and a reproduction that never happened reads as a refutation. Build
|
|
308
|
+
such an invocation as an array expanded braced and quoted —
|
|
309
|
+
`cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
|
|
310
|
+
assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
|
|
311
|
+
unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
|
|
312
|
+
zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`,
|
|
313
|
+
never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable
|
|
314
|
+
spelling either: measured, bash word-splits it into `SETB=1` and
|
|
315
|
+
`BADJ=1[@]`, so the injection variable is set to a corrupted value, while
|
|
316
|
+
zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0.
|
|
317
|
+
|
|
318
|
+
**Commit BEFORE you mutate, and restore with `cp`, never a git discard.**
|
|
319
|
+
`git checkout -- <file>` reverts the whole file, not your mutant — so it also
|
|
320
|
+
eats uncommitted edits you made earlier, and the "clean baseline" you measure
|
|
321
|
+
next is silently the reverted file. Two members hit this in one run; one lost
|
|
322
|
+
prose edits and caught it only because a non-catch control failed. Copy the
|
|
323
|
+
file aside and copy it back. Better still, mutate a copy under
|
|
324
|
+
`<scratch>/pr<N>/mutate/` and leave the worktree untouched — that is what
|
|
325
|
+
refuters are already required to do, and it has no blast radius at all.
|
|
326
|
+
|
|
327
|
+
**Never `git stash` or `git stash pop` here either — a WIP commit is the
|
|
328
|
+
substitute, not a second scratch mechanism: `git commit -m wip`, then
|
|
329
|
+
restore or amend once you're back to real work.** The stash stack is
|
|
330
|
+
repo-global too, not per-worktree or per-session — the same `refs/stash`
|
|
331
|
+
every concurrent member and the main checkout share, not partitioned the
|
|
332
|
+
way `<scratch>/pr<N>/mutate/` above is. A bare pop takes whichever entry is
|
|
333
|
+
on top, from any worktree, silently — rc 0, no error — when the tree
|
|
334
|
+
receiving it is clean on the affected paths, and refuses only when that
|
|
335
|
+
tree is already dirty there. A bare `git stash` (push) does not reach into
|
|
336
|
+
a sibling's tree, so that half is not the risk — the pop is. Nothing
|
|
337
|
+
partitions the stack; this prohibition is the whole of the protection.
|
|
338
|
+
|
|
339
|
+
**Report LAST, and only once nothing can still change.** A report you have
|
|
340
|
+
sent **pins that SHA** for the controller, which dispatches a finisher against
|
|
341
|
+
it. If a further instruction arrives after you have reported, reply saying the
|
|
342
|
+
SHA is moving *before* you touch the tree again — do not silently do the work
|
|
343
|
+
and re-report. Measured: three members in one run sent a final report and kept
|
|
344
|
+
working; one had its worktree audited mid-mutation, another handed over a SHA
|
|
345
|
+
that was two commits stale, and a finisher dispatched on either would have
|
|
346
|
+
halted on a diverged head.
|
|
347
|
+
|
|
348
|
+
**Before you report, write every ruling to `<scratch>/dispositions-<your name>.json`**,
|
|
349
|
+
`<your name>` the `fix-pr-<pr>[-x]` you were dispatched as — the record the controller checks with
|
|
350
|
+
`dispositions-check.mjs` before it dispatches any finisher. It is
|
|
351
|
+
`{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}`
|
|
352
|
+
— `run` the `<run>` of the review path above, which the check holds against the
|
|
353
|
+
review the PR's latest `reviewed=` names: a record written against an earlier
|
|
354
|
+
review, a same-head one included, is a mismatch. One entry per
|
|
355
|
+
`survived` finding and per `unverified` finding, plus one per `refuted`
|
|
356
|
+
finding you reverse. Each entry carries `bucket`
|
|
357
|
+
(`survived|unverified|refuted`), `index` (its position in that bucket of the
|
|
358
|
+
review file), `scope` (`in|out`), `claimKind` (`behavior|shape`) and
|
|
359
|
+
`disposition` (`apply|defer`), and where they apply `reason`, `issue` (the
|
|
360
|
+
number you filed it to or commented on), `verdictPath` (a suggestion's
|
|
361
|
+
refuter verdict file, in scope and, above the claim bar, out of scope) and
|
|
362
|
+
`remedyFiles` (the files its remedy names). An out-of-scope suggestion whose
|
|
363
|
+
refuter crashed before any verdict reached you still names the path its
|
|
364
|
+
verdict would have taken. A `refuted` entry carries `scope`, `claimKind` and `disposition`
|
|
365
|
+
like every other entry, and a non-empty `reason` holding the evidence that
|
|
366
|
+
reverses it; a missing or blank `reason` is a mismatch. A finding with no
|
|
367
|
+
`line`, or on a line the PR's diff touched —
|
|
368
|
+
`git diff` from its merge-base with `origin/main` to the review's head — is
|
|
369
|
+
in scope whatever its `scope` says. An in-scope `survived` finding you defer
|
|
370
|
+
carries `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or
|
|
371
|
+
`remedy-outside-diff`; the last needs `remedyFiles` to name a file the PR's
|
|
372
|
+
diff does not touch, and for a `critical` or `important` finding it sends the
|
|
373
|
+
PR to a human instead of passing. Any
|
|
374
|
+
other reason, none, or a `survived` or `unverified` finding with no entry is
|
|
375
|
+
a mismatch, and the PR gets no finisher. `disposition` has no `dismiss`: an
|
|
376
|
+
in-scope `survived` finding verified correct, needing no change, is deferred
|
|
377
|
+
with `reason` `false-rationale` and filed on the closed suggestion-band
|
|
378
|
+
record.
|
|
379
|
+
|
|
380
|
+
Then report to the controller the pushed SHA, your apply/defer split, how
|
|
381
|
+
many refuters you dispatched against out-of-scope suggestions, and
|
|
382
|
+
the deferral issue numbers — a `filed: #N <subject>` line for every issue
|
|
383
|
+
step 5 created, and `unrecorded: #N <subject>` for one whose `ledger.mjs filed`
|
|
384
|
+
failed twice — and exit. **Deferring everything is a normal
|
|
385
|
+
outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
|
|
386
|
+
index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and you
|
|
387
|
+
report `no-op, HEAD unchanged at <sha>` in place of a new SHA. Say it
|
|
388
|
+
explicitly — silence there is indistinguishable from a member that died. Never
|
|
389
|
+
manufacture a commit to make CI fire.
|
|
390
|
+
## kind: conflict
|
|
391
|
+
Bring `<branch>` current with `origin/main`, resolving every conflict by the
|
|
392
|
+
**No-undo audit** in `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md`.
|
|
393
|
+
Run `<testCmd>` from the worktree before you push, then push with
|
|
394
|
+
`git push origin HEAD:<branch>`. Report the new head, or that no conflict was
|
|
395
|
+
left.
|
|
396
|
+
## kind: dispositions-retry
|
|
397
|
+
|
|
398
|
+
This is the one automatic retry of a dispositions mismatch. The mismatched
|
|
399
|
+
member's record is `<mismatched record>`: start from it, and write your own
|
|
400
|
+
record as above. The check printed these violations, each naming a bucket, an
|
|
401
|
+
index and a rule:
|
|
402
|
+
|
|
403
|
+
<violations>
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
arg ticket N
|
|
3
|
+
arg worktree abs-path
|
|
4
|
+
arg branch branch
|
|
5
|
+
arg scratch scratch
|
|
6
|
+
arg brief distilled brief
|
|
7
|
+
arg staleness staleness
|
|
8
|
+
path worktree
|
|
9
|
+
path scratch
|
|
10
|
+
---
|
|
11
|
+
Implement ticket <N>. You are ALREADY in worktree `<abs-path>`, whose PR branch is
|
|
12
|
+
`<branch>`. Your scratch directory is `<scratch>/impl-<N>/`; write nowhere else
|
|
13
|
+
outside the worktree.
|
|
14
|
+
|
|
15
|
+
The ticket, pasted verbatim from the controller's own read — its title, the
|
|
16
|
+
`## Agent Brief` comment or the issue body, whichever carries the brief, and its
|
|
17
|
+
`Out of scope`:
|
|
18
|
+
|
|
19
|
+
<distilled brief>
|
|
20
|
+
|
|
21
|
+
The controller's staleness probe: <staleness>
|
|
22
|
+
|
|
23
|
+
The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
|
|
24
|
+
A member runs its test suite in the foreground and blocks on it. Exit 75 from the suite is not a test result; run the command again.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
arg n n
|
|
3
|
+
arg scratch scratch
|
|
4
|
+
path scratch
|
|
5
|
+
literal N
|
|
6
|
+
---
|
|
7
|
+
You are merge-bot-<n>. Read `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
|
|
8
|
+
pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
|
|
9
|
+
for late labels, then report once and exit. The controller dispatched you, which
|
|
10
|
+
is what makes you hold that grace instead of arming your own watcher.
|
|
11
|
+
|
|
12
|
+
Your scratch directory is `<scratch>/`; you write only under
|
|
13
|
+
`<scratch>/pr<N>/merge-bot-<n>/`.
|
|
14
|
+
|
|
15
|
+
**zsh word-splits an unquoted command substitution's result; it does NOT split
|
|
16
|
+
an unquoted parameter expansion.** That one difference is the whole rule, and the
|
|
17
|
+
hazard is the **assigned-variable** form, never `$(…)`. Measured on zsh 5.9
|
|
18
|
+
against `849`, `850`, `852` on three lines:
|
|
19
|
+
|
|
20
|
+
| Form | zsh | bash / sh |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| `prs=$(gh pr list …)` then `for pr in $prs` | **1 iteration**, all three glued into one value | 3 |
|
|
23
|
+
| `for pr in $(gh pr list …)` | 3 | 3 |
|
|
24
|
+
| `for _ in $(seq 1 60)` | 60 | 60 |
|
|
25
|
+
|
|
26
|
+
**Word the rule against the first row.** A warning spelled *never `for x in
|
|
27
|
+
$(…)`* names the safe form as the hazard, so a reader avoids the form that works,
|
|
28
|
+
keeps the one that collapses, and rewrites correct bounded polls on the way.
|
|
29
|
+
A ticket was once filed carrying that inversion in its own remedy clause and in its title,
|
|
30
|
+
and its filer measured both forms and retracted it; the corrected rule is this
|
|
31
|
+
row. `$(…)` splits. Leave it alone.
|
|
32
|
+
|
|
33
|
+
**Capture-then-loop needs `while IFS= read -r` fed by a heredoc**, which is
|
|
34
|
+
line-exact under every shell:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
while IFS= read -r pr; do
|
|
38
|
+
[ -n "$pr" ] || continue # a blank line from an empty capture, not a probe that could not look
|
|
39
|
+
node …/ci-state.mjs --pr "$pr" </dev/null # every inner call, per the trap below
|
|
40
|
+
done <<EOF
|
|
41
|
+
$prs
|
|
42
|
+
EOF
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase
|
|
46
|
+
3's block uses, but it splits on *every* whitespace character, so it is safe only
|
|
47
|
+
for values that cannot contain one — PR numbers cannot, branch names and paths
|
|
48
|
+
can. Measured on a two-line list whose first value is `two words`: three
|
|
49
|
+
iterations through `$(printf …)`, two through `while IFS= read -r`. On an empty
|
|
50
|
+
`$prs` the counts diverge the other way: `for pr in $(printf '%s\n' "$prs")`
|
|
51
|
+
iterates **zero** times, but the heredoc form iterates **once** with `pr` empty —
|
|
52
|
+
the guard above is what stops that iteration from probing `--pr ""`.
|
|
53
|
+
|
|
54
|
+
**`</dev/null` every command inside a `while read` loop.** The loop's stdin *is*
|
|
55
|
+
the list, and any inner command that reads stdin eats the rest of it. Measured on
|
|
56
|
+
the three-line list above: one unredirected inner reader takes the loop to **1
|
|
57
|
+
iteration**, `</dev/null` on it restores 3 — the identical signature to the
|
|
58
|
+
word-split bug, so a correct heredoc fix missing this half looks exactly like no
|
|
59
|
+
fix at all, and reads as one.
|
|
60
|
+
|
|
61
|
+
**A probe that could not look emits an event; it never `continue`s.** Stated in
|
|
62
|
+
full at *A probe that cannot read is a transition event, not silence* in Phase 3,
|
|
63
|
+
and it binds every watcher in this file rather than that one block: the third
|
|
64
|
+
value beside pass and fail is what turns a broken loop into a loud failure
|
|
65
|
+
instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json" ]
|
|
66
|
+
|| continue` — makes *could not look* indistinguishable from *nothing to report*.
|
|
67
|
+
|
|
68
|
+
**`$?`/`PIPESTATUS` is unconditionally-TRUE in zsh.** zsh has no `PIPESTATUS`
|
|
69
|
+
(its array is lowercase `pipestatus`, 1-indexed), so `${PIPESTATUS[0]}` is always
|
|
70
|
+
empty and `[ "" -eq 0 ]` passes. A bot's merge gate opened without ever reading
|
|
71
|
+
an exit code.
|
|
72
|
+
|
|
73
|
+
**`status` is a READ-ONLY variable in zsh**, an alias for `$?`. So the obvious
|
|
74
|
+
bash idiom for reading the payload — `status=$(jq -r '.status' ci.json)` — aborts
|
|
75
|
+
with `read-only variable: status`. Measured this way it fails safe (a hard abort,
|
|
76
|
+
no merge), but the same assignment inside an `if`, or with stderr suppressed,
|
|
77
|
+
reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
|
|
78
|
+
trap, opposite failure direction — so name the variable anything else
|
|
79
|
+
(`ci_status`).
|
|
80
|
+
|
|
81
|
+
The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
---
|
|
2
|
+
arg repo repo
|
|
3
|
+
arg scratch scratch
|
|
4
|
+
path repo
|
|
5
|
+
path scratch
|
|
6
|
+
---
|
|
7
|
+
Derive, prove and cache the Recipe of the repository at `<repo>`. Your
|
|
8
|
+
scratch directory is `<scratch>/derive-recipe/`; write nowhere else.
|
|
9
|
+
Follow your definition's procedure exactly, and end with its report line.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
arg pr pr
|
|
3
|
+
arg branch branch
|
|
4
|
+
arg worktree worktree
|
|
5
|
+
arg testCmd testCmd
|
|
6
|
+
arg scratch scratch
|
|
7
|
+
path worktree
|
|
8
|
+
path scratch
|
|
9
|
+
---
|
|
10
|
+
Run the review of PR <pr> and report where its result is. Your five arguments are
|
|
11
|
+
the whole of your task:
|
|
12
|
+
|
|
13
|
+
pr: <pr>
|
|
14
|
+
branch: <branch>
|
|
15
|
+
worktree: <worktree>
|
|
16
|
+
testCmd: <testCmd>
|
|
17
|
+
scratch: <scratch>
|
|
18
|
+
|
|
19
|
+
`scratch` is the scratch root itself, the absolute path `scratch-root.mjs` prints,
|
|
20
|
+
never a directory whose last component is `pr` plus digits: the review creates
|
|
21
|
+
that partition under the root itself.
|
|
22
|
+
|
|
23
|
+
The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
|