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
@@ -0,0 +1,779 @@
1
+ /**
2
+ * `SUCCESS.md` — the one file the methodology calls the measure, and the one
3
+ * the scaffold never wrote (#485).
4
+ *
5
+ * `CLAUDE.md` opens its rules with:
6
+ *
7
+ * > **SUCCESS.md is the measure** — it states what we are building and the
8
+ * > falsifiable claims that mean it works. Before filing an issue, reviewing
9
+ * > a PR, or acting on an audit finding, say which claim it moves.
10
+ *
11
+ * No generator, no template, no step produced it. rungate's own was
12
+ * hand-written once in `22aa5b20` and nothing reproduced that for anyone
13
+ * else, while `specs/HARNESS-STANDARD.md` carried SC-822 asserting a
14
+ * property of a file the scaffold never created. A consumer scaffolded a
15
+ * project, read the generated `AGENTS.md`, and never learned the file was
16
+ * supposed to exist.
17
+ *
18
+ * ## Why a validator and not just a generator
19
+ *
20
+ * A generator alone makes it worse. **An unfilled template is
21
+ * indistinguishable from a considered one to everything except a reader** —
22
+ * that is the same argument `.claude/rules/checks-must-be-able-to-fail.md`
23
+ * makes about guards, applied to a document. A project that ran
24
+ * `create-success` and stopped would now have a `SUCCESS.md` that every
25
+ * "does it exist" check waves through, and five TODO claims read as
26
+ * deliberate at a glance.
27
+ *
28
+ * So the template ships placeholders that are obviously placeholders, marked
29
+ * with a token no prose would contain, and `successViolations` refuses while
30
+ * any survive. **The generator must not invent claims**: five plausible
31
+ * generated claims would be worse than none, because they read as considered
32
+ * and are not.
33
+ *
34
+ * ## Absent is UNMEASURED, not FAIL
35
+ *
36
+ * A project that never opted in has not failed at anything, but it has not
37
+ * succeeded either, and `SKIP` is indistinguishable from success — see
38
+ * `.claude/rules/config-access.md`. So an absent file produces a loud
39
+ * UNMEASURED and a present-but-unfilled one produces a refusal.
40
+ */
41
+
42
+ import { existsSync, lstatSync, readFileSync } from "fs";
43
+ import { dirname, join } from "path";
44
+ import { fileURLToPath } from "url";
45
+
46
+ /**
47
+ * The token the template puts on every line a human must replace.
48
+ *
49
+ * An HTML comment, so it renders as nothing and a consumer who leaves one in
50
+ * sees a clean document — which is exactly why a machine has to be the thing
51
+ * that notices. Distinctive enough that no prose contains it by accident.
52
+ */
53
+ export const PLACEHOLDER_MARKER = "rungate:placeholder";
54
+
55
+ /**
56
+ * ## Two accepted forms, and why that is not a weakening
57
+ *
58
+ * The template below writes `### Claim N — statement`. rungate's own
59
+ * `SUCCESS.md` — hand-written in `22aa5b20`, four months before this
60
+ * validator, and the ONLY real instance of the document this file validates —
61
+ * writes `1. **statement**` with an indented `Check:` underneath.
62
+ *
63
+ * The first draft of this parser recognised only the template's form, and the
64
+ * consequence was immediate: run against the document that defines the genre,
65
+ * it reported *"SUCCESS.md defines no claims"*. A validator whose single
66
+ * real-world example fails it is not strict, it is miscalibrated — and the
67
+ * repair everybody actually reaches for is to stop running the validator.
68
+ *
69
+ * So both forms parse. This costs nothing in strictness, because **neither
70
+ * form is what the check is about**: the refusals are placeholders left in,
71
+ * claims with nothing that can falsify them, and a standing table that
72
+ * disagrees with the claims. A document can satisfy either syntax and still
73
+ * fail all three. Widening the syntax does not widen what passes.
74
+ */
75
+ const CLAIM_FORMS: RegExp[] = [
76
+ /** `### Claim N — statement`, the form the template writes. */
77
+ /^###\s+Claim\s+(\d+)\s*[—–-]\s*(.*)$/,
78
+ /** `N. **statement**`, the form rungate's own SUCCESS.md has always used. */
79
+ /^(\d+)\.\s+\*\*(.+?)\*\*\s*$/,
80
+ ];
81
+
82
+ /**
83
+ * The falsifiability line. Its absence is the defect this file exists for.
84
+ *
85
+ * `Check:` is rungate's spelling of it and `**How it fails:**` is the
86
+ * template's; they are one field asked two ways.
87
+ *
88
+ * **`**How to measure it:**` is deliberately NOT one of them.** It is the
89
+ * other half of the template and it answers a different question — the
90
+ * command that produces the observation, not the observation that would prove
91
+ * the claim false. Admitting it here was the first draft, and it meant a
92
+ * claim could satisfy the falsifiability rule while saying only how to look:
93
+ * "run the suite" with nothing stating what a failure would look like is the
94
+ * slogan this refusal exists to catch. An unfilled measurement line is still
95
+ * caught, by the placeholder and TODO checks.
96
+ */
97
+ const FALSIFIABILITY = /^(?:\*\*How it fails:\*\*|Check:)\s*(.*)$/;
98
+
99
+ /**
100
+ * A standing-table row, keyed by the claim number in its first cell.
101
+ *
102
+ * `| 1 | untested |` (template) and `| 1 — gates can fail | Partial… |`
103
+ * (rungate) both key on 1. A first cell that does not START with a number is
104
+ * not a claim row and is skipped rather than refused — rungate's table has a
105
+ * `| consumer list |` row, and the file carries two unrelated `| mutation |`
106
+ * tables whose cells are prose.
107
+ */
108
+ const STANDING_ROW = /^\|\s*(\d+)\s*(?:[—–-][^|]*)?\|/;
109
+
110
+ /**
111
+ * Text that means the author stopped at the template.
112
+ *
113
+ * The first version was `/^(TODO\b|-+$|—$)/` — uppercase `TODO` only — and a
114
+ * review walked straight through it: `todo`, `TBD`, `FIXME`, `???`, `xxx`,
115
+ * `N/A` and a one-character `.` all scored zero violations as both the claim
116
+ * statement AND its `How it fails`. A detector narrower than what it detects,
117
+ * and the narrowing was a `[A-Z]`.
118
+ *
119
+ * The length floor catches the rest of the family without needing to
120
+ * enumerate it. Ten characters is below any real claim and above every
121
+ * placeholder anyone writes; a claim shorter than that is not a falsifiable
122
+ * statement whatever words are in it.
123
+ */
124
+ const UNFILLED = /^(TODO|TBD|FIXME|XXX|N\/?A)\b|^(\?+|-+|—|\.+)$/i;
125
+ const MIN_MEANINGFUL = 10;
126
+ function unfilled(text: string): boolean {
127
+ const t = text.trim();
128
+ return t.length < MIN_MEANINGFUL || UNFILLED.test(t);
129
+ }
130
+
131
+ export interface SuccessClaim {
132
+ number: number;
133
+ statement: string;
134
+ /** The text after `**How it fails:**`, or null when the line is absent. */
135
+ howItFails: string | null;
136
+ }
137
+
138
+ export interface SuccessDoc {
139
+ claims: SuccessClaim[];
140
+ /** Claim numbers the standing table names. */
141
+ standingRows: number[];
142
+ /** Lines still carrying the placeholder marker, by 1-based line number. */
143
+ placeholderLines: number[];
144
+ }
145
+
146
+ /** Read the structure out of a SUCCESS.md. Pure; takes the text. */
147
+ export function parseSuccessDoc(text: string): SuccessDoc {
148
+ const claims: SuccessClaim[] = [];
149
+ const standingRows: number[] = [];
150
+ const placeholderLines: number[] = [];
151
+ const lines = text.split("\n");
152
+
153
+ let current: SuccessClaim | null = null;
154
+ let fenced = false;
155
+ for (let i = 0; i < lines.length; i++) {
156
+ const line = lines[i];
157
+ if (/^\s*(```|~~~)/.test(line)) {
158
+ fenced = !fenced;
159
+ continue;
160
+ }
161
+ if (line.includes(PLACEHOLDER_MARKER)) placeholderLines.push(i + 1);
162
+ if (fenced) continue;
163
+
164
+ let heading: RegExpExecArray | null = null;
165
+ for (const form of CLAIM_FORMS) {
166
+ heading = form.exec(line);
167
+ if (heading) break;
168
+ }
169
+ if (heading) {
170
+ current = { number: Number(heading[1]), statement: heading[2].trim(), howItFails: null };
171
+ claims.push(current);
172
+ continue;
173
+ }
174
+ const fails = FALSIFIABILITY.exec(line.trim());
175
+ // Attributed to the claim it sits under. A `How it fails` before any
176
+ // claim heading belongs to nothing and is not counted, which is right —
177
+ // the template's own prose mentions the phrase above the first claim.
178
+ // FIRST one wins, so a claim's refusal always quotes the line a reader
179
+ // would look at rather than whichever duplicate came last.
180
+ //
181
+ // `current` is cleared at the next heading and the scan skips fenced
182
+ // regions, both for the same reason: without them the first matching
183
+ // line ANYWHERE below a claim satisfied it. A `Check:` six lines down
184
+ // under `## Appendix` counted, and so did one inside a ```markdown block
185
+ // — so a SUCCESS.md that documents its own format handed every claim
186
+ // below the example a falsifiability line for free.
187
+ if (fails && current && current.howItFails === null) {
188
+ current.howItFails = fails[1].trim();
189
+ continue;
190
+ }
191
+ // Any heading ends the previous claim's scope, so a falsifiability line
192
+ // under a later section cannot be borrowed by an earlier claim.
193
+ if (/^#{1,6}\s/.test(line)) current = null;
194
+ const row = STANDING_ROW.exec(line.trim());
195
+ if (row) standingRows.push(Number(row[1]));
196
+ }
197
+ return { claims, standingRows, placeholderLines };
198
+ }
199
+
200
+ /** What a reading of SUCCESS.md established, and what it could not. */
201
+ export interface SuccessVerdict {
202
+ /** Refusals. Empty means the document is structurally sound. */
203
+ violations: string[];
204
+ /** Set when there is no document to read at all. Never a silent pass. */
205
+ unmeasured: string | null;
206
+ }
207
+
208
+ /**
209
+ * The ONE place that decides whether a SUCCESS.md is real (#485).
210
+ *
211
+ * Kept separate from the conformity test and from the CLI so there is a
212
+ * single binding to mutate, and so every case can be driven without a
213
+ * filesystem.
214
+ */
215
+ export function successViolations(text: string | null, template: string | null): SuccessVerdict {
216
+ // Three states, not two. `undefined` means the caller is not asking for a
217
+ // residue comparison at all — the parser's own unit tests, which have no
218
+ // template and are not pretending to. `TEMPLATE_MISSING` (or an explicit
219
+ // `null`, in case a future reader reintroduces one) means a template WAS
220
+ // looked for and not found, and that is a refusal rather than a quiet skip.
221
+ const templateAbsent = template === TEMPLATE_MISSING || template === null;
222
+ const residueTemplate =
223
+ templateAbsent || template === NO_RESIDUE_CHECK ? undefined : template;
224
+ if (text === null) {
225
+ return {
226
+ violations: [],
227
+ unmeasured:
228
+ `UNMEASURED: this project has no SUCCESS.md, so there is nothing stating what it is ` +
229
+ `building or which claims would prove it works. That is not a failure and it is not ` +
230
+ `clean either — nothing here can be measured against a target that was never written ` +
231
+ `down. Run \`bunx rungate create-success\` to seed one.`,
232
+ };
233
+ }
234
+
235
+ if (text === UNREADABLE) {
236
+ return {
237
+ violations: [
238
+ `SUCCESS.md exists but could not be read as a regular file — it may be a symlink, a ` +
239
+ `directory, a device, or have permissions that deny reading. A symlink is refused ` +
240
+ `deliberately, the same way the scaffold refuses to write through one. That is not ` +
241
+ `the same as having no SUCCESS.md, and it is not clean: nothing could be measured.`,
242
+ ],
243
+ unmeasured: null,
244
+ };
245
+ }
246
+
247
+ // The generator's seed, untouched, is UNMEASURED rather than a failure.
248
+ //
249
+ // The scaffold now seeds this file whether or not the project asked, so a
250
+ // consumer who re-scaffolds to take an unrelated update would otherwise go
251
+ // from a green suite to a hard FAIL over a document they never wrote, with
252
+ // no way back — deleting it is undone by the next re-scaffold.
253
+ //
254
+ // And it is the honest verdict: a pristine seed carries exactly as much
255
+ // information about this project as no file at all, which is the thing
256
+ // `null` already reports as unmeasured. The refusal is aimed at a document
257
+ // somebody STARTED and left half-written, because that is the state which
258
+ // reads as considered and is not. Any edit at all moves it into that set.
259
+ if (residueTemplate && isPristineSeed(text, residueTemplate)) {
260
+ return {
261
+ violations: [],
262
+ unmeasured:
263
+ `UNMEASURED: SUCCESS.md is the generator's template, unmodified, so this project ` +
264
+ `has not yet stated what it is building or which claims would prove it works. ` +
265
+ `Nothing here is failing — nothing has been claimed yet. Edit it and this check ` +
266
+ `starts measuring; every placeholder you leave behind then becomes a refusal.`,
267
+ };
268
+ }
269
+
270
+ const doc = parseSuccessDoc(text);
271
+ const out: string[] = [];
272
+
273
+ if (doc.placeholderLines.length > 0) {
274
+ out.push(
275
+ `SUCCESS.md still carries ${doc.placeholderLines.length} placeholder marker(s) from the ` +
276
+ `generator, on line(s) ${doc.placeholderLines.join(", ")}. An unfilled template is ` +
277
+ `indistinguishable from a considered one to everything except a reader, which is why ` +
278
+ `this refuses rather than counting the file as present.`,
279
+ );
280
+ }
281
+
282
+ // The residue check could not run. Reported rather than skipped: without
283
+ // this branch an installation missing the template reverts to the pre-#502
284
+ // behaviour exactly, and the document that scored 1 violation scores 0 with
285
+ // `unmeasured` still null — indistinguishable from a clean document.
286
+ if (templateAbsent) {
287
+ out.push(
288
+ `SUCCESS.md could not be compared against the generator's template — ` +
289
+ `templates/SUCCESS-TEMPLATE.md is not in this rungate installation, so the check that ` +
290
+ `catches a document still carrying the template's prose did not run. This is not a ` +
291
+ `clean result: see test/package-closure.test.ts, which exists to stop exactly this.`,
292
+ );
293
+ }
294
+
295
+ // The backstop the marker check turned out to need. Asked before the
296
+ // per-claim rules so the loudest problem is reported first.
297
+ if (residueTemplate) {
298
+ const residue = templateResidue(text, residueTemplate);
299
+ if (residue.length > 0) {
300
+ out.push(
301
+ // "passage(s)", not "line(s) verbatim". The check now matches lines
302
+ // AND reflowed sentences, so a hit need not be a line and need not
303
+ // be verbatim — reflow surviving the comparison is the point of
304
+ // #515, and a message saying "verbatim" about a re-wrapped
305
+ // paragraph sends the reader looking for text that is not there.
306
+ // The count is a count of distinct passages, which is why a
307
+ // two-line paragraph can report more hits than it has lines.
308
+ `SUCCESS.md still carries ${residue.length} passage(s) from the generator's ` +
309
+ `template, so this document is partly unwritten: ` +
310
+ residue.slice(0, 3).map(l => JSON.stringify(l.slice(0, 70))).join(", ") +
311
+ `${residue.length > 3 ? `, and ${residue.length - 3} more` : ""}. ` +
312
+ `Deleting the placeholder markers is not the same as replacing the text they mark.`,
313
+ );
314
+ }
315
+ }
316
+
317
+ if (doc.claims.length === 0) {
318
+ out.push(
319
+ `SUCCESS.md defines no claims. The file's whole purpose is the falsifiable statements ` +
320
+ `that mean the project works. Declare one as "### Claim N — ..." or as a numbered ` +
321
+ `"N. **...**" list item.`,
322
+ );
323
+ }
324
+
325
+ for (const claim of doc.claims) {
326
+ if (unfilled(claim.statement)) {
327
+ out.push(`SUCCESS.md claim ${claim.number} has no statement — it still reads "${claim.statement}".`);
328
+ }
329
+ if (claim.howItFails === null) {
330
+ out.push(
331
+ `SUCCESS.md claim ${claim.number} has no "**How it fails:**" (or "Check:") line. A ` +
332
+ `claim nothing can falsify is a slogan — make it measurable or delete it.`,
333
+ );
334
+ } else if (unfilled(claim.howItFails)) {
335
+ out.push(
336
+ `SUCCESS.md claim ${claim.number}'s "How it fails" is still the template's placeholder ` +
337
+ `("${claim.howItFails}"), so nothing states what would prove the claim false.`,
338
+ );
339
+ }
340
+ }
341
+
342
+ // Both directions. A standing table listing a claim nobody defined is as
343
+ // broken as a claim nobody tracks, and the second is the one that rots
344
+ // quietly — a claim added and never given a row reads as met by omission.
345
+ const defined = new Set(doc.claims.map(c => c.number));
346
+ const tracked = new Set(doc.standingRows);
347
+ for (const n of [...tracked].sort((a, b) => a - b)) {
348
+ if (!defined.has(n)) {
349
+ out.push(`SUCCESS.md's standing table has a row for claim ${n}, which no claim defines.`);
350
+ }
351
+ }
352
+ for (const n of [...defined].sort((a, b) => a - b)) {
353
+ if (!tracked.has(n)) {
354
+ out.push(
355
+ `SUCCESS.md claim ${n} has no row in the standing table, so nothing records where it ` +
356
+ `actually stands. A claim with no standing reads as met by omission.`,
357
+ );
358
+ }
359
+ }
360
+
361
+ return { violations: out, unmeasured: null };
362
+ }
363
+
364
+ /**
365
+ * Lines the project still shares, verbatim, with the template it came from.
366
+ *
367
+ * ## Why the placeholder markers were not enough
368
+ *
369
+ * The first version of this check rested entirely on `PLACEHOLDER_MARKER`,
370
+ * and a security review found the hole by reading what the generator PRINTS:
371
+ * `create-success` tells the user "Replace every line marked
372
+ * `rungate:placeholder`". A user who does exactly that — deletes the five
373
+ * marker lines, names the claims, writes a `How it fails` for each, and stops
374
+ * — produced **seven surviving `TODO`s and zero violations**. `## The thing`
375
+ * was still the template's instruction text, every `**How to measure it:**`
376
+ * still read `TODO`, and `owner:`/`updated:` were still `TODO-OWNER` and
377
+ * `TODO-DATE`.
378
+ *
379
+ * One `grep -v` cleared the entire guard. That is the second shape in
380
+ * `.claude/rules/checks-must-be-able-to-fail.md` — a detector narrower than
381
+ * what it detects — and the narrowing was *instructed by our own output*.
382
+ *
383
+ * ## Why this shape rather than more rules
384
+ *
385
+ * Adding a rule per section (require a filled `## The thing`, require a
386
+ * `**How to measure it:**`, ...) would be a list that has to stay in sync
387
+ * with the template by hand, and a new template section would silently go
388
+ * unchecked. This asks the question directly instead: **is this document
389
+ * still, in part, the template?** It needs no per-section knowledge.
390
+ *
391
+ * **What it does NOT cover, stated because the first version of this
392
+ * sentence claimed otherwise.** It said "a new template section is covered
393
+ * the day it ships", and sec-485 showed that is false: anything the
394
+ * template writes as a table row, a non-claim heading, or a structurally
395
+ * pure line is invisible to this check permanently. The guarantee is
396
+ * narrower — *template PROSE, and claim statements, are covered the day
397
+ * they ship*. A future template that puts its placeholder text into table
398
+ * cells is not covered, and whoever writes one has to think about it.
399
+ *
400
+ * Two of the exclusions were narrowed in response rather than merely
401
+ * documented: claim headings now compare their statement (see below), and
402
+ * the old flat `length <= 12` floor became a test for structural purity,
403
+ * because a short sentence is still a sentence. The floor was hiding
404
+ * `"prevent."` on today's own template.
405
+ *
406
+ * Structural lines are excluded because they are SUPPOSED to match: headings,
407
+ * table rows, frontmatter keys, and anything too short to be instruction
408
+ * prose. Measured against the one real instance — rungate's own SUCCESS.md,
409
+ * written four months before the template — the only overlap is
410
+ * `doc-type: reference` and `status: active`, both frontmatter.
411
+ */
412
+ /**
413
+ * Template prose as REFLOW-INVARIANT units: whole sentences, read out of the
414
+ * template with its line breaks collapsed (#515).
415
+ *
416
+ * `templateResidue` compared line against line, so it saw a copy-pasted
417
+ * paragraph only while the line breaks were byte-identical. `prettier
418
+ * --prose-wrap`, a different editor width, or one pass of an LLM rewriting
419
+ * the file moved them without touching a word, and the whole paragraph went
420
+ * invisible. That is the second shape in
421
+ * `.claude/rules/checks-must-be-able-to-fail.md` — *text matching that a
422
+ * reformat, a line break or a different platform defeats* — and the
423
+ * docstring above claimed a guarantee it did not have.
424
+ *
425
+ * ## Why the unit is a sentence and not a block
426
+ *
427
+ * #515 proposed comparing normalized BLOCKS. Measured against the shipped
428
+ * template, that catches strictly less than the line check it would have
429
+ * replaced, and it fails the verbatim case it was meant to keep:
430
+ *
431
+ * - The template writes `<!-- rungate:placeholder -->` on the line directly
432
+ * above the prose it marks, with no blank line between, so the block IS
433
+ * the comment plus the prose. A reader who deletes the comment — which
434
+ * that comment instructs them to do — no longer matches the block. That
435
+ * is the likeliest real shape, and block comparison misses it.
436
+ * - A reader who keeps one sentence of a four-sentence paragraph no longer
437
+ * matches the block either, where the line check matched the lines kept.
438
+ *
439
+ * Splitting to sentences fixes both: the unit stops depending on where the
440
+ * newlines are AND on how much of the paragraph survived. It also drops the
441
+ * residual false-refusal surface #515 names — a single wrapped word like
442
+ * `prevent.` is never a sentence, so it stops being a comparable unit at
443
+ * all, where as a LINE it was one.
444
+ *
445
+ * `stripHtmlComments` is applied to BOTH sides, and the battery is the
446
+ * reason it is still here rather than the argument above. Making it a
447
+ * no-op was 0 red of 62 on the first pass: every comment the template
448
+ * carries sits above a `TODO` placeholder that `unfilled()` discards
449
+ * anyway, so no fixture could tell the two apart. The input that can is a
450
+ * reader keeping a template sentence and splitting it with a comment —
451
+ * `test/success-doc.test.ts`'s "an HTML comment interleaved into the prose"
452
+ * case — which is the reformat-defeats-the-detector shape one layer down.
453
+ *
454
+ * Two things measured and NOT changed, recorded so the next reader does not
455
+ * have to measure them again:
456
+ *
457
+ * - **The TEMPLATE-side strip is dead on today's template.** Dropping it is
458
+ * 0 red; dropping the DOCUMENT-side one is 1. An input that distinguishes
459
+ * them exists — template comment text quoted inside a fenced block in a
460
+ * document — but it is contrived, and a fixture built to make a number
461
+ * move is worth less than the sentence saying so. Kept for symmetry, with
462
+ * the asymmetry written down rather than implied.
463
+ * - **`unfilled()`'s 10-character floor was chosen for an EQUALITY test and
464
+ * is reused for a SUBSTRING test.** That is sound today — the shortest
465
+ * live template unit is 22 characters and the shortest non-placeholder
466
+ * one is 45, and 52,333 external markdown files produce zero new
467
+ * refusals. A future template sentence of 10-20 characters becomes a
468
+ * substring landmine against every document in a consumer repo, and the
469
+ * argument below reasons only about the 4-character `TODO`.
470
+ *
471
+ * `unfilled()` is the floor rather than a fresh number. It is already the
472
+ * module's answer to "is this string too slight to mean anything", and the
473
+ * only template unit it removes is the bare `TODO` a claim heading reduces
474
+ * to — four characters, which as a substring test would match almost every
475
+ * document in this repo.
476
+ */
477
+ function templateSentences(template: string): string[] {
478
+ const out: string[] = [];
479
+ for (const block of stripHtmlComments(template).split(/\n[ \t]*\n/)) {
480
+ const prose: string[] = [];
481
+ // `structural` is a WHOLE-LINE classifier, and inside a block only the
482
+ // leading lines are whole lines — the rest are continuations of a
483
+ // sentence that started above them. Asking it about a continuation is
484
+ // asking the wrong question, and it answers:
485
+ //
486
+ // Name the one thing that is true when this works. Do not
487
+ // hedge: a hedged claim cannot fail, and a claim that cannot
488
+ // fail is not a claim.
489
+ //
490
+ // `hedge: ...` matches the frontmatter rule, is dropped, and lines 1
491
+ // and 3 join across the hole to produce `Do not fail is not a claim.`
492
+ // — a sentence that exists nowhere, replacing one that does. Re-wrap
493
+ // the same prose one word differently and which sentence survives
494
+ // changes. That is the line-break dependence this function exists to
495
+ // remove, still present in the function that removes it.
496
+ //
497
+ // So structural lines are only recognised as a LEADING RUN. Once prose
498
+ // starts, the rest of the block is its continuation. A heading
499
+ // immediately above a paragraph still drops; a paragraph that happens
500
+ // to wrap onto `hedge:` does not.
501
+ //
502
+ // Found by sec-515 on a synthetic template. Zero instances on today's,
503
+ // which is why the fixture in `test/success-doc.test.ts` is synthetic
504
+ // too — a latent falsification of a documented guarantee is still a
505
+ // falsification.
506
+ let leading = true;
507
+ for (const line of block.split("\n").map(l => l.trim()).filter(l => l.length > 0)) {
508
+ const claim = CLAIM_HEADING.exec(line);
509
+ // A claim heading contributes its STATEMENT and not its prefix, for
510
+ // the same reason the line path strips it: `### Claim 1 — <text>` is
511
+ // a heading by syntax and the claim itself by content.
512
+ if (claim) {
513
+ if (claim[2].trim()) {
514
+ prose.push(claim[2].trim());
515
+ leading = false;
516
+ }
517
+ continue;
518
+ }
519
+ if (leading && structural(line)) continue;
520
+ leading = false;
521
+ prose.push(line);
522
+ }
523
+ if (prose.length === 0) continue;
524
+ // Joined FIRST, then split. Splitting per line would re-introduce the
525
+ // dependency on where the breaks are, which is the whole defect.
526
+ for (const sentence of collapseWhitespace(prose.join(" ")).split(SENTENCE_BREAK)) {
527
+ // No dedup here. `templateResidue` already refuses to push a unit it
528
+ // has, so a second `!out.includes` was a decider nothing could
529
+ // distinguish — measured at 0 red of 71, where the two sites in
530
+ // `templateResidue` are 1 each. Two guards answering one question are
531
+ // behaviourally one, and the dead one is invisible.
532
+ const u = sentence.trim();
533
+ if (u.length > 0 && !unfilled(u)) out.push(u);
534
+ }
535
+ }
536
+ return out;
537
+ }
538
+
539
+ /** After a terminator, before something that can open a sentence. */
540
+ const SENTENCE_BREAK = /(?<=[.!?])\s+(?=[A-Z"`*\[(])/;
541
+
542
+ /**
543
+ * ONE binding each, shared by both halves of `templateResidue` (#515).
544
+ *
545
+ * They were local to the line matcher. The sentence matcher needs the same
546
+ * two questions answered the same way, and a second private copy would be
547
+ * the fourth shape in `.claude/rules/checks-must-be-able-to-fail.md`: two
548
+ * deciders that agree, where mutating either leaves the other holding every
549
+ * case up and no behavioural test can say which one is dead.
550
+ */
551
+ const CLAIM_HEADING = /^(#{1,6}\s+\w[\w ]*\d+\s*[—–:-]\s*)(.*)$/;
552
+ const structural = (l: string) =>
553
+ l.length === 0
554
+ || /^[\s|:+_*=~-]*$/.test(l)
555
+ || l.startsWith("|")
556
+ || l.startsWith("---")
557
+ || (l.startsWith("#") && !CLAIM_HEADING.test(l))
558
+ || /^[a-z][a-z-]*:\s/.test(l);
559
+ const collapseWhitespace = (s: string) => s.replace(/\s+/g, " ").trim();
560
+
561
+ /**
562
+ * Terminated HTML comments become a space. An UNTERMINATED `<!--` is left
563
+ * exactly as it is.
564
+ *
565
+ * Written as a scan rather than `s.replace(/<!--[\s\S]*?-->/g, " ")`, which
566
+ * is quadratic on unterminated openers and runs on consumer documents.
567
+ * Measured by sec-515 through `templateResidue`, doubling the input:
568
+ *
569
+ * | input | regex | this |
570
+ * |---|---|---|
571
+ * | 80 KB (20k openers) | 616 ms | — |
572
+ * | 200 KB | 3.85 s | — |
573
+ * | 400 KB | 15.70 s | — |
574
+ * | 800 KB | 61.77 s | — |
575
+ * | 320 KB, isolated | 9.99 s | 0.1 ms |
576
+ *
577
+ * For each `<!--` the lazy body scans to end-of-input looking for `-->`,
578
+ * fails, backtracks, and the engine advances one position: O(N·L). Properly
579
+ * closed comments are fine either way — 200k of them in 3.8 ms — so the
580
+ * blowup needs only one malformed document to arrive.
581
+ *
582
+ * Anchoring the unterminated case with `(?:-->|$)` would also be linear, and
583
+ * is NOT what this does: it would make a stray `<!--` swallow the rest of
584
+ * the file, and everything after it would stop being comparable. That is a
585
+ * silent narrowing of the check, bought to fix a performance bug.
586
+ */
587
+ const stripHtmlComments = (s: string) => {
588
+ let out = "";
589
+ let i = 0;
590
+ for (;;) {
591
+ const open = s.indexOf("<!--", i);
592
+ if (open === -1) break;
593
+ const close = s.indexOf("-->", open + 4);
594
+ if (close === -1) break;
595
+ out += `${s.slice(i, open)} `;
596
+ i = close + 3;
597
+ }
598
+ return out + s.slice(i);
599
+ };
600
+
601
+ export function templateResidue(text: string, template: string): string[] {
602
+ // A claim heading is NOT structural. `### Claim 1 — TODO` is a heading by
603
+ // syntax and the claim's whole statement by content, and excluding it
604
+ // outright made every claim statement permanently invisible to this check
605
+ // — held up only by `unfilled()`, which catches `TODO` and nothing else.
606
+ // sec-485 demonstrated the consequence on a plausible next-version
607
+ // template: a document whose two claims still read "the system behaves as
608
+ // intended under normal use" scored ZERO violations, because that text
609
+ // lives in a heading. So the prefix is stripped and the STATEMENT is
610
+ // compared.
611
+ //
612
+ // The prefix is matched by SHAPE — a word-run, a number, a separator —
613
+ // rather than by the literal word `Claim` and the literal em-dash today's
614
+ // template happens to use. sec-500 measured the narrow version against
615
+ // four spellings of one statement: `Claim 1 —` and `Claim 1 -` were
616
+ // caught, `Claim 1:` and `SC 1 —` were INVISIBLE, because a heading that
617
+ // misses the pattern falls back to being excluded as structural. That is
618
+ // sec-485's finding surviving for every spelling but one, and a colon is
619
+ // not an exotic choice, so keying the check to a template detail would
620
+ // have reopened the hole on the next template edit.
621
+ //
622
+ // The cost, named because it is real: this cannot tell `Claim 1 — <a
623
+ // statement the reader must write>` from `Phase 2 - <a section title the
624
+ // reader must keep>`, so a template carrying the second gets a false
625
+ // refusal. Zero instances today — the shipped template has no numbered
626
+ // heading but its claims, and the widening flags nothing new across all
627
+ // 227 markdown files in this repo — and `test/success-doc.test.ts`'s
628
+ // "R1 cost" case fails loudly for whoever adds the first one.
629
+ const comparable = (l: string) => {
630
+ const m = CLAIM_HEADING.exec(l);
631
+ return m ? m[2].trim() : l;
632
+ };
633
+
634
+ // Structurally pure, rather than merely short.
635
+ //
636
+ // This replaced a flat `l.length <= 12` floor, which was the weakest rule
637
+ // in the check and the only one with no second layer behind it. On today's
638
+ // template it already hid a real line of body prose — `"prevent."`, eight
639
+ // characters — and on sec-485's next-version fixture it hid `Describe it.`
640
+ // and `List them.`, the entire contents of two sections. A short sentence
641
+ // is still a sentence; what cannot be residue is punctuation and table
642
+ // scaffolding, so that is what this excludes.
643
+ const mine = new Set(text.split("\n").map(l => comparable(l.trim())));
644
+ const out: string[] = [];
645
+ for (const raw of template.split("\n")) {
646
+ const l = raw.trim();
647
+ if (structural(l)) continue;
648
+ const c = comparable(l);
649
+ if (!mine.has(c)) continue;
650
+ if (!out.includes(c)) out.push(c);
651
+ }
652
+
653
+ // UNION, not replacement, and the two halves are kept because each
654
+ // reaches an input the other cannot (#515).
655
+ //
656
+ // This is the arrangement `.claude/rules/checks-must-be-able-to-fail.md`
657
+ // permits for two deciders — "keep both and give each an input only it
658
+ // can reach" — rather than the one it warns about, and the inputs are
659
+ // written down as named cases in `test/success-doc.test.ts`:
660
+ //
661
+ // | Input | Caught by |
662
+ // |---|---|
663
+ // | the paragraph REFLOWED onto one line | sentences only |
664
+ // | the paragraph with one word changed mid-sentence | lines only |
665
+ // | the paragraph verbatim | both |
666
+ //
667
+ // The line half is not redundant: a sentence is a coarser unit, so an
668
+ // edit anywhere inside one destroys the whole match, while the untouched
669
+ // LINES either side of that edit still match. Dropping it to "simplify"
670
+ // loses the partial-edit case, which is the lazy-fill this check exists
671
+ // for. Measured: the union flags nothing new across all 227 markdown
672
+ // files in this repo — the only file it refuses is the template itself.
673
+ const normalised = collapseWhitespace(stripHtmlComments(text));
674
+ for (const sentence of templateSentences(template)) {
675
+ if (!normalised.includes(sentence)) continue;
676
+ if (!out.includes(sentence)) out.push(sentence);
677
+ }
678
+ return out;
679
+ }
680
+
681
+ /**
682
+ * The installation is missing `templates/SUCCESS-TEMPLATE.md`.
683
+ *
684
+ * A distinct value rather than `null`, for the reason `UNREADABLE` is: the
685
+ * residue check is the half of this validator that catches a document which
686
+ * deleted the markers and kept the prose, and a falsy template silently
687
+ * switched it off. Same document, same checker, template absent: **1
688
+ * violation became 0, with nothing recorded.** That is the first shape in
689
+ * `.claude/rules/checks-must-be-able-to-fail.md` — a read failure defaulting
690
+ * to an empty violation list — and #484 is this repo's standing proof that
691
+ * "`templates/` is in `files[]`, so it cannot happen" is a thing that has
692
+ * already happened once while every check stayed green.
693
+ *
694
+ * `create-success` and `seedSuccessDoc` both name a missing template loudly.
695
+ * This makes `successViolations` the third reader of that file rather than
696
+ * the only one that shrugs.
697
+ */
698
+ export const TEMPLATE_MISSING = "\u0000rungate:template-missing";
699
+
700
+ /**
701
+ * "I am deliberately not comparing against the template."
702
+ *
703
+ * The opt-out the parser's own unit cases need, made explicit. The
704
+ * parameter used to be optional, so OMITTING it switched the residue check
705
+ * off silently — and the only thing keeping it on in production was that
706
+ * nobody had yet written a third call site that forgot the argument.
707
+ * Nothing asserted it; it was convention.
708
+ *
709
+ * sec-485's note, and the same move as `readSuccessTemplate(): string`
710
+ * applied to the parameter rather than the return: omission is now a type
711
+ * error, and an opt-out is something a reader sees at the call site.
712
+ */
713
+ export const NO_RESIDUE_CHECK = "\u0000rungate:no-residue-check";
714
+
715
+ /**
716
+ * The template the generator copies.
717
+ *
718
+ * Never returns `null` — an absent template is `TEMPLATE_MISSING`, which
719
+ * `successViolations` refuses. Returning a falsy value here is what made the
720
+ * residue check fail open, so the type no longer permits it.
721
+ */
722
+ export function readSuccessTemplate(): string {
723
+ const p = join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "SUCCESS-TEMPLATE.md");
724
+ return existsSync(p) ? readFileSync(p, "utf-8") : TEMPLATE_MISSING;
725
+ }
726
+
727
+ /** Read the project's SUCCESS.md, or null when there is none. */
728
+ export const UNREADABLE = "\u0000rungate:unreadable";
729
+
730
+ export function readSuccessDoc(root: string): string | null {
731
+ const p = join(root, "SUCCESS.md");
732
+ // `existsSync` is true for a DIRECTORY, and `readFileSync` then throws
733
+ // EISDIR. The throw escaped `seedSuccessDoc` and aborted the whole scaffold
734
+ // run mid-way — after some files were written and before others — which is
735
+ // a worse outcome than any verdict this function can return.
736
+ //
737
+ // It returns a distinct UNREADABLE rather than `null`, because "the file is
738
+ // there and I could not read it" and "there is no file" are different
739
+ // answers and collapsing them is the SKIP-is-indistinguishable-from-success
740
+ // shape. UNREADABLE refuses; absent is unmeasured.
741
+ let stat;
742
+ try {
743
+ stat = lstatSync(p);
744
+ } catch {
745
+ return null;
746
+ }
747
+ if (!stat.isFile()) return UNREADABLE;
748
+ try {
749
+ return readFileSync(p, "utf-8");
750
+ } catch {
751
+ return UNREADABLE;
752
+ }
753
+ }
754
+
755
+ /**
756
+ * Fill the template's owner and date. ONE substitution, two callers.
757
+ *
758
+ * `create-success` did this and `seedSuccessDoc` wrote the template raw, so
759
+ * the same logical seed produced different bytes depending on which path
760
+ * created it — a scaffolded SUCCESS.md kept `owner: TODO-OWNER` and
761
+ * `updated: TODO-DATE` forever, and nothing checked frontmatter.
762
+ */
763
+ export function seedFromTemplate(template: string, owner: string, date: string): string {
764
+ return template
765
+ .replace("owner: TODO-OWNER", `owner: ${owner}`)
766
+ .replace("updated: TODO-DATE", `updated: ${date}`);
767
+ }
768
+
769
+ /**
770
+ * Is this document the generator's seed, untouched?
771
+ *
772
+ * Owner and date are normalised out, because those are the two things the
773
+ * generator itself fills in — a seed with them substituted is still a seed.
774
+ */
775
+ export function isPristineSeed(text: string, template: string): boolean {
776
+ const norm = (t: string) =>
777
+ t.replace(/^owner:.*$/m, "owner:").replace(/^updated:.*$/m, "updated:").trim();
778
+ return norm(text) === norm(template);
779
+ }