rungate 0.8.13 → 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 (88) hide show
  1. package/README.md +182 -0
  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/VerifyPhaseLock.hook.ts +3 -3
  8. package/hooks/lib/findWorkflow.ts +3 -2
  9. package/hooks/lib/paths.ts +14 -2
  10. package/hooks/lib/utils.ts +23 -3
  11. package/lib/active-milestone.ts +50 -0
  12. package/lib/ai-review-rounds.ts +99 -0
  13. package/lib/ai-review-suppression.ts +200 -21
  14. package/lib/bash-write-guard.ts +397 -23
  15. package/lib/board-flow.ts +280 -0
  16. package/lib/board-lane-health.ts +578 -0
  17. package/lib/board-mirror.ts +136 -39
  18. package/lib/board-ready-fanout.ts +297 -14
  19. package/lib/board-ready-rule.ts +1211 -0
  20. package/lib/board-throughput.ts +136 -0
  21. package/lib/board-walkthrough.ts +240 -0
  22. package/lib/body-evidence.ts +203 -0
  23. package/lib/branch-protection.ts +399 -9
  24. package/lib/bun-version.ts +36 -0
  25. package/lib/cli-commands.ts +75 -4
  26. package/lib/closing-reference-audit.ts +307 -6
  27. package/lib/config-loader.ts +254 -25
  28. package/lib/config-readers.ts +170 -10
  29. package/lib/config-trackable.ts +96 -57
  30. package/lib/conformity.ts +121 -7
  31. package/lib/create-sc.ts +25 -2
  32. package/lib/derived-spec.ts +21 -9
  33. package/lib/filing-compliance.ts +367 -0
  34. package/lib/filing-plan.ts +47 -21
  35. package/lib/finding-arbiter.ts +79 -5
  36. package/lib/finding-jury.ts +43 -4
  37. package/lib/finding-promotion.ts +1123 -0
  38. package/lib/generators/agents-md.ts +149 -0
  39. package/lib/git-isolation.ts +137 -1
  40. package/lib/github-api-base.ts +66 -0
  41. package/lib/github.ts +194 -9
  42. package/lib/graphql-cursor.ts +80 -0
  43. package/lib/hook-scopes.ts +78 -0
  44. package/lib/issue-create-override.ts +415 -3
  45. package/lib/issue-decomposition.ts +124 -7
  46. package/lib/issue-extraction.ts +9 -7
  47. package/lib/issue-file-overlap.ts +373 -0
  48. package/lib/issue-filing-gate.ts +1109 -52
  49. package/lib/issue-repair.ts +90 -9
  50. package/lib/issue-shape.ts +199 -0
  51. package/lib/live-issues.ts +31 -2
  52. package/lib/local-work.ts +423 -0
  53. package/lib/markdown-fence.ts +134 -0
  54. package/lib/milestone-title.ts +46 -0
  55. package/lib/scaffold/ai-review-findings.ts +148 -3
  56. package/lib/scaffold/ai-review-step.ts +65 -5
  57. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  58. package/lib/scaffold/steps.ts +115 -9
  59. package/lib/source-census.ts +108 -0
  60. package/lib/spec-deps.ts +55 -11
  61. package/lib/spec-placement.ts +203 -13
  62. package/lib/spec-registry.ts +75 -16
  63. package/lib/spec-source.ts +609 -0
  64. package/lib/spec-write-sweep.ts +4 -0
  65. package/lib/stage-ladder.ts +896 -3
  66. package/lib/state-claim-readings.ts +252 -0
  67. package/lib/success-doc.ts +7 -6
  68. package/lib/test-command-positions.ts +135 -1
  69. package/lib/work-status.ts +551 -0
  70. package/lib/worktree-repo.ts +14 -2
  71. package/package.json +7 -1
  72. package/scripts/ai-review-findings.ts +8 -13
  73. package/scripts/ai-review-threads.ts +16 -17
  74. package/scripts/audit-closing-references.ts +330 -0
  75. package/scripts/audit-specs.ts +59 -103
  76. package/scripts/board-conformance.ts +747 -40
  77. package/scripts/board-mirror.ts +594 -13
  78. package/scripts/board-ready.ts +979 -0
  79. package/scripts/board-snapshot.ts +464 -12
  80. package/scripts/claim-files.ts +578 -0
  81. package/scripts/criterion-inventory.ts +526 -50
  82. package/scripts/finding-promotion.ts +547 -0
  83. package/scripts/generate-code-map.ts +1 -1
  84. package/scripts/plan-issues.ts +279 -40
  85. package/scripts/plan-spec.ts +105 -3
  86. package/scripts/sync-sc-status.ts +147 -7
  87. package/scripts/worktree-census.ts +958 -0
  88. package/scripts/worktree-sweep.ts +269 -0
