@feigi/fleet-ctl 3.121.0 → 3.122.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.121.0",
3
+ "version": "3.122.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -371,11 +371,12 @@ function reasonWords(r, table) {
371
371
  }
372
372
  }
373
373
 
374
- // The Stratum and the numbers that set it.
374
+ // The Stratum and the numbers that set it: a Slice's parent sets it, ahead of the brief's numbers.
375
375
  function stratumWords(r) {
376
376
  if (r.sized !== null) return `${r.stratum}: sized ${r.sized}`;
377
377
  if (r.brief === null) return `${r.stratum}: no brief read`;
378
378
  if (r.reason === "no-sizing") return `${r.stratum}: no sizing`;
379
+ if (r.parent !== null) return `${r.stratum}: Slice of #${r.parent}`;
379
380
  const past = (n, at) => `${n > at ? "past" : "not past"} ${grouped(at)}`;
380
381
  return `${r.stratum}: ${grouped(r.brief)} chars (${past(r.brief, HEAVY_BRIEF_CHARS)}), ${r.criteria} criteria (${past(r.criteria, HEAVY_CRITERIA)})`;
381
382
  }
@@ -132,6 +132,11 @@
132
132
  // 7 claimKind shape, below the claim bar suggestion-band record
133
133
  // 8 survived, out of scope, whatever its reason open, needs-triage
134
134
  //
135
+ // The labels in the table and below are Label roles (label-map.mjs): the
136
+ // script reads a home's labels, and words the home, as the strings the
137
+ // Label map maps those roles to — `needs-triage`, `ready-for-agent` and
138
+ // `wontfix` are the identity map's spellings.
139
+ //
135
140
  // Row 4 outranks row 7, and row 7 every other row. A row-5 deferral is
136
141
  // held to row 1's reasons: one of ALLOWED_DEFER other than
137
142
  // false-rationale, `remedy-outside-diff` under the rule above. A row-6b
@@ -152,7 +157,8 @@
152
157
  // check again once `gh` answers.
153
158
  //
154
159
  // Exit status: 0 ok; 1 mismatch, escalate or unchecked; 2 nothing judged and
155
- // nothing written — a bad flag, an unreadable or malformed review file, a
160
+ // nothing written — a bad flag, no valid Label map (the message names
161
+ // `label-map.mjs ensure`), an unreadable or malformed review file, a
156
162
  // record file that exists but cannot be read, a git or ledger failure. A
157
163
  // missing or unparseable RECORD is judged, not refused: the fix-applier wrote
158
164
  // nothing a reader can use, so every finding it had to cover is dropped.
@@ -182,6 +188,7 @@ import { makeDie, defineFlags } from "./arg.mjs";
182
188
  import { isCLI } from "./is-cli.mjs";
183
189
  import { gitEnv } from "./git-env.mjs";
184
190
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
191
+ import { readLabelMap } from "./label-map.mjs";
185
192
  import { parseMember, memberTokens, rowNums, dispositionsToken, firstReview, prTokens } from "./ledger-grammar.mjs";
186
193
  import { deriveRun, LedgerError } from "./fleet-tick.mjs";
187
194
  import { VERDICT_SCHEMA } from "./review-core.mjs";
@@ -212,7 +219,9 @@ export const CHARGES = Object.freeze(["false-claim", "unmet", "both", "none"]);
212
219
  export const CHARGE_REASONS = Object.freeze(["defect-outside-acceptance", "not-the-implementers-text", "claim-about-untouched-code"]);
213
220
 
214
221
  // The filing table: a deferral's home by its finding's state. `record` is the
