rungate 0.5.0 → 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 (55) hide show
  1. package/lib/agents-md-sections.ts +144 -0
  2. package/lib/branch-diff.ts +139 -0
  3. package/lib/bun-version.ts +268 -0
  4. package/lib/ci-checkout.ts +1 -1
  5. package/lib/compliance.ts +13 -11
  6. package/lib/config-loader.ts +12 -0
  7. package/lib/conformity.ts +184 -88
  8. package/lib/context-docs.ts +143 -28
  9. package/lib/create-brief.ts +2 -1
  10. package/lib/create-sc.ts +90 -4
  11. package/lib/doc-scan-targets.ts +9 -0
  12. package/lib/evidence-command-transport.ts +160 -0
  13. package/lib/evidence-prevalidator.ts +22 -0
  14. package/lib/fallow-availability.ts +129 -0
  15. package/lib/gate-refusal-currency.ts +112 -0
  16. package/lib/gate-timeouts.ts +82 -0
  17. package/lib/generators/agent-briefs.ts +4 -1
  18. package/lib/generators/agents-md.ts +71 -23
  19. package/lib/generators/code-map.ts +2 -1
  20. package/lib/generators/types.ts +8 -0
  21. package/lib/git-dates.ts +55 -0
  22. package/lib/junit-checks.ts +484 -0
  23. package/lib/local-calendar-day.ts +78 -0
  24. package/lib/project-state-shape.ts +59 -0
  25. package/lib/promote-outputs.ts +6 -2
  26. package/lib/report-provenance.ts +156 -0
  27. package/lib/sc-claim-forms.ts +75 -0
  28. package/lib/sc-id-cross-tree.ts +311 -0
  29. package/lib/scaffold/ai-review-step.ts +180 -0
  30. package/lib/scaffold/owned-files.ts +42 -2
  31. package/lib/scaffold/rehearsal.ts +205 -71
  32. package/lib/scaffold/steps.ts +128 -73
  33. package/lib/scaffold/write-steps.ts +6 -4
  34. package/lib/scanner.ts +38 -12
  35. package/lib/spec-listing.ts +148 -0
  36. package/lib/spec-requirements.ts +209 -0
  37. package/lib/suite-run-reading.ts +170 -0
  38. package/lib/test-command.ts +133 -0
  39. package/lib/test-suite-lock.ts +166 -10
  40. package/lib/tool-probe.ts +120 -0
  41. package/lib/tracked-vs-ignored.ts +234 -0
  42. package/lib/validators/spec-validators.ts +3 -2
  43. package/package.json +1 -1
  44. package/scripts/audit-specs.ts +247 -12
  45. package/scripts/audit-transcript.ts +2 -1
  46. package/scripts/convert-spec.ts +2 -1
  47. package/scripts/create-sc.ts +17 -7
  48. package/scripts/create-spec.ts +2 -1
  49. package/scripts/create-success.ts +2 -1
  50. package/scripts/extract-constraints.ts +90 -19
  51. package/scripts/generate-code-map.ts +53 -12
  52. package/scripts/scaffold-project.ts +4 -1
  53. package/scripts/split-spec.ts +2 -1
  54. package/scripts/sync-sc-status.ts +57 -5
  55. package/scripts/sync-spec-tests.ts +2 -1
package/lib/create-sc.ts CHANGED
@@ -9,7 +9,9 @@ import { join, dirname } from "path";
9
9
  import { fileURLToPath } from "url";
10
10
 
11
11
  import type { ScRegistry } from "./sc-ids";
12
- import { isFixtureScId } from "./sc-ids";
12
+ import { isFixtureScId, scIdsSpelledInSource, SC_SOURCE_DIRS } from "./sc-ids";
13
+ import type { ScNamespaceReading, SourceReading } from "./sc-id-cross-tree";
14
+ import { readScNamespace } from "./sc-id-cross-tree";
13
15
  import { tryLoadRungateConfig } from "./config-loader";
14
16
 
15
17
  // ── Types ─────────────────────────────────────────────────────
