rungate 0.8.21 → 0.8.23

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/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- 36e88dc95acdd61bc72fdbbfffcae7a21722942437fbac2c5b2a5515cf2640ef
1
+ e387efb0e00e0aa4e64f43d5fed7be9d6279267723195e1531aff90000f927f7
@@ -2,6 +2,10 @@
2
2
  /**
3
3
  * AgentBriefGuard — PreToolUse on Agent (SC-367, SC-370)
4
4
  * Validates briefs use templates + bypassPermissions. Delegates to lib/agent-brief-validation.ts
5
+ *
6
+ * USER scope since #1585: WORK_DIR/BASE_DIR are ~/.rungate and ~/.claude (machine state),
7
+ * and a project registration never loads in the worktree sessions where agents spawn agents.
8
+ * Registered live in ~/.claude/settings.json (measured 2026-11-15, #2225).
5
9
  */
6
10
  import { BASE_DIR, WORK_DIR } from './lib/paths';
7
11
  import { parseHookInput } from './lib/parseStdin';
@@ -41,6 +41,22 @@
41
41
  * and records both answers. Change either hook and update that table and
42
42
  * `specs/HOOK-ARCHITECTURE-SPEC.md` § "The workflow-state.json write contract"
43
43
  * in the same commit.
44
+ *
45
+ * ## User scope since #1585
46
+ *
47
+ * This was `project` scope and registered in `.claude/settings.json`. Agent
48
+ * sessions run in worktrees and do not load project settings, so it never
49
+ * fired, while `GateResultProtection` fired on the same tool calls from user
50
+ * settings. What it guards is machine-wide — the matcher below has no project
51
+ * scoping, and `lib/bash-write-guard.ts` records that a live
52
+ * `workflow-state.json` is almost never inside the project root — so SC-518
53
+ * puts it in user settings. The repo no longer registers it (dual registration
54
+ * fires twice) and reports it UNMEASURED. Registered live in ~/.claude/settings.json
55
+ * (measured 2026-11-15, #2225); the session-start reading reports it if that stops (#2229).
56
+ *
57
+ * A scaffolded consumer is unaffected: `deployHooksToConsumers` filters on
58
+ * `deployToConsumers`, not on scope, so the paragraph above about consumer
59
+ * trees still holds.
44
60
  */
45
61
 
46
62
  import { parseHookInput } from './lib/utils';
@@ -299,6 +299,16 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
299
299
  "rungate unaccounted-work [--project-root <dir>] [--repo <owner/name>] [--issues-fixture <file.json>] [--json] " +
300
300
  "(exit 1 when work is unaccounted, 2 when a source could not be read)",
301
301
  },
302
+ // #2248: the command #2233 (fix-commits on push to main) and #2234
303
+ // (gate-refusals at the end of a ship run) call, per #1126's decision that
304
+ // each intake source runs on its own trigger.
305
+ intake: {
306
+ script: "scripts/intake.ts",
307
+ summary: "Run each intake source and print its reading — MEASURED with a count, or UNMEASURED naming why",
308
+ usage:
309
+ "rungate intake [--project-root <dir>] [--source <id>] [--json] " +
310
+ "(advisory: an unreadable source prints UNMEASURED and exits 0; exit 2 on a bad argument)",
311
+ },
302
312
  // Reads a `gh pr view`-shaped payload on stdin, which the dispatcher passes
303
313
  // through (`stdio: "inherit"`), or `--fixture` offline.
