rungate 0.2.1 → 0.3.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 (119) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/canary.ts +117 -0
  11. package/lib/check-registry.ts +226 -0
  12. package/lib/ci-checkout.ts +400 -0
  13. package/lib/cli-commands.ts +137 -0
  14. package/lib/compliance-backfill.ts +220 -0
  15. package/lib/compliance-report.ts +504 -0
  16. package/lib/compliance.ts +361 -0
  17. package/lib/config-loader.ts +255 -0
  18. package/lib/conformity.ts +1818 -131
  19. package/lib/container-provenance.ts +230 -0
  20. package/lib/create-brief.ts +150 -0
  21. package/lib/create-sc.ts +272 -0
  22. package/lib/deep-merge.ts +69 -0
  23. package/lib/dev-liveness.ts +214 -0
  24. package/lib/directive-extractor.ts +210 -0
  25. package/lib/distribution-standing.ts +113 -0
  26. package/lib/doc-hygiene.ts +238 -0
  27. package/lib/eval-criteria.ts +6 -0
  28. package/lib/evidence-portability.ts +123 -0
  29. package/lib/evidence-prevalidator.ts +390 -0
  30. package/lib/evidence-required.ts +150 -0
  31. package/lib/evidence-satisfiability.ts +288 -0
  32. package/lib/frontmatter.ts +163 -0
  33. package/lib/gap-scanner.ts +348 -0
  34. package/lib/gate-enforcement.ts +366 -0
  35. package/lib/generators/agent-briefs.ts +136 -0
  36. package/lib/generators/agents-md.ts +506 -0
  37. package/lib/generators/code-map.ts +60 -0
  38. package/lib/generators/types.ts +184 -0
  39. package/lib/git-ref-normalizer.ts +107 -0
  40. package/lib/github.ts +539 -0
  41. package/lib/harness-identity.ts +63 -0
  42. package/lib/hill-climb.ts +164 -0
  43. package/lib/instruction-effectiveness.ts +131 -0
  44. package/lib/issue-closure-audit.ts +225 -0
  45. package/lib/issue-create-override.ts +343 -0
  46. package/lib/js-top-level-code.ts +250 -0
  47. package/lib/liveness-contradiction.ts +149 -0
  48. package/lib/organize.ts +505 -0
  49. package/lib/paths.ts +197 -6
  50. package/lib/post-fix-verify.ts +157 -0
  51. package/lib/prior-branch.ts +489 -0
  52. package/lib/project-state-shape.ts +166 -0
  53. package/lib/promote-outputs.ts +156 -0
  54. package/lib/prove-label-gate.ts +35 -0
  55. package/lib/reachability.ts +302 -0
  56. package/lib/release-preflight.ts +186 -0
  57. package/lib/rule-health-pipeline.ts +264 -0
  58. package/lib/rule-health-trend.ts +161 -0
  59. package/lib/rule-provenance.ts +149 -0
  60. package/lib/rule-registry.ts +128 -0
  61. package/lib/rungate-schema.ts +114 -4
  62. package/lib/sc-claim-forms.ts +179 -0
  63. package/lib/sc-cover.ts +150 -0
  64. package/lib/sc-guard.ts +157 -0
  65. package/lib/sc-ids.ts +344 -0
  66. package/lib/scaffold/defaults.ts +165 -0
  67. package/lib/scaffold/managed-workflow.ts +370 -0
  68. package/lib/scaffold/owned-files.ts +265 -0
  69. package/lib/scaffold/steps.ts +2680 -0
  70. package/lib/scanner.ts +701 -0
  71. package/lib/screenshot-upload.ts +73 -0
  72. package/lib/secret-patterns.ts +112 -0
  73. package/lib/security-verdict.ts +616 -0
  74. package/lib/signal-phrases.ts +1 -0
  75. package/lib/spec-change-conformity.ts +80 -0
  76. package/lib/spec-files.ts +62 -0
  77. package/lib/spec-registry.ts +133 -0
  78. package/lib/spec-updater.ts +96 -0
  79. package/lib/stale-cleanup.ts +224 -0
  80. package/lib/stale-issue-scanner.ts +36 -0
  81. package/lib/strip-js-comments.ts +269 -0
  82. package/lib/suite-measurement.ts +228 -0
  83. package/lib/task-completion-checks.ts +177 -0
  84. package/lib/test-suite-lock.ts +1136 -0
  85. package/lib/transcript-checker.ts +1140 -0
  86. package/lib/validators/spec-validators.ts +171 -0
  87. package/lib/verdict-capture.ts +73 -0
  88. package/lib/verified-push.ts +358 -0
  89. package/lib/workflow-security.ts +174 -0
  90. package/lib/worktree-cleanup.ts +250 -0
  91. package/lib/worktree-collect.ts +283 -0
  92. package/lib/worktree-isolation.ts +82 -0
  93. package/package.json +24 -2
  94. package/prompts/ac-adversary.md +14 -2
  95. package/prompts/aditi.md +5 -0
  96. package/prompts/blast-radius.md +5 -0
  97. package/prompts/container-verify.md +5 -0
  98. package/prompts/discovery.md +4 -0
  99. package/prompts/environment.md +5 -0
  100. package/prompts/evidence-hierarchy.md +5 -0
  101. package/prompts/evidence-validator.md +11 -0
  102. package/prompts/marcus.md +5 -0
  103. package/prompts/prevention.md +5 -0
  104. package/prompts/prove-reproducer.md +12 -0
  105. package/prompts/quinn-decision-tree.md +5 -0
  106. package/prompts/quinn-ui-brief.md +5 -0
  107. package/prompts/quinn.md +5 -0
  108. package/prompts/rca.md +5 -0
  109. package/prompts/read-before-write.md +4 -0
  110. package/prompts/regression.md +5 -0
  111. package/prompts/serena.md +5 -0
  112. package/scripts/audit-specs.ts +464 -0
  113. package/scripts/convert-spec.ts +293 -0
  114. package/scripts/create-sc.ts +92 -0
  115. package/scripts/create-spec.ts +166 -0
  116. package/scripts/extract-constraints.ts +4 -3
  117. package/scripts/generate-code-map.ts +1 -1
  118. package/scripts/scaffold-project.ts +138 -1426
  119. package/scripts/sync-spec-tests.ts +211 -126