@@ -267,6 +269,18 @@ export function listPatterns(): string {
267
269
  * collision this function exists to prevent. The reservation is enforced
268
270
  * against specs by SC-1524, not by making the allocator pretend.
269
271
  */
272
+ /**
273
+ * The ids a spec's own text spells, as one binding.
274
+ *
275
+ * The allocator counts them and the reading reports how many it counted; two
276
+ * scans of the same string would be two deciders that agree, and a reading
277
+ * whose numbers come from a different pattern than the allocation used is a
278
+ * reading of something else.
279
+ */
280
+ function idsInSpecContent(specContent: string): string[] {
281
+ return [...specContent.matchAll(/SC-(\d+)/g)].map(m => m[0]);
282
+ }
283
+
270
284
  export function nextSCNumber(
271
285
  specContent: string,
272
286
  reg?: ScRegistry,
@@ -277,15 +291,87 @@ export function nextSCNumber(
277
291
  const n = Number(raw.replace(/^SC-[A-Z]?/, ""));
278
292
  if (Number.isFinite(n)) ids.push(n);
279
293
  };
280
- const pattern = /SC-(\d+)/g;
281
- let match;
282
- while ((match = pattern.exec(specContent)) !== null) take(match[0]);
294
+ for (const raw of idsInSpecContent(specContent)) take(raw);
283
295
  for (const id of reg?.declaredById.keys() ?? []) take(id);
284
296
  for (const id of spelledInSource ?? []) if (!isFixtureScId(id)) take(id);
285
297
  if (ids.length === 0) return 1;
286
298
  return Math.max(...ids) + 1;
287
299
  }
288
300
 
301
+ /**
302
+ * The next free SC number for a project, over every namespace this machine
303
+ * can see (#503).
304
+ *
305
+ * `nextSCNumber` answers the question for the arguments it is handed, and
306
+ * three widths of that question have each been wrong in turn: one spec's
307
+ * content (#392), the spec registry without test fixtures (#399), and the
308
+ * registry of whichever working tree the command ran in (#503). This is the
309
+ * composition, in one place, so a caller cannot assemble two of the three and
310
+ * believe it asked.
311
+ *
312
+ * It returns the reading alongside the number because the number is a FLOOR:
313
+ * a clone on another machine is outside anything this process can reach, and
314
+ * a caller that printed only the number would be claiming a guarantee the
315
+ * reading explicitly does not give.
316
+ *
317
+ * ## `reg` is REQUIRED, and was optional for two issues (#593)
318
+ *
319
+ * Omit it and `nextSCNumber` skips `reg.declaredById` entirely: the answer is
320
+ * assembled from the spec's own content, source-spelled fixtures and the
321
+ * cross-tree namespace, and the spec registry — the width #392 was filed
322
+ * over — is not consulted at all. The number comes back looking exactly like
323
+ * one that had asked everything, which is the composition failure the
324
+ * paragraph above says this function exists to make impossible. A caller
325
+ * with no registry to hand has `buildScRegistry([])`, which states "this
326
+ * tree declares nothing" instead of defaulting to it.
327
+ *
328
+ * The two readings agree whenever every spec-declared id is also spelled in
329
+ * a source file, which is most of the time and is why nothing noticed. They
330
+ * diverged the day a spec declared eight criteria no test mentioned yet.
331
+ *
332
+ * ## The reading names every leg, not just the cross-tree ones
333
+ *
334
+ * `readScNamespace` accounts for the worktrees and refs it read. The other
335
+ * three widths were invisible in the returned reading, so a CLI could print
336
+ * the number and a complete-looking account of where it came from while one
337
+ * of the legs behind it had never run. They are appended as sources of their
338
+ * own, with the count each contributed — `0` from a leg that was consulted
339
+ * and `0` from a leg that was skipped are the same number and opposite
340
+ * facts (`.claude/rules/config-access.md`).
341
+ */
342
+ export function allocateScNumber(
343
+ root: string,
344
+ specContent: string,
345
+ reg: ScRegistry,
346
+ ): { number: number; namespace: ScNamespaceReading } {
347
+ const namespace = readScNamespace(root);
348
+ const spelled = [...scIdsSpelledInSource(root).keys()];
349
+ const number = nextSCNumber(specContent, reg, [...spelled, ...namespace.ids.keys()]);
350
+
351
+ const legs: SourceReading[] = [
352
+ {
353
+ label: "the spec's own content",
354
+ kind: "spec-content",
355
+ status: "read",
356
+ found: new Set(idsInSpecContent(specContent)).size,
357
+ },
358
+ {
359
+ label: "spec registry (every declared id, checkbox and heading)",
360
+ kind: "registry",
361
+ status: "read",
362
+ found: reg.declaredById.size,
363
+ },
364
+ {
365
+ label: `SC ids spelled under ${SC_SOURCE_DIRS.join(", ")}`,
366
+ kind: "source-mentions",
367
+ status: "read",
368
+ found: new Set(spelled).size,
369
+ },
370
+ ];
371
+
372
+ return { number, namespace: { ...namespace, sources: [...legs, ...namespace.sources] } };
373
+ }
374
+
289
375
  /**
290
376
  * Format an SC line for appending to a spec file.
291
377
  */
@@ -393,6 +393,15 @@ export function planDocScan(projectPath: string): DocScanPlan {
393
393
  if (real === null) { st.refused.push(path); continue; }
394
394
  if (st.seen.has(real)) continue;
395
395
  st.seen.add(real);
396
+ // A name is not a file type. `walkMarkdown` asks `statSync` before it
397
+ // decides; this loop asked only the suffix, so a DIRECTORY called
398
+ // `NOTES.md` at the project root was planned as a document and handed
399
+ // to `readFileSync`, which throws EISDIR — the plan claimed a file it
400
+ // could never read (#508). Nothing reports it either way: a directory
401
+ // with a markdown name carries no prose.
402
+ let isFile: boolean;
403
+ try { isFile = statSync(real).isFile(); } catch { continue; }
404
+ if (!isFile) continue;
396
405
  if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
397
406
  st.files.push(anchored(projectPath, st.rootReal, real));
398
407
  }
@@ -0,0 +1,160 @@
1
+ /**
2
+ * Moving an agent-authored evidence command from discovery to the state file,
3
+ * and recording every legitimate change made to one on the way (#614).
4
+ *
5
+ * ## The defect this module exists for
6
+ *
7
+ * `workflows/ship.js` persisted discovery's ACs by interpolating
8
+ * `JSON.stringify(discovery.acs…)` into a DOUBLE-QUOTED `bun -e "…"` shell
9
+ * string in the setup agent's prompt. Inside double quotes a shell expands
10
+ * `$1` to the empty string, `${VAR}` to the environment, and `$(cmd)` by
11
+ * RUNNING it. On run `wf_c92dd0a7-fe6` the command
12
+ *
13
+ * grep -rhcE '^export function localCalendarDay' lib | awk '{s+=$1} END {print s+0}'
14
+ *
15
+ * arrived in `workflow-state.json` as `awk '{s+=} END {print s+0}'` — an awk
16
+ * syntax error. The AC could never produce evidence, stayed PENDING, and took
17
+ * the verify gate down with four failures. The blast radius was every evidence
18
+ * command containing a `$`.
19
+ *
20
+ * The fix is to stop putting agent-authored text where a shell looks. The
21
+ * payload leaves the generator as a SINGLE-QUOTED argument — the one shell
22
+ * construct with no expansion inside it at all — and the `bun -e` program
23
+ * reads it out of `process.argv` instead of carrying it as program text.
24
+ *
25
+ * ## Why the provenance half is in the same module
26
+ *
27
+ * Three places legitimately rewrite an evidence command: discovery's path
28
+ * normaliser, discovery's evidence-type-ratio upgrade, and the git-ref
29
+ * qualification at the execution boundary (#118). Each used to overwrite
30
+ * `evidenceMethod.command` in place, so a reader of a broken command could not
31
+ * tell a repair from a corruption — which is exactly the question #614 took a
32
+ * run and a post-mortem to answer. `recordEvidenceRewrite` is the single site
33
+ * that changes a command, and it keeps the FIRST authored form.
34
+ *
35
+ * It belongs here because it is the same claim from the other side: the first
36
+ * half says nothing may change the command by accident, the second says
37
+ * everything that changes it on purpose must say so.
38
+ *
39
+ * `workflows/ship.js` cannot import (#69). It carries an inlined copy inside
40
+ * the `AC-PAYLOAD-TRANSPORT` markers, and `test/evidence-command-roundtrip.test.ts`
41
+ * runs both over one matrix so drift is red.
42
+ */
43
+ import { shellSingleQuote } from "./phase2-decomposition";
44
+
45
+ /**
46
+ * Where the payload arrives inside the `bun -e` program.
47
+ *
48
+ * `bun -e '<program>' a b` gives the program `process.argv[1] === "a"`.
49
+ */
50
+ export const AC_PAYLOAD_ARGV_INDEX = 1;
51
+
52
+ /** One recorded change to an evidence command. */
53
+ export interface EvidenceRewrite {
54
+ /** The site that made the change, named so a reader can go and read it. */
55
+ by: string;
56
+ /** The command as it stood before this change. */
57
+ from: string;
58
+ /** The command as it stands after it. */
59
+ to: string;
60
+ }
61
+
62
+ /** The AC fields the setup step persists into workflow-state.json. */
63
+ export interface AcPayloadRecord {
64
+ id: unknown;
65
+ type: unknown;
66
+ statement: unknown;
67
+ threshold: unknown;
68
+ evidenceMethod: unknown;
69
+ specElement: unknown;
70
+ coversCriteria: unknown[];
71
+ contextFiles: unknown[];
72
+ }
73
+
74
+ /**
75
+ * Project discovery's ACs onto the fields `writeACs` persists.
76
+ *
77
+ * Kept as a function rather than inlined at the two call sites because the
78
+ * two used to be two copies of the same object literal, and a field added to
79
+ * one of them would have been silently missing from the fix-acs fallback.
80
+ */
81
+ export function acPayloadRecords(acs: unknown): AcPayloadRecord[] {
82
+ return (Array.isArray(acs) ? acs : []).map((ac: any) => ({
83
+ id: ac.id,
84
+ type: ac.type,
85
+ statement: ac.statement,
86
+ threshold: ac.threshold,
87
+ evidenceMethod: ac.evidenceMethod,
88
+ specElement: ac.specElement,
89
+ coversCriteria: ac.coversCriteria || [],
90
+ contextFiles: ac.contextFiles || [],
91
+ }));
92
+ }
93
+
94
+ /** The payload exactly as it will be written to disk. */
95
+ export function acPayloadJson(acs: unknown): string {
96
+ return JSON.stringify(acPayloadRecords(acs));
97
+ }
98
+
99
+ /**
100
+ * The payload as a shell WORD, to sit after the closing quote of the
101
+ * `bun -e "…"` program.
102
+ *
103
+ * Single quotes are the one shell construct with no expansion inside them at
104
+ * all, so this is the only position in the command where agent-authored text
105
+ * is safe. `shellSingleQuote` closes, escapes and reopens on an apostrophe,
106
+ * which is the single character the construct cannot carry verbatim — and
107
+ * evidence commands are full of apostrophes, because that is how an awk or
108
+ * grep expression is quoted.
109
+ *
110
+ * ## Why an argument and not a file
111
+ *
112
+ * The obvious alternative — write the payload to `${WORK_DIR}/…json` and have
113
+ * the `bun -e` read it — was built first and does not work, for a reason
114
+ * worth recording rather than rediscovering. `initWorkflow` calls `beginRun`,
115
+ * whose whole job (#288) is to sweep the work directory into
116
+ * `previous-run-<id>/` so a dead run's artefacts cannot be read as this
117
+ * run's. A payload written before `initWorkflow` is archived by it, and the
118
+ * read that follows is an ENOENT; a payload written after it needs a third
119
+ * command in the agent's prompt. The argument has neither problem: one
120
+ * process, no new file in a swept directory, and no ordering to get wrong.
121
+ */
122
+ export function acPayloadShellArgument(acs: unknown): string {
123
+ return shellSingleQuote(acPayloadJson(acs));
124
+ }
125
+
126
+ /**
127
+ * The JavaScript expression that reads the payload back, for embedding in the
128
+ * `bun -e` program that calls `writeACs`.
129
+ *
130
+ * It contains no agent-authored text and no `$`, so it is safe inside the
131
+ * double-quoted shell string the setup step still is.
132
+ */
133
+ export function acPayloadReadExpression(): string {
134
+ return `JSON.parse(process.argv[${AC_PAYLOAD_ARGV_INDEX}])`;
135
+ }
136
+
137
+ /**
138
+ * Change an evidence command, on the record.
139
+ *
140
+ * Returns true when the command actually changed. A no-op records nothing: a
141
+ * recorder that logged every call would leave `rewrites` non-empty on every
142
+ * AC and the field would stop meaning "this command was changed".
143
+ *
144
+ * `authoredCommand` is written once and never overwritten. A field holding
145
+ * "whatever it was one rewrite ago" cannot answer the question #614 asks,
146
+ * which is what the agent wrote.
147
+ */
148
+ export function recordEvidenceRewrite(
149
+ evidenceMethod: { command?: string; authoredCommand?: string; rewrites?: EvidenceRewrite[] } | undefined | null,
150
+ by: string,
151
+ next: string,
152
+ ): boolean {
153
+ if (!evidenceMethod || typeof evidenceMethod.command !== "string") return false;
154
+ const from = evidenceMethod.command;
155
+ if (from === next) return false;
156
+ if (evidenceMethod.authoredCommand === undefined) evidenceMethod.authoredCommand = from;
157
+ evidenceMethod.command = next;
158
+ evidenceMethod.rewrites = [...(evidenceMethod.rewrites || []), { by, from, to: next }];
159
+ return true;
160
+ }
@@ -57,6 +57,23 @@ export interface EvidencePrevalidationReading {
57
57
  checkedAt: string;
58
58
  /** Per-AC results. Empty — and only empty — when the verdict is UNMEASURED. */
59
59
  acs: PrevalidationResult[];
60
+ /**
61
+ * The ids of the ACs classified `broken`, in the order they were measured.
62
+ *
63
+ * Derived from `acs`, never supplied — `EvidencePrevalidationSchema` refuses
64
+ * a reading whose `broken` disagrees with its own results, so this cannot
65
+ * drift into an independent claim.
66
+ *
67
+ * It exists because the gate's single refusal site,
68
+ * `prevalidationViolations` in gates/workflow.test.ts, names the ACs to fix
69
+ * out of exactly this key — and until #274 no writer produced it. Every
70
+ * genuine FAIL therefore refused with "no broken AC ids were recorded", which
71
+ * is true of the key and false of the reading: the per-AC results were right
72
+ * there under `acs`. Fail-closed, so nothing shipped that should not have,
73
+ * but a refusal the heal loop cannot act on costs a round and teaches
74
+ * nothing, which is part of how #261 cost two.
75
+ */
76
+ broken: string[];
60
77
  /** Why the reading is UNMEASURED. Null — and only null — when it is not. */
61
78
  reason: string | null;
62
79
  }
@@ -348,6 +365,7 @@ export async function measureEvidencePrevalidation(
348
365
  verdict: "UNMEASURED",
349
366
  checkedAt,
350
367
  acs: [],
368
+ broken: [],
351
369
  reason,
352
370
  });
