@feigi/fleet-ctl 3.142.0 → 3.143.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/closeout.mjs +136 -56
- package/scripts/finisher-scope.mjs +12 -1
- package/scripts/main-checkout.mjs +19 -10
- package/scripts/phase0-receipt.mjs +1 -1
- package/scripts/phase0.mjs +85 -7
- package/scripts/reclaim-scratch.mjs +45 -4
- package/scripts/run-records.mjs +251 -0
- package/skills/run-team/references/close-out.md +31 -2
- package/skills/run-team/references/finisher.md +1 -1
- package/skills/run-team/references/phase-0.md +30 -2
package/package.json
CHANGED
package/scripts/closeout.mjs
CHANGED
|
@@ -38,13 +38,31 @@
|
|
|
38
38
|
// The verdicts come from `tier-outcomes.mjs append`, which
|
|
39
39
|
// works them out from the Charges; this script never writes one.
|
|
40
40
|
// metrics `metrics-refresh.mjs`. Any non-zero exit is a failed step.
|
|
41
|
+
// gather run-records.mjs's gather(): every run archive `ledger.mjs
|
|
42
|
+
// rotate` left in `.fleet/` (`ledger.<stamp>.md`,
|
|
43
|
+
// `phase0.<stamp>.json`, `closeout.<stamp>.json`) into
|
|
44
|
+
// `docs/metrics/runs/<stamp>/` with its `plugin-version`, and
|
|
45
|
+
// every review's `review.json` and Charges file under the
|
|
46
|
+
// scratch root into `docs/metrics/reviews/<pr>/<run>/`. The
|
|
47
|
+
// phase-0 receipt's `recipe` step output is withheld, since
|
|
48
|
+
// a Recipe command can carry an environment assignment. A
|
|
49
|
+
// run's own archives exist only once the next run has
|
|
50
|
+
// rotated, so this commits the runs before it; a file main
|
|
51
|
+
// already holds comes back byte for byte and adds nothing.
|
|
52
|
+
// A directory it cannot list or a file it cannot copy fails
|
|
53
|
+
// the step.
|
|
41
54
|
// commit-and-pr `git switch -c <branch>` (`--branch`, default
|
|
42
55
|
// `chore/run-artifacts-<UTC date>`, suffixed `b`, `c`… while
|
|
43
|
-
// that name exists locally or on origin),
|
|
44
|
-
//
|
|
45
|
-
//
|
|
46
|
-
//
|
|
47
|
-
//
|
|
56
|
+
// that name exists locally or on origin), `git add` the
|
|
57
|
+
// new and changed files under `docs/metrics/runs/` and
|
|
58
|
+
// `docs/metrics/reviews/` that isRunRecord() allows, commit
|
|
59
|
+
// exactly those and the three `docs/metrics/*.tsv` files,
|
|
60
|
+
// `git fetch origin`, `git rebase origin/main`, push `-u`
|
|
61
|
+
// with a lease, `gh pr
|
|
62
|
+
// create --label patch` with a body naming the reason, the
|
|
63
|
+
// rows each file gained and lost and the record files
|
|
64
|
+
// added, `git switch main`. A file there that isRunRecord()
|
|
65
|
+
// does not allow is never staged; the output names it. The
|
|
48
66
|
// rebase is three-way, so rows `main` gained during the run
|
|
49
67
|
// stay; one that conflicts or that git refuses is aborted, the
|
|
50
68
|
// branch is pushed as it was, and the PR is opened all the
|
|
@@ -146,13 +164,14 @@ import { homedir } from "node:os";
|
|
|
146
164
|
import { dirname, join } from "node:path";
|
|
147
165
|
import { fileURLToPath } from "node:url";
|
|
148
166
|
import { makeDie, defineFlags } from "./arg.mjs";
|
|
149
|
-
import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
|
|
167
|
+
import { FleetDirUnresolvable, fleetFile, scratchRoot } from "./fleet-dir.mjs";
|
|
150
168
|
import { inertVerdict } from "./finisher-scope.mjs";
|
|
151
169
|
import { gitEnv } from "./git-env.mjs";
|
|
152
170
|
import { isCLI } from "./is-cli.mjs";
|
|
153
171
|
import { CLOSEOUT_RECEIPT, RECEIPT, RECEIPT_HELD, memberTokens, rowPr, isOmpSessionDirName } from "./ledger-grammar.mjs";
|
|
154
172
|
import { encodeProjectDir } from "./member-record.mjs";
|
|
155
173
|
import { tickCaps } from "./phase0-receipt.mjs";
|
|
174
|
+
import { RECORD_DIRS, gather, recordChanges, refusedLine } from "./run-records.mjs";
|
|
156
175
|
|
|
157
176
|
const NAME = "closeout";
|
|
158
177
|
const SCRIPTS = dirname(fileURLToPath(import.meta.url));
|
|
@@ -334,12 +353,31 @@ function stepMetrics({ cwd }) {
|
|
|
334
353
|
return r.status === 0 ? ok(r.stdout) : failed(`metrics-refresh.mjs failed: ${detail(r)}`);
|
|
335
354
|
}
|
|
336
355
|
|
|
337
|
-
//
|
|
356
|
+
// Copies the run archives and the review evidence into the checkout, for the
|
|
357
|
+
// commit step to stage.
|
|
358
|
+
function stepGather({ fleetDir }) {
|
|
359
|
+
const wt = workTree();
|
|
360
|
+
if (wt.error) return failed(wt.error);
|
|
361
|
+
let scratch;
|
|
362
|
+
try {
|
|
363
|
+
scratch = scratchRoot({ cwd: wt.cwd });
|
|
364
|
+
} catch (e) {
|
|
365
|
+
if (!(e instanceof FleetDirUnresolvable)) throw e;
|
|
366
|
+
return failed(`cannot name the scratch root: ${e.message}`);
|
|
367
|
+
}
|
|
368
|
+
try {
|
|
369
|
+
return ok(gather({ cwd: wt.cwd, fleetDir, scratch }).join("\n"));
|
|
370
|
+
} catch (e) {
|
|
371
|
+
return failed(`gather failed: ${e.message}`);
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
// A name for the branch: `--branch` as given, else `stem` and the UTC date,
|
|
338
376
|
// lettered while the name is taken. A probe that fails to answer is no answer
|
|
339
377
|
// at all, never "not taken".
|
|
340
|
-
function pickBranch(git, given) {
|
|
378
|
+
function pickBranch(git, given, stem) {
|
|
341
379
|
if (given !== null) return { name: given };
|
|
342
|
-
const base =
|
|
380
|
+
const base = `${stem}${new Date().toISOString().slice(0, 10).replaceAll("-", "")}`;
|
|
343
381
|
for (const suffix of ["", ..."bcdefghijklmnopqrstuvwxyz"]) {
|
|
344
382
|
const name = base + suffix;
|
|
345
383
|
const local = git(["show-ref", "--verify", "--quiet", `refs/heads/${name}`]);
|
|
@@ -351,11 +389,22 @@ function pickBranch(git, given) {
|
|
|
351
389
|
return { error: `every lettered ${base} name is taken` };
|
|
352
390
|
}
|
|
353
391
|
|
|
354
|
-
// The rows each metrics file gained and lost on the branch, one TSV line a
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
392
|
+
// The rows each metrics file gained and lost on the branch, one TSV line a
|
|
393
|
+
// row, then the record files it adds under each of RECORD_DIRS.
|
|
394
|
+
function rowCounts(git, tsvs) {
|
|
395
|
+
const lines = [];
|
|
396
|
+
if (tsvs.length > 0) {
|
|
397
|
+
const r = git(["diff", "--numstat", "origin/main...HEAD", "--", ...tsvs]);
|
|
398
|
+
if (r.status !== 0) return { error: `git diff --numstat failed: ${detail(r)}` };
|
|
399
|
+
lines.push(...r.stdout.split("\n").filter(Boolean).map((l) => l.split("\t")).map(([added, removed, file]) => `- ${file}: +${added} -${removed}`));
|
|
400
|
+
}
|
|
401
|
+
for (const dir of RECORD_DIRS) {
|
|
402
|
+
const r = git(["diff", "--name-only", "--diff-filter=A", "origin/main...HEAD", "--", dir]);
|
|
403
|
+
if (r.status !== 0) return { error: `git diff --name-only -- ${dir} failed: ${detail(r)}` };
|
|
404
|
+
const added = r.stdout.split("\n").filter(Boolean).length;
|
|
405
|
+
if (added > 0) lines.push(`- ${dir}/: ${added} file(s) added`);
|
|
406
|
+
}
|
|
407
|
+
return { lines };
|
|
359
408
|
}
|
|
360
409
|
|
|
361
410
|
// Replays the branch's commit onto the `origin/main` just fetched, three-way,
|
|
@@ -385,42 +434,57 @@ function rebaseOntoMain(git) {
|
|
|
385
434
|
return { leftOpen: `rebase refused: ${refused}` };
|
|
386
435
|
}
|
|
387
436
|
|
|
388
|
-
// Everything the
|
|
389
|
-
// caller switches back to main whatever this returns.
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
const
|
|
398
|
-
|
|
437
|
+
// Everything the commit flow does while the checkout is on its branch; the
|
|
438
|
+
// caller switches back to main whatever this returns or throws. `tsvs` are
|
|
439
|
+
// the metrics files the commit carries beside the record files; `rebase`
|
|
440
|
+
// false skips the fetch and the replay, for a caller whose branch was cut from
|
|
441
|
+
// an `origin/main` it has just fetched and whose work tree may hold changes
|
|
442
|
+
// the commit leaves out.
|
|
443
|
+
function onBranch({ git, cwd, title, tsvs, rebase, state, save }) {
|
|
444
|
+
const records = recordChanges(git, cwd);
|
|
445
|
+
if (records.error) return failed(records.error);
|
|
446
|
+
const refusedLines = records.refused.map(refusedLine);
|
|
447
|
+
const fail = (line) => failed([...refusedLines, line].join("\n"));
|
|
448
|
+
if (records.allowed.length > 0) {
|
|
449
|
+
const add = git(["add", "--", ...records.allowed]);
|
|
450
|
+
if (add.status !== 0) return fail(`git add failed: ${detail(add)}`);
|
|
451
|
+
}
|
|
452
|
+
const paths = [...tsvs, ...records.allowed];
|
|
453
|
+
if (paths.length > 0) {
|
|
454
|
+
const dirty = git(["status", "--porcelain", "--", ...paths]);
|
|
455
|
+
if (dirty.status !== 0) return fail(`git status failed: ${detail(dirty)}`);
|
|
456
|
+
if (dirty.stdout !== "") {
|
|
457
|
+
const commit = git(["commit", "-m", title, "--", ...paths]);
|
|
458
|
+
if (commit.status !== 0) return fail(`git commit failed: ${detail(commit)}`);
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
const rebased = rebase ? rebaseOntoMain(git) : { leftOpen: null };
|
|
462
|
+
if (rebased.error) return fail(rebased.error);
|
|
399
463
|
const ahead = git(["rev-list", "--count", "origin/main..HEAD"]);
|
|
400
|
-
if (ahead.status !== 0) return
|
|
401
|
-
if (ahead.stdout === "0") return
|
|
464
|
+
if (ahead.status !== 0) return fail(`git rev-list --count origin/main..HEAD failed: ${detail(ahead)}`);
|
|
465
|
+
if (ahead.stdout === "0") return fail(`nothing to commit: ${[...tsvs, ...RECORD_DIRS].join(", ")} are unchanged`);
|
|
402
466
|
const head = git(["rev-parse", "HEAD"]);
|
|
403
|
-
if (head.status !== 0) return
|
|
467
|
+
if (head.status !== 0) return fail(`git rev-parse HEAD failed: ${detail(head)}`);
|
|
404
468
|
|
|
405
469
|
// The lease is the head this step last pushed, never what the fetch above
|
|
406
470
|
// just read: an empty one expects the branch absent from origin.
|
|
407
|
-
const lease = `--force-with-lease=refs/heads/${
|
|
408
|
-
const push = git(["push", "-u", lease, "origin",
|
|
409
|
-
if (push.status !== 0) return
|
|
410
|
-
|
|
411
|
-
|
|
471
|
+
const lease = `--force-with-lease=refs/heads/${state.branch}:${state.pin ?? ""}`;
|
|
472
|
+
const push = git(["push", "-u", lease, "origin", state.branch], NETWORK_TIMEOUT_MS);
|
|
473
|
+
if (push.status !== 0) return fail(`git push failed: ${detail(push)}`);
|
|
474
|
+
state.pin = head.stdout;
|
|
475
|
+
state.rebase = rebased.leftOpen;
|
|
412
476
|
save();
|
|
413
|
-
const lines = [`pushed ${
|
|
414
|
-
|
|
415
|
-
if (
|
|
416
|
-
const counts = rowCounts(git);
|
|
417
|
-
if (counts.error) return
|
|
418
|
-
const body =
|
|
419
|
-
const pr = run("gh", ["pr", "create", "--head",
|
|
420
|
-
if (pr.status !== 0) return
|
|
421
|
-
|
|
477
|
+
const lines = [...refusedLines, `pushed ${state.pin}`, ...(rebased.leftOpen === null ? [] : [rebased.leftOpen])];
|
|
478
|
+
|
|
479
|
+
if (state.pr !== null) return ok([...lines, `PR ${state.pr} already opened for ${state.branch}`].join("\n"));
|
|
480
|
+
const counts = rowCounts(git, tsvs);
|
|
481
|
+
if (counts.error) return fail(counts.error);
|
|
482
|
+
const body = `${title}\n\nRows changed:\n${counts.lines.join("\n")}\n`;
|
|
483
|
+
const pr = run("gh", ["pr", "create", "--head", state.branch, "--title", title, "--label", "patch", "--body", body], { cwd, env: { GH_REPO: "" }, timeoutMs: NETWORK_TIMEOUT_MS });
|
|
484
|
+
if (pr.status !== 0) return fail(`gh pr create failed: ${detail(pr)}`);
|
|
485
|
+
state.pr = pr.stdout.split("\n").at(-1);
|
|
422
486
|
save();
|
|
423
|
-
return ok([...lines, `PR ${
|
|
487
|
+
return ok([...lines, `PR ${state.pr} opened on ${state.branch}`].join("\n"));
|
|
424
488
|
}
|
|
425
489
|
|
|
426
490
|
// The work tree the command runs in, as `{ cwd }`, or `{ error }`.
|
|
@@ -429,29 +493,44 @@ function workTree() {
|
|
|
429
493
|
return top.status === 0 ? { cwd: top.stdout } : { error: `not inside a git work tree: ${detail(top)}` };
|
|
430
494
|
}
|
|
431
495
|
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
496
|
+
/**
|
|
497
|
+
* The commit flow the Close-out PR and phase 0's catch-up share, run in the
|
|
498
|
+
* checkout at `cwd`: switch to `state.branch`, or cut one (`given`, else
|
|
499
|
+
* pickBranch() over `stem`) when it is null, stage and commit the allowed
|
|
500
|
+
* record files and `tsvs` under `title`, rebase when `rebase` is true, push
|
|
501
|
+
* with a lease, open the PR, and switch back to main, a throw on the branch
|
|
502
|
+
* included. `state` carries `{branch, pr, pin, rebase}` across calls and
|
|
503
|
+
* `save()` records it. The result is a step's `{status, output}`.
|
|
504
|
+
*/
|
|
505
|
+
export function commitAndPr({ cwd, given = null, stem, title, tsvs, rebase, state, save }) {
|
|
436
506
|
const git = (args, timeoutMs) => run("git", args, { cwd, timeoutMs });
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
const picked = pickBranch(git, branch);
|
|
507
|
+
if (state.branch === null) {
|
|
508
|
+
const picked = pickBranch(git, given, stem);
|
|
440
509
|
if (picked.error) return failed(picked.error);
|
|
441
510
|
const made = git(["switch", "-c", picked.name]);
|
|
442
511
|
if (made.status !== 0) return failed(`git switch -c ${picked.name} failed: ${detail(made)}`);
|
|
443
|
-
|
|
512
|
+
state.branch = picked.name;
|
|
444
513
|
save();
|
|
445
514
|
} else {
|
|
446
|
-
const back = git(["switch",
|
|
447
|
-
if (back.status !== 0) return failed(`git switch ${
|
|
515
|
+
const back = git(["switch", state.branch]);
|
|
516
|
+
if (back.status !== 0) return failed(`git switch ${state.branch} failed: ${detail(back)}`);
|
|
517
|
+
}
|
|
518
|
+
let result = null;
|
|
519
|
+
try {
|
|
520
|
+
result = onBranch({ git, cwd, title, tsvs, rebase, state, save });
|
|
521
|
+
} finally {
|
|
522
|
+
const main = git(["switch", "main"]);
|
|
523
|
+
if (main.status !== 0 && result !== null) result = failed([result.status === "ok" ? null : result.output, `git switch main failed: ${detail(main)}`].filter(Boolean).join("\n"));
|
|
448
524
|
}
|
|
449
|
-
const result = onBranch({ git, cwd, reason, receipt, save });
|
|
450
|
-
const main = git(["switch", "main"]);
|
|
451
|
-
if (main.status !== 0) return failed([result.status === "ok" ? null : result.output, `git switch main failed: ${detail(main)}`].filter(Boolean).join("\n"));
|
|
452
525
|
return result;
|
|
453
526
|
}
|
|
454
527
|
|
|
528
|
+
function stepCommitAndPR({ reason, branch, receipt, save }) {
|
|
529
|
+
const wt = workTree();
|
|
530
|
+
if (wt.error) return failed(wt.error);
|
|
531
|
+
return commitAndPr({ cwd: wt.cwd, given: branch, stem: "chore/run-artifacts-", title: `Closeout: ${reason}`, tsvs: METRICS, rebase: true, state: receipt, save });
|
|
532
|
+
}
|
|
533
|
+
|
|
455
534
|
// The receipt `phase0.mjs` resumes would otherwise outlive the run it describes.
|
|
456
535
|
// It is set aside under the name `phase0.mjs` holds a previous run's receipt
|
|
457
536
|
// under, which the next run's rotation restores and archives with the ledger.
|
|
@@ -619,6 +698,7 @@ const FINISH = {
|
|
|
619
698
|
scrape: stepScrape,
|
|
620
699
|
"tier-outcomes": stepTierOutcomes,
|
|
621
700
|
metrics: stepMetrics,
|
|
701
|
+
gather: stepGather,
|
|
622
702
|
"commit-and-pr": stepCommitAndPR,
|
|
623
703
|
"phase0-receipt": stepPhase0Receipt,
|
|
624
704
|
"heartbeat-stop": stepHeartbeatStop,
|
|
@@ -30,7 +30,11 @@
|
|
|
30
30
|
// CLAUDE.md or GEMINI.md, at any depth. A file directly in the root
|
|
31
31
|
// .out-of-scope/, spelled exactly so, is exempt from the dot rule
|
|
32
32
|
// alone
|
|
33
|
-
// data one of the METRICS paths closeout.mjs names,
|
|
33
|
+
// data one of the METRICS paths closeout.mjs names, or a run record or
|
|
34
|
+
// review evidence file run-records.mjs's isRunRecord() accepts — a
|
|
35
|
+
// path of the allowlisted shape under docs/metrics/runs/ or
|
|
36
|
+
// docs/metrics/reviews/ — that is also outside the prompt surface,
|
|
37
|
+
// and no other file
|
|
34
38
|
//
|
|
35
39
|
// Stdout is one JSON line:
|
|
36
40
|
//
|
|
@@ -60,6 +64,7 @@ import { statSync } from "node:fs";
|
|
|
60
64
|
import { isAbsolute, resolve } from "node:path";
|
|
61
65
|
import { makeDie, defineFlags, writeAll } from "./arg.mjs";
|
|
62
66
|
import { METRICS } from "./closeout.mjs";
|
|
67
|
+
import { isRunRecord } from "./run-records.mjs";
|
|
63
68
|
import { isDocs, isMarkdown, isTestDir } from "./diff-stats.mjs";
|
|
64
69
|
import { gitEnv } from "./git-env.mjs";
|
|
65
70
|
import { isCLI } from "./is-cli.mjs";
|
|
@@ -136,6 +141,12 @@ export function classifyEntry(path, status, oldMode, newMode) {
|
|
|
136
141
|
const mode = modeProblem(status, oldMode, newMode);
|
|
137
142
|
if (mode !== null) return { class: null, why: mode };
|
|
138
143
|
if (METRICS.includes(path)) return { class: "data", why: "run metrics file" };
|
|
144
|
+
if (isRunRecord(path)) {
|
|
145
|
+
// No name isRunRecord() accepts is on the prompt surface today; the check
|
|
146
|
+
// stays so a record still has to pass it should either rule ever widen.
|
|
147
|
+
const surface = promptSurface(path);
|
|
148
|
+
return surface === null ? { class: "data", why: "run record or review evidence file" } : { class: null, why: surface };
|
|
149
|
+
}
|
|
139
150
|
if (isTestDir(path)) return { class: null, why: "under a test directory" };
|
|
140
151
|
if (!isMarkdown(path)) return { class: null, why: isDocs(path) ? "docs, but not .md or .markdown" : "not prose or data" };
|
|
141
152
|
const surface = promptSurface(path);
|
|
@@ -56,10 +56,17 @@
|
|
|
56
56
|
// Compared like any other path, the first append would hold every
|
|
57
57
|
// dispatching row for the rest of the run, and clearing it with `--record`
|
|
58
58
|
// after every ruling would certify whatever stray write landed beside it.
|
|
59
|
-
// So `snapshot()` leaves
|
|
60
|
-
//
|
|
61
|
-
//
|
|
62
|
-
//
|
|
59
|
+
// So `snapshot()` leaves those three paths out, for the reason instruments.sh
|
|
60
|
+
// leaves `docs/metrics/` out of its pin.
|
|
61
|
+
// The same holds for the run records and review evidence the close-out and
|
|
62
|
+
// phase 0's catch-up copy into `docs/metrics/runs/` and `docs/metrics/reviews/`
|
|
63
|
+
// and commit on a branch, which appear in the work tree and leave it again
|
|
64
|
+
// when the checkout switches back to main: a path run-records.mjs's
|
|
65
|
+
// isRunRecord() allows is left out too, while it is the regular file with no
|
|
66
|
+
// executable bit a commit carries. A symlink or an executable there, which
|
|
67
|
+
// the commit refuses, is still audited. Named files and one allowlisted shape,
|
|
68
|
+
// not the directory: anything else under `docs/metrics/` is still a stray
|
|
69
|
+
// write. The price: a member's leaked write to one of those paths goes unseen.
|
|
63
70
|
//
|
|
64
71
|
// FOUR ANSWERS, worktree-audit.sh's three plus the baseline's own refusal:
|
|
65
72
|
// clean — the porcelain entries and hashes equal the baseline's, and HEAD
|
|
@@ -124,10 +131,12 @@ import { join } from "node:path";
|
|
|
124
131
|
import { isCLI } from "./is-cli.mjs";
|
|
125
132
|
import { makeDie, defineFlags } from "./arg.mjs";
|
|
126
133
|
import { gitEnv, mainCheckoutDirFromGitCommonDir } from "./git-env.mjs";
|
|
134
|
+
import { isPlainFile, isRunRecord } from "./run-records.mjs";
|
|
127
135
|
|
|
128
136
|
export const BASELINE_FILE = "main-checkout.sha";
|
|
129
137
|
export const RECORD_COMMAND = "~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-checkout.mjs --record";
|
|
130
|
-
const
|
|
138
|
+
const RUN_METRICS = new Set(["docs/metrics/tier-outcomes.tsv", "docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv"]);
|
|
139
|
+
const isRunBookkeeping = (root, rel) => RUN_METRICS.has(rel) || (isRunRecord(rel) && isPlainFile(join(root, rel)));
|
|
131
140
|
// Any change to an entry's hash or to a line's format bumps VERSION: a
|
|
132
141
|
// baseline an older plugin wrote then reads `outdated` (re-record) and one a
|
|
133
142
|
// newer plugin wrote reads `newer`, never as a baseline this code wrote.
|
|
@@ -209,11 +218,11 @@ const sha = (buf) => createHash("sha256").update(buf).digest("hex");
|
|
|
209
218
|
// the hash where its status line would not — folded with its HEAD, so a
|
|
210
219
|
// commit in it moves the hash too. A commitless repository's HEAD is the
|
|
211
220
|
// branch it names. Nothing is left out: the run's bookkeeping is
|
|
212
|
-
// `
|
|
221
|
+
// `isRunBookkeeping`, the main checkout's paths, not a nested
|
|
213
222
|
// repository's. Any git that fails throws: `unknown`, never a hash that reads
|
|
214
223
|
// clean.
|
|
215
224
|
function nestedHash(abs, env) {
|
|
216
|
-
const now = entriesAt(abs, env,
|
|
225
|
+
const now = entriesAt(abs, env, () => false);
|
|
217
226
|
if (!now.ok) throw new Error(now.why);
|
|
218
227
|
let head = git("git rev-parse HEAD", ["rev-parse", "-q", "--verify", "HEAD^{commit}"], abs, env);
|
|
219
228
|
if (!head.ok) {
|
|
@@ -241,10 +250,10 @@ function nestedHash(abs, env) {
|
|
|
241
250
|
* `--no-renames` so every entry names exactly one path.
|
|
242
251
|
*/
|
|
243
252
|
export function snapshot(root, env = process.env) {
|
|
244
|
-
return entriesAt(root, env,
|
|
253
|
+
return entriesAt(root, env, (rel) => isRunBookkeeping(root, rel));
|
|
245
254
|
}
|
|
246
255
|
|
|
247
|
-
// `snapshot` of the repository at `root`, leaving out
|
|
256
|
+
// `snapshot` of the repository at `root`, leaving out each path `skip` accepts.
|
|
248
257
|
function entriesAt(root, env, skip) {
|
|
249
258
|
const r = git("git status --porcelain -uall", ["--no-optional-locks", "status", "--porcelain", "-uall", "-z", "--no-renames"], root, env);
|
|
250
259
|
if (!r.ok) return r;
|
|
@@ -253,8 +262,8 @@ function entriesAt(root, env, skip) {
|
|
|
253
262
|
if (!line) continue;
|
|
254
263
|
if (line.length < 4 || line[2] !== " ") return { ok: false, why: `git status printed an entry it does not document: ${JSON.stringify(line)}` };
|
|
255
264
|
const rel = line.slice(3);
|
|
256
|
-
if (skip.has(rel)) continue;
|
|
257
265
|
try {
|
|
266
|
+
if (skip(rel)) continue;
|
|
258
267
|
entries.set(line, hashPath(root, rel, env));
|
|
259
268
|
} catch (e) {
|
|
260
269
|
return { ok: false, why: `cannot hash ${rel}: ${e?.code ?? e?.message ?? e}` };
|
|
@@ -20,7 +20,7 @@ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x)
|
|
|
20
20
|
// by a finished phase 0.
|
|
21
21
|
export const STEP_NAMES = Object.freeze([
|
|
22
22
|
"alarm", "branch", "fast-forward", "pin", "baseline", "labels", "preflight", "ruleset", "tier-roles", "metrics",
|
|
23
|
-
"cockpit", "rotate", "reclaim", "evict", "recipe", "fold-in", "stranded", "shortlist",
|
|
23
|
+
"cockpit", "rotate", "catch-up", "reclaim", "evict", "recipe", "fold-in", "stranded", "shortlist",
|
|
24
24
|
]);
|
|
25
25
|
|
|
26
26
|
// The statuses a step can end in that let the run go on: `ok`, and the two
|
package/scripts/phase0.mjs
CHANGED
|
@@ -18,9 +18,9 @@
|
|
|
18
18
|
// worktree refuses: the checks below judge the checkout the controller reads
|
|
19
19
|
// its rules from). The steps, each a named entry in the receipt, run in
|
|
20
20
|
// this order because the order is the point — the pin is recorded after the
|
|
21
|
-
// fast-forward, the rotation comes before the fold-in, the
|
|
22
|
-
//
|
|
23
|
-
// Pull is routed:
|
|
21
|
+
// fast-forward, the rotation comes before the fold-in, the catch-up straight
|
|
22
|
+
// after the rotation and the scratch reclaim straight after the catch-up, the
|
|
23
|
+
// metrics refresh before the first Pull is routed:
|
|
24
24
|
//
|
|
25
25
|
// alarm `~/.fleet/alarm/<pid>.json` names this omp's pid and start time
|
|
26
26
|
// and this `.fleet/`. Missing, malformed or mismatched, or no omp
|
|
@@ -38,6 +38,8 @@
|
|
|
38
38
|
// pin `instruments.sh --pin`, which certifies the Install root; the
|
|
39
39
|
// ok line names its kind, root and version. A linked
|
|
40
40
|
// checkout refuses: a fleet run executes an installed package.
|
|
41
|
+
// The `version=` line the pin writes to
|
|
42
|
+
// `.fleet/instruments.sha` is the receipt's `pluginVersion`.
|
|
41
43
|
// baseline `main-checkout.mjs --record`; its refusals fail the step.
|
|
42
44
|
// labels `label-map.mjs ensure`, the Label map derivation step. Exit 0
|
|
43
45
|
// is ok, its output the map ensure printed. Exit 3 is pending,
|
|
@@ -65,6 +67,25 @@
|
|
|
65
67
|
// cockpit `board.mjs serve --open` launched detached, `--spend-dir`
|
|
66
68
|
// passed through. Recorded; never fails the run.
|
|
67
69
|
// rotate `ledger.mjs rotate`. Exit 2 is a refusal and fails the step.
|
|
70
|
+
// catch-up run-records.mjs's gather() copies every run archive in
|
|
71
|
+
// `.fleet/` (the previous run's, which the rotation has just
|
|
72
|
+
// filed, and any earlier one) and every review evidence file
|
|
73
|
+
// under the scratch root into `docs/metrics/runs/` and
|
|
74
|
+
// `docs/metrics/reviews/`; when that leaves main lacking a
|
|
75
|
+
// record of a run that never closed out — no
|
|
76
|
+
// `closeout.<stamp>.json` beside its ledger archive —
|
|
77
|
+
// closeout.mjs's commitAndPr() commits every file main lacks
|
|
78
|
+
// alone on `chore/run-records-<UTC date>` (lettered while
|
|
79
|
+
// taken), pushes it and opens a PR, then switches back to
|
|
80
|
+
// main. A run that closed out leaves its records to this
|
|
81
|
+
// run's close-out, which gathers them again, so the catch-up
|
|
82
|
+
// opens no second PR carrying the same files. Before the
|
|
83
|
+
// reclaim, so a close-out that never ran loses nothing: the
|
|
84
|
+
// reclaim keeps a merged PR's evidence until main holds it.
|
|
85
|
+
// Recorded, and never fails the run but for a checkout it
|
|
86
|
+
// could not switch back to main; what it could not commit,
|
|
87
|
+
// the close-out gathers again, and its output says how far
|
|
88
|
+
// a failed commit got — a branch pushed with no PR included.
|
|
68
89
|
// reclaim `reclaim-scratch.mjs --root <scratch> --after-rotate --apply`,
|
|
69
90
|
// then `reclaim-scratch.mjs --siblings --root <scratch> --apply`
|
|
70
91
|
// for the other keys under the scratch parent, which runs
|
|
@@ -102,7 +123,7 @@
|
|
|
102
123
|
// THE RECEIPT is `.fleet/phase0.json` (resolved through fleet-dir.mjs, so a
|
|
103
124
|
// worktree and the main checkout name one file):
|
|
104
125
|
//
|
|
105
|
-
// { run, session, scratch, inFlight, objective,
|
|
126
|
+
// { run, session, scratch, inFlight, objective, pluginVersion,
|
|
106
127
|
// steps: { <name>: { status, at, output } } }
|
|
107
128
|
//
|
|
108
129
|
// `status` is ok, pending, failed, drift or unanswered; `at` an ISO time;
|
|
@@ -119,6 +140,8 @@
|
|
|
119
140
|
// default when it records none — and a resume whose `--objective` names the
|
|
120
141
|
// other one exits 2 naming both, leaving the receipt as it was. A resumed
|
|
121
142
|
// receipt recording a value that is not an Objective exits 3 naming it.
|
|
143
|
+
// `pluginVersion` is the version the pin recorded, null when it recorded
|
|
144
|
+
// none; a resumed receipt keeps it.
|
|
122
145
|
//
|
|
123
146
|
// RESUMABLE. A re-run reads the receipt. It continues it — skipping every `ok`
|
|
124
147
|
// step but `alarm` and re-running the rest — only when its `run` equals the
|
|
@@ -173,6 +196,7 @@ import { dirname, join, resolve } from "node:path";
|
|
|
173
196
|
import { fileURLToPath } from "node:url";
|
|
174
197
|
import { makeDie, defineFlags, isDigits } from "./arg.mjs";
|
|
175
198
|
import { alarmFile } from "./controller-alarm.mjs";
|
|
199
|
+
import { commitAndPr } from "./closeout.mjs";
|
|
176
200
|
import { ownClosingIssues } from "./closing-refs.mjs";
|
|
177
201
|
import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
|
|
178
202
|
import { readState, stateFileIn } from "./fleet-state.mjs";
|
|
@@ -183,6 +207,7 @@ import { OBJECTIVES, RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, ro
|
|
|
183
207
|
import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
|
|
184
208
|
import { IN_FLIGHT_DEFAULT, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
|
|
185
209
|
import { readRecipe } from "./recipe-read.mjs";
|
|
210
|
+
import { gather, recordChanges, refusedLine, unclosedRecords } from "./run-records.mjs";
|
|
186
211
|
|
|
187
212
|
const NAME = "phase0";
|
|
188
213
|
const SCRIPTS = dirname(fileURLToPath(import.meta.url));
|
|
@@ -249,14 +274,28 @@ function fastForward({ cwd }) {
|
|
|
249
274
|
return ok(`fast-forwarded ${behind} commits to origin/main`);
|
|
250
275
|
}
|
|
251
276
|
|
|
252
|
-
function pin({ cwd }) {
|
|
277
|
+
function pin({ cwd, fleetDir, receipt }) {
|
|
253
278
|
const r = sh("instruments.sh", ["--pin"], { cwd });
|
|
254
279
|
if (r.status !== 0) return refusal("instruments.sh --pin failed:", r);
|
|
280
|
+
receipt.pluginVersion = pinnedVersion(fleetDir);
|
|
255
281
|
// `instruments: pinned <digest> over <kind> <root> (version <v>)`
|
|
256
282
|
const m = /^instruments: pinned [0-9a-f]+ over (.+)$/m.exec(r.stderr);
|
|
257
283
|
return ok(`instruments pinned: ${m ? m[1] : r.stderr || "?"}`);
|
|
258
284
|
}
|
|
259
285
|
|
|
286
|
+
// The `version=` line of the pin `instruments.sh --pin` just wrote, or null
|
|
287
|
+
// when it wrote none or the file cannot be read.
|
|
288
|
+
function pinnedVersion(fleetDir) {
|
|
289
|
+
let text;
|
|
290
|
+
try {
|
|
291
|
+
text = readFileSync(join(fleetDir, "instruments.sha"), "utf8");
|
|
292
|
+
} catch {
|
|
293
|
+
return null;
|
|
294
|
+
}
|
|
295
|
+
const m = /^version=(\S+)$/m.exec(text);
|
|
296
|
+
return m === null ? null : m[1];
|
|
297
|
+
}
|
|
298
|
+
|
|
260
299
|
function baseline({ cwd }) {
|
|
261
300
|
const r = node("main-checkout.mjs", ["--record"], { cwd });
|
|
262
301
|
if (r.status !== 0) return refusal("main-checkout.mjs --record refused:", r);
|
|
@@ -352,6 +391,44 @@ function rotate(ctx) {
|
|
|
352
391
|
return ok([head, ...lines(r.stderr).map((l) => l.trim())].join("\n"));
|
|
353
392
|
}
|
|
354
393
|
|
|
394
|
+
// The previous runs' archives and the review evidence in scratch, committed on
|
|
395
|
+
// a branch of their own when main lacks a record of a run that never closed
|
|
396
|
+
// out. A run that closed out leaves its records to the next close-out, this
|
|
397
|
+
// run's, which gathers everything again, so committing them here too would
|
|
398
|
+
// open a second PR carrying the same files. The work tree may hold the metrics
|
|
399
|
+
// refresh's rows, which the commit leaves out, so the branch is cut from the
|
|
400
|
+
// main the fast-forward just brought level and is not rebased.
|
|
401
|
+
function catchUp({ cwd, fleetDir, scratch }) {
|
|
402
|
+
let gathered;
|
|
403
|
+
try {
|
|
404
|
+
gathered = gather({ cwd, fleetDir, scratch });
|
|
405
|
+
} catch (e) {
|
|
406
|
+
return ok(`not gathered: ${e.message} — the close-out gathers them`);
|
|
407
|
+
}
|
|
408
|
+
const git = (args, timeoutMs) => run("git", args, { cwd, timeoutMs });
|
|
409
|
+
const records = recordChanges(git, cwd);
|
|
410
|
+
if (records.error) return ok([...gathered, `not committed: ${records.error} — the close-out commits them`].join("\n"));
|
|
411
|
+
const refused = records.refused.map(refusedLine);
|
|
412
|
+
if (records.allowed.length === 0) {
|
|
413
|
+
return ok([...gathered, ...refused, "nothing to catch up: main holds every run record and review evidence file"].join("\n"));
|
|
414
|
+
}
|
|
415
|
+
if (unclosedRecords(fleetDir, records.allowed).length === 0) {
|
|
416
|
+
return ok([...gathered, ...refused, "nothing to catch up: every run whose records main lacks closed out, so this run's close-out commits them"].join("\n"));
|
|
417
|
+
}
|
|
418
|
+
const state = { branch: null, pr: null, pin: null, rebase: null };
|
|
419
|
+
const result = commitAndPr({ cwd, stem: "chore/run-records-", title: "Run records: phase 0 catch-up", tsvs: [], rebase: false, state, save: () => {} });
|
|
420
|
+
if (result.status === "ok") return ok([...gathered, result.output].join("\n"));
|
|
421
|
+
const head = git(["symbolic-ref", "-q", "HEAD"]);
|
|
422
|
+
if (head.status === 0 && head.stdout === "refs/heads/main") {
|
|
423
|
+
// How far the flow got before it failed, from what it recorded on the way.
|
|
424
|
+
const left = state.pin !== null
|
|
425
|
+
? `pushed ${state.branch} at ${state.pin}, but no PR is open for it`
|
|
426
|
+
: state.branch !== null ? `not pushed; whatever was committed stays on the local branch ${state.branch}` : "not committed";
|
|
427
|
+
return ok([...gathered, `${left}: ${result.output} — the close-out commits them`].join("\n"));
|
|
428
|
+
}
|
|
429
|
+
return failed([...gathered, result.output, "the checkout is not back on main — switch it to main before the run goes on"].join("\n"));
|
|
430
|
+
}
|
|
431
|
+
|
|
355
432
|
function reclaim({ cwd, scratch }) {
|
|
356
433
|
const live = node("reclaim-scratch.mjs", ["--root", scratch, "--after-rotate", "--apply"], { cwd });
|
|
357
434
|
// The sibling pass runs whatever the live sweep answered: a failure there is recorded beside it, never a reason to skip it.
|
|
@@ -549,7 +626,7 @@ function alarm({ fleetDir }) {
|
|
|
549
626
|
const STEPS = {
|
|
550
627
|
"alarm": alarm, "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "labels": labels,
|
|
551
628
|
"preflight": preflight, "ruleset": ruleset, "tier-roles": tierRoles, "metrics": metrics, "cockpit": cockpit, "rotate": rotate,
|
|
552
|
-
"reclaim": reclaim, "evict": evict, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
|
|
629
|
+
"catch-up": catchUp, "reclaim": reclaim, "evict": evict, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
|
|
553
630
|
};
|
|
554
631
|
|
|
555
632
|
const STEP_NAMES = Object.keys(STEPS);
|
|
@@ -705,7 +782,8 @@ function main() {
|
|
|
705
782
|
renameSync(receiptPath, held);
|
|
706
783
|
}
|
|
707
784
|
|
|
708
|
-
const
|
|
785
|
+
const pluginVersion = resumed && typeof previous.pluginVersion === "string" ? previous.pluginVersion : null;
|
|
786
|
+
const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, objective, pluginVersion, steps: {} };
|
|
709
787
|
for (const name of STEP_NAMES) {
|
|
710
788
|
// `alarm` checks the omp running this invocation, so its `ok` is never carried.
|
|
711
789
|
const was = resumed && name !== "alarm" ? previous.steps[name] : undefined;
|
|
@@ -34,7 +34,16 @@
|
|
|
34
34
|
// of them: a bot's token names no PR, and GitHub reads MERGED
|
|
35
35
|
// while the bot is still writing under pr<M>/merge-bot-<n>/. An
|
|
36
36
|
// OPEN PR's pr<M>/ is kept whole except its run-* roots, which
|
|
37
|
-
// follow the --pr rule below.
|
|
37
|
+
// follow the --pr rule below. A MERGED PR's entry that holds
|
|
38
|
+
// review evidence — a `<run>/review.json` under pr<M>/, or a
|
|
39
|
+
// Charges file naming its run — is also kept until origin/main
|
|
40
|
+
// holds every file of it where run-records.mjs's reviewTargets()
|
|
41
|
+
// puts it, under docs/metrics/reviews/<M>/: the Close-out PR
|
|
42
|
+
// carries it there. `git ls-tree origin/main` in the checkout the
|
|
43
|
+
// ledger sits in answers that, once per sweep; a lookup that fails,
|
|
44
|
+
// or evidence that cannot be read, keeps the entry with that
|
|
45
|
+
// reason. A CLOSED PR gets no Ruling, and its entries keep the
|
|
46
|
+
// rule above.
|
|
38
47
|
// impl-<N>/
|
|
39
48
|
// removed when issue #N is CLOSED, or OPEN with no live
|
|
40
49
|
// impl-<N>[-x] token, no claim worktree standing, and idle past
|
|
@@ -121,6 +130,7 @@ import { gitEnv } from "./git-env.mjs";
|
|
|
121
130
|
import { ghAliasedRead, how } from "./gh-aliased-read.mjs";
|
|
122
131
|
import { isCLI } from "./is-cli.mjs";
|
|
123
132
|
import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
|
|
133
|
+
import { REVIEWS_DIR, reviewTargets } from "./run-records.mjs";
|
|
124
134
|
|
|
125
135
|
const NAME = "reclaim-scratch";
|
|
126
136
|
const die = makeDie(NAME);
|
|
@@ -269,6 +279,16 @@ function worktreeListing(checkout) {
|
|
|
269
279
|
}
|
|
270
280
|
}
|
|
271
281
|
|
|
282
|
+
// The paths origin/main holds under REVIEWS_DIR, as `{paths}`, or `{unknown}`
|
|
283
|
+
// naming why the checkout could not say. A missing origin/main is an unknown.
|
|
284
|
+
function evidenceOnMain(checkout) {
|
|
285
|
+
const r = spawnSync("git", ["ls-tree", "-r", "-z", "--name-only", "--full-tree", "origin/main", "--", `${REVIEWS_DIR}/`], {
|
|
286
|
+
cwd: checkout, encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS, env: gitEnv(),
|
|
287
|
+
});
|
|
288
|
+
if (r.error || r.status !== 0) return { unknown: `git ls-tree origin/main -- ${REVIEWS_DIR}/ failed (${how(r)})` };
|
|
289
|
+
return { paths: new Set(r.stdout.split("\0").filter(Boolean)) };
|
|
290
|
+
}
|
|
291
|
+
|
|
272
292
|
// Whether a claim worktree stands for issue `n`: a listed worktree directly under
|
|
273
293
|
// `.worktrees/` whose directory name names `n` as a whole segment, and whose
|
|
274
294
|
// directory is still there. `{stands}` is true or false; `{unknown}`
|
|
@@ -329,7 +349,7 @@ function githubStates(numbers) {
|
|
|
329
349
|
}
|
|
330
350
|
|
|
331
351
|
// The root sweep's verdicts: `{remove: [{path, reason}], kept: [{path, reason}]}`.
|
|
332
|
-
function judgeRoot(root, names, live, now, listing) {
|
|
352
|
+
function judgeRoot(root, names, live, now, listing, checkout) {
|
|
333
353
|
const cutoff = now - RETENTION_MS;
|
|
334
354
|
const remove = [];
|
|
335
355
|
const kept = [];
|
|
@@ -342,6 +362,22 @@ function judgeRoot(root, names, live, now, listing) {
|
|
|
342
362
|
return r !== null && Number(r[1]) === n;
|
|
343
363
|
});
|
|
344
364
|
const implHolder = (n) => liveMembers.find((m) => m.family === "impl" && m.number === n)?.name;
|
|
365
|
+
// Why a MERGED PR's entry is kept for its review evidence, or null when it
|
|
366
|
+
// holds none origin/main lacks. origin/main is read once, on first need.
|
|
367
|
+
let onMain = null;
|
|
368
|
+
const evidenceHold = (path, name, n) => {
|
|
369
|
+
let found;
|
|
370
|
+
try {
|
|
371
|
+
found = reviewTargets(path, name);
|
|
372
|
+
} catch (e) {
|
|
373
|
+
return `PR #${n} is MERGED, and its review evidence cannot be read: ${e.code ?? e.message}`;
|
|
374
|
+
}
|
|
375
|
+
if (found.targets.length === 0) return null;
|
|
376
|
+
onMain ??= evidenceOnMain(checkout);
|
|
377
|
+
if (onMain.unknown !== undefined) return `PR #${n} is MERGED, but whether origin/main holds its review evidence cannot be told: ${onMain.unknown}`;
|
|
378
|
+
const missing = found.targets.filter((t) => !onMain.paths.has(t.to)).map((t) => t.to);
|
|
379
|
+
return missing.length === 0 ? null : `PR #${n} is MERGED, but origin/main does not hold its review evidence yet: ${missing.join(", ")}`;
|
|
380
|
+
};
|
|
345
381
|
|
|
346
382
|
const byAge = (path, name, young) => {
|
|
347
383
|
const holder = live.find((t) => name.includes(t));
|
|
@@ -437,7 +473,12 @@ function judgeRoot(root, names, live, now, listing) {
|
|
|
437
473
|
continue;
|
|
438
474
|
}
|
|
439
475
|
const holder = prHolder(n);
|
|
440
|
-
if (holder !== undefined)
|
|
476
|
+
if (holder !== undefined) {
|
|
477
|
+
kept.push({ path, reason: `PR #${n} is ${s.state}, but live ${holder} names it` });
|
|
478
|
+
continue;
|
|
479
|
+
}
|
|
480
|
+
const held = s.state === "MERGED" ? evidenceHold(path, name, n) : null;
|
|
481
|
+
if (held !== null) kept.push({ path, reason: held });
|
|
441
482
|
else remove.push({ path, reason: `PR #${n} is ${s.state}` });
|
|
442
483
|
continue;
|
|
443
484
|
}
|
|
@@ -600,7 +641,7 @@ function main() {
|
|
|
600
641
|
die(`could not list --root ${root}: ${e.message}`);
|
|
601
642
|
}
|
|
602
643
|
const listing = worktreeListing(found.checkout);
|
|
603
|
-
({ remove, kept } = judgeRoot(root, names, live, now, listing));
|
|
644
|
+
({ remove, kept } = judgeRoot(root, names, live, now, listing, found.checkout));
|
|
604
645
|
}
|
|
605
646
|
|
|
606
647
|
const removed = [];
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
// A run's records and each reviewed PR's review evidence, as files the
|
|
2
|
+
// Close-out PR commits under docs/metrics/ — the one place that names them.
|
|
3
|
+
//
|
|
4
|
+
// docs/metrics/runs/<stamp>/ledger.md, phase0.json, closeout.json,
|
|
5
|
+
// plugin-version
|
|
6
|
+
// docs/metrics/reviews/<pr>/<run>/review.json,
|
|
7
|
+
// dispositions-fix-pr-<pr>[-x].json
|
|
8
|
+
//
|
|
9
|
+
// `<stamp>` is the ledger archive's own (`ledger.<stamp>.md`, archiveStamp()
|
|
10
|
+
// in ledger-grammar.mjs), and the three files under it are the archives
|
|
11
|
+
// `ledger.mjs rotate` leaves beside the ledger: `ledger.<stamp>.md`,
|
|
12
|
+
// `phase0.<stamp>.json` and `closeout.<stamp>.json`. The phase-0 receipt is
|
|
13
|
+
// committed with its `recipe` step's output withheld: that output is the
|
|
14
|
+
// Recipe's command lines, and a command can carry an environment assignment,
|
|
15
|
+
// a secret among them. A phase-0 archive that cannot be read as JSON cannot be
|
|
16
|
+
// withheld from, so it is not committed. `plugin-version` is one line, the
|
|
17
|
+
// `pluginVersion` that run's phase-0 receipt recorded from the instruments
|
|
18
|
+
// pin; a receipt that records none gets no file. `<run>` is the review's run
|
|
19
|
+
// root (`run-` and eight characters), `<scratch>/pr<pr>/<run>/`, and a Charges
|
|
20
|
+
// file goes into the run its own `run` field names.
|
|
21
|
+
//
|
|
22
|
+
// isRunRecord() is the allowlist: the commit step stages only paths it
|
|
23
|
+
// accepts, as isPlainFile() files, finisher-scope.mjs classifies only those as
|
|
24
|
+
// data beside the metrics TSVs, and main-checkout.mjs leaves the plain files
|
|
25
|
+
// among them out of its snapshot as the run's own bookkeeping. A file of any
|
|
26
|
+
// other name under those directories — a recipe, a transcript, a brief — is
|
|
27
|
+
// never staged. reviewTargets() is the one mapping from a scratch entry to the
|
|
28
|
+
// paths its evidence is committed under: gather() copies along it, and
|
|
29
|
+
// reclaim-scratch.mjs keeps a merged PR's evidence until origin/main holds
|
|
30
|
+
// every one of them.
|
|
31
|
+
//
|
|
32
|
+
// Zero deps: node builtins and sibling scripts only.
|
|
33
|
+
|
|
34
|
+
import { chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
35
|
+
import { dirname, join } from "node:path";
|
|
36
|
+
|
|
37
|
+
export const RUNS_DIR = "docs/metrics/runs";
|
|
38
|
+
export const REVIEWS_DIR = "docs/metrics/reviews";
|
|
39
|
+
export const RECORD_DIRS = Object.freeze([RUNS_DIR, REVIEWS_DIR]);
|
|
40
|
+
export const PLUGIN_VERSION = "plugin-version";
|
|
41
|
+
|
|
42
|
+
const STAMP = "[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{6}Z";
|
|
43
|
+
const RUN_ROOT = /^run-[A-Za-z0-9]{8}$/;
|
|
44
|
+
const RUN_RECORD = new RegExp(`^${RUNS_DIR}/${STAMP}/(?:ledger\\.md|phase0\\.json|closeout\\.json|${PLUGIN_VERSION})$`);
|
|
45
|
+
const RUN_DIR = new RegExp(`^${RUNS_DIR}/(${STAMP})/`);
|
|
46
|
+
const REVIEW_RECORD = new RegExp(`^${REVIEWS_DIR}/([1-9][0-9]*)/run-[A-Za-z0-9]{8}/(?:review\\.json|dispositions-fix-pr-\\1(?:-[a-z])?\\.json)$`);
|
|
47
|
+
// The archives `ledger.mjs rotate` leaves beside the ledger, by stamp, and the
|
|
48
|
+
// name each takes under docs/metrics/runs/<stamp>/.
|
|
49
|
+
const ARCHIVE = new RegExp(`^(?:ledger\\.(${STAMP})\\.md|phase0\\.(${STAMP})\\.json|closeout\\.(${STAMP})\\.json)$`);
|
|
50
|
+
const PR_ENTRY = /^pr([1-9][0-9]*)$/;
|
|
51
|
+
const DISPOSITIONS_ENTRY = /^dispositions-fix-pr-([1-9][0-9]*)(?:-[a-z])?\.json$/;
|
|
52
|
+
|
|
53
|
+
/** Whether `path` (repository-relative, `/`-separated) is a run record or review evidence file the Close-out PR may commit. */
|
|
54
|
+
export const isRunRecord = (path) => RUN_RECORD.test(path) || REVIEW_RECORD.test(path);
|
|
55
|
+
|
|
56
|
+
// The lstat of `path` when it is a regular file — never a symlink's target —
|
|
57
|
+
// else null; an absent path is null, any other failure throws.
|
|
58
|
+
const fileStat = (path) => {
|
|
59
|
+
try {
|
|
60
|
+
const st = lstatSync(path);
|
|
61
|
+
return st.isFile() ? st : null;
|
|
62
|
+
} catch (e) {
|
|
63
|
+
if (e.code === "ENOENT") return null;
|
|
64
|
+
throw e;
|
|
65
|
+
}
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
const isFile = (path) => fileStat(path) !== null;
|
|
69
|
+
|
|
70
|
+
/** Whether `path` is a regular file with no executable bit: the only kind of run record a commit carries. */
|
|
71
|
+
export const isPlainFile = (path) => {
|
|
72
|
+
const st = fileStat(path);
|
|
73
|
+
return st !== null && (st.mode & 0o111) === 0;
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
/** What the committed phase-0 receipt holds in place of its `recipe` step's output. */
|
|
77
|
+
export const RECIPE_WITHHELD = "withheld: the Recipe's command lines can carry environment assignments";
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* The run records `fleetDir` holds: `{copies: [{from, to}], writes: [{to,
|
|
81
|
+
* text}], notes}`, `to` repository-relative. A phase-0 archive is written with
|
|
82
|
+
* its `recipe` step's output withheld, and one that cannot be read as JSON is
|
|
83
|
+
* left out, with a note. Throws when `fleetDir` cannot be listed or a phase-0
|
|
84
|
+
* archive cannot be read.
|
|
85
|
+
*/
|
|
86
|
+
export function runArchives(fleetDir) {
|
|
87
|
+
const copies = [];
|
|
88
|
+
const writes = [];
|
|
89
|
+
const notes = [];
|
|
90
|
+
for (const name of readdirSync(fleetDir).sort()) {
|
|
91
|
+
const m = ARCHIVE.exec(name);
|
|
92
|
+
if (m === null) continue;
|
|
93
|
+
const from = join(fleetDir, name);
|
|
94
|
+
if (!isFile(from)) continue;
|
|
95
|
+
const [stamp, file] = m[1] ? [m[1], "ledger.md"] : m[2] ? [m[2], "phase0.json"] : [m[3], "closeout.json"];
|
|
96
|
+
const dir = `${RUNS_DIR}/${stamp}`;
|
|
97
|
+
if (file !== "phase0.json") {
|
|
98
|
+
copies.push({ from, to: `${dir}/${file}` });
|
|
99
|
+
continue;
|
|
100
|
+
}
|
|
101
|
+
const text = readFileSync(from, "utf8");
|
|
102
|
+
let receipt;
|
|
103
|
+
try {
|
|
104
|
+
receipt = JSON.parse(text);
|
|
105
|
+
} catch {
|
|
106
|
+
// Not the parser's message: it can quote the receipt's own bytes.
|
|
107
|
+
notes.push(`${from} not committed: it is not JSON, so its recipe step cannot be withheld`);
|
|
108
|
+
continue;
|
|
109
|
+
}
|
|
110
|
+
const recipe = receipt?.steps?.recipe;
|
|
111
|
+
if (recipe !== null && typeof recipe === "object" && "output" in recipe) recipe.output = RECIPE_WITHHELD;
|
|
112
|
+
writes.push({ to: `${dir}/phase0.json`, text: `${JSON.stringify(receipt, null, 2)}\n` });
|
|
113
|
+
const version = receipt?.pluginVersion;
|
|
114
|
+
if (typeof version === "string" && /^[^\s]+$/.test(version)) writes.push({ to: `${dir}/${PLUGIN_VERSION}`, text: `${version}\n` });
|
|
115
|
+
}
|
|
116
|
+
return { copies, writes, notes };
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* The paths a scratch entry's review evidence is committed under, as
|
|
121
|
+
* `{targets: [{from, to}], notes}`. `pr<M>/` gives each `<run>/review.json`
|
|
122
|
+
* under it; `dispositions-fix-pr-<M>[-x].json` gives itself, in the run its
|
|
123
|
+
* `run` field names, or a note when it names none. Any other entry gives
|
|
124
|
+
* nothing. Throws when the entry cannot be read.
|
|
125
|
+
*/
|
|
126
|
+
export function reviewTargets(path, name) {
|
|
127
|
+
const pr = PR_ENTRY.exec(name);
|
|
128
|
+
if (pr !== null) {
|
|
129
|
+
let runs;
|
|
130
|
+
try {
|
|
131
|
+
runs = readdirSync(path, { withFileTypes: true });
|
|
132
|
+
} catch (e) {
|
|
133
|
+
if (e.code === "ENOTDIR") return { targets: [], notes: [] };
|
|
134
|
+
throw e;
|
|
135
|
+
}
|
|
136
|
+
const targets = runs
|
|
137
|
+
.filter((d) => d.isDirectory() && RUN_ROOT.test(d.name) && isFile(join(path, d.name, "review.json")))
|
|
138
|
+
.map((d) => ({ from: join(path, d.name, "review.json"), to: `${REVIEWS_DIR}/${pr[1]}/${d.name}/review.json` }))
|
|
139
|
+
.sort((a, b) => (a.to < b.to ? -1 : 1));
|
|
140
|
+
return { targets, notes: [] };
|
|
141
|
+
}
|
|
142
|
+
const d = DISPOSITIONS_ENTRY.exec(name);
|
|
143
|
+
if (d === null || !isFile(path)) return { targets: [], notes: [] };
|
|
144
|
+
let run;
|
|
145
|
+
try {
|
|
146
|
+
run = JSON.parse(readFileSync(path, "utf8")).run;
|
|
147
|
+
} catch (e) {
|
|
148
|
+
return { targets: [], notes: [`${path} names no review run: ${e.message}`] };
|
|
149
|
+
}
|
|
150
|
+
if (typeof run !== "string" || !RUN_ROOT.test(run)) return { targets: [], notes: [`${path} names no review run: run is ${JSON.stringify(run ?? null)}`] };
|
|
151
|
+
return { targets: [{ from: path, to: `${REVIEWS_DIR}/${d[1]}/${run}/${name}` }], notes: [] };
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Every review evidence file under `scratch`, as reviewTargets() maps it.
|
|
156
|
+
* An absent scratch root holds none; one that cannot be listed throws.
|
|
157
|
+
*/
|
|
158
|
+
export function reviewEvidence(scratch) {
|
|
159
|
+
let names;
|
|
160
|
+
try {
|
|
161
|
+
names = readdirSync(scratch).sort();
|
|
162
|
+
} catch (e) {
|
|
163
|
+
if (e.code === "ENOENT") return { copies: [], notes: [] };
|
|
164
|
+
throw e;
|
|
165
|
+
}
|
|
166
|
+
const copies = [];
|
|
167
|
+
const notes = [];
|
|
168
|
+
for (const name of names) {
|
|
169
|
+
const found = reviewTargets(join(scratch, name), name);
|
|
170
|
+
copies.push(...found.targets);
|
|
171
|
+
notes.push(...found.notes);
|
|
172
|
+
}
|
|
173
|
+
return { copies, notes };
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Copies every run archive in `fleetDir` and every review evidence file under
|
|
178
|
+
* `scratch` into the checkout at `cwd`, plain mode 0644, replacing what is
|
|
179
|
+
* there: a file already committed comes back byte for byte, so git sees only
|
|
180
|
+
* what is new. What stood at a destination is removed first, so a symlink
|
|
181
|
+
* there is replaced rather than written through. The lines it returns say
|
|
182
|
+
* what was gathered; it throws on a directory it cannot list or a file it
|
|
183
|
+
* cannot copy.
|
|
184
|
+
*/
|
|
185
|
+
export function gather({ cwd, fleetDir, scratch }) {
|
|
186
|
+
const runs = runArchives(fleetDir);
|
|
187
|
+
const reviews = reviewEvidence(scratch);
|
|
188
|
+
const place = (to) => {
|
|
189
|
+
const abs = join(cwd, to);
|
|
190
|
+
mkdirSync(dirname(abs), { recursive: true });
|
|
191
|
+
rmSync(abs, { force: true });
|
|
192
|
+
return abs;
|
|
193
|
+
};
|
|
194
|
+
for (const { from, to } of [...runs.copies, ...reviews.copies]) {
|
|
195
|
+
const abs = place(to);
|
|
196
|
+
copyFileSync(from, abs);
|
|
197
|
+
chmodSync(abs, 0o644);
|
|
198
|
+
}
|
|
199
|
+
for (const { to, text } of runs.writes) {
|
|
200
|
+
const abs = place(to);
|
|
201
|
+
writeFileSync(abs, text);
|
|
202
|
+
chmodSync(abs, 0o644);
|
|
203
|
+
}
|
|
204
|
+
return [
|
|
205
|
+
`${runs.copies.length + runs.writes.length} run record file(s) from ${fleetDir}`,
|
|
206
|
+
`${reviews.copies.length} review evidence file(s) from ${scratch}`,
|
|
207
|
+
...runs.notes,
|
|
208
|
+
...reviews.notes,
|
|
209
|
+
];
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* The run records among `paths` whose run left no close-out receipt
|
|
214
|
+
* (`closeout.<stamp>.json`) in `fleetDir`. A run that closed out leaves its
|
|
215
|
+
* records to the next run's close-out; phase 0's catch-up commits for the
|
|
216
|
+
* others.
|
|
217
|
+
*/
|
|
218
|
+
export function unclosedRecords(fleetDir, paths) {
|
|
219
|
+
return paths.filter((path) => {
|
|
220
|
+
const m = RUN_DIR.exec(path);
|
|
221
|
+
return m !== null && !isFile(join(fleetDir, `closeout.${m[1]}.json`));
|
|
222
|
+
});
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** The output line naming a path recordChanges() refused. */
|
|
226
|
+
export const refusedLine = (path) => `not staged, not a run record isRunRecord() allows: ${path}`;
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* What the commit may stage under RECORD_DIRS in the checkout at `cwd`, which
|
|
230
|
+
* `git` runs in: `{allowed, refused}`, each a list of repository-relative
|
|
231
|
+
* paths, or `{error}`. The candidates are what `git ls-files --others
|
|
232
|
+
* --modified --exclude-standard` lists there, and what the index already
|
|
233
|
+
* holds staged there, as a commit that failed after its `git add` leaves it.
|
|
234
|
+
* Only a regular file isRunRecord() accepts, with no executable bit, is
|
|
235
|
+
* allowed; anything else — another name, a symlink, an executable, a
|
|
236
|
+
* deletion — is refused, so a commit never carries it.
|
|
237
|
+
*/
|
|
238
|
+
export function recordChanges(git, cwd) {
|
|
239
|
+
const paths = [];
|
|
240
|
+
for (const args of [["ls-files", "-z", "--others", "--modified", "--exclude-standard"], ["diff", "--cached", "--name-only", "--no-renames", "-z"]]) {
|
|
241
|
+
const r = git([...args, "--", ...RECORD_DIRS]);
|
|
242
|
+
if (r.status !== 0) return { error: `git ${args[0]} -- ${RECORD_DIRS.join(" ")} failed: ${[r.stdout, r.stderr].filter(Boolean).join("\n") || r.how}` };
|
|
243
|
+
paths.push(...r.stdout.split("\0").filter(Boolean));
|
|
244
|
+
}
|
|
245
|
+
const allowed = [];
|
|
246
|
+
const refused = [];
|
|
247
|
+
for (const path of new Set(paths)) {
|
|
248
|
+
(isRunRecord(path) && isPlainFile(join(cwd, path)) ? allowed : refused).push(path);
|
|
249
|
+
}
|
|
250
|
+
return { allowed, refused };
|
|
251
|
+
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Close-out: what each metrics step does and why
|
|
2
2
|
|
|
3
|
-
`closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh, the commit of the metrics files, and the phase-0 receipt move, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses, and how `closeout.mjs reopen` undoes a drain. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
|
|
3
|
+
`closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh, the gather of the run records and the review evidence, the commit of the metrics and record files, and the phase-0 receipt move, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses, and how `closeout.mjs reopen` undoes a drain. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
|
|
4
4
|
|
|
5
5
|
- **The run ends, or the maintainer says drain** → `fleet-event.mjs drain --reason "<reason>"`
|
|
6
6
|
first (below). The marker is on disk, so the tick
|
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
once the run is draining with no open PR and no live implementer.
|
|
20
20
|
3. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
|
|
21
21
|
the run's member facts, checks the tier-outcomes rows, refreshes the
|
|
22
|
-
metrics,
|
|
22
|
+
metrics, gathers the earlier runs' records and the review evidence,
|
|
23
|
+
commits them with the three metrics files and opens their PR, sets the
|
|
23
24
|
phase-0 receipt aside as `.fleet/phase0.previous.json`, records
|
|
24
25
|
`fleet-heartbeat.mjs --stop`, because every reader takes a recorded stop
|
|
25
26
|
as the end of the run, and then merges the Close-out PR. On `NEED
|
|
@@ -124,6 +125,26 @@ the cause and run `finish` again — the pending file stays in `.fleet/` and the
|
|
|
124
125
|
next run's phase-0 pass drains it — and never commit the metrics files with a
|
|
125
126
|
drain that failed claiming the corpus is complete.
|
|
126
127
|
|
|
128
|
+
## Gather the run records and the review evidence
|
|
129
|
+
|
|
130
|
+
**Gather the run records and the review evidence after the metrics refresh,
|
|
131
|
+
before the commit.** The `gather` step of `closeout.mjs finish` copies, from
|
|
132
|
+
`.fleet/`, every run archive `ledger.mjs rotate` left there into
|
|
133
|
+
`docs/metrics/runs/<UTC stamp>/` — `ledger.md`, `phase0.json`, `closeout.json`,
|
|
134
|
+
and a `plugin-version` line from the version the phase-0 receipt recorded —
|
|
135
|
+
and, from the scratch root, every review's `review.json` into
|
|
136
|
+
`docs/metrics/reviews/<pr>/<run>/`, with each Charges file
|
|
137
|
+
(`dispositions-fix-pr-<pr>[-x].json`) beside the review run it answers. The
|
|
138
|
+
phase-0 receipt goes in with its `recipe` step's output withheld, because that
|
|
139
|
+
output is the Recipe's command lines and a command can carry an environment
|
|
140
|
+
assignment; a phase-0 archive that cannot be read as JSON is not gathered, and
|
|
141
|
+
the step's output names it. A run's own archives exist only once the next run
|
|
142
|
+
has rotated, so the records it carries are the earlier runs'; a file main
|
|
143
|
+
already holds comes back byte for byte and adds nothing. A Charges file that
|
|
144
|
+
names no review run is not gathered, and the step's output names it. A
|
|
145
|
+
directory it cannot list or a file it cannot copy fails the step, so
|
|
146
|
+
`commit-and-pr` stays pending: fix the cause and run `finish` again.
|
|
147
|
+
|
|
127
148
|
## Commit the metrics files and open a PR
|
|
128
149
|
|
|
129
150
|
The metrics files are the run's own artifacts and none commits itself. Carry
|
|
@@ -141,6 +162,14 @@ a data row loses it: `member-outcomes.tsv` is regenerated from harness
|
|
|
141
162
|
transcripts the fleet does not own, so re-running the scrape later is worth
|
|
142
163
|
only what the harness still holds.
|
|
143
164
|
|
|
165
|
+
The commit carries the run records and the review evidence beside the three
|
|
166
|
+
metrics files, because a review's evidence is deleted from scratch once its PR
|
|
167
|
+
has merged and main holds it, and a run's ledger and receipts otherwise stay on
|
|
168
|
+
one machine. Only the files `isRunRecord()` in `run-records.mjs` allows are
|
|
169
|
+
staged: the shapes above, regular files with no executable bit. Anything else
|
|
170
|
+
under `docs/metrics/runs/` or `docs/metrics/reviews/` — a recipe, a transcript,
|
|
171
|
+
a brief — is left out of the commit, and the step's output names it.
|
|
172
|
+
|
|
144
173
|
## Move the phase-0 receipt
|
|
145
174
|
|
|
146
175
|
**Set aside the phase-0 receipt after the commit — before the heartbeat.** The receipt `.fleet/phase0.json` records each phase-0 step's result and the In-flight bound the tick reads; `closeout.mjs finish` moves it to `.fleet/phase0.previous.json` so the next run can find it under the name `phase0.mjs` reserves for a previous run's receipt, and that run's rotation restores and archives it with the ledger. A missing `.fleet/phase0.json` counts as nothing to move and is `ok`.
|
|
@@ -222,7 +222,7 @@ not rely on that.
|
|
|
222
222
|
**The acceptance mutation runs unless `finisher-scope.mjs` says the diff is inert.**
|
|
223
223
|
A mutation that loosens a regex, deletes a guard or flips a reset has nothing to
|
|
224
224
|
kill in a diff made only of Markdown prose (`.md` or `.markdown` outside the
|
|
225
|
-
prompt surface) or only of the run-metrics files. The finisher does not decide
|
|
225
|
+
prompt surface) or only of the run-metrics files, run records and review evidence. The finisher does not decide
|
|
226
226
|
that by reading the diff: the script reads it, and only its exit 0 skips the
|
|
227
227
|
mutation. An exit 1 is not overridden, and an exit 2 is never read as a 0.
|
|
228
228
|
|
|
@@ -32,7 +32,7 @@ into one free implementer slot, the moment it frees (phase 1).
|
|
|
32
32
|
|
|
33
33
|
`phase0.mjs` runs the start sequence in
|
|
34
34
|
its fixed order — alarm, branch, fast-forward, pin, baseline, labels, preflight, ruleset,
|
|
35
|
-
tier-roles, metrics, cockpit, rotate, reclaim, evict, recipe, fold-in, stranded,
|
|
35
|
+
tier-roles, metrics, cockpit, rotate, catch-up, reclaim, evict, recipe, fold-in, stranded,
|
|
36
36
|
shortlist — prints one `phase0: <step>: <status>` line per step with the
|
|
37
37
|
`NEED` lines last, and records each step in `.fleet/phase0.json`, which the
|
|
38
38
|
tick reads: it prints `PHASE0-INCOMPLETE` and holds every dispatching row
|
|
@@ -79,6 +79,8 @@ yourself. The baseline records the root it
|
|
|
79
79
|
certified beside the digest, and every later check — yours, a finisher's, the
|
|
80
80
|
merge gate's own leg — compares it with the live root and refuses when they
|
|
81
81
|
differ. Never dispatch a member into a run whose phase-0 pin refused.
|
|
82
|
+
`phase0.mjs` records the version the pin wrote into the receipt as
|
|
83
|
+
`pluginVersion`, so the run's archived receipt says which plugin it ran.
|
|
82
84
|
|
|
83
85
|
## Record the main-checkout baseline
|
|
84
86
|
|
|
@@ -388,13 +390,39 @@ archives, hand-named ones included, are left alone.
|
|
|
388
390
|
Before the rotation, `phase0.mjs` puts the held-aside receipt (`phase0.previous.json`) back at `phase0.json`, which `ledger.mjs rotate` then files as `phase0.<UTC stamp>.json`.
|
|
389
391
|
`ledger.mjs rotate` archives the run's two receipts with the ledger, under the ledger archive's own stamp: `.fleet/phase0.<UTC stamp>.json` and `.fleet/closeout.<UTC stamp>.json` beside `.fleet/ledger.<UTC stamp>.md`.
|
|
390
392
|
|
|
393
|
+
## Catch up the run records
|
|
394
|
+
|
|
395
|
+
**Catch up the run records straight after the rotation, before the reclaim —
|
|
396
|
+
every run.** The `catch-up` step copies every run archive in `.fleet/` — the
|
|
397
|
+
previous run's, which the rotation has just filed, and any earlier one — into
|
|
398
|
+
`docs/metrics/runs/<UTC stamp>/`, and every review's evidence under the
|
|
399
|
+
scratch root into `docs/metrics/reviews/<pr>/<run>/`, the same gather the
|
|
400
|
+
close-out runs (references/close-out.md). When main lacks a record of a run
|
|
401
|
+
that never closed out — no `.fleet/closeout.<UTC stamp>.json` beside its
|
|
402
|
+
ledger archive — it commits every file main lacks alone on a branch of its own
|
|
403
|
+
in this checkout, pushes it, opens a PR and switches back to `main`; the
|
|
404
|
+
metrics files' changes stay in the work tree, out of that commit. The PR is an
|
|
405
|
+
Owned PR, so the fold-in below queues it. A run that closed out leaves its
|
|
406
|
+
records to this run's close-out, which gathers them again, so the step opens
|
|
407
|
+
no second PR carrying the same files and its output says so. A run whose
|
|
408
|
+
close-out never ran therefore loses nothing: its ledger, receipts and version
|
|
409
|
+
reach main here, and its review evidence is still in scratch when the reclaim
|
|
410
|
+
runs, which keeps a merged PR's evidence until main holds it. The step never
|
|
411
|
+
stops the run but for a checkout it could not switch back to `main`; a commit
|
|
412
|
+
it could not make is named in its output, with how far it got — a branch
|
|
413
|
+
pushed with no PR open for it is named so — and the close-out gathers those
|
|
414
|
+
files again.
|
|
415
|
+
|
|
391
416
|
## Reclaim scratch
|
|
392
417
|
|
|
393
|
-
**Reclaim scratch straight after the
|
|
418
|
+
**Reclaim scratch straight after the catch-up — every run.**
|
|
394
419
|
`~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run reclaim-scratch.mjs --root <scratch>
|
|
395
420
|
--after-rotate --apply`, `<scratch>` the path `scratch-root.mjs` prints,
|
|
396
421
|
so a run that merges nothing still reclaims the previous run's leftovers
|
|
397
422
|
(`reclaim-scratch.mjs`'s header says what it removes).
|
|
423
|
+
A merged PR's `pr<pr>/` and Charges files that hold review evidence stay
|
|
424
|
+
until `origin/main` holds that evidence under `docs/metrics/reviews/<pr>/`,
|
|
425
|
+
and a lookup that cannot answer keeps them.
|
|
398
426
|
`--after-rotate` goes on this call always and on no other: rotate leaves
|
|
399
427
|
no ledger behind when it carried nothing, and the flag reads that absence
|
|
400
428
|
as "no live token" — rotate's own verdict — where without it the script
|