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
@@ -102,14 +102,27 @@ function extractSCs(content: string, specFile: string): ParsedSC[] {
102
102
 
103
103
  // ── Closest pattern matching for rewrites ─────────────────────
104
104
 
105
+ export interface ClosestPattern {
106
+ patternName: string;
107
+ rewrite: string;
108
+ ambiguous: boolean;
109
+ /**
110
+ * Set ONLY by the last-resort file-token match (#589).
111
+ *
112
+ * `patternName` cannot carry this: the last resort renders `file-exists`,
113
+ * which is also the name of a real heuristic, so a caller reading the name
114
+ * alone cannot tell a pattern the statement matched from one inferred off a
115
+ * filename that happened to be in the sentence.
116
+ */
117
+ fallback?: boolean;
118
+ }
119
+
105
120
  /**
106
121
  * Score how well an SC statement matches a registry pattern by
107
122
  * looking for keyword overlaps. Returns the best pattern name and
108
123
  * a generated rewrite, or null if nothing is close enough.
109
124
  */
110
- function findClosestPattern(
111
- statement: string
112
- ): { patternName: string; rewrite: string; ambiguous: boolean } | null {
125
+ function findClosestPattern(statement: string): ClosestPattern | null {
113
126
  const registry = loadRegistry();
114
127
  const lower = statement.toLowerCase();
115
128
 
@@ -118,6 +131,10 @@ function findClosestPattern(
118
131
  pattern: string;
119
132
  keywords: string[];
120
133
  extractor: (stmt: string) => string | null;
134
+ /** All keywords must be present, not any one of them (#586). */
135
+ requireAll?: boolean;
136
+ /** The extractor ignores its argument, so it cannot be unambiguous (#586). */
137
+ constant?: boolean;
121
138
  }> = [
122
139
  {
123
140
  pattern: "pointer-exists",
@@ -228,36 +245,81 @@ function findClosestPattern(
228
245
  },
229
246
  {
230
247
  pattern: "all-specs-frontmatter",
248
+ // #586: `requireAll`, because the keyword test below is `some` and the
249
+ // bare word `frontmatter` was firing a rule about ALL SPECS. It turned
250
+ // `Baseline rules carry no paths: key in frontmatter` into
251
+ // `all specs have frontmatter` — a different, weaker property.
252
+ // "all specs" is the phrase that scopes this rule; "frontmatter" is
253
+ // the phrase it shares with every other frontmatter criterion.
254
+ requireAll: true,
231
255
  keywords: ["all specs", "frontmatter"],
232
256
  extractor: () => "all specs have frontmatter",
257
+ /**
258
+ * The extractor never reads its argument, so it cannot know what the
259
+ * criterion said. #586: that is precisely when the original must be
260
+ * kept in the file, and this rule claimed `ambiguous: false` — the
261
+ * one flag that suppresses the `<!-- REVIEW: original — … -->` marker.
262
+ */
263
+ constant: true,
233
264
  },
234
265
  {
235
266
  pattern: "canary",
236
267
  keywords: ["canary"],
237
268
  extractor: () => "canary test exists",
269
+ constant: true,
238
270
  },
239
271
  ];
240
272
 
241
273
  // Try each heuristic — first one whose extractor succeeds wins
242
274
  for (const h of heuristics) {
243
- // Check if any keyword matches
244
- const hasKeyword = h.keywords.some((k) => lower.includes(k));
275
+ const hasKeyword = h.requireAll
276
+ ? h.keywords.every((k) => lower.includes(k))
277
+ : h.keywords.some((k) => lower.includes(k));
245
278
  if (!hasKeyword) continue;
246
279
 
247
280
  const rewrite = h.extractor(statement);
248
281
  if (rewrite) {
249
- return { patternName: h.pattern, rewrite, ambiguous: false };
282
+ // A constant extractor is ambiguous BY CONSTRUCTION. Marking it
283
+ // otherwise discards the original from the file in the only case where
284
+ // nothing can reconstruct it.
285
+ return { patternName: h.pattern, rewrite, ambiguous: h.constant === true };
250
286
  }
251
287
  }
252
288
 
253
- // If no heuristic matched, try a loose file-exists match
254
- // Look for any filename-like token (word.ext) in the statement
289
+ // If no heuristic matched, try a loose file-exists match.
290
+ // Look for any filename-like token (word.ext) in the statement.
291
+ //
292
+ // #586 looked hard at narrowing this to statements whose verb is
293
+ // existence, and did not. The fallback does turn behaviour into presence —
294
+ // measured over the real tree, two criteria go through it:
295
+ //
296
+ // "Rejecting a promoted rule writes its hash to
297
+ // `reference/rejected-constraints.md` and it is never re-promoted"
298
+ // -> "reference/rejected-constraints.md exists"
299
+ //
300
+ // "Makefile targets, `package.json` scripts and CI workflow files are
301
+ // scanned for constraints alongside markdown"
302
+ // -> "package.json exists"
303
+ //
304
+ // — but it reports `ambiguous: true`, and an ambiguous rewrite writes
305
+ // `<!-- REVIEW: original — … -->` beside the line. #426 kept this path for
306
+ // exactly that reason (see SC-1587: "a lossy render by nature … kept as the
307
+ // one remaining rewrite path precisely because it writes the statement it
308
+ // replaced into the next line"). Nothing is discarded, so this is a
309
+ // DOWNGRADE, not a LOSS, and #586 is about loss.
310
+ //
311
+ // Narrowing it here turns SC-1587 and SC-1594 red for a reason those
312
+ // criteria are right about, which is how the distinction got found. The
313
+ // downgrade is #589, and it is now scoped by `coordinatedClaims` below
314
+ // rather than by narrowing the token match: WHICH statements this may
315
+ // speak for is a question about the criterion, not about the filename.
255
316
  const fileToken = statement.match(/\b(\S+\.\w{1,5})\b/);
256
317
  if (fileToken) {
257
318
  return {
258
319
  patternName: "file-exists",
259
320
  rewrite: `${fileToken[1]} exists`,
260
321
  ambiguous: true,
322
+ fallback: true,
261
323
  };
262
324
  }
263
325
 
@@ -334,7 +396,7 @@ export type RewriteDecision =
334
396
  */
335
397
  export function decideRewrite(
336
398
  statement: string,
337
- closest: { patternName: string; rewrite: string; ambiguous: boolean } | null,
399
+ closest: ClosestPattern | null,
338
400
  ): RewriteDecision {
339
401
  if (alreadyStructured(statement)) {
340
402
  return { kind: "keep", reason: "already a structured criterion — a matcher gap is not a licence to rewrite it" };
@@ -351,14 +413,180 @@ export function decideRewrite(
351
413
  };
352
414
  }
353
415
 
416
+ // #589: the last resort may only speak for a criterion that makes ONE
417
+ // claim. It takes a filename-like token from anywhere in a sentence and
418
+ // renders the whole criterion as `<that file> exists`, which can be about
419
+ // at most one thing — so a criterion that coordinates a second claim is
420
+ // guaranteed to come back as a statement about something else.
421
+ //
422
+ // Measured over the corpus `--fix` edits: two criteria went through it,
423
+ // SC-1940 (a hash is written AND the rule never resurfaces) and SC-1943 (a
424
+ // three-item subject of which the filename is one). Both are kept now.
425
+ //
426
+ // Scoped to the fallback deliberately. A heuristic that MATCHED the
427
+ // statement was chosen by what the statement says; the last resort was
428
+ // chosen by a filename being present, and that is the difference this
429
+ // guard is about.
430
+ if (closest.fallback) {
431
+ const claims = coordinatedClaims(statement);
432
+ if (claims.length > 0) {
433
+ return {
434
+ kind: "keep",
435
+ reason:
436
+ `rewriting as ${closest.patternName} would assert only that ${closest.rewrite}, ` +
437
+ `while the criterion coordinates a further claim (${claims[0]}) — ` +
438
+ `the file is mentioned, not what the criterion is about`,
439
+ };
440
+ }
441
+ }
442
+
354
443
  const rationale = rationaleOf(statement);
355
444
  const rewritten = rationale ? `${closest.rewrite} — ${rationale}` : closest.rewrite;
445
+
446
+ // #586: the fourth guard, and the general one. The three above protect
447
+ // specific things — a structured line, a missing pattern, a named file.
448
+ // This one asks the question they are each a special case of: **does the
449
+ // rewrite still say what the criterion was about?**
450
+ //
451
+ // It exists because the three above all passed on
452
+ // `Baseline rules carry no paths: key in frontmatter`, which was rewritten
453
+ // to `all specs have frontmatter`. Nothing of the original survived and no
454
+ // guard was looking at that.
455
+ //
456
+ // It asks the question of `rewritten`, not of `closest.rewrite`, and the
457
+ // difference is #426's SC-1591: the rationale clause is carried across, so
458
+ // a statement whose meaning lives in its `— because …` half survives a
459
+ // constant rewrite with that half intact. Asking it of the bare pattern
460
+ // text refuses those, which turns the enricher off for every criterion
461
+ // that explains itself. SC-1930 has no rationale clause, so nothing of it
462
+ // survives either way and it is still refused.
463
+ const terms = distinguishingTerms(statement);
464
+ const lowered = rewritten.toLowerCase();
465
+ if (terms.length > 0 && !terms.some(t => lowered.includes(t))) {
466
+ return {
467
+ kind: "keep",
468
+ reason:
469
+ `rewriting as ${closest.patternName} would drop every distinguishing term the ` +
470
+ `criterion uses (${terms.join(", ")}) — the rewrite would be about something else`,
471
+ };
472
+ }
473
+
356
474
  if (rewritten === statement) {
357
475
  return { kind: "keep", reason: "the rewrite is what is already written" };
358
476
  }
359
477
  return { kind: "rewrite", statement: rewritten };
360
478
  }
361
479
 
480
+ /**
481
+ * The words that say what THIS criterion is about (#586).
482
+ *
483
+ * Deliberately not "every word": a rewrite legitimately drops grammar, and
484
+ * the term that caused the heuristic to fire is shared with every other
485
+ * criterion the heuristic matches. Counting the MATCHED keyword as retained
486
+ * content is how a constant rewrite reads as a faithful one — the proxy
487
+ * standing in for the property, which `.claude/rules/checks-must-be-able-to-fail.md`
488
+ * names as the trap in wording a refusal.
489
+ *
490
+ * So: lowercase alphanumeric tokens of four characters or more, minus
491
+ * stopwords, minus the vocabulary every registry pattern already uses.
492
+ */
493
+ const REWRITE_STOPWORDS = new Set([
494
+ "that", "this", "with", "from", "have", "has", "does", "must", "will", "when",
495
+ "then", "than", "each", "every", "into", "over", "under", "about", "there",
496
+ "their", "which", "where", "while", "been", "being", "they", "them", "than",
497
+ // The registry's own vocabulary. A rewrite keeping only these has kept
498
+ // nothing specific to the criterion it replaced.
499
+ "frontmatter", "specs", "spec", "exists", "contains", "canary", "test",
500
+ "tests", "file", "files", "all", "none",
501
+ ]);
502
+
503
+ export function distinguishingTerms(statement: string): string[] {
504
+ const words = statement.toLowerCase().match(/[a-z0-9]{4,}/g) ?? [];
505
+ return [...new Set(words)].filter(w => !REWRITE_STOPWORDS.has(w));
506
+ }
507
+
508
+ /**
509
+ * The further claims this criterion coordinates, if any (#589).
510
+ *
511
+ * Returns the clause after each `and`/`or`, so the refusal can name what the
512
+ * rewrite would have dropped rather than merely reporting that something was
513
+ * dropped. Empty for a criterion that makes one claim.
514
+ *
515
+ * One exported binding, so there is exactly one thing to mutate — and it is
516
+ * the only thing that decides which statements the last resort may speak
517
+ * for.
518
+ */
519
+ export function coordinatedClaims(statement: string): string[] {
520
+ const claims: string[] = [];
521
+ const coordinator = /\s+(?:and|or)\s+/gi;
522
+ let m: RegExpExecArray | null;
523
+ while ((m = coordinator.exec(statement)) !== null) {
524
+ const rest = statement.slice(m.index + m[0].length).trim();
525
+ // A trailing coordinator joins nothing. An empty string here would read
526
+ // as a second claim whose text is gone, and refuse a rewrite on it.
527
+ if (rest.length > 0) claims.push(rest);
528
+ }
529
+ return claims;
530
+ }
531
+
532
+ /**
533
+ * `findClosestPattern`, exported so a test can drive the real decision.
534
+ *
535
+ * One binding (#586). A test that reimplemented the heuristic walk would
536
+ * agree with it right up until somebody changed one of them.
537
+ */
538
+ export function closestPatternFor(statement: string): ClosestPattern | null {
539
+ return findClosestPattern(statement);
540
+ }
541
+
542
+ // ── Editing one SC line ───────────────────────────────────────
543
+
544
+ /**
545
+ * Put `replacement` where `match` was, as LITERAL TEXT (#586).
546
+ *
547
+ * `String.prototype.replace(re, string)` treats the second argument as a
548
+ * replacement TEMPLATE: `$'` is "everything after the match", `$&` is the
549
+ * match, `$1` is the first capture group. Every one of those is a sequence a
550
+ * success criterion can legitimately contain — `--fix` is a tool for editing
551
+ * documents written by people about shell and regex syntax — and the text
552
+ * being substituted in here is the criterion itself.
553
+ *
554
+ * Measured before this existed, on a four-criterion fixture whose first
555
+ * statement read ``Baseline rules carry no $' key in frontmatter``:
556
+ *
557
+ * - [ ] SC-9301: Baseline rules carry no <- its text, truncated
558
+ * - [ ] SC-9302: … <- the remainder of the
559
+ * - [ ] SC-9303: … document, pasted in
560
+ * - [ ] SC-9304: …
561
+ * key in frontmatter
562
+ *
563
+ * Three ids now appeared twice in one spec and one criterion had lost its
564
+ * statement — on a run whose own ledger reported `kept` and `before ===
565
+ * after` for all four. The report and the file disagreed and only the report
566
+ * was ever read.
567
+ *
568
+ * It splices by INDEX rather than re-running the regex, which also removes
569
+ * the second search: the caller has already found the line, and a function
570
+ * that searched for it again would be a second answer to a question that was
571
+ * already answered.
572
+ */
573
+ function replaceLine(content: string, match: RegExpMatchArray, replacement: string): string {
574
+ const at = match.index!;
575
+ return content.slice(0, at) + replacement + content.slice(at + match[0].length);
576
+ }
577
+
578
+ /**
579
+ * Does `marker` already sit on the line directly below the matched line?
580
+ *
581
+ * The question the suppression guard has to ask (#586). It used to ask
582
+ * `modified.includes(marker)` — of the WHOLE FILE — so the second criterion
583
+ * declined for a given reason was silently left unmarked, and the commonest
584
+ * reason by far is the generic "no registry pattern was close enough".
585
+ */
586
+ function followsWith(content: string, match: RegExpMatchArray, marker: string): boolean {
587
+ return content.slice(match.index! + match[0].length).startsWith(`\n${marker}`);
588
+ }
589
+
362
590
  // ── Core audit function ───────────────────────────────────────
363
591
 
364
592
  export function auditSpecs(
@@ -432,8 +660,15 @@ export function auditSpecs(
432
660
  // the file it names or the prose that says why it exists.
433
661
  if (decision.kind === "keep") {
434
662
  const marker = `<!-- REVIEW: unmatched (${decision.reason}) -->`;
435
- if (!modified.includes(marker)) {
436
- modified = modified.replace(scLinePattern, `${scMatch[0]}\n${marker}`);
663
+ // #586: asked of THIS criterion's own next line, not of the whole
664
+ // file. A file-wide `includes` meant that two criteria declined
665
+ // for the same reason — and "no registry pattern was close enough"
666
+ // is the commonest reason there is — shared one marker: measured
667
+ // at four unmatched criteria and one marker. The three unmarked
668
+ // ones read as reviewed because of a comment about a different
669
+ // criterion.
670
+ if (!followsWith(modified, scMatch, marker)) {
671
+ modified = replaceLine(modified, scMatch, `${scMatch[0]}\n${marker}`);
437
672
  hasChanges = true;
438
673
  }
439
674
  rewrites.push({
@@ -452,7 +687,7 @@ export function auditSpecs(
452
687
  if (closest!.ambiguous) {
453
688
  replacement += `\n<!-- REVIEW: original — ${usc.statement} -->`;
454
689
  }
455
- modified = modified.replace(scLinePattern, replacement);
690
+ modified = replaceLine(modified, scMatch, replacement);
456
691
  hasChanges = true;
457
692
  rewrites.push({
458
693
  scId: usc.id,
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env bun
2
2
  import { readFileSync, readdirSync } from "fs";
3
3
  import { join, basename, resolve } from "path";
4
+ import { localCalendarDay } from "../lib/local-calendar-day";
4
5
  import {
5
6
  type ToolCall,
6
7
  type TranscriptData,
@@ -184,7 +185,7 @@ export function formatReport(audits: AgentAudit[]): string {
184
185
  const lines: string[] = [];
185
186
  lines.push("# Workflow Transcript Audit Report");
186
187
  lines.push(`\nAudited: ${audits.length} agents`);
187
- lines.push(`Date: ${new Date().toISOString().split("T")[0]}`);
188
+ lines.push(`Date: ${localCalendarDay()}`);
188
189
 
189
190
  const avgScore = Math.round(audits.reduce((s, a) => s + a.score, 0) / audits.length);
190
191
  lines.push(`\n## Summary: ${avgScore}% average (${audits.map((a) => a.grade).join(", ")})`);
@@ -16,6 +16,7 @@
16
16
  import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
17
17
  import { join, basename, dirname } from "path";
18
18
  import { SIGNAL_PHRASE_PATTERNS } from "../lib/signal-phrases";
19
+ import { localCalendarDay } from "../lib/local-calendar-day";
19
20
 
20
21
  // ── Argument parsing ──────────────────────────────────────────
21
22
 
@@ -225,7 +226,7 @@ function deriveSlug(title: string): string {
225
226
  // ── Spec generation ───────────────────────────────────────────
226
227
 
227
228
  function generateSpec(rules: ExtractedRule[], title: string, governs: string): string {
228
- const today = new Date().toISOString().split("T")[0];
229
+ const today = localCalendarDay();
229
230
 
230
231
  // Build SC lines
231
232
  const scLines = rules.map((rule, i) => {
@@ -11,13 +11,13 @@
11
11
  */
12
12
  import { readFileSync, writeFileSync, existsSync } from "fs";
13
13
  import {
14
+ allocateScNumber,
14
15
  generateSCText,
15
16
  listPatterns,
16
- nextSCNumber,
17
17
  formatSCLine,
18
18
  } from "../lib/create-sc";
19
19
  import { readScRegistry } from "./sync-sc-status";
20
- import { scIdsSpelledInSource } from "../lib/sc-ids";
20
+ import { describeReading } from "../lib/sc-id-cross-tree";
21
21
  import { join } from "path";
22
22
 
23
23
  /** Same resolution sync-sc-status uses, so both halves read one tree. */
@@ -83,17 +83,27 @@ try {
83
83
  // spell SC ids in the same namespace without appearing in any registry,
84
84
  // so an allocation that consults only the registry can mint a criterion
85
85
  // out of a number a fixture already depends on.
86
- const scNumber = nextSCNumber(
87
- content,
88
- readScRegistry(),
89
- scIdsSpelledInSource(ROOT).keys(),
90
- );
86
+ //
87
+ // And a THIRD half, which is the one the first two could not see (#503):
88
+ // the registry is `specs/` in whichever working tree this command runs
89
+ // in. Two sessions in two worktrees both read "highest + 1" correctly and
90
+ // both got the same number.
91
+ //
92
+ // All three widths compose inside `allocateScNumber`, so this CLI cannot
93
+ // assemble two of them and believe it asked.
94
+ const { number: scNumber, namespace } = allocateScNumber(ROOT, content, readScRegistry());
91
95
  const scLine = formatSCLine(scNumber, statement);
92
96
 
93
97
  // Append SC line to the end of the file
94
98
  const newContent = content.trimEnd() + "\n" + scLine + "\n";
95
99
  writeFileSync(specPath, newContent);
96
100
  console.log(`Appended to ${specPath}: ${scLine}`);
101
+ // What the number is a floor over, stated rather than implied. A clone on
102
+ // another machine is outside anything this process can reach, and an
103
+ // allocator that printed only the number would be claiming a guarantee it
104
+ // cannot give (`.claude/rules/config-access.md`).
105
+ console.log(` namespace: ${describeReading(namespace)}`);
106
+ for (const gap of namespace.unmeasured) console.log(` UNMEASURED: ${gap}`);
97
107
  } else {
98
108
  // Output to stdout for piping
99
109
  const scLine = formatSCLine(0, statement);
@@ -17,6 +17,7 @@ import { existsSync, writeFileSync, mkdirSync } from "fs";
17
17
  import { join } from "path";
18
18
  import { isMatchablePattern, isBehavioralSC, type ParsedSC } from "../lib/conformity";
19
19
  import { loadRegistry, type RegistryEntry } from "../lib/create-sc";
20
+ import { localCalendarDay } from "../lib/local-calendar-day";
20
21
 
21
22
  // ── Argument parsing ──────────────────────────────────────────
22
23
 
@@ -123,7 +124,7 @@ if (scStatements.length > 0) {
123
124
 
124
125
  // ── Generate spec content ─────────────────────────────────────
125
126
 
126
- const today = new Date().toISOString().split("T")[0];
127
+ const today = localCalendarDay();
127
128
 
128
129
  // Build SC lines from validated --sc statements, or use placeholder
129
130
  let scSection: string;
@@ -0,0 +1,163 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * `rungate create-success` — seed the file the methodology calls the measure (#485).
4
+ *
5
+ * A sibling of `create-spec`, and deliberately the dumbest one: it copies a
6
+ * template and fills in the owner and the date. **It does not invent
7
+ * claims.** Five plausible generated claims would be worse than none,
8
+ * because they read as considered and are not, and the conformity check
9
+ * refuses while any placeholder survives — so a project that runs this and
10
+ * stops is LOUDER than one that never ran it, which is the intended
11
+ * direction.
12
+ *
13
+ * Refuses to overwrite. A project's SUCCESS.md is the one document nothing
14
+ * should regenerate over, and `--force` exists only because a half-written
15
+ * seed is a thing people want to restart.
16
+ */
17
+
18
+ import { existsSync, lstatSync, readFileSync, unlinkSync, writeFileSync } from "fs";
19
+ import { dirname, join, resolve } from "path";
20
+ import { fileURLToPath } from "url";
21
+ import { seedFromTemplate } from "../lib/success-doc";
22
+ import { localCalendarDay } from "../lib/local-calendar-day";
23
+
24
+ const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
25
+
26
+ /**
27
+ * A flag's value, refusing the next FLAG as a value.
28
+ *
29
+ * `--project-root --force` returned `"--force"` and the script then ENOENTed
30
+ * with a raw stack on `--force/SUCCESS.md` — in a file whose own comment
31
+ * says "Named rather than swallowed" about exactly this class of failure,
32
+ * one argv slot away.
33
+ */
34
+ function arg(name: string): string | null {
35
+ const i = process.argv.indexOf(`--${name}`);
36
+ if (i === -1 || i + 1 >= process.argv.length) return null;
37
+ const value = process.argv[i + 1];
38
+ if (value.startsWith("--")) {
39
+ console.error(`create-success: --${name} needs a value, but the next argument is ${value}.`);
40
+ process.exit(1);
41
+ }
42
+ return value;
43
+ }
44
+
45
+ // `resolve`, so the path reported back is the one actually written. A
46
+ // relative or `..`-bearing root is the user's to choose — this is a local
47
+ // CLI and they can write anywhere they can write — but it must be VISIBLE,
48
+ // and `join` normalising traversal silently is how a mistyped root lands
49
+ // somewhere nobody notices.
50
+ const root = resolve(arg("project-root") ?? process.cwd());
51
+ const force = process.argv.includes("--force");
52
+ const target = join(root, "SUCCESS.md");
53
+
54
+ // `lstatSync`, NOT `existsSync`. BUG-440-A's shape: `existsSync` RESOLVES a
55
+ // symlink and `writeFileSync` FOLLOWS one, so a dangling
56
+ // `SUCCESS.md -> /elsewhere/x` reads as absent to the guard and as a live
57
+ // target to the writer. Measured before this line existed: the command
58
+ // reported "Created SUCCESS.md" and wrote 2,007 bytes to
59
+ // `/tmp/symprobe/victim/absent.md`, outside the project entirely. With
60
+ // `--force` and a symlink to a REAL file it destroyed a 26-byte hand-written
61
+ // note the same way, exit 0, refusal never reached.
62
+ //
63
+ // `lstatSync` describes the LINK, so both kinds count as "already there".
64
+ let present = true;
65
+ let stat: ReturnType<typeof lstatSync> | null = null;
66
+ try {
67
+ stat = lstatSync(target);
68
+ } catch {
69
+ present = false;
70
+ }
71
+
72
+ // A DIRECTORY at `SUCCESS.md` is neither "replace it" nor "absent". Without
73
+ // this, `--force` reached `unlinkSync` on a directory and the user got a raw
74
+ // stack trace out of `scripts/create-success.ts:82` — the right exit code
75
+ // with none of the information. `--force` means "restart this project's
76
+ // SUCCESS.md", and there is no reading of that which includes removing a
77
+ // directory tree, so it refuses rather than guessing.
78
+ if (present && stat && !stat.isFile() && !stat.isSymbolicLink()) {
79
+ console.error(
80
+ `create-success: ${target} is not a regular file (it is a ${
81
+ stat.isDirectory() ? "directory" : "special file"
82
+ }).\n` +
83
+ `Neither --force nor a plain run will remove it — move or delete it yourself if you ` +
84
+ `meant that, so the removal is something you did rather than something this did.`,
85
+ );
86
+ process.exit(1);
87
+ }
88
+
89
+ if (present && !force) {
90
+ console.error(
91
+ `create-success: ${target} already exists.\n` +
92
+ `This file is the project's own, and regenerating over it would discard the ` +
93
+ `claims someone thought about. Pass --force only if you mean to restart it.`,
94
+ );
95
+ process.exit(1);
96
+ }
97
+
98
+ const templatePath = join(PACKAGE_ROOT, "templates", "SUCCESS-TEMPLATE.md");
99
+ if (!existsSync(templatePath)) {
100
+ // Named rather than swallowed: #484 was a documented command that ENOENTed
101
+ // for every consumer because `files[]` omitted the directory it read from.
102
+ console.error(
103
+ `create-success: templates/SUCCESS-TEMPLATE.md is not in this installation. ` +
104
+ `The package's "files" field and this script disagree — see ` +
105
+ `test/package-closure.test.ts, which exists to stop this.`,
106
+ );
107
+ process.exit(1);
108
+ }
109
+
110
+ // `||`, not `??`. `??` guards null and undefined only, so `USER=""` — an
111
+ // empty environment, a container, a cron job — produced a bare `owner:`.
112
+ const owner = arg("owner") || process.env.USER || "TODO-OWNER";
113
+ // The owner goes into YAML frontmatter verbatim, so a newline or a colon
114
+ // lets it introduce keys: `--owner $'evil\nstatus: deprecated\ndoc-type: spec'`
115
+ // wrote a duplicate `status` and an attacker-chosen `doc-type` into a file
116
+ // other tooling parses. Refused rather than quoted — a SUCCESS.md owner with
117
+ // a colon in it is a typo every time.
118
+ if (/[\r\n:]/.test(owner)) {
119
+ console.error(
120
+ `create-success: --owner may not contain a newline or a colon (got ${JSON.stringify(owner)}).\n` +
121
+ `It is written into YAML frontmatter, where either one would introduce a new key.`,
122
+ );
123
+ process.exit(1);
124
+ }
125
+ const today = localCalendarDay();
126
+
127
+ // The SHARED substitution, so this and the scaffold's seed step cannot
128
+ // produce different bytes for the same logical seed.
129
+ const body = seedFromTemplate(readFileSync(templatePath, "utf-8"), owner, today);
130
+
131
+ // `--force` means "restart THIS project's SUCCESS.md", never "write through
132
+ // whatever this path points at". Unlinking first turns a symlink into an
133
+ // absent path, so the `wx` write below creates a real file here rather than
134
+ // following the link somewhere else.
135
+ if (force && present) unlinkSync(target);
136
+
137
+ // `wx` is `O_CREAT|O_EXCL`: it refuses an existing path AND refuses a
138
+ // symlink, dangling or not, at the syscall rather than in a check above it.
139
+ // That also closes the window between the `lstatSync` and this line — a
140
+ // guard-then-write is a TOCTOU by construction, and the flag makes the
141
+ // refusal atomic instead of merely early.
142
+ try {
143
+ writeFileSync(target, body, { flag: "wx" });
144
+ } catch (e) {
145
+ console.error(
146
+ `create-success: refused to write ${target} — ${(e as Error).message}\n` +
147
+ `Something is at that path that was not there a moment ago, or it is a ` +
148
+ `symlink. The generator will not write through either.`,
149
+ );
150
+ process.exit(1);
151
+ }
152
+
153
+ console.log(`Created ${target} (from templates/SUCCESS-TEMPLATE.md)
154
+
155
+ It is a TEMPLATE and the conformity suite REFUSES it in this state, on purpose.
156
+ Replace every line marked \`rungate:placeholder\`:
157
+
158
+ - the one sentence under "The thing"
159
+ - what you are deliberately NOT building
160
+ - each claim, its "How it fails" and its "How to measure it"
161
+ - the standing table, which should say \`untested\` until something measures it
162
+
163
+ Delete the claims you do not need. Three well-chosen claims beat five padded ones.`);