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,269 @@
1
+ /**
2
+ * Blank every comment in a JavaScript/TypeScript source, leaving string,
3
+ * template and regex contents alone (#273).
4
+ *
5
+ * ## Why this exists
6
+ *
7
+ * Six phase-ordering assertions in `test/spec-compliance.test.ts` located
8
+ * their anchors with `indexOf` over the raw text of `workflows/ship.js`, and
9
+ * five of the eight strings they searched for occur ONLY inside comments —
10
+ * `PHASE 5: VALIDATE` is a banner, `create-pr` is a note about a step. Three
11
+ * of the six therefore compared one comment to another. Deleting the PR step
12
+ * out of `ship.js` while leaving its comment in place left all six green
13
+ * against a harness with zero `pr-upsert` call sites. That is the third shape
14
+ * `.claude/rules/checks-must-be-able-to-fail.md` names: a detector narrower
15
+ * than what it detects, here narrowed to text that is not code at all.
16
+ *
17
+ * ## The one property callers depend on
18
+ *
19
+ * **Offsets are preserved.** Every comment character is replaced by a space —
20
+ * newlines are kept — so the output has the same length, the same line count,
21
+ * and the same byte offsets as the input. Two things follow, and both are
22
+ * load-bearing:
23
+ *
24
+ * - An ordering comparison over the stripped copy is directly comparable to
25
+ * one over the raw copy; nothing shifts.
26
+ * - `stripped.slice(i, i + anchor.length) === anchor` is an exact answer to
27
+ * "is the anchor at offset `i` code or comment?", which is how the anchor
28
+ * audit in `test/ship-phase-ordering-mutation.test.ts` classifies every
29
+ * remaining anchor in the suite rather than asserting a claim about them.
30
+ *
31
+ * ## What it is not
32
+ *
33
+ * Not a parser. It is a scanner over five contexts — code, line comment,
34
+ * block comment, quoted string, template literal (with `${}` interpolations
35
+ * nested to any depth) — plus the standard previous-token heuristic for
36
+ * telling a regex literal from a division. The heuristic's known blind spot
37
+ * is `)` followed by `/`, which is read as division; no such construct exists
38
+ * in the files this is pointed at, and `test/strip-js-comments.test.ts`
39
+ * asserts the outcome on the real file rather than trusting the scanner.
40
+ */
41
+
42
+ /** Characters after which a `/` starts a regex literal rather than a division. */
43
+ const REGEX_ALLOWED_AFTER = new Set([
44
+ "", "(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "+", "-", "*", "%", "<", ">", "~", "^", "\n",
45
+ ]);
46
+
47
+ /** Keywords after which a `/` starts a regex literal. */
48
+ const REGEX_ALLOWED_AFTER_WORD = new Set([
49
+ "return", "typeof", "instanceof", "in", "of", "new", "delete", "void",
50
+ "case", "do", "else", "yield", "await", "throw",
51
+ ]);
52
+
53
+ type Ctx = { kind: "code" | "template"; depth: number };
54
+
55
+ export interface StripOptions {
56
+ /**
57
+ * Also blank the CONTENTS of every string, template and regex literal,
58
+ * keeping their delimiters and every offset (#254).
59
+ *
60
+ * Off by default, because the token a caller is looking for usually lives
61
+ * inside a literal: `workflows/ship.js` is mostly prompts, and `pr-upsert` is
62
+ * a command inside one.
63
+ *
64
+ * On, the result is the view a BRACE MATCHER may count over, and nothing
65
+ * else. `${WORK_DIR}`, `{rebuild:'SKIP'}` and a JSON example in a prompt all
66
+ * carry braces that are text, and a matcher run over the comment-stripped
67
+ * copy closes `if (containerConfig) {` in the middle of a prompt — which is
68
+ * how a call site trapped inside an arm measures as outside it.
69
+ *
70
+ * The braces of a `${ … }` interpolation go with the literal; the CODE inside
71
+ * one is left alone, because its braces are necessarily balanced and so
72
+ * cannot move a match. Offsets are preserved exactly as without the option,
73
+ * which is what makes one view's index comparable to the other's range.
74
+ */
75
+ blankLiterals?: boolean;
76
+ }
77
+
78
+ export function stripJsComments(src: string, opts: StripOptions = {}): string {
79
+ const blankLiterals = opts.blankLiterals === true;
80
+ const out = src.split("");
81
+ const n = src.length;
82
+ const stack: Ctx[] = [{ kind: "code", depth: 0 }];
83
+
84
+ // Last significant code character and last identifier, for regex detection.
85
+ let prevSig = "";
86
+ let prevWord = "";
87
+
88
+ const blank = (from: number, to: number) => {
89
+ for (let k = from; k < to && k < n; k++) if (out[k] !== "\n") out[k] = " ";
90
+ };
91
+
92
+ let i = 0;
93
+ while (i < n) {
94
+ const top = stack[stack.length - 1];
95
+ const c = src[i];
96
+ const d = i + 1 < n ? src[i + 1] : "";
97
+
98
+ if (top.kind === "template") {
99
+ if (c === "\\") { if (blankLiterals) blank(i, i + 2); i += 2; continue; }
100
+ if (c === "`") { stack.pop(); prevSig = "`"; prevWord = ""; i++; continue; }
101
+ if (c === "$" && d === "{") {
102
+ // The interpolation's own braces belong to the literal; the code
103
+ // between them does not, and is left intact.
104
+ if (blankLiterals) blank(i, i + 2);
105
+ stack.push({ kind: "code", depth: 0 });
106
+ prevSig = "{"; prevWord = "";
107
+ i += 2;
108
+ continue;
109
+ }
110
+ if (blankLiterals) blank(i, i + 1);
111
+ i++;
112
+ continue;
113
+ }
114
+
115
+ // ── code context ──
116
+ if (c === "/" && d === "/") {
117
+ let j = i;
118
+ while (j < n && src[j] !== "\n") j++;
119
+ blank(i, j);
120
+ i = j;
121
+ continue;
122
+ }
123
+ if (c === "/" && d === "*") {
124
+ let j = i + 2;
125
+ while (j < n && !(src[j] === "*" && src[j + 1] === "/")) j++;
126
+ j = Math.min(n, j + 2);
127
+ blank(i, j);
128
+ i = j;
129
+ continue;
130
+ }
131
+ if (c === "'" || c === '"') {
132
+ let j = i + 1;
133
+ let closed = false;
134
+ while (j < n) {
135
+ if (src[j] === "\\") { j += 2; continue; }
136
+ if (src[j] === c) { j++; closed = true; break; }
137
+ // An unterminated string would otherwise swallow the rest of the file
138
+ // and silently disable the whole stripper — a fail-open.
139
+ if (src[j] === "\n") break;
140
+ j++;
141
+ }
142
+ // Contents, not delimiters. The quotes stay so the surrounding code still
143
+ // reads as code, and an unterminated string blanks only as far as the
144
+ // scanner actually got.
145
+ if (blankLiterals) blank(i + 1, closed ? j - 1 : j);
146
+ prevSig = c; prevWord = "";
147
+ i = j;
148
+ continue;
149
+ }
150
+ if (c === "`") {
151
+ stack.push({ kind: "template", depth: 0 });
152
+ i++;
153
+ continue;
154
+ }
155
+ if (c === "{") { top.depth++; prevSig = "{"; prevWord = ""; i++; continue; }
156
+ if (c === "}") {
157
+ if (top.depth === 0 && stack.length > 1) {
158
+ // Closes a `${ … }` interpolation; the enclosing template resumes. It
159
+ // is the literal's brace, so it goes wherever its `${` went.
160
+ if (blankLiterals) blank(i, i + 1);
161
+ stack.pop();
162
+ } else {
163
+ top.depth--;
164
+ }
165
+ prevSig = "}"; prevWord = "";
166
+ i++;
167
+ continue;
168
+ }
169
+ if (c === "/") {
170
+ const regex = prevWord
171
+ ? REGEX_ALLOWED_AFTER_WORD.has(prevWord)
172
+ : REGEX_ALLOWED_AFTER.has(prevSig);
173
+ if (regex) {
174
+ let j = i + 1;
175
+ let inClass = false;
176
+ let closed = false;
177
+ let endSlash = -1;
178
+ while (j < n) {
179
+ const ch = src[j];
180
+ if (ch === "\\") { j += 2; continue; }
181
+ if (ch === "\n") break;
182
+ if (inClass) { if (ch === "]") inClass = false; }
183
+ else if (ch === "[") inClass = true;
184
+ else if (ch === "/") { endSlash = j; j++; closed = true; break; }
185
+ j++;
186
+ }
187
+ if (closed) {
188
+ while (j < n && /[a-z]/i.test(src[j])) j++;
189
+ // A `{` in a pattern is a quantifier or an escaped brace, never a
190
+ // block — same reason the string contents go.
191
+ if (blankLiterals) blank(i + 1, endSlash);
192
+ prevSig = "/"; prevWord = "";
193
+ i = j;
194
+ continue;
195
+ }
196
+ // Unterminated — it was a division after all.
197
+ }
198
+ prevSig = "/"; prevWord = "";
199
+ i++;
200
+ continue;
201
+ }
202
+ if (/\s/.test(c)) { i++; continue; }
203
+ if (/[A-Za-z0-9_$]/.test(c)) {
204
+ let j = i;
205
+ while (j < n && /[A-Za-z0-9_$]/.test(src[j])) j++;
206
+ prevWord = src.slice(i, j);
207
+ prevSig = src[j - 1];
208
+ i = j;
209
+ continue;
210
+ }
211
+ prevSig = c;
212
+ prevWord = "";
213
+ i++;
214
+ }
215
+
216
+ return out.join("");
217
+ }
218
+
219
+ /**
220
+ * Which offsets lie inside a comment (#360).
221
+ *
222
+ * Lives here rather than beside its caller because it is the inverse of what
223
+ * `stripJsComments` already knows, and a second scanner answering the same
224
+ * question is a second scanner to drift.
225
+ *
226
+ * The subtlety is that blanking writes a SPACE and leaves newlines alone, so
227
+ * "differs from the source" is true for a comment's words and FALSE for the
228
+ * whitespace between them. A naive maximal run therefore stops at the first
229
+ * space: the first version of #360's census read `SC-633,` as the whole
230
+ * enclosing comment, which made every comment in the repo look like a bare
231
+ * id and put 192 of 220 credits in the wrong bucket.
232
+ *
233
+ * So: mark the differing offsets, then bridge runs of whitespace that have a
234
+ * marked offset on both sides. Consecutive line comments merge into one
235
+ * block, which is the right answer for `// …\n// …` and is stated here
236
+ * because it is a choice rather than an accident.
237
+ */
238
+ export function commentMask(src: string): boolean[] {
239
+ const blanked = stripJsComments(src);
240
+ const mask = Array.from(src, (ch, i) => blanked[i] !== ch);
241
+ let i = 0;
242
+ while (i < src.length) {
243
+ if (!mask[i] && /\s/.test(src[i])) {
244
+ let j = i;
245
+ while (j < src.length && !mask[j] && /\s/.test(src[j])) j++;
246
+ if (i > 0 && mask[i - 1] && j < src.length && mask[j]) {
247
+ for (let k = i; k < j; k++) mask[k] = true;
248
+ }
249
+ i = j;
250
+ continue;
251
+ }
252
+ i++;
253
+ }
254
+ return mask;
255
+ }
256
+
257
+ /** The maximal masked run around `at`, and where in it `at` fell. */
258
+ export function enclosingComment(
259
+ src: string,
260
+ mask: boolean[],
261
+ at: number,
262
+ ): { text: string; offset: number } {
263
+ if (!mask[at]) return { text: "", offset: -1 };
264
+ let lo = at;
265
+ let hi = at;
266
+ while (lo > 0 && mask[lo - 1]) lo--;
267
+ while (hi + 1 < src.length && mask[hi + 1]) hi++;
268
+ return { text: src.slice(lo, hi + 1), offset: at - lo };
269
+ }
@@ -0,0 +1,228 @@
1
+ /**
2
+ * The suite result, and the commit it was measured against (#224).
3
+ *
4
+ * Run `wf_7ac5f614-d21` reported `{"status":"SHIPPED","regressions":0}` over
5
+ * `worktree-wf_7ac5f614-d21-9`. Checked out, that branch's suite reported one
6
+ * failing test — a guard from #149 that had caught a real regression, named
7
+ * it, and pointed at the file. The guard worked. The number the run published
8
+ * did not come from the tree being shipped, and nothing could tell, because a
9
+ * count with no commit attached cannot be checked against anything.
10
+ *
11
+ * Two facts have to be inseparable for that to be detectable:
12
+ *
13
+ * 1. A suite result carries the SHA it was measured against. A count on its
14
+ * own is not evidence; it is a number whose provenance was discarded.
15
+ * 2. The absence of a result is its own verdict. "Nobody measured" and "it
16
+ * measured clean" serialise to the same object as soon as a missing
17
+ * record is allowed to default to zero failures — which is the shape of
18
+ * every fail-open in .claude/rules/checks-must-be-able-to-fail.md.
19
+ *
20
+ * So this module has three verdicts, not two, and UNMEASURED is the one it
21
+ * reaches for whenever it cannot positively establish both facts. Nothing here
22
+ * throws: it is read on the path that decides whether a run may ship, and a
23
+ * throw is a refusal the caller's error handling can turn back into a ship.
24
+ */
25
+
26
+ /** A commit SHA: 7-40 hex, case-insensitive. Normalised to lowercase. */
27
+ const SHA = /^[0-9a-f]{7,40}$/i;
28
+
29
+ /**
30
+ * UNMEASURED is not a result. It is the statement that this run has no suite
31
+ * evidence, and it is deliberately not writable — see gates/schema.ts, which
32
+ * accepts PASS and FAIL only. A recorded UNMEASURED would be a measurement
33
+ * saying there was no measurement.
34
+ */
35
+ export type SuiteVerdict = "PASS" | "FAIL" | "UNMEASURED";
36
+
37
+ /** What a recorder persists at `suiteMeasurement` in workflow-state.json. */
38
+ export interface SuiteMeasurement {
39
+ verdict: "PASS" | "FAIL";
40
+ /** The commit the suite actually ran against. */
41
+ measuredSha: string;
42
+ /** Failing tests. 0 for a PASS, at least 1 for a FAIL. */
43
+ failures: number;
44
+ measuredAt?: string;
45
+ }
46
+
47
+ export interface SuiteReading {
48
+ verdict: SuiteVerdict;
49
+ /**
50
+ * The failing-test count, or null when the suite was not measured.
51
+ *
52
+ * null rather than 0 on purpose. 0 is the answer a consumer adds up, and
53
+ * "no failures recorded" counting as "no failures" is the whole of #224.
54
+ */
55
+ failures: number | null;
56
+ /** The commit the count describes, or null when there isn't one. */
57
+ measuredSha: string | null;
58
+ /** Why the reading is UNMEASURED. Null — and only null — when it is not. */
59
+ reason: string | null;
60
+ }
61
+
62
+ /**
63
+ * The SHA a measurement is pinned to, or null.
64
+ *
65
+ * Returning null rather than a fallback is the point: there is no safe default
66
+ * commit for a suite result, and "it must have been HEAD" is the assumption
67
+ * that let an unpinned count stand in for a measured one.
68
+ */
69
+ export function suiteMeasurementSha(value: unknown): string | null {
70
+ if (typeof value !== "string") return null;
71
+ const trimmed = value.trim();
72
+ return SHA.test(trimmed) ? trimmed.toLowerCase() : null;
73
+ }
74
+
75
+ function isRecord(v: unknown): v is Record<string, unknown> {
76
+ return typeof v === "object" && v !== null && !Array.isArray(v);
77
+ }
78
+
79
+ function describe(v: unknown): string {
80
+ if (v === undefined) return "nothing";
81
+ if (v === null) return "null";
82
+ if (Array.isArray(v)) return `an array of ${v.length}`;
83
+ if (typeof v === "object") return "an object";
84
+ // Symbols and functions stringify to undefined, which would read as a hole
85
+ // in the message rather than as a description of the value.
86
+ return JSON.stringify(v) ?? String(v);
87
+ }
88
+
89
+ function unmeasured(reason: string): SuiteReading {
90
+ return { verdict: "UNMEASURED", failures: null, measuredSha: null, reason };
91
+ }
92
+
93
+ /**
94
+ * Resolve the suite verdict carried by a workflow state.
95
+ *
96
+ * FAILS CLOSED EVERYWHERE. A state that is not an object, a missing record, a
97
+ * record with no SHA, a malformed SHA, a count that is not a count, a verdict
98
+ * nobody recognises, and a verdict its own count contradicts all return
99
+ * UNMEASURED. Each of those is the absence of a usable measurement, and the
100
+ * one thing this function may never do is turn an absence into a PASS.
101
+ *
102
+ * The contradiction cases are here rather than left to the schema because the
103
+ * schema guards the write path only. A file edited by hand, produced by an
104
+ * older harness, or merged from somewhere else reaches this function without
105
+ * ever passing through writeWorkflowState, and `{"verdict":"PASS",
106
+ * "failures":3}` is not a result anyone can act on in either direction.
107
+ */
108
+ export function readSuiteMeasurement(state: unknown): SuiteReading {
109
+ if (!isRecord(state)) {
110
+ return unmeasured(
111
+ `the suite was not measured: the workflow state is ${describe(state)}, so it carries no suite result`,
112
+ );
113
+ }
114
+
115
+ const raw = state.suiteMeasurement;
116
+ if (!isRecord(raw)) {
117
+ return unmeasured(
118
+ `the suite was not measured: workflow-state.json has no suiteMeasurement record (got ${describe(raw)}) — ` +
119
+ `no run of the suite has been bound to a commit, so there is no failure count to read`,
120
+ );
121
+ }
122
+
123
+ const measuredSha = suiteMeasurementSha(raw.measuredSha);
124
+ if (!measuredSha) {
125
+ return unmeasured(
126
+ `the suite measurement is not bound to a commit: measuredSha is ${describe(raw.measuredSha)}, not a ` +
127
+ `commit SHA — a count that cannot be checked against the tree being shipped is not evidence (#224)`,
128
+ );
129
+ }
130
+
131
+ const failures = raw.failures;
132
+ if (typeof failures !== "number" || !Number.isInteger(failures) || failures < 0) {
133
+ return unmeasured(
134
+ `the suite measurement for ${measuredSha} has no usable failure count (got ${describe(failures)})`,
135
+ );
136
+ }
137
+
138
+ const verdict = raw.verdict;
139
+ if (verdict !== "PASS" && verdict !== "FAIL") {
140
+ return unmeasured(
141
+ `the suite measurement for ${measuredSha} carries no usable verdict (got ${describe(verdict)}) — ` +
142
+ `only PASS and FAIL are results; anything else means the suite was not measured`,
143
+ );
144
+ }
145
+
146
+ if (verdict === "PASS" && failures > 0) {
147
+ return unmeasured(
148
+ `the suite measurement for ${measuredSha} contradicts itself: PASS with ${failures} failing test(s) — ` +
149
+ `refusing to read it as either result`,
150
+ );
151
+ }
152
+ if (verdict === "FAIL" && failures === 0) {
153
+ return unmeasured(
154
+ `the suite measurement for ${measuredSha} contradicts itself: FAIL with no failing tests — ` +
155
+ `refusing to read it as either result`,
156
+ );
157
+ }
158
+
159
+ return { verdict, failures, measuredSha, reason: null };
160
+ }
161
+
162
+ /**
163
+ * Whether a suite reading is about the commit a run is shipping.
164
+ *
165
+ * Two failures, two words, deliberately not collapsed into one:
166
+ *
167
+ * - `STALE` — the suite WAS measured, against a commit the branch has since
168
+ * moved past. A contradiction the run can name, and a hard refusal: a count
169
+ * predating the final commit cannot satisfy a gate.
170
+ * - `UNRECORDED` — nothing usable was written down. An absence, not a
171
+ * contradiction. It must never read as clean, but aborting every run that
172
+ * has not recorded a SHA yet would brick the harness, so it resolves to an
173
+ * UNMEASURED reading and caps the terminal status instead.
174
+ *
175
+ * An abbreviation matches in either direction: `measuredSha` arrives through
176
+ * an agent reading workflow-state.json and `headSha` from `git rev-parse`, so
177
+ * either may be short.
178
+ */
179
+ export type SuiteCurrencyState = "CURRENT" | "STALE" | "UNRECORDED";
180
+
181
+ export interface SuiteCurrency {
182
+ state: SuiteCurrencyState;
183
+ /** Why the reading is not CURRENT. Null — and only null — when it is. */
184
+ reason: string | null;
185
+ }
186
+
187
+ /**
188
+ * FAILS CLOSED, and never throws, for the same reason as the rest of this
189
+ * module: it decides whether a run may ship, and a throw is a refusal the
190
+ * caller's error handling could turn back into a ship.
191
+ *
192
+ * `workflows/ship.js` carries an INLINED COPY of this function inside
193
+ * `SUITE-CURRENCY` markers — the Workflow sandbox has no module loading and a
194
+ * top-level require() there killed every ship run before it spawned an agent
195
+ * (#69). This is the source of truth; the copy is held to it by
196
+ * test/suite-measurement-parity.test.ts, which extracts the block, executes
197
+ * it, and drives both over one input matrix. Change one, change the other.
198
+ */
199
+ export function suiteCurrency(measuredSha: unknown, headSha: unknown): SuiteCurrency {
200
+ const measured = suiteMeasurementSha(measuredSha);
201
+ const head = suiteMeasurementSha(headSha);
202
+
203
+ if (!measured) {
204
+ return {
205
+ state: "UNRECORDED",
206
+ reason:
207
+ `the suite result records ${describe(measuredSha)} as the commit it was ` +
208
+ `measured against, which is not a commit SHA — a count with no SHA is not evidence`,
209
+ };
210
+ }
211
+ if (!head) {
212
+ return {
213
+ state: "UNRECORDED",
214
+ reason:
215
+ `the branch tip read at ship time is ${describe(headSha)}, not a commit SHA, ` +
216
+ `so the suite result measured against ${measured} cannot be confirmed against it`,
217
+ };
218
+ }
219
+ if (!(measured.startsWith(head) || head.startsWith(measured))) {
220
+ return {
221
+ state: "STALE",
222
+ reason:
223
+ `the suite result is stale: it was measured against ${measured} but the branch now ends ` +
224
+ `at ${head} — the count did not come from the tree this run would ship`,
225
+ };
226
+ }
227
+ return { state: "CURRENT", reason: null };
228
+ }
@@ -0,0 +1,177 @@
1
+ /**
2
+ * Task Completion Quality Checks
3
+ *
4
+ * Quality gates that run before allowing task completion.
5
+ * Used by TaskCompleted hook to ensure work meets minimum standards.
6
+ *
7
+ * Issue: #579
8
+ */
9
+
10
+ import { spawnSync } from 'child_process';
11
+ import { existsSync, readFileSync } from 'fs';
12
+ import { join } from 'path';
13
+
14
+ export interface CompletionCheckResult {
15
+ passed: boolean;
16
+ blockers: string[];
17
+ warnings: string[];
18
+ }
19
+
20
+ /**
21
+ * Run test suite and check for failures.
22
+ * Returns blocker if tests fail, warning if tests can't run.
23
+ */
24
+ export function checkTests(projectRoot: string): CompletionCheckResult {
25
+ const blockers: string[] = [];
26
+ const warnings: string[] = [];
27
+
28
+ try {
29
+ const result = spawnSync('bun', ['test'], {
30
+ cwd: projectRoot,
31
+ encoding: 'utf-8',
32
+ timeout: 120000, // 2 minute timeout
33
+ });
34
+
35
+ // Parse test output for failures
36
+ // Combine stdout and stderr as bun test may use either
37
+ const output = (result.stdout || '') + (result.stderr || '');
38
+ const failMatch = output.match(/(\d+) fail/);
39
+ const passMatch = output.match(/(\d+) pass/);
40
+
41
+ // Check for failures first
42
+ if (failMatch) {
43
+ const failCount = parseInt(failMatch[1], 10);
44
+ if (failCount > 0) {
45
+ blockers.push(`Test suite has ${failCount} failing test(s). Fix failures before completing task.`);
46
+ }
47
+ }
48
+
49
+ // If exit code is non-zero, treat it as a failure even if we can't parse the output
50
+ if (result.status !== 0 && blockers.length === 0) {
51
+ // Look for test failure patterns (not just any error)
52
+ if (output.match(/\(fail\)/i) || output.match(/test.*failed/i)) {
53
+ blockers.push('Test suite failed with errors. Check test output for details.');
54
+ } else if (output.match(/no test files found/i) || output.match(/0 tests/i)) {
55
+ warnings.push('No test files found or tests defined.');
56
+ } else {
57
+ warnings.push('Test command exited with non-zero status, but no explicit failures found.');
58
+ }
59
+ }
60
+
61
+ if (passMatch) {
62
+ const passCount = parseInt(passMatch[1], 10);
63
+ if (passCount === 0 && blockers.length === 0 && result.status === 0) {
64
+ warnings.push('No tests passed — possible test suite issue.');
65
+ }
66
+ }
67
+ } catch (err) {
68
+ warnings.push(`Could not run tests: ${err instanceof Error ? err.message : String(err)}`);
69
+ }
70
+
71
+ return {
72
+ passed: blockers.length === 0,
73
+ blockers,
74
+ warnings,
75
+ };
76
+ }
77
+
78
+ /**
79
+ * Check for uncommitted changes.
80
+ * Returns warning if there are uncommitted files.
81
+ */
82
+ export function checkUncommittedChanges(projectRoot: string): CompletionCheckResult {
83
+ const warnings: string[] = [];
84
+
85
+ try {
86
+ const result = spawnSync('git', ['status', '--porcelain'], {
87
+ cwd: projectRoot,
88
+ encoding: 'utf-8',
89
+ });
90
+
91
+ const output = (result.stdout || '').trim();
92
+ if (output) {
93
+ const lines = output.split('\n');
94
+ warnings.push(`${lines.length} uncommitted file(s). Consider committing work before completing task.`);
95
+ }
96
+ } catch (err) {
97
+ // Not in a git repo or git not available — skip check
98
+ }
99
+
100
+ return {
101
+ passed: true, // Warnings don't block
102
+ blockers: [],
103
+ warnings,
104
+ };
105
+ }
106
+
107
+ /**
108
+ * Run conformity checks if rungate.json exists.
109
+ * Returns blocker if conformity fails.
110
+ */
111
+ export function checkConformity(projectRoot: string): CompletionCheckResult {
112
+ const blockers: string[] = [];
113
+ const warnings: string[] = [];
114
+
115
+ const rungateConfig = join(projectRoot, '.claude', 'rungate.json');
116
+ if (!existsSync(rungateConfig)) {
117
+ // No rungate config — skip conformity check
118
+ return { passed: true, blockers: [], warnings: [] };
119
+ }
120
+
121
+ try {
122
+ const result = spawnSync('bun', ['test', 'test/scaffold-conformity.test.ts'], {
123
+ cwd: projectRoot,
124
+ encoding: 'utf-8',
125
+ timeout: 60000, // 1 minute timeout
126
+ });
127
+
128
+ const output = result.stdout || result.stderr || '';
129
+ const failMatch = output.match(/(\d+) fail/);
130
+
131
+ if (failMatch) {
132
+ const failCount = parseInt(failMatch[1], 10);
133
+ if (failCount > 0) {
134
+ blockers.push(`Conformity check has ${failCount} failing check(s). Fix conformity issues before completing task.`);
135
+ }
136
+ }
137
+
138
+ if (result.status !== 0 && blockers.length === 0) {
139
+ warnings.push('Conformity check exited with non-zero status, but no explicit failures found.');
140
+ }
141
+ } catch (err) {
142
+ warnings.push(`Could not run conformity checks: ${err instanceof Error ? err.message : String(err)}`);
143
+ }
144
+
145
+ return {
146
+ passed: blockers.length === 0,
147
+ blockers,
148
+ warnings,
149
+ };
150
+ }
151
+
152
+ /**
153
+ * Run all completion checks and aggregate results.
154
+ */
155
+ export function runAllCompletionChecks(projectRoot: string): CompletionCheckResult {
156
+ const testResult = checkTests(projectRoot);
157
+ const gitResult = checkUncommittedChanges(projectRoot);
158
+ const conformityResult = checkConformity(projectRoot);
159
+
160
+ const allBlockers = [
161
+ ...testResult.blockers,
162
+ ...gitResult.blockers,
163
+ ...conformityResult.blockers,
164
+ ];
165
+
166
+ const allWarnings = [
167
+ ...testResult.warnings,
168
+ ...gitResult.warnings,
169
+ ...conformityResult.warnings,
170
+ ];
171
+
172
+ return {
173
+ passed: allBlockers.length === 0,
174
+ blockers: allBlockers,
175
+ warnings: allWarnings,
176
+ };
177
+ }