@feigi/fleet-ctl 3.53.1 → 3.54.1
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/closeout.mjs +428 -0
- package/scripts/dispatch-prompt.mjs +257 -0
- package/scripts/ledger-grammar.mjs +7 -3
- package/scripts/ledger.mjs +19 -16
- 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
|
@@ -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);
|
|
@@ -22,13 +22,17 @@
|
|
|
22
22
|
import { createHash } from "node:crypto";
|
|
23
23
|
|
|
24
24
|
// How an archive beside the ledger is named. `ledger.mjs rotate` files the
|
|
25
|
-
// ledger as `ledger.<stamp>.md` and the phase-0
|
|
26
|
-
//
|
|
27
|
-
//
|
|
25
|
+
// ledger as `ledger.<stamp>.md` and the two run receipts, the phase-0 one as
|
|
26
|
+
// `phase0.<stamp>.json` and the end-of-run one as `closeout.<stamp>.json`,
|
|
27
|
+
// under one stamp. `phase0.mjs` files a phase-0 receipt the rotation left
|
|
28
|
+
// behind the same way, so the format lives here once.
|
|
28
29
|
const RECEIPT_STEM = "phase0";
|
|
29
30
|
export const RECEIPT = `${RECEIPT_STEM}.json`;
|
|
30
31
|
export const archiveStamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
|
|
31
32
|
export const receiptArchiveName = (stamp) => `${RECEIPT_STEM}.${stamp}.json`;
|
|
33
|
+
const CLOSEOUT_STEM = "closeout";
|
|
34
|
+
export const CLOSEOUT_RECEIPT = `${CLOSEOUT_STEM}.json`;
|
|
35
|
+
export const closeoutArchiveName = (stamp) => `${CLOSEOUT_STEM}.${stamp}.json`;
|
|
32
36
|
|
|
33
37
|
// The outcome vocabulary, verbatim from the spec. A word is matched exactly,
|
|
34
38
|
// except the three that carry a value, which match OUTCOME_PATTERNS below.
|
package/scripts/ledger.mjs
CHANGED
|
@@ -47,7 +47,7 @@ import { fileURLToPath } from "node:url";
|
|
|
47
47
|
import { spawnSync, execFileSync } from "node:child_process";
|
|
48
48
|
import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
|
|
49
49
|
import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
|
|
50
|
-
import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
|
|
50
|
+
import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
|
|
51
51
|
import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD } from "./fleet-tick.mjs";
|
|
52
52
|
import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
|
|
53
53
|
import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
|
|
@@ -1446,10 +1446,10 @@ function runCheck() {
|
|
|
1446
1446
|
// hard-linked to its stamped name, then unlinked or, when a successor is
|
|
1447
1447
|
// carried, replaced by it — so its bytes are untouched, and the link refuses
|
|
1448
1448
|
// atomically when that name is already taken rather than overwriting an older
|
|
1449
|
-
// archive.
|
|
1450
|
-
//
|
|
1451
|
-
// stamp
|
|
1452
|
-
// when
|
|
1449
|
+
// archive. The two receipts beside the ledger, `phase0.json` and
|
|
1450
|
+
// `closeout.json`, belong to the same run, so each is archived as
|
|
1451
|
+
// `<name>.<stamp>.json` under the ledger archive's own stamp — a warning-only
|
|
1452
|
+
// move after the ledger move, refused up front only when a name is taken.
|
|
1453
1453
|
//
|
|
1454
1454
|
// What follows depends on the verdict below. After a `dead` or `none` one
|
|
1455
1455
|
// nothing is carried: the next write subcommand finds no file and starts the
|
|
@@ -1567,14 +1567,17 @@ function runRotate() {
|
|
|
1567
1567
|
carry = carryOf(text);
|
|
1568
1568
|
}
|
|
1569
1569
|
const carrying = carry.rows.length > 0 || carry.dispatched.length > 0 || carry.retired.length > 0;
|
|
1570
|
-
// The
|
|
1571
|
-
//
|
|
1572
|
-
// `ledger.<stamp>.md`. A name already taken
|
|
1573
|
-
// as the ledger's own does.
|
|
1570
|
+
// The receipts beside the ledger belong to the run being rotated away, so
|
|
1571
|
+
// each takes the archive's own stamp: `phase0.<stamp>.json` and
|
|
1572
|
+
// `closeout.<stamp>.json` next to `ledger.<stamp>.md`. A name already taken
|
|
1573
|
+
// refuses before anything moves, as the ledger's own does.
|
|
1574
1574
|
const stamp = archiveStamp();
|
|
1575
|
-
const
|
|
1576
|
-
|
|
1577
|
-
|
|
1575
|
+
const receipts = [[RECEIPT, receiptArchiveName], [CLOSEOUT_RECEIPT, closeoutArchiveName]]
|
|
1576
|
+
.map(([name, archiveName]) => ({ from: join(dirname(file), name), to: join(dirname(file), archiveName(stamp)) }))
|
|
1577
|
+
.filter(({ from }) => existsSync(from));
|
|
1578
|
+
for (const { to } of receipts) {
|
|
1579
|
+
if (existsSync(to)) die(`refusing to rotate ${file}: ${to} already exists`);
|
|
1580
|
+
}
|
|
1578
1581
|
let archive = null;
|
|
1579
1582
|
if (exists) {
|
|
1580
1583
|
archive = join(dirname(file), `${basename(file, ".md")}.${stamp}.md`);
|
|
@@ -1601,12 +1604,12 @@ function runRotate() {
|
|
|
1601
1604
|
// After the ledger has moved, and a warning rather than a refusal: the
|
|
1602
1605
|
// ledger is already archived, and a receipt left where it is is read as a
|
|
1603
1606
|
// previous run's by the next phase 0, which moves it aside itself.
|
|
1604
|
-
|
|
1607
|
+
for (const { from, to } of receipts) {
|
|
1605
1608
|
try {
|
|
1606
|
-
renameSync(
|
|
1607
|
-
console.error(` archived ${
|
|
1609
|
+
renameSync(from, to);
|
|
1610
|
+
console.error(` archived ${from} -> ${to}`);
|
|
1608
1611
|
} catch (e) {
|
|
1609
|
-
console.error(` could not archive ${
|
|
1612
|
+
console.error(` could not archive ${from} -> ${to}: ${e.message}`);
|
|
1610
1613
|
}
|
|
1611
1614
|
}
|
|
1612
1615
|
// Nothing to carry writes nothing, so the next write starts the skeleton
|
|
@@ -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.
|