rungate 0.4.1 → 0.6.0

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 (87) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/agents-md-sections.ts +144 -0
  11. package/lib/branch-diff.ts +139 -0
  12. package/lib/bun-version.ts +268 -0
  13. package/lib/ci-checkout.ts +1 -1
  14. package/lib/cli-commands.ts +7 -1
  15. package/lib/compliance.ts +13 -11
  16. package/lib/config-loader.ts +12 -0
  17. package/lib/conformity.ts +1147 -116
  18. package/lib/context-docs.ts +143 -28
  19. package/lib/create-brief.ts +2 -1
  20. package/lib/create-sc.ts +90 -4
  21. package/lib/doc-scan-targets.ts +9 -0
  22. package/lib/evidence-command-transport.ts +160 -0
  23. package/lib/evidence-prevalidator.ts +22 -0
  24. package/lib/fallow-availability.ts +129 -0
  25. package/lib/gate-refusal-currency.ts +112 -0
  26. package/lib/gate-timeouts.ts +82 -0
  27. package/lib/generators/agent-briefs.ts +4 -1
  28. package/lib/generators/agents-md.ts +71 -23
  29. package/lib/generators/code-map.ts +2 -1
  30. package/lib/generators/types.ts +8 -0
  31. package/lib/git-dates.ts +55 -0
  32. package/lib/github.ts +195 -0
  33. package/lib/js-top-level-code.ts +27 -2
  34. package/lib/junit-checks.ts +484 -0
  35. package/lib/local-calendar-day.ts +78 -0
  36. package/lib/package-closure.ts +278 -2
  37. package/lib/project-state-shape.ts +59 -0
  38. package/lib/promote-outputs.ts +6 -2
  39. package/lib/release-preflight.ts +196 -0
  40. package/lib/report-provenance.ts +156 -0
  41. package/lib/sc-claim-forms.ts +75 -0
  42. package/lib/sc-id-cross-tree.ts +311 -0
  43. package/lib/scaffold/ai-review-step.ts +180 -0
  44. package/lib/scaffold/defaults.ts +40 -0
  45. package/lib/scaffold/managed-workflow.ts +125 -27
  46. package/lib/scaffold/owned-files.ts +48 -2
  47. package/lib/scaffold/profiles.ts +94 -0
  48. package/lib/scaffold/rehearsal.ts +232 -73
  49. package/lib/scaffold/steps.ts +777 -152
  50. package/lib/scaffold/write-steps.ts +56 -13
  51. package/lib/scanner.ts +38 -12
  52. package/lib/source-anchor.ts +144 -0
  53. package/lib/spec-listing.ts +148 -0
  54. package/lib/spec-requirements.ts +209 -0
  55. package/lib/success-doc.ts +779 -0
  56. package/lib/suite-run-reading.ts +364 -0
  57. package/lib/test-census.ts +199 -0
  58. package/lib/test-command.ts +133 -0
  59. package/lib/test-suite-lock.ts +166 -10
  60. package/lib/tool-probe.ts +120 -0
  61. package/lib/tracked-vs-ignored.ts +234 -0
  62. package/lib/trajectory.ts +377 -0
  63. package/lib/validators/spec-validators.ts +35 -6
  64. package/lib/workflow-security.ts +101 -0
  65. package/lib/workflow-test-harness.ts +349 -0
  66. package/package.json +6 -1
  67. package/scripts/audit-specs.ts +247 -12
  68. package/scripts/audit-transcript.ts +2 -1
  69. package/scripts/convert-spec.ts +2 -1
  70. package/scripts/create-sc.ts +17 -7
  71. package/scripts/create-spec.ts +2 -1
  72. package/scripts/create-success.ts +163 -0
  73. package/scripts/extract-constraints.ts +90 -19
  74. package/scripts/generate-code-map.ts +53 -12
  75. package/scripts/scaffold-project.ts +31 -4
  76. package/scripts/split-spec.ts +2 -1
  77. package/scripts/sync-sc-status.ts +57 -5
  78. package/scripts/sync-spec-tests.ts +2 -1
  79. package/specs/SPEC-TEMPLATE.md +200 -0
  80. package/templates/SUCCESS-TEMPLATE.md +72 -0
  81. package/templates/agent-briefs/_shared.md +9 -0
  82. package/templates/agent-briefs/aditi.md +46 -0
  83. package/templates/agent-briefs/discovery.md +37 -0
  84. package/templates/agent-briefs/marcus.md +39 -0
  85. package/templates/agent-briefs/quinn.md +67 -0
  86. package/templates/agent-briefs/rook.md +40 -0
  87. package/templates/agent-briefs/serena.md +39 -0