@@ -252,8 +252,13 @@ function trackedAndIgnoredPaths(root: string): TrackableReading {
252
252
  * `worktrees/` and everything else stay ignored exactly as before.
253
253
  * 3./4. the two config locations, re-included by name.
254
254
  */
255
- export function configTrackabilityBlock(): string {
255
+ export function configTrackabilityBlock(opts: { parentExcluded?: boolean } = {}): string {
256
256
  const parent = RUNGATE_CONFIG_PARENT_DIR;
257
+ // #2071: lines 1-2 are needed ONLY when the parent directory itself is
258
+ // excluded. Under a `.claude/*` rule git already descends into it, and a
259
+ // second `.claude/*` appended here re-ignores every directory the project
260
+ // re-included above this block — 128 tracked files on the consumer that reported it.
261
+ const parentLines = opts.parentExcluded === false ? [] : [`!${parent}/`, `${parent}/*`];
257
262
  return [
258
263
  "",
259
264
  `# Added by rungate scaffold: the harness config must survive a branch`,
@@ -267,8 +272,7 @@ export function configTrackabilityBlock(): string {
267
272
  `# (\`${RUNGATE_CONFIG_DIR}/nested/config.json\`) and any file this list does`,
268
273
  `# not name. Ignored is the safe side of the default for a path nobody has`,
269
274
  `# thought of yet; a new config file is a change to this list.`,
270
- `!${parent}/`,
271
- `${parent}/*`,
275
+ ...parentLines,
272
276
  `!${RUNGATE_CONFIG_DIR}/`,
273
277
  `${RUNGATE_CONFIG_DIR}/*`,
274
278
  ...DIRECTORY_CONFIG_FILES.map(f => `!${RUNGATE_CONFIG_DIR}/${f}`),
@@ -277,6 +281,67 @@ export function configTrackabilityBlock(): string {
277
281
  ].join("\n");
278
282
  }
279
283
 
284
+ type EditOutcome = { kind: "ok" } | { kind: "still-ignored" | "refused"; why: string };
285
+
286
+ /**
287
+ * Whether the block just written made the config committable and changed
288
+ * nothing else. Pure measurement; the caller reverts on anything but `ok`.
289
+ */
290
+ function verifyTrackableEdit(root: string, trackedBefore: string[], ignoredBefore: string[]): EditOutcome {
291
+ const after = configPathsIgnored(root);
292
+ if (after.failure !== null) return { kind: "refused", why: `could not verify the edit worked — ${after.failure}` };
293
+ if (after.ignored.length > 0) {
294
+ // The rule is not `.claude/`-shaped, so this block cannot reach it.
295
+ // Name the rule rather than the guess: `check-ignore -v` reports the
296
+ // source file, line and pattern, which is what a consumer needs.
297
+ const why = git(root, ["check-ignore", "--no-index", "-v", ...after.ignored]);
298
+ return {
299
+ kind: "still-ignored",
300
+ why:
301
+ `the rungate config is still ignored after the negation — ${after.ignored.join(", ")}` +
302
+ (why.stdout.trim() ? ` (matched by ${why.stdout.trim().split("\n").join("; ")})` : "") +
303
+ `. Un-ignore it by hand; a config git treats as disposable is deleted by an ordinary branch switch`,
304
+ };
305
+ }
306
+
307
+ const trackedAfter = trackedAndIgnoredPaths(root);
308
+ if (trackedAfter.failure !== null) {
309
+ return { kind: "refused", why: `could not verify the edit ignored nothing new — ${trackedAfter.failure}` };
310
+ }
311
+ const newlyIgnored = trackedAfter.ignored.filter(p => !trackedBefore.includes(p));
312
+ if (newlyIgnored.length > 0) {
313
+ return {
314
+ kind: "refused",
315
+ why:
316
+ `the negation would newly ignore ${newlyIgnored.length} tracked file(s) — ` +
317
+ `${newlyIgnored.slice(0, 3).join(", ")}${newlyIgnored.length > 3 ? ", …" : ""}`,
318
+ };
319
+ }
320
+
321
+ // The symmetric half, and the one that generalises. Exactly the config
322
+ // paths may leave the ignored set; a glob that reaches one path further
323
+ // than intended shows up here as a file that stopped being ignored, and
324
+ // that is a REFUSAL rather than a surprise in three consumers' trees.
325
+ const ignoredAfter = ignoredPaths(root);
326
+ if (ignoredAfter.failure !== null) {
327
+ return { kind: "refused", why: `could not verify the edit un-ignored nothing else — ${ignoredAfter.failure}` };
328
+ }
329
+ const stillIgnored = new Set(ignoredAfter.ignored);
330
+ const unIgnored = ignoredBefore.filter(
331
+ p => !stillIgnored.has(p) && !(RUNGATE_CONFIG_IGNORE_PATHS as readonly string[]).includes(p)
332
+ && !isConfigFragment(p),
333
+ );
334
+ if (unIgnored.length > 0) {
335
+ return {
336
+ kind: "refused",
337
+ why:
338
+ `the negation reaches further than the config — ${unIgnored.length} other file(s) stopped ` +
339
+ `being ignored: ${unIgnored.slice(0, 3).join(", ")}${unIgnored.length > 3 ? ", …" : ""}`,
340
+ };
341
+ }
342
+ return { kind: "ok" };
343
+ }
344
+
280
345
  /**
281
346
  * Make the rungate config committable, or say plainly that it could not be.
282
347
  *
@@ -301,7 +366,7 @@ export function configTrackabilityBlock(): string {
301
366
  export function ensureConfigTrackable(
302
367
  root: string,
303
368
  actions: string[],
304
- block: string = configTrackabilityBlock(),
369
+ blockOverride?: string,
305
370
  ): void {
306
371
  const before = configPathsIgnored(root);
307
372
  if (before.failure !== null) {
@@ -327,69 +392,43 @@ export function ensureConfigTrackable(
327
392
  return;
328
393
  }
329
394
 
330
- writeFileSync(gitignorePath, original.trimEnd() + "\n" + block);
395
+ // Which block (#2071). NOT decided by probing whether `.claude` itself is
396
+ // excluded: a bare-path probe can only match a directory-only `.claude/`
397
+ // rule by stat-ing the directory, and on a first scaffold there is none,
398
+ // so it reads `.claude/` as `.claude/*` (review of #2071). Instead the
399
+ // narrow block is TRIED first — it is the one that cannot re-ignore
400
+ // directories a `.claude/*` project re-included — and the full block is
401
+ // tried only when the narrow one leaves the config ignored, which is
402
+ // exactly the `.claude/`-excluded case. A caller-supplied block is tried
403
+ // alone. Every attempt is measured by the same checks and reverted
404
+ // byte-for-byte when it fails.
405
+ const attempts = blockOverride !== undefined
406
+ ? [blockOverride]
407
+ : [configTrackabilityBlock({ parentExcluded: false }), configTrackabilityBlock({ parentExcluded: true })];
331
408
 
332
409
  // Byte-for-byte, and the file is REMOVED rather than blanked when there
333
410
  // was none: a project that acquires an empty `.gitignore` from a step that
334
411
  // reported a refusal has been changed by a step that said it changed
335
412
  // nothing.
336
- const revert = (why: string) => {
413
+ const restore = () => {
337
414
  if (had) writeFileSync(gitignorePath, original);
338
415
  else unlinkSync(gitignorePath);
339
- actions.push(`REFUSED: .gitignore (${why})`);
340
416
  };
341
417
 
342
- const after = configPathsIgnored(root);
343
- if (after.failure !== null) {
344
- revert(`could not verify the edit worked — ${after.failure}`);
345
- return;
346
- }
347
- if (after.ignored.length > 0) {
348
- // The rule is not `.claude/`-shaped, so this block cannot reach it.
349
- // Name the rule rather than the guess: `check-ignore -v` reports the
350
- // source file, line and pattern, which is what a consumer needs.
351
- const why = git(root, ["check-ignore", "--no-index", "-v", ...after.ignored]);
352
- revert(
353
- `the rungate config is still ignored after the negation — ${after.ignored.join(", ")}` +
354
- (why.stdout.trim() ? ` (matched by ${why.stdout.trim().split("\n").join("; ")})` : "") +
355
- `. Un-ignore it by hand; a config git treats as disposable is deleted by an ordinary branch switch`,
356
- );
357
- return;
358
- }
359
-
360
- const trackedAfter = trackedAndIgnoredPaths(root);
361
- if (trackedAfter.failure !== null) {
362
- revert(`could not verify the edit ignored nothing new — ${trackedAfter.failure}`);
363
- return;
364
- }
365
- const newlyIgnored = trackedAfter.ignored.filter(p => !trackedBefore.ignored.includes(p));
366
- if (newlyIgnored.length > 0) {
367
- revert(
368
- `the negation would newly ignore ${newlyIgnored.length} tracked file(s) — ` +
369
- `${newlyIgnored.slice(0, 3).join(", ")}${newlyIgnored.length > 3 ? ", …" : ""}`,
370
- );
371
- return;
372
- }
373
-
374
- // The symmetric half, and the one that generalises. Exactly the config
375
- // paths may leave the ignored set; a glob that reaches one path further
376
- // than intended shows up here as a file that stopped being ignored, and
377
- // that is a REFUSAL rather than a surprise in three consumers' trees.
378
- const ignoredAfter = ignoredPaths(root);
379
- if (ignoredAfter.failure !== null) {
380
- revert(`could not verify the edit un-ignored nothing else — ${ignoredAfter.failure}`);
381
- return;
418
+ let refusal: string | null = null;
419
+ for (let i = 0; i < attempts.length; i++) {
420
+ writeFileSync(gitignorePath, original.trimEnd() + "\n" + attempts[i]);
421
+ const outcome = verifyTrackableEdit(root, trackedBefore.ignored, ignoredBefore.ignored);
422
+ if (outcome.kind === "ok") { refusal = null; break; }
423
+ restore();
424
+ refusal = outcome.why;
425
+ // Only "still ignored" earns the wider block. A narrow block that
426
+ // ignored or un-ignored too much is refused as it is: the wider block
427
+ // carries every line the narrow one does, so it could only do more.
428
+ if (outcome.kind !== "still-ignored") break;
382
429
  }
383
- const stillIgnored = new Set(ignoredAfter.ignored);
384
- const unIgnored = ignoredBefore.ignored.filter(
385
- p => !stillIgnored.has(p) && !(RUNGATE_CONFIG_IGNORE_PATHS as readonly string[]).includes(p)
386
- && !isConfigFragment(p),
387
- );
388
- if (unIgnored.length > 0) {
389
- revert(
390
- `the negation reaches further than the config — ${unIgnored.length} other file(s) stopped ` +
391
- `being ignored: ${unIgnored.slice(0, 3).join(", ")}${unIgnored.length > 3 ? ", …" : ""}`,
392
- );
430
+ if (refusal !== null) {
431
+ actions.push(`REFUSED: .gitignore (${refusal})`);
393
432
  return;
394
433
  }
395
434
 
package/lib/conformity.ts CHANGED
@@ -36,14 +36,19 @@ import {
36
36
  } from "./behavioral-cache";
37
37
  import { tryLoadRungateConfig } from "./config-loader";
38
38
  import {
39
+ type ProtectionFacts,
39
40
  type ProtectionProbe,
40
41
  githubProtectionProbe,
41
42
  protectionSubject,
43
+ readFindingDisposition,
42
44
  readMergeSerialisation,
43
45
  readPushCi,
46
+ readThreadProducer,
47
+ unmeasuredPushCi,
44
48
  } from "./branch-protection";
45
49
  import { stripJsComments } from "./strip-js-comments";
46
50
  import { remedyMessage } from "./check-remedy";
51
+ import { governsOf, isValidGoverns } from "./spec-registry";
47
52
  import { parseScDeclarations } from "./sc-ids";
48
53
  import { isHarnessItself } from "./harness-identity";
49
54
  import {
@@ -1999,13 +2004,33 @@ export function runDocHygiene(
1999
2004
  const missing: string[] = [];
2000
2005
  for (const f of collectSpecFiles(specsDir)) { // #225 — subdirectories too
2001
2006
  const content = readFileSync(join(specsDir, f), "utf-8");
2002
- const fm = parseFrontmatter(content);
2003
- if (!fm) continue;
2004
- const governs = fm.governs || "";
2005
- if (!governs || governs.includes("TODO")) missing.push(f);
2007
+ if (!parseFrontmatter(content)) continue;
2008
+ // #1692 — the criteria used to be spelled out again here, identically
2009
+ // to `isValidGoverns`. Two deciders answering the same question about
2010
+ // the same input are behaviourally one, so neither could see that both
2011
+ // read `governs: >-` as the governs text itself.
2012
+ //
2013
+ // #1906 — and the value must come from the same EXTRACTOR as the
2014
+ // registry's, not from this file's general-purpose parser. That one
2015
+ // flattens a bare `governs:` block into `"a; b"` where the registry's
2016
+ // saw nothing at all, so the two readers disagreed one shape along
2017
+ // from the one the predicate had just been taught.
2018
+ if (!isValidGoverns(governsOf(content))) missing.push(f);
2006
2019
  }
2007
2020
  // Was unconditionally passing after a console.warn (#80).
2008
- expect(missing).toEqual([]);
2021
+ expect(
2022
+ missing,
2023
+ remedyMessage({
2024
+ root,
2025
+ check: "HYGIENE-1",
2026
+ violations: missing,
2027
+ fix:
2028
+ "give each spec a `governs:` saying what it governs, on ONE line. " +
2029
+ "A folded or literal block (`governs: >-` with the text indented " +
2030
+ "below) is refused: every reader in this tree captures the two " +
2031
+ "characters `>-` and never sees the prose (#1692).",
2032
+ }),
2033
+ ).toEqual([]);
2009
2034
  });
2010
2035
 
2011
2036
  test("HYGIENE-2: All specs have updated field in frontmatter", () => {
@@ -4973,6 +4998,24 @@ export function runBranchProtectionValidation(
4973
4998
  const probe = opts.probe ?? githubProtectionProbe;
4974
4999
  const subject = opts.subject ?? protectionSubject;
4975
5000
 
5001
+ /**
5002
+ * ONE protection reading per run, shared by both checks (#1858 round 4).
5003
+ *
5004
+ * PROTECT-2 called `probe` a second time for the same slug. That is three
5005
+ * more admin-scoped GETs per run, and worse than the cost: **two readings
5006
+ * of one branch inside one run can disagree.** The protection endpoint
5007
+ * 403s as its ORDINARY outcome on a consumer's default token, and a
5008
+ * secondary rate limit trips on the second round-trip rather than the
5009
+ * first — so a run could report PROTECT-1 clean and PROTECT-2 UNMEASURED
5010
+ * about the identical branch, with nothing in the output saying which
5011
+ * reading to believe.
5012
+ *
5013
+ * That is the same defect #1852 closed one lane over, reintroduced here by
5014
+ * the check that was written to catch a different instance of it.
5015
+ */
5016
+ let protectionOnce: Promise<ProtectionFacts> | null = null;
5017
+ const factsFor = (slug: string): Promise<ProtectionFacts> => (protectionOnce ??= probe(slug));
5018
+
4976
5019
  describe("Branch protection (#909)", () => {
4977
5020
  test("PROTECT-1: merging one PR does not invalidate every other open PR", async () => {
4978
5021
  const slug = subject(root);
@@ -4988,12 +5031,12 @@ export function runBranchProtectionValidation(
4988
5031
  return;
4989
5032
  }
4990
5033
 
4991
- const facts = await probe(slug);
5034
+ const facts = await factsFor(slug);
4992
5035
  // Read against the branch the FACTS are about. Defaulting to "main"
4993
5036
  // here would answer a question about a branch the repo may not protect.
4994
5037
  const pushCi = facts.branch
4995
5038
  ? readPushCi(root, facts.contexts, facts.branch)
4996
- : { onPush: [], missing: [], unmeasured: "UNMEASURED push-CI: the default branch is unknown, so no trigger could be matched against it." };
5039
+ : unmeasuredPushCi("the default branch is unknown, so no trigger could be matched against it");
4997
5040
  const reading = readMergeSerialisation(facts, pushCi);
4998
5041
 
4999
5042
  if (reading.verdict === "UNMEASURED") {
@@ -5020,6 +5063,77 @@ export function runBranchProtectionValidation(
5020
5063
  // written against the value rather than against the narrowing.
5021
5064
  expect(reading.verdict as string, message).toBe("PASS");
5022
5065
  });
5066
+
5067
+ /**
5068
+ * PROTECT-2 (#1650, CRC-C3) — a finding nobody answered blocks the merge.
5069
+ *
5070
+ * The same probe and the same facts object as PROTECT-1, one question
5071
+ * further on: `required_conversation_resolution`. It is the only
5072
+ * protection setting that can read a review thread, so it is the only one
5073
+ * that can tell *this finding was answered* from *nobody looked*.
5074
+ *
5075
+ * **It exists because the setting regressed in silence.** On this repo it
5076
+ * was applied 2026-10-23, read `true` 2026-10-25, and observably gating
5077
+ * three pull requests through 2026-10-27. On 2026-11-07 it read `false`
5078
+ * and #1857 merged with five unresolved threads. The field had no reader
5079
+ * anywhere in the tree, so the spec went on recording it as applied for
5080
+ * thirteen days. `lib/branch-protection.ts` carries the readings.
5081
+ *
5082
+ * FAILS, like PROTECT-1, and for the same reason: the thing that did not
5083
+ * work was writing it down.
5084
+ */
5085
+ test("PROTECT-2: a pull request cannot merge with a finding nobody answered", async () => {
5086
+ const slug = subject(root);
5087
+ if (!slug) {
5088
+ addFinding({
5089
+ ruleId: "PROTECT-2",
5090
+ severity: "WARN",
5091
+ file: "",
5092
+ message:
5093
+ "UNMEASURED: this tree's origin remote names no owner/name, so there is no repo to " +
5094
+ "read protection for. Nothing was checked, which is not the same as nothing being wrong.",
5095
+ });
5096
+ return;
5097
+ }
5098
+
5099
+ // **No short-circuit here, and the battery is why.** The first draft of
5100
+ // this returned early when `readThreadProducer` found no producer, on
5101
+ // the reasoning that round 1 applied inside `readFindingDisposition`:
5102
+ // do not consult a fact that cannot change the answer. Mutating that
5103
+ // branch away reddened NOTHING — predicted 1, observed 0.
5104
+ //
5105
+ // It was dead, and `factsFor` is why: PROTECT-1 has already taken the
5106
+ // reading on every path that reaches here, so the memo returns it and
5107
+ // no request is saved. Keeping the branch would have shipped a line
5108
+ // whose removal no case can observe, which is the shape this session
5109
+ // spent four rounds finding elsewhere
5110
+ // (`.claude/rules/checks-must-be-able-to-fail.md`).
5111
+ const producer = readThreadProducer(root);
5112
+ const facts = await factsFor(slug);
5113
+ const disposition = readFindingDisposition(facts, producer);
5114
+
5115
+ if (disposition.verdict === "UNMEASURED") {
5116
+ addFinding({ ruleId: "PROTECT-2", severity: "WARN", file: "", message: disposition.reason });
5117
+ return;
5118
+ }
5119
+ if (disposition.verdict === "PASS") return;
5120
+
5121
+ addFinding({
5122
+ ruleId: "PROTECT-2",
5123
+ severity: "FAIL",
5124
+ file: "",
5125
+ message: `${disposition.reason}\n\nREMEDY: ${disposition.remedy}`,
5126
+ // Reads. Never writes — the same line PROTECT-1 holds. A fixCommand
5127
+ // that PUT a protection payload would be the harness silently
5128
+ // rewriting a repository's security settings, and the operator's next
5129
+ // read of their own config would be a reading of what a tool decided.
5130
+ fixCommand: `gh api repos/${facts.slug}/branches/${facts.branch ?? "main"}/protection -q .required_conversation_resolution`,
5131
+ });
5132
+ // Widened for the same reason as PROTECT-1: control flow has narrowed
5133
+ // `verdict` to "FAIL", so the comparison typechecks as a contradiction
5134
+ // and reads as dead. It is what turns the finding into a red suite.
5135
+ expect(disposition.verdict as string, `${disposition.reason}\n\nREMEDY: ${disposition.remedy}`).toBe("PASS");
5136
+ });
5023
5137
  });
5024
5138
  }
5025
5139
 
package/lib/create-sc.ts CHANGED
@@ -9,7 +9,13 @@ import { join, dirname } from "path";
9
9
  import { fileURLToPath } from "url";
10
10
 
11
11
  import type { ScRegistry } from "./sc-ids";
12
- import { isFixtureScId, scIdsSpelledInSourceReading, SC_SOURCE_DIRS } from "./sc-ids";
12
+ import {
13
+ isFixtureScId,
14
+ parseScDeclarations,
15
+ parseScHeadingDeclarations,
16
+ scIdsSpelledInSourceReading,
17
+ SC_SOURCE_DIRS,
18
+ } from "./sc-ids";
13
19
  import type { ScNamespaceReading, SourceReading } from "./sc-id-cross-tree";
14
20
  import { readScNamespace } from "./sc-id-cross-tree";
15
21
  import type { ScReservation, ScReservationReading } from "./sc-reservations";
@@ -288,9 +294,26 @@ export function listPatterns(): string {
288
294
  * scans of the same string would be two deciders that agree, and a reading
289
295
  * whose numbers come from a different pattern than the allocation used is a
290
296
  * reading of something else.
297
+ *
298
+ * #2067: a fixture-range id the spec only MENTIONS is left out, exactly as it
299
+ * is for source above. One sentence citing `SC-9999` used to send the next
300
+ * criterion to `SC-10000`. A fixture-range id the spec DECLARES, as a checkbox
301
+ * or a `### SC-N:` heading, stays in: a declaration is authoritative at any
302
+ * number.
291
303
  */
292
304
  function idsInSpecContent(specContent: string): string[] {
293
- return [...specContent.matchAll(/SC-(\d+)/g)].map(m => m[0]);
305
+ // Indented checkboxes count as declarations here (review of #2128). The
306
+ // registry patterns anchor at column 0, and missing a nested declaration
307
+ // would hand its id out again; for an allocator, over-counting is safe.
308
+ const indented = [...specContent.matchAll(/^[ \t]+[-*][ \t]+\[[ xX]\][ \t]+(SC-\d+):/gm)].map(m => m[1]!);
309
+ const declared = new Set([
310
+ ...parseScDeclarations(specContent, "").map(d => d.id),
311
+ ...parseScHeadingDeclarations(specContent, "").map(d => d.id),
312
+ ...indented,
313
+ ]);
314
+ return [...specContent.matchAll(/SC-(\d+)/g)]
315
+ .map(m => m[0])
316
+ .filter(id => !isFixtureScId(id) || declared.has(id));
294
317
  }
295
318
 
296
319
  export function nextSCNumber(
@@ -70,15 +70,20 @@
70
70
  * costs a line in a report. A derived file wrongly written costs the
71
71
  * consumer's suite, and the edit is thrown away at the next regeneration.
72
72
  *
73
- * ## No relative imports, on purpose
74
- *
75
- * `test/derived-spec-guard.test.ts` builds a mutant copy of this file in an
76
- * `mkdtemp` directory and runs the real write path against it. A relative
77
- * import here would make that mutant die on module resolution, and a mutant
78
- * that failed to load is indistinguishable from a guard that held —
79
- * `.claude/rules/checks-must-be-able-to-fail.md`.
73
+ * ## One relative import, and the mutant trees carry it
74
+ *
75
+ * `test/derived-spec-guard.test.ts` and `test/spec-write-chokepoint.test.ts`
76
+ * build a mutant copy of this file in an `mkdtemp` directory and run the real
77
+ * write path against it. A relative import the copier did not carry would
78
+ * make that mutant die on module resolution, and a mutant that failed to load
79
+ * is indistinguishable from a guard that held —
80
+ * `.claude/rules/checks-must-be-able-to-fail.md`. So the one import here,
81
+ * `./markdown-fence` (#2135), is copied into both trees, and the guard test
82
+ * asserts it is the only one.
80
83
  */
81
84
 
85
+ import { readFences } from "./markdown-fence";
86
+
82
87
  /** The frontmatter key by which a file declares which generator produces it. */
83
88
  export const DERIVED_KEY = "generated-by";
84
89
 
@@ -109,9 +114,16 @@ const PROSE_DECLARATIONS = [
109
114
  /\bgenerated\s+by\b/i,
110
115
  ];
111
116
 
112
- /** Fenced blocks hold examples OF markers, never markers. */
117
+ /**
118
+ * Fenced blocks hold examples OF markers, never markers. Each fenced line is
119
+ * blanked, so the head's line structure is kept. The grammar is
120
+ * `lib/markdown-fence.ts`'s (#2135): the regex this replaced ended a ````
121
+ * block at its first ``` content line.
122
+ */
113
123
  function stripFences(text: string): string {
114
- return text.replace(/^(```|~~~)[\s\S]*?^\1[^\n]*$/gm, "");
124
+ const lines = text.split("\n");
125
+ const { roles } = readFences(lines);
126
+ return lines.map((line, i) => (roles[i] === "prose" ? line : "")).join("\n");
115
127
  }
116
128
 
117
129
  /**