304
314
  "audit-closing-references": {
@@ -211,6 +211,25 @@ interface FileReading {
211
211
 
212
212
  const READABLE: FileReading = { failure: null, unmeasured: null };
213
213
 
214
+ /**
215
+ * The directories a strike scan may read: every visible one, and no hidden one
216
+ * (#1987, SC-2771).
217
+ *
218
+ * A hidden directory under the run store is where runs are set aside, not run.
219
+ * `~/.rungate/.archive` is the one that exists. On 2026-11-15 it held 67
220
+ * workflow-state files within the two levels the scan below walks, and every
221
+ * one was counted as a live attempt. So a project whose failed runs had been
222
+ * archived stayed blocked by the strike rule, and the only workaround was to
223
+ * move the archive out of `~/.rungate` (DBD #1513).
224
+ *
225
+ * The rule is the hidden-directory convention, not the word: a directory named
226
+ * `archive` without the dot is a live run and is still read. One function and
227
+ * both scan levels call it, so there is one site to mutate.
228
+ */
229
+ export function excludeArchivedRuns<T extends { readonly name: string }>(dirs: readonly T[]): T[] {
230
+ return dirs.filter(d => !d.name.startsWith('.'));
231
+ }
232
+
214
233
  /**
215
234
  * Scan workflow-state.json files under workDir for active gate failures.
216
235
  * Returns the first failure found (scope > verify > ship priority).
@@ -239,8 +258,9 @@ export function findWorkflowGateFailure(workDir: string): WorkflowScan {
239
258
  };
240
259
 
241
260
  try {
242
- const dirs = readdirSync(workDir, { withFileTypes: true })
243
- .filter(d => d.isDirectory());
261
+ const dirs = excludeArchivedRuns(
262
+ readdirSync(workDir, { withFileTypes: true }).filter(d => d.isDirectory()),
263
+ );
244
264
 
245
265
  for (const d of dirs) {
246
266
  // Level 1: direct children
@@ -248,8 +268,9 @@ export function findWorkflowGateFailure(workDir: string): WorkflowScan {
248
268
 
249
269
  // Level 2: nested subdirectories
250
270
  try {
251
- const subDirs = readdirSync(`${workDir}/${d.name}`, { withFileTypes: true })
252
- .filter(sd => sd.isDirectory());
271
+ const subDirs = excludeArchivedRuns(
272
+ readdirSync(`${workDir}/${d.name}`, { withFileTypes: true }).filter(sd => sd.isDirectory()),
273
+ );
253
274
  for (const sd of subDirs) {
254
275
  take(checkWorkflowFile(
255
276
  `${workDir}/${d.name}/${sd.name}/workflow-state.json`,
@@ -386,6 +386,14 @@ export function unplacedHooks(input: {
386
386
  */
387
387
  export const NOT_LIVE_CLAIM = /\bnot live\b/i;
388
388
 
389
+ /**
390
+ * The reverse claim: a registry description saying its hook is registered in
391
+ * user settings (#2229). Checked against `user-settings` specifically, because
392
+ * that is the file the sentence names; a registration somewhere else does not
393
+ * make the sentence true.
394
+ */
395
+ export const LIVE_CLAIM = /\bregistered live in ~\/\.claude\/settings\.json/i;
396
+
389
397
  /**
390
398
  * Registry entries whose NOT LIVE claim the machine's registration contradicts,
391
399
  * as lines a person reads at session start (#1986).
@@ -396,8 +404,9 @@ export const NOT_LIVE_CLAIM = /\bnot live\b/i;
396
404
  * NOT LIVE claim disagree with itself. With that scope empty, `registered`
397
405
  * means a settings file a session loads names the hook — a disagreement;
398
406
  * `unmeasured` means a machine scope could not be read — said as UNMEASURED,
399
- * which is every CI runner; `unregistered` agrees with the claim, and is
400
- * silent.
407
+ * which is a machine with no user settings file (most CI runners);
408
+ * `unregistered` agrees with the claim, and is silent. Entries claiming the
409
+ * opposite, "registered live", are read by `liveRegistrationLine` (#2229).
401
410
  */
402
411
  export function liveClaimLines(
403
412
  entries: readonly { name?: unknown; description?: unknown }[],
@@ -410,7 +419,10 @@ export function liveClaimLines(
410
419
  const lines: string[] = [];
411
420
  for (const e of entries) {
412
421
  if (typeof e.name !== "string" || typeof e.description !== "string") continue;
413
- if (!NOT_LIVE_CLAIM.test(e.description)) continue;
422
+ if (!NOT_LIVE_CLAIM.test(e.description)) {
423
+ if (LIVE_CLAIM.test(e.description)) lines.push(...liveRegistrationLine(e.name, loaded));
424
+ continue;
425
+ }
414
426
  const r = hookRegistration(e.name, loaded);
415
427
  if (r.verdict === "registered") {
416
428
  lines.push(
@@ -427,6 +439,46 @@ export function liveClaimLines(
427
439
  return lines;
428
440
  }
429
441
 
442
+ /**
443
+ * #2229: an entry that claims user settings registers it. Silent when the
444
+ * `user-settings` scope names the hook. UNMEASURED when that scope could not
445
+ * be read, which is a machine with no `~/.claude/settings.json` (most CI
446
+ * runners). Otherwise a disagreement, naming where the hook IS registered, if
447
+ * anywhere.
448
+ *
449
+ * The claim is about the machine the registration was measured on, and the
450
+ * registry is shared. So on a machine whose user settings exist but never
451
+ * registered the hook (another contributor's laptop, a review sandbox), the
452
+ * reading is DISAGREES, and it is true FOR THAT MACHINE: the hook does not run
453
+ * there. The message says "on this machine" so it reads as that, and not as a
454
+ * claim that the entry is wrong everywhere (review of #2232).
455
+ */
456
+ function liveRegistrationLine(hook: string, loaded: ScopeReading[]): string[] {
457
+ const user = loaded.find(r => r.scope === "user-settings");
458
+ if (user === undefined || user.commands === null) {
459
+ return [
460
+ `Hook registry UNMEASURED: ${hook} is described as registered live in ~/.claude/settings.json, and ` +
461
+ `user-settings could not be read to check that claim (#2229)`,
462
+ ];
463
+ }
464
+ if (user.commands.some(c => commandNamesHook(c, hook))) return [];
465
+ const elsewhere = loaded.filter(r => (r.commands ?? []).some(c => commandNamesHook(c, hook))).map(r => r.scope);
466
+ // Registered in another scope a session loads (user-local-settings, say):
467
+ // the hook runs, and only the file the entry names is wrong. Saying "does
468
+ // not run here" then would be false (review of #2232, round 2).
469
+ if (elsewhere.length > 0) {
470
+ return [
471
+ `Hook registry DISAGREES: ${hook} is described as registered live in ~/.claude/settings.json, but ` +
472
+ `this machine registers it in ${elsewhere.join(", ")} instead — the entry names the wrong file (#2229)`,
473
+ ];
474
+ }
475
+ return [
476
+ `Hook registry DISAGREES: ${hook} is described as registered live in ~/.claude/settings.json, but ` +
477
+ `this machine's user settings do not register it, so it does not run here — ` +
478
+ `register it on this machine, or correct the entry if it is no longer meant to run (#2229)`,
479
+ ];
480
+ }
481
+
430
482
  /**
431
483
  * `liveClaimLines` over a fresh reading, as its own reading (#1986).
432
484
  *
@@ -196,8 +196,14 @@ ${opts.setupBunEnv}
196
196
  # reads it as GITHUB_TOKEN, board-ready as BOARD_PROJECT_TOKEN. An absent
197
197
  # secret is the empty string with no error, so each command's own
198
198
  # UNMEASURED refusal is what reports it.
199
+ #
200
+ # \`!cancelled()\` (#2239): an \`if:\` with no status function means
201
+ # \`success() && …\`, so a refusal in any step above skipped both of these
202
+ # for every issue the merge had just created. Each reads the whole board
203
+ # and writes only what is missing, so it never depends on an earlier step
204
+ # succeeding. The run is still red when one of those failed.
199
205
  - name: Criteria column on the board
200
- if: steps.accepted.outputs.any == 'true'
206
+ if: \${{ !cancelled() && steps.accepted.outputs.any == 'true' }}
201
207
  env:
202
208
  GITHUB_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
203
209
  PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
@@ -209,7 +215,7 @@ ${opts.setupBunEnv}
209
215
  ${cli} board-mirror --project "$PROJECT_ID" --write
210
216
 
211
217
  - name: Top up Ready from the new issues
212
- if: steps.accepted.outputs.any == 'true'
218
+ if: \${{ !cancelled() && steps.accepted.outputs.any == 'true' }}
213
219
  env:
214
220
  BOARD_PROJECT_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
215
221
  PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
@@ -135,6 +135,7 @@ import {
135
135
  AI_REVIEW_VERDICT_KEY,
136
136
  SEVERITY_RANK,
137
137
  type Severity,
138
+ AI_REVIEW_UNTRUSTED_PATHS,
138
139
  } from "./ai-review-step";
139
140
 
140
141
  export {
@@ -2352,6 +2353,71 @@ export function aiReviewScopeLine(reading: AiReviewFindingsReading): string {
2352
2353
  );
2353
2354
  }
2354
2355
 
2356
+ /** The prefix of the line naming the changed files the reviewer read from base (#1887). */
2357
+ export const AI_REVIEW_RESTORED_LINE = "ai-review restored from base, not reviewed:";
2358
+
2359
+ /**
2360
+ * The changed files the review step restored from the base branch before the
2361
+ * reviewer ran, so the verdict was reached over the BASE copy (#1887).
2362
+ *
2363
+ * The restore is correct and stays: it is what stops a pull request editing
2364
+ * the instructions that judge it. What was wrong is that the verdict said
2365
+ * nothing, so a review that never read three of four changed files (#1882)
2366
+ * looked like a review that read all four.
2367
+ *
2368
+ * `restored` defaults to `AI_REVIEW_UNTRUSTED_PATHS`, the list the generated
2369
+ * restore step is built from, so there is no second copy to drift. A path
2370
+ * counts when it IS a restored entry or sits under one as a directory, which
2371
+ * is how `git checkout <base> -- <path>` reaches it. The match is byte for
2372
+ * byte on git's spelling: the runner's filesystem is case-sensitive, so
2373
+ * `claude.md` is not `CLAUDE.md` and was not restored.
2374
+ */
2375
+ export function restoredFromBase(
2376
+ files: readonly string[],
2377
+ restored: readonly string[] = AI_REVIEW_UNTRUSTED_PATHS,
2378
+ ): string[] {
2379
+ return files.filter(raw => {
2380
+ const f = repoPathSpelling(raw);
2381
+ return f !== null && restored.some(r => f === r || f.startsWith(`${r}/`));
2382
+ });
2383
+ }
2384
+
2385
+ /**
2386
+ * The line `main` prints after the scope line: how many changed files were
2387
+ * reviewed against the base copy, and which. Printed on every run, an empty
2388
+ * overlap included as an explicit `0 of N` — "nothing was hidden" and "nobody
2389
+ * looked" must not be the same bytes. With no readable changed-file list the
2390
+ * overlap is UNMEASURED, never zero.
2391
+ *
2392
+ * A report only, as #1887 scopes it. Whether an unreviewed fraction should
2393
+ * ever block is a separate decision, and nothing here refuses.
2394
+ */
2395
+ export function restoredFromBaseLine(scope: AiReviewScopeReading): string {
2396
+ if (scope.status !== "MEASURED") {
2397
+ return (
2398
+ `${AI_REVIEW_RESTORED_LINE} UNMEASURED — the changed-file list is ${scope.status}, so which ` +
2399
+ `changed files were reviewed against the base copy cannot be said`
2400
+ );
2401
+ }
2402
+ const hit = restoredFromBase(scope.files);
2403
+ const of = `${hit.length} of ${scope.files.length} changed files`;
2404
+ // An entry with no comparable spelling (git's C-quoted form for a non-ASCII
2405
+ // name, or a path escaping the root) cannot be classified either way. It is
2406
+ // NAMED rather than folded into "not restored": a restored `.claude/réglages.md`
2407
+ // arrives C-quoted, and counting it clean is the silence #1887 is about.
2408
+ const unread = scope.files.filter(f => repoPathSpelling(f) === null);
2409
+ const unreadNote =
2410
+ unread.length === 0
2411
+ ? ""
2412
+ : `; ${unread.length} could not be read as a repository path and may also have been ` +
2413
+ `restored: ${unread.map(p => JSON.stringify(p)).join(", ")}`;
2414
+ if (hit.length === 0) return `${AI_REVIEW_RESTORED_LINE} ${of}${unreadNote}`;
2415
+ return (
2416
+ `${AI_REVIEW_RESTORED_LINE} ${of} — the reviewer read the base branch's copy of ` +
2417
+ `${hit.map(p => JSON.stringify(p)).join(", ")}, not this pull request's${unreadNote}`
2418
+ );
2419
+ }
2420
+
2355
2421
  // `parseFindingsArgv` and `AiReviewFindingsArgv` lived here and are gone.
2356
2422
  // The parser refused a SECOND POSITIONAL argument by design, which is
2357
2423
  // exactly the invocation CRC-B7 deploys, so the flag CLI and the
@@ -2547,6 +2613,9 @@ export function main(
2547
2613
  // on the command line reaches a stream GitHub parses workflow commands out
2548
2614
  // of, and this module escapes exactly once, at the point of emission.
2549
2615
  console.log(escapeAnnotation(aiReviewScopeLine(reading)));
2616
+ // #1887: which changed files the reviewer saw only as the base copy. Same
2617
+ // escaping, for the same reason: these are paths off the command line.
2618
+ console.log(escapeAnnotation(restoredFromBaseLine(reading.scope)));
2550
2619
 
2551
2620
  // The ONE place a value reaches a workflow command. Everything upstream of
2552
2621
  // here — `renderFinding`, every `detail` sentence, `aiReviewRefusal` — builds
@@ -3199,6 +3199,13 @@ export const AI_REVIEW_THREADS_PR_VAR = "AI_REVIEW_THREADS_PR";
3199
3199
  export const AI_REVIEW_THREADS_REPO_VAR = "AI_REVIEW_THREADS_REPO";
3200
3200
  export const AI_REVIEW_THREADS_SHA_VAR = "AI_REVIEW_THREADS_SHA";
3201
3201
  export const AI_REVIEW_THREADS_TOKEN_VAR = "AI_REVIEW_THREADS_TOKEN";
3202
+ /**
3203
+ * Whether this run is a fork, for the threads CLI's 403 decision (#1992,
3204
+ * #2203). Spelt here rather than imported from `lib/ai-review-threads.ts`,
3205
+ * which would pull that module's import tree into this deliberately
3206
+ * import-light generator; `test/ai-review-threads.test.ts` binds the two.
3207
+ */
3208
+ export const AI_REVIEW_FORK_VAR = "RUNGATE_PR_IS_FORK";
3202
3209
 
3203
3210
  /**
3204
3211
  * The script the threads step runs.
@@ -3244,11 +3251,15 @@ export const AI_REVIEW_THREADS_TOKEN_VAR = "AI_REVIEW_THREADS_TOKEN";
3244
3251
  export function buildThreadsScript(version: string): string {
3245
3252
  const poster =
3246
3253
  `bunx ${AI_REVIEW_ADJUDICATOR_PACKAGE}@${version} ${AI_REVIEW_THREADS_COMMAND}`;
3247
- // Matched with `grep -qF` inside SINGLE quotes, where a double quote is
3248
- // literal and needs no escaping. The quotes are part of the signal:
3249
- // `bin/rungate.ts` prints the name quoted, and an unquoted match would
3250
- // also hit a findings summary that happened to mention the command.
3251
- const skew = `unknown command "${AI_REVIEW_THREADS_COMMAND}"`;
3254
+ // The WHOLE line `bin/rungate.ts` prints for an unknown command, matched
3255
+ // with `grep -qxF` (#2203). A substring match let the command's own
3256
+ // output satisfy it: a finding quoting the phrase turned a refusal into an
3257
+ // UNMEASURED exit 0. Since 0.8.21 (#1992) every line the command prints
3258
+ // from a finding is escaped and prefixed `ai-review-threads: `, so no
3259
+ // finding text can BE this line. The exit code cannot separate the cases:
3260
+ // the unknown-command path exits 1 like every refusal. Inside SINGLE
3261
+ // quotes below, where the double quotes are literal.
3262
+ const skew = `rungate: unknown command "${AI_REVIEW_THREADS_COMMAND}"`;
3252
3263
  return [
3253
3264
  `set -uo pipefail`,
3254
3265
  ``,
@@ -3274,7 +3285,7 @@ export function buildThreadsScript(version: string): string {
3274
3285
  ` --changed-files "\${${AI_REVIEW_CHANGED_FILES_PATH_VAR}}" 2>&1)" || threads_code=$?`,
3275
3286
  `printf '%s\\n' "$threads_out"`,
3276
3287
  ``,
3277
- `if [ "$threads_code" -ne 0 ] && printf '%s' "$threads_out" | grep -qF '${skew}'; then`,
3288
+ `if [ "$threads_code" -ne 0 ] && printf '%s\\n' "$threads_out" | grep -qxF '${skew}'; then`,
3278
3289
  ` echo "::warning title=AI review threads::UNMEASURED - rungate@${version} does not carry the ${AI_REVIEW_THREADS_COMMAND} command yet, so no review threads were posted. This workflow is ahead of the published package; it resolves itself on the next release."`,
3279
3290
  ` exit 0`,
3280
3291
  `fi`,
@@ -11695,6 +11706,11 @@ export function buildReviewRunStep(
11695
11706
  ` ${AI_REVIEW_THREADS_SHA_VAR}: \${{ github.event.pull_request.head.sha }}`,
11696
11707
  ` ${AI_REVIEW_THREADS_REPO_VAR}: \${{ github.repository }}`,
11697
11708
  ` ${AI_REVIEW_THREADS_TOKEN_VAR}: \${{ secrets.GITHUB_TOKEN }}`,
11709
+ // #1992/#2203: a 403 degrades only on a fork. GitHub evaluates this to
11710
+ // the string "true" or "false", which is exactly what the CLI reads. On
11711
+ // a merge_group run it reads "true", harmlessly: the script exits before
11712
+ // posting when there is no pull request.
11713
+ ` ${AI_REVIEW_FORK_VAR}: \${{ github.event.pull_request.head.repo.full_name != github.repository }}`,
11698
11714
  // AC-3. This step POSTS the threads, so it is the one that can create a
11699
11715
  // duplicate, and until now it was the only reader handed no suppression
11700
11716
  // gate — the adjudicator dropped a repeat from its annotation while this
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}
@@ -509,6 +509,68 @@ export function stageLadderViolations(raw: unknown): string[] {
509
509
  });
510
510
  });
511
511
 
512
+ out.push(...duplicateVerifyViolations(raw));
513
+ return out;
514
+ }
515
+
516
+ /**
517
+ * Two items proved by one command — #2236.
518
+ *
519
+ * They can never disagree, so the second is never checked as its own claim:
520
+ * whatever makes the first true makes the second true, which is the
521
+ * done-condition restated that AGENTS.md rule 10 forbids. On #2221, E4's first
522
+ * proof was B4's `criteria-field` reading copied byte for byte, and only
523
+ * review caught it.
524
+ *
525
+ * Across the WHOLE ladder, not within a stage, because that is where it
526
+ * happened. Compared after trimming, so a copied command with a stray newline
527
+ * is still the same command. A null verify is an item nobody has written a
528
+ * proof for yet, and two of those duplicate nothing.
529
+ *
530
+ * Retro improvements are in the same population (review of #2243): an
531
+ * improvement's verify proves a mechanism is in place, which is a claim of
532
+ * the same kind, and the live plan carried #1849's improvement in two retros
533
+ * with one command until #2245. An improvement is named by its stage and its
534
+ * 1-based position, `"C retro improvement 2"`, because it has no id.
535
+ */
536
+ function duplicateVerifyViolations(raw: unknown[]): string[] {
537
+ const proofs: { id: string; verify: unknown }[] = [];
538
+ for (const s of raw) {
539
+ const stage = s as { id?: unknown; items?: unknown; retro?: unknown } | null;
540
+ if (stage === null || typeof stage !== "object") continue;
541
+ if (Array.isArray(stage.items)) {
542
+ for (const it of stage.items) {
543
+ const item = it as { id?: unknown; verify?: unknown } | null;
544
+ if (item !== null && typeof item === "object") proofs.push({ id: String(item.id), verify: item.verify });
545
+ }
546
+ }
547
+ const improvements = (stage.retro as { improvements?: unknown } | null)?.improvements;
548
+ if (Array.isArray(improvements)) {
549
+ improvements.forEach((imp, k) => {
550
+ const i = imp as { verify?: unknown } | null;
551
+ if (i !== null && typeof i === "object") {
552
+ proofs.push({ id: `${String(stage.id)} retro improvement ${k + 1}`, verify: i.verify });
553
+ }
554
+ });
555
+ }
556
+ }
557
+ const first = new Map<string, string>();
558
+ const out: string[] = [];
559
+ for (const { id, verify } of proofs) {
560
+ if (typeof verify !== "string") continue;
561
+ const cmd = verify.trim();
562
+ if (cmd === "") continue;
563
+ const earlier = first.get(cmd);
564
+ if (earlier === undefined) {
565
+ first.set(cmd, id);
566
+ continue;
567
+ }
568
+ out.push(
569
+ `"${earlier}" and "${id}" carry the same verify command, so they can never disagree and ` +
570
+ `"${id}" is never checked as its own claim — a done-condition restated (AGENTS.md rule 10). ` +
571
+ `Give "${id}" a command that reads what only it claims.`,
572
+ );
573
+ }
512
574
  return out;
513
575
  }
514
576
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.21",
3
+ "version": "0.8.23",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -37,6 +37,7 @@
37
37
  "scripts/board-ready.ts",
38
38
  "scripts/board-id.ts",
39
39
  "scripts/unaccounted-work.ts",
40
+ "scripts/intake.ts",
40
41
  "scripts/board-intake-move.ts",
41
42
  "scripts/audit-closing-references.ts",
42
43
  "scripts/create-spec.ts",
@@ -200,6 +200,31 @@ export interface BoardSnapshot {
200
200
  * UNMEASURED — same convention as {@link closedBlockers}.
201
201
  */
202
202
  declaredWork?: DeclaredWork[];
203
+
204
+ /**
205
+ * EVERY open issue in ANY phase-milestone family, with the board's Criteria
206
+ * column — #2223, stage item E4.
207
+ *
208
+ * Distinct from {@link issues}, which is the one family `--prefix` names
209
+ * (B4's population). E4 is "the board column reflects the bodies" for the
210
+ * rest of the specs too, and measuring it on `issues` would restate B4's
211
+ * done-condition (AGENTS.md rule 10).
212
+ *
213
+ * **Absent means the producer never read the column for them**, and
214
+ * `criteria-field-all` goes UNMEASURED. A row without `criteriaField` is a
215
+ * column that was not read for that issue, the same convention as
216
+ * {@link BoardIssue.criteriaField}.
217
+ */
218
+ familyIssues?: FamilyIssue[];
219
+ }
220
+
221
+ /** One open issue in some phase-milestone family — #2223 / E4. */
222
+ export interface FamilyIssue {
223
+ number: number;
224
+ /** The milestone family: `Pipeline`, `Convergence`, or `""` for bare `Phase N` titles. */
225
+ family: string;
226
+ /** Absent: not read. `null`: read and empty. */
227
+ criteriaField?: string | null;
203
228
  }
204
229
 
205
230
  /** One piece of declared work — SC-2752. */
@@ -623,6 +648,37 @@ export const READINGS: readonly ReadingSpec[] = [
623
648
  .filter(i => i.names.length === 0 && !i.servesNone)
624
649
  .map(i => `#${i.number} — names no criterion and does not declare that it serves none`),
625
650
  },
651
+ {
652
+ name: "criteria-field-all",
653
+ item: "E4",
654
+ what: "the board's Criteria column is populated for every open issue in every phase-milestone family, not only the engine's",
655
+ readsIssueRefs: false,
656
+ // The same two refusals as B4's `criteria-field`, over a different
657
+ // population. ANY row missing the key is unread, never short: dropping
658
+ // it from the denominator would make the reading easier the less of the
659
+ // board was looked at.
660
+ unreadable: b => {
661
+ if (b.familyIssues === undefined) {
662
+ return (
663
+ "the open issues of every milestone family were never read with their Criteria column — " +
664
+ "`issues` above is the engine family only, which is B4's population"
665
+ );
666
+ }
667
+ const unread = b.familyIssues.filter(i => !("criteriaField" in i)).map(i => `#${i.number}`);
668
+ return unread.length === 0
669
+ ? null
670
+ : `the Criteria column was not read for ${unread.length} of ${b.familyIssues.length} family issue(s) ` +
671
+ `(${unread.slice(0, 5).join(", ")}${unread.length > 5 ? ", …" : ""}) — that is not an empty column`;
672
+ },
673
+ measure: b => ({
674
+ measured: b.familyIssues!.filter(i => (i.criteriaField ?? "").trim() !== "").length,
675
+ target: b.familyIssues!.length,
676
+ }),
677
+ offenders: b =>
678
+ b.familyIssues!
679
+ .filter(i => (i.criteriaField ?? "").trim() === "")
680
+ .map(i => `#${i.number} (${i.family}) — the Criteria column is empty`),
681
+ },
626
682
  {
627
683
  name: "dependency-edges",
628
684
  item: "E3",
@@ -1073,6 +1129,12 @@ export function readSnapshotText(text: string): SnapshotRead {
1073
1129
  const declaredRows = Array.isArray(raw.declaredWork) ? raw.declaredWork.map(normaliseDeclaredWork) : null;
1074
1130
  const declared =
1075
1131
  declaredRows !== null && declaredRows.every(w => w !== null) ? { declaredWork: declaredRows as DeclaredWork[] } : {};
1132
+ // #2223 / E4. The declared-work rule, for the declared-work reason: one
1133
+ // row this command cannot identify unreads the whole population, because
1134
+ // dropping it would shorten the denominator `criteria-field-all` counts.
1135
+ const familyRows = Array.isArray(raw.familyIssues) ? raw.familyIssues.map(normaliseFamilyIssue) : null;
1136
+ const family =
1137
+ familyRows !== null && familyRows.every(f => f !== null) ? { familyIssues: familyRows as FamilyIssue[] } : {};
1076
1138
 
1077
1139
  return {
1078
1140
  board: {
@@ -1086,11 +1148,23 @@ export function readSnapshotText(text: string): SnapshotRead {
1086
1148
  ...repoIssues,
1087
1149
  ...edges,
1088
1150
  ...declared,
1151
+ ...family,
1089
1152
  },
1090
1153
  why: null,
1091
1154
  };
1092
1155
  }
1093
1156
 
1157
+ /** One family-issue row, or `null` for one this command cannot identify — #2223 / E4. */
1158
+ function normaliseFamilyIssue(raw: unknown): FamilyIssue | null {
1159
+ if (typeof raw !== "object" || raw === null) return null;
1160
+ const r = raw as Record<string, unknown>;
1161
+ if (typeof r.number !== "number" || !Number.isInteger(r.number) || typeof r.family !== "string") return null;
1162
+ // Present-only, like `BoardIssue.criteriaField`: absence is "not read".
1163
+ if (!("criteriaField" in r)) return { number: r.number, family: r.family };
1164
+ if (r.criteriaField !== null && typeof r.criteriaField !== "string") return null;
1165
+ return { number: r.number, family: r.family, criteriaField: r.criteriaField as string | null };
1166
+ }
1167
+
1094
1168
  /** One declared-work row, or `null` for one this command cannot identify — SC-2752. */
1095
1169
  function normaliseDeclaredWork(raw: unknown): DeclaredWork | null {
1096
1170
  if (raw === null || typeof raw !== "object") return null;
@@ -54,6 +54,7 @@ import {
54
54
  } from "../lib/live-issues";
55
55
  import {
56
56
  criterionCoverage,
57
+ familyOf,
57
58
  milestonePlan,
58
59
  placementCoverage,
59
60
  placementReading,
@@ -62,7 +63,7 @@ import {
62
63
  // SC-2615, SC-2616, SC-2617 — the three repository-wide populations.
63
64
  import { answerableIds, criterionAnswer, specCriteriaIn, specPathSweep } from "../lib/board-mirror";
64
65
  import { dependencyPlan } from "../lib/spec-deps";
65
- import type { DeclaredWork, PlannedEdge, RepoIssueCriteria, SpecDeferral, SpecPlacementRow } from "./board-conformance";
66
+ import type { DeclaredWork, FamilyIssue, PlannedEdge, RepoIssueCriteria, SpecDeferral, SpecPlacementRow } from "./board-conformance";
66
67
  import { parseCriteria } from "../lib/spec-evidence";
67
68
 
68
69
  /**
@@ -243,6 +244,8 @@ export interface ProducedSnapshot {
243
244
  plannedEdges?: PlannedEdge[];
244
245
  /** SC-2752: unticked criteria in in-scope specs and open stage items. Absent when it could not be read. */
245
246
  declaredWork?: DeclaredWork[];
247
+ /** #2223 / E4: every open issue in any phase-milestone family, with the Criteria column. Absent when the column was not read. */
248
+ familyIssues?: FamilyIssue[];
246
249
  }
247
250
 
248
251
  /**
@@ -735,7 +738,13 @@ export async function main(
735
738
  // report `0 of N — N short` for a column nobody finished reading.
736
739
  const criteria = new Map<number, ProjectFieldReading>();
737
740
  const board = readBoardConfig(root);
738
- if (board !== null && engine.length > 0) {
741
+ // #2223 / E4: every OPEN issue in ANY phase-milestone family, read in the
742
+ // same query as the engine's so one answer covers both populations.
743
+ const familyOpen = liveIssues.filter(i => i.state === "OPEN" && familyOf(i.milestone) !== null);
744
+ const fieldNumbers = [...new Set([...engine.map(i => i.number), ...familyOpen.map(i => i.number)])];
745
+ /** True only when `readFieldValues` answered; anything else is "not read". */
746
+ let columnQueried = false;
747
+ if (board !== null && fieldNumbers.length > 0) {
739
748
  try {
740
749
  const identity = await gh.readFieldIdentity(board.criteriaFieldId);
741
750
  if (identity.projectId !== board.projectId) {
@@ -750,12 +759,13 @@ export async function main(
750
759
  } else {
751
760
  for (const [number, reading] of await gh.readFieldValues(
752
761
  repo,
753
- engine.map(i => i.number),
762
+ fieldNumbers,
754
763
  board.projectId,
755
764
  identity.name,
756
765
  )) {
757
766
  criteria.set(number, reading);
758
767
  }
768
+ columnQueried = true;
759
769
  }
760
770
  } catch (e) {
761
771
  console.error(
@@ -881,9 +891,13 @@ export async function main(
881
891
  // for a truncated `blockedBy` among other reasons, and a truncated read
882
892
  // produces exactly the false `missing` edges this reading would then count
883
893
  // as the tracker's failure.
894
+ //
895
+ // `!== "MEASURED"`, not `=== "UNMEASURED"` (#2239): a one-phase tracker is
896
+ // NOTHING_TO_SEQUENCE, and its empty plan is no order at all, so it omits
897
+ // the key too rather than reading as 0 of 0 derived edges.
884
898
  const plan = dependencyPlan(liveIssues);
885
899
  const edges =
886
- plan.reading === "UNMEASURED"
900
+ plan.reading !== "MEASURED"
887
901
  ? {}
888
902
  : {
889
903
  plannedEdges: [
@@ -898,6 +912,19 @@ export async function main(
898
912
  // UNMEASURED rather than a stage-only count.
899
913
  const declared = placements.specPlacements === undefined ? {} : readDeclaredWork(root, placements.specPlacements);
900
914
 
915
+ // #2223 / E4. Emitted only when the column was actually queried: no board,
916
+ // a mismatched field, or a failed read all omit the key, and
917
+ // `criteria-field-all` is then UNMEASURED on its own.
918
+ const family = columnQueried
919
+ ? {
920
+ familyIssues: familyOpen.map(i => ({
921
+ number: i.number,
922
+ family: familyOf(i.milestone) as string,
923
+ ...criteriaKey(i.number),
924
+ })),
925
+ }
926
+ : {};
927
+
901
928
  const snapshot: ProducedSnapshot = {
902
929
  producedAt: new Date().toISOString(),
903
930
  spec: specArg,
@@ -911,6 +938,7 @@ export async function main(
911
938
  ...repoIssues,
912
939
  ...edges,
913
940
  ...declared,
941
+ ...family,
914
942
  };
915
943
 
916
944
  process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
@@ -0,0 +1,101 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * `rungate intake` — run the registered intake sources and print each one's
4
+ * reading (#2248).
5
+ *
6
+ * Before this, nothing outside `lib/intake-sources.ts` called
7
+ * `mineObservedFailures`, so no command ran intake at all. Jason decided on
8
+ * #1126 (2026-11-15) that each source runs on its own trigger: `fix-commits`
9
+ * in CI on push to main with full history (#2233), `gate-refusals` at the end
10
+ * of a ship run (#2234). Both call this.
11
+ *
12
+ * ADVISORY. A source that cannot be read here prints UNMEASURED with the
13
+ * producer's own reason and the command still exits 0: a shallow clone or an
14
+ * absent run store says nothing about the change that triggered the run, so
15
+ * it must never turn that run red. UNMEASURED is printed, never a silent
16
+ * zero, and the partial count of an unmeasured reading is never printed as
17
+ * the reading (`AggregateIntakeReading` withholds `candidates` there for the
18
+ * same reason). A bad argument is the only refusal.
19
+ */
20
+ import { resolve } from "path";
21
+ import {
22
+ INTAKE_SOURCES,
23
+ defaultIntakeContext,
24
+ mineObservedFailures,
25
+ type IntakeContext,
26
+ } from "../lib/intake-sources";
27
+
28
+ /** A bad argument. The only non-zero exit: every reading exits 0. */
29
+ export const EXIT_REFUSED = 2;
30
+
31
+ const USAGE =
32
+ "rungate intake [--project-root <dir>] [--source <id>] [--json] " +
33
+ `(sources: ${INTAKE_SOURCES.map(s => s.id).join(", ")}; advisory — an unreadable source prints UNMEASURED and exits 0)`;
34
+
35
+ /**
36
+ * `deps.workStore` overrides the run store, so a test reads a fixture rather
37
+ * than this machine's `~/.rungate`. Absent, `defaultIntakeContext` decides,
38
+ * which reads `RUNGATE_WORK_DIR` through `lib/paths.ts`.
39
+ */
40
+ export function main(argv: readonly string[], deps: { workStore?: string } = {}): number {
41
+ let rootArg: string | undefined;
42
+ let source: string | undefined;
43
+ let json = false;
44
+ for (let i = 0; i < argv.length; i++) {
45
+ const a = argv[i];
46
+ if (a === "--json") {
47
+ json = true;
48
+ } else if (a === "--project-root" || a === "--source") {
49
+ const next = argv[i + 1];
50
+ if (next === undefined || next.startsWith("--")) {
51
+ console.error(`intake: ${a} needs a value after it. Nothing was read.\n${USAGE}`);
52
+ return EXIT_REFUSED;
53
+ }
54
+ if (a === "--project-root") rootArg = next;
55
+ else source = next;
56
+ i++;
57
+ } else {
58
+ console.error(`intake: unknown argument ${JSON.stringify(a)}. Nothing was read.\n${USAGE}`);
59
+ return EXIT_REFUSED;
60
+ }
61
+ }
62
+
63
+ const sources = source === undefined ? INTAKE_SOURCES : INTAKE_SOURCES.filter(s => s.id === source);
64
+ if (sources.length === 0) {
65
+ console.error(
66
+ `intake: no source is named ${JSON.stringify(source)}. The registered sources are ` +
67
+ `${INTAKE_SOURCES.map(s => s.id).join(", ")}. Nothing was read.`,
68
+ );
69
+ return EXIT_REFUSED;
70
+ }
71
+
72
+ const root = resolve(rootArg ?? process.cwd());
73
+ const base = defaultIntakeContext(root);
74
+ const ctx: IntakeContext = deps.workStore === undefined ? base : { ...base, workStore: deps.workStore };
75
+ const reading = mineObservedFailures(ctx, sources);
76
+
77
+ if (json) {
78
+ console.log(JSON.stringify(reading, null, 2));
79
+ return 0;
80
+ }
81
+
82
+ for (const s of sources) {
83
+ const r = reading.bySource[s.id];
84
+ if (r.reading === "MEASURED") {
85
+ console.log(
86
+ `${s.id}: MEASURED — ${r.candidates.length} candidate(s) from ${r.commitsScanned} unit(s) of history read`,
87
+ );
88
+ } else {
89
+ console.log(`${s.id}: UNMEASURED — ${r.unmeasuredReasons.join("; ")}`);
90
+ }
91
+ }
92
+ console.log(
93
+ reading.reading === "MEASURED"
94
+ ? `intake: MEASURED — ${reading.candidates.length} candidate(s) across ${sources.length} source(s)`
95
+ : `intake: UNMEASURED — ${reading.unmeasuredReasons.length} reason(s) above; ` +
96
+ `${reading.partialCandidates.length} candidate(s) came from the sources that could be read, and are not a reading`,
97
+ );
98
+ return 0;
99
+ }
100
+
101
+ if (import.meta.main) process.exitCode = main(process.argv.slice(2));
@@ -284,7 +284,9 @@ export async function main(argv: string[], gh: PlanDepsGitHub = LIVE_GITHUB): Pr
284
284
  ? "not-requested"
285
285
  : refuseWrite
286
286
  ? "refused"
287
- : failures.length > 0
287
+ : plan.reading === "NOTHING_TO_SEQUENCE"
288
+ ? "nothing-to-sequence"
289
+ : failures.length > 0
288
290
  ? "partial"
289
291
  : "yes";
290
292
  console.log(JSON.stringify({ ...plan, results, wrote }, null, 2));
@@ -327,6 +329,18 @@ export async function main(argv: string[], gh: PlanDepsGitHub = LIVE_GITHUB): Pr
327
329
  console.log(` ${plan.unphased.length} issue(s) carry no Phase milestone and get no edge.`);
328
330
  }
329
331
 
332
+ // #2239: one phase over a sound read. Never the "already carries" sentence
333
+ // below — an empty plan from one phase is not a sequenced tracker — and
334
+ // never a refusal, because nothing was left unread. `missing` is empty by
335
+ // construction, so there is no write to skip.
336
+ if (plan.reading === "NOTHING_TO_SEQUENCE") {
337
+ console.log(
338
+ `\nNothing written: nothing to sequence: every ${values["include-closed"] ? "" : "open "}issue ` +
339
+ `sits in Phase ${plan.phases[0]}. One phase states no order, so no edge is missing and none is derived.`,
340
+ );
341
+ return 0;
342
+ }
343
+
330
344
  if (!values.write) {
331
345
  console.log(
332
346
  plan.missing.length > 0