rungate 0.2.1 → 0.4.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/bin/rungate.ts +70 -0
- package/lib/aes-calculator.ts +66 -0
- package/lib/agent-audit.ts +139 -0
- package/lib/agent-brief-validation.ts +359 -0
- package/lib/agents-md-refs.ts +90 -0
- package/lib/bash-file-read.ts +197 -0
- package/lib/behavioral-cache.ts +78 -0
- package/lib/branch-cleanup.ts +234 -0
- package/lib/brief-context-parser.ts +35 -0
- package/lib/brief-precedence.ts +114 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +426 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +232 -0
- package/lib/compliance-report.ts +605 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +2161 -137
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +267 -0
- package/lib/decomposition-waves.ts +197 -0
- package/lib/deep-merge.ts +69 -0
- package/lib/dev-liveness.ts +214 -0
- package/lib/directive-extractor.ts +210 -0
- package/lib/distribution-standing.ts +113 -0
- package/lib/doc-hygiene.ts +238 -0
- package/lib/eval-criteria.ts +6 -0
- package/lib/evidence-portability.ts +123 -0
- package/lib/evidence-prevalidator.ts +390 -0
- package/lib/evidence-required.ts +150 -0
- package/lib/evidence-satisfiability.ts +288 -0
- package/lib/frontmatter.ts +163 -0
- package/lib/gap-scanner.ts +348 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +511 -0
- package/lib/generators/code-map.ts +60 -0
- package/lib/generators/types.ts +184 -0
- package/lib/git-ref-normalizer.ts +107 -0
- package/lib/github.ts +539 -0
- package/lib/harness-identity.ts +63 -0
- package/lib/hill-climb.ts +164 -0
- package/lib/instruction-effectiveness.ts +131 -0
- package/lib/issue-closure-audit.ts +225 -0
- package/lib/issue-create-override.ts +343 -0
- package/lib/issue-extraction.ts +368 -0
- package/lib/js-top-level-code.ts +250 -0
- package/lib/liveness-contradiction.ts +149 -0
- package/lib/organize.ts +505 -0
- package/lib/paths.ts +197 -6
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +512 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +128 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +288 -0
- package/lib/rule-health-pipeline.ts +264 -0
- package/lib/rule-health-trend.ts +161 -0
- package/lib/rule-provenance.ts +149 -0
- package/lib/rule-registry.ts +128 -0
- package/lib/rungate-schema.ts +127 -5
- package/lib/sc-claim-forms.ts +179 -0
- package/lib/sc-cover.ts +150 -0
- package/lib/sc-guard.ts +157 -0
- package/lib/sc-ids.ts +344 -0
- package/lib/scaffold/defaults.ts +165 -0
- package/lib/scaffold/managed-workflow.ts +370 -0
- package/lib/scaffold/owned-files.ts +265 -0
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/steps.ts +2621 -0
- package/lib/scanner.ts +701 -0
- package/lib/scope-denylist.ts +258 -0
- package/lib/screenshot-upload.ts +73 -0
- package/lib/secret-patterns.ts +112 -0
- package/lib/security-verdict.ts +616 -0
- package/lib/signal-phrases.ts +1 -0
- package/lib/spec-change-conformity.ts +80 -0
- package/lib/spec-files.ts +62 -0
- package/lib/spec-registry.ts +133 -0
- package/lib/spec-updater.ts +96 -0
- package/lib/stale-cleanup.ts +224 -0
- package/lib/stale-issue-scanner.ts +36 -0
- package/lib/strip-js-comments.ts +269 -0
- package/lib/suite-measurement.ts +228 -0
- package/lib/task-completion-checks.ts +224 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +535 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +432 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/lib/worktree-repo.ts +300 -0
- package/package.json +27 -3
- package/prompts/ac-adversary.md +14 -2
- package/prompts/aditi.md +5 -0
- package/prompts/blast-radius.md +5 -0
- package/prompts/container-verify.md +5 -0
- package/prompts/discovery.md +4 -0
- package/prompts/environment.md +5 -0
- package/prompts/evidence-hierarchy.md +5 -0
- package/prompts/evidence-validator.md +11 -0
- package/prompts/marcus.md +5 -0
- package/prompts/prevention.md +5 -0
- package/prompts/prove-reproducer.md +12 -0
- package/prompts/quinn-decision-tree.md +5 -0
- package/prompts/quinn-ui-brief.md +5 -0
- package/prompts/quinn.md +5 -0
- package/prompts/rca.md +5 -0
- package/prompts/read-before-write.md +4 -0
- package/prompts/regression.md +5 -0
- package/prompts/serena.md +5 -0
- package/scripts/audit-specs.ts +464 -0
- package/scripts/convert-spec.ts +293 -0
- package/scripts/create-sc.ts +92 -0
- package/scripts/create-spec.ts +166 -0
- package/scripts/extract-constraints.ts +4 -3
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/scaffold-project.ts +138 -1426
- package/scripts/sync-spec-tests.ts +211 -126
package/lib/sc-ids.ts
ADDED
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One owner for what an SC id is, and what a mention of one means
|
|
3
|
+
* (#330, #352, #358).
|
|
4
|
+
*
|
|
5
|
+
* Three files parsed SC ids with three different regexes:
|
|
6
|
+
*
|
|
7
|
+
* lib/conformity.ts extractSCs `SC-\w+` declarations
|
|
8
|
+
* scripts/sync-sc-status.ts coverageClaimIds `SC-\d+(?!\d)` mentions
|
|
9
|
+
* test/spec-sc-ids-unique.ts DECLARATION `SC-\d+` duplicates
|
|
10
|
+
*
|
|
11
|
+
* #330 called the divergence the root cause and named two of the three. The
|
|
12
|
+
* consequences are the three issues this module closes:
|
|
13
|
+
*
|
|
14
|
+
* - The uniqueness guard cannot see `SC-A1`, so three specs declare it and
|
|
15
|
+
* nothing notices.
|
|
16
|
+
* - The coverage lookup cannot see `SC-A1` either, so six anti-criteria are
|
|
17
|
+
* invisible — but widening it naively is worse, see below.
|
|
18
|
+
* - Every single-digit id is a real registry entry owned by
|
|
19
|
+
* `specs/bootstrap-data-flow/success-criteria.md`, and issues number their
|
|
20
|
+
* own criteria from 1. A comment about an issue's first criterion was
|
|
21
|
+
* credited as covering a behavioural, unimplemented bootstrap criterion.
|
|
22
|
+
*
|
|
23
|
+
* ## The notation, stated rather than assumed
|
|
24
|
+
*
|
|
25
|
+
* `SC-<n>` is a **global** id. The registry owns the number; exactly one spec
|
|
26
|
+
* may declare it.
|
|
27
|
+
*
|
|
28
|
+
* `SC-A<n>` is an **anti-criterion**, and `specs/SPEC-TEMPLATE.md` says what
|
|
29
|
+
* it is for: "anti-criterion — must NOT happen". Every spec numbers its own
|
|
30
|
+
* from A1, so the id is **per-spec by design**. Three specs declaring `SC-A1`
|
|
31
|
+
* is correct; three specs declaring `SC-640` would not be.
|
|
32
|
+
*
|
|
33
|
+
* Issue success criteria are **not** SC ids. The harness numbers them
|
|
34
|
+
* positionally when an issue does not number its own, so `#341 SC-1` and
|
|
35
|
+
* `#194 SC-640` look identical and mean opposite things — the first is this
|
|
36
|
+
* issue's first criterion, the second is a reference to the registry entry
|
|
37
|
+
* the file genuinely covers. Written as `AC-n` or longhand they are
|
|
38
|
+
* distinguishable; written as `SC-n` they are not, and no reader of the text
|
|
39
|
+
* can recover which was meant.
|
|
40
|
+
*
|
|
41
|
+
* ## Why crediting is gated on the registry
|
|
42
|
+
*
|
|
43
|
+
* #330 measured what `SC-\w+` additionally matches across `test/`:
|
|
44
|
+
* `SC-ID`, `SC-NNN`, `SC-TEST`, `SC-X`, `SC-guard`, `SC-numbered`, `SC-to`,
|
|
45
|
+
* `SC-S01`, `SC-S53` — prose fragments and placeholders. Crediting those
|
|
46
|
+
* manufactures coverage out of English, which is the flattering direction.
|
|
47
|
+
*
|
|
48
|
+
* So the pattern widens and the **credit** narrows: an id is creditable only
|
|
49
|
+
* if the registry declares it. `SC-guard` is not a registry id and never
|
|
50
|
+
* becomes one, so the widening cannot reach it. That is a property of the
|
|
51
|
+
* data rather than of the regex, which is the point — a regex narrow enough
|
|
52
|
+
* to exclude prose is also narrow enough to exclude `SC-A1`.
|
|
53
|
+
*/
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* How a spec declared an id. Two forms, two different questions (#392).
|
|
57
|
+
*
|
|
58
|
+
* `checkbox` is a TRACKED criterion — `- [ ] SC-N: ...` — and the only form
|
|
59
|
+
* the status flipper can tick.
|
|
60
|
+
*
|
|
61
|
+
* `heading` is `### SC-N: ...`, a documentation subsection. It tracks nothing,
|
|
62
|
+
* but it OWNS the number just as firmly, and ignoring that is what produced
|
|
63
|
+
* ten collisions: GATE-CONTRACTS-SPEC.md headed ten consecutive subsections
|
|
64
|
+
* whose numbers four other specs later reissued as tracked checkboxes. Those
|
|
65
|
+
* headings have since been renumbered into a block nobody else holds, so the
|
|
66
|
+
* example is history rather than live — but the rule it bought is not, and
|
|
67
|
+
* `crossFormCollisions` is what keeps the bank at zero.
|
|
68
|
+
*/
|
|
69
|
+
export type ScDeclarationForm = "checkbox" | "heading";
|
|
70
|
+
|
|
71
|
+
export interface ScDeclaration {
|
|
72
|
+
id: string;
|
|
73
|
+
specFile: string;
|
|
74
|
+
checked: boolean;
|
|
75
|
+
statement: string;
|
|
76
|
+
form: ScDeclarationForm;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* The id itself: `SC-`, an optional uppercase class letter, digits.
|
|
81
|
+
*
|
|
82
|
+
* Not `\w+`. A class letter is part of the notation (`A` for anti-criterion);
|
|
83
|
+
* an arbitrary word is a prose fragment. Kept as a source string so the
|
|
84
|
+
* declaration and mention patterns are built from one definition and cannot
|
|
85
|
+
* drift — the drift is what #330 is about.
|
|
86
|
+
*/
|
|
87
|
+
export const SC_ID_SOURCE = "SC-[A-Z]?\\d+";
|
|
88
|
+
|
|
89
|
+
/** A declared id: a checklist line opening with one. Not a mention. */
|
|
90
|
+
export function scDeclarationPattern(): RegExp {
|
|
91
|
+
return new RegExp(`^- \\[([ xX])\\] (${SC_ID_SOURCE}):\\s*(.+)$`, "gm");
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* A declared id in heading form: `### SC-N: what this section is about`.
|
|
96
|
+
*
|
|
97
|
+
* Same anchoring discipline as the checklist pattern — the id must OPEN the
|
|
98
|
+
* heading. A heading that merely mentions one ("### Why SC-640 was wrong") is
|
|
99
|
+
* prose, and crediting it would be the citation-vs-claim trap that
|
|
100
|
+
* `.claude/rules/claiming-sc-coverage.md` exists about.
|
|
101
|
+
*/
|
|
102
|
+
export function scHeadingDeclarationPattern(): RegExp {
|
|
103
|
+
return new RegExp(`^#{1,6}[ \\t]+(${SC_ID_SOURCE}):\\s*(.+)$`, "gm");
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* A mention of an id, anywhere.
|
|
108
|
+
*
|
|
109
|
+
* The trailing boundary is "not a word character and not a hyphen": `SC-1`
|
|
110
|
+
* must not match inside `SC-15` (#148) or inside `SC-1-draft`. The leading
|
|
111
|
+
* `\b` keeps `MISC-1` out.
|
|
112
|
+
*/
|
|
113
|
+
export function scMentionPattern(): RegExp {
|
|
114
|
+
return new RegExp(`\\b${SC_ID_SOURCE}(?![\\w-])`, "g");
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** One specific id, for asking "does this text name THIS criterion". */
|
|
118
|
+
export function oneScMentionPattern(id: string): RegExp {
|
|
119
|
+
return new RegExp(`\\b${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w-])`);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Anti-criteria are numbered per spec, so the id alone does not identify one.
|
|
124
|
+
* `specs/SPEC-TEMPLATE.md` ships `- [ ] SC-A1: [anti-criterion — must NOT
|
|
125
|
+
* happen]`, which is where every spec's A1 comes from.
|
|
126
|
+
*/
|
|
127
|
+
export function isAntiCriterion(id: string): boolean {
|
|
128
|
+
return /^SC-[A-Z]\d+$/.test(id);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Could this id equally be an issue's own criterion?
|
|
133
|
+
*
|
|
134
|
+
* The harness numbers an issue's criteria from 1, so every id a short issue
|
|
135
|
+
* produces is `SC-1`..`SC-9` — and all nine are declared by
|
|
136
|
+
* `specs/bootstrap-data-flow/success-criteria.md`. The overlap is exactly the
|
|
137
|
+
* single-digit numerics; `SC-640` cannot be an issue's 640th criterion.
|
|
138
|
+
*/
|
|
139
|
+
export function isIssueShaped(id: string): boolean {
|
|
140
|
+
return /^SC-\d$/.test(id);
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* The registry: which spec files declare each id.
|
|
145
|
+
*
|
|
146
|
+
* TWO maps, because "may this be ticked" and "does this id name one
|
|
147
|
+
* criterion" are different questions and conflating them is #392 (#330 only
|
|
148
|
+
* ever needed the first, so there was only ever one map).
|
|
149
|
+
*
|
|
150
|
+
* byId CHECKBOX declarations only. The flipper's view, and
|
|
151
|
+
* `crossSpecCollisions`'s. Unchanged semantics — a heading
|
|
152
|
+
* must never become tickable.
|
|
153
|
+
* declaredById EVERY form. The namespace as it actually is, which is what
|
|
154
|
+
* ambiguity and allocation have to be computed over.
|
|
155
|
+
*/
|
|
156
|
+
export interface ScRegistry {
|
|
157
|
+
byId: Map<string, string[]>;
|
|
158
|
+
declaredById: Map<string, string[]>;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** The template's ids are placeholders — `isTemplateSpec` already skips it. */
|
|
162
|
+
export function isTemplateSpec(specFile: string): boolean {
|
|
163
|
+
return specFile.includes("SPEC-TEMPLATE");
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* The TRACKED criteria a spec declares. Checkbox form only.
|
|
168
|
+
*
|
|
169
|
+
* This is `extractSCs` — `lib/conformity.ts:339` returns it verbatim, which
|
|
170
|
+
* is #330's "one owner for what a declaration is" and must stay that way.
|
|
171
|
+
*
|
|
172
|
+
* Headings are deliberately NOT here, and the first version of #392 put them
|
|
173
|
+
* here and was wrong: the conformity engine runs an assertion against every
|
|
174
|
+
* declaration it is handed, so a `### SC-N: gate-executor pass/fail criteria`
|
|
175
|
+
* section title became a criterion to satisfy, and ten of them joined the
|
|
176
|
+
* corpus of things that can fail a gate. A heading owns a NUMBER; it does not
|
|
177
|
+
* state a checkable claim. Two questions, two parsers — see
|
|
178
|
+
* `parseScHeadingDeclarations`.
|
|
179
|
+
*/
|
|
180
|
+
export function parseScDeclarations(content: string, specFile: string): ScDeclaration[] {
|
|
181
|
+
const out: ScDeclaration[] = [];
|
|
182
|
+
for (const m of content.matchAll(scDeclarationPattern())) {
|
|
183
|
+
out.push({
|
|
184
|
+
id: m[2],
|
|
185
|
+
specFile,
|
|
186
|
+
checked: m[1].toLowerCase() === "x",
|
|
187
|
+
statement: m[3].trim(),
|
|
188
|
+
form: "checkbox",
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
return out;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* The ids a spec OWNS without tracking — `### SC-N: ...` subsection titles.
|
|
196
|
+
*
|
|
197
|
+
* Only the registry wants these, and only for the namespace question: is this
|
|
198
|
+
* id ambiguous, and is this number free. Nothing may tick one and nothing may
|
|
199
|
+
* assert against one.
|
|
200
|
+
*/
|
|
201
|
+
export function parseScHeadingDeclarations(content: string, specFile: string): ScDeclaration[] {
|
|
202
|
+
const out: ScDeclaration[] = [];
|
|
203
|
+
for (const m of content.matchAll(scHeadingDeclarationPattern())) {
|
|
204
|
+
out.push({
|
|
205
|
+
id: m[1],
|
|
206
|
+
specFile,
|
|
207
|
+
// A heading tracks nothing, so it is never "done".
|
|
208
|
+
checked: false,
|
|
209
|
+
statement: m[2].trim(),
|
|
210
|
+
form: "heading",
|
|
211
|
+
});
|
|
212
|
+
}
|
|
213
|
+
return out;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
export function buildScRegistry(specs: Array<{ file: string; content: string }>): ScRegistry {
|
|
217
|
+
const byId = new Map<string, string[]>();
|
|
218
|
+
const declaredById = new Map<string, string[]>();
|
|
219
|
+
const record = (map: Map<string, string[]>, id: string, file: string) => {
|
|
220
|
+
const seen = map.get(id) ?? [];
|
|
221
|
+
// By FILE, not by declaration: a spec that heads a section with the id it
|
|
222
|
+
// also tracks is one declarer, and counting it twice would make every
|
|
223
|
+
// such spec collide with itself.
|
|
224
|
+
if (!seen.includes(file)) seen.push(file);
|
|
225
|
+
map.set(id, seen);
|
|
226
|
+
};
|
|
227
|
+
for (const { file, content } of specs) {
|
|
228
|
+
if (isTemplateSpec(file)) continue;
|
|
229
|
+
for (const d of parseScDeclarations(content, file)) {
|
|
230
|
+
record(byId, d.id, file);
|
|
231
|
+
record(declaredById, d.id, file);
|
|
232
|
+
}
|
|
233
|
+
// Headings reach `declaredById` ONLY. A heading that became tickable
|
|
234
|
+
// would let the status flipper tick a section title.
|
|
235
|
+
for (const d of parseScHeadingDeclarations(content, file)) {
|
|
236
|
+
record(declaredById, d.id, file);
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
return { byId, declaredById };
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* A GLOBAL id declared by more than one spec. Anti-criteria are exempt
|
|
244
|
+
* because being per-spec is their definition, not their defect.
|
|
245
|
+
*
|
|
246
|
+
* `test/spec-sc-ids-unique.test.ts` checks each spec against itself and so
|
|
247
|
+
* cannot see this: two specs each declaring `SC-2` once are each internally
|
|
248
|
+
* consistent.
|
|
249
|
+
*/
|
|
250
|
+
export function crossSpecCollisions(reg: ScRegistry): string[] {
|
|
251
|
+
return [...reg.byId.entries()]
|
|
252
|
+
.filter(([id, specs]) => !isAntiCriterion(id) && specs.length > 1)
|
|
253
|
+
.map(([id, specs]) => `${id} declared by ${specs.join(" and ")}`)
|
|
254
|
+
.sort();
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* The same collision, counted over EVERY declaration form (#392).
|
|
259
|
+
*
|
|
260
|
+
* Separate from `crossSpecCollisions` rather than folded into it, and the
|
|
261
|
+
* separation is the decision: widening that function would turn
|
|
262
|
+
* `test/spec-sc-ids-unique.test.ts`'s real-tree assertion red over ten ids,
|
|
263
|
+
* and the remedy it prescribes — "renumber the later claimant" — is a
|
|
264
|
+
* spec-content call about who moves, not something to take while fixing a
|
|
265
|
+
* credit bug.
|
|
266
|
+
*
|
|
267
|
+
* So the tracked-criterion guard stays at zero and this one ships as a
|
|
268
|
+
* counted ratchet, per `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
269
|
+
* Qualification (`ambiguityOf` reads `declaredById`) already stops the known
|
|
270
|
+
* ten doing harm; this stops an eleventh arriving unnoticed.
|
|
271
|
+
*/
|
|
272
|
+
export function crossFormCollisions(reg: ScRegistry): string[] {
|
|
273
|
+
return [...reg.declaredById.entries()]
|
|
274
|
+
.filter(([id, specs]) => !isAntiCriterion(id) && specs.length > 1)
|
|
275
|
+
.map(([id, specs]) => `${id} declared by ${specs.join(" and ")}`)
|
|
276
|
+
.sort();
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* Does a bare mention of this id say which criterion it means?
|
|
281
|
+
*
|
|
282
|
+
* Three ways it does not, and they are different facts:
|
|
283
|
+
* per-spec an anti-criterion, numbered from A1 in every spec
|
|
284
|
+
* multi-spec a global id two specs both claim — a collision, not a scope
|
|
285
|
+
* issue-shaped a number an issue's own criteria also use
|
|
286
|
+
*/
|
|
287
|
+
export type Ambiguity = "none" | "per-spec" | "multi-spec" | "issue-shaped" | "not-a-criterion";
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* `declaredById`, not `byId` (#392). An id is ambiguous when two specs
|
|
291
|
+
* DECLARE it, and a `### SC-N:` heading declares one — the reported case was
|
|
292
|
+
* a number naming both a GATE-CONTRACTS subsection and a
|
|
293
|
+
* SCAFFOLD-DECOMPOSITION criterion, read as unambiguous because only the
|
|
294
|
+
* second form was being counted, so a comment that said
|
|
295
|
+
* "GATE-CONTRACTS-SPEC.md" in as many words ticked the other one. That pair
|
|
296
|
+
* has since been renumbered apart; the rule outlives the example.
|
|
297
|
+
*/
|
|
298
|
+
export function ambiguityOf(id: string, reg: ScRegistry): Ambiguity {
|
|
299
|
+
const specs = reg.declaredById.get(id);
|
|
300
|
+
if (!specs || specs.length === 0) return "not-a-criterion";
|
|
301
|
+
if (isAntiCriterion(id)) return "per-spec";
|
|
302
|
+
if (specs.length > 1) return "multi-spec";
|
|
303
|
+
if (isIssueShaped(id)) return "issue-shaped";
|
|
304
|
+
return "none";
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
export function requiresQualification(id: string, reg: ScRegistry): boolean {
|
|
308
|
+
const a = ambiguityOf(id, reg);
|
|
309
|
+
return a === "per-spec" || a === "multi-spec" || a === "issue-shaped";
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/**
|
|
313
|
+
* The tokens that name a spec in prose.
|
|
314
|
+
*
|
|
315
|
+
* `specs/bootstrap-data-flow/success-criteria.md` is cited as
|
|
316
|
+
* "bootstrap-data-flow" far more often than by its filename, so the
|
|
317
|
+
* containing directory counts too. Both are compared case-insensitively
|
|
318
|
+
* because prose capitalises.
|
|
319
|
+
*/
|
|
320
|
+
export function qualifierTokens(specFile: string): string[] {
|
|
321
|
+
const parts = specFile.replace(/^specs\//, "").split("/");
|
|
322
|
+
const base = parts[parts.length - 1].replace(/\.md$/, "");
|
|
323
|
+
const tokens = [base];
|
|
324
|
+
if (parts.length > 1) tokens.push(parts[parts.length - 2]);
|
|
325
|
+
return tokens;
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** How far either side of a mention a qualifier is allowed to sit. */
|
|
329
|
+
export const QUALIFIER_WINDOW_BEFORE = 240;
|
|
330
|
+
export const QUALIFIER_WINDOW_AFTER = 120;
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* Is the mention at `at` qualified by a token naming `specFile`?
|
|
334
|
+
*
|
|
335
|
+
* A window rather than a sentence, because the mention may be in a `describe`
|
|
336
|
+
* title whose spec is named in the docblock above it — which is the project's
|
|
337
|
+
* most common way of saying which spec a file is about.
|
|
338
|
+
*/
|
|
339
|
+
export function isQualifiedBy(source: string, at: number, specFile: string): boolean {
|
|
340
|
+
const window = source
|
|
341
|
+
.slice(Math.max(0, at - QUALIFIER_WINDOW_BEFORE), at + QUALIFIER_WINDOW_AFTER)
|
|
342
|
+
.toLowerCase();
|
|
343
|
+
return qualifierTokens(specFile).some(t => window.includes(t.toLowerCase()));
|
|
344
|
+
}
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* scaffold/defaults.ts — what a GREENFIELD scaffold writes into
|
|
3
|
+
* `.claude/rungate/roles.json` and `.claude/rungate/hooks.json`.
|
|
4
|
+
*
|
|
5
|
+
* Both scaffold entry points (lib/scaffold/steps.ts and
|
|
6
|
+
* scripts/scaffold-rungate-config.ts) used to hardcode `{}` and `[]` here.
|
|
7
|
+
* A project scaffolded that way looks configured and is not: ship.js finds no
|
|
8
|
+
* role to dispatch and no hook to deploy, and nothing says so out loud (#70).
|
|
9
|
+
*
|
|
10
|
+
* Roles are DERIVED from DEFAULT_AGENT_META rather than restated, so the role
|
|
11
|
+
* set a project is scaffolded with and the role set brief generation falls back
|
|
12
|
+
* to cannot drift apart. Only the two fields DEFAULT_AGENT_META has no opinion
|
|
13
|
+
* about — the brief path and the standard task — are added here.
|
|
14
|
+
*
|
|
15
|
+
* The migration path (splitMonolithToDirectory) must NOT use any of this: an
|
|
16
|
+
* existing project's roles and hooks are the answer, and injecting defaults
|
|
17
|
+
* into a split would silently rewrite someone's config.
|
|
18
|
+
*/
|
|
19
|
+
import { DEFAULT_AGENT_META } from "../create-brief";
|
|
20
|
+
|
|
21
|
+
export interface HookRegistration {
|
|
22
|
+
name: string;
|
|
23
|
+
hookFor: string;
|
|
24
|
+
command: string;
|
|
25
|
+
enabled: boolean;
|
|
26
|
+
matcher?: string;
|
|
27
|
+
description: string;
|
|
28
|
+
deployToConsumers?: boolean;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Project-agnostic smoke task per role, used by `test-brief` and
|
|
33
|
+
* `fresh-eyes-test` when no task is given. Deliberately phrased against things
|
|
34
|
+
* every scaffolded project has (a test command, a source tree, a brief) rather
|
|
35
|
+
* than against rungate's own files.
|
|
36
|
+
*/
|
|
37
|
+
const DEFAULT_STANDARD_TASKS: Record<string, string> = {
|
|
38
|
+
discovery: "Read the issue, size the work, and write ACs with evidence commands",
|
|
39
|
+
marcus: "Add config/test.json with {name: test} and write a unit test for it",
|
|
40
|
+
quinn: "Validate the latest commit passes all tests and type checks, report AC evidence",
|
|
41
|
+
rook: "Review the changed files for input validation, path traversal, and command injection",
|
|
42
|
+
serena: "Review the largest source module and propose a decomposition into smaller modules",
|
|
43
|
+
aditi: "Review the primary user-facing surface for layout, hierarchy, and accessibility",
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
function standardTaskFor(role: string, description: string): string {
|
|
47
|
+
return DEFAULT_STANDARD_TASKS[role] ?? `Perform ${description.toLowerCase()} tasks as assigned`;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* The role map a greenfield `.claude/rungate/roles.json` is written with.
|
|
52
|
+
*
|
|
53
|
+
* Every entry satisfies RoleSchema (brief + standardTask required) and carries
|
|
54
|
+
* the full agent meta, because buildAgentMeta fills a missing `tools`/`model`
|
|
55
|
+
* with its own generic default — an entry that omits them would quietly
|
|
56
|
+
* downgrade marcus from opus to sonnet on the next brief generation.
|
|
57
|
+
*/
|
|
58
|
+
export function buildDefaultRoles(): Record<string, Record<string, unknown>> {
|
|
59
|
+
const roles: Record<string, Record<string, unknown>> = {};
|
|
60
|
+
|
|
61
|
+
for (const [name, meta] of Object.entries(DEFAULT_AGENT_META)) {
|
|
62
|
+
roles[name] = {
|
|
63
|
+
brief: `.claude/agents/${name}.md`,
|
|
64
|
+
...(meta.isolation ? { isolation: meta.isolation } : {}),
|
|
65
|
+
standardTask: standardTaskFor(name, meta.description),
|
|
66
|
+
description: meta.description,
|
|
67
|
+
tools: meta.tools,
|
|
68
|
+
model: meta.model,
|
|
69
|
+
...(meta.tiers ? { tiers: meta.tiers } : {}),
|
|
70
|
+
...(meta.memory ? { memory: meta.memory } : {}),
|
|
71
|
+
...(meta.maxTurns ? { maxTurns: meta.maxTurns } : {}),
|
|
72
|
+
...(meta.effort ? { effort: meta.effort } : {}),
|
|
73
|
+
...(meta.disallowedTools ? { disallowedTools: meta.disallowedTools } : {}),
|
|
74
|
+
...(meta.omitClaudeMd ? { omitClaudeMd: meta.omitClaudeMd } : {}),
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
return roles;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Hook registrations a greenfield `.claude/rungate/hooks.json` is written with.
|
|
83
|
+
*
|
|
84
|
+
* Curated rather than "every file in hooks/": each entry below names a hook
|
|
85
|
+
* implementation that ships with the harness AND is meaningful in a project
|
|
86
|
+
* that has no specs, no issue tracker wiring and no gates configured yet.
|
|
87
|
+
* Spec- and issue-coupled hooks (SpecSCGuard, IssueCloseGuard, MergeGuard, …)
|
|
88
|
+
* are left for a project to opt into once it has the thing they guard.
|
|
89
|
+
*
|
|
90
|
+
* `${RUNGATE_HOOKS_DIR}` stays unexpanded on disk — deployHooksToConsumers
|
|
91
|
+
* resolves it at deploy time, so the file survives the harness moving.
|
|
92
|
+
*/
|
|
93
|
+
export function buildDefaultHooks(): HookRegistration[] {
|
|
94
|
+
return [
|
|
95
|
+
{
|
|
96
|
+
name: "BashToolGuard",
|
|
97
|
+
hookFor: "PreToolUse",
|
|
98
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/BashToolGuard.hook.ts",
|
|
99
|
+
enabled: true,
|
|
100
|
+
matcher: "Bash",
|
|
101
|
+
description: "Blocks cat/head/tail file reading — agents must use the Read tool",
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
name: "TestSuiteGuard",
|
|
105
|
+
hookFor: "PreToolUse",
|
|
106
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/TestSuiteGuard.hook.ts",
|
|
107
|
+
enabled: true,
|
|
108
|
+
matcher: "Bash",
|
|
109
|
+
description: "Blocks a third full test suite run in one session — forces targeted tests",
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
name: "AgentBriefGuard",
|
|
113
|
+
hookFor: "PreToolUse",
|
|
114
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/AgentBriefGuard.hook.ts",
|
|
115
|
+
enabled: true,
|
|
116
|
+
matcher: "Agent",
|
|
117
|
+
description: "Validates agent brief templates and enforces the ship-active marker",
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
name: "AgentVerdictCapture",
|
|
121
|
+
hookFor: "SubagentStop",
|
|
122
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/AgentVerdictCapture.hook.ts",
|
|
123
|
+
enabled: true,
|
|
124
|
+
description: "Captures agent verdicts and writes them to workflow-state.json",
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
name: "AutoVerifyGate",
|
|
128
|
+
hookFor: "PostToolUse",
|
|
129
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/AutoVerifyGate.hook.ts",
|
|
130
|
+
enabled: true,
|
|
131
|
+
matcher: "Agent",
|
|
132
|
+
description: "Nudges the DA to run the verify gate after an agent completes",
|
|
133
|
+
},
|
|
134
|
+
{
|
|
135
|
+
name: "CommitEnforcement",
|
|
136
|
+
hookFor: "PostToolUse",
|
|
137
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/CommitEnforcement.hook.ts",
|
|
138
|
+
enabled: true,
|
|
139
|
+
matcher: "Agent",
|
|
140
|
+
description: "Detects uncommitted changes left behind in agent worktrees",
|
|
141
|
+
},
|
|
142
|
+
{
|
|
143
|
+
name: "GateEnforcement",
|
|
144
|
+
hookFor: "PreToolUse",
|
|
145
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/GateEnforcement.hook.ts",
|
|
146
|
+
enabled: true,
|
|
147
|
+
matcher: ".*",
|
|
148
|
+
description: "Nags on gate failures and blocks Skill calls after max strikes",
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
name: "PostCompact",
|
|
152
|
+
hookFor: "PostCompact",
|
|
153
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/PostCompact.hook.ts",
|
|
154
|
+
enabled: true,
|
|
155
|
+
description: "Re-injects critical rules after context window compaction",
|
|
156
|
+
},
|
|
157
|
+
{
|
|
158
|
+
name: "StaleTTLCleanup",
|
|
159
|
+
hookFor: "SessionStart",
|
|
160
|
+
command: "bun ${RUNGATE_HOOKS_DIR}/StaleTTLCleanup.hook.ts",
|
|
161
|
+
enabled: true,
|
|
162
|
+
description: "Cleans up stale workflow-state.json and ship-active files",
|
|
163
|
+
},
|
|
164
|
+
];
|
|
165
|
+
}
|