rungate 0.8.14 → 0.8.16

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 (72) hide show
  1. package/README.md +105 -5
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/HarnessAFKGate.hook.ts +5 -1
  4. package/hooks/HookCurrency.hook.ts +11 -8
  5. package/hooks/MergeGuard.hook.ts +7 -1
  6. package/hooks/StaleTTLCleanup.hook.ts +4 -4
  7. package/hooks/lib/findWorkflow.ts +3 -2
  8. package/hooks/lib/paths.ts +14 -2
  9. package/hooks/lib/utils.ts +23 -3
  10. package/lib/active-milestone.ts +50 -0
  11. package/lib/bash-write-guard.ts +347 -18
  12. package/lib/board-flow.ts +45 -0
  13. package/lib/board-lane-health.ts +198 -1
  14. package/lib/board-mirror.ts +83 -4
  15. package/lib/board-ready-fanout.ts +242 -2
  16. package/lib/board-ready-rule.ts +742 -76
  17. package/lib/bun-version.ts +36 -0
  18. package/lib/cli-commands.ts +75 -4
  19. package/lib/closing-reference-audit.ts +307 -6
  20. package/lib/config-loader.ts +254 -25
  21. package/lib/config-readers.ts +170 -10
  22. package/lib/config-trackable.ts +96 -57
  23. package/lib/conformity.ts +26 -5
  24. package/lib/create-sc.ts +25 -2
  25. package/lib/derived-spec.ts +21 -9
  26. package/lib/filing-plan.ts +47 -21
  27. package/lib/finding-jury.ts +43 -4
  28. package/lib/finding-promotion.ts +1123 -0
  29. package/lib/git-isolation.ts +137 -1
  30. package/lib/github-api-base.ts +66 -0
  31. package/lib/github.ts +115 -9
  32. package/lib/hook-scopes.ts +78 -0
  33. package/lib/issue-decomposition.ts +91 -4
  34. package/lib/issue-extraction.ts +9 -7
  35. package/lib/issue-file-overlap.ts +42 -9
  36. package/lib/issue-filing-gate.ts +938 -46
  37. package/lib/issue-repair.ts +77 -0
  38. package/lib/issue-shape.ts +8 -5
  39. package/lib/live-issues.ts +31 -2
  40. package/lib/local-work.ts +423 -0
  41. package/lib/markdown-fence.ts +134 -0
  42. package/lib/milestone-title.ts +46 -0
  43. package/lib/scaffold/ai-review-findings.ts +139 -2
  44. package/lib/scaffold/ai-review-step.ts +30 -4
  45. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  46. package/lib/scaffold/steps.ts +115 -9
  47. package/lib/spec-deps.ts +24 -3
  48. package/lib/spec-placement.ts +96 -14
  49. package/lib/spec-registry.ts +75 -16
  50. package/lib/spec-source.ts +609 -0
  51. package/lib/spec-write-sweep.ts +4 -0
  52. package/lib/stage-ladder.ts +868 -0
  53. package/lib/state-claim-readings.ts +252 -0
  54. package/lib/success-doc.ts +7 -6
  55. package/lib/test-command-positions.ts +135 -1
  56. package/lib/work-status.ts +210 -82
  57. package/lib/worktree-repo.ts +14 -2
  58. package/package.json +7 -1
  59. package/scripts/audit-closing-references.ts +330 -0
  60. package/scripts/audit-specs.ts +59 -103
  61. package/scripts/board-conformance.ts +747 -40
  62. package/scripts/board-mirror.ts +408 -40
  63. package/scripts/board-ready.ts +979 -0
  64. package/scripts/board-snapshot.ts +464 -12
  65. package/scripts/claim-files.ts +578 -0
  66. package/scripts/criterion-inventory.ts +526 -50
  67. package/scripts/finding-promotion.ts +547 -0
  68. package/scripts/plan-issues.ts +279 -40
  69. package/scripts/plan-spec.ts +49 -25
  70. package/scripts/sync-sc-status.ts +147 -7
  71. package/scripts/worktree-census.ts +958 -0
  72. package/scripts/worktree-sweep.ts +269 -0
