rungate 0.5.0 → 0.7.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 (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -0,0 +1,287 @@
1
+ /**
2
+ * Which directory `CommitEnforcement` is allowed to run `git` in (#1001).
3
+ *
4
+ * ## The defect this exists to close
5
+ *
6
+ * The hook found its subject by matching `payload.tool_response` against a
7
+ * case-insensitive pattern for "a slash, any non-space run, `worktrees/`,
8
+ * `agent-<hex>`, any non-space run". (Written out rather than quoted: the
9
+ * pattern ends in a sequence that closes a block comment, which is its own
10
+ * small lesson.)
11
+ *
12
+ * That text is the subagent's own reply — agent-authored, and reachable by
13
+ * anything able to influence what an agent writes. **A regex match is not a
14
+ * confinement.** The hook then ran `git -C <that>` twice, and `git` executes
15
+ * the config of whatever repository it is pointed at.
16
+ *
17
+ * ## Why the first fix was wrong, measured
18
+ *
19
+ * PR #1024 confined the candidate to `$HOME/.claude/.claude/worktrees` — the
20
+ * spelling the hook's own fallback branch already had inline. The doubled
21
+ * `.claude` is not a typo; that directory exists. It is also **dead**:
22
+ *
23
+ * ```
24
+ * registered worktrees under $HOME/.claude/.claude/worktrees → 0
25
+ * registered worktrees under <main>/.claude/worktrees → 136
26
+ * directory entries under $HOME/.claude/.claude/worktrees → 16 (all stale)
27
+ * ```
28
+ *
29
+ * Every live agent worktree on this machine is repo-local. Confining to the
30
+ * other base does not merely fail to protect — combined with a fallback that
31
+ * ran whenever confinement returned null, it **actively misattributed**: the
32
+ * reply names a real repo-local worktree, confinement refuses it for being in
33
+ * the wrong place, and the fallback then emits a tripwire signal naming the
34
+ * most recently touched of sixteen stale directories. With several agents
35
+ * running at once that is not a corner case. A check confined to a location
36
+ * nothing uses is a check that cannot fail.
37
+ *
38
+ * ## The anchor: ask git, from a root the subject cannot choose
39
+ *
40
+ * A path list is the wrong shape for this question twice over — it has to be
41
+ * kept in agreement with where worktrees actually get created, and it answers
42
+ * "does this path look right" when the question is "is this a worktree of my
43
+ * own repository". So the subject must appear in `git worktree list` for the
44
+ * harness's own repo, resolved from `import.meta.dir` — this file's location,
45
+ * which no agent reply can influence.
46
+ *
47
+ * **This repository already knew that.** `gitWorktreeBase` below is moved,
48
+ * not written: #120 established "asking git removes the guess" for the
49
+ * collection path, and `scripts/collect-worktree-files.ts` has derived the
50
+ * base from `--git-common-dir` ever since. The hook guessed anyway, because
51
+ * the knowledge lived in a script a hook could not import. That is the same
52
+ * failure as #1001's own git-isolation half — *a lesson learned once and
53
+ * propagated nowhere* — so the function moves here and the script re-exports
54
+ * it rather than a second derivation being written.
55
+ *
56
+ * ## WHAT THIS DOES NOT COVER
57
+ *
58
+ * - **A hostile repository that IS a registered worktree.** Registration says
59
+ * this tree belongs to my repo, not that its contents are safe.
60
+ * `lib/git-isolation.ts` is what makes running `git` there survivable.
61
+ * - **A race between the check and the `git` call.** The path is resolved and
62
+ * matched once; a symlink swapped in afterwards is not detected. Closing
63
+ * that needs a file descriptor held across both, which `git -C` cannot take.
64
+ * - **Worktrees of OTHER repositories.** Deliberately: the hook's subject is
65
+ * an agent of this harness.
66
+ *
67
+ * Issue: #1001. Refs #120, #971, #999, #960, PR #1024.
68
+ */
69
+
70
+ import { execFileSync } from "child_process";
71
+ import { realpathSync, statSync } from "fs";
72
+ import { basename, join } from "path";
73
+ import { repoRootFrom } from "./paths";
74
+ import { recordHookFiring } from "./hook-evidence";
75
+ import { gitIsolatedArgs, gitIsolatedEnv } from "./git-isolation";
76
+
77
+ /** Agent worktree directory names, as `git worktree add` is asked for them. */
78
+ const AGENT_WORKTREE_NAME = /^agent-[a-f0-9]+$/i;
79
+
80
+ /**
81
+ * Where git itself puts this repo's agent worktrees (#120).
82
+ *
83
+ * `git worktree add` run from inside a linked worktree resolves against the
84
+ * COMMON dir, so agent worktrees land under the main checkout regardless of
85
+ * which worktree the caller is in. No caller-supplied root controls that,
86
+ * which is why a root-derived base only *happens* to work: it covers the
87
+ * usual case where the caller is the main checkout, and fails silently
88
+ * whenever it is not.
89
+ *
90
+ * Returns null rather than throwing. For `collect-worktree-files` this is an
91
+ * additional base and losing it degrades to caller-supplied behaviour; the
92
+ * failure is logged there, because a silent catch would turn "git is broken"
93
+ * into "there is no such directory", which is the fail-open shape this
94
+ * project keeps getting bitten by.
95
+ */
96
+ export function gitWorktreeBase(projectRoot: string): string | null {
97
+ let commonDir: string;
98
+ try {
99
+ commonDir = execFileSync(
100
+ "git",
101
+ ["-C", projectRoot, "rev-parse", "--path-format=absolute", "--git-common-dir"],
102
+ { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
103
+ ).trim();
104
+ } catch (e) {
105
+ const msg = (e as Error).message || "";
106
+ if (!/not a git repository/i.test(msg)) {
107
+ console.error(`collect: WARNING could not ask git where worktrees live: ${msg.split("\n")[0]}`);
108
+ }
109
+ return null;
110
+ }
111
+ if (!commonDir) return null;
112
+
113
+ // <main>/.git -> <main>. Anchored to a trailing path segment so a repo at
114
+ // /srv/.github or a directory merely containing ".git" in its name is not
115
+ // silently truncated. A bare repo (no trailing /.git) yields no match and
116
+ // returns null — it has no working tree, so no agent worktrees either.
117
+ const mainRepo = commonDir.replace(/\/\.git\/?$/, "");
118
+ if (mainRepo === commonDir || mainRepo === "") return null;
119
+
120
+ // Resolve before handing it out. Comparisons downstream are against
121
+ // realpath'd worktree paths, and on macOS /tmp is a symlink to /private/tmp
122
+ // — an unresolved base silently matches nothing.
123
+ let resolved: string;
124
+ try {
125
+ resolved = realpathSync(mainRepo);
126
+ } catch {
127
+ return null;
128
+ }
129
+ return join(resolved, ".claude", "worktrees");
130
+ }
131
+
132
+ /**
133
+ * The LINKED worktrees of `repoRoot`, realpath'd, or null if git could not be
134
+ * asked.
135
+ *
136
+ * Null and `[]` are different answers and callers must treat them so: an
137
+ * empty list means this repository genuinely has no linked worktrees, and a
138
+ * null means the question was not answered. Collapsing them is how a refusal
139
+ * turns into "nothing matched, carry on".
140
+ *
141
+ * The PRIMARY checkout is excluded. It is a worktree by git's reckoning, but
142
+ * attributing a subagent's uncommitted work to the main tree — which on this
143
+ * machine has carried staged work for weeks — would produce a signal about
144
+ * the user's own edits on nearly every agent that runs. The test is whether
145
+ * `.git` is a file rather than a directory, which is what actually
146
+ * distinguishes a linked worktree, rather than a reliance on list ordering.
147
+ */
148
+ export function registeredWorktrees(repoRoot: string): string[] | null {
149
+ let out: string;
150
+ try {
151
+ out = execFileSync("git", gitIsolatedArgs(["-C", repoRoot, "worktree", "list", "--porcelain"]), {
152
+ encoding: "utf-8",
153
+ timeout: 10000,
154
+ stdio: ["ignore", "pipe", "ignore"],
155
+ env: gitIsolatedEnv(),
156
+ });
157
+ } catch {
158
+ return null;
159
+ }
160
+
161
+ const paths: string[] = [];
162
+ for (const line of out.split("\n")) {
163
+ if (!line.startsWith("worktree ")) continue;
164
+ const raw = line.slice("worktree ".length).trim();
165
+ if (!raw) continue;
166
+ let resolved: string;
167
+ try {
168
+ resolved = realpathSync(raw);
169
+ } catch {
170
+ continue; // registered but gone from disk
171
+ }
172
+ try {
173
+ if (!statSync(join(resolved, ".git")).isFile()) continue; // the primary checkout
174
+ } catch {
175
+ continue;
176
+ }
177
+ paths.push(resolved);
178
+ }
179
+ return paths;
180
+ }
181
+
182
+ /** The harness's own repository, located from this file rather than from input. */
183
+ export function harnessRepoRoot(): string | null {
184
+ return repoRootFrom(import.meta.dir);
185
+ }
186
+
187
+ /**
188
+ * `candidate` accepted only if it resolves to a registered linked worktree of
189
+ * the harness's own repository; `null` otherwise.
190
+ *
191
+ * `realpathSync` on both sides. Resolving the candidate is what defeats `..`
192
+ * and a symlink: `/base/agent-x/../../etc` resolves to `/etc` and then
193
+ * matches nothing. Equality rather than a prefix test, because the subject of
194
+ * the signal is the worktree, and because a prefix test is the thing that put
195
+ * `…/worktrees-evil` inside `…/worktrees`.
196
+ */
197
+ export function registeredWorktreePath(
198
+ candidate: string,
199
+ worktrees: readonly string[] | null,
200
+ ): string | null {
201
+ if (worktrees === null || worktrees.length === 0) return null;
202
+ let resolved: string;
203
+ try {
204
+ resolved = realpathSync(candidate);
205
+ } catch {
206
+ return null;
207
+ }
208
+ return worktrees.includes(resolved) ? resolved : null;
209
+ }
210
+
211
+ /**
212
+ * The subject of a worktree tripwire, resolved from an agent-authored reply.
213
+ *
214
+ * The whole decision in one place, because the ORDER is the security
215
+ * property and splitting it across a hook is how the order gets lost:
216
+ *
217
+ * 1. a candidate named in the reply is accepted only if registered;
218
+ * 2. **a named candidate that is refused ends here** — recorded, not
219
+ * replaced. PR #1024 fell through to step 3 instead, which is how a
220
+ * confinement became a signal naming a different agent's worktree;
221
+ * 3. only a reply naming nothing at all reaches the scan.
222
+ *
223
+ * The pattern is a case-insensitive match for "a slash, any non-space run,
224
+ * `worktrees/`, `agent-<hex>`, any non-space run" — spelled out rather than
225
+ * quoted here because it ends in a sequence that closes a block comment.
226
+ */
227
+ export function agentWorktreeSubject(
228
+ respText: string,
229
+ hook: string,
230
+ detail: Record<string, unknown> = {},
231
+ worktrees: readonly string[] | null = harnessWorktrees(),
232
+ ): string | null {
233
+ const pathMatch = respText.match(/(?:\/[^\s]*worktrees\/agent-[a-f0-9]+[^\s]*)/i);
234
+ if (!pathMatch) return mostRecentAgentWorktree(worktrees);
235
+
236
+ const subject = registeredWorktreePath(pathMatch[0], worktrees);
237
+ if (subject === null) {
238
+ recordHookFiring(hook, "declined-unregistered-worktree", {
239
+ ...detail,
240
+ candidate: pathMatch[0],
241
+ registered: worktrees === null ? null : worktrees.length,
242
+ });
243
+ }
244
+ return subject;
245
+ }
246
+
247
+ /**
248
+ * The harness's own registered worktrees, or null if git could not be asked.
249
+ *
250
+ * The default argument of `agentWorktreeSubject`, separate so a case can
251
+ * supply a fixture repository's list instead of this machine's. The DEFAULT
252
+ * is the non-forgeable one, which is the property that matters; a parameter
253
+ * that a caller must go out of its way to override is not an input an agent
254
+ * reply can reach.
255
+ */
256
+ export function harnessWorktrees(): string[] | null {
257
+ const root = harnessRepoRoot();
258
+ return root === null ? null : registeredWorktrees(root);
259
+ }
260
+
261
+ /**
262
+ * The most recently modified registered worktree whose directory name is
263
+ * `agent-<hex>`, or null.
264
+ *
265
+ * Only reached when the reply named NO candidate at all. A candidate that was
266
+ * named and refused is a terminal refusal in `agentWorktreeSubject`: falling
267
+ * back here is how a confinement becomes a misattribution.
268
+ */
269
+ export function mostRecentAgentWorktree(worktrees: readonly string[] | null): string | null {
270
+ if (worktrees === null) return null;
271
+ let best: string | null = null;
272
+ let bestMtime = -Infinity;
273
+ for (const wt of worktrees) {
274
+ if (!AGENT_WORKTREE_NAME.test(basename(wt))) continue;
275
+ let mtime: number;
276
+ try {
277
+ mtime = statSync(wt).mtimeMs;
278
+ } catch {
279
+ continue;
280
+ }
281
+ if (mtime > bestMtime) {
282
+ bestMtime = mtime;
283
+ best = wt;
284
+ }
285
+ }
286
+ return best;
287
+ }
@@ -0,0 +1,209 @@
1
+ /**
2
+ * The one section of AGENTS.md the harness does not own (#568).
3
+ *
4
+ * `specs/bootstrap-data-flow/problem-statement.md` makes exactly one promise
5
+ * about user content surviving a scaffold run:
6
+ *
7
+ * > Everything is regenerable. All harness-managed files can be rebuilt
8
+ * > from scratch by re-running scaffold. **The only user-owned content
9
+ * > that survives regeneration is Hard Constraints in AGENTS.md**
10
+ * > (preserved between markers).
11
+ *
12
+ * Nothing implemented it. `lib/scaffold/write-steps.ts` built the file from
13
+ * a template and called `writeFileSync`, so the section and both extraction
14
+ * markers went with it. Measured on a consumer: 37 constraint lines removed
15
+ * by one run, reported as `REGENERATED: AGENTS.md`, exit 0.
16
+ *
17
+ * The cost is not the file. Those lines are the project's non-inferable
18
+ * rules — which port is destructive, which endpoint is permanently off,
19
+ * what the deploy sequence is — and an agent cannot recover them by reading
20
+ * the code, which is the entire reason the section exists. Four weeks after
21
+ * that run, an agent on that project removed a flag another issue had
22
+ * deliberately set, because nothing in the repo said why.
23
+ *
24
+ * ## Why a heading and not a marker pair
25
+ *
26
+ * The spec says "preserved between markers", and the extractor
27
+ * (`scripts/extract-constraints.ts`) does write between
28
+ * `<!-- BEGIN AUTO-EXTRACTED -->` and `<!-- END AUTO-EXTRACTED -->`. But on
29
+ * the consumer that lost them, most of the section was OUTSIDE the markers:
30
+ * eight extracted lines between them and twenty-nine hand-written ones
31
+ * after. Preserving only the marked block would have rescued the lines a
32
+ * machine can regenerate and dropped the ones only a human holds — the
33
+ * section's most valuable content, defined by the mechanism that was easiest
34
+ * to anchor on.
35
+ *
36
+ * So the unit is the **section**: the heading, and everything up to the next
37
+ * one. The markers are ordinary lines inside it and are preserved by being
38
+ * inside it, which is also what makes a project that has never run the
39
+ * extractor work the same way.
40
+ *
41
+ * ## The post-condition is the check, not the merge
42
+ *
43
+ * `preserveSections` could be wrong in a dozen ways — an anchor that is not
44
+ * there, a heading at EOF, a generated template that one day grows its own
45
+ * Hard Constraints section. Rather than reason about each, it compares
46
+ * the lines it found against the lines it produced and reports what is
47
+ * missing. A merge that silently drops something is the defect; a merge that
48
+ * names what it dropped is a refusal the caller can act on.
49
+ */
50
+
51
+ /**
52
+ * ## One merge, two files (#655)
53
+ *
54
+ * `.claude/agents/*.md` has the same problem AGENTS.md had, for the same
55
+ * reason: a rule mined from a project's own compliance history is
56
+ * non-inferable by construction — it is derived from what THIS repo's agents
57
+ * got wrong — and until #655 the only surfaces that could hold one were
58
+ * regenerated from harness-wide inputs. `templates/agent-briefs/_shared.md`
59
+ * resolves under `scan.harnessTemplatesDir`, so a project rule written there
60
+ * reaches every consumer.
61
+ *
62
+ * What differs between the two files is a heading and a list of anchors.
63
+ * What must NOT differ is the merge, the loss check, or the refusal — so
64
+ * those stay in one function and the vocabulary travels as data. Two copies
65
+ * of `preserveSections` with different constants would be two deciders
66
+ * answering one question, and a mutation of either would leave the other
67
+ * holding every case up (`.claude/rules/checks-must-be-able-to-fail.md`).
68
+ */
69
+ export interface SectionSpec {
70
+ /** How the file names the preserved section, for a refusal a human reads. */
71
+ label: string;
72
+ /** The heading that opens it. Case-sensitive, at the start of a line. */
73
+ heading: RegExp;
74
+ /**
75
+ * Where the section is re-inserted, in order of preference. An anchor that
76
+ * is not in the generated output is not an error — appending is.
77
+ */
78
+ anchors: RegExp[];
79
+ }
80
+
81
+ /** AGENTS.md's user-owned section (#568). */
82
+ export const HARD_CONSTRAINTS_SECTION: SectionSpec = {
83
+ label: "## Hard Constraints",
84
+ heading: /^##[ \t]+Hard Constraints\b[^\n]*$/m,
85
+ // `## Rules` first, because constraints are rules and a reader scanning for
86
+ // one should not have to pass the Commands table to find the other. The
87
+ // fallbacks exist because a profile can omit sections.
88
+ anchors: [/^##[ \t]+Rules$/m, /^##[ \t]+Commands$/m, /^##[ \t]+Workflow$/m],
89
+ };
90
+
91
+ /**
92
+ * An agent brief's project-owned section (#655).
93
+ *
94
+ * A different heading from AGENTS.md's on purpose. The two sections hold
95
+ * different things — AGENTS.md's constraints are read by every agent, a
96
+ * brief's are scoped to one role — and one spelling for both would make a
97
+ * rule written in the wrong file look like it was in the right one.
98
+ *
99
+ * The anchors are the three headings every generated brief in this
100
+ * repository carries at least one of; `## Reference (read when needed)` is
101
+ * last in each template, so the section lands above it rather than after a
102
+ * table of file paths.
103
+ */
104
+ export const BRIEF_CONSTRAINTS_SECTION: SectionSpec = {
105
+ label: "## Project Constraints",
106
+ heading: /^##[ \t]+Project Constraints\b[^\n]*$/m,
107
+ anchors: [
108
+ /^##[ \t]+Reference \(read when needed\)$/m,
109
+ /^##[ \t]+Workflow$/m,
110
+ /^##[ \t]+Reference$/m,
111
+ ],
112
+ };
113
+
114
+ /** Any other `##` heading — where the preserved section ends. */
115
+ const NEXT_H2 = /^##[ \t]+/m;
116
+
117
+ export interface SectionReading {
118
+ /** The section verbatim — heading line through the last line before the next `##`. */
119
+ text: string;
120
+ /** Its non-blank lines, heading included. The unit the loss check counts. */
121
+ lines: string[];
122
+ }
123
+
124
+ export interface PreserveResult {
125
+ /** The bytes to write. Equal to `generated` when there was nothing to preserve. */
126
+ content: string;
127
+ /** The section carried over, or null when the existing file had none. */
128
+ preserved: SectionReading | null;
129
+ /**
130
+ * Lines that were in the existing section and are not in `content`.
131
+ *
132
+ * Always empty on the paths this module controls. It is non-empty only
133
+ * when the merge itself failed, which is the case a caller must refuse on
134
+ * rather than write.
135
+ */
136
+ lost: string[];
137
+ }
138
+
139
+ /**
140
+ * Read the Hard Constraints section out of an AGENTS.md, or null.
141
+ *
142
+ * Returns null for "no such heading" AND for a heading with nothing under
143
+ * it — the second is a section somebody emptied, and carrying an empty
144
+ * heading forward would make a run that preserved nothing look identical to
145
+ * a run that preserved something.
146
+ */
147
+ export function readPreservedSection(
148
+ content: string | null,
149
+ spec: SectionSpec = HARD_CONSTRAINTS_SECTION,
150
+ ): SectionReading | null {
151
+ if (content === null) return null;
152
+ const open = spec.heading.exec(content);
153
+ if (open === null) return null;
154
+
155
+ const start = open.index;
156
+ const rest = content.slice(start + open[0].length);
157
+ const next = NEXT_H2.exec(rest);
158
+ const text = (next === null ? content.slice(start) : content.slice(start, start + open[0].length + next.index)).replace(/\s+$/, "");
159
+
160
+ const lines = text.split("\n").map(l => l.trim()).filter(l => l !== "");
161
+ // The heading alone is not a section. One line means nothing survived the
162
+ // last edit, and there is no content to promise anybody.
163
+ if (lines.length < 2) return null;
164
+ return { text, lines };
165
+ }
166
+
167
+ /**
168
+ * AGENTS.md's reading, by name. The existing callers ask this question and
169
+ * only this one; the spec'd form above is what a second file uses.
170
+ */
171
+ export function readHardConstraints(content: string | null): SectionReading | null {
172
+ return readPreservedSection(content, HARD_CONSTRAINTS_SECTION);
173
+ }
174
+
175
+ /**
176
+ * Graft the existing file's Hard Constraints section into freshly generated
177
+ * content, and report anything the graft dropped.
178
+ *
179
+ * Idempotent by construction: the section is re-inserted at the same anchor
180
+ * every run, so the second run over its own output is byte-identical, which
181
+ * is what SC-364 asks of every generator here.
182
+ */
183
+ export function preserveSections(
184
+ existing: string | null,
185
+ generated: string,
186
+ spec: SectionSpec = HARD_CONSTRAINTS_SECTION,
187
+ ): PreserveResult {
188
+ const preserved = readPreservedSection(existing, spec);
189
+ if (preserved === null) return { content: generated, preserved: null, lost: [] };
190
+
191
+ // A generated template that already carries the section is not a case
192
+ // today, and writing it off as impossible is how the next person finds a
193
+ // duplicate heading in a consumer's AGENTS.md. Its own section wins, and
194
+ // the post-condition below reports whatever that costs.
195
+ let content: string;
196
+ const own = readPreservedSection(generated, spec);
197
+ if (own !== null) {
198
+ content = generated;
199
+ } else {
200
+ const anchor = spec.anchors.map(a => a.exec(generated)).find(m => m !== null) ?? null;
201
+ content =
202
+ anchor === null
203
+ ? `${generated.replace(/\s+$/, "")}\n\n${preserved.text}\n`
204
+ : `${generated.slice(0, anchor.index)}${preserved.text}\n\n${generated.slice(anchor.index)}`;
205
+ }
206
+
207
+ const have = new Set(content.split("\n").map(l => l.trim()));
208
+ return { content, preserved, lost: preserved.lines.filter(l => !have.has(l)) };
209
+ }
@@ -10,7 +10,7 @@
10
10
  */
11
11
 
12
12
  import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
13
- import { dirname } from "path";
13
+ import { dirname, join } from "path";
14
14
 
15
15
  // ── Types ───────────────────────────────────────────────
16
16
 
@@ -28,6 +28,20 @@ const STALE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
28
28
 
29
29
  // ── Public API ──────────────────────────────────────────
30
30
 
31
+ /**
32
+ * Where the behavioral results cache lives, for a given project root.
33
+ *
34
+ * One binding, because this path had three. `lib/agent-audit.ts` and
35
+ * `scripts/test-brief.ts` WRITE it and `scripts/sync-sc-status.ts` READS it,
36
+ * and each one assembled `join(root, ".rungate", "behavioral-results.json")`
37
+ * for itself with nothing comparing the three. A drift in any one of them
38
+ * writes where nobody reads — and the symptom, an empty cache, is
39
+ * indistinguishable from "no behavioral results recorded yet" (#328).
40
+ */
41
+ export function behavioralCachePath(projectRoot: string): string {
42
+ return join(projectRoot, ".rungate", "behavioral-results.json");
43
+ }
44
+
31
45
  /**
32
46
  * Read the behavioral results cache from disk.
33
47
  * Returns empty object if file doesn't exist or is malformed.
@@ -65,14 +79,148 @@ export function isStale(timestamp: string): boolean {
65
79
 
66
80
  /**
67
81
  * Read cache and filter out stale entries (older than 7 days).
82
+ *
83
+ * Projected off `behavioralReading` rather than asking `isStale` a second
84
+ * time. The census below answers "has this criterion been measured" and so
85
+ * does this function; two deciders that agree are behaviourally one, and a
86
+ * mutation of either would leave the other holding every case up
87
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
68
88
  */
69
89
  export function readFreshCache(path: string): BehavioralCache {
70
90
  const cache = readCache(path);
71
91
  const fresh: BehavioralCache = {};
72
92
  for (const [id, entry] of Object.entries(cache)) {
73
- if (!isStale(entry.timestamp)) {
93
+ if (behavioralReading(entry).startsWith("fresh")) {
74
94
  fresh[id] = entry;
75
95
  }
76
96
  }
77
97
  return fresh;
78
98
  }
99
+
100
+ // ── The unmeasured census (#758) ────────────────────────
101
+
102
+ /**
103
+ * What the cache says about one criterion.
104
+ *
105
+ * Four states, not two. `stale` and `absent` are both "nobody has measured
106
+ * this", but they are different facts about why and a reader can act on only
107
+ * one of them, so they are counted apart.
108
+ */
109
+ export type BehavioralReadingKind = "fresh-pass" | "fresh-fail" | "stale" | "absent";
110
+
111
+ /**
112
+ * Whether the cache file could be read at all.
113
+ *
114
+ * `readCache` returns `{}` for a file that is missing AND for one that is
115
+ * corrupt, which is the conflation this census exists to undo — a corrupt
116
+ * cache is never a missing cache (`.claude/rules/config-access.md`). Nothing
117
+ * here goes through `readCache`.
118
+ */
119
+ export type BehavioralCacheState = "absent" | "unreadable" | "present";
120
+
121
+ export interface BehavioralCensus {
122
+ /** The one discriminator. Everything else is a projection of the lists. */
123
+ reading: "MEASURED" | "UNMEASURED";
124
+ unmeasuredReasons: string[];
125
+ cacheState: BehavioralCacheState;
126
+ counts: Record<BehavioralReadingKind, number>;
127
+ /** Every criterion with no fresh reading, named — a count sends nobody anywhere. */
128
+ unmeasured: string[];
129
+ total: number;
130
+ }
131
+
132
+ /**
133
+ * What the cache says about one criterion — the ONE decider.
134
+ *
135
+ * `readFreshCache`, `behavioralPattern` and the census all route through
136
+ * this. An entry with no parseable timestamp is `absent` rather than fresh:
137
+ * a reading whose date cannot be read is a reading nobody can date, and
138
+ * `new Date("")` is `NaN`, which makes every arithmetic comparison false and
139
+ * would otherwise read as brand new.
140
+ */
141
+ export function behavioralReading(entry: CacheEntry | undefined): BehavioralReadingKind {
142
+ if (!entry || typeof entry.timestamp !== "string") return "absent";
143
+ if (Number.isNaN(new Date(entry.timestamp).getTime())) return "absent";
144
+ if (isStale(entry.timestamp)) return "stale";
145
+ return entry.passed ? "fresh-pass" : "fresh-fail";
146
+ }
147
+
148
+ /** Absent, corrupt, or readable — three facts, never folded into two. */
149
+ export function behavioralCacheState(path: string): BehavioralCacheState {
150
+ if (!existsSync(path)) return "absent";
151
+ try {
152
+ const parsed = JSON.parse(readFileSync(path, "utf-8"));
153
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return "unreadable";
154
+ return "present";
155
+ } catch {
156
+ return "unreadable";
157
+ }
158
+ }
159
+
160
+ /**
161
+ * How many ticked `(behavioral)` criteria actually have a reading (#758).
162
+ *
163
+ * #328 connected the consumption half: a fresh `passed: false` entry now
164
+ * fails the suite. Nothing guarantees an entry is ever WRITTEN — the two
165
+ * writers run during a ship run or a brief test, never during an ordinary
166
+ * `bun test` — so the live state for all 35 ticked behavioral criteria is
167
+ * "no reading", which routed to `behavioral`: reported, ratcheted, and not
168
+ * checked.
169
+ *
170
+ * A criterion nobody has measured and a criterion that passed are different
171
+ * states and only one is reportable, but both were green and a reader could
172
+ * not tell which they had. This is the supply end of *Silent Default
173
+ * Substitution*, and the fix is #597's: not to make the measurement happen,
174
+ * but to make the report say it did not.
175
+ */
176
+ export function behavioralCensus(ids: string[], path: string): BehavioralCensus {
177
+ const state = behavioralCacheState(path);
178
+ const cache: BehavioralCache = state === "present"
179
+ ? JSON.parse(readFileSync(path, "utf-8"))
180
+ : {};
181
+
182
+ const counts: Record<BehavioralReadingKind, number> = {
183
+ "fresh-pass": 0, "fresh-fail": 0, stale: 0, absent: 0,
184
+ };
185
+ const unmeasured: string[] = [];
186
+
187
+ for (const id of ids) {
188
+ const kind = behavioralReading(cache[id]);
189
+ counts[kind]++;
190
+ if (kind === "stale" || kind === "absent") unmeasured.push(id);
191
+ }
192
+
193
+ const reasons: string[] = [];
194
+ // An empty population agrees with every bound. Said first, because the two
195
+ // counts below are both 0 for a census that collected nothing and for one
196
+ // in which everything was measured.
197
+ if (ids.length === 0) reasons.push("no ticked (behavioral) criteria were collected — the scan read nothing");
198
+ if (state === "absent") reasons.push("the behavioral results cache does not exist, so no criterion has a reading");
199
+ if (state === "unreadable") reasons.push("the behavioral results cache exists and could not be parsed");
200
+ if (counts.stale > 0) reasons.push(`${counts.stale} criterion(s) have only a stale reading, older than the 7-day threshold`);
201
+ if (counts.absent > 0 && state === "present") reasons.push(`${counts.absent} criterion(s) have no entry in the cache`);
202
+
203
+ return {
204
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
205
+ unmeasuredReasons: reasons,
206
+ cacheState: state,
207
+ counts,
208
+ unmeasured,
209
+ total: ids.length,
210
+ };
211
+ }
212
+
213
+ /**
214
+ * The census as one line for the suite output (#758 SC-1).
215
+ *
216
+ * A figure, not a line per criterion: 35 log lines is something a reader
217
+ * scrolls past, and the number is the thing that moves.
218
+ */
219
+ export function behavioralCensusLine(c: BehavioralCensus): string {
220
+ const m = c.counts["fresh-pass"] + c.counts["fresh-fail"];
221
+ return (
222
+ `BEHAVIORAL: ${c.reading} — ${m}/${c.total} criteria have a fresh reading ` +
223
+ `(pass ${c.counts["fresh-pass"]}, fail ${c.counts["fresh-fail"]}, ` +
224
+ `stale ${c.counts.stale}, no entry ${c.counts.absent}; cache ${c.cacheState})`
225
+ );
226
+ }