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.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- 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
|
+
}
|
package/lib/behavioral-cache.ts
CHANGED
|
@@ -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 (
|
|
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
|
+
}
|