353
371
 
@@ -385,6 +403,10 @@ export async function measureEvidencePrevalidation(
385
403
  verdict: broken.length > 0 ? "FAIL" : "PASS",
386
404
  checkedAt,
387
405
  acs: results,
406
+ // Mapped from the same filter the verdict is derived from, at the single
407
+ // site that derives it, so the verdict and the names it refuses under
408
+ // cannot disagree.
409
+ broken: broken.map((r) => r.id),
388
410
  reason: null,
389
411
  };
390
412
  }
@@ -0,0 +1,129 @@
1
+ /**
2
+ * Whether `fallow` can be run without reaching the network (#581).
3
+ *
4
+ * `fallow` is an optional external tool and is NOT a declared dependency —
5
+ * not in `package.json`, not in `node_modules/.bin`, not on `PATH`, on this
6
+ * machine or on CI. So every bare `npx fallow` is a registry fetch.
7
+ *
8
+ * `lib/conformity.ts` learned that in its own words:
9
+ *
10
+ * > When it is absent, `npx fallow` does a registry fetch on every
11
+ * > invocation — four tests x one fetch each, each outliving bun's
12
+ * > per-test timeout. … Resolve it locally instead, with no network path.
13
+ *
14
+ * and then kept the fix to itself. `scripts/generate-code-map.ts` — the
15
+ * caller on the **scaffold** path, which runs once per consumer forever
16
+ * rather than four times in a suite — still spawned `npx fallow`
17
+ * unconditionally. So the fix landed in the cheap caller and not in the
18
+ * expensive one, and the cost of that is not a slow test: a consumer
19
+ * scaffolding behind a proxy, in an air-gapped CI, or on a bad connection
20
+ * gets a 30-second stall and then a silently degraded CODE-MAP, with nothing
21
+ * in the output saying a network call was attempted.
22
+ *
23
+ * It also made the suite non-deterministic. PR #580 — three state files, no
24
+ * code — went red on `SC-1665`, which asserts that `.fallow/cache.bin` was
25
+ * produced by both of two scaffold runs; when the fetch fails it is produced
26
+ * by neither. Reproduced with no repo change at all:
27
+ *
28
+ * npm_config_registry=http://127.0.0.1:1/ bun test test/scaffold-relative-root.test.ts
29
+ * error: .fallow/cache.bin is excluded but was not produced by both runs
30
+ *
31
+ * ## One binding
32
+ *
33
+ * This module exists rather than an export from `lib/conformity.ts` because
34
+ * conformity imports `bun:test` at module scope and so cannot be imported by
35
+ * a CLI. Same arrangement as `lib/git-dates.ts` (#508) and
36
+ * `lib/harness-identity.ts` (#380): one implementation, re-exported, because
37
+ * two answers to one question are behaviourally one and no test can tell
38
+ * them apart.
39
+ */
40
+
41
+ import { existsSync } from "fs";
42
+ import { join } from "path";
43
+
44
+ /**
45
+ * Memoised PER ROOT.
46
+ *
47
+ * `runFallowCheck` is exported and consumer projects call it with their own
48
+ * root, so a single process can ask about several. A root-independent cache
49
+ * would answer for the wrong directory.
50
+ */
51
+ const FALLOW_AVAILABLE = new Map<string, boolean>();
52
+
53
+ export function fallowAvailable(root: string): boolean {
54
+ const cached = FALLOW_AVAILABLE.get(root);
55
+ if (cached !== undefined) return cached;
56
+ const available = existsSync(join(root, "node_modules", ".bin", "fallow")) || Bun.which("fallow") !== null;
57
+ FALLOW_AVAILABLE.set(root, available);
58
+ return available;
59
+ }
60
+
61
+ /** Test seam: drop the memo so a case can change the answer. */
62
+ export function resetFallowAvailability(): void {
63
+ FALLOW_AVAILABLE.clear();
64
+ }
65
+
66
+ /**
67
+ * Why a fallow-derived reading is missing, or null when it is not missing.
68
+ *
69
+ * Three outcomes, not two. `null` from the old `runFallow()` meant "not
70
+ * installed", "the spawn failed", "the output did not parse" and "it ran and
71
+ * found nothing" all at once, and a CODE-MAP written from it was
72
+ * byte-identical in every case — which is
73
+ * `.claude/rules/config-access.md`'s *Silent Default Substitution* with a
74
+ * document as the victim.
75
+ */
76
+ export type FallowUnavailable =
77
+ | { kind: "not-installed"; reason: string }
78
+ | { kind: "run-failed"; reason: string };
79
+
80
+ export function fallowNotInstalled(): FallowUnavailable {
81
+ return {
82
+ kind: "not-installed",
83
+ reason:
84
+ "fallow is not installed (it is an optional tool, not a declared dependency) — " +
85
+ "no static analysis was run, and no registry fetch was attempted",
86
+ };
87
+ }
88
+
89
+ /**
90
+ * A tool's output, made safe to put in a document an agent reads.
91
+ *
92
+ * The `run-failed` reason quotes what fallow printed, and that string ends
93
+ * up inside CODE-MAP.md — which `.claude/rules/key-files.md` tells every
94
+ * agent to read to understand the codebase. So it is untrusted text on its
95
+ * way into a trusted document, and fallow's error text can quote the repo's
96
+ * own file names and contents.
97
+ *
98
+ * One line, an allowlist, and a cap. Not an escape routine: a denylist of
99
+ * markdown syntax is a detector narrower than what it detects, and the
100
+ * useful content of a tool error survives an allowlist intact.
101
+ */
102
+ export function safeToolDetail(raw: string): string {
103
+ const firstLine = raw.split("\n")[0] ?? "";
104
+ // A RUN of disallowed characters collapses to one `?`, rather than one
105
+ // `?` each. Both are safe; the difference is whether a detail that was
106
+ // entirely unprintable comes back as `????????` — which carries no
107
+ // information and is indistinguishable from a tool that said something.
108
+ const cleaned = firstLine.replace(/[^A-Za-z0-9 .,:;()/'"=+-]+/g, "?").slice(0, 120).trim();
109
+ return /^[?\s]*$/.test(cleaned) ? "(no printable detail)" : cleaned;
110
+ }
111
+
112
+ export function fallowRunFailed(detail: string): FallowUnavailable {
113
+ return {
114
+ kind: "run-failed",
115
+ reason: `fallow is installed but the run did not produce a reading: ${safeToolDetail(detail)}`,
116
+ };
117
+ }
118
+
119
+ /**
120
+ * The line a generated document carries in place of a section it could not
121
+ * produce.
122
+ *
123
+ * UNMEASURED by name. An omitted section and a section reporting nothing
124
+ * wrong are the same absence to a reader, and the reader of a CODE-MAP is an
125
+ * agent deciding whether this project has dead code.
126
+ */
127
+ export function fallowUnmeasuredNotice(u: FallowUnavailable): string {
128
+ return `## Code Health (fallow)\n\n**UNMEASURED** — ${u.reason}.`;
129
+ }
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Which recorded refusals are still true at the end of the run (#532).
3
+ *
4
+ * The ship gate RE-RUNS the verify checks. `runGateTests` spawns
5
+ * `bun test gates/ --test-name-pattern "schema|scope|verify|ship|B1|B2"` for
6
+ * the ship gate, so every `verify checks > …` name is measured a second
7
+ * time, later, against a tree the heal rounds have since changed.
8
+ *
9
+ * Measured on run `wf_e230fddc-a71`:
10
+ *
11
+ * | Check | `gates.verify.failures` | `gates.ship.failures` |
12
+ * |---|---|---|
13
+ * | `verify checks > tests-pass` | FAIL | FAIL |
14
+ * | `verify checks > evidence-prevalidation` | **FAIL** | **absent** |
15
+ * | `verify checks > tsc-pass` | FAIL | FAIL |
16
+ *
17
+ * `state.evidencePrevalidation` in that same file reads
18
+ * `{"verdict":"PASS", acs: [… all "ok" …]}`. The refusal was round one, a
19
+ * heal fixed it, the ship gate re-ran it and it passed — and the terminal
20
+ * report listed it anyway, because the report is the UNION of every gate's
21
+ * list rather than the latest reading of each check.
22
+ *
23
+ * The run returned 19 refusals. Several were already resolved, so the real
24
+ * count was smaller, and the one that actually blocked the run — a
25
+ * `SECURITY_REVIEW_STALE` — was buried among them. A report with false
26
+ * entries in it is a report nobody reads twice.
27
+ *
28
+ * ## Absence is not a pass
29
+ *
30
+ * The whole thing turns on one distinction, and getting it wrong is worse
31
+ * than the bug it fixes: a check missing from a later gate's FAILURES means
32
+ * either *it passed there* or *that gate never ran it*. Those are opposite
33
+ * facts and a failure list cannot tell them apart. Retiring on absence
34
+ * would silently drop every refusal a later gate's narrower pattern skipped.
35
+ *
36
+ * So retirement requires a positive witness — `checksRun`, the names the
37
+ * later gate reported a verdict for, recorded by `gates/orchestrator.ts`
38
+ * from the same `results` array the failures come from. A gate with no
39
+ * `checksRun` retires NOTHING. `null` and `[]` are different answers here
40
+ * and only one of them is a measurement
41
+ * (.claude/rules/config-access.md, Silent Default Substitution).
42
+ *
43
+ * ## Why this is duplicated into ship.js
44
+ *
45
+ * `workflows/ship.js` runs in a sandbox with no module loading (#69), so it
46
+ * cannot import this. It carries an inlined copy inside
47
+ * `REFUSAL-CURRENCY` markers, and `test/gate-refusal-currency.test.ts`
48
+ * extracts that copy, executes it, and runs both over one input matrix —
49
+ * the same technique `test/suite-measurement-parity.test.ts` uses for
50
+ * `suiteCurrency`, and for the same reason: two copies of a rule is a
51
+ * defect waiting for one of them to drift, and the drift is silent.
52
+ */
53
+
54
+ /** What a gate run reported back: the names it measured and the ones it failed. */
55
+ export interface GateReport {
56
+ checksRun?: unknown;
57
+ failedChecks?: unknown;
58
+ }
59
+
60
+ /** One recorded refusal. `check` is absent for refusals no gate produced. */
61
+ export interface RefusalEntry {
62
+ check?: unknown;
63
+ [k: string]: unknown;
64
+ }
65
+
66
+ /**
67
+ * The checks a gate ran and did NOT fail — the only thing that can retire an
68
+ * earlier refusal.
69
+ *
70
+ * `null` when the gate reported no `checksRun`, and that is the
71
+ * load-bearing return rather than an empty array: a caller has to be able
72
+ * to tell "this gate said nothing about what it ran" from "this gate ran
73
+ * nothing".
74
+ */
75
+ export function resolvedCheckNames(report: GateReport | null | undefined): string[] | null {
76
+ if (!report || !Array.isArray(report.checksRun)) return null;
77
+ const failed = new Set(
78
+ (Array.isArray(report.failedChecks) ? report.failedChecks : []).filter(
79
+ (c: unknown): c is string => typeof c === "string" && c !== "",
80
+ ),
81
+ );
82
+ return report.checksRun.filter(
83
+ (c: unknown): c is string => typeof c === "string" && c !== "" && !failed.has(c),
84
+ );
85
+ }
86
+
87
+ /**
88
+ * Remove, IN PLACE, every earlier refusal about a check this gate re-ran and
89
+ * did not reproduce. Returns the entries it removed.
90
+ *
91
+ * In place because the ledger is one array the whole run appends to, and
92
+ * returning a copy would leave the original to be reported by whichever
93
+ * reader got there first. The removed entries are returned rather than
94
+ * discarded: a refusal that was retired is a thing an operator may want to
95
+ * see, and silently shortening a list is how a report stops being checkable.
96
+ */
97
+ export function retireSupersededRefusals(
98
+ entries: RefusalEntry[],
99
+ report: GateReport | null | undefined,
100
+ ): RefusalEntry[] {
101
+ const resolved = resolvedCheckNames(report);
102
+ if (resolved === null || resolved.length === 0) return [];
103
+ const names = new Set(resolved);
104
+ const dropped: RefusalEntry[] = [];
105
+ for (let i = entries.length - 1; i >= 0; i--) {
106
+ const check = entries[i]?.check;
107
+ if (typeof check === "string" && check !== "" && names.has(check)) {
108
+ dropped.unshift(entries.splice(i, 1)[0]);
109
+ }
110
+ }
111
+ return dropped;
112
+ }
@@ -0,0 +1,82 @@
1
+ /**
2
+ * The gate run's three nested time budgets, and the order they must be in (#550).
3
+ *
4
+ * A gate check is three processes deep, and each layer can kill the one
5
+ * inside it. Before this file the three numbers were written in three places
6
+ * by three issues and **two of the three orderings were backwards**:
7
+ *
8
+ * | Layer | Was | Where |
9
+ * |---|---|---|
10
+ * | the compiler `tsc-pass` spawns | 240000 | `gates/workflow.test.ts` |
11
+ * | the `test()` around that spawn | 5000 (bun's default) | nowhere — undeclared |
12
+ * | the whole `bun test gates/` run | 120000 | `gates/gate-executor.ts` |
13
+ *
14
+ * So the compiler was allowed four minutes by a call killed after five
15
+ * seconds, inside a run killed after two. `tsc-pass` **could not pass on any
16
+ * project whose typecheck takes longer than five seconds**, which is every
17
+ * project large enough to have a gate run. Observed live: the check printed
18
+ * `Type check PASS: bunx tsc --noEmit` to its own stdout and recorded FAIL,
19
+ * and the timeout line that said why was attributed to the NEXT check by the
20
+ * parser (the other half of #550).
21
+ *
22
+ * Nothing could say so, because a timeout and a genuine failure are the same
23
+ * red, and the 240000 beside the spawn reads as deliberate.
24
+ *
25
+ * **The rule is one line: each layer must strictly outlive the one inside
26
+ * it.** Equal is not enough — a spawn killed at the same instant as its test
27
+ * is a race, and which of the two messages you get is not decided by this
28
+ * repo.
29
+ *
30
+ * Declared here, once, so the ordering is a property of four exported
31
+ * constants rather than of four numbers nobody reads together. The numbers
32
+ * themselves are judgement, and the judgement is written down:
33
+ *
34
+ * - `EXEC_TIMEOUT_MS` — the `git`/shell helpers. Unchanged at 30s; these are
35
+ * local repository reads and one that takes longer is hung, not slow.
36
+ * - `TYPECHECK_TIMEOUT_MS` — 90s, LOWERED from 240s. 240 was never reachable,
37
+ * and a single check is not entitled to twice the whole gate's budget.
38
+ * - `GATE_TEST_TIMEOUT_MS` — 120s, the per-test default. Declared at file
39
+ * level with `setDefaultTimeout` and not as a per-test argument, because
40
+ * `}, 120000);` on `tsc-pass` alone covers exactly one check and the next
41
+ * spawning check added inherits nothing. A rule naming one test is a rule
42
+ * the next one evades.
43
+ * - `GATE_SUITE_TIMEOUT_MS` — 180s, RAISED from 120s, so the outer kill is
44
+ * above the per-test budget rather than below it.
45
+ */
46
+
47
+ /** `exec`, `execArgv`, `execArgvOf` — local git and shell reads. */
48
+ export const EXEC_TIMEOUT_MS = 30_000;
49
+
50
+ /** `bunx tsc --noEmit`, the slowest single subprocess a check starts. */
51
+ export const TYPECHECK_TIMEOUT_MS = 90_000;
52
+
53
+ /** The per-test default for `gates/workflow.test.ts`. */
54
+ export const GATE_TEST_TIMEOUT_MS = 120_000;
55
+
56
+ /** The whole `bun test gates/` run, spawned by `runGateTests`. */
57
+ export const GATE_SUITE_TIMEOUT_MS = 180_000;
58
+
59
+ /**
60
+ * The ordering, as a function so it can be driven over values that are not
61
+ * these ones — otherwise the check compares the constants against themselves
62
+ * and no mutation of them can be observed.
63
+ */
64
+ export function gateTimeoutOrderingViolations(t: {
65
+ exec: number;
66
+ typecheck: number;
67
+ test: number;
68
+ suite: number;
69
+ }): string[] {
70
+ const layers: Array<[string, number, string, number]> = [
71
+ ["the exec helpers", t.exec, "the typecheck spawn", t.typecheck],
72
+ ["the typecheck spawn", t.typecheck, "the test around it", t.test],
73
+ ["the test", t.test, "the gate suite run", t.suite],
74
+ ];
75
+ return layers
76
+ .filter(([, inner, , outer]) => !(inner < outer))
77
+ .map(
78
+ ([innerName, inner, outerName, outer]) =>
79
+ `${innerName} is allowed ${inner}ms inside ${outerName}'s ${outer}ms — the inner process ` +
80
+ `outlives the thing that started it, so it is killed before it can report (#550)`,
81
+ );
82
+ }
@@ -65,7 +65,10 @@ export function generateAgentBriefs(scan: ProjectScan): Record<string, string> {
65
65
  const harness = scan.harnessConfig;
66
66
  const devUi = harness?.dev?.uiBase || null;
67
67
  const devApi = harness?.dev?.apiBase || null;
68
- const testCmd = harness?.dev?.testCmd || scan.testCmd || "bun test";
68
+ // #488 — `scan.testCmd` already IS the decision: `testCommandDecision`
69
+ // puts `dev.testCmd` on its first rung, so re-asking here was a second
70
+ // ladder that could disagree with the first and never be noticed.
71
+ const testCmd = scan.testCmd || "bun test";
69
72
  const typeCheck = harness?.dev?.typeCheck || "bunx tsc --noEmit";
70
73
  const pages = harness?.pages || {};
71
74
  const pagesTable = Object.keys(pages).length > 0