rungate 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -151,7 +151,11 @@ export function preflightRefusal(
151
151
  `${treeVersion}, so the tag would describe a release that is not the one cut`
152
152
  );
153
153
  }
154
- if (state.versions.includes(treeVersion)) {
154
+ // `registryServes`, not a second `versions.includes` here (#445). Two
155
+ // deciders answering the same question about the same input are
156
+ // behaviourally one guard, and no behavioural test can tell them apart —
157
+ // the fourth shape in .claude/rules/checks-must-be-able-to-fail.md.
158
+ if (registryServes(state, treeVersion)) {
155
159
  return (
156
160
  `rungate@${treeVersion} is already on the registry — publishing it again is ` +
157
161
  `rejected by npm, and a job that treats that rejection as success reports a ` +
@@ -162,30 +166,109 @@ export function preflightRefusal(
162
166
  }
163
167
 
164
168
  /**
165
- * The single place that decides whether a release actually happened. `null`
166
- * allows.
169
+ * The ONE question the postflight answers: is the version on the registry?
170
+ *
171
+ * The `versions` list, not `dist-tags.latest` (#445). They are different
172
+ * facts and #364 conflated them. A version that appears in `versions` has
173
+ * been published — `npm install rungate@0.4.0` resolves — whatever `latest`
174
+ * currently points at, because a dist-tag is a pointer that moves on its own
175
+ * schedule and can be aimed anywhere. Reading `latest` to answer "did the
176
+ * publish take effect" is reading a pointer to answer a question about the
177
+ * thing pointed at.
178
+ *
179
+ * Exported as its own binding so there is exactly one place to mutate.
180
+ * `preflightRefusal` asks the same predicate in the opposite direction — the
181
+ * version must NOT be here before, and MUST be here after — which is the
182
+ * whole of the two-readings design in one field.
183
+ */
184
+ export function registryServes(state: RegistryState, version: string): boolean {
185
+ return state.versions.includes(version);
186
+ }
187
+
188
+ /**
189
+ * What the postflight established, and what it could not (#445).
190
+ *
191
+ * Three states, not two, because `v0.3.0` and `v0.4.0` both published
192
+ * successfully and both were recorded as failures. The old shape had only
193
+ * `refusal | null`, so a stale read had nowhere to go but into a refusal, and
194
+ * the refusal it got said *the publish step did not take effect* — a cause
195
+ * the guard had not established and could not establish from where it stood.
196
+ */
197
+ export interface PostflightVerdict {
198
+ /** `true` only when the registry serves the version being cut. */
199
+ published: boolean;
200
+ /**
201
+ * Set when the release is published but `latest` still points elsewhere.
202
+ * Reported, never decided on: a lagging dist-tag is propagation, and the
203
+ * guard calling it a failed publish is the whole of #445.
204
+ */
205
+ note: string | null;
206
+ /**
207
+ * Set when the version is absent from the packument. Deliberately NOT a
208
+ * finding — both explanations are named and neither is chosen. See
209
+ * `.claude/rules/config-access.md`: a reading that could not be obtained is
210
+ * UNMEASURED, and `0`, `{}`, `null` and `SKIP` are indistinguishable from
211
+ * success while UNMEASURED is not.
212
+ */
213
+ unmeasured: string | null;
214
+ }
215
+
216
+ /** The command a human runs to settle what this guard cannot. */
217
+ export function confirmCommand(pkg: string, version: string): string {
218
+ return `npm view ${pkg}@${version} version`;
219
+ }
220
+
221
+ /**
222
+ * The single place that decides whether a release actually happened.
167
223
  *
168
224
  * Run AFTER the publish step, against a freshly read registry. This is the
169
225
  * half that cannot be satisfied by doing nothing: a skipped, swallowed or
170
- * silently-failed publish leaves `latest` where it was.
226
+ * silently-failed publish leaves the registry without the version.
227
+ *
228
+ * What it will not do is say WHY the version is missing. From one stale read
229
+ * "the publish did not take effect" and "the packument has not propagated"
230
+ * are the same observation, and #407 answered that by waiting longer, which
231
+ * is a bigger guess rather than a different mechanism. This answers it by
232
+ * declining to guess and naming the command that settles it.
171
233
  */
172
- export function postflightRefusal(treeVersion: string, latestAfter: string | null): string | null {
173
- if (latestAfter === null) {
174
- return (
175
- `the registry has no latest version for rungate after the publish step — ` +
176
- `the release did not happen, whatever the job's exit code says`
177
- );
178
- }
179
- if (latestAfter !== treeVersion) {
180
- return (
181
- `the registry's latest is ${latestAfter}, not the ${treeVersion} this run was ` +
182
- `cutting — the publish step did not take effect`
183
- );
234
+ export function postflightVerdict(
235
+ pkg: string,
236
+ treeVersion: string,
237
+ state: RegistryState,
238
+ read: { attempts: number; waitedMs: number },
239
+ ): PostflightVerdict {
240
+ const seconds = Math.round(read.waitedMs / 1000);
241
+ const reads = `${read.attempts} read${read.attempts === 1 ? "" : "s"} over ${seconds}s`;
242
+
243
+ if (registryServes(state, treeVersion)) {
244
+ return {
245
+ published: true,
246
+ note:
247
+ state.latest === treeVersion
248
+ ? null
249
+ : `the registry serves ${pkg}@${treeVersion} while dist-tags.latest is ` +
250
+ `${state.latest ?? "unset"} — the publish landed and the tag has not ` +
251
+ `caught up. That is propagation and it is not a failed publish`,
252
+ unmeasured: null,
253
+ };
184
254
  }
185
- return null;
255
+
256
+ return {
257
+ published: false,
258
+ note: null,
259
+ unmeasured:
260
+ `UNMEASURED: ${pkg}@${treeVersion} is absent from the registry's packument ` +
261
+ `after ${reads} (dist-tags.latest is ${state.latest ?? "unset"}). Two ` +
262
+ `explanations fit this reading and nothing available here tells them apart: ` +
263
+ `the publish did not take effect, or the packument has not propagated. ` +
264
+ `The publish may well have succeeded. Settle it with ` +
265
+ `\`${confirmCommand(pkg, treeVersion)}\` — if that prints ${treeVersion} the ` +
266
+ `release landed and only this job's result is wrong; if it fails, the publish ` +
267
+ `did not happen and the release must be cut again.`,
268
+ };
186
269
  }
187
270
 
188
- /** What a postflight poll saw, and how hard it had to look (#407). */
271
+ /** What a postflight poll saw, and how hard it had to look (#407, #445). */
189
272
  export interface PostflightReading {
190
273
  /** The `latest` dist-tag on the final read. */
191
274
  latest: string | null;
@@ -193,13 +276,30 @@ export interface PostflightReading {
193
276
  attempts: number;
194
277
  /** Time spent sleeping between reads, in ms. */
195
278
  waitedMs: number;
196
- /** The refusal, or `null` to allow. */
197
- refusal: string | null;
279
+ /** What the final read established. */
280
+ verdict: PostflightVerdict;
198
281
  }
199
282
 
200
- /** Defaults sized for npm's observed read-after-write lag: up to ~30s. */
201
- export const POSTFLIGHT_ATTEMPTS = 10;
202
- export const POSTFLIGHT_DELAY_MS = 3_000;
283
+ /**
284
+ * The whole poll window, as ONE exported constant (#445 SC-4).
285
+ *
286
+ * #407 shipped the window as two numbers — ten attempts, three seconds apart
287
+ * — so widening it meant reasoning about their product, and the next person
288
+ * to widen it would raise whichever one they noticed. One constant, one edit,
289
+ * and `POSTFLIGHT_DELAY_MS` below cannot change the window no matter what it
290
+ * is set to. The positive control in `test/release-guard.test.ts` proves the
291
+ * guard still refuses an absent version, so widening this cannot quietly turn
292
+ * the check off.
293
+ */
294
+ export const POSTFLIGHT_BUDGET_MS = 120_000;
295
+
296
+ /** How often to re-read inside the budget. A cadence, not a budget knob. */
297
+ export const POSTFLIGHT_DELAY_MS = 5_000;
298
+
299
+ /** Reads the budget buys at a given cadence. The first read costs no wait. */
300
+ export function postflightAttempts(budgetMs: number, delayMs: number): number {
301
+ return Math.floor(budgetMs / delayMs) + 1;
302
+ }
203
303
 
204
304
  /**
205
305
  * Poll the registry until it serves `treeVersion`, or give up and refuse (#407).
@@ -218,9 +318,16 @@ export const POSTFLIGHT_DELAY_MS = 3_000;
218
318
  * ## The bound is the point
219
319
  *
220
320
  * Retrying until it goes green would turn this into the defect in the other
221
- * direction. The loop is bounded, a publish that never lands still refuses,
222
- * and the refusal says how long it waited — otherwise "it refused" and "it
223
- * did not wait long enough" are indistinguishable to whoever reads the log.
321
+ * direction. The loop is bounded, a version that never appears is never
322
+ * reported as published, and the reading says how many times it looked and
323
+ * for how long — so a reader can tell a bounded search from an impatient one
324
+ * without the guard having to interpret the number for them.
325
+ *
326
+ * ## What it stopped claiming (#445)
327
+ *
328
+ * Exhausting the budget used to produce a refusal naming a cause. It now
329
+ * produces `verdict.unmeasured`, which names both causes and neither. See
330
+ * `postflightVerdict`.
224
331
  *
225
332
  * ## Why an intermediate throw retries and the last one does not
226
333
  *
@@ -239,45 +346,46 @@ export async function awaitRegistryServes(
239
346
  opts: {
240
347
  fetchImpl?: typeof fetch;
241
348
  base?: string;
242
- attempts?: number;
349
+ budgetMs?: number;
243
350
  delayMs?: number;
244
351
  sleep?: (ms: number) => Promise<void>;
245
352
  } = {},
246
353
  ): Promise<PostflightReading> {
247
- const attempts = opts.attempts ?? POSTFLIGHT_ATTEMPTS;
354
+ const budgetMs = opts.budgetMs ?? POSTFLIGHT_BUDGET_MS;
248
355
  const delayMs = opts.delayMs ?? POSTFLIGHT_DELAY_MS;
249
- // A zero-attempt poll reads nothing and would fall out of the loop with no
250
- // refusal — a check that never runs, reported as a check that passed.
251
- if (!Number.isInteger(attempts) || attempts < 1) {
252
- throw new Error(`postflight needs at least one attempt, got ${opts.attempts}`);
356
+ // An unbounded budget is the defect in the other direction — a poll that
357
+ // retries until it goes green cannot fail — and a zero delay divides the
358
+ // budget by nothing and never terminates.
359
+ if (!Number.isFinite(budgetMs) || budgetMs < 0 || !Number.isFinite(delayMs) || delayMs <= 0) {
360
+ throw new Error(
361
+ `postflight needs a finite non-negative budget and a positive delay, got ` +
362
+ `${opts.budgetMs} / ${opts.delayMs}`,
363
+ );
253
364
  }
365
+ const attempts = postflightAttempts(budgetMs, delayMs);
254
366
  const sleep = opts.sleep ?? ((ms: number) => new Promise(r => setTimeout(r, ms)));
255
367
 
256
368
  let waitedMs = 0;
257
- let latest: string | null = null;
258
- let refusal: string | null = null;
259
369
 
260
370
  for (let attempt = 1; attempt <= attempts; attempt++) {
261
371
  const last = attempt === attempts;
372
+ let state: RegistryState;
262
373
  try {
263
- const state = await registryState(pkg, opts.fetchImpl ?? fetch, opts.base);
264
- latest = state.latest;
265
- refusal = postflightRefusal(treeVersion, latest);
374
+ state = await registryState(pkg, opts.fetchImpl ?? fetch, opts.base);
266
375
  } catch (e) {
376
+ // A transient error is exactly what polling is for. The FINAL one
377
+ // rethrows, because `registryState` throws rather than returning an
378
+ // empty state precisely so that "could not measure" cannot read as
379
+ // "nothing wrong", and swallowing it here would put that back.
267
380
  if (last) throw e;
268
- refusal = `could not read the registry: ${(e as Error).message}`;
381
+ await sleep(delayMs);
382
+ waitedMs += delayMs;
383
+ continue;
269
384
  }
270
385
 
271
- if (refusal === null) return { latest, attempts: attempt, waitedMs, refusal: null };
272
- if (last) {
273
- return {
274
- latest,
275
- attempts: attempt,
276
- waitedMs,
277
- refusal:
278
- `${refusal} — read ${attempt} times over ${Math.round(waitedMs / 1000)}s, ` +
279
- `which is long enough that this is not the registry catching up`,
280
- };
386
+ const verdict = postflightVerdict(pkg, treeVersion, state, { attempts: attempt, waitedMs });
387
+ if (verdict.published || last) {
388
+ return { latest: state.latest, attempts: attempt, waitedMs, verdict };
281
389
  }
282
390
  await sleep(delayMs);
283
391
  waitedMs += delayMs;
@@ -162,7 +162,29 @@ export const ProjectHarnessSchema = z.object({
162
162
  forbiddenCommands: z.array(z.string()).optional(),
163
163
  consumers: z.array(z.string()).optional(),
164
164
  promptKeywords: z.record(z.array(z.string())).optional(),
165
- contextDocs: z.record(z.string().nullable()).optional(),
165
+ /**
166
+ * Both authored shapes, because both have always been consumed (#439).
167
+ *
168
+ * This was `z.record(...)` — object only — while `gates/brief-assembler.ts`
169
+ * read `Array.isArray(docs) ? docs : Object.values(docs)` and
170
+ * `gates/brief-assembler.test.ts` tested the array form explicitly. The
171
+ * contradiction was invisible because the assembler parsed the file itself
172
+ * with `JSON.parse` and never reached the validator. Routing it through
173
+ * the loader is what made the schema and the consumer meet.
174
+ *
175
+ * The ENTRIES are `unknown` on purpose, which is the only place in this
176
+ * schema that is true. `lib/context-docs.ts` is the single decider for what
177
+ * a declared doc becomes, and it reports per entry — "docs/x.md: not a
178
+ * string" names the offender, where a schema throw would refuse the whole
179
+ * brief and name the key. Validating the entries here as well would be a
180
+ * second decider agreeing with the first, and the first would then be
181
+ * unreachable in production: its "not a string" arm could never fire, and
182
+ * no test could tell. See `.claude/rules/checks-must-be-able-to-fail.md`.
183
+ */
184
+ contextDocs: z.union([
185
+ z.record(z.unknown()),
186
+ z.array(z.unknown()),
187
+ ]).optional(),
166
188
  mcp: z.array(McpServerSchema).optional(),
167
189
  research: z.array(ResearchToolSchema).optional(),
168
190
  roles: z.record(RoleSchema).optional(),
package/lib/sc-cover.ts CHANGED
@@ -44,7 +44,7 @@
44
44
  import { readdirSync, readFileSync } from "fs";
45
45
  import { join } from "path";
46
46
 
47
- import { isBehavioralSC, matchPattern } from "./conformity";
47
+ import { collectTestableSpecs, isBehavioralSC, matchPattern, planSCTests } from "./conformity";
48
48
  import { buildScRegistry, isTemplateSpec, parseScDeclarations, type ScDeclaration } from "./sc-ids";
49
49
 
50
50
  export interface UncoveredSc {
@@ -148,3 +148,94 @@ export function ratchetViolations(
148
148
  }
149
149
  return out.sort();
150
150
  }
151
+
152
+ /**
153
+ * The two halves of "checked, and the engine can build no assertion" (#441).
154
+ *
155
+ * `UNMATCHED_CHECKED_RATCHET` was one number counting both, and its docblock
156
+ * read it as debt: SCs marked done that carry no assertion and are therefore
157
+ * wishes. That reading was right at 54. It stopped being right once the repo
158
+ * started writing criteria about REFUSALS, because the registry's whole
159
+ * vocabulary — file-exists, content-contains, count-threshold — is claims
160
+ * about the state of the tree, and there is no state of a tree that expresses
161
+ * "X refuses, and says which of two things happened".
162
+ *
163
+ * So the number rose on #397, #398 and #399 for criteria that are all covered
164
+ * by executed tests, and the only way to lower it would have been to rewrite
165
+ * them as weaker claims about file contents. A ratchet that rises whenever an
166
+ * issue writes a good behavioural criterion is measuring the matcher's
167
+ * vocabulary, not the project's honesty.
168
+ *
169
+ * - `unclaimed` — no test file declares it. The wish the old docblock meant.
170
+ * - `claimed` — a test file declares it per
171
+ * `.claude/rules/claiming-sc-coverage.md`, and the engine still cannot
172
+ * build the assertion. A measure of the vocabulary.
173
+ *
174
+ * `SUPERSEDED` ticks are excluded from BOTH, matching `uncoveredTickedScs`.
175
+ * A tick that points at its replacement is not a criterion anybody owes a
176
+ * test for, and leaving it in would have put one criterion in `unclaimed`
177
+ * that the census next door deliberately drops — a disagreement between two
178
+ * numbers about the same tree, arrived at by accident.
179
+ */
180
+ export interface UnmatchedSplit {
181
+ unclaimed: UncoveredSc[];
182
+ claimed: UncoveredSc[];
183
+ }
184
+
185
+ export function splitUnmatchedChecked(opts: {
186
+ projectRoot: string;
187
+ claimed: Set<string>;
188
+ scopedKey: (specFile: string, id: string) => string;
189
+ }): UnmatchedSplit {
190
+ const { projectRoot, claimed, scopedKey } = opts;
191
+ const out: UnmatchedSplit = { unclaimed: [], claimed: [] };
192
+
193
+ for (const [specFile, meta] of collectTestableSpecs(projectRoot)) {
194
+ for (const entry of planSCTests(meta.scs)) {
195
+ if (entry.kind !== "unmatched") continue;
196
+ if (isSuperseded(entry.sc.statement)) continue;
197
+ const row = { id: entry.sc.id, specFile, statement: entry.sc.statement };
198
+ if (claimed.has(scopedKey(specFile, entry.sc.id))) out.claimed.push(row);
199
+ else out.unclaimed.push(row);
200
+ }
201
+ }
202
+ return out;
203
+ }
204
+
205
+ /**
206
+ * Where the unclaimed half disagrees with the uncovered census next door.
207
+ *
208
+ * Measured before this existed: of 155 unclaimed criteria, **154** were
209
+ * already in `uncoveredTickedScs`'s census, which
210
+ * `test/ticked-sc-cover.test.ts` ratchets per spec, both directions, naming
211
+ * the ids. Banking the unclaimed count as a SECOND global number would have
212
+ * been two deciders answering one question — the fourth shape in
213
+ * `.claude/rules/checks-must-be-able-to-fail.md` — and a mutation of either
214
+ * would have left the other holding every case up.
215
+ *
216
+ * So this returns the DIFFERENCE rather than a count, and the test asserts
217
+ * the difference is exactly what is explained below. The per-spec ratchet
218
+ * stays the one place a new untested criterion is refused; this is the
219
+ * relationship between the two populations, checked rather than assumed.
220
+ *
221
+ * The two known residues, both of them the other function behaving correctly
222
+ * and this one being narrower:
223
+ *
224
+ * - `collectTestableSpecs` skips a spec whose frontmatter says
225
+ * `testable: no`, and `readSpecs` does not. `DA-COMPLIANCE-SPEC.md` is one.
226
+ * - `uncoveredTickedScs` also counts a criterion whose matcher MATCHES and
227
+ * then FAILS, which is not `unmatched` and so is invisible here.
228
+ */
229
+ export function unclaimedCensusResidue(opts: {
230
+ unclaimed: UncoveredSc[];
231
+ census: UncoveredSc[];
232
+ scopedKey: (specFile: string, id: string) => string;
233
+ }): { onlyUnclaimed: string[]; onlyCensus: string[] } {
234
+ const { scopedKey } = opts;
235
+ const a = new Set(opts.unclaimed.map(u => scopedKey(u.specFile, u.id)));
236
+ const b = new Set(opts.census.map(u => scopedKey(u.specFile, u.id)));
237
+ return {
238
+ onlyUnclaimed: [...a].filter(k => !b.has(k)).sort(),
239
+ onlyCensus: [...b].filter(k => !a.has(k)).sort(),
240
+ };
241
+ }
package/lib/sc-ids.ts CHANGED
@@ -140,6 +140,46 @@ export function isIssueShaped(id: string): boolean {
140
140
  return /^SC-\d$/.test(id);
141
141
  }
142
142
 
143
+ /**
144
+ * Ids at or above this number are reserved for test fixtures and will never
145
+ * be allocated to a real criterion (#399).
146
+ *
147
+ * **The namespace has two halves and only one of them was ever guarded.**
148
+ * `nextSCNumber`, `crossSpecCollisions`, `crossFormCollisions` and
149
+ * `requiresQualification` all reason over `specs/` — correctly, and blind to
150
+ * the other half. A test file that writes `- [ ] SC-9441: AGENTS.md exists`
151
+ * inside a string literal has put a checkbox declaration into the live
152
+ * namespace where no guard can see it, so the allocator proposes 900 as free,
153
+ * every collision detector agrees it is free, and the number collides with a
154
+ * literal the suite depends on. That is
155
+ * `.claude/rules/checks-must-be-able-to-fail.md`'s second shape: a detector
156
+ * narrower than what it detects.
157
+ *
158
+ * **It is not hypothetical.** `test/stale-issue-scanner.test.ts` plants
159
+ * `SC-379` and `SC-380` as fixtures, and
160
+ * `specs/CONFIG-DRIVEN-TESTING-SPEC.md:77-78` declares both as real tracked
161
+ * criteria. The collision #399 was filed to prevent had already landed.
162
+ *
163
+ * 9000 rather than 9900, which is what the issue proposed: the convention the
164
+ * tree already follows is 9000+, measured — 209 fixture mentions sit at
165
+ * 9001..9902 across eight files, against 24 strays below. Picking the floor
166
+ * the repo converged on costs no migrations that were not already needed, and
167
+ * `test/sc-claim-forms.test.ts` argued for the convention first.
168
+ */
169
+ export const FIXTURE_SC_FLOOR = 9000;
170
+
171
+ /**
172
+ * Is this id reserved for fixtures?
173
+ *
174
+ * ONE exported predicate, consulted by the allocator and by the stray guard,
175
+ * so there is a single binding to mutate rather than a convention each caller
176
+ * reimplements — which is what the four spec-only guards above already are.
177
+ */
178
+ export function isFixtureScId(id: string): boolean {
179
+ const n = Number(id.replace(/^SC-/, ""));
180
+ return Number.isInteger(n) && n >= FIXTURE_SC_FLOOR;
181
+ }
182
+
143
183
  /**
144
184
  * The registry: which spec files declare each id.
145
185
  *
@@ -342,3 +382,114 @@ export function isQualifiedBy(source: string, at: number, specFile: string): boo
342
382
  .toLowerCase();
343
383
  return qualifierTokens(specFile).some(t => window.includes(t.toLowerCase()));
344
384
  }
385
+
386
+ // ── The other half of the namespace: ids spelled in source ──
387
+
388
+ /** Directories whose sources can spell an SC id. */
389
+ export const SC_SOURCE_DIRS: readonly string[] = ["test", "lib", "scripts", "gates"];
390
+
391
+ /** One mention of an SC id in a source file. */
392
+ export interface ScMentionInSource {
393
+ id: string;
394
+ file: string;
395
+ /** True when the mention sits in a comment rather than in code. */
396
+ inComment: boolean;
397
+ }
398
+
399
+ /**
400
+ * Every numeric SC id spelled anywhere under `SC_SOURCE_DIRS`.
401
+ *
402
+ * Deliberately NOT restricted to declaring forms. The allocator's question is
403
+ * "could handing out this number break something", and a fixture spelled in
404
+ * any position — a string literal, an array of ids, a `-t` filter — breaks
405
+ * the same way once a spec claims the number. `commentClaimForm` draws the
406
+ * narrower line for CREDIT, and that line is settled and must not move
407
+ * (`.claude/rules/claiming-sc-coverage.md`); this is a different question
408
+ * asked for a different purpose, and widening it here cannot credit anything.
409
+ */
410
+ export function scMentionsInSource(root: string): ScMentionInSource[] {
411
+ const { readdirSync, readFileSync } = require("fs") as typeof import("fs");
412
+ const { join } = require("path") as typeof import("path");
413
+ const { commentMask } = require("./strip-js-comments") as typeof import("./strip-js-comments");
414
+ const out: ScMentionInSource[] = [];
415
+
416
+ const walk = (dir: string): void => {
417
+ let entries;
418
+ try {
419
+ entries = readdirSync(dir, { withFileTypes: true });
420
+ } catch {
421
+ return; // a source dir this consumer does not have
422
+ }
423
+ for (const e of entries) {
424
+ if (e.name === "node_modules" || e.name === ".git") continue;
425
+ const p = join(dir, e.name);
426
+ if (e.isDirectory()) { walk(p); continue; }
427
+ if (!e.name.endsWith(".ts") && !e.name.endsWith(".js")) continue;
428
+ const src = readFileSync(p, "utf-8");
429
+ if (!src.includes("SC-")) continue;
430
+ const mask = commentMask(src);
431
+ for (const m of src.matchAll(/SC-(\d+)(?!\d)/g)) {
432
+ out.push({ id: m[0], file: p.slice(root.length + 1), inComment: mask[m.index!] === true });
433
+ }
434
+ }
435
+ };
436
+ for (const d of SC_SOURCE_DIRS) walk(join(root, d));
437
+ return out;
438
+ }
439
+
440
+ /** Ids spelled in source, with the files that spell them. */
441
+ export function scIdsSpelledInSource(root: string): Map<string, string[]> {
442
+ const found = new Map<string, string[]>();
443
+ for (const m of scMentionsInSource(root)) {
444
+ const files = found.get(m.id) ?? [];
445
+ if (!files.includes(m.file)) files.push(m.file);
446
+ found.set(m.id, files);
447
+ }
448
+ return found;
449
+ }
450
+
451
+ /**
452
+ * Fixture ids living in the live namespace: spelled in source, declared by
453
+ * no spec, and below `FIXTURE_SC_FLOOR`.
454
+ *
455
+ * "Declared by no spec" is what makes it a fixture rather than a coverage
456
+ * claim. `// covers SC-640` names a real criterion and must not be moved;
457
+ * `{ id: "SC-9441", done: true }` names nothing and is a number the
458
+ * allocator is free to hand out tomorrow. The difference is in the registry,
459
+ * not in the spelling, which is why this takes one.
460
+ *
461
+ * ## What this deliberately does NOT catch, and why
462
+ *
463
+ * A fixture reusing an id a spec ALREADY declares is invisible here, and
464
+ * that case is real — two instances, both found by hand rather than by any
465
+ * guard:
466
+ *
467
+ * - `test/stale-issue-scanner.test.ts` plants `SC-379`/`SC-380`, both
468
+ * declared in `specs/CONFIG-DRIVEN-TESTING-SPEC.md:77-78`.
469
+ * - `test/sync-sc-status-matching.test.ts` planted `SC-91`/`SC-92`/`SC-93`,
470
+ * all declared in `specs/bootstrap-data-flow/success-criteria.md`, under a
471
+ * comment reading "with IDs this repo does not use so the file does not
472
+ * claim them" — true when written, false by the time it mattered, and
473
+ * nothing could notice.
474
+ *
475
+ * **Catching those by POSITION was tried and is wrong.** "In a comment it is
476
+ * a citation, in code it is a fixture" reports 338 violations on this tree,
477
+ * because `test("SC-1504: …")` is a test TITLE — a claim form
478
+ * `.claude/rules/claiming-sc-coverage.md` lists as valid and settled. And a
479
+ * planted fixture string containing `test("SC-91: …")` is textually
480
+ * identical to a real title, so no position rule separates them. Widening
481
+ * here would have swapped a guard that misses two cases for one that
482
+ * misreports three hundred, which is the worse trade in the direction this
483
+ * repo has already chosen: toward NOT reporting.
484
+ *
485
+ * The residue is filed rather than hidden. See #399's PR.
486
+ */
487
+ export function strayFixtureIds(root: string, reg: ScRegistry): Map<string, string[]> {
488
+ const stray = new Map<string, string[]>();
489
+ for (const [id, files] of scIdsSpelledInSource(root)) {
490
+ if (reg.declaredById.has(id)) continue;
491
+ if (isFixtureScId(id)) continue;
492
+ stray.set(id, files);
493
+ }
494
+ return stray;
495
+ }