@@ -868,6 +868,13 @@ export function stripHeredocs(s: string, blankComments = true): string {
868
868
  if (looksComment) continue;
869
869
  const delim = heredocDelimiter(line);
870
870
  if (!delim) continue;
871
+ // #1355: the rest of a CONTINUED opener line is command, not body. The
872
+ // body starts after the logical line, which is where the shell starts it.
873
+ // A `#` line among them is a comment once the shell joins it, and gets
874
+ // the same #1176 blanking as any other (review round 2 of PR #2077).
875
+ for (const end = logicalEnd(lines, i - 1); i <= end; i++) {
876
+ out.push(/^\s*#/.test(lines[i]) && blankComments ? '' : lines[i]);
877
+ }
871
878
  // #1184: buffer the body rather than consuming to end-of-input. A
872
879
  // heredoc whose terminator never arrives is not a heredoc this module can
873
880
  // trust, and dropping the rest of the command is a BYPASS — `cat <<EOF`
@@ -958,13 +965,305 @@ function unquotedPositions(line: string): boolean[] {
958
965
  * wrong character position (`<<<`); this is the wrong quoting position.
959
966
  */
960
967
  function heredocDelimiter(line: string): string | null {
968
+ return heredocOperator(line)?.delim ?? null;
969
+ }
970
+
971
+ /** `heredocDelimiter`, and where on the line its operator sits (#1355). */
972
+ function heredocOperator(line: string): { delim: string; at: number } | null {
961
973
  // #1184: `(?<!<)` and `(?!<)` exclude a `<<<` HERESTRING, which has no
962
974
  // terminator at all. Matching one invented a delimiter from the quoted text
963
975
  // after it and then ran straight into the unterminated case above.
964
976
  const re = /(?<!<)<<(?!<)-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
965
977
  const open = unquotedPositions(line);
966
978
  for (let m = re.exec(line); m; m = re.exec(line)) {
967
- if (open[m.index]) return m[2];
979
+ if (open[m.index]) return { delim: m[2], at: m.index };
980
+ }
981
+ return null;
982
+ }
983
+
984
+ /**
985
+ * Does this physical line continue onto the next (#1355)?
986
+ *
987
+ * An unquoted backslash immediately before the newline is a line
988
+ * continuation: the shell deletes the pair and reads on, so a heredoc's
989
+ * opener line ends further down than its newline, and its BODY starts after
990
+ * the logical line rather than after the physical one. `cat <<'EOF' \⏎| bash`
991
+ * pipes the body into a shell; reading the `| bash` line as the first line of
992
+ * the body deleted it from every view.
993
+ *
994
+ * An even run of backslashes is escaped backslashes, and a backslash inside
995
+ * a quote or a comment is data.
996
+ */
997
+ function continues(line: string): boolean {
998
+ const run = /\\+$/.exec(line);
999
+ if (!run || run[0].length % 2 === 0) return false;
1000
+ const text = line.slice(0, -1) + ' ';
1001
+ const open = unquotedPositions(text);
1002
+ if (!open[text.length - 1]) return false;
1003
+ for (let k = 0; k < text.length; k++) {
1004
+ if (open[k] && opensComment(text, k)) return false;
1005
+ }
1006
+ return true;
1007
+ }
1008
+
1009
+ /**
1010
+ * Does an unquoted `text[k]` open a comment? A `#` does when it begins a
1011
+ * word — after whitespace OR an operator, so `;#` is a comment too.
1012
+ *
1013
+ * One predicate for `continues` and `nest` (review of PR #2077): with two
1014
+ * copies, the narrower one read the backslash in `bash <<'EOF' ;# note \`
1015
+ * as a continuation and swallowed the body's first line as opener text.
1016
+ */
1017
+ function opensComment(text: string, k: number): boolean {
1018
+ return text[k] === '#' && (k === 0 || /[\s;&|()]/.test(text[k - 1]));
1019
+ }
1020
+
1021
+ /** The last physical line of the logical line that starts at line `i`. */
1022
+ function logicalEnd(lines: string[], i: number): number {
1023
+ let end = i;
1024
+ while (end + 1 < lines.length && continues(lines[end])) end++;
1025
+ return end;
1026
+ }
1027
+
1028
+ /** One level of shell nesting open at a position, and where it opened. */
1029
+ interface Frame {
1030
+ close: string;
1031
+ open: number;
1032
+ /** A command substitution or process substitution: its OUTPUT is an argument. */
1033
+ subst: boolean;
1034
+ }
1035
+
1036
+ const QUOTE_CLOSERS = new Set(["'", '"']);
1037
+
1038
+ /**
1039
+ * Advance a nesting reading over `text[i]`; returns the next index (#1355).
1040
+ *
1041
+ * Quotes, `$( )` / `<( )` / `>( )` and backticks, subshells and brace groups.
1042
+ * The minimum the reach question needs — where does the group this heredoc
1043
+ * sits in END — and deliberately nothing else: keywords such as `if`/`fi`
1044
+ * are not groups here, so a heredoc inside one reaches no further than it
1045
+ * did before. Its failure mode is a group that never closes, which reaches
1046
+ * nothing, so a misreading costs a missed reach and never a new refusal.
1047
+ */
1048
+ function nest(text: string, i: number, stack: Frame[]): number {
1049
+ const c = text[i];
1050
+ const top = stack[stack.length - 1];
1051
+ if (top?.close === "'") {
1052
+ if (c === "'") stack.pop();
1053
+ return i + 1;
1054
+ }
1055
+ if (c === '\\') return i + 2;
1056
+ if (top?.close === '"' || top?.close === '`') {
1057
+ if (c === top.close) stack.pop();
1058
+ else if (c === '$' && text[i + 1] === '(') {
1059
+ stack.push({ close: ')', open: i + 1, subst: true });
1060
+ return i + 2;
1061
+ } else if (c === '`') stack.push({ close: '`', open: i, subst: true });
1062
+ return i + 1;
1063
+ }
1064
+ const wordStart = i === 0 || /[\s;&|()]/.test(text[i - 1]);
1065
+ if (opensComment(text, i)) {
1066
+ const nl = text.indexOf('\n', i);
1067
+ return nl === -1 ? text.length : nl;
1068
+ }
1069
+ if (c === "'" || c === '"' || c === '`') stack.push({ close: c, open: i, subst: c === '`' });
1070
+ else if (c === '(') stack.push({ close: ')', open: i, subst: /[$<>]/.test(text[i - 1] ?? '') });
1071
+ else if (c === ')' && top?.close === ')') stack.pop();
1072
+ else if (c === '{' && wordStart && /\s/.test(text[i + 1] ?? '')) stack.push({ close: '}', open: i, subst: false });
1073
+ else if (c === '}' && wordStart && top?.close === '}') stack.pop();
1074
+ return i + 1;
1075
+ }
1076
+
1077
+ /**
1078
+ * One element of a pipeline: its raw text, for the command word, and `flat`,
1079
+ * the part at the pipeline's own depth with quotes, nested groups, escapes
1080
+ * and comments blanked, for its redirections.
1081
+ */
1082
+ interface Element {
1083
+ raw: string;
1084
+ flat: string;
1085
+ }
1086
+
1087
+ /** Is this the separator that ends a pipeline element at `text[i]`? */
1088
+ function endsElement(text: string, i: number): boolean {
1089
+ const c = text[i];
1090
+ const redirect = text[i - 1] === '>' || text[i + 1] === '>';
1091
+ return c === '\n' || c === ';' || c === '|' || (c === '&' && !redirect);
1092
+ }
1093
+
1094
+ /**
1095
+ * The elements of the pipeline starting at `i`, at the depth `frames`
1096
+ * describe — `) > f | sed … | bash`. It ends at `;`, `&&`, `||`, `&`, a
1097
+ * newline, or the close of an outer group. Reads a COPY of the nesting, so
1098
+ * the caller's cursor is not moved.
1099
+ */
1100
+ function pipeline(text: string, i: number, frames: Frame[]): Element[] {
1101
+ const stack = frames.slice();
1102
+ const base = stack.length;
1103
+ const out: Element[] = [];
1104
+ let from = i;
1105
+ let flat = '';
1106
+ while (i < text.length && stack.length >= base) {
1107
+ if (stack.length === base && endsElement(text, i)) {
1108
+ if (text[i] !== '|' || text[i + 1] === '|') break;
1109
+ out.push({ raw: text.slice(from, i), flat });
1110
+ from = text[i + 1] === '&' ? i + 2 : i + 1;
1111
+ flat = '';
1112
+ i = from;
1113
+ continue;
1114
+ }
1115
+ const depth = stack.length;
1116
+ const next = nest(text, i, stack);
1117
+ if (depth === base && stack.length === base) {
1118
+ const inert = text[i] === '\\' || opensComment(text, i);
1119
+ flat += inert ? ' '.repeat(next - i) : text.slice(i, next);
1120
+ } else if (depth === base && stack.length > base && text[i] === '(' && /[<>]/.test(text[i - 1] ?? '')) {
1121
+ flat = flat.slice(0, -1) + ' '; // `>(…)` is a process substitution, not a redirect
1122
+ }
1123
+ i = next;
1124
+ }
1125
+ out.push({ raw: text.slice(from, i), flat });
1126
+ return out;
1127
+ }
1128
+
1129
+ /**
1130
+ * Does this element send its standard output somewhere other than the pipe?
1131
+ * `>`, `>>`, `>|`, `1>`, `&>` and `>&N` do. `2>` and `2>&1` move another
1132
+ * descriptor and leave stdout where it was.
1133
+ */
1134
+ function redirectsStdout(flat: string): boolean {
1135
+ for (let j = 0; j < flat.length; j++) {
1136
+ if (flat[j] !== '>' || flat[j - 1] === '>' || flat[j - 1] === '<') continue;
1137
+ const fd = /\d*$/.exec(flat.slice(0, j))![0];
1138
+ if (fd === '' || fd === '1') return true;
1139
+ }
1140
+ return false;
1141
+ }
1142
+
1143
+ /**
1144
+ * Where a pipeline sends what enters its first element: the interpreter it
1145
+ * reaches, `null` when a stdout redirection severs it first, or `undefined`
1146
+ * when it flows on into the enclosing group's output.
1147
+ *
1148
+ * `own` is the heredoc's OWN pipeline, whose interpreters are
1149
+ * `heredocInterpreter`'s question; here it can only be severed (review
1150
+ * round 2 of PR #2077: `(cat <<'EOF' > x.md … ) | bash` hands `bash`
1151
+ * nothing, because the body went to the file).
1152
+ */
1153
+ function flow(elements: Element[], own: boolean): string | null | undefined {
1154
+ for (let k = 0; k < elements.length; k++) {
1155
+ if (k > 0 && !own) {
1156
+ const word = commandWord(elements[k].raw);
1157
+ if (isInterpreterWord(word)) return word;
1158
+ }
1159
+ if (redirectsStdout(elements[k].flat)) return null;
1160
+ }
1161
+ return undefined;
1162
+ }
1163
+
1164
+ /** Where the heredoc's own command begins: after the last separator at its depth. */
1165
+ function elementStart(text: string, at: number, frames: Frame[]): number {
1166
+ const stack = frames.slice();
1167
+ const base = stack.length;
1168
+ let i = base > 0 ? frames[base - 1].open + 1 : 0;
1169
+ let start = i;
1170
+ while (i < at) {
1171
+ if (stack.length === base && endsElement(text, i)) {
1172
+ start = ++i;
1173
+ continue;
1174
+ }
1175
+ i = nest(text, i, stack);
1176
+ }
1177
+ return start;
1178
+ }
1179
+
1180
+ /**
1181
+ * The command word of the command a substitution opened at `open` belongs to:
1182
+ * the text back to the enclosing command frame, or to the start of the
1183
+ * logical line, whichever is nearer.
1184
+ */
1185
+ function enclosingWord(text: string, open: number, outer: Frame | undefined): string {
1186
+ let start = text.lastIndexOf('\n', open - 1) + 1;
1187
+ while (start > 0) {
1188
+ const prev = text.lastIndexOf('\n', start - 2) + 1;
1189
+ if (!continues(text.slice(prev, start - 1))) break;
1190
+ start = prev;
1191
+ }
1192
+ if (outer && outer.open + 1 > start) start = outer.open + 1;
1193
+ const segs = segments(text.slice(start, open));
1194
+ return commandWord(segs[segs.length - 1] ?? '');
1195
+ }
1196
+
1197
+ /** A word that runs its argument as shell text, without being an interpreter. */
1198
+ const EVALUATORS = new Set(['eval']);
1199
+
1200
+ /**
1201
+ * Words that run a FILE as shell text in the current shell (#2079). Handed a
1202
+ * process substitution `<(…)`, the file IS the substitution's output, so a
1203
+ * heredoc inside it is a program. Handed `$(…)`, the output is only a file
1204
+ * NAME, so these are not evaluators there.
1205
+ */
1206
+ const SOURCERS = new Set(['source', '.']);
1207
+
1208
+ /**
1209
+ * Where a heredoc's ENCLOSING groups send its body (#1355, SC-2750).
1210
+ *
1211
+ * `text` is the whole command with every terminated heredoc body removed, so
1212
+ * what follows the operator is what the shell resumes reading after the
1213
+ * terminator, and `at` is the operator's offset in it. The opener line alone
1214
+ * cannot answer this: in
1215
+ *
1216
+ * (cat <<'EOF' { cat <<'EOF' eval "$(cat <<'EOF'
1217
+ * … … …
1218
+ * EOF EOF EOF
1219
+ * ) | bash } | bash )"
1220
+ *
1221
+ * the interpreter is on a line after the body. Each group open at the
1222
+ * operator is walked outward in turn: a subshell or brace group reaches an
1223
+ * interpreter when its close is piped into one, and a substitution when the
1224
+ * command it is an argument of is an interpreter or `eval`. A stdout
1225
+ * redirection on the way — on the heredoc's own command or on a group —
1226
+ * severs the body from everything outside it, and the walk stops there.
1227
+ *
1228
+ * Only the ENCLOSING groups, never the heredoc's own command line, which
1229
+ * `heredocInterpreter` already decides — so no spelling is decided twice by
1230
+ * two rules that could drift apart without either going red.
1231
+ */
1232
+ function heredocReach(text: string, at: number): string | null {
1233
+ const stack: Frame[] = [];
1234
+ let i = 0;
1235
+ while (i < at) i = nest(text, i, stack);
1236
+ // The operator was read as unquoted by `heredocOperator`. A reading that
1237
+ // places it inside a quote disagrees with that one, and a reading that
1238
+ // disagrees is not one to widen anything on.
1239
+ if (stack.length > 0 && QUOTE_CLOSERS.has(stack[stack.length - 1].close)) return null;
1240
+ const frames = stack.slice();
1241
+ const ownElements = pipeline(text, elementStart(text, at, frames), frames);
1242
+ // #2079: the heredoc belongs to the INNERMOST command that owns the `<<`,
1243
+ // not to whatever the line starts with. `X=$(bash <<'EOF'` feeds `bash`,
1244
+ // and so does `T=$(echo x 2>&1) bash <<'EOF'`, whose `&` the line-start
1245
+ // reading splits on. `heredocInterpreter` reads from the line start and
1246
+ // decides first, so this is reached only when it found nothing, and no
1247
+ // spelling is decided twice. Before the sever check, because an
1248
+ // interpreter runs its stdin wherever its own stdout goes.
1249
+ const owner = commandWord(ownElements[0]?.raw ?? '');
1250
+ if (isInterpreterWord(owner)) return owner;
1251
+ const own = flow(ownElements, true);
1252
+ if (own !== undefined) return own;
1253
+ for (let level = frames.length; level > 0; level--) {
1254
+ while (i < text.length && stack.length >= level) i = nest(text, i, stack);
1255
+ if (stack.length >= level) return null; // never closed, so nothing follows it
1256
+ const frame = frames[level - 1];
1257
+ if (QUOTE_CLOSERS.has(frame.close)) continue;
1258
+ if (frame.subst) {
1259
+ const outer = frames.slice(0, level - 1).reverse().find(f => !QUOTE_CLOSERS.has(f.close));
1260
+ const word = enclosingWord(text, frame.open, outer);
1261
+ if (isInterpreterWord(word) || EVALUATORS.has(word)) return word;
1262
+ if (SOURCERS.has(word) && text[frame.open - 1] === '<') return word;
1263
+ } else {
1264
+ const word = flow(pipeline(text, i, stack), false);
1265
+ if (word !== undefined) return word;
1266
+ }
968
1267
  }
969
1268
  return null;
970
1269
  }
@@ -979,6 +1278,10 @@ function heredocDelimiter(line: string): string | null {
979
1278
  * those bodies is what stopped 1,860 real commands from being refused for
980
1279
  * quoting the words this guard looks for. That distinction is the whole
981
1280
  * reason this is a predicate rather than "stop stripping heredocs".
1281
+ *
1282
+ * #1355: `line` is the LOGICAL opener line, continuations joined. What lies
1283
+ * beyond it — a group closing after the body, a substitution handed to
1284
+ * `eval` — is `heredocReach`'s question, not this one's.
982
1285
  */
983
1286
  function heredocInterpreter(line: string): string | null {
984
1287
  const segs = segments(line);
@@ -1002,15 +1305,30 @@ function heredocInterpreter(line: string): string | null {
1002
1305
  * those lines unchanged — the #1184 fail-closed direction — so every arm
1003
1306
  * can already see them, and returning them again would double-count a body
1004
1307
  * that is not hidden in the first place.
1308
+ *
1309
+ * #1355: a heredoc is decided once the WHOLE command has been read, because
1310
+ * the group it sits in can close — and be piped into a shell — lines after
1311
+ * its body ends. `skeleton` is the command as the shell parses it around the
1312
+ * bodies; `heredocReach` reads it.
1005
1313
  */
1006
1314
  export function interpreterPrograms(cmd: string): Array<{ shell: boolean; program: string }> {
1007
- const out: Array<{ shell: boolean; program: string }> = [];
1315
+ type Pending = { opener: string; at: number; body: string };
1316
+ const found: Array<{ shell: boolean; program: string } | Pending> = [];
1008
1317
  const lines = cmd.split('\n');
1318
+ const skeleton: string[] = [];
1319
+ let offset = 0; // where the next skeleton line starts in `skeleton.join('\n')`
1320
+ const keep = (l: string): void => {
1321
+ skeleton.push(l);
1322
+ offset += l.length + 1;
1323
+ };
1009
1324
  let i = 0;
1010
1325
  while (i < lines.length) {
1011
1326
  const line = lines[i];
1012
- i++;
1013
- if (/^\s*#/.test(line)) continue; // a comment cannot open either form
1327
+ if (/^\s*#/.test(line)) {
1328
+ keep(line);
1329
+ i++;
1330
+ continue; // a comment cannot open either form
1331
+ }
1014
1332
 
1015
1333
  // A HERESTRING has no body and no terminator, which is why
1016
1334
  // `heredocDelimiter` excludes it (#1184). It is still a program, and it
@@ -1021,25 +1339,36 @@ export function interpreterPrograms(cmd: string): Array<{ shell: boolean; progra
1021
1339
  const owner = segments(line).find(s => /(?<!<)<<<(?!<)/.test(s));
1022
1340
  const word = owner ? commandWord(owner) : '';
1023
1341
  if (isInterpreterWord(word)) {
1024
- out.push({ shell: isShellWord(word), program: dequote(hs[1]).trim() });
1342
+ found.push({ shell: isShellWord(word), program: dequote(hs[1]).trim() });
1025
1343
  }
1026
1344
  }
1027
1345
 
1028
- const delim = heredocDelimiter(line);
1029
- if (!delim) continue;
1030
- const body: string[] = [];
1031
- let j = i;
1032
- while (j < lines.length && lines[j].trim() !== delim) {
1033
- body.push(lines[j]);
1034
- j++;
1346
+ const op = heredocOperator(line);
1347
+ if (!op) {
1348
+ keep(line);
1349
+ i++;
1350
+ continue;
1035
1351
  }
1036
- if (j < lines.length) {
1037
- const word = heredocInterpreter(line);
1038
- if (word) out.push({ shell: isShellWord(word), program: body.join('\n') });
1039
- i = j + 1;
1040
- } else {
1041
- i = j; // unterminated: already visible, see the docblock
1352
+ const at = offset + op.at;
1353
+ const end = logicalEnd(lines, i);
1354
+ for (let k = i; k <= end; k++) keep(lines[k]);
1355
+ const body: string[] = [];
1356
+ let j = end + 1;
1357
+ while (j < lines.length && lines[j].trim() !== op.delim) body.push(lines[j++]);
1358
+ if (j === lines.length) break; // unterminated: already visible, see the docblock
1359
+ found.push({ opener: lines.slice(i, end + 1).join('\n'), at, body: body.join('\n') });
1360
+ i = j + 1;
1361
+ }
1362
+
1363
+ const text = skeleton.join('\n');
1364
+ const out: Array<{ shell: boolean; program: string }> = [];
1365
+ for (const f of found) {
1366
+ if (!('opener' in f)) {
1367
+ out.push(f);
1368
+ continue;
1042
1369
  }
1370
+ const word = heredocInterpreter(f.opener) ?? heredocReach(text, f.at);
1371
+ if (word) out.push({ shell: isShellWord(word) || EVALUATORS.has(word) || SOURCERS.has(word), program: f.body });
1043
1372
  }
1044
1373
  return out.filter(p => p.program !== '');
1045
1374
  }
package/lib/board-flow.ts CHANGED
@@ -60,8 +60,47 @@ export const LANE_EVENTS = [
60
60
  "issue_reopened",
61
61
  "pr_ready",
62
62
  "pr_closed_unmerged",
63
+ // Not a GitHub webhook action. `blocked_by_added` reaches the REST
64
+ // timeline and emits no `issues` event at all — measured on #1495, where
65
+ // the edge landed at 02:01:08Z and zero workflow runs started, against
66
+ // four unfiltered `issues` subscribers that would have fired (#1929). So
67
+ // the event is `board-ready`'s own walk noticing an incumbent that no
68
+ // longer meets Ready's entry condition. It is spelled `issue_` because it
69
+ // is about one issue and authorises one identity, like the rest.
70
+ "issue_blocked_in_ready",
63
71
  ] as const;
64
72
 
73
+ /**
74
+ * The subset `scripts/board-flow.ts` may be handed on `--event`.
75
+ *
76
+ * **`LANE_EVENTS` stopped being one list the moment a derived kind joined
77
+ * it** (#1929, ai-review round 1). Every other kind is a webhook action: the
78
+ * event IS the evidence, and `board-flow.ts` can write the lane `laneFor`
79
+ * returns after checking only the actor's permission.
80
+ * `issue_blocked_in_ready` is not. It means *my caller has already verified
81
+ * the card is in Ready, open, and has a live blocker* — three conditions
82
+ * `incumbentDecisions` checks and `board-flow.ts` does not. Validating
83
+ * `--event` against the full list made `--event issue_blocked_in_ready
84
+ * --issue N` demote any issue to Backlog with none of them performed.
85
+ *
86
+ * Unreachable through the wired automation today, because
87
+ * `.github/workflows/board-flow.yml`'s case statement emits only the real
88
+ * webhook kinds. That is why it is worth closing now rather than later: the
89
+ * cost is a derived list, and the thing it prevents is a future trigger, a
90
+ * `workflow_dispatch`, or a copied case statement quietly skipping the
91
+ * verification this feature exists to provide.
92
+ *
93
+ * Derived by subtraction, not written out. A second hand-written list would
94
+ * agree with this one on every input anybody tests, and adding a kind to
95
+ * `LANE_EVENTS` would silently leave it out of both.
96
+ */
97
+ export const DERIVED_LANE_EVENTS = ["issue_blocked_in_ready"] as const;
98
+
99
+ export const WEBHOOK_LANE_EVENTS = LANE_EVENTS.filter(
100
+ (e): e is Exclude<(typeof LANE_EVENTS)[number], (typeof DERIVED_LANE_EVENTS)[number]> =>
101
+ !(DERIVED_LANE_EVENTS as readonly string[]).includes(e),
102
+ );
103
+
65
104
  export interface LaneEvent {
66
105
  readonly kind: (typeof LANE_EVENTS)[number];
67
106
  /**
@@ -192,6 +231,12 @@ export function laneFor(e: LaneEvent): LaneDecision {
192
231
 
193
232
  case "issue_reopened":
194
233
  case "pr_closed_unmerged":
234
+ // A card in Ready that has acquired an open blocker is moving backwards
235
+ // for the same reason the two above are: Ready's entry condition is a
236
+ // claim about the blocker graph, and that claim is now false. It shares
237
+ // their answer rather than carrying its own, so there is one rule for
238
+ // everything that goes backwards and one site to mutate (#1929).
239
+ case "issue_blocked_in_ready":
195
240
  // **One rule for everything that goes backwards.** An item that went
196
241
  // backwards has a blocker graph nobody has re-checked, and Ready's
197
242
  // entry condition is precisely a claim about that graph — so going