rungate 0.8.20 → 0.8.22

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.
@@ -30,7 +30,12 @@
30
30
  * add step with a warning and no item id, and the move step's `if:` skips on
31
31
  * the empty id (`.claude/rules/config-access.md`). Any other failure stands.
32
32
  *
33
- * ## What the move step keeps, each piece asserted in test/board-intake.test.ts
33
+ * ## What the move step keeps
34
+ *
35
+ * Since #2183 the step is one call to `rungate board-intake-move`
36
+ * (`lib/board-intake-move.ts`, #2193); the retry, the read-backs, the
37
+ * truncation and null-node refusals below are that code's, each tested in
38
+ * test/board-intake-move.test.ts. This file keeps the step's shape:
34
39
  *
35
40
  * - It owns only the opened -> In review edge. `merged -> Done` and
36
41
  * `closed -> Done` stay with GitHub's built-in workflows, so each
@@ -38,13 +43,10 @@
38
43
  * - Drafts are not moved (BI-2): Jason's call, 2026-11-04.
39
44
  * - It keys off the item the add step created (BI-1), never a re-query, which
40
45
  * would race the built-in "Item added to project" workflow.
41
- * - Every call goes through one retrying helper (BI-7), whose value is stdout
42
- * only (BI-8). Every write is read back from the item AND from the project's
43
- * search index, which is what the board draws from (BI-6, BI-9). Every paged
44
- * read reports truncation instead of reading a full page as absence (BI-10),
45
- * and every `node(id:)` refuses a null node by naming the id (BI-11).
46
- * - No `${{ }}` inside a `run:` block (BI-4), and the one scratch file is
47
- * removed on exit (BI-12).
46
+ * - Every call is retried, every write is read back from the item AND from the
47
+ * project's search index, a full page is never read as absence, and a null
48
+ * or wrong-type node is refused by naming the id: in the command.
49
+ * - No `${{ }}` inside a `run:` block (BI-4), and no scratch file (BI-12).
48
50
  * - The field and option are resolved by NAME at run time, so a renamed
49
51
  * column fails loudly rather than writing a stale id.
50
52
  *
@@ -113,278 +115,21 @@ echo "projectId=\${project}" >> "\${GITHUB_OUTPUT}"
113
115
  `;
114
116
  }
115
117
 
118
+ /** The CLI command the move step runs (#2193, #2183). */
119
+ export const BOARD_INTAKE_MOVE_COMMAND = "board-intake-move";
120
+
116
121
  /**
117
- * The move step's `run:` body, carried verbatim from the hand-written file
118
- * (#2166). PROJECT_ID now comes from the add step's output rather than a
119
- * pasted id; nothing in this text changed.
122
+ * The move step's `run:` body: one call to the tested command. Its 260 lines
123
+ * of shell are now `lib/board-intake-move.ts`, and each refusal is observed
124
+ * failing against a stub client in `test/board-intake-move.test.ts`. Values
125
+ * arrive through `env:`, never interpolated into this block (BI-4).
126
+ * Exported so a test reads THIS text.
120
127
  */
121
- export const BOARD_INTAKE_MOVE_SCRIPT = `set -euo pipefail
122
-
123
- # EVERY API CALL GOES THROUGH HERE, and the reason is \`set -e\`.
124
- # A bare \`gh api graphql\` that fails on a network blip, a secondary
125
- # rate limit or a momentary 5xx aborts this step instantly with gh's
126
- # raw error: the retry loop below is never reached and none of the
127
- # diagnostics in this script ever print. The loop would then be
128
- # guarding the race it was written for and nothing else.
129
- #
130
- # Three calls had that exposure, not the one that was reported —
131
- # resolving the field, mutating, and reading back — so it is fixed
132
- # as a population and \`test/board-intake.test.ts\` BI-7 asserts no
133
- # bare \`gh api graphql\` survives anywhere in this step.
134
- #
135
- # STDERR GOES TO A FILE, NOT INTO THE RETURN VALUE. An earlier
136
- # revision captured \`2>&1\`, which is right for the failure path —
137
- # \${out} is quoted into the ::error — and wrong for the success
138
- # path, because the same \${out} is what callers parse. \`gh\` writes
139
- # to stderr on calls that SUCCEED: the update notifier, rate-limit
140
- # warnings. Two of the three call sites treat the result as data,
141
- # and the read-back is the dangerous one. A comparison against
142
- # "\${COLUMN}" that is polluted by a one-line warning simply stops
143
- # matching, so the loop logs "a concurrent write won" for a race
144
- # that never happened and then blames a competing writer for a
145
- # dirty capture — the right exit code reporting the wrong
146
- # mechanism (\`.claude/rules/checks-must-be-able-to-fail.md\`, the
147
- # sixth shape).
148
- #
149
- # Setting GH_NO_UPDATE_NOTIFIER would silence the one warning that
150
- # was named and leave the class open, so it is not the fix.
151
- err=$(mktemp)
152
- # A trap, not a trailing \`rm\`. Every refusal below exits the step
153
- # early, so a cleanup line at the bottom runs on exactly the path
154
- # that did not need it. Asserted by BI-12.
155
- trap 'rm -f "\${err}"' EXIT
156
- gql() {
157
- local out attempt
158
- for attempt in 1 2 3; do
159
- if out=$(gh api graphql "$@" 2>"\${err}"); then
160
- printf '%s' "\${out}"
161
- return 0
162
- fi
163
- sleep $(( attempt * 2 ))
164
- done
165
- echo "::error title=Board intake::GitHub's GraphQL API failed three times. The item may or may not be on the board and its Status is UNKNOWN — this run measured nothing. Last error: $(< "\${err}")" >&2
166
- return 1
167
- }
168
-
169
- # \`node(id: ID!)\` IS NULLABLE, and a null node is an id that did not
170
- # resolve rather than an empty reading. A stale id, a wrong
171
- # PROJECT_ID, or a project this token lost access to returns
172
- # \`{"data":{"node":null}}\` with NO GraphQL error, so \`gql\` exits 0
173
- # and \`--jq '.data.node.X'\` prints the four bytes \`null\`.
174
- #
175
- # What that does downstream, measured:
176
- #
177
- # jq '.data.node.fields' on a null node -> null, exit 0
178
- # jq -r '[.nodes[] | …]' on \`null\` -> exit 5
179
- # jq -r '.pageInfo.hasNextPage' on \`null\` -> null, exit 0
180
- #
181
- # So \`set -euo pipefail\` does kill the job rather than write the
182
- # wrong column — but it dies on jq's "Cannot iterate over null",
183
- # naming jq and not the id, and the truncation guard above compares
184
- # the string \`null\` against \`true\` and stays silent. Right exit
185
- # code, unreadable cause, which is this workflow's own subject one
186
- # layer down. BI-11 asserts it over all three reads.
187
- require_node() {
188
- if [ -z "$2" ] || [ "$2" = "null" ]; then
189
- echo "::error title=Board intake::\${1} is UNMEASURED and nothing was written: node(id: \${3}) came back null, so that id did not resolve — it is stale, it names an object this token cannot see, or PROJECT_ID is wrong. This is NOT a missing field, NOT an unset column and NOT an empty board." >&2
190
- exit 1
191
- fi
192
- }
193
-
194
- # An empty item id means the add step did not produce one. Writing a
195
- # field against "" returns a confusing NOT_FOUND about the project,
196
- # so say which half actually failed.
197
- if [ -z "\${ITEM_ID}" ]; then
198
- echo "::error title=Board intake::The add step produced no itemId, so there is nothing to move. The item was NOT added and its Status is UNSET — this is not a board that merely missed a transition." >&2
199
- exit 1
200
- fi
201
-
202
- # A TRUNCATED PAGE IS NOT AN ABSENT VALUE, and this step asked three
203
- # connections for a FIRST page and then read "not in it" as "not
204
- # there" at all three. Every one of them had the same consequence:
205
- # a confident error message naming a cause that did not happen.
206
- #
207
- # Found in review round 8, reported at one site. It is a population
208
- # — \`fields\`, \`fieldValues\` and the index \`items\` query — and the
209
- # round that introduced it fixed the identical shape in the board
210
- # sweep without carrying it across.
211
- #
212
- # THAT SWEEP IS NOT IN THIS TREE. It is \`scripts/board-status-sweep.ts\`
213
- # on branch \`rg/board-sweep\`, open as PR #1754 and unmerged, so a
214
- # reader of this file cannot resolve the path and review was right
215
- # to say so. Naming the pull request instead: a cross-branch
216
- # reference a reader can follow beats a path that 404s, and the
217
- # citation is kept rather than deleted because the precedent is the
218
- # reason this fix has the shape it does.
219
- #
220
- # The repair is NOT a bigger page. A bigger page has the same defect
221
- # further out. Each connection now asks \`pageInfo { hasNextPage }\`,
222
- # and "wanted value not found AND the page was full" is reported as
223
- # UNMEASURED with its own message — the same treatment #1754 gives
224
- # the same fact under the name \`statusUnread\`, so the two halves
225
- # answer it the same way once both land.
226
- # \`test/board-intake.test.ts\` BI-10 asserts the population rather
227
- # than any one site.
228
- fields=$(gql -f project="\${PROJECT_ID}" -f query='
229
- query($project: ID!) {
230
- node(id: $project) {
231
- ... on ProjectV2 {
232
- fields(first: 50) {
233
- pageInfo { hasNextPage }
234
- nodes { ... on ProjectV2SingleSelectField { id name options { id name } } }
235
- }
236
- }
237
- }
238
- }' --jq '.data.node.fields')
239
- require_node "the project's field list" "\${fields}" "\${PROJECT_ID}"
240
-
241
- status=$(printf '%s' "\${fields}" | jq -r '[.nodes[] | select(.name == "Status")] | first // empty')
242
- field_id=$(printf '%s' "\${status}" | jq -r '.id // empty')
243
- option_id=$(printf '%s' "\${status}" | jq -r --arg c "\${COLUMN}" '.options[]? | select(.name == $c) | .id')
244
-
245
- if [ -z "\${field_id}" ] && [ "$(printf '%s' "\${fields}" | jq -r '.pageInfo.hasNextPage')" = "true" ]; then
246
- echo "::error title=Board intake::The first 50 fields on this project do not include one named 'Status', AND there are more fields beyond that page — so this read is UNMEASURED, not a missing field. Nothing was written. Do not rename anything on the strength of this message; page the fields query instead." >&2
247
- exit 1
248
- fi
249
-
250
- # Resolved by name on purpose, so a renamed field or column is a red
251
- # job rather than a stale node id writing the wrong column quietly.
252
- # Reachable only when the page was NOT truncated, so it can now say
253
- # "renamed" and mean it.
254
- if [ -z "\${field_id}" ] || [ -z "\${option_id}" ]; then
255
- echo "::error title=Board intake::Could not resolve the Status field or its '\${COLUMN}' option on this project. The whole field list was read, so this is not a truncated page. The item WAS added; only the transition failed. Someone renamed the field or the column — update COLUMN in this workflow to match the board." >&2
256
- exit 1
257
- fi
258
-
259
- # WRITE, THEN READ BACK. Keying off the add step's itemId settles
260
- # WHICH item is written and says nothing about WHEN. This job and
261
- # GitHub's built-in "Item added to project" automation fire off the
262
- # same event and run concurrently, and this one is the slower of
263
- # the two by construction: it resolves the field and the option
264
- # first, which is two round trips the built-in does not make. If
265
- # the built-in's "set to Backlog" lands after this step's write,
266
- # the board reverts and the defect this workflow exists to fix
267
- # returns non-deterministically.
268
- #
269
- # So the mutation's exit code is NOT a reading of the board. A
270
- # write whose effect is never read is indistinguishable from one
271
- # overwritten a millisecond later
272
- # (\`.claude/rules/checks-must-be-able-to-fail.md\`, the sixth
273
- # shape). Three attempts, each verified, and a loud refusal if the
274
- # last one did not stick.
275
- for attempt in 1 2 3; do
276
- gql \\
277
- -f project="\${PROJECT_ID}" -f item="\${ITEM_ID}" \\
278
- -f field="\${field_id}" -f option="\${option_id}" -f query='
279
- mutation($project: ID!, $item: ID!, $field: ID!, $option: String!) {
280
- updateProjectV2ItemFieldValue(input: {
281
- projectId: $project, itemId: $item, fieldId: $field,
282
- value: { singleSelectOptionId: $option }
283
- }) { projectV2Item { id } }
284
- }' --jq '.data.updateProjectV2ItemFieldValue.projectV2Item.id' > /dev/null
285
-
286
- # Give a concurrent built-in write time to land, so the read-back
287
- # observes the SETTLED value rather than this step's own write
288
- # racing ahead of it. Reading immediately would report success
289
- # and then be overwritten, which is the exact failure being
290
- # guarded against.
291
- sleep 3
292
-
293
- values=$(gql -f item="\${ITEM_ID}" -f query='
294
- query($item: ID!) {
295
- node(id: $item) {
296
- ... on ProjectV2Item {
297
- fieldValues(first: 50) {
298
- pageInfo { hasNextPage }
299
- nodes {
300
- ... on ProjectV2ItemFieldSingleSelectValue {
301
- name field { ... on ProjectV2FieldCommon { name } }
302
- }
303
- }
304
- }
305
- }
306
- }
307
- }' --jq '.data.node.fieldValues')
308
- require_node "the item's field values, read back after the write" "\${values}" "\${ITEM_ID}"
309
-
310
- current=$(printf '%s' "\${values}" | jq -r '[.nodes[] | select(.field.name == "Status") | .name] | first // ""')
311
-
312
- # The worst of the three, because its wrong diagnosis is the one
313
- # a reader would act on: an item carrying more field values than
314
- # the page holds reads back as "" and the loop below blames a
315
- # competing writer for a race that never happened, three times,
316
- # then fails a job whose write in fact succeeded.
317
- if [ -z "\${current}" ] && [ "$(printf '%s' "\${values}" | jq -r '.pageInfo.hasNextPage')" = "true" ]; then
318
- echo "::error title=Board intake::Status was not among this item's first 50 field values and there are more beyond that page, so the read-back is UNMEASURED — the write may well have worked. This is NOT a competing writer and NOT an unset column. Page the fieldValues query." >&2
319
- exit 1
320
- fi
321
-
322
- # THE FIELD VALUE IS NOT WHAT THE BOARD DRAWS, AND THIS STEP USED
323
- # TO STOP HERE. Projects serves a board view from a SEARCH INDEX
324
- # that is separate from the item data, and the two can disagree.
325
- #
326
- # Measured on this project, 2026-11-04. Four pull requests held
327
- # Status "In review" in the data; \`items(query: "status:...")\`
328
- # returned two, and the board drew exactly those two. #1740 and
329
- # #1747 were invisible on the board for over an hour while every
330
- # field-value read said they were fine — which is precisely the
331
- # read this loop was doing.
332
- #
333
- # So a read-back that only asks the data path CANNOT observe the
334
- # failure it exists to catch: it returns "In review", the job
335
- # reports success, and nobody sees the card. Right exit code,
336
- # wrong mechanism (\`.claude/rules/checks-must-be-able-to-fail.md\`,
337
- # the sixth shape).
338
- #
339
- # Both readings must agree before this job claims the move worked.
340
- index_page=$(gql -f project="\${PROJECT_ID}" -f q="status:\\"\${COLUMN}\\"" -f query='
341
- query($project: ID!, $q: String!) {
342
- node(id: $project) {
343
- ... on ProjectV2 {
344
- items(first: 100, query: $q) {
345
- pageInfo { hasNextPage }
346
- nodes { id }
347
- }
348
- }
349
- }
350
- }' --jq '.data.node.items')
351
- require_node "the search index for the '\${COLUMN}' column" "\${index_page}" "\${PROJECT_ID}"
352
-
353
- # \`--arg\` rather than interpolating ITEM_ID into the jq program.
354
- # The id is minted by GitHub so this is not a sanitisation fix; a
355
- # value pasted into a program text is simply a different thing
356
- # from a value passed to one, and only one of them stays a value.
357
- indexed=$(printf '%s' "\${index_page}" | jq -r --arg id "\${ITEM_ID}" '[.nodes[].id] | index($id) // empty')
358
-
359
- # The third site. A column holding more than 100 cards is not
360
- # hypothetical on a 121-item board, and without this the job
361
- # reports the card as absent from the index and tells a human to
362
- # go and look at an index that is in fact correct.
363
- if [ -z "\${indexed}" ] && [ "$(printf '%s' "\${index_page}" | jq -r '.pageInfo.hasNextPage')" = "true" ]; then
364
- echo "::error title=Board intake::More than 100 items match '\${COLUMN}' in the project's search index and this item was not in the first page, so its membership is UNMEASURED — it may well be indexed and rendering. Do not read this as a missing card. Page the index query." >&2
365
- exit 1
366
- fi
367
-
368
- if [ "\${current}" = "\${COLUMN}" ] && [ -n "\${indexed}" ]; then
369
- echo "::notice title=Board intake::Moved to '\${COLUMN}' on attempt \${attempt}, confirmed in BOTH the item's field value and the project's search index — so the card will actually render. This workflow owns only the opened->In review edge; merged->Done and closed->Done remain GitHub's built-in project workflows, so exactly one decider writes each transition."
370
- exit 0
371
- fi
372
-
373
- if [ "\${current}" = "\${COLUMN}" ]; then
374
- echo "Attempt \${attempt}: the field value reads '\${COLUMN}' but the search index does not carry this item yet, so the board would not draw it. Re-writing to prompt a re-index."
375
- else
376
- echo "Attempt \${attempt}: wrote '\${COLUMN}', read back '\${current:-(nothing)}' — a concurrent write won. Retrying."
377
- fi
378
- done
379
-
380
- if [ "\${current}" = "\${COLUMN}" ]; then
381
- echo "::error title=Board intake::The Status field reads '\${COLUMN}' but after three attempts the project's SEARCH INDEX still does not list this item under it, and the board draws from the index. The data is right and the card is invisible — do not 'fix' the Status, it is already correct. Re-writing the same value is what repairs the index entry; if three did not take, the index is lagging and this needs a human to re-check later." >&2
382
- exit 1
383
- fi
384
-
385
- echo "::error title=Board intake::Wrote '\${COLUMN}' three times and the board still reads '\${current:-(nothing)}'. Something else is writing this item's Status and winning: check the project's built-in workflows for a rule that also fires on a pull request being added. The item IS on the board; only its column is wrong. Not exiting 0 on this — a job that writes and does not check is how the column silently reverted before." >&2
386
- exit 1
128
+ export function buildBoardIntakeMoveScript(version: string): string {
129
+ return `set -euo pipefail
130
+ bunx rungate@${version} ${BOARD_INTAKE_MOVE_COMMAND} --project "\${PROJECT_ID}" --item "\${ITEM_ID}" --column "\${COLUMN}"
387
131
  `;
132
+ }
388
133
 
389
134
  export interface BoardIntakeWorkflowOptions {
390
135
  /** The `runs-on:` value, already JSON-quoted by the caller. */
@@ -464,6 +209,6 @@ ${indent(buildBoardIntakeAddScript(opts.version), " ")}
464
209
  ITEM_ID: \${{ steps.add.outputs.itemId }}
465
210
  COLUMN: In review
466
211
  run: |
467
- ${indent(BOARD_INTAKE_MOVE_SCRIPT, " ")}
212
+ ${indent(buildBoardIntakeMoveScript(opts.version), " ")}
468
213
  `;
469
214
  }
package/lib/spec-deps.ts CHANGED
@@ -71,8 +71,17 @@ export interface DepEdge {
71
71
  }
72
72
 
73
73
  export interface DependencyPlan {
74
- /** UNMEASURED FAILS. An empty edge list from an unread input is not a clean one. */
75
- reading: "MEASURED" | "UNMEASURED";
74
+ /**
75
+ * UNMEASURED FAILS. An empty edge list from an unread input is not a clean one.
76
+ *
77
+ * NOTHING_TO_SEQUENCE (#2239) is a sound read in which every considered
78
+ * issue sits in ONE phase. It writes nothing and refuses nothing: one phase
79
+ * states no order, so "missing: []" here means nothing to sequence, and it
80
+ * must never be reported as MEASURED, whose empty plan reads as *already
81
+ * sequenced*. It was a refusal until 2026-11-15, when the engine reached its
82
+ * last phase and the refusal skipped adr-accepted.yml's board steps.
83
+ */
84
+ reading: "MEASURED" | "UNMEASURED" | "NOTHING_TO_SEQUENCE";
76
85
  unmeasuredReasons: string[];
77
86
  /** The phase numbers that carry at least one considered issue, ascending. */
78
87
  phases: number[];
@@ -123,6 +132,13 @@ export interface DependencyPlan {
123
132
  * input that reaches none of them. Row 5 is orthogonal — the phases can be
124
133
  * fine while the live edge list is short — so it is checked alongside rather
125
134
  * than inside the count.
135
+ *
136
+ * **Row 4 is not a refusal, and is not returned from here (#2239).** Rows 1-3
137
+ * are reads that could not be taken; row 4 is a read that was taken in full
138
+ * and found one phase. {@link dependencyPlan} names it as its own reading,
139
+ * `NOTHING_TO_SEQUENCE`, which is neither this list's refusal nor the
140
+ * flattering MEASURED. So the property is still the one above, stated
141
+ * exactly: fewer than two phases is never MEASURED.
126
142
  */
127
143
  export function degenerateReasons(r: {
128
144
  readonly read: number;
@@ -149,11 +165,6 @@ export function degenerateReasons(r: {
149
165
  `what phaseOf reads. An empty plan from this input means "nothing was read", ` +
150
166
  `not "the tracker already carries the phase order"`,
151
167
  );
152
- } else if (r.phases.length === 1) {
153
- out.push(
154
- `every issue read sits in Phase ${r.phases[0]} — one phase states no order, so an ` +
155
- `empty plan here means "nothing to sequence" and not "already sequenced"`,
156
- );
157
168
  }
158
169
  if (r.truncated.length > 0) {
159
170
  out.push(
@@ -272,7 +283,8 @@ export function dependencyPlan(
272
283
  const openPhases = open.filter((p): p is number => p !== null);
273
284
 
274
285
  return {
275
- reading: reasons.length > 0 ? "UNMEASURED" : "MEASURED",
286
+ // Row 4 of `degenerateReasons`' table, decided here and nowhere else.
287
+ reading: reasons.length > 0 ? "UNMEASURED" : phases.length === 1 ? "NOTHING_TO_SEQUENCE" : "MEASURED",
276
288
  unmeasuredReasons: reasons,
277
289
  phases,
278
290
  missing: derived.filter(e => !liveKeys.has(key(e))),
@@ -315,6 +315,17 @@ export function parseCriteria(content: string): ParsedCriterion[] {
315
315
  return out;
316
316
  }
317
317
 
318
+ /**
319
+ * A statement that OPENS with `SUPERSEDED` — a pointer to what replaced the
320
+ * criterion, or the record of a withdrawal (#1720). The same reading as
321
+ * `isSuperseded` in `lib/sc-cover.ts`, restated here because this module must
322
+ * stay import-free for its mutation battery; `test/spec-evidence.test.ts`
323
+ * holds the two in agreement on the inputs that separate them.
324
+ */
325
+ export function supersededStatement(statement: string): boolean {
326
+ return /^SUPERSEDED\b/.test(statement.trim());
327
+ }
328
+
318
329
  /**
319
330
  * Every way this spec's criteria fail the evidence rule.
320
331
  *
@@ -336,6 +347,10 @@ export function evidenceViolations(
336
347
  for (const c of parseCriteria(content)) {
337
348
  const at = `${c.id} (line ${c.line})`;
338
349
 
350
+ // A ticked SUPERSEDED line claims nothing was proved, so it owes nothing.
351
+ // Ticked only: an unticked one is still a criterion somebody owes.
352
+ if (c.ticked && supersededStatement(c.text)) continue;
353
+
339
354
  if (!hasContent(c.needs)) {
340
355
  out.push({
341
356
  id: c.id,
@@ -67,6 +67,12 @@ export interface SpecRequirementReading {
67
67
  declaredNone: boolean;
68
68
  /** Why it states none. A declaration with no reason is a mute. */
69
69
  reason: string | null;
70
+ /**
71
+ * SC-2623: the raw `serves:` value — which SUCCESS.md claim(s) this spec
72
+ * serves. `null` when the key is absent (opt-in, like `evidence: required`);
73
+ * `""` when the key is present and empty, which is refused, not skipped.
74
+ */
75
+ serves: string | null;
70
76
  }
71
77
 
72
78
  function frontmatterField(content: string, key: string): string | null {
@@ -85,9 +91,79 @@ export function readSpecRequirements(specsDir: string, rel: string): SpecRequire
85
91
  criteria: countCriteria(content),
86
92
  declaredNone: declared === "none",
87
93
  reason: reason && reason.length > 0 ? reason : null,
94
+ serves: servesField(content),
88
95
  };
89
96
  }
90
97
 
98
+ /**
99
+ * The `serves:` value, keeping "present and empty" apart from "absent".
100
+ * `frontmatterField` needs one character after the colon, so an empty key
101
+ * would otherwise read as no key at all — an opt-in that silently opts out.
102
+ */
103
+ function servesField(content: string): string | null {
104
+ const fm = content.match(/^---\n([\s\S]*?)\n---/);
105
+ if (!fm) return null;
106
+ const m = fm[1].match(/^serves:[ \t]*(.*)$/m);
107
+ return m ? m[1].trim() : null;
108
+ }
109
+
110
+ /**
111
+ * SC-2623: the claim numbers SUCCESS.md states under "## Done, for the
112
+ * harness" — `1. **…**` lines, up to the next `## ` heading. The consumer
113
+ * section numbers its own list from 1 too, which is why the section bounds
114
+ * the read.
115
+ */
116
+ export function successClaimNumbers(successMd: string): number[] {
117
+ const out: number[] = [];
118
+ let inSection = false;
119
+ for (const line of successMd.split("\n")) {
120
+ if (line.startsWith("## ")) {
121
+ inSection = /^## Done, for the harness\b/.test(line);
122
+ continue;
123
+ }
124
+ if (!inSection) continue;
125
+ const m = line.match(/^(\d+)\. \*\*/);
126
+ if (m) out.push(Number(m[1]));
127
+ }
128
+ return out;
129
+ }
130
+
131
+ /**
132
+ * SC-2623: refusals for a `serves:` declaration that does not name a real
133
+ * claim. A spec with no key is untouched. `claims` is `null` when SUCCESS.md
134
+ * could not be read, and then every declaration is UNMEASURED rather than
135
+ * accepted: an unread list of claims is not a list every number is in.
136
+ */
137
+ export function servesViolations(readings: SpecRequirementReading[], claims: number[] | null): string[] {
138
+ const out: string[] = [];
139
+ for (const r of readings) {
140
+ if (r.serves === null) continue;
141
+ if (claims === null || claims.length === 0) {
142
+ out.push(
143
+ `${r.spec} declares "serves: ${r.serves}" and SUCCESS.md's claims could not be read, so the ` +
144
+ `declaration is UNMEASURED, not accepted.`,
145
+ );
146
+ continue;
147
+ }
148
+ const parts = r.serves.split(",").map(p => p.trim());
149
+ if (parts.length === 0 || parts.some(p => !/^\d+$/.test(p))) {
150
+ out.push(
151
+ `${r.spec} declares "serves: ${r.serves}", which is not a list of SUCCESS.md claim numbers. ` +
152
+ `Name the claim(s) it serves from "## Done, for the harness", e.g. "serves: 7".`,
153
+ );
154
+ continue;
155
+ }
156
+ const unknown = parts.map(Number).filter(n => !claims.includes(n));
157
+ if (unknown.length > 0) {
158
+ out.push(
159
+ `${r.spec} declares it serves claim ${unknown.join(", ")}, which SUCCESS.md's "Done, for the ` +
160
+ `harness" does not state (it states ${claims.join(", ")}).`,
161
+ );
162
+ }
163
+ }
164
+ return out;
165
+ }
166
+
91
167
  /**
92
168
  * Refusals, worded after the property rather than after the proxy.
93
169
  *
@@ -65,6 +65,14 @@ import { localCalendarDay } from "./local-calendar-day";
65
65
  /** What a generated spec must carry for `lib/spec-evidence.ts` to bind it. */
66
66
  export const EVIDENCE_FRONTMATTER_KEY = "evidence: required";
67
67
 
68
+ /**
69
+ * SC-2623: which SUCCESS.md claim the spec serves. Emitted as a placeholder
70
+ * that `servesViolations` in `lib/spec-requirements.ts` refuses until it is a
71
+ * claim number, so a new spec answers "which goal does this serve" before it
72
+ * merges rather than never.
73
+ */
74
+ export const SERVES_FRONTMATTER_PLACEHOLDER = "serves: TODO — the SUCCESS.md claim number(s) this spec serves";
75
+
68
76
  export interface SpecTemplateInput {
69
77
  title: string;
70
78
  /** One line saying what the spec governs. May be the `TODO —` placeholder. */
@@ -121,6 +129,7 @@ governs: ${input.governs}
121
129
  testable: true
122
130
  compliance: strict
123
131
  ${EVIDENCE_FRONTMATTER_KEY}
132
+ ${SERVES_FRONTMATTER_PLACEHOLDER}
124
133
  ---
125
134
 
126
135
  # ${input.title}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.20",
3
+ "version": "0.8.22",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -32,13 +32,17 @@
32
32
  */
33
33
  import { createGitHubClient } from "../lib/github";
34
34
  import {
35
+ AI_REVIEW_PR_IS_FORK_VAR,
35
36
  aiReviewThreadsExitCode,
36
37
  postReviewThreads,
38
+ prIsForkReading,
39
+ threadsDetailLines,
37
40
  threadsLandedPhrase,
38
41
  type AiReviewThreadPoster,
39
42
  type AiReviewThreadResponse,
40
43
  } from "../lib/ai-review-threads";
41
44
  import {
45
+ escapeAnnotation,
42
46
  readAiReviewChangedFiles,
43
47
  readAiReviewFindingsFile,
44
48
  } from "../lib/scaffold/ai-review-findings";
@@ -113,7 +117,11 @@ if (!parsed.ok) {
113
117
  // UNMEASURED, not a refusal. A step invoked wrongly has not discovered that
114
118
  // a review produced no threads; it has not looked. Exiting non-zero here
115
119
  // would red the job for a reason that says nothing about the review.
116
- console.log(`::warning title=AI review threads::${COMMAND}: ${parsed.error} — UNMEASURED, nothing was posted`);
120
+ // Escaped: the error quotes the positionals, which are this process's argv
121
+ // (#1992).
122
+ console.log(
123
+ `::warning title=AI review threads::${COMMAND}: ${escapeAnnotation(parsed.error)} — UNMEASURED, nothing was posted`,
124
+ );
117
125
  process.exit(0);
118
126
  }
119
127
 
@@ -180,8 +188,12 @@ const post: AiReviewThreadPoster = async request => {
180
188
  // every round would re-post every thread. `lineTextFor` comes off the SAME
181
189
  // reader the gate above was built from, so it is the same cache and the same
182
190
  // normalisation rather than a second one that happens to agree.
183
- const result = await postReviewThreads(reading, post, f => carryKey(f, lineTextFor(f)));
184
- for (const line of result.detail) console.log(`${COMMAND}: ${line}`);
191
+ // #1992: whether this run is a fork, read exactly from the variable the
192
+ // workflow sets (#2203). Unset reads null, which keeps the fork degrade — so
193
+ // this CLI under a workflow that does not yet set it behaves as before.
194
+ const fork = prIsForkReading(process.env[AI_REVIEW_PR_IS_FORK_VAR]);
195
+ const result = await postReviewThreads(reading, post, f => carryKey(f, lineTextFor(f)), fork);
196
+ for (const line of threadsDetailLines(result, COMMAND)) console.log(line);
185
197
  console.log(
186
198
  `${COMMAND}: ${result.outcome} — attempted ${result.attempted}, posted ${result.posted}, ` +
187
199
  `demoted ${result.demoted}`,