215
- // suggestion-band record; `open` the weakest triage label an open home may carry.
222
+ // suggestion-band record; `open` the Label role of the weakest triage label an
223
+ // open home may carry — a role, never a string: homeText and homeHolds read the
224
+ // string it maps to from the Label map handed to checkDispositions.
216
225
  export const FILING_ROWS = Object.freeze({
217
226
  1: { finding: "an in-scope survived finding deferred for an allowed reason other than false-rationale", open: "needs-triage" },
218
227
  2: { finding: "an in-scope survived finding deferred false-rationale", record: true },
@@ -224,22 +233,28 @@ export const FILING_ROWS = Object.freeze({
224
233
  7: { finding: "a finding whose claim is about shape, below the claim bar", record: true },
225
234
  8: { finding: "an out-of-scope survived finding, whatever its reason", open: "needs-triage" },
226
235
  });
227
- // Strongest first: an open home may carry a label above its row's, never below.
228
- const TRIAGE_LABELS = ["ready-for-agent", "needs-triage"];
236
+ // The triage roles, strongest first: an open home may carry a label above its
237
+ // row's, never below.
238
+ const TRIAGE_ROLES = ["ready-for-agent", "needs-triage"];
229
239
  // Row 1's reasons, which a row-5 deferral is held to.
230
240
  const ROW_1_DEFER = ALLOWED_DEFER.filter((r) => r !== "false-rationale");
231
241
  export const recordTitle = (pr) => `PR #${pr} review: the suggestion band, checked`;
232
242
 
233
- function homeText(row, pr) {
234
- if (row.record) return `the closed "${recordTitle(pr)}" issue, labelled wontfix`;
235
- return `an open issue labelled ${TRIAGE_LABELS.slice(0, TRIAGE_LABELS.indexOf(row.open) + 1).reverse().join(" or ")}`;
243
+ // `roles` is the Label map's role -> string table: the tracker spells a label
244
+ // its own way, and the home is read and worded in that spelling.
245
+ function homeText(row, pr, roles) {
246
+ if (row.record) return `the closed "${recordTitle(pr)}" issue, labelled ${roles.wontfix}`;
247
+ return `an open issue labelled ${TRIAGE_ROLES.slice(0, TRIAGE_ROLES.indexOf(row.open) + 1).reverse().map((r) => roles[r]).join(" or ")}`;
236
248
  }
237
249
 
238
- // Whether an issue `{state, title, labels}` is `row`'s home on PR `pr`.
239
- function homeHolds(row, { state, title, labels }, pr) {
240
- if (row.record) return state === "CLOSED" && title.trim() === recordTitle(pr) && labels.includes("wontfix");
241
- const triage = labels.filter((l) => TRIAGE_LABELS.includes(l));
242
- return state === "OPEN" && triage.length === 1 && TRIAGE_LABELS.indexOf(triage[0]) <= TRIAGE_LABELS.indexOf(row.open);
250
+ // Whether an issue `{state, title, labels}` is `row`'s home on PR `pr`. The
251
+ // labels are the names `gh` returned, compared as they stand: the map holds
252
+ // the tracker's own spelling.
253
+ function homeHolds(row, { state, title, labels }, pr, roles) {
254
+ if (row.record) return state === "CLOSED" && title.trim() === recordTitle(pr) && labels.includes(roles.wontfix);
255
+ const triage = TRIAGE_ROLES.map((role) => roles[role]);
256
+ const carried = labels.filter((l) => triage.includes(l));
257
+ return state === "OPEN" && carried.length === 1 && triage.indexOf(carried[0]) <= TRIAGE_ROLES.indexOf(row.open);
243
258
  }
244
259
 
245
260
  // The row a deferral's finding state puts it on, by precedence, or null when
@@ -465,8 +480,10 @@ function chargeProblem(e, { inScope, required }) {
465
480
  * defers `remedy-outside-diff`; `run` the review's run root name, or null when
466
481
  * no ledger names it — a record answers it only by carrying the same `run`;
467
482
  * `roots` the directories an absolute finding
468
- * or remedy path is read relative to. `filing` is `{pr, issue(n), verdict(path)}`,
469
- * required only when an entry defers or is a suggestion whose verdict is read: `issue`
483
+ * or remedy path is read relative to. `filing` is `{pr, roles, issue(n), verdict(path)}`,
484
+ * required only when an entry defers or is a suggestion whose verdict is read: `roles` is
485
+ * the Label map's role -> string table, the spelling a home's labels are compared and worded
486
+ * in; `issue`
470
487
  * answers `{state, title, labels}` — `state` upper-case, `labels` names — or
471
488
  * `{problem}` when the tracker cannot say; `verdict` answers `{refuted}` for
472
489
  * a refuter verdict path or `{problem}` when it is no usable evidence, with
@@ -564,7 +581,7 @@ export function checkDispositions({ review, record, recordProblem = null, run =
564
581
  if (e.disposition === "apply" && (refuted === true || (refuted === null && !inScope))) {
565
582
  const rowNo = filingRow({ bucket, inScope, crashed, refuted, shape });
566
583
  const though = refuted ? "its verdict is refuted: true —" : `its refuter decided nothing — ${problem};`;
567
- at(bucket, index, `filing row ${rowNo} (${FILING_ROWS[rowNo].finding}): applied, though ${though} it belongs in ${homeText(FILING_ROWS[rowNo], filing.pr)}`);
584
+ at(bucket, index, `filing row ${rowNo} (${FILING_ROWS[rowNo].finding}): applied, though ${though} it belongs in ${homeText(FILING_ROWS[rowNo], filing.pr, filing.roles)}`);
568
585
  return;
569
586
  }
570
587
  }
@@ -603,9 +620,9 @@ export function checkDispositions({ review, record, recordProblem = null, run =
603
620
  return;
604
621
  }
605
622
  const row = FILING_ROWS[rowNo];
606
- const { pr, issue: readIssue } = filingOf();
623
+ const { pr, roles, issue: readIssue } = filingOf();
607
624
  if (e.issue === undefined) {
608
- at(bucket, index, `filing row ${rowNo} (${row.finding}): a deferral names the issue it was filed to, and this entry names none — it belongs in ${homeText(row, pr)}`);
625
+ at(bucket, index, `filing row ${rowNo} (${row.finding}): a deferral names the issue it was filed to, and this entry names none — it belongs in ${homeText(row, pr, roles)}`);
609
626
  return;
610
627
  }
611
628
  const issue = readIssue(e.issue);
@@ -613,8 +630,8 @@ export function checkDispositions({ review, record, recordProblem = null, run =
613
630
  unchecked.push({ bucket, index, issue: e.issue, problem: issue.problem });
614
631
  return;
615
632
  }
616
- if (!homeHolds(row, issue, pr)) {
617
- at(bucket, index, `filing row ${rowNo} (${row.finding}): it belongs in ${homeText(row, pr)}, and #${e.issue} is ${describeIssue(issue)}`);
633
+ if (!homeHolds(row, issue, pr, roles)) {
634
+ at(bucket, index, `filing row ${rowNo} (${row.finding}): it belongs in ${homeText(row, pr, roles)}, and #${e.issue} is ${describeIssue(issue)}`);
618
635
  }
619
636
  });
620
637
 
@@ -831,18 +848,32 @@ function main() {
831
848
  const standalone = has("no-ledger");
832
849
  if (standalone && arg("ledger") !== null) die("--no-ledger and --ledger contradict: name one");
833
850
  const ledgerFile = standalone ? null : ledgerInUse(arg("ledger"), repo);
851
+ // Without a ledger nothing names the review the record answers, so `--review`
852
+ // must; with one, the latest `reviewed=` already does. Both are usage errors,
853
+ // so they are told before the Label map, the ledger or the tracker is read.
854
+ if (ledgerFile === null && arg("review") === null) die(`no ledger names PR #${pr}'s review — pass --review <path> for the review file ${member.name}'s record answers`);
855
+ if (ledgerFile !== null && arg("review") !== null) die(`--review and a ledger contradict: with a ledger the review is the one PR #${pr}'s latest reviewed= names`);
856
+ // The Label map, read once, here at the I/O boundary — after the flags and the
857
+ // ledger's location are settled, before the ledger or the tracker is read: a
858
+ // home's labels are compared and worded in the tracker's own spelling. No
859
+ // valid map is "nothing judged" (exit 2), never a verdict; the reader's
860
+ // message names `ensure`.
861
+ let roles;
862
+ try {
863
+ roles = readLabelMap({ cwd: repo });
864
+ } catch (e) {
865
+ die(e.message);
866
+ }
834
867
 
835
868
  // The review the record answers. With a ledger it is the one PR M's latest
836
869
  // `reviewed=` names — `<scratch>/pr<M>/<run>/review.json`, read off the
837
870
  // same per-PR fold `ledger.mjs dispatch` gates the finisher by, so the check
838
- // and the gate never judge two different reviews. Without one nothing names
839
- // it, so `--review` must.
871
+ // and the gate never judge two different reviews. Without one it is the
872
+ // `--review` path the checks above required.
840
873
  let data = null, row = null, run = null, charges = false, reviewPath;
841
874
  if (ledgerFile === null) {
842
875
  reviewPath = arg("review");
843
- if (reviewPath === null) die(`no ledger names PR #${pr}'s review — pass --review <path> for the review file ${member.name}'s record answers`);
844
876
  } else {
845
- if (arg("review") !== null) die(`--review and a ledger contradict: with a ledger the review is the one PR #${pr}'s latest reviewed= names`);
846
877
  data = JSON.parse(runLedger(ledgerFile, ["read"], "read the ledger"));
847
878
  // The verdict lands on the row carrying the member on its own PR's row —
848
879
  // where `ledger.mjs dispatch` wrote it, and where the gate reads PR M's
@@ -908,7 +939,7 @@ function main() {
908
939
 
909
940
  const { violations, escalations, unchecked } = checkDispositions({
910
941
  review, record, recordProblem, run, touched: touchedLines(diff), diffFiles, roots: [review.snapshot, top], charges,
911
- filing: { pr, issue: issueReader(repo), verdict: verdictReader(scratch, pr) },
942
+ filing: { pr, roles, issue: issueReader(repo), verdict: verdictReader(scratch, pr) },
912
943
  });
913
944
  // No ledger, no row: the exit status below is the verdict, and with no
914
945
  // earlier fix-applier's verdict to count, a broken rule is always a
@@ -817,10 +817,12 @@ export function drawCell({ session, ticket, policyCell, cells }) {
817
817
  // POLICY the policy row's Cell CELL the Pull's Cell
818
818
  // DRAW k/K of the draw BY burn-in | every-5th
819
819
  // STRATUM light | heavy | unknown BRIEF the brief's chars
820
- // CRITERIA the criteria count SIZED arm B's sizing label
821
- // OBJECTIVE cost | speed TRIPPED the guard's tripped Cells
822
- // REASON the first thing that went wrong
823
- // DRAW and BY are `-` together (no draw); so are BRIEF and CRITERIA (no issue read).
820
+ // CRITERIA the criteria count PARENT a Slice's parent issue
821
+ // SIZED arm B's sizing label OBJECTIVE cost | speed
822
+ // TRIPPED the guard's tripped Cells REASON the first thing that went wrong
823
+ // DRAW and BY are `-` together (no draw); so are BRIEF and CRITERIA (no issue
824
+ // read), and PARENT is `-` with them. A line written before PARENT was a part
825
+ // carries none, and reads as `PARENT=-`.
824
826
  export const STRATA = Object.freeze(["light", "heavy", "unknown"]);
825
827
  // What a run asks the router to minimise. phase0.mjs records the run's in its
826
828
  // receipt, and every Routing names the one it routed by.
@@ -828,19 +830,24 @@ export const OBJECTIVES = Object.freeze(["cost", "speed"]);
828
830
  const DRAWN_BY = Object.freeze(["burn-in", "every-5th"]);
829
831
  export const ROUTING_REASONS = Object.freeze(["ok", "no-issue-json", "no-sizing", "guard-missing", "guard-tripped", "table-cell-tripped"]);
830
832
  const SIZINGS = Object.freeze(["light", "heavy"]);
831
- const ROUTING_KEYS = Object.freeze(["POLICY", "CELL", "DRAW", "BY", "STRATUM", "BRIEF", "CRITERIA", "SIZED", "OBJECTIVE", "TRIPPED", "REASON"]);
833
+ const ROUTING_KEYS = Object.freeze(["POLICY", "CELL", "DRAW", "BY", "STRATUM", "BRIEF", "CRITERIA", "PARENT", "SIZED", "OBJECTIVE", "TRIPPED", "REASON"]);
834
+ const PARENT_AT = ROUTING_KEYS.indexOf("PARENT");
835
+ const ISSUE = /^[1-9][0-9]*$/;
832
836
  const COUNT = /^(?:0|[1-9][0-9]*)$/;
833
837
  const DRAW = /^([1-9][0-9]*)\/([1-9][0-9]*)$/;
834
838
 
835
839
  /**
836
840
  * A Routing line read into its parts, or null when it is not one.
837
841
  * @returns {null | { policy: string, cell: string, draw: null | { k: number, K: number }, by: null | string,
838
- * stratum: string, brief: null | number, criteria: null | number, sized: null | string, objective: string,
839
- * tripped: string[], reason: string }}
842
+ * stratum: string, brief: null | number, criteria: null | number, parent: null | number, sized: null | string,
843
+ * objective: string, tripped: string[], reason: string }}
840
844
  */
841
845
  export function parseRouting(line) {
842
846
  if (typeof line !== "string") return null;
843
847
  const words = line.split(" ");
848
+ // A line written before PARENT was a part is one word short; one that holds
849
+ // PARENT= and lacks another key instead fails the per-key check.
850
+ if (words.length === ROUTING_KEYS.length - 1) words.splice(PARENT_AT, 0, "PARENT=-");
844
851
  if (words.length !== ROUTING_KEYS.length) return null;
845
852
  const v = {};
846
853
  for (const [i, key] of ROUTING_KEYS.entries()) {
@@ -859,6 +866,7 @@ export function parseRouting(line) {
859
866
  stratum: STRATA.includes(v.STRATUM) ? v.STRATUM : undefined,
860
867
  brief: count(v.BRIEF),
861
868
  criteria: count(v.CRITERIA),
869
+ parent: v.PARENT === "-" ? null : ISSUE.test(v.PARENT) && Number.isSafeInteger(Number(v.PARENT)) ? Number(v.PARENT) : undefined,
862
870
  sized: opt(v.SIZED, (x) => SIZINGS.includes(x)),
863
871
  objective: OBJECTIVES.includes(v.OBJECTIVE) ? v.OBJECTIVE : undefined,
864
872
  tripped: tripped.every((c) => CELL.test(c)) ? tripped : undefined,
@@ -867,15 +875,16 @@ export function parseRouting(line) {
867
875
  if (Object.values(r).includes(undefined)) return null;
868
876
  if (r.draw !== null && r.draw.k > r.draw.K) return null;
869
877
  if ((r.draw === null) !== (r.by === null) || (r.brief === null) !== (r.criteria === null)) return null;
878
+ if (r.parent !== null && r.brief === null) return null;
870
879
  return r;
871
880
  }
872
881
 
873
882
  /** The Routing line for parsed parts; throws on parts no Routing line can carry, so nothing writes one parseRouting refuses. */
874
- export function formatRouting({ policy, cell, draw, by, stratum, brief, criteria, sized, objective, tripped, reason }) {
883
+ export function formatRouting({ policy, cell, draw, by, stratum, brief, criteria, parent, sized, objective, tripped, reason }) {
875
884
  const none = (x) => (x === null ? "-" : String(x));
876
885
  const line = [
877
886
  `POLICY=${policy}`, `CELL=${cell}`, `DRAW=${draw === null ? "-" : `${draw.k}/${draw.K}`}`, `BY=${none(by)}`,
878
- `STRATUM=${stratum}`, `BRIEF=${none(brief)}`, `CRITERIA=${none(criteria)}`, `SIZED=${none(sized)}`,
887
+ `STRATUM=${stratum}`, `BRIEF=${none(brief)}`, `CRITERIA=${none(criteria)}`, `PARENT=${none(parent)}`, `SIZED=${none(sized)}`,
879
888
  `OBJECTIVE=${objective}`, `TRIPPED=${tripped.length === 0 ? "-" : tripped.join(",")}`, `REASON=${reason}`,
880
889
  ].join(" ");
881
890
  if (parseRouting(line) === null) throw new Error(`not a Routing: ${line}`);
@@ -89,14 +89,16 @@ import { parseMemberName } from "./member-record.mjs";
89
89
  import { isImplementer } from "./member-outcomes.mjs";
90
90
  import { DATE, isDerivedNote, rulingFor, rulingsByTicket } from "./tier-outcomes.mjs";
91
91
 
92
- // The ticket-features row, one per Pull, in this order. `objective` came last
93
- // and is optional on read: a file whose header lacks it reads it blank.
92
+ // The ticket-features row, one per Pull, in this order. `objective` and
93
+ // `parent` came last and are optional on read: a file whose header lacks
94
+ // either reads it blank. `parent` is a Slice's parent issue number, blank for
95
+ // a ticket that is no Slice (ticket-router.mjs's sliceParent).
94
96
  export const FEATURE_COLUMNS = Object.freeze([
95
97
  "run_date", "session", "agent", "ticket", "policy_cell", "chosen_cell", "exploration_draw",
96
98
  "sizing_src", "sizing_pre", "router_usd", "brief_chars", "criteria", "comments", "age_days",
97
- "paths", "test_paths", "xrefs", "kind", "objective",
99
+ "paths", "test_paths", "xrefs", "kind", "objective", "parent",
98
100
  ]);
99
- const OPTIONAL_COLUMNS = new Set(["objective"]);
101
+ export const OPTIONAL_COLUMNS = new Set(["objective", "parent"]);
100
102
 
101
103
  // The quality floor's margin, in points of fail rate.
102
104
  export const TRIP_POINTS = 15;
@@ -170,6 +172,7 @@ export function parseFeatures(text) {
170
172
  const row = Object.fromEntries(header.map((c, j) => [c, cells[j]]));
171
173
  for (const c of OPTIONAL_COLUMNS) row[c] ??= "";
172
174
  if (!isDigits(row.ticket)) throw new Error(`ticket-features.tsv row ${i + 1}: ticket ${JSON.stringify(row.ticket)} is not a number`);
175
+ if (row.parent !== "" && !isDigits(row.parent)) throw new Error(`ticket-features.tsv row ${i + 1}: parent ${JSON.stringify(row.parent)} is not blank or a number`);
173
176
  if (!CELL.test(row.chosen_cell)) throw new Error(`ticket-features.tsv row ${i + 1}: chosen_cell ${JSON.stringify(row.chosen_cell)} is not a cell`);
174
177
  return row;
175
178
  });
@@ -0,0 +1,114 @@
1
+ #!/usr/bin/env node
2
+ // Fills the `parent` column of a ticket-features corpus from each ticket's
3
+ // issue body, so the Router's fit reads every Slice as a Slice.
4
+ //
5
+ // slice-fill.mjs [--features <tsv>]
6
+ //
7
+ // `--features` is the corpus, `docs/metrics/ticket-features.tsv` under the cwd
8
+ // when omitted; `gh` reads the issues of the repository the cwd is in. A
9
+ // corpus whose header lacks `parent` gains it, blank on every row. Then every
10
+ // row whose ticket is a Slice (ticket-router.mjs's sliceParent, off the
11
+ // issue's current body) gets its parent's number, and nothing else changes: a
12
+ // row whose ticket is no Slice keeps its `parent` as it is, and a run over a
13
+ // filled corpus writes nothing. So it is safe to run again, and it is what
14
+ // sets `parent` on rows a run drained from a plugin that wrote no `parent`.
15
+ //
16
+ // Prints one line naming how many rows it set. Exit 0 when every ticket's
17
+ // issue was read; 1 when some could not be — their rows are left as they
18
+ // were, each named on stderr, and the rest are written; 2 on a usage error, a
19
+ // corpus that does not parse, or a corpus that cannot be written, which
20
+ // writes nothing.
21
+
22
+ import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
23
+ import { resolve } from "node:path";
24
+ import { makeDie, defineFlags } from "./arg.mjs";
25
+ import { ghAliasedRead } from "./gh-aliased-read.mjs";
26
+ import { isCLI } from "./is-cli.mjs";
27
+ import { parseFeatures } from "./pull-attribution.mjs";
28
+ import { sliceParent } from "./ticket-router.mjs";
29
+
30
+ const NAME = "slice-fill";
31
+ const DEFAULT_FEATURES = "docs/metrics/ticket-features.tsv";
32
+ const GH_TIMEOUT_MS = 120_000;
33
+
34
+ /**
35
+ * `text`, a ticket-features corpus, with `parent` set on every row whose
36
+ * ticket `parents` maps to a parent number: `parents` maps a ticket (as a
37
+ * string) to its parent's number, or to "" for a ticket that is no Slice. A
38
+ * ticket it leaves out keeps its rows as they are. A header without `parent`
39
+ * gains it, blank on every row. Comment lines, row order and every other cell
40
+ * are kept byte for byte. Throws on a corpus parseFeatures refuses.
41
+ * @returns {{ text: string, set: number, widened: boolean }}
42
+ */
43
+ export function fillParent(text, parents) {
44
+ parseFeatures(text);
45
+ const lines = String(text).split("\n");
46
+ let ticketAt = -1;
47
+ let at = -1;
48
+ let set = 0;
49
+ let widened = false;
50
+ const out = lines.map((l) => {
51
+ if (!l.trim() || l.startsWith("#")) return l;
52
+ if (at === -1) {
53
+ const header = l.split("\t");
54
+ ticketAt = header.indexOf("ticket");
55
+ at = header.indexOf("parent");
56
+ if (at !== -1) return l;
57
+ widened = true;
58
+ at = header.length;
59
+ return `${l}\tparent`;
60
+ }
61
+ const cells = l.split("\t");
62
+ if (widened) cells.push("");
63
+ const parent = parents.get(cells[ticketAt]) ?? "";
64
+ if (parent !== "" && cells[at] !== parent) {
65
+ cells[at] = parent;
66
+ set += 1;
67
+ }
68
+ return cells.join("\t");
69
+ });
70
+ return { text: out.join("\n"), set, widened };
71
+ }
72
+
73
+ function main() {
74
+ const die = makeDie(NAME);
75
+ const F = defineFlags(die, { flags: { features: "value" } });
76
+ F.sweep();
77
+ F.stray();
78
+ const file = resolve(F.arg("features") ?? DEFAULT_FEATURES);
79
+ let text;
80
+ let tickets;
81
+ try {
82
+ text = readFileSync(file, "utf8");
83
+ tickets = [...new Set(parseFeatures(text).map((r) => Number(r.ticket)))];
84
+ } catch (e) {
85
+ die(`${file}: ${e.message}`);
86
+ }
87
+ const parents = new Map();
88
+ let missed = 0;
89
+ for (const [n, got] of ghAliasedRead(tickets, { field: "issue", selection: "{body}", timeoutMs: GH_TIMEOUT_MS })) {
90
+ if (typeof got.node?.body === "string") {
91
+ parents.set(String(n), sliceParent(got.node.body));
92
+ continue;
93
+ }
94
+ missed += 1;
95
+ process.stderr.write(`${NAME}: issue #${n} ${got.notFound ? "not found" : `unreadable (${got.unreachable ?? "no body"})`} — its rows are left as they were\n`);
96
+ }
97
+ const filled = fillParent(text, parents);
98
+ if (filled.text !== text) {
99
+ try {
100
+ writeFileSync(`${file}.tmp`, filled.text);
101
+ renameSync(`${file}.tmp`, file);
102
+ } catch (e) {
103
+ // A .tmp the rename left behind goes too; one that cannot be removed is
104
+ // overwritten by the next run, and the die message names the failure.
105
+ try { rmSync(`${file}.tmp`, { force: true }); } catch {}
106
+ die(`${file}: cannot write: ${e.message}`);
107
+ }
108
+ }
109
+ const slices = [...parents.values()].filter((p) => p !== "").length;
110
+ process.stdout.write(`${NAME}: ${file}: parent set on ${filled.set} row${filled.set === 1 ? "" : "s"}${filled.widened ? ", parent column added" : ""}; ${slices} of ${parents.size} ticket${parents.size === 1 ? "" : "s"} read are Slices\n`);
111
+ if (missed > 0) process.exitCode = 1;
112
+ }
113
+
114
+ if (isCLI(import.meta.url)) main();
@@ -9,7 +9,7 @@
9
9
  // [--chain-head] [--pending <tsv>]
10
10
  // Prints one line, the Pull's Routing (ledger-grammar.mjs owns its
11
11
  // grammar): `POLICY=<cell> CELL=<cell> DRAW=<k/K|-> BY=<burn-in|every-5th|->
12
- // STRATUM=<light|heavy|unknown> BRIEF=<chars|-> CRITERIA=<n|->
12
+ // STRATUM=<light|heavy|unknown> BRIEF=<chars|-> CRITERIA=<n|-> PARENT=<N|->
13
13
  // SIZED=<light|heavy|-> OBJECTIVE=<cost|speed> TRIPPED=<cell,…|->
14
14
  // REASON=<reason>`,
15
15
  // routing by the objective's row set, and appends the Pull's
@@ -55,7 +55,7 @@ import { CELL, OBJECTIVES, POLICY_CELL, STRATA, drawCell, formatRouting, parseMe
55
55
  import { objectiveFromReceipt, sessionFromReceipt } from "./phase0-receipt.mjs";
56
56
  import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
57
57
  import {
58
- AttributionError, FEATURE_COLUMNS, TRIP_POINTS, attribute, bootUnit, bootstrapDiffCI, generations, parseFeatures, tally, underFloor,
58
+ AttributionError, FEATURE_COLUMNS, OPTIONAL_COLUMNS, TRIP_POINTS, attribute, bootUnit, bootstrapDiffCI, generations, parseFeatures, tally, underFloor,
59
59
  } from "./pull-attribution.mjs";
60
60
  import { RulingError, parseTierOutcomes } from "./tier-outcomes.mjs";
61
61
  import { briefPaths, briefText } from "./ticket-text.mjs";
@@ -83,6 +83,32 @@ const DAY_MS = 86_400_000;
83
83
  // metrics — every one free, deterministic and known before dispatch
84
84
  // ---------------------------------------------------------------------------
85
85
 
86
+ // A Slice names its parent at the top of its issue body: `Spec: #<N>` at the
87
+ // start of the first non-blank line, or a `## Parent` section the body opens
88
+ // with, whose first issue named (`#<N>` or an issue URL) is the parent.
89
+ const SPEC_LINE = /^Spec: #([1-9][0-9]*)(?![0-9])/;
90
+ const PARENT_HEADING = /^##\s+Parent\s*$/;
91
+ const HEADING = /^#{1,6}\s/;
92
+ const ISSUE_REF = /(?:^|[^\w/&])#([1-9][0-9]*)(?![0-9])|https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/issues\/([1-9][0-9]*)(?![0-9])/;
93
+
94
+ /**
95
+ * A Slice's parent issue number off its issue body, as a string, or "" when
96
+ * the body makes no Slice. The body alone decides: a later `## Agent Brief`
97
+ * comment leaves a Slice a Slice. `Spec #<N>` with no colon, a `## Parent`
98
+ * section naming no issue and a `Part of #<N>` line make none.
99
+ */
100
+ export function sliceParent(body) {
101
+ const lines = String(body ?? "").split(/\r?\n/);
102
+ const at = lines.findIndex((l) => l.trim() !== "");
103
+ if (at === -1) return "";
104
+ const spec = SPEC_LINE.exec(lines[at]);
105
+ if (spec !== null) return spec[1];
106
+ if (!PARENT_HEADING.test(lines[at])) return "";
107
+ const end = lines.findIndex((l, i) => i > at && HEADING.test(l));
108
+ const ref = ISSUE_REF.exec(lines.slice(at + 1, end === -1 ? undefined : end).join("\n"));
109
+ return ref === null ? "" : ref[1] ?? ref[2];
110
+ }
111
+
86
112
  /** The metric columns for a parsed `gh issue view --json title,body,comments,labels,createdAt`, or null when it is not one. */
87
113
  export function issueMetrics(issue, now = Date.now()) {
88
114
  if (issue === null || typeof issue !== "object" || Array.isArray(issue) || typeof issue.body !== "string") return null;
@@ -100,12 +126,19 @@ export function issueMetrics(issue, now = Date.now()) {
100
126
  test_paths: String(paths.filter((p) => /\.test\.|(^|\/)tests?\//.test(p)).length),
101
127
  xrefs: String(new Set([...brief.matchAll(/#(\d+)/g)].map((m) => m[1])).size),
102
128
  kind,
129
+ parent: sliceParent(issue.body),
103
130
  };
104
131
  }
105
132
 
106
- /** The `rule` classifier, over a row's metric columns: blank metrics are `unknown`. */
107
- export function ruleStratum({ brief_chars, criteria }) {
133
+ /**
134
+ * The `rule` classifier, over a row's metric columns: blank metrics are
135
+ * `unknown`, a Slice (a row with a `parent`) is `heavy`, and any other row is
136
+ * `heavy` past the brief length or the criteria count. A Slice whose metrics
137
+ * are blank stays `unknown`, as it was routed: its issue was not read then.
138
+ */
139
+ export function ruleStratum({ brief_chars, criteria, parent }) {
108
140
  if (brief_chars === "" || brief_chars === undefined || criteria === "" || criteria === undefined) return "unknown";
141
+ if (parent) return "heavy";
109
142
  return Number(brief_chars) > HEAVY_BRIEF_CHARS || Number(criteria) > HEAVY_CRITERIA ? "heavy" : "light";
110
143
  }
111
144
 
@@ -219,7 +252,7 @@ export function route({ session, ticket, arm, implRow, chainHead = false, issue,
219
252
 
220
253
  const metrics = issueMetrics(issue, now);
221
254
  if (metrics === null) degrade("no-issue-json");
222
- const blank = Object.fromEntries(["brief_chars", "criteria", "comments", "age_days", "paths", "test_paths", "xrefs", "kind"].map((c) => [c, ""]));
255
+ const blank = Object.fromEntries(["brief_chars", "criteria", "comments", "age_days", "paths", "test_paths", "xrefs", "kind", "parent"].map((c) => [c, ""]));
223
256
  const m = metrics ?? blank;
224
257
  const ruleS = ruleStratum(m);
225
258
 
@@ -284,13 +317,16 @@ export function route({ session, ticket, arm, implRow, chainHead = false, issue,
284
317
  const line = formatRouting({
285
318
  policy, cell, draw, by, stratum,
286
319
  brief: metrics === null ? null : Number(metrics.brief_chars), criteria: metrics === null ? null : Number(metrics.criteria),
320
+ parent: m.parent === "" ? null : Number(m.parent),
287
321
  sized: sizingPre === "" ? null : sizingPre, objective, tripped: guard?.tripped ?? [], reason,
288
322
  });
289
323
  return { line, row };
290
324
  }
291
325
 
292
- export function formatFeatureRow(row) {
293
- return FEATURE_COLUMNS.map((c) => String(row[c] ?? "").replace(/[\t\r\n]/g, " ")).join("\t");
326
+ // `columns` is the header of the file the row joins: a pending file a run
327
+ // began before a column was added keeps its own width.
328
+ export function formatFeatureRow(row, columns = FEATURE_COLUMNS) {
329
+ return columns.map((c) => String(row[c] ?? "").replace(/[\t\r\n]/g, " ")).join("\t");
294
330
  }
295
331
 
296
332
  // ---------------------------------------------------------------------------
@@ -686,11 +722,24 @@ function main() {
686
722
  // The header decision and the append are not atomic and take no lock. That is
687
723
  // safe only while the run's controller is the only process that routes or
688
724
  // drains on a checkout, doing both serially: one controller per checkout is
689
- // the rule, and neither this append nor the drain checks it.
725
+ // the rule, and neither this append nor the drain checks it. A pending file
726
+ // already begun keeps its header's columns, so a plugin updated mid-run
727
+ // never appends a row wider or narrower than the file. A first line that is
728
+ // no features header — a required column missing, or a name no features
729
+ // file carries — is refused, not appended against.
690
730
  try {
691
731
  mkdirSync(dirname(pending), { recursive: true });
692
- const header = statSync(pending, { throwIfNoEntry: false })?.size > 0 ? "" : `${FEATURE_COLUMNS.join("\t")}\n`;
693
- appendFileSync(pending, `${header}${formatFeatureRow(row)}\n`);
732
+ const had = statSync(pending, { throwIfNoEntry: false })?.size > 0 ? readFileSync(pending, "utf8").split("\n", 1)[0].split("\t") : null;
733
+ if (had !== null) {
734
+ const missing = FEATURE_COLUMNS.filter((c) => !had.includes(c) && !OPTIONAL_COLUMNS.has(c));
735
+ const unknown = had.filter((c) => !FEATURE_COLUMNS.includes(c));
736
+ if (missing.length || unknown.length) {
737
+ const why = [missing.length ? `lacks ${missing.join(", ")}` : "", unknown.length ? `names ${unknown.map((c) => JSON.stringify(c)).join(", ")}` : ""];
738
+ throw new Error(`its first line is no ticket-features header: it ${why.filter(Boolean).join(" and ")}`);
739
+ }
740
+ }
741
+ const header = had === null ? `${FEATURE_COLUMNS.join("\t")}\n` : "";
742
+ appendFileSync(pending, `${header}${formatFeatureRow(row, had ?? FEATURE_COLUMNS)}\n`);
694
743
  } catch (e) {
695
744
  process.stderr.write(`${NAME}: WARNING could not append to ${pending}: ${e.message} — this Pull's ticket-features row is not recorded\n`);
696
745
  }
@@ -251,7 +251,7 @@ terminating in exactly one dispatch or an empty shortlist:
251
251
  7. **Route, row, then dispatch** — `~/.fleet/bin/fleet-run ticket-router.mjs route
252
252
  --session <session> --ticket <N> --arm <A|B> --impl-row <k>[ --chain-head] --issue
253
253
  <scratch>/impl-<N>/issue.json --guard .fleet/cost-guard.json` prints the Pull's
254
- Routing, `POLICY=… CELL=… DRAW=… BY=… STRATUM=… BRIEF=… CRITERIA=… SIZED=… OBJECTIVE=… TRIPPED=… REASON=…`
254
+ Routing, `POLICY=… CELL=… DRAW=… BY=… STRATUM=… BRIEF=… CRITERIA=… PARENT=… SIZED=… OBJECTIVE=… TRIPPED=… REASON=…`
255
255
  (the router's arguments paragraph below the list says what each argument is);
256
256
  then `ledger.mjs row <N> "impl-<N>[ · tier=<CELL>]" --routing "<that line>"`,
257
257
  `tier=<CELL>` exactly when `DRAW` is not `-`, which writes the row and files