@@ -0,0 +1,283 @@
1
+ /**
2
+ * Collect the output of N parallel agents, each working in its own worktree,
3
+ * into one tree that can be staged and committed (#81).
4
+ *
5
+ * `workflows/ship.js` flattened every agent's `filesChanged` into a single list
6
+ * and then kept only the LAST agent's `worktreePath`. `relativizePaths` only
7
+ * tries `[commitDir, PROJECT_ROOT]`, so paths belonging to the other N-1
8
+ * worktrees stayed absolute and `buildSafeGitAdd` rejected them — correctly, it
9
+ * refuses absolute paths. Eleven agents produced 37 minutes of valid work on
10
+ * run wf_5e32e9d4-dd2 and none of it could be committed.
11
+ *
12
+ * The losing information was the pairing: which files came from which worktree.
13
+ * Keep that, and collection is straightforward.
14
+ *
15
+ * Copying rather than merging branches is deliberate. The parallel path is only
16
+ * taken when the sub-issues have NON-OVERLAPPING file sets (ship.js falls back
17
+ * to a single sequential agent otherwise), so no two worktrees can claim the
18
+ * same file and there is nothing for a merge to resolve. A copy also leaves the
19
+ * agents' worktrees untouched, which matters when one sibling fails and the
20
+ * others' work has to survive.
21
+ */
22
+
23
+ import { copyFileSync, existsSync, lstatSync, mkdirSync, realpathSync } from "fs";
24
+ import { dirname, isAbsolute, join, relative, resolve } from "path";
25
+
26
+ export interface AgentBuildResult {
27
+ worktreePath?: string;
28
+ filesChanged?: string[];
29
+ }
30
+
31
+ export interface WorktreeGroup {
32
+ worktreePath: string;
33
+ /** Paths relative to `worktreePath`. */
34
+ files: string[];
35
+ }
36
+
37
+ export interface CollectResult {
38
+ /** Paths relative to the project root — safe to hand to buildSafeGitAdd. */
39
+ copied: string[];
40
+ /** Absolute source paths an agent claimed to have written that do not exist. */
41
+ missing: string[];
42
+ }
43
+
44
+ /**
45
+ * True when `child` is at or beneath `parent`, comparing LEXICALLY.
46
+ *
47
+ * Used only to reject obviously-escaping paths before touching the disk.
48
+ * Lexical containment alone is not a security boundary: `resolve` and
49
+ * `relative` never consult the filesystem, so `wt/lib/a.ts` is "inside" the
50
+ * worktree by string even when `wt/lib` is a symlink to somewhere else
51
+ * entirely. `realIsInside` is the check that actually decides.
52
+ */
53
+ function isInside(parent: string, child: string): boolean {
54
+ const rel = relative(resolve(parent), resolve(child));
55
+ return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
56
+ }
57
+
58
+ /**
59
+ * True when `child`'s REAL path is at or beneath `parent`'s real path.
60
+ *
61
+ * `child` may not exist yet (a destination), so walk up to the deepest
62
+ * ancestor that does, resolve that, and re-attach the remainder. This is what
63
+ * catches a symlinked intermediate directory, which lexical comparison cannot.
64
+ */
65
+ function realIsInside(parent: string, child: string): boolean {
66
+ let realParent: string;
67
+ try {
68
+ realParent = realpathSync(resolve(parent));
69
+ } catch {
70
+ return false;
71
+ }
72
+
73
+ let probe = resolve(child);
74
+ const tail: string[] = [];
75
+ while (!existsSync(probe)) {
76
+ const up = dirname(probe);
77
+ if (up === probe) return false; // walked to the filesystem root
78
+ tail.unshift(relative(up, probe));
79
+ probe = up;
80
+ }
81
+
82
+ let realChild: string;
83
+ try {
84
+ realChild = join(realpathSync(probe), ...tail);
85
+ } catch {
86
+ return false;
87
+ }
88
+
89
+ const rel = relative(realParent, realChild);
90
+ return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
91
+ }
92
+
93
+ /**
94
+ * Pair each agent's reported files with the worktree it reported them from,
95
+ * converting to worktree-relative paths and discarding anything that escapes.
96
+ *
97
+ * An agent naming a file outside its own worktree is either confused or
98
+ * hostile. Either way, copying it would write somewhere nobody authorised, so
99
+ * it is dropped here rather than being handed to the copy step.
100
+ */
101
+ /**
102
+ * Remove a trailing parenthesised annotation from a reported path (#279).
103
+ *
104
+ * Agents describe what they did to a file as they list it:
105
+ *
106
+ * "lib/strip-js-comments.ts (NEW, 178 lines)"
107
+ * "test/spec-compliance.test.ts (MOD: +SHIP_CODE at L8-28)"
108
+ *
109
+ * Only a trailing ` (...)` is an annotation. Splitting on the first space
110
+ * instead would mangle `docs/my notes.md` into a miss, which trades a silent
111
+ * drop for a silent rejection — the same bug facing the other way.
112
+ */
113
+ export function stripPathAnnotation(entry: string): string {
114
+ const m = entry.match(/^(.*?)\s+\([^()]*\)$/);
115
+ return m ? m[1] : entry;
116
+ }
117
+
118
+ export function groupFilesByWorktree(results: AgentBuildResult[]): WorktreeGroup[] {
119
+ const groups: WorktreeGroup[] = [];
120
+
121
+ for (const r of results || []) {
122
+ const wt = (r?.worktreePath || "").trim();
123
+ // No worktree means nothing can be resolved against it. Silently keeping
124
+ // the files would reintroduce the absolute paths that caused #81.
125
+ if (!wt) continue;
126
+
127
+ const files: string[] = [];
128
+ for (const raw of r.filesChanged || []) {
129
+ const p = String(raw).trim();
130
+ if (!p) continue;
131
+ const abs = isAbsolute(p) ? p : join(wt, p);
132
+ if (!isInside(wt, abs)) continue;
133
+ const rel = relative(wt, abs);
134
+ if (rel) files.push(rel);
135
+ }
136
+ if (files.length > 0) groups.push({ worktreePath: wt, files });
137
+ }
138
+
139
+ return groups;
140
+ }
141
+
142
+ /**
143
+ * Copy each group's files from its worktree into `projectRoot`.
144
+ *
145
+ * Throws rather than skipping when a destination would land outside
146
+ * `projectRoot`. A traversal here is not a path to sanitise away quietly — it
147
+ * means the inputs cannot be trusted, and the caller must abort the commit
148
+ * rather than proceed with a partially-collected tree.
149
+ */
150
+ export function collectWorktreeFiles(
151
+ groups: WorktreeGroup[],
152
+ projectRoot: string,
153
+ allowedWorktrees: string[],
154
+ ): CollectResult {
155
+ const copied: string[] = [];
156
+ const missing: string[] = [];
157
+
158
+ // `allowedWorktrees` is required, and an empty list authorises nothing.
159
+ // Making it optional with an "allow anything" default would restore exactly
160
+ // the hole it exists to close, in the quietest possible way.
161
+ const allowed = new Set<string>();
162
+ for (const w of allowedWorktrees || []) {
163
+ try {
164
+ allowed.add(realpathSync(resolve(w)));
165
+ } catch {
166
+ // A worktree the caller named but that does not exist authorises nothing.
167
+ }
168
+ }
169
+
170
+ for (const group of groups) {
171
+ // Every other check in this function validates a path against
172
+ // `group.worktreePath`. That value arrives from `agentResults` and is
173
+ // agent-reported, so until it is checked the containment root is chosen by
174
+ // the same party the checks defend against: `worktreePath: "/"` makes every
175
+ // file on the machine "inside the worktree". The destination stays within
176
+ // the project root, so the payload is not a write outside — it is a read of
177
+ // anything on disk INTO the repo, which the caller then stages, commits and
178
+ // pushes. Authorise the root against the caller's list before trusting it.
179
+ let realWorktree: string;
180
+ try {
181
+ realWorktree = realpathSync(resolve(group.worktreePath));
182
+ } catch {
183
+ throw new Error(`refusing an unresolvable worktree path: ${group.worktreePath}`);
184
+ }
185
+ if (!allowed.has(realWorktree)) {
186
+ throw new Error(`refusing a worktree the caller did not authorise: ${group.worktreePath}`);
187
+ }
188
+
189
+ for (const rawRel of group.files) {
190
+ // #279: an agent may annotate the path it reports — run wf_ea3e428f-64f
191
+ // wrote "lib/strip-js-comments.ts (NEW, 178 lines)" for all five of its
192
+ // files, and joining that whole string onto the worktree missed every
193
+ // one of them. 926 lines were dropped and the script exited zero.
194
+ //
195
+ // The literal entry is tried FIRST so a real path that happens to end in
196
+ // parentheses keeps working, and a genuinely missing file stays missing
197
+ // after stripping rather than becoming a second silent drop.
198
+ const stripped = stripPathAnnotation(rawRel);
199
+ const rel =
200
+ stripped !== rawRel && !existsSync(resolve(group.worktreePath, rawRel))
201
+ ? stripped
202
+ : rawRel;
203
+
204
+ const dest = resolve(projectRoot, rel);
205
+ if (!isInside(projectRoot, dest)) {
206
+ throw new Error(`refusing to write outside the project root: ${rel}`);
207
+ }
208
+
209
+ const src = resolve(group.worktreePath, rel);
210
+
211
+ // lstat, not stat: it describes the link itself rather than its target.
212
+ // copyFileSync FOLLOWS links, so a source symlink would copy a file the
213
+ // agent was never given — lexical containment cannot see that, because
214
+ // the path sits inside the worktree by string.
215
+ const st = lstatSync(src, { throwIfNoEntry: false });
216
+ if (!st) {
217
+ missing.push(src);
218
+ continue;
219
+ }
220
+ if (st.isSymbolicLink()) {
221
+ throw new Error(`refusing to collect a symlink: ${rel}`);
222
+ }
223
+ if (!st.isFile()) {
224
+ missing.push(src);
225
+ continue;
226
+ }
227
+ // A hard link defeats every check above: lstat reports a regular file and
228
+ // the path genuinely is inside the worktree, because a hard link has no
229
+ // target path to resolve — it is a second name for the same inode. Only
230
+ // the link count gives it away. Source files written by an agent have
231
+ // one name; anything else is reaching for a file it was not given.
232
+ if (st.nlink > 1) {
233
+ throw new Error(`refusing to collect a hard link: ${rel}`);
234
+ }
235
+ // Catches a symlinked intermediate directory (`wt/lib` -> elsewhere),
236
+ // which the lstat above cannot see because the leaf is a real file.
237
+ if (!realIsInside(group.worktreePath, src)) {
238
+ throw new Error(`refusing to read outside the worktree: ${rel}`);
239
+ }
240
+
241
+ // Same path on both sides: the agent worked directly in the project root
242
+ // (the single-agent path). copyFileSync onto itself would truncate.
243
+ if (src !== dest) {
244
+ // Check BEFORE creating anything. `mkdirSync(recursive)` used to run
245
+ // first, so a pre-existing symlink in the project root meant the
246
+ // directories had already been created outside it by the time the
247
+ // check threw — the refusal was correct and still left a side effect
248
+ // where it had no business writing. realIsInside walks up to the
249
+ // deepest existing ancestor, so it answers correctly for a path that
250
+ // does not exist yet.
251
+ if (!realIsInside(projectRoot, dirname(dest))) {
252
+ throw new Error(`destination directory escapes the project root: ${rel}`);
253
+ }
254
+ mkdirSync(dirname(dest), { recursive: true });
255
+ // And again after: mkdir resolved and created real directories, but a
256
+ // symlinked component could have been introduced between the two.
257
+ if (!realIsInside(projectRoot, dirname(dest))) {
258
+ throw new Error(`destination directory escapes the project root: ${rel}`);
259
+ }
260
+ // The leaf can be a symlink even when its directory is clean, and
261
+ // copyFileSync writes THROUGH a link to whatever it targets. Checking
262
+ // the directory alone would still let a planted link in the project
263
+ // root overwrite a file outside it.
264
+ const dst = lstatSync(dest, { throwIfNoEntry: false });
265
+ if (dst?.isSymbolicLink()) {
266
+ throw new Error(`refusing to overwrite a symlink in the project root: ${rel}`);
267
+ }
268
+ if (dst && !dst.isFile()) {
269
+ throw new Error(`refusing to overwrite a non-regular file: ${rel}`);
270
+ }
271
+ // Same inode trick on the destination side: copyFileSync writes
272
+ // through a hard link into whatever else shares the inode.
273
+ if (dst && dst.nlink > 1) {
274
+ throw new Error(`refusing to overwrite a hard link: ${rel}`);
275
+ }
276
+ copyFileSync(src, dest);
277
+ }
278
+ copied.push(relative(projectRoot, dest));
279
+ }
280
+ }
281
+
282
+ return { copied: [...new Set(copied)], missing };
283
+ }
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Worktree isolation — creates and cleans up git worktrees
3
+ * for test-brief agent spawning.
4
+ *
5
+ * Agent runs in a git worktree with throwaway writes.
6
+ * Transcript file persists outside the worktree for auditing.
7
+ *
8
+ * SC-407: Worktree isolation mechanism
9
+ */
10
+
11
+ import { existsSync, mkdirSync } from "fs";
12
+ import { join } from "path";
13
+ import { spawnSync } from "child_process";
14
+
15
+ export interface WorktreeConfig {
16
+ projectRoot: string;
17
+ branchPrefix?: string;
18
+ transcriptDir?: string;
19
+ }
20
+
21
+ export interface WorktreeResult {
22
+ worktreePath: string;
23
+ branchName: string;
24
+ transcriptDir: string;
25
+ cleanup: () => void;
26
+ }
27
+
28
+ /**
29
+ * Create an isolated git worktree for agent testing.
30
+ * Transcript directory is created outside the worktree so it persists after cleanup.
31
+ */
32
+ export function createWorktree(config: WorktreeConfig): WorktreeResult {
33
+ const { projectRoot, branchPrefix = "test-brief" } = config;
34
+
35
+ const id = `${branchPrefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
36
+ const branchName = id;
37
+ const worktreePath = join(projectRoot, ".claude", "worktrees", id);
38
+
39
+ // Transcript dir persists outside worktree
40
+ const transcriptDir = config.transcriptDir || join(projectRoot, ".rungate", "test-brief-transcripts", id);
41
+ if (!existsSync(transcriptDir)) {
42
+ mkdirSync(transcriptDir, { recursive: true });
43
+ }
44
+
45
+ // Create worktree
46
+ const result = spawnSync("git", ["worktree", "add", "-b", branchName, worktreePath, "HEAD"], {
47
+ cwd: projectRoot,
48
+ timeout: 30_000,
49
+ encoding: "utf-8",
50
+ });
51
+
52
+ if (result.status !== 0) {
53
+ throw new Error(`Failed to create worktree: ${result.stderr}`);
54
+ }
55
+
56
+ return {
57
+ worktreePath,
58
+ branchName,
59
+ transcriptDir,
60
+ cleanup() {
61
+ removeWorktree(projectRoot, worktreePath, branchName);
62
+ },
63
+ };
64
+ }
65
+
66
+ /**
67
+ * Remove a git worktree and its branch.
68
+ * Internal — use WorktreeResult.cleanup() instead.
69
+ */
70
+ function removeWorktree(projectRoot: string, worktreePath: string, branchName: string): void {
71
+ spawnSync("git", ["worktree", "remove", "--force", worktreePath], {
72
+ cwd: projectRoot,
73
+ timeout: 15_000,
74
+ encoding: "utf-8",
75
+ });
76
+
77
+ spawnSync("git", ["branch", "-D", branchName], {
78
+ cwd: projectRoot,
79
+ timeout: 5_000,
80
+ encoding: "utf-8",
81
+ });
82
+ }
package/package.json CHANGED
@@ -1,31 +1,53 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.2.1",
3
+ "version": "0.3.0",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/hornjason/pai-harness.git"
9
+ },
10
+ "homepage": "https://github.com/hornjason/pai-harness#readme",
11
+ "bugs": {
12
+ "url": "https://github.com/hornjason/pai-harness/issues"
13
+ },
6
14
  "files": [
15
+ "bin/",
7
16
  "lib/",
8
17
  "prompts/",
9
18
  "scripts/scaffold-project.ts",
10
19
  "scripts/extract-constraints.ts",
20
+ "scripts/convert-spec.ts",
11
21
  "scripts/sync-spec-tests.ts",
12
22
  "scripts/generate-code-map.ts",
23
+ "scripts/audit-specs.ts",
24
+ "scripts/create-spec.ts",
25
+ "scripts/create-sc.ts",
13
26
  "package.json"
14
27
  ],
15
28
  "exports": {
16
29
  "./lib/conformity": "./lib/conformity.ts",
17
30
  "./lib/rungate-schema": "./lib/rungate-schema.ts",
18
- "./lib/signal-phrases": "./lib/signal-phrases.ts"
31
+ "./lib/signal-phrases": "./lib/signal-phrases.ts",
32
+ "./lib/compliance": "./lib/compliance.ts",
33
+ "./scripts/audit-specs": "./scripts/audit-specs.ts"
19
34
  },
20
35
  "scripts": {
21
36
  "test": "bun test",
37
+ "posttest": "bun scripts/sync-sc-status.ts",
38
+ "sync-scs": "bun scripts/sync-sc-status.ts",
22
39
  "test:structure": "bun test test/structure.test.ts",
23
40
  "test:external-deps": "bun test test/external-deps.test.ts"
24
41
  },
25
42
  "dependencies": {
43
+ "@octokit/rest": "^22.0.1",
44
+ "acorn": "^8.19.0",
26
45
  "zod": "^3.23.0"
27
46
  },
28
47
  "devDependencies": {
29
48
  "@types/bun": "latest"
49
+ },
50
+ "bin": {
51
+ "rungate": "bin/rungate.ts"
30
52
  }
31
53
  }
@@ -1,3 +1,10 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-20
6
+ ---
7
+
1
8
  You are an adversarial AC reviewer. Your objective: find ways to pass
2
9
  every AC without actually fixing the bug.
3
10
 
@@ -10,11 +17,16 @@ For each AC, answer:
10
17
 
11
18
  Output as JSON:
12
19
  {
13
- "gameable": <number of gameable ACs>,
14
- "approved": <true if 0 gameable>,
20
+ "gameable": NUMBER_OF_GAMEABLE_ACS,
21
+ "approved": true_IF_0_GAMEABLE,
15
22
  "exploits": [
16
23
  {"acId": "SC-1", "exploit": "how to pass without fixing", "recommendation": "how to tighten"}
17
24
  ]
18
25
  }
19
26
 
20
27
  If ALL ACs are robust, output: {"gameable": 0, "approved": true, "exploits": []}
28
+
29
+ ### Never
30
+ - Never approve ACs where the evidence command can be passed by code that doesn't fix the stated problem
31
+ - Never accept self-attestation ("I verified it works") as a valid evidence method
32
+ - Never rate a structural check (file exists, grep count) as equivalent to a behavioral check (runtime output)
package/prompts/aditi.md CHANGED
@@ -27,3 +27,8 @@ You are Aditi Sharma, UI/UX designer. Specify component layouts and interaction
27
27
  ### Constraints
28
28
  - Use existing design system components first
29
29
  - shadcn/ui as component library baseline
30
+
31
+ ### Never
32
+ - Never skip accessibility requirements — every component spec must include ARIA roles and keyboard navigation
33
+ - Never ignore existing design system components in favor of custom elements — check shadcn/ui first
34
+ - Never deliver a component spec without error states and loading states
@@ -27,3 +27,8 @@ filesRead >= filesChanged — you must read more than you change.
27
27
  ### Gate enforcement
28
28
  - Read-before-write ratio >= 3:1 (read tokens / write tokens)
29
29
  - Files changed outside brief's listed files = WARN
30
+
31
+ ### Never
32
+ - Never change files not listed in the brief without explicit scope expansion approval
33
+ - Never skip reading dependent files before modifying their imports — downstream breakage is the most common blast-radius failure
34
+ - Never proceed when filesChanged > filesRead — stop and read more
@@ -26,3 +26,8 @@ After container-rebuild completes — before declaring deploy success.
26
26
  - Container HEAD: {sha}
27
27
  - Health: {response}
28
28
  - Failures: [list or "none"]
29
+
30
+ ### Never
31
+ - Never skip the health endpoint check — a running container is not the same as a healthy container
32
+ - Never declare container verified without completing smoke tests on critical endpoints
33
+ - Never report "verified" when the container HEAD doesn't match the expected commit SHA
@@ -25,3 +25,7 @@ DISCOVERY phase of ship cycle — before writing any code.
25
25
  - Key constraints discovered
26
26
  - Files that will be touched
27
27
  - Risks or unknowns to flag
28
+
29
+ ### Never
30
+ - Never write code before completing the discovery read list — implementation without context produces scope violations
31
+ - Never skip reading AGENTS.md — it contains project identity, constraints, and commands that govern all work
@@ -26,3 +26,8 @@ Ship DISCOVERY phase — after reading docs, before coding.
26
26
  - Environment: ready / blocked
27
27
  - Baseline test results: N pass, N fail
28
28
  - Blockers: [list or "none"]
29
+
30
+ ### Never
31
+ - Never skip environment verification and proceed directly to coding — a broken baseline wastes the entire session
32
+ - Never assume dependencies are installed — run the checks and capture actual output
33
+ - Never report "ready" with failing type checks or missing env vars
@@ -29,3 +29,8 @@ Gate enforcement — maps evidence types to tiers per AC type.
29
29
  - UI → B (browser verification)
30
30
  - BUG-FIX → S (negative control)
31
31
  - Static analysis → C supplementary only
32
+
33
+ ### Never
34
+ - Never accept tier F (self-attestation) evidence for any AC — it is always rejected
35
+ - Never mix evidence tiers to inflate a verdict — the weakest piece of evidence governs the tier
36
+ - Never use static grep (tier D) as the sole evidence for more than 25% of ACs
@@ -1,3 +1,10 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-20
6
+ ---
7
+
1
8
  You are an evidence validator. Your objective: run evidence commands
2
9
  independently and report whether results meet AC thresholds.
3
10
 
@@ -20,3 +27,7 @@ Report as JSON:
20
27
 
21
28
  Do not infer, assume, or extrapolate. If the command fails to run,
22
29
  verdict is FAIL with the error message as rawOutput.
30
+
31
+ ### Never
32
+ - Never infer or extrapolate evidence from partial command output — if the command didn't produce a clear result, verdict is FAIL
33
+ - Never modify source code — you run in a read-only worktree and exist solely to validate evidence
package/prompts/marcus.md CHANGED
@@ -27,3 +27,8 @@ You are Marcus Webb, principal engineer. You implement code changes, write tests
27
27
 
28
28
  ### Report format
29
29
  For each AC, provide evidence: file:line, grep output, or test result.
30
+
31
+ ### Never
32
+ - Never skip reading AGENTS.md as the first action — it contains project constraints that govern implementation
33
+ - Never report done without running the full test suite and capturing pass/fail counts
34
+ - Never implement without writing a failing test first (TDD is mandatory)
@@ -24,3 +24,8 @@ After identifying root cause — before implementing the fix.
24
24
  ### Example
25
25
  Bad: `if (x) doThing(x)` — fixes one caller
26
26
  Good: `function doThing(x: NonNullable<T>)` — prevents all callers
27
+
28
+ ### Never
29
+ - Never fix only the immediate instance without auditing sibling files for the same pattern
30
+ - Never skip the regression test — a fix without a test that would have caught it is incomplete
31
+ - Never add a guard without narrowing the type — runtime checks that the compiler can't enforce will recur
@@ -1,3 +1,10 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-20
6
+ ---
7
+
1
8
  You are a prove reproducer. Your objective: reproduce the bug described
2
9
  in the issue, verify the fix works, and capture evidence.
3
10
 
@@ -41,3 +48,8 @@ Verdict rules:
41
48
  - PROVEN: bug was reproduced in before-state AND fix verified in after-state
42
49
  - UNPROVEN: fix does not resolve the issue (evidence shows problem persists)
43
50
  - INCONCLUSIVE: could not reproduce the bug or connect to dev server
51
+
52
+ ### Never
53
+ - Never claim UI verification without browser tools — output SKIP with reason "no browser tools — requires Quinn"
54
+ - Never infer evidence — every verdict needs captured command output, API response, or grep result
55
+ - Never report PROVEN without both reproducing the bug in before-state AND verifying the fix in after-state
@@ -29,3 +29,8 @@ Embedded in Quinn's brief — referenced during journey execution.
29
29
  ### Circuit breaker
30
30
  3 consecutive FAIL steps → abort journey, report partial results.
31
31
  Max 8 steps per journey — split longer flows.
32
+
33
+ ### Never
34
+ - Never skip pre-conditions — if the page isn't loaded or shows errors, report FAIL immediately without testing ACs
35
+ - Never report PASS without a11y snapshot or screenshot evidence backing the assertion
36
+ - Never use screenshots as the primary assertion method — browser_snapshot (a11y tree) is always primary
@@ -93,6 +93,11 @@ Overall: PASS | FAIL
93
93
  {If FAIL: blocking issues listed}
94
94
  ```
95
95
 
96
+ ### Never
97
+ - Never guess URLs — always use the pages map from rungate.json for target URLs
98
+ - Never skip viewport setup (browser_resize) before testing — assertions against wrong viewport produce false passes
99
+ - Never report PASS without attaching snapshot or screenshot evidence for each AC
100
+
96
101
  ## Interpolation Variables
97
102
 
98
103
  | Variable | Source |
package/prompts/quinn.md CHANGED
@@ -27,3 +27,8 @@ Each step: action → wait_for → assertion → on_fail
27
27
 
28
28
  ### Circuit breaker
29
29
  3 consecutive FAIL steps → abort journey with partial results.
30
+
31
+ ### Never
32
+ - Never trust prior test results — always run fresh browser assertions in the current state
33
+ - Never skip anti-checks even when all AC journey steps pass
34
+ - Never report PASS without snapshot or screenshot evidence attached
package/prompts/rca.md CHANGED
@@ -26,3 +26,8 @@ Marcus brief for bug-fix issues — required RCA section.
26
26
  3. Identify the exact line where behavior diverges from expected
27
27
  4. State root cause as "X happens because Y at file:line"
28
28
  5. Predict the fix outcome before implementing
29
+
30
+ ### Never
31
+ - Never implement a fix without first reproducing the bug — an unreproduced bug means you're guessing at root cause
32
+ - Never skip the prediction step — state what will happen after the fix before implementing it
33
+ - Never fix at the symptom level when the root cause is upstream in the data flow
@@ -28,3 +28,7 @@ Read-to-write ratio >= 3:1 (measured in tokens).
28
28
 
29
29
  ### Gate check
30
30
  `readTokens / writeTokens >= 3.0` — FAIL if under.
31
+
32
+ ### Never
33
+ - Never write code before reading at least 3x the tokens you plan to write — the gate enforces this mechanically
34
+ - Never skip reading dependency files that import the files you'll change — downstream breakage from unread dependents is the top failure mode
@@ -24,3 +24,8 @@ After implementing a fix — before marking AC complete.
24
24
  ### Gate enforcement
25
25
  - Test count post >= test count pre — decrease = FAIL
26
26
  - Zero test removals without explicit rationale
27
+
28
+ ### Never
29
+ - Never delete existing tests to make a new fix pass — test removals require explicit rationale
30
+ - Never skip the negative control (reverting the fix to confirm the test fails without it)
31
+ - Never write a test that covers only the symptom — test the root cause
package/prompts/serena.md CHANGED
@@ -26,3 +26,8 @@ You are Serena Blackwood, architect. Evaluate structural decisions before implem
26
26
 
27
27
  ### Output
28
28
  ADR recommendation or architecture approval with cited file:line evidence.
29
+
30
+ ### Never
31
+ - Never approve shallow wrappers that add indirection without information hiding — demand deep modules
32
+ - Never skip contract test coverage for shared interfaces — untested contracts break silently at integration
33
+ - Never approve an architectural change without citing file:line evidence from the current codebase