@feigi/fleet-ctl 3.40.2 → 3.41.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/candidates.mjs +25 -6
- package/scripts/fleet-tick.mjs +39 -11
- package/scripts/main-checkout.mjs +42 -11
- package/scripts/shortlist.mjs +24 -16
- package/skills/run-team/SKILL.md +36 -12
package/package.json
CHANGED
package/scripts/candidates.mjs
CHANGED
|
@@ -14,8 +14,9 @@
|
|
|
14
14
|
// unattended fleet has no channel to one.
|
|
15
15
|
//
|
|
16
16
|
// Exit-code contract — the whole interface for a caller that reads no
|
|
17
|
-
// stderr: 0 = survivors, JSON array on stdout
|
|
18
|
-
//
|
|
17
|
+
// stderr: 0 = survivors, JSON array on stdout (under `--with-dropped`, the
|
|
18
|
+
// envelope described below). 1 = the query succeeded and returned no rows at
|
|
19
|
+
// all. 2 = the query broke (bad args, gh failure, a
|
|
19
20
|
// reduction that did not apply, a capped result). 3 = the query succeeded,
|
|
20
21
|
// returned at least one row, and every row was removed by the to-spec
|
|
21
22
|
// filter — distinct from 1 so a caller such as run-team's phase 0 can say
|
|
@@ -24,6 +25,14 @@
|
|
|
24
25
|
// `--allow-fallback`, a labeled all-specs pass that falls back to a
|
|
25
26
|
// genuinely empty unfiltered pass is exit 1, not 3; the drop count is never
|
|
26
27
|
// carried across the two attempts.
|
|
28
|
+
//
|
|
29
|
+
// `--with-dropped` changes stdout and nothing else: `{rows, dropped}`, where
|
|
30
|
+
// `rows` is the survivor array the flagless run prints and `dropped` names
|
|
31
|
+
// every row the to-spec filter removed as `{n, reason}`, oldest first. It
|
|
32
|
+
// describes the same final attempt `rows` and exit 3 do. The exit codes are
|
|
33
|
+
// the same with and without it. It exists for a caller that reads no stderr —
|
|
34
|
+
// shortlist.mjs — so an empty or short shortlist can still name what the
|
|
35
|
+
// filter took.
|
|
27
36
|
|
|
28
37
|
import { execFileSync } from "node:child_process";
|
|
29
38
|
import { parseArgs } from "node:util";
|
|
@@ -44,6 +53,7 @@ const has = makeHas(die);
|
|
|
44
53
|
|
|
45
54
|
const requireLabel = arg("require-label");
|
|
46
55
|
const allowFallback = has("allow-fallback");
|
|
56
|
+
const withDropped = has("with-dropped");
|
|
47
57
|
|
|
48
58
|
// Default well above the proving ground's real volume. Measured 2026-07-23:
|
|
49
59
|
// 106 issues survive the exclusions, so the previous hardcoded 100 dropped six
|
|
@@ -82,6 +92,7 @@ if (!Number.isInteger(limit) || limit < 1) die(`--limit must be a positive integ
|
|
|
82
92
|
const OPTIONS = {
|
|
83
93
|
"require-label": { type: "string" },
|
|
84
94
|
"allow-fallback": { type: "boolean" },
|
|
95
|
+
"with-dropped": { type: "boolean" },
|
|
85
96
|
"limit": { type: "string" },
|
|
86
97
|
};
|
|
87
98
|
// No `strict: true`: strict IS parseArgs' default, and stays the default when
|
|
@@ -501,6 +512,9 @@ function refuseIfCapped(rows, description) {
|
|
|
501
512
|
}
|
|
502
513
|
}
|
|
503
514
|
|
|
515
|
+
// The `reason` a `--with-dropped` caller receives for a to-spec drop.
|
|
516
|
+
const SPEC_REASON = "to-spec: User Stories heading";
|
|
517
|
+
|
|
504
518
|
// `## User Stories` is to-spec's signature — mandatory in its template, absent
|
|
505
519
|
// from every ticket template. to-spec stamps a whole spec `ready-for-agent`
|
|
506
520
|
// with "no need for additional triage", so it arrives looking admissible; it is
|
|
@@ -564,16 +578,18 @@ function refuseIfCapped(rows, description) {
|
|
|
564
578
|
// from "2 drops, 2 specs" at a glance. Deliberately not deduplicated.
|
|
565
579
|
function dropSpecs(rows, pass) {
|
|
566
580
|
const kept = [];
|
|
581
|
+
const dropped = [];
|
|
567
582
|
for (const { spec, ...rest } of rows) {
|
|
568
583
|
if (spec) {
|
|
569
584
|
// "no silent caps" covers drops too — a filtered list that does not say
|
|
570
585
|
// what it filtered is indistinguishable from a complete one.
|
|
571
586
|
console.error(` dropped #${rest.n} — to-spec spec, not a ticket (User Stories heading) [${pass}]`);
|
|
587
|
+
dropped.push({ n: rest.n, reason: SPEC_REASON });
|
|
572
588
|
} else {
|
|
573
589
|
kept.push(rest);
|
|
574
590
|
}
|
|
575
591
|
}
|
|
576
|
-
return kept;
|
|
592
|
+
return { kept, dropped };
|
|
577
593
|
}
|
|
578
594
|
|
|
579
595
|
let rows = query(requireLabel);
|
|
@@ -592,7 +608,8 @@ refuseIfCapped(rows, requireLabel ? ` with label:${requireLabel}` : "");
|
|
|
592
608
|
// all-filtered (raw>0) whose fallback pass is genuinely empty (raw=0), which
|
|
593
609
|
// must read as the fallback's own facts (exit 1), not a merge of the two.
|
|
594
610
|
const rawCount1 = rows.length;
|
|
595
|
-
|
|
611
|
+
let dropped;
|
|
612
|
+
({ kept: rows, dropped } = dropSpecs(rows, requireLabel ? `label:${requireLabel}` : "unfiltered"));
|
|
596
613
|
let allFilteredOut = rawCount1 > 0 && rows.length === 0;
|
|
597
614
|
|
|
598
615
|
if (rows.length === 0 && allowFallback && requireLabel) {
|
|
@@ -604,7 +621,7 @@ if (rows.length === 0 && allowFallback && requireLabel) {
|
|
|
604
621
|
// not transfer, as no gate follows this one. The call must exist because the
|
|
605
622
|
// fallback's rows arrive raw and nothing downstream drops a spec.
|
|
606
623
|
const rawCount2 = rows.length;
|
|
607
|
-
rows = dropSpecs(rows, "unfiltered (fallback)");
|
|
624
|
+
({ kept: rows, dropped } = dropSpecs(rows, "unfiltered (fallback)"));
|
|
608
625
|
allFilteredOut = rawCount2 > 0 && rows.length === 0;
|
|
609
626
|
}
|
|
610
627
|
|
|
@@ -619,6 +636,7 @@ if (rows.length === 0 && allowFallback && requireLabel) {
|
|
|
619
636
|
// Native sub-issue links are still not read: parent/child is hierarchy, not
|
|
620
637
|
// blocking, so a blocker recorded only as one reaches it with none.
|
|
621
638
|
rows.sort((a, b) => a.n - b.n);
|
|
639
|
+
dropped.sort((a, b) => a.n - b.n);
|
|
622
640
|
|
|
623
641
|
for (const r of rows) {
|
|
624
642
|
console.error(` #${r.n} [${r.l.join(",")}] ${r.t}${r.d.length ? ` deps:${r.d.join(";")}` : ""}`);
|
|
@@ -658,7 +676,8 @@ for (const r of rows) {
|
|
|
658
676
|
// without copying up to `--limit` rows to do it. Add a field to the
|
|
659
677
|
// reduction that stdout SHOULD carry and it needs naming here, or it
|
|
660
678
|
// silently never ships.
|
|
661
|
-
|
|
679
|
+
const replacer = (k, v) => (k === "dh" ? undefined : v);
|
|
680
|
+
console.log(withDropped ? JSON.stringify({ rows, dropped }, replacer) : JSON.stringify(rows, replacer));
|
|
662
681
|
|
|
663
682
|
// Exit 1 for a successful query with no survivors, exit 3 when those zero
|
|
664
683
|
// survivors are the filter's doing rather than the query's — see the
|
package/scripts/fleet-tick.mjs
CHANGED
|
@@ -35,9 +35,12 @@
|
|
|
35
35
|
// the git common dir as ledger.mjs resolves the ledger. Its
|
|
36
36
|
// entries minus every ticket with an `impl-` row, or an `excluded`
|
|
37
37
|
// row whose premise still holds, are the heads a PULL names; its
|
|
38
|
-
// `scanned` is the supply.
|
|
38
|
+
// `scanned` is the supply. Its `dropped`, the rows candidates.mjs's
|
|
39
|
+
// to-spec filter removed before `scanned` was counted, is named on
|
|
40
|
+
// the implementer row as `specs-dropped=` and counts toward
|
|
41
|
+
// nothing. Missing or unparsable is depth 0 and a
|
|
39
42
|
// refresh, never a refusal: the depth only ever bounds PULLs
|
|
40
|
-
// downward.
|
|
43
|
+
// downward. A file with no `dropped` names no drops.
|
|
41
44
|
// gh The open PRs, by label, by whether they close an issue and by
|
|
42
45
|
// GitHub's `mergeable` — the merge queue, which PRs are owed a
|
|
43
46
|
// review, and which conflict. Also, for each ticket
|
|
@@ -153,10 +156,22 @@ function replaceStep(held, implNames) {
|
|
|
153
156
|
].filter(Boolean).join("; ");
|
|
154
157
|
}
|
|
155
158
|
|
|
159
|
+
// `specs-dropped=#<n> #<n> (to-spec: User Stories heading)`, one clause per
|
|
160
|
+
// reason, or "" when nothing was dropped. A dropped ticket never reaches
|
|
161
|
+
// `supply`, so without this an all-specs queue reads as no work at all.
|
|
162
|
+
function specsDropped(dropped) {
|
|
163
|
+
if (!dropped.length) return "";
|
|
164
|
+
const by = new Map();
|
|
165
|
+
for (const { n, reason } of dropped) by.set(reason, [...(by.get(reason) ?? []), `#${n}`]);
|
|
166
|
+
return `specs-dropped=${[...by].map(([reason, ns]) => `${ns.join(" ")} (${reason})`).join(", ")}`;
|
|
167
|
+
}
|
|
168
|
+
|
|
156
169
|
function implementers(s, left) {
|
|
170
|
+
const dropped = specsDropped(s.dropped);
|
|
157
171
|
const row = mkRow("implementers", s.implLive, s.implCap,
|
|
158
172
|
`unclaimed=${s.heads.length} supply=${s.supply ?? "?"} unreviewed=${left.unreviewed}`
|
|
159
|
-
+ (s.shortlistStatus === "ok" ? "" : ` shortlist=${s.shortlistStatus}`)
|
|
173
|
+
+ (s.shortlistStatus === "ok" ? "" : ` shortlist=${s.shortlistStatus}`)
|
|
174
|
+
+ (dropped ? ` ${dropped}` : ""));
|
|
160
175
|
|
|
161
176
|
// Drain stops supply and nothing else. Read from the file, so
|
|
162
177
|
// a replacement controller that never saw the drain is held by it too.
|
|
@@ -898,9 +913,11 @@ export function unclaimed(entries, run) {
|
|
|
898
913
|
return entries.map((e) => e.n).filter((n) => !run.claimed.has(n) || unverifiable.has(n));
|
|
899
914
|
}
|
|
900
915
|
|
|
901
|
-
// shortlist.mjs's payload, `{scanned, shortlist: [{n, t}]
|
|
916
|
+
// shortlist.mjs's payload, `{scanned, shortlist: [{n, t}], dropped: [{n,
|
|
917
|
+
// reason}]}`, or unparsable. A payload with no `dropped` predates the field
|
|
918
|
+
// and reads as no drops.
|
|
902
919
|
export function parseShortlist(text) {
|
|
903
|
-
const none = { status: "unparsable", scanned: null, entries: [] };
|
|
920
|
+
const none = { status: "unparsable", scanned: null, entries: [], dropped: [] };
|
|
904
921
|
let d;
|
|
905
922
|
try {
|
|
906
923
|
d = JSON.parse(text);
|
|
@@ -909,7 +926,12 @@ export function parseShortlist(text) {
|
|
|
909
926
|
}
|
|
910
927
|
if (!d || typeof d !== "object" || !Number.isInteger(d.scanned) || d.scanned < 0 || !Array.isArray(d.shortlist)
|
|
911
928
|
|| !d.shortlist.every((e) => e && Number.isInteger(e.n) && e.n > 0 && typeof e.t === "string")) return none;
|
|
912
|
-
|
|
929
|
+
const dropped = d.dropped === undefined ? [] : d.dropped;
|
|
930
|
+
if (!Array.isArray(dropped) || !dropped.every((e) => e && Number.isInteger(e.n) && e.n > 0 && typeof e.reason === "string")) return none;
|
|
931
|
+
return {
|
|
932
|
+
status: "ok", scanned: d.scanned, entries: d.shortlist.map(({ n, t }) => ({ n, t })),
|
|
933
|
+
dropped: dropped.map(({ n, reason }) => ({ n, reason })),
|
|
934
|
+
};
|
|
913
935
|
}
|
|
914
936
|
|
|
915
937
|
// Why this tick refreshes the shortlist, or null. The premise-lifted
|
|
@@ -1178,16 +1200,16 @@ function shortlistPath() {
|
|
|
1178
1200
|
}
|
|
1179
1201
|
|
|
1180
1202
|
function readShortlist(path) {
|
|
1181
|
-
if (path === null) return { status: "missing", scanned: null, entries: [] };
|
|
1203
|
+
if (path === null) return { status: "missing", scanned: null, entries: [], dropped: [] };
|
|
1182
1204
|
let text;
|
|
1183
1205
|
try {
|
|
1184
1206
|
text = readFileSync(path, "utf8");
|
|
1185
1207
|
} catch (e) {
|
|
1186
|
-
if (e.code === "ENOENT") return { status: "missing", scanned: null, entries: [] };
|
|
1208
|
+
if (e.code === "ENOENT") return { status: "missing", scanned: null, entries: [], dropped: [] };
|
|
1187
1209
|
// Distinct from `unparsable`: that label's only other producer is
|
|
1188
1210
|
// genuinely malformed JSON, and a permissions/filesystem fault reported
|
|
1189
1211
|
// as a JSON-content fault sends the operator chasing the wrong repair.
|
|
1190
|
-
return { status: "unreadable", scanned: null, entries: [], code: e.code ?? null, message: e.message };
|
|
1212
|
+
return { status: "unreadable", scanned: null, entries: [], dropped: [], code: e.code ?? null, message: e.message };
|
|
1191
1213
|
}
|
|
1192
1214
|
return parseShortlist(text);
|
|
1193
1215
|
}
|
|
@@ -1369,6 +1391,7 @@ function main() {
|
|
|
1369
1391
|
// so a slot the current file could not fill does not wait a tick for it.
|
|
1370
1392
|
let heads = unclaimed(current.entries, run);
|
|
1371
1393
|
let supply = current.scanned;
|
|
1394
|
+
let dropped = current.dropped;
|
|
1372
1395
|
let fresh = null;
|
|
1373
1396
|
const trigger = refreshWhy({ draining: run.draining, status: current.status, entries: current.entries.length,
|
|
1374
1397
|
unclaimed: heads.length, implCap: caps.implCap })
|
|
@@ -1379,6 +1402,7 @@ function main() {
|
|
|
1379
1402
|
const excludedSet = new Set(run.excluded.map((x) => x.n));
|
|
1380
1403
|
heads = [...new Set([...heads, ...unclaimed(r.entries, run)])];
|
|
1381
1404
|
supply = r.scanned;
|
|
1405
|
+
dropped = r.dropped;
|
|
1382
1406
|
fresh = {
|
|
1383
1407
|
ok: true, trigger, entries: r.entries.length,
|
|
1384
1408
|
lifted: r.entries.filter((e) => excludedSet.has(e.n)).length,
|
|
@@ -1396,7 +1420,7 @@ function main() {
|
|
|
1396
1420
|
const mainCheckout = checkMainCheckout();
|
|
1397
1421
|
|
|
1398
1422
|
const rows = reconcile({
|
|
1399
|
-
...caps, ...run, heads, supply, shortlistStatus: current.status, refresh: fresh, mainCheckout, router,
|
|
1423
|
+
...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, router,
|
|
1400
1424
|
});
|
|
1401
1425
|
const said = describe(mainCheckout, run.live);
|
|
1402
1426
|
// Re-read rather than reusing priorState: this must be the freshest
|
|
@@ -1446,7 +1470,11 @@ function main() {
|
|
|
1446
1470
|
// `quiet`, and named on the folded line for as long as it stays live
|
|
1447
1471
|
// past its threshold. The digest already moves when its bucket does.
|
|
1448
1472
|
const aged = stale.map((s) => `; CHECK-LIVENESS ${s.member} persists`).join("");
|
|
1449
|
-
|
|
1473
|
+
// The to-spec drops the same way: advice, and the one reason an empty
|
|
1474
|
+
// shortlist is not "no work".
|
|
1475
|
+
const specs = specsDropped(dropped);
|
|
1476
|
+
const drops = specs ? `; ${specs} persists` : "";
|
|
1477
|
+
console.log(`fleet-tick: unchanged, nothing to act on (quiet=${prev.quiet + 1})${held}${aged}${drops} — full rows on the next change`);
|
|
1450
1478
|
return;
|
|
1451
1479
|
}
|
|
1452
1480
|
for (const line of lines) console.log(line);
|
|
@@ -66,8 +66,10 @@
|
|
|
66
66
|
// unknown — some read failed: git, a hash, HEAD, `origin/main`, or a baseline
|
|
67
67
|
// that EXISTS but cannot be read (unreadable file, unsearchable
|
|
68
68
|
// `.fleet/`, dangling symlink, not written by --record) — or is a
|
|
69
|
-
// v1 baseline, which says nothing of HEAD: re-record it
|
|
70
|
-
//
|
|
69
|
+
// v1 baseline, which says nothing of HEAD: re-record it — or names
|
|
70
|
+
// a commit absent from the repository: examine HEAD, then
|
|
71
|
+
// re-record it. "A failure is an unknown answer, never a 'no'" —
|
|
72
|
+
// never `clean`.
|
|
71
73
|
// absent — no baseline at all: the run never recorded one. A refusal
|
|
72
74
|
// ("record at run start"), never `clean`.
|
|
73
75
|
//
|
|
@@ -78,7 +80,20 @@
|
|
|
78
80
|
// so it refuses on every unknown cause it can see: a baseline that exists but
|
|
79
81
|
// cannot be read, and any failed git or hash read (no snapshot, nothing to
|
|
80
82
|
// write). A detached HEAD has no symbolic ref to record, so it refuses that
|
|
81
|
-
// too. A v1 baseline
|
|
83
|
+
// too. A v1 baseline, and one whose commit is gone (it never reads the
|
|
84
|
+
// recorded commit), it overwrites without a word.
|
|
85
|
+
//
|
|
86
|
+
// A BASELINE COMMIT GONE FROM THE REPOSITORY is its own unknown. An amend or
|
|
87
|
+
// reset leaves the baseline's commit unreachable, and once reflog expiry and
|
|
88
|
+
// gc prune it the ancestry read fails where it would have answered `dirty`.
|
|
89
|
+
// What failed is the baseline, not the environment, so "fix the failure and
|
|
90
|
+
// never re-baseline" would forbid the one remedy: the advice is to examine
|
|
91
|
+
// HEAD against `origin/main` FIRST — the move off that commit is unexamined —
|
|
92
|
+
// and only then re-record. The check returns before it compares paths, so the
|
|
93
|
+
// advice also says to resolve any stray paths. On the baseline's own branch it
|
|
94
|
+
// is still `unknown`, never `dirty` or `clean`: the read that would have
|
|
95
|
+
// judged the move could not be made. A different branch reads `dirty` before
|
|
96
|
+
// any ancestry read.
|
|
82
97
|
//
|
|
83
98
|
// ROOT. The main checkout is the parent of `git rev-parse --git-common-dir`
|
|
84
99
|
// (git-env.mjs's `workspaceDirFromGitCommonDir`, as fleet-tick.mjs resolves
|
|
@@ -272,13 +287,18 @@ function originMain(root, env) {
|
|
|
272
287
|
|
|
273
288
|
/**
|
|
274
289
|
* Did HEAD move off the baseline's? `{ok, change}`: `change` is null, or the
|
|
275
|
-
* `HEAD <was> → <now>` entry; `{ok: false, why}` when a read failed
|
|
290
|
+
* `HEAD <was> → <now>` entry; `{ok: false, why}` when a read failed, with
|
|
291
|
+
* `missing: true` when the failure is the baseline's commit being absent.
|
|
276
292
|
* Clean is all of: the same symbolic ref; the baseline's commit an ancestor of
|
|
277
293
|
* HEAD or equal to it; no commit in `B..HEAD` that `origin/main` lacks. So a
|
|
278
294
|
* fast-forward to `origin/main` and a commit already unpushed at the baseline
|
|
279
295
|
* read clean, while a stray commit, a reset or an amend do not. `origin/main`
|
|
280
296
|
* is read even when HEAD equals the baseline: a checkout that cannot name it
|
|
281
297
|
* is one this cannot vouch for.
|
|
298
|
+
* A failed ancestry read is followed by `git cat-file -e B`, which exits 1
|
|
299
|
+
* for an absent object and 0 for a present one, even a corrupt one;
|
|
300
|
+
* `-e B^{commit}` exits 128 for both, so it cannot tell them apart. Only
|
|
301
|
+
* exit 1 is the missing answer; anything else keeps the ancestry failure.
|
|
282
302
|
*/
|
|
283
303
|
function headMove(root, env, was, now) {
|
|
284
304
|
const origin = originMain(root, env);
|
|
@@ -287,7 +307,12 @@ function headMove(root, env, was, now) {
|
|
|
287
307
|
if (now.ref !== was.ref) return moved;
|
|
288
308
|
if (now.oid === was.oid) return { ok: true, change: null };
|
|
289
309
|
const ancestor = git("git merge-base --is-ancestor", ["merge-base", "--is-ancestor", was.oid, now.oid], root, env);
|
|
290
|
-
if (!ancestor.ok)
|
|
310
|
+
if (!ancestor.ok) {
|
|
311
|
+
if (ancestor.status === 1) return moved;
|
|
312
|
+
const present = git("git cat-file -e", ["cat-file", "-e", was.oid], root, env);
|
|
313
|
+
if (present.ok || present.status !== 1) return ancestor;
|
|
314
|
+
return { ok: false, missing: true, why: `baseline commit ${was.oid.slice(0, 7)} is missing from this repository; HEAD is ${headLabel(now)}` };
|
|
315
|
+
}
|
|
291
316
|
const stray = git("git rev-list", ["rev-list", "--max-count=1", `${was.oid}..${now.oid}`, "^refs/remotes/origin/main"], root, env);
|
|
292
317
|
if (!stray.ok) return stray;
|
|
293
318
|
return stray.stdout.trim() === "" ? { ok: true, change: null } : moved;
|
|
@@ -345,9 +370,10 @@ export function changedPaths(baseline, current) {
|
|
|
345
370
|
|
|
346
371
|
/**
|
|
347
372
|
* The tick's question: `{state, root?, baseline?, changed?, headMove?, why?, cause?}`.
|
|
348
|
-
* `cause` tells the
|
|
373
|
+
* `cause` tells the four unknowns apart — `"baseline"` (it exists but cannot
|
|
349
374
|
* be read), `"outdated"` (a v1 baseline: it says nothing of HEAD, so it can
|
|
350
|
-
* answer nothing)
|
|
375
|
+
* answer nothing), `"missing"` (the baseline's commit is absent from the
|
|
376
|
+
* repository) and `"read"` (git or a hash failed) — since each has its own
|
|
351
377
|
* message. The baseline is read before the tree, because without one there
|
|
352
378
|
* is nothing to compare against and no reason to look.
|
|
353
379
|
* A HEAD move is the first entry of `changed`, also named in `headMove`.
|
|
@@ -359,13 +385,13 @@ export function checkMainCheckout({ cwd = process.cwd(), env = process.env } = {
|
|
|
359
385
|
const path = baselinePath(root);
|
|
360
386
|
const base = readBaseline(path);
|
|
361
387
|
if (base.status === "absent") return { state: "absent", root, baseline: path };
|
|
362
|
-
|
|
363
|
-
if (base.status === "
|
|
364
|
-
|
|
388
|
+
const unknown = (why, cause = "read") => ({ state: "unknown", cause, root, baseline: path, why });
|
|
389
|
+
if (base.status === "unreadable") return unknown(base.why, "baseline");
|
|
390
|
+
if (base.status === "outdated") return unknown(base.why, "outdated");
|
|
365
391
|
const now = readState(root, env);
|
|
366
392
|
if (!now.ok) return unknown(now.why);
|
|
367
393
|
const move = headMove(root, env, base.head, now.head);
|
|
368
|
-
if (!move.ok) return unknown(move.why);
|
|
394
|
+
if (!move.ok) return unknown(move.why, move.missing ? "missing" : "read");
|
|
369
395
|
const changed = changedPaths(base.entries, now.entries);
|
|
370
396
|
if (move.change !== null) changed.unshift(move.change);
|
|
371
397
|
if (!changed.length) return { state: "clean", root, baseline: path };
|
|
@@ -400,6 +426,11 @@ export function describe(check, live = null) {
|
|
|
400
426
|
return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members}`
|
|
401
427
|
+ ` — dispatch held: resolve any stray paths FIRST, then re-record with ${RECORD_COMMAND} (it overwrites, it does not compare)`;
|
|
402
428
|
}
|
|
429
|
+
if (check.cause === "missing") {
|
|
430
|
+
return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members}`
|
|
431
|
+
+ " — dispatch held: examine HEAD against origin/main FIRST, since a missing baseline commit means HEAD moved off it by an amend or reset nobody has looked at, and resolve any stray paths;"
|
|
432
|
+
+ ` then re-record with ${RECORD_COMMAND} (it overwrites, it does not compare)`;
|
|
433
|
+
}
|
|
403
434
|
return check.cause === "baseline"
|
|
404
435
|
? `MAIN-CHECKOUT-UNKNOWN baseline unreadable: ${check.why}${members}`
|
|
405
436
|
+ " — dispatch held: fix the baseline so it can be read; NEVER re-baseline over it, --record overwrites rather than compares"
|
package/scripts/shortlist.mjs
CHANGED
|
@@ -6,8 +6,11 @@
|
|
|
6
6
|
//
|
|
7
7
|
// The filters, in the order they run:
|
|
8
8
|
//
|
|
9
|
-
// 1. `candidates.mjs --require-label ready-for-agent
|
|
10
|
-
// re-ranked. Its row count is `scanned`, the
|
|
9
|
+
// 1. `candidates.mjs --require-label ready-for-agent --with-dropped`,
|
|
10
|
+
// oldest-first and never re-ranked. Its row count is `scanned`, the
|
|
11
|
+
// supply the tick reports; the rows its to-spec filter removed are
|
|
12
|
+
// `dropped`, which counts toward nothing and is carried so an empty or
|
|
13
|
+
// short shortlist still names them.
|
|
11
14
|
// 2. The dependency scan on each row's `d`: an open blocker drops the ticket
|
|
12
15
|
// (next-ticket step 2). A blocker that is itself a candidate is open by
|
|
13
16
|
// construction — candidates.mjs queries `--state open` — so only the rest
|
|
@@ -50,9 +53,9 @@
|
|
|
50
53
|
// Unlike the ledger there
|
|
51
54
|
// is no cwd-relative degrade: outside a repository inflight.sh cannot answer
|
|
52
55
|
// for a single ticket either, so there is nothing honest to write. The payload
|
|
53
|
-
// is `{scanned, shortlist: [{n, t}]}`, written to a
|
|
54
|
-
// renamed over the target so a reader never sees half
|
|
55
|
-
// the same object plus `file`.
|
|
56
|
+
// is `{scanned, shortlist: [{n, t}], dropped: [{n, reason}]}`, written to a
|
|
57
|
+
// sibling temp file and renamed over the target so a reader never sees half
|
|
58
|
+
// of it; stdout carries the same object plus `file`.
|
|
56
59
|
//
|
|
57
60
|
// The ledger is read through `ledger.mjs read`, never parsed here, so the
|
|
58
61
|
// ledger keeps one parser. candidates.mjs's stderr passes straight through —
|
|
@@ -150,31 +153,36 @@ function shortlistPath() {
|
|
|
150
153
|
}
|
|
151
154
|
|
|
152
155
|
function scan() {
|
|
153
|
-
const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "candidates.mjs"), "--require-label", LABEL], {
|
|
156
|
+
const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "candidates.mjs"), "--require-label", LABEL, "--with-dropped"], {
|
|
154
157
|
encoding: "utf8", maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "inherit"],
|
|
155
158
|
});
|
|
156
159
|
if (r.error) die(`candidates.mjs did not run: ${how(r)}`);
|
|
157
|
-
const out = (r.stdout ?? "").trim();
|
|
158
160
|
// Exit 1 (an empty queue) and exit 3 (every row a to-spec spec) are both the
|
|
159
161
|
// empty answer. Exit 1 is also Node's own code for a crash, so the payload
|
|
160
|
-
// decides.
|
|
161
|
-
if (
|
|
162
|
-
if (r.status !== 0) {
|
|
162
|
+
// decides: it must parse, with no rows.
|
|
163
|
+
if (r.status !== 0 && r.status !== 1 && r.status !== 3) {
|
|
163
164
|
die(`candidates.mjs ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`} — the scan did not answer, so there is no shortlist to write`);
|
|
164
165
|
}
|
|
165
|
-
let
|
|
166
|
+
let out;
|
|
166
167
|
try {
|
|
167
|
-
|
|
168
|
+
out = JSON.parse(r.stdout ?? "");
|
|
168
169
|
} catch (e) {
|
|
170
|
+
if (r.status !== 0) die(`candidates.mjs exited ${r.status} — the scan did not answer, so there is no shortlist to write`);
|
|
169
171
|
die(`could not parse candidates.mjs output: ${e.message}`);
|
|
170
172
|
}
|
|
171
|
-
if (!Array.isArray(rows)
|
|
173
|
+
if (!out || typeof out !== "object" || !Array.isArray(out.rows) || !Array.isArray(out.dropped)) {
|
|
174
|
+
die("candidates.mjs did not return {rows, dropped}");
|
|
175
|
+
}
|
|
176
|
+
const { rows, dropped } = out;
|
|
177
|
+
if (r.status !== 0 && rows.length) die(`candidates.mjs exited ${r.status} with rows — the scan did not answer, so there is no shortlist to write`);
|
|
172
178
|
const bad = rows.findIndex(
|
|
173
179
|
(row) => !row || !Number.isInteger(row.n) || typeof row.t !== "string" ||
|
|
174
180
|
!Array.isArray(row.d) || !row.d.every(Number.isInteger),
|
|
175
181
|
);
|
|
176
182
|
if (bad !== -1) die(`candidates.mjs row ${bad} is not {n, t, d} with integer refs`);
|
|
177
|
-
|
|
183
|
+
const badDrop = dropped.findIndex((e) => !e || !Number.isInteger(e.n) || typeof e.reason !== "string");
|
|
184
|
+
if (badDrop !== -1) die(`candidates.mjs dropped entry ${badDrop} is not {n, reason}`);
|
|
185
|
+
return { rows, dropped: dropped.map(({ n, reason }) => ({ n, reason })) };
|
|
178
186
|
}
|
|
179
187
|
|
|
180
188
|
function ledgerRows() {
|
|
@@ -236,7 +244,7 @@ async function main() {
|
|
|
236
244
|
const extra = process.argv.slice(2);
|
|
237
245
|
if (extra.length) die(`takes no arguments, got ${extra.join(" ")}`);
|
|
238
246
|
const file = shortlistPath();
|
|
239
|
-
const rows = scan();
|
|
247
|
+
const { rows, dropped } = scan();
|
|
240
248
|
const ledger = ledgerRows();
|
|
241
249
|
|
|
242
250
|
// Dependency scan.
|
|
@@ -316,7 +324,7 @@ async function main() {
|
|
|
316
324
|
return false;
|
|
317
325
|
});
|
|
318
326
|
|
|
319
|
-
const payload = { scanned: rows.length, shortlist: survivors.map(({ n, t }) => ({ n, t })) };
|
|
327
|
+
const payload = { scanned: rows.length, shortlist: survivors.map(({ n, t }) => ({ n, t })), dropped };
|
|
320
328
|
const tmp = `${file}.${process.pid}.tmp`;
|
|
321
329
|
try {
|
|
322
330
|
mkdirSync(dirname(file), { recursive: true });
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -309,7 +309,9 @@ phase, or in any later one, asks the maintainer which tickets to take.
|
|
|
309
309
|
certifies them. **Never re-record over `MAIN-CHECKOUT-UNKNOWN`**: that
|
|
310
310
|
walks the run from "could not look" to "certified clean" in one step, so
|
|
311
311
|
`--record` itself refuses over a baseline it cannot read and on any git
|
|
312
|
-
read that fails.
|
|
312
|
+
read that fails. The exceptions are a v1 baseline and a baseline whose
|
|
313
|
+
commit is missing from the repository; Phase 3's tick lines say how each
|
|
314
|
+
is cleared. `main-checkout.mjs --check` prints the same answer
|
|
313
315
|
without a tick.
|
|
314
316
|
|
|
315
317
|
**Run the pre-flight, once the pin and the baseline are recorded.**
|
|
@@ -606,8 +608,10 @@ phase, or in any later one, asks the maintainer which tickets to take.
|
|
|
606
608
|
— no ticket body is read here, because a Pull reads one ticket in full at
|
|
607
609
|
the moment it admits it:
|
|
608
610
|
|
|
609
|
-
- **Candidate scan** — `candidates.mjs --require-label ready-for-agent
|
|
610
|
-
oldest-first, never re-ranked. Its row count is
|
|
611
|
+
- **Candidate scan** — `candidates.mjs --require-label ready-for-agent
|
|
612
|
+
--with-dropped`, oldest-first, never re-ranked. Its row count is
|
|
613
|
+
`scanned`, the supply; the rows its to-spec filter removed are
|
|
614
|
+
`dropped`, counted nowhere.
|
|
611
615
|
- **Dependency scan**, `next-ticket` step 2, on each row's `d` array. Open
|
|
612
616
|
blocker → drop.
|
|
613
617
|
- **Live Exclusions** — a ticket whose ledger row reads `excluded ·
|
|
@@ -618,7 +622,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
|
|
|
618
622
|
free. Both drop the ticket, logged by number.
|
|
619
623
|
|
|
620
624
|
It writes the survivors, in order, to `.fleet/shortlist.json` —
|
|
621
|
-
`{scanned, shortlist: [{n, t}]}` — resolved against the git common dir by
|
|
625
|
+
`{scanned, shortlist: [{n, t}], dropped: [{n, reason}]}` — resolved against the git common dir by
|
|
622
626
|
`fleet-dir.mjs`, the one locator `ledger.mjs` resolves `.fleet/ledger.md`
|
|
623
627
|
with too, so you, the tick and a member in its own worktree all name one
|
|
624
628
|
file. **Exit 0 is the file written,
|
|
@@ -638,15 +642,20 @@ phase, or in any later one, asks the maintainer which tickets to take.
|
|
|
638
642
|
widen the list: `ready-for-human` needs a human to brainstorm first and you
|
|
639
643
|
have no channel to one mid-flight.
|
|
640
644
|
|
|
641
|
-
`candidates.mjs`'s exit 3 reaches you as an empty shortlist
|
|
642
|
-
|
|
645
|
+
`candidates.mjs`'s exit 3 reaches you as an empty shortlist whose `dropped`
|
|
646
|
+
names every ticket the to-spec filter took, by number and reason — and the
|
|
647
|
+
tick prints the same list on every tick, `specs-dropped=#<N> (to-spec: User
|
|
648
|
+
Stories heading)` on the implementer row. **Exit 3 is not that empty queue, and never a reason to
|
|
643
649
|
widen the net.** It says the labeled query returned rows and the to-spec
|
|
644
650
|
filter took every one: what is queued is to-tickets' input rather than
|
|
645
651
|
claimable tickets, and a member handed one implements an entire spec as a
|
|
646
652
|
single ticket. Log it as
|
|
647
|
-
specs awaiting to-tickets, not as no work —
|
|
653
|
+
specs awaiting to-tickets, not as no work — read the numbers off
|
|
654
|
+
`dropped` or `specs-dropped=`, not off stderr, which the tick's own
|
|
655
|
+
refresh discards — and still do not pass
|
|
648
656
|
`--allow-fallback`, whose second pass is unfiltered and so reaches the
|
|
649
|
-
`ready-for-human` and untriaged work you have no channel for.
|
|
657
|
+
`ready-for-human` and untriaged work you have no channel for. A partial
|
|
658
|
+
drop, survivors and specs together, is named the same way.
|
|
650
659
|
2. **Refresh is the tick's from here on.** `fleet-tick.mjs` runs
|
|
651
660
|
`shortlist.mjs` itself when unclaimed entries fall below the implementer
|
|
652
661
|
cap, when the file is missing or empty, and when an `excluded` premise has
|
|
@@ -1859,6 +1868,10 @@ depth** guard table applied in code. Act on each line as it reads:
|
|
|
1859
1868
|
blind until it can.
|
|
1860
1869
|
- `SUGGEST /triage, hold idle` — nothing is admissible after the refresh.
|
|
1861
1870
|
Suggest, never run (**Queue depth**).
|
|
1871
|
+
- `specs-dropped=#<N> … (to-spec: User Stories heading)` at the end of the
|
|
1872
|
+
implementer row's counts, whatever its ACTION — the tickets the to-spec
|
|
1873
|
+
filter kept out of `supply`, read off the shortlist's `dropped`. Never
|
|
1874
|
+
actionable. Log them as specs awaiting to-tickets (phase 0), not as no work.
|
|
1862
1875
|
- `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survived or unverified findings,
|
|
1863
1876
|
a dispositions mismatch no retry has answered, or a `conflict-hold:#<M>` — the merge bot's, or one you recorded off a `CONFLICT` line (**Reviewers**). Printed
|
|
1864
1877
|
ahead of reviews on purpose: finishing what is started beats starting more.
|
|
@@ -1931,9 +1944,13 @@ depth** guard table applied in code. Act on each line as it reads:
|
|
|
1931
1944
|
could not look: a git or hash read failed (`could not look:`), or the
|
|
1932
1945
|
baseline exists but cannot be read (`baseline unreadable:`). Never clean,
|
|
1933
1946
|
and **never re-baseline over it** — `--record` overwrites, so that certifies
|
|
1934
|
-
a tree nobody read. Fix what the line names and tick again. The
|
|
1935
|
-
|
|
1936
|
-
of HEAD
|
|
1947
|
+
a tree nobody read. Fix what the line names and tick again. The exceptions
|
|
1948
|
+
are the two whose remedy is `--record`: `baseline v1 — re-record`, an
|
|
1949
|
+
old-format baseline that says nothing of HEAD; and `baseline commit <oid> is
|
|
1950
|
+
missing from this repository`, which an amend or reset followed by gc
|
|
1951
|
+
leaves — examine HEAD against `origin/main` FIRST, since HEAD moved off
|
|
1952
|
+
that commit and nobody has looked at the move, and resolve any stray paths,
|
|
1953
|
+
which the line does not name; only then re-record.
|
|
1937
1954
|
- `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
|
|
1938
1955
|
baseline was recorded. Yours to fix: run Phase 0's `--record`. A baseline
|
|
1939
1956
|
that vanished mid-run is not a fresh run — report it to the maintainer
|
|
@@ -2018,6 +2035,9 @@ A live member past its family's threshold folds the same way — it is advice, s
|
|
|
2018
2035
|
nothing for the heartbeat to act on by itself — and the folded line names each
|
|
2019
2036
|
such member (`…; CHECK-LIVENESS fix-pr-5 persists — …`) for as long as it stays
|
|
2020
2037
|
live past the threshold.
|
|
2038
|
+
To-spec drops fold the same way, and the folded line names them
|
|
2039
|
+
(`…; specs-dropped=#<N> (to-spec: User Stories heading) persists — …`) for as
|
|
2040
|
+
long as the shortlist carries them.
|
|
2021
2041
|
|
|
2022
2042
|
**When you stop on purpose, say why — one command, and it is the last thing
|
|
2023
2043
|
you owe the next run.** The beat leaves a dated mark on every hold, so a run
|
|
@@ -3814,6 +3834,10 @@ never as a second, hand-run copy of it.
|
|
|
3814
3834
|
| below the cap, missing or empty | the tick refreshes first — `REFRESHED shortlist: n entries; k lifted` — and Pulls from what it found |
|
|
3815
3835
|
| 0 after that refresh | `SUGGEST /triage, hold idle` |
|
|
3816
3836
|
|
|
3837
|
+
Whatever the row prints, a `specs-dropped=#<N> (…)` at the end of its counts
|
|
3838
|
+
names the tickets the to-spec filter kept out of the shortlist — specs
|
|
3839
|
+
awaiting to-tickets, so an empty shortlist carrying one is not "no work".
|
|
3840
|
+
|
|
3817
3841
|
Four holds outrank every row: `HOLD (draining)` once `ledger.mjs drain` has
|
|
3818
3842
|
recorded the drain, `HOLD (tier mismatch impl-<N>)` until a replacement is
|
|
3819
3843
|
dispatched at the right tier, `HOLD (tier unchecked impl-<N>)` until
|
|
@@ -4356,7 +4380,7 @@ Plus a queue-depth line: shortlist, supply, whether triage was suggested.
|
|
|
4356
4380
|
- "This member finished, send it the next ticket" → resumes its transcript.
|
|
4357
4381
|
- "The name is cosmetic" → the name is the ledger token and the hub address.
|
|
4358
4382
|
- "Name the specialists too" → a depth-2 member cannot dispatch further.
|
|
4359
|
-
- "ready-for-agent came back empty, widen to ready-for-human" → empty means no work.
|
|
4383
|
+
- "ready-for-agent came back empty, widen to ready-for-human" → empty with no `specs-dropped=` means no work; empty with drops means specs awaiting to-tickets, and is still never a reason to widen.
|
|
4360
4384
|
- "The reap at the end will pick up the claim I never dispatched" → it declines:
|
|
4361
4385
|
not `[gone]`, no unique commits. Release it, or it reads as taken next run.
|
|
4362
4386
|
- "Touches eight files, too big for the fleet" → size is not the axis. Decided is.
|