@@ -4,6 +4,7 @@ import { join, relative } from "path";
4
4
  import { createHash } from "crypto";
5
5
  import { SIGNAL_PHRASE_PATTERNS } from "../lib/signal-phrases";
6
6
  import { planDocScan, type DocScanPlan } from "../lib/doc-scan-targets";
7
+ import { lastCommitDates } from "../lib/git-dates";
7
8
 
8
9
  // ── Types ────────────────────────────────────────────────────────
9
10
 
@@ -21,6 +22,37 @@ export interface StalenessEntry {
21
22
  type: string;
22
23
  }
23
24
 
25
+ /**
26
+ * What the scan planned against what it actually read (#508).
27
+ *
28
+ * `scan` below says what the walk could SEE. Nothing said what the extractor
29
+ * then managed to READ, and the two are different questions: a candidate
30
+ * count of zero from a scan that read 91 documents and a candidate count of
31
+ * zero from a scan that read 4 are the same line of output.
32
+ *
33
+ * `.claude/rules/checks-must-be-able-to-fail.md` states the general form
34
+ * after #492 measured it — *a scan that reports a verdict should report its
35
+ * own coverage* — and HYGIENE-6 is the verdict in question: it ended in
36
+ * `expect(true).toBe(true)`, so a timeout was the only red it could produce.
37
+ */
38
+ export interface ScanCoverage {
39
+ /** Documents the plan listed. */
40
+ planned: number;
41
+ /** Documents whose bytes reached `extractSignalPhrases`. */
42
+ read: number;
43
+ /**
44
+ * Planned documents the read could not take, with the error that stopped
45
+ * it — `ENOENT` for a file that moved between the walk and the read,
46
+ * `EISDIR`, `EACCES`.
47
+ *
48
+ * Recorded rather than thrown, and recorded rather than dropped. A throw
49
+ * takes an advisory backlog report down over one transient file; a drop
50
+ * makes a partial scan indistinguishable from a complete one, which is
51
+ * the failure this whole interface exists to stop.
52
+ */
53
+ unread: Array<{ file: string; reason: string }>;
54
+ }
55
+
24
56
  export interface ExtractResult {
25
57
  candidates: Candidate[];
26
58
  deduped: {
@@ -29,6 +61,8 @@ export interface ExtractResult {
29
61
  candidatesRemoved: number;
30
62
  };
31
63
  staleness: StalenessEntry[];
64
+ /** What was planned against what was read. Never inferred from `candidates`. */
65
+ coverage: ScanCoverage;
32
66
  /**
33
67
  * What was scanned and what could not be (#440).
34
68
  *
@@ -111,24 +145,44 @@ function loadRejectedHashes(projectPath: string): Set<string> {
111
145
  return hashes;
112
146
  }
113
147
 
148
+ /**
149
+ * One git subprocess for every document, not one per document (#508).
150
+ *
151
+ * This was `Bun.spawnSync(["git", …, "log", "-1", …, "--", rel])` inside
152
+ * the loop — the exact code #323 removed from `runDocHygiene`, in a file
153
+ * #323 did not touch. 92 documents meant 92 serial subprocesses against
154
+ * the same repository, and nothing was wrong with any single one: the
155
+ * check was load-sensitive by construction, so a busy machine, a cold
156
+ * cache or another suite holding the index pushed it past the 5000ms
157
+ * default test timeout. Measured before the change at 4169ms, 4521ms and
158
+ * 3969ms on an IDLE machine with a warm cache; HYGIENE-6 had been seen red
159
+ * four times in full runs and green standalone every time.
160
+ *
161
+ * `lastCommitDates` walks the whole history newest-first with `--name-only`
162
+ * and returns every path's latest commit date from one call. Imported from
163
+ * `lib/git-dates.ts` rather than copied, because two implementations of
164
+ * one question are behaviourally one and no test can tell them apart.
165
+ */
114
166
  function computeStaleness(projectPath: string, files: string[]): StalenessEntry[] {
167
+ const considered = files
168
+ .map(f => relative(projectPath, f))
169
+ .filter(rel => !(rel.includes("docs/adr/") || /ADR/i.test(rel)));
170
+ // The exact lookup set is the pathspec, so the keys and the query cannot
171
+ // drift — #323 got this wrong first time by passing the directories.
172
+ const lastCommit = lastCommitDates(projectPath, considered);
173
+
115
174
  const stale: StalenessEntry[] = [];
116
- for (const filePath of files) {
117
- const rel = relative(projectPath, filePath);
118
- const isAdr = rel.includes("docs/adr/") || /ADR/i.test(rel);
119
- if (isAdr) continue;
120
- try {
121
- const result = Bun.spawnSync(["git", "-C", projectPath, "log", "-1", "--format=%ci", "--", rel], { timeout: 5_000 });
122
- const dateStr = result.stdout.toString().trim().split(" ")[0];
123
- if (!dateStr) continue;
124
- const daysSince = (Date.now() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24);
125
- const isSpec = rel.startsWith("specs/");
126
- const threshold = isSpec ? 90 : 180;
127
- const type = isSpec ? "spec" : "guide";
128
- if (daysSince > threshold) {
129
- stale.push({ file: rel, daysSince: Math.floor(daysSince), threshold, type });
130
- }
131
- } catch {}
175
+ for (const rel of considered) {
176
+ const dateStr = lastCommit.get(rel);
177
+ // No commit means untracked or newly added, which is the opposite of stale.
178
+ if (!dateStr) continue;
179
+ const daysSince = (Date.now() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24);
180
+ const isSpec = rel.startsWith("specs/");
181
+ const threshold = isSpec ? 90 : 180;
182
+ const type = isSpec ? "spec" : "guide";
183
+ if (daysSince > threshold) {
184
+ stale.push({ file: rel, daysSince: Math.floor(daysSince), threshold, type });
185
+ }
132
186
  }
133
187
  return stale;
134
188
  }
@@ -171,16 +225,32 @@ function applyToAgentsMd(projectPath: string, candidates: Candidate[]): void {
171
225
 
172
226
  export async function extractConstraints(
173
227
  projectPath: string,
174
- options?: { apply?: boolean }
228
+ options?: { apply?: boolean; plan?: DocScanPlan }
175
229
  ): Promise<ExtractResult> {
176
- const scan = planDocScan(projectPath);
230
+ // `plan` is a seam, and it is here for one reason worth stating: the
231
+ // unread branch below is unreachable from outside this function, because
232
+ // the walk that produces the plan only lists files it has just stat'd. A
233
+ // branch no test can reach is the subject of this repo's central rule, so
234
+ // the plan is an input a caller may supply — which is also the race the
235
+ // branch is about, a plan taken a moment before the tree moved.
236
+ const scan = options?.plan ?? planDocScan(projectPath);
177
237
  const scanFiles = scan.files;
178
238
  const existingConstraints = loadExistingConstraints(projectPath);
179
239
  const rejectedHashes = loadRejectedHashes(projectPath);
180
240
 
181
241
  let allCandidates: Candidate[] = [];
242
+ const unread: ScanCoverage["unread"] = [];
243
+ let read = 0;
182
244
  for (const filePath of scanFiles) {
183
- const content = readFileSync(filePath, "utf-8");
245
+ let content: string;
246
+ try {
247
+ content = readFileSync(filePath, "utf-8");
248
+ } catch (err) {
249
+ const e = err as NodeJS.ErrnoException;
250
+ unread.push({ file: relative(projectPath, filePath), reason: e.code ?? e.name });
251
+ continue;
252
+ }
253
+ read++;
184
254
  allCandidates.push(...extractSignalPhrases(content, filePath, projectPath));
185
255
  }
186
256
 
@@ -215,6 +285,7 @@ export async function extractConstraints(
215
285
  candidatesRemoved: existingRemoved + rejectedRemoved,
216
286
  },
217
287
  staleness,
288
+ coverage: { planned: scanFiles.length, read, unread },
218
289
  scan,
219
290
  };
220
291
  }
@@ -10,6 +10,14 @@
10
10
  */
11
11
  import { existsSync, readFileSync, readdirSync, writeFileSync, statSync } from "fs";
12
12
  import { join, basename } from "path";
13
+ import { localCalendarDay } from "../lib/local-calendar-day";
14
+ import {
15
+ fallowAvailable,
16
+ fallowNotInstalled,
17
+ fallowRunFailed,
18
+ fallowUnmeasuredNotice,
19
+ type FallowUnavailable,
20
+ } from "../lib/fallow-availability";
13
21
 
14
22
  const projectPath = process.argv[2];
15
23
  if (!projectPath || !existsSync(projectPath)) {
@@ -18,7 +26,7 @@ if (!projectPath || !existsSync(projectPath)) {
18
26
  }
19
27
 
20
28
  const projectName = basename(projectPath);
21
- const today = new Date().toISOString().split("T")[0];
29
+ const today = localCalendarDay();
22
30
 
23
31
  // ── Fallow analysis ──────────────────────────────────────────
24
32
 
@@ -30,16 +38,38 @@ interface FallowData {
30
38
  elapsed: number;
31
39
  }
32
40
 
33
- function runFallow(): FallowData | null {
41
+ /**
42
+ * Three outcomes, not two (#581).
43
+ *
44
+ * This returned `null` for "not installed", "the spawn failed", "the output
45
+ * did not parse" and — through `||` in the summary table below — "it ran and
46
+ * found zero". A CODE-MAP written from any of them was byte-identical, so a
47
+ * reader could not tell a project with no dead code from a project nobody
48
+ * looked at.
49
+ */
50
+ type FallowOutcome = { data: FallowData } | { unavailable: FallowUnavailable };
51
+
52
+ function runFallow(): FallowOutcome {
53
+ // Resolved locally, with no network path. A bare `npx fallow` for a tool
54
+ // that is not a declared dependency is a registry fetch on the SCAFFOLD
55
+ // path — once per consumer, forever, including behind a proxy and in an
56
+ // air-gapped CI. `lib/conformity.ts` fixed this for itself in #510 and
57
+ // this caller never got it.
58
+ if (!fallowAvailable(projectPath) && !fallowAvailable(process.cwd())) {
59
+ return { unavailable: fallowNotInstalled() };
60
+ }
34
61
  const result = Bun.spawnSync(
35
62
  ["npx", "fallow", "dead-code", "--format", "json", "--quiet"],
36
63
  { cwd: projectPath, timeout: 30_000 }
37
64
  );
38
65
  const stdout = result.stdout.toString().trim();
39
- if (!stdout || stdout.startsWith("{\"error\"")) return null;
66
+ if (!stdout) return { unavailable: fallowRunFailed(`exit ${result.exitCode}, no output`) };
67
+ if (stdout.startsWith("{\"error\"")) {
68
+ return { unavailable: fallowRunFailed(stdout.slice(0, 200)) };
69
+ }
40
70
  try {
41
71
  const d = JSON.parse(stdout);
42
- return {
72
+ return { data: {
43
73
  entryPoints: d.entry_points?.total || 0,
44
74
  unusedFiles: (d.unused_files || []).map((f: any) => f.path),
45
75
  unusedExports: (d.unused_exports || []).map((e: any) => ({
@@ -49,8 +79,10 @@ function runFallow(): FallowData | null {
49
79
  files: c.files || [c.path]
50
80
  })),
51
81
  elapsed: d.elapsed_ms || 0,
52
- };
53
- } catch { return null; }
82
+ } };
83
+ } catch (e) {
84
+ return { unavailable: fallowRunFailed(`output did not parse as JSON (${(e as Error).name})`) };
85
+ }
54
86
  }
55
87
 
56
88
  // ── Route scanning ───────────────────────────────────────────
@@ -192,7 +224,9 @@ function readPackageInfo(): { name: string; deps: number; devDeps: number; scrip
192
224
 
193
225
  console.log(`Scanning ${projectName}...`);
194
226
 
195
- const fallow = runFallow();
227
+ const fallowOutcome = runFallow();
228
+ const fallow = "data" in fallowOutcome ? fallowOutcome.data : null;
229
+ const fallowMissing = "unavailable" in fallowOutcome ? fallowOutcome.unavailable : null;
196
230
  const routes = scanRoutes();
197
231
  const dirs = scanDirectories();
198
232
  const components = scanComponents();
@@ -200,7 +234,9 @@ const pkg = readPackageInfo();
200
234
  const consumerMappings = scanConsumerModules();
201
235
  const pageMappings = scanPageComponents();
202
236
 
203
- console.log(` Fallow: ${fallow ? `${fallow.entryPoints} entry points, ${fallow.elapsed}ms` : "not available"}`);
237
+ console.log(
238
+ ` Fallow: ${fallow ? `${fallow.entryPoints} entry points, ${fallow.elapsed}ms` : `UNMEASURED — ${fallowMissing?.reason}`}`,
239
+ );
204
240
  console.log(` Routes: ${routes.length}`);
205
241
  console.log(` Directories: ${dirs.length}`);
206
242
  console.log(` Components: ${components.length}`);
@@ -240,10 +276,10 @@ sections.push(`## Summary
240
276
  | Dev dependencies | ${pkg.devDeps} |
241
277
  | API routes | ${routes.length} |
242
278
  | React components | ${components.length} |
243
- | Entry points (fallow) | ${fallow?.entryPoints || "N/A"} |
244
- | Unused files | ${fallow?.unusedFiles.length || "N/A"} |
245
- | Unused exports | ${fallow?.unusedExports.length || "N/A"} |
246
- | Circular dependencies | ${fallow?.circularDeps.length || "N/A"} |
279
+ | Entry points (fallow) | ${fallow ? fallow.entryPoints : "UNMEASURED"} |
280
+ | Unused files | ${fallow ? fallow.unusedFiles.length : "UNMEASURED"} |
281
+ | Unused exports | ${fallow ? fallow.unusedExports.length : "UNMEASURED"} |
282
+ | Circular dependencies | ${fallow ? fallow.circularDeps.length : "UNMEASURED"} |
247
283
  | Module import mappings | ${consumerMappings.length} |
248
284
  | Page-component mappings | ${pageMappings.length} |`);
249
285
 
@@ -324,6 +360,11 @@ if (fallow) {
324
360
  }
325
361
 
326
362
  sections.push(health.trim());
363
+ } else if (fallowMissing) {
364
+ // Named, not omitted. A missing section and a section reporting nothing
365
+ // wrong are the same absence to a reader, and the reader of a CODE-MAP is
366
+ // an agent deciding whether this project has dead code.
367
+ sections.push(fallowUnmeasuredNotice(fallowMissing));
327
368
  }
328
369
 
329
370
  // Scripts
@@ -14,6 +14,7 @@ import { reportScaffoldActions } from "../lib/scaffold/steps";
14
14
  import { runScaffoldWriteSteps } from "../lib/scaffold/write-steps";
15
15
  import { cloneForRehearsal, discardRehearsal, rehearsalNotice } from "../lib/scaffold/rehearsal";
16
16
  import type { ProjectType } from "../lib/generators/types";
17
+ import { parseProfile, STEPS_NOT_MINIMAL, type ScaffoldProfile } from "../lib/scaffold/profiles";
17
18
 
18
19
  // ── CLI argument parsing ───────────────────────────────────────
19
20
 
@@ -24,9 +25,19 @@ const typeFlag = args.find(arg => arg.startsWith('--type='))?.split('=')[1] ||
24
25
  const fix = args.includes('--fix');
25
26
  // #216: both default false — re-scaffold is how a consumer takes an UPDATE.
26
27
  const force = args.includes('--force'), commit = args.includes('--commit');
28
+ // #42. Auto-fix is opt-OUT: a re-scaffold that reports a gap it could have
29
+ // closed is a worse onboarding than one that closes it. Pruning consumers is
30
+ // opt-IN and separate — see `pruneStaleConsumers` for why deleting a config
31
+ // entry is not in the same risk class as adding a frontmatter line.
32
+ const autoFix = !args.includes('--no-auto-fix');
33
+ const pruneConsumers = args.includes('--prune-consumers');
34
+ // #449. Orthogonal to --type: that selects WHICH generators run, this selects
35
+ // whether the harness-only ones run at all.
36
+ const profileFlag = args.find(arg => arg.startsWith('--profile='))?.split('=')[1] ||
37
+ (args.indexOf('--profile') !== -1 ? args[args.indexOf('--profile') + 1] : null);
27
38
 
28
39
  if (!projectPath) {
29
- console.error("Usage: scaffold-project.ts /path/to/project [--type code|workflow] [--fix] [--force] [--commit]");
40
+ console.error("Usage: scaffold-project.ts /path/to/project [--type code|content|infra|workflow] [--profile full|minimal] [--fix] [--force] [--commit] [--no-auto-fix] [--prune-consumers]");
30
41
  process.exit(1);
31
42
  }
32
43
 
@@ -46,6 +57,16 @@ if (typeFlag && !['code', 'content', 'infra', 'workflow'].includes(typeFlag)) {
46
57
  process.exit(1);
47
58
  }
48
59
 
60
+ // parseProfile throws rather than defaulting: a typo'd --profile=minimial that
61
+ // silently scaffolded the full harness would look like the flag was honoured.
62
+ let profile: ScaffoldProfile;
63
+ try {
64
+ profile = parseProfile(profileFlag);
65
+ } catch (err) {
66
+ console.error(`ERROR: ${(err as Error).message}`);
67
+ process.exit(1);
68
+ }
69
+
49
70
  // ── Main ───────────────────────────────────────────────────────
50
71
 
51
72
  const actions: string[] = [];
@@ -55,10 +76,11 @@ const projectName = basename(projectPath);
55
76
  console.log(`Detected project type: ${projectType}`);
56
77
  console.log(`Project: ${projectName}`);
57
78
  console.log(`Path: ${projectPath}`);
79
+ console.log(`Profile: ${profile}${profile === "minimal" ? ` — not written: ${[...STEPS_NOT_MINIMAL.keys()].join(", ")}` : ""}`);
58
80
  console.log("---");
59
81
 
60
82
  if (fix) {
61
- runScaffoldWriteSteps(projectPath, projectType, actions, { force, commit });
83
+ runScaffoldWriteSteps(projectPath, projectType, actions, { force, commit, profile, autoFix, pruneConsumers });
62
84
  } else {
63
85
  // Audit does not PREDICT what --fix would do; it does it, against a clone,
64
86
  // and reports what the real steps said (#398). The previous audit branch was
@@ -78,9 +100,14 @@ if (fix) {
78
100
  }
79
101
  try {
80
102
  console.log(rehearsalNotice(rehearsal));
81
- runScaffoldWriteSteps(rehearsal.dir, projectType, actions, { force, commit: false, rehearsing: true });
103
+ // The rehearsal gets the same flags, so an audit reports what --fix would
104
+ // actually do rather than what it would do with different settings (#398).
105
+ runScaffoldWriteSteps(rehearsal.dir, projectType, actions, { force, commit: false, rehearsing: true, profile, autoFix, pruneConsumers });
82
106
  } finally {
83
- discardRehearsal(rehearsal);
107
+ // #549: a cleanup failure is a sentence, not an exception. The report
108
+ // has already printed by now, and throwing here threw it away.
109
+ const leaked = discardRehearsal(rehearsal);
110
+ if (leaked) console.error(`WARNING: ${leaked}`);
84
111
  }
85
112
  }
86
113
 
@@ -2,6 +2,7 @@
2
2
 
3
3
  import { readFileSync, writeFileSync, mkdirSync } from "fs";
4
4
  import { join, dirname } from "path";
5
+ import { localCalendarDay } from "../lib/local-calendar-day";
5
6
 
6
7
  export interface SplitBoundary {
7
8
  heading: string;
@@ -166,7 +167,7 @@ export function generateSplitFiles(
166
167
  metadata: { owner: string; testable: boolean }
167
168
  ): SplitFile[] {
168
169
  const lines = content.split("\n");
169
- const now = new Date().toISOString().split("T")[0];
170
+ const now = localCalendarDay();
170
171
  const groups = groupBoundaries(boundaries, lines.length);
171
172
 
172
173
  return groups.map((group) => {
@@ -16,7 +16,7 @@
16
16
 
17
17
  import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
18
18
  import { commentMask, enclosingComment, stripJsComments } from "../lib/strip-js-comments";
19
- import { commentClaimForm, type ClaimForm } from "../lib/sc-claim-forms";
19
+ import { commentClaimForm, titleCall, type ClaimForm } from "../lib/sc-claim-forms";
20
20
  import { join } from "path";
21
21
  import { execSync } from "child_process";
22
22
  import { matchPattern, isBehavioralSC, type ParsedSC } from "../lib/conformity";
@@ -101,8 +101,6 @@ export function findUncheckedSCs(specsDir?: string): UncheckedSC[] {
101
101
  */
102
102
  export const scMentionPattern = oneScMentionPattern;
103
103
 
104
- /** Opens a `describe`/`test`/`it` title, allowing `.each(...)`, `.only`, `.skip`. */
105
- const TITLE_CALL = /\b(?:describe|test|it)\s*(?:\.\w+\s*(?:\([^)]*\))?\s*)*\(\s*$/;
106
104
 
107
105
  /**
108
106
  * The success criteria a source file CLAIMS to cover (#149).
@@ -189,7 +187,7 @@ export interface ClaimSite {
189
187
  * Where it was written. A comment is a claim for an unambiguous id and is
190
188
  * NOT enough for an ambiguous one — see `findTestFilesForSCs`.
191
189
  */
192
- kind: "comment" | "title" | "bare";
190
+ kind: "comment" | "title" | "unrun-title" | "bare";
193
191
  /**
194
192
  * For a comment, WHICH structural declaring form it occupies, or `null` for
195
193
  * a bare mention inside running prose (#360). Always `null` for the other
@@ -243,7 +241,15 @@ export function coverageClaimSites(source: string): ClaimSite[] {
243
241
  while (open > 0 && !/['"`]/.test(codeOnly[open])) open--;
244
242
  if (!/['"`]/.test(codeOnly[open] ?? "")) continue;
245
243
 
246
- if (TITLE_CALL.test(codeOnly.slice(Math.max(0, open - 120), open))) add(id, at, "title");
244
+ // A title is a declaring position; a title that never runs is a
245
+ // declaration of INTENT (#574). `test.todo("SC-N: …")` is the honest way
246
+ // to write down work you have not done, and crediting it ticked 37
247
+ // criteria whose only test was the word todo. Kept as a site rather than
248
+ // dropped, so the sync can report it as UNMEASURED — dropping it would
249
+ // make "nobody wrote this test" look like "nobody mentioned this id".
250
+ const call = titleCall(codeOnly.slice(Math.max(0, open - 120), open));
251
+ if (call === "runs") add(id, at, "title");
252
+ else if (call === "never-runs") add(id, at, "unrun-title");
247
253
  }
248
254
 
249
255
  return claims;
@@ -324,6 +330,10 @@ export function findTestFilesForSCs(
324
330
  // project declares coverage and where it explains itself, and a bare id
325
331
  // inside a running sentence is a citation.
326
332
  if (kind === "comment" && !form) continue;
333
+ // #574. The direction this is allowed to be wrong in is toward NOT
334
+ // crediting, and a todo is the clearest case there is: nothing can go
335
+ // red, so nothing can be measured.
336
+ if (kind === "unrun-title") continue;
327
337
  for (const specFile of wanted.get(id) ?? []) {
328
338
  if (requiresQualification(id, reg) && !(kind === "title" && isQualifiedBy(source, at, specFile))) continue;
329
339
  if (!credits.some(c => c.id === id && c.specFile === specFile)) {
@@ -336,6 +346,36 @@ export function findTestFilesForSCs(
336
346
  return out;
337
347
  }
338
348
 
349
+ /**
350
+ * Ids whose only declaring position in the test tree is a title that never
351
+ * runs (#574), with the files that name them.
352
+ *
353
+ * An id that ALSO has a running title or a declaring comment anywhere is
354
+ * not here: the question is whether anything can measure it, not whether a
355
+ * todo exists. That distinction is the whole report — otherwise every
356
+ * criterion with a todo beside a real test would be listed as unmeasured
357
+ * and the list would be ignored within a week.
358
+ */
359
+ export function intendedOnly(testDir: string): Map<string, string[]> {
360
+ const out = new Map<string, string[]>();
361
+ if (!existsSync(testDir)) return out;
362
+ const measured = new Set<string>();
363
+ const intended = new Map<string, string[]>();
364
+ for (const file of readdirSync(testDir).filter(f => f.endsWith(".test.ts"))) {
365
+ for (const site of coverageClaimSites(readFileSync(join(testDir, file), "utf-8"))) {
366
+ if (site.kind === "unrun-title") {
367
+ const files = intended.get(site.id) ?? [];
368
+ if (!files.includes(file)) files.push(file);
369
+ intended.set(site.id, files);
370
+ } else if (site.kind === "title" || (site.kind === "comment" && site.form)) {
371
+ measured.add(site.id);
372
+ }
373
+ }
374
+ }
375
+ for (const [id, files] of intended) if (!measured.has(id)) out.set(id, files);
376
+ return out;
377
+ }
378
+
339
379
  /**
340
380
  * Mentions that look like claims and are not credited, with why (#330).
341
381
  *
@@ -631,6 +671,18 @@ if (isDirectExecution) {
631
671
  for (const line of [...unqualified.values()].sort()) console.log(line);
632
672
  }
633
673
 
674
+ // #574. A criterion whose only test is a `.todo` is UNMEASURED, and
675
+ // UNMEASURED has to be loud: `0`, `{}`, `null` and silence are all
676
+ // indistinguishable from success. Reported by name, with the file, so the
677
+ // list is a backlog rather than a number.
678
+ const intended = intendedOnly(TEST_DIR);
679
+ if (intended.size > 0) {
680
+ console.log(`\n⚠️ UNMEASURED: ${intended.size} SC(s) named only by a test that never runs:`);
681
+ for (const [id, files] of [...intended].sort()) {
682
+ console.log(` ${id}: ${files.join(", ")} — a .todo or .skip title is a declaration of intent, not coverage`);
683
+ }
684
+ }
685
+
634
686
  // Step 3: Run hand-written tests — scope by spec file
635
687
  const passingSCs = new Set<string>();
636
688
  const failingSCs = new Set<string>();
@@ -17,6 +17,7 @@ import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
17
17
  import { collectSpecFiles } from "../lib/spec-files";
18
18
  import { resolve, join } from "path";
19
19
  import { harnessRootFor } from "../lib/paths";
20
+ import { localCalendarDay } from "../lib/local-calendar-day";
20
21
 
21
22
  /**
22
23
  * Where this script reads specs and writes tests (#141).
@@ -208,7 +209,7 @@ function generateTest(claims: Claim[]): string {
208
209
  `// AUTO-GENERATED by scripts/sync-spec-tests.ts — do not edit manually`,
209
210
  `// Regenerate: bun scripts/sync-spec-tests.ts`,
210
211
  `// Source: specs/ (every spec with testable: true)`,
211
- `// Generated: ${new Date().toISOString().split("T")[0]}`,
212
+ `// Generated: ${localCalendarDay()}`,
212
213
  ``,
213
214
  `import { test, expect, describe } from "bun:test";`,
214
215
  `import { readFileSync } from "fs";`,