@feigi/fleet-ctl 0.0.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.
Files changed (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,441 @@
1
+ #!/usr/bin/env node
2
+ // Writer and checker for docs/metrics/tier-outcomes.tsv (#2207, split off
3
+ // #1398). The `tier` column used to be typed by hand from what the controller
4
+ // MEANT to dispatch and was never compared with what ran: #1445 and #1446 say
5
+ // `opus` for two implementers dispatched as a generic `task` that ran
6
+ // sonnet/high, which is neither tier arm.
7
+ //
8
+ // append <pr> --class <c> --closed-own-ticket yes|no --minted-false-claim yes|no
9
+ // --note <text> [--sizing light|heavy] [--profile <p>] [--loc <n>] [--files <n>]
10
+ // Fills `run_date` (today, the ruling date), `pr`, `ticket` (off
11
+ // `gh pr view --json closingIssuesReferences`) and `tier`. Idempotent by
12
+ // PR: a row already present is named and nothing is written, exit 0.
13
+ // check [--live]
14
+ // Post-switch rows only: a filled `tier` must equal the short name of the
15
+ // ticket's single implementer row in member-outcomes.tsv, and that row
16
+ // must be a `fleet-implementer*` definition — exit 1 otherwise. `--live`
17
+ // (a run in progress; CI never passes it) adds a WARNING, never a
18
+ // failure, per PR whose run-ledger row carries `reviewed=` but which has
19
+ // no row here. `--ledger <path>` names another ledger than the run's own.
20
+ //
21
+ // `tier` resolution, in order (never tie-broken by `run_date`: the two files'
22
+ // `run_date`s mean different things — this file's header measures 92 of 267
23
+ // PRs whose date here is on no member row of theirs):
24
+ // 1. the `tier-ok=impl-<N>:<definition>` token tier-check.mjs wrote on the
25
+ // ticket's row of THIS run's ledger (there is one ledger per run);
26
+ // 2. else the ticket's single implementer row in member-outcomes.tsv, when
27
+ // its `subagent_type` is a `fleet-implementer*` definition — the PR ruled
28
+ // in a later run than the one that dispatched it;
29
+ // 3. else blank, with a WARNING naming why.
30
+ // A ledger mismatch is positive evidence the implementer did NOT run under
31
+ // its definition, so it blanks the tier rather than letting step 2 reach an
32
+ // older dispatch of the same ticket — read from either the free-text
33
+ // `tier-mismatch=impl-<N>:<definition>` token tier-check.mjs writes when the
34
+ // member is already settled some other way, or the member's own settled
35
+ // `impl-<N>=tier-mismatch` outcome, tier-check.mjs's main path for a mismatch
36
+ // caught while the member is still live.
37
+ //
38
+ // Values are definition SHORT NAMES (ADR 0011: never a vendor family):
39
+ // `fleet-implementer` is `default`, `fleet-implementer-<x>` is `<x>` (`alt`,
40
+ // or a #2030 per-cell name). Rows dated before TIER_SWITCH_DATE hold the old
41
+ // `opus`/`sonnet` spelling and are never checked; the header records the
42
+ // switch and how the old values map.
43
+ //
44
+ // Exit codes: 0 ok, 1 `check` found a mismatch, 2 usage or unreadable input.
45
+
46
+ import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
47
+ import { execFileSync } from "node:child_process";
48
+ import { dirname, join } from "node:path";
49
+ import { fileURLToPath, pathToFileURL } from "node:url";
50
+ import { makeDie, defineFlags, isDigits } from "./arg.mjs";
51
+ import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
52
+ import { parseMember, parseToken, memberTokens } from "./ledger-grammar.mjs";
53
+ import { rowText } from "./tier-check.mjs";
54
+ import { PR_MENTION } from "./fleet-tick.mjs";
55
+
56
+ const NAME = "tier-outcomes";
57
+ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
58
+ const LEDGER_SCRIPT = join(SCRIPT_DIR, "ledger.mjs");
59
+
60
+ // ---------------------------------------------------------------------------
61
+ // pure core — exercised through the CLI by tier-outcomes.test.mjs; only
62
+ // COLUMNS and TIER_SWITCH_DATE are imported directly, the rest through argv
63
+ // ---------------------------------------------------------------------------
64
+
65
+ // APPENDED TO, never inserted into: every awk read-out in the file's header
66
+ // and in run-team/SKILL.md indexes by position.
67
+ export const COLUMNS = Object.freeze([
68
+ "run_date", "pr", "ticket", "class", "tier", "closed_own_ticket",
69
+ "minted_false_claim", "note", "sizing", "profile", "loc", "files",
70
+ ]);
71
+ // Rows predating the four difficulty covariates are SHORT on purpose.
72
+ export const LEGACY_WIDTH = COLUMNS.length - 4;
73
+
74
+ // The first `run_date` whose `tier` is a definition short name. Also the
75
+ // date of the header's switch note.
76
+ export const TIER_SWITCH_DATE = "2026-09-29";
77
+
78
+ const DATE = /^\d{4}-\d{2}-\d{2}$/;
79
+ const BASE_DEFINITION = "fleet-implementer";
80
+
81
+ // `fleet-implementer` -> `default`, `fleet-implementer-<x>` -> `<x>`, anything
82
+ // else (a generic `task`, a blank pre-#1066 subagent_type) -> null.
83
+ export function shortName(definition) {
84
+ const d = String(definition ?? "");
85
+ if (d === BASE_DEFINITION) return "default";
86
+ if (d.startsWith(`${BASE_DEFINITION}-`) && d.length > BASE_DEFINITION.length + 1) return d.slice(BASE_DEFINITION.length + 1);
87
+ return null;
88
+ }
89
+
90
+ // Data rows as objects keyed by COLUMNS, plus the raw `line`. A row of any
91
+ // width but the legacy or the full one is refused: a tab typed into `note`
92
+ // shifts every field after it, and a reader keyed by position cannot tell.
93
+ export function parseTierOutcomes(text) {
94
+ return String(text ?? "").split("\n")
95
+ .filter((l) => l.trim() && !l.startsWith("#"))
96
+ .map((line) => {
97
+ const cells = line.split("\t");
98
+ if (cells.length !== LEGACY_WIDTH && cells.length !== COLUMNS.length) {
99
+ throw new Error(`malformed row: ${cells.length} fields, expected ${LEGACY_WIDTH} or ${COLUMNS.length} — ${line.slice(0, 60)}`);
100
+ }
101
+ const row = { line };
102
+ COLUMNS.forEach((c, i) => { row[c] = cells[i] ?? ""; });
103
+ return row;
104
+ });
105
+ }
106
+
107
+ export function formatRow(fields) {
108
+ return COLUMNS.map((c) => String(fields[c] ?? "")).join("\t");
109
+ }
110
+
111
+ // Every member-outcomes.tsv row for the ticket's implementer, of ANY agent
112
+ // type: a lone `task` row is still the ticket's one implementer, and the
113
+ // point of the check is to catch exactly that.
114
+ export function implementerRows(memberRows, ticket) {
115
+ return memberRows.filter((r) => r.role === "implementer" && r.ticket === String(ticket));
116
+ }
117
+
118
+ // tier-check.mjs's verdict tokens on a ledger row, restricted to this
119
+ // ticket's implementers.
120
+ const TIER_VERDICT = /^tier-(ok|mismatch)=([^:\s]+):(\S+)$/;
121
+
122
+ // A `{tier, source}` on success or `{tier: "", warning}` when the tier must
123
+ // stay blank — built ONLY through these two constructors, so a return site
124
+ // cannot pair a non-empty tier with a warning, or the reverse, by drifting
125
+ // out of convention (four independent literal object constructions used to
126
+ // enforce this by hand across tierFromLedger and tierFromMembers).
127
+ const ok = (tier, source) => ({ tier, source, warning: null });
128
+ const blocked = (warning) => ({ tier: "", source: null, warning });
129
+
130
+ // Step 1. Returns `ok(...)`, `blocked(...)` on a recorded mismatch, or null
131
+ // to fall through to member-outcomes.tsv. The implementer whose settled
132
+ // outcome is `PR#<pr>` owns the verdict when the ledger says who that is;
133
+ // otherwise the row must carry verdicts for exactly one member. A mismatch is
134
+ // read from EITHER of two ledger shapes: the free-text `tier-mismatch=impl-
135
+ // <N>:<definition>` token tier-check.mjs writes when the member is already
136
+ // settled some other way, or the member's own settled outcome
137
+ // `impl-<N>=tier-mismatch` — tier-check.mjs's main path, a mismatch caught
138
+ // while the member is still live, writes only that settled outcome and no
139
+ // free-text token (tier-check.mjs's recordImplementer).
140
+ export function tierFromLedger(ledger, ticket, pr) {
141
+ const text = rowText(ledger ?? {}, ticket);
142
+ if (!text) return null;
143
+ const ours = (name) => {
144
+ const m = parseMember(name);
145
+ return m?.family === "impl" && m.number === Number(ticket);
146
+ };
147
+ const tokens = [...(ledger.dispatched ?? []).map(parseToken), ...memberTokens(text)].filter((t) => t && ours(t.name));
148
+
149
+ const verdicts = [
150
+ ...text.split(/\s+/)
151
+ .map((t) => TIER_VERDICT.exec(t))
152
+ .filter(Boolean)
153
+ .map((m) => ({ kind: m[1], member: m[2], definition: m[3] }))
154
+ .filter((v) => ours(v.member)),
155
+ ...tokens.filter((t) => t.outcome === "tier-mismatch").map((t) => ({ kind: "mismatch", member: t.name, definition: null })),
156
+ ];
157
+ if (verdicts.length === 0) return null;
158
+
159
+ const owners = new Set(tokens.filter((t) => t.outcome === `PR#${pr}`).map((t) => t.name));
160
+ // A member settled to anything else terminal (released, bailed, killed) is
161
+ // positive evidence it did NOT open this PR, so its stale tier-ok verdict
162
+ // never wins the no-owner fallback below — but `tier-mismatch` itself is
163
+ // exempt: that outcome IS the mismatch verdict this function reports, not
164
+ // evidence of a different owner.
165
+ const disqualified = new Set(tokens.filter((t) => t.outcome !== null && t.outcome !== `PR#${pr}` && t.outcome !== "tier-mismatch").map((t) => t.name));
166
+ const mine = owners.size === 1 ? verdicts.filter((v) => owners.has(v.member)) : verdicts.filter((v) => !disqualified.has(v.member));
167
+ const members = new Set(mine.map((v) => v.member));
168
+ if (members.size !== 1) return null;
169
+ const [member] = members;
170
+
171
+ const mismatch = mine.find((v) => v.kind === "mismatch");
172
+ if (mismatch) {
173
+ return blocked(mismatch.definition
174
+ ? `the ledger records tier-mismatch=${member}:${mismatch.definition} — it did not run under its definition`
175
+ : `the ledger settled ${member}=tier-mismatch — it did not run under its definition`);
176
+ }
177
+ const definitions = new Set(mine.map((v) => v.definition));
178
+ if (definitions.size !== 1) return null;
179
+ const [definition] = definitions;
180
+ const tier = shortName(definition);
181
+ return tier ? ok(tier, `ledger tier-ok=${member}:${definition}`) : null;
182
+ }
183
+
184
+ // The member did not run a `fleet-implementer*` definition — shared between
185
+ // append's WARNING (tierFromMembers) and check's FAIL (checkRows) so the two
186
+ // wordings cannot drift apart.
187
+ const notADefinition = (m) => `${m.member} ran as ${m.subagentType ? `'${m.subagentType}'` : "no recorded agent type"}, not a ${BASE_DEFINITION}* definition`;
188
+
189
+ // Step 2, and step 3's reasons.
190
+ export function tierFromMembers(memberRows, ticket) {
191
+ const rows = implementerRows(memberRows, ticket);
192
+ if (rows.length === 0) return blocked(`no implementer row for #${ticket} in member-outcomes.tsv`);
193
+ if (rows.length > 1) {
194
+ return blocked(`${rows.length} implementer rows for #${ticket} in member-outcomes.tsv (${rows.map((r) => r.member).join(", ")}) — never tie-broken by run_date`);
195
+ }
196
+ const [row] = rows;
197
+ const tier = shortName(row.subagentType);
198
+ if (!tier) return blocked(notADefinition(row));
199
+ return ok(tier, `member-outcomes.tsv ${row.member} (${row.subagentType})`);
200
+ }
201
+
202
+ export function resolveTier({ ledger, memberRows, ticket, pr }) {
203
+ return tierFromLedger(ledger, ticket, pr) ?? tierFromMembers(memberRows, ticket);
204
+ }
205
+
206
+ // `check` over the committed files. Returns failure lines and skip counts.
207
+ export function checkRows(rows, memberRows) {
208
+ const failures = [];
209
+ const skipped = { preSwitch: 0, blank: 0, noMemberRow: 0, severalMemberRows: 0 };
210
+ let checked = 0;
211
+ for (const row of rows) {
212
+ if (!DATE.test(row.run_date)) {
213
+ failures.push(`PR #${row.pr}: run_date '${row.run_date}' is not YYYY-MM-DD`);
214
+ continue;
215
+ }
216
+ if (row.run_date < TIER_SWITCH_DATE) { skipped.preSwitch++; continue; }
217
+ if (row.tier === "") { skipped.blank++; continue; }
218
+ const members = implementerRows(memberRows, row.ticket);
219
+ if (members.length === 0) { skipped.noMemberRow++; continue; }
220
+ if (members.length > 1) { skipped.severalMemberRows++; continue; }
221
+ checked++;
222
+ const [m] = members;
223
+ const actual = shortName(m.subagentType);
224
+ if (actual === null) {
225
+ failures.push(`PR #${row.pr} (ticket #${row.ticket}): tier=${row.tier}, but ${notADefinition(m)}`);
226
+ } else if (actual !== row.tier) {
227
+ failures.push(`PR #${row.pr} (ticket #${row.ticket}): tier=${row.tier}, but ${m.member} ran as ${m.subagentType} (${actual})`);
228
+ }
229
+ }
230
+ return { failures, skipped, checked };
231
+ }
232
+
233
+ // The ledger half of `check`: every PR a run-ledger row marks `reviewed=` that
234
+ // has no row here. The row's PR is read the way fleet-tick.mjs reads it — a
235
+ // `PR#M` mention, else the row's own key.
236
+ export function unrecordedReviewedPrs(ledger, rows) {
237
+ const have = new Set(rows.map((r) => r.pr));
238
+ const missing = new Set();
239
+ for (const text of ledger?.rows ?? []) {
240
+ if (!text.split(/\s+/).some((t) => t.startsWith("reviewed="))) continue;
241
+ const key = text.split(/\s/)[0];
242
+ const mention = PR_MENTION.exec(text);
243
+ const pr = mention ? mention[1] : /^#[0-9]+$/.test(key) ? key.slice(1) : null;
244
+ if (pr && !have.has(pr)) missing.add(Number(pr));
245
+ }
246
+ return [...missing].sort((a, b) => a - b);
247
+ }
248
+
249
+ // ---------------------------------------------------------------------------
250
+ // CLI
251
+ // ---------------------------------------------------------------------------
252
+
253
+ const USAGE = "usage: tier-outcomes.mjs append <pr> --class <c> --closed-own-ticket yes|no --minted-false-claim yes|no --note <text> "
254
+ + "[--sizing light|heavy] [--profile <p>] [--loc <n>] [--files <n>] [--file <tsv>] [--member-outcomes <tsv>] [--ledger <path>]\n"
255
+ + " tier-outcomes.mjs check [--live] [--file <tsv>] [--member-outcomes <tsv>] [--ledger <path>]";
256
+
257
+ const die = makeDie(NAME);
258
+ const APPEND_FLAGS = {
259
+ class: "value", "closed-own-ticket": "value", "minted-false-claim": "value", note: "value",
260
+ sizing: "value", profile: "value", loc: "value", files: "value",
261
+ };
262
+ const FLAGS = { ...APPEND_FLAGS, file: "value", "member-outcomes": "value", ledger: "value", live: "bool" };
263
+ const { arg, has, sweep } = defineFlags(die, { flags: FLAGS });
264
+
265
+ // The positionals — a subcommand and, for `append`, the PR — skipping every
266
+ // declared flag's value the way arg.mjs's own stray scan does.
267
+ function positionals() {
268
+ const argv = process.argv.slice(2);
269
+ const out = [];
270
+ for (let i = 0; i < argv.length; i++) {
271
+ const a = argv[i];
272
+ if (a.startsWith("--")) {
273
+ if (!a.includes("=") && FLAGS[a.slice(2)] === "value") i++;
274
+ continue;
275
+ }
276
+ out.push(a);
277
+ }
278
+ return out;
279
+ }
280
+
281
+ function readText(path) {
282
+ try {
283
+ return existsSync(path) ? readFileSync(path, "utf8") : null;
284
+ } catch (e) {
285
+ die(`cannot read ${path}: ${e.code ?? e.message}`);
286
+ }
287
+ }
288
+
289
+ function readRows(path) {
290
+ const text = readText(path);
291
+ if (text === null) return { text: null, rows: [] };
292
+ try {
293
+ return { text, rows: parseTierOutcomes(text) };
294
+ } catch (e) {
295
+ die(`${path}: ${e.message}`);
296
+ }
297
+ }
298
+
299
+ function readMemberRows(path) {
300
+ const text = readText(path);
301
+ if (text === null) {
302
+ console.error(`${NAME}: no ${path} — no member rows to read`);
303
+ return [];
304
+ }
305
+ try {
306
+ return parseMemberTsv(text);
307
+ } catch (e) {
308
+ die(`${path}: ${e.message}`);
309
+ }
310
+ }
311
+
312
+ function readLedger(ledgerFile, requireFile) {
313
+ const args = [LEDGER_SCRIPT, ...(ledgerFile ? ["--file", ledgerFile] : []), ...(requireFile ? ["--require-file"] : []), "read"];
314
+ let raw;
315
+ try {
316
+ raw = execFileSync(process.execPath, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
317
+ } catch (e) {
318
+ die(`could not read the ledger: ${e.stderr?.trim() || e.message}`);
319
+ }
320
+ try {
321
+ return JSON.parse(raw);
322
+ } catch (e) {
323
+ die(`could not read the ledger: ${e.message}`);
324
+ }
325
+ }
326
+
327
+ function closingTicket(pr) {
328
+ let raw;
329
+ try {
330
+ raw = execFileSync("gh", ["pr", "view", pr, "--json", "closingIssuesReferences"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
331
+ } catch (e) {
332
+ die(`gh pr view ${pr} failed: ${e.stderr?.trim() || e.message}`);
333
+ }
334
+ let refs;
335
+ try {
336
+ refs = JSON.parse(raw).closingIssuesReferences;
337
+ } catch (e) {
338
+ die(`gh pr view ${pr} returned unreadable JSON: ${e.message}`);
339
+ }
340
+ if (!Array.isArray(refs)) die(`gh pr view ${pr} returned no closingIssuesReferences array`);
341
+ const numbers = [...new Set(refs.map((r) => r?.number))];
342
+ if (numbers.length !== 1 || !Number.isInteger(numbers[0])) {
343
+ die(`PR #${pr} closes ${numbers.length === 0 ? "no issue" : `${numbers.length} issues (${numbers.map((n) => `#${n}`).join(", ")})`} per GitHub's closingIssuesReferences — a tier-outcomes row keys on exactly one ticket`);
344
+ }
345
+ return String(numbers[0]);
346
+ }
347
+
348
+ function today() {
349
+ const d = new Date();
350
+ const pad = (n) => String(n).padStart(2, "0");
351
+ return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
352
+ }
353
+
354
+ function append(pr, paths) {
355
+ if (!isDigits(pr) || Number(pr) === 0) die(`append needs a PR number, got '${pr}'`);
356
+ pr = String(Number(pr));
357
+ if (has("live")) die("--live is a check flag");
358
+ const fields = {
359
+ class: arg("class"), closed_own_ticket: arg("closed-own-ticket"), minted_false_claim: arg("minted-false-claim"),
360
+ note: arg("note"), sizing: arg("sizing") ?? "", profile: arg("profile") ?? "", loc: arg("loc") ?? "", files: arg("files") ?? "",
361
+ };
362
+ for (const col of ["class", "closed_own_ticket", "minted_false_claim", "note"]) {
363
+ if (fields[col] === null) die(`append needs --${col.replaceAll("_", "-")}\n${USAGE}`);
364
+ }
365
+ for (const [col, value] of Object.entries(fields)) {
366
+ if (/[\t\r\n]/.test(value)) die(`--${col.replaceAll("_", "-")} holds a tab or newline — it would shift every field after it`);
367
+ }
368
+ for (const col of ["closed_own_ticket", "minted_false_claim"]) {
369
+ if (!["yes", "no"].includes(fields[col])) die(`--${col.replaceAll("_", "-")} must be yes or no, got '${fields[col]}'`);
370
+ }
371
+ if (!/^[a-z][a-z-]*$/.test(fields.class)) die(`--class must be one lowercase word, got '${fields.class}'`);
372
+ if (fields.sizing && !["light", "heavy"].includes(fields.sizing)) die(`--sizing must be light or heavy, got '${fields.sizing}'`);
373
+ for (const col of ["loc", "files"]) {
374
+ if (fields[col] && !isDigits(fields[col])) die(`--${col} must be a count, got '${fields[col]}'`);
375
+ }
376
+
377
+ const { text, rows } = readRows(paths.file);
378
+ const existing = rows.find((r) => r.pr === pr);
379
+ if (existing) {
380
+ console.log(`${NAME}: PR #${pr} already has a row in ${paths.file} — nothing appended:\n${existing.line}`);
381
+ return;
382
+ }
383
+
384
+ const ticket = closingTicket(pr);
385
+ const ledger = readLedger(paths.ledger, false);
386
+ const memberRows = readMemberRows(paths.members);
387
+ const resolved = resolveTier({ ledger, memberRows, ticket, pr });
388
+ if (resolved.warning) console.error(`${NAME}: WARNING tier left blank for PR #${pr} (ticket #${ticket}): ${resolved.warning}`);
389
+ else console.error(`${NAME}: tier=${resolved.tier} from ${resolved.source}`);
390
+
391
+ const line = formatRow({ ...fields, run_date: today(), pr, ticket, tier: resolved.tier });
392
+ if (text === null) writeFileSync(paths.file, `# ${COLUMNS.join("\t")}\n${line}\n`);
393
+ else appendFileSync(paths.file, `${text === "" || text.endsWith("\n") ? "" : "\n"}${line}\n`);
394
+ console.log(line);
395
+ }
396
+
397
+ function check(paths) {
398
+ for (const flag of Object.keys(APPEND_FLAGS)) {
399
+ if (arg(flag) !== null) die(`--${flag} is an append flag`);
400
+ }
401
+ const { text, rows } = readRows(paths.file);
402
+ if (text === null) die(`no ${paths.file} — no rows to check`);
403
+ const memberRows = readMemberRows(paths.members);
404
+ const { failures, skipped, checked } = checkRows(rows, memberRows);
405
+
406
+ if (has("live")) {
407
+ const ledger = readLedger(paths.ledger, true);
408
+ for (const pr of unrecordedReviewedPrs(ledger, rows)) {
409
+ console.error(`${NAME}: WARNING PR #${pr} carries reviewed= on the ledger but has no row in ${paths.file} — run \`tier-outcomes.mjs append ${pr}\` if it is an implementer PR`);
410
+ }
411
+ }
412
+
413
+ for (const f of failures) console.error(`${NAME}: FAIL ${f}`);
414
+ console.log(`${NAME}: ${rows.length} rows; ${checked} checked, ${failures.length} failed; skipped ${skipped.preSwitch} before ${TIER_SWITCH_DATE}, `
415
+ + `${skipped.blank} blank, ${skipped.noMemberRow} with no member row, ${skipped.severalMemberRows} with several member rows`);
416
+ process.exit(failures.length ? 1 : 0);
417
+ }
418
+
419
+ function main() {
420
+ const paths = {
421
+ file: arg("file") ?? "docs/metrics/tier-outcomes.tsv",
422
+ members: arg("member-outcomes") ?? "docs/metrics/member-outcomes.tsv",
423
+ ledger: arg("ledger"),
424
+ };
425
+ // Below every flag read, per arg.mjs's ordering contract, and above the
426
+ // subcommand checks, so a stray flag is refused by name before anything
427
+ // reads a file or asks gh.
428
+ sweep();
429
+ const [cmd, ...rest] = positionals();
430
+ if (cmd === "append") {
431
+ if (rest.length !== 1) die(`append takes exactly one PR number\n${USAGE}`);
432
+ append(rest[0], paths);
433
+ } else if (cmd === "check") {
434
+ if (rest.length) die(`check takes no positional, got '${rest[0]}'\n${USAGE}`);
435
+ check(paths);
436
+ } else {
437
+ die(cmd ? `unknown subcommand '${cmd}'\n${USAGE}` : USAGE);
438
+ }
439
+ }
440
+
441
+ if (import.meta.url === pathToFileURL(process.argv[1] || "").href) main();