crysk 0.0.0-stage → 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 (229) hide show
  1. package/LICENSE +176 -0
  2. package/README.md +610 -2
  3. package/bin/pr-hero.js +166 -0
  4. package/config/models/anthropic.json +5 -0
  5. package/dist/SKILL-7e3725zn.md +496 -0
  6. package/dist/SKILL-7q35wcaz.md +66 -0
  7. package/dist/SKILL-9at22381.md +74 -0
  8. package/dist/SKILL-ex2hxxh3.md +134 -0
  9. package/dist/adjudicator-dtg2axnh.md +86 -0
  10. package/dist/admission-config.example-a9vqmmad.json +9 -0
  11. package/dist/ci-admission-camfbx2b.md +122 -0
  12. package/dist/cli.js +42292 -0
  13. package/dist/consolidate-ac0mnfyj.md +24 -0
  14. package/dist/deep-review-lifecycle-m698ybjp.md +362 -0
  15. package/dist/deep-review-logic-a6b1gczf.md +156 -0
  16. package/dist/deep-review-parity-0ec904db.md +120 -0
  17. package/dist/deep-review-reliability-qyakbjb9.md +125 -0
  18. package/dist/deep-review-resilience-3tz8y26e.md +118 -0
  19. package/dist/index.js +20190 -0
  20. package/dist/opencode-ci-7b0be64p.md +141 -0
  21. package/dist/review-refuter-j4e9gezy.md +71 -0
  22. package/dist/scout-yvp153q7.md +140 -0
  23. package/dist/summarizer-zca44nxa.md +18 -0
  24. package/dist/workflow-w1g9szna.yml +151 -0
  25. package/package.json +82 -4
  26. package/prompts/consolidate.md +24 -0
  27. package/prompts/default/PROVENANCE.md +18 -0
  28. package/prompts/default/deep-review-lifecycle.md +362 -0
  29. package/prompts/default/deep-review-logic.md +156 -0
  30. package/prompts/default/deep-review-parity.md +120 -0
  31. package/prompts/default/deep-review-reliability.md +125 -0
  32. package/prompts/default/deep-review-resilience.md +118 -0
  33. package/prompts/default/review-refuter.md +71 -0
  34. package/prompts/scout.md +140 -0
  35. package/prompts/summarizer.md +18 -0
  36. package/skills/crysk/SKILL.md +74 -0
  37. package/skills/crysk-ci-setup/SKILL.md +134 -0
  38. package/skills/crysk-ci-setup/assets/admission-config.example.json +9 -0
  39. package/skills/crysk-ci-setup/assets/workflow.yml +151 -0
  40. package/skills/crysk-ci-setup/references/ci-admission.md +122 -0
  41. package/skills/crysk-ci-setup/references/opencode-ci.md +141 -0
  42. package/skills/crysk-loop/SKILL.md +496 -0
  43. package/skills/crysk-loop/adjudicator.md +86 -0
  44. package/skills/crysk-pr/SKILL.md +66 -0
  45. package/src/agent-env.ts +1084 -0
  46. package/src/asset-manifest.ts +83 -0
  47. package/src/assets.d.ts +6 -0
  48. package/src/assets.ts +183 -0
  49. package/src/brand-paths.ts +155 -0
  50. package/src/brand.ts +255 -0
  51. package/src/ci/admission-ledger.ts +350 -0
  52. package/src/ci/classify-error.ts +73 -0
  53. package/src/ci/cli-record.ts +271 -0
  54. package/src/ci/force-comment.ts +39 -0
  55. package/src/ci/gates.ts +923 -0
  56. package/src/ci/outcome.ts +2181 -0
  57. package/src/ci/override.ts +187 -0
  58. package/src/ci/publish.ts +1639 -0
  59. package/src/ci/reporter.ts +626 -0
  60. package/src/ci/review-admission.ts +901 -0
  61. package/src/ci/review-levels.ts +310 -0
  62. package/src/ci/review-policy.ts +18 -0
  63. package/src/ci/review-risk.ts +184 -0
  64. package/src/ci/setup.ts +844 -0
  65. package/src/ci/trigger.ts +1353 -0
  66. package/src/cli.ts +348 -0
  67. package/src/commands/activity.ts +67 -0
  68. package/src/commands/ci-setup-questions.ts +397 -0
  69. package/src/commands/ci-setup.ts +381 -0
  70. package/src/commands/config.ts +99 -0
  71. package/src/commands/doctor.ts +108 -0
  72. package/src/commands/init.ts +139 -0
  73. package/src/commands/mcp.ts +10 -0
  74. package/src/commands/menu.ts +129 -0
  75. package/src/commands/post.ts +302 -0
  76. package/src/commands/skills.ts +83 -0
  77. package/src/commands/status.ts +173 -0
  78. package/src/commands/triage.ts +342 -0
  79. package/src/commands/uninstall.ts +37 -0
  80. package/src/commands/upgrade.ts +214 -0
  81. package/src/commands/usage.ts +98 -0
  82. package/src/compare/compare.ts +28 -0
  83. package/src/compare/floor-test.ts +471 -0
  84. package/src/compare/martian-adapter.ts +80 -0
  85. package/src/config/config.ts +267 -0
  86. package/src/corpus/corpus.ts +1094 -0
  87. package/src/corpus/preflight.ts +1789 -0
  88. package/src/diversity/accounting.ts +90 -0
  89. package/src/diversity/adjudication.ts +145 -0
  90. package/src/diversity/admission.ts +60 -0
  91. package/src/diversity/benchmark.ts +195 -0
  92. package/src/diversity/clustering.ts +285 -0
  93. package/src/diversity/errors.ts +7 -0
  94. package/src/diversity/identity.ts +285 -0
  95. package/src/diversity/index.ts +11 -0
  96. package/src/diversity/pipeline-integration.ts +448 -0
  97. package/src/diversity/projection.ts +57 -0
  98. package/src/diversity/self-contained.ts +68 -0
  99. package/src/diversity/target-validation.ts +179 -0
  100. package/src/doctor-migration.ts +209 -0
  101. package/src/doctor.ts +723 -0
  102. package/src/errors.ts +83 -0
  103. package/src/execution/admission.ts +75 -0
  104. package/src/execution/atomic-write.ts +35 -0
  105. package/src/execution/attempt-evidence.ts +415 -0
  106. package/src/execution/bucket-id.ts +136 -0
  107. package/src/execution/concurrency-limiter.ts +175 -0
  108. package/src/execution/contracts.ts +443 -0
  109. package/src/execution/failure-classification.ts +42 -0
  110. package/src/execution/failure-policy.ts +240 -0
  111. package/src/execution/harness.ts +2548 -0
  112. package/src/execution/settlement.ts +348 -0
  113. package/src/execution/spawned-process.ts +66 -0
  114. package/src/execution/spend-limiter.ts +424 -0
  115. package/src/execution/step-artifacts.ts +55 -0
  116. package/src/execution/usage-normalized.ts +469 -0
  117. package/src/git/git.ts +396 -0
  118. package/src/git/identity.ts +64 -0
  119. package/src/git/refs.ts +140 -0
  120. package/src/home-preflight.ts +443 -0
  121. package/src/home.ts +243 -0
  122. package/src/ignore-file.ts +336 -0
  123. package/src/ignore-read.ts +118 -0
  124. package/src/index.ts +34 -0
  125. package/src/legacy-launchd.ts +29 -0
  126. package/src/mcp/mcp.ts +150 -0
  127. package/src/mcp/preflight.ts +407 -0
  128. package/src/menu-context.ts +192 -0
  129. package/src/model/catalog.ts +251 -0
  130. package/src/model/exec-snapshots.ts +390 -0
  131. package/src/model/free-discovery.ts +302 -0
  132. package/src/model/provider-capabilities.ts +814 -0
  133. package/src/model/routing.ts +600 -0
  134. package/src/pr/admission.ts +847 -0
  135. package/src/pr/ci-admission-gate.ts +665 -0
  136. package/src/pr/ci-publish.ts +76 -0
  137. package/src/pr/discovery.ts +432 -0
  138. package/src/pr/inline.ts +507 -0
  139. package/src/pr/plan.ts +366 -0
  140. package/src/pr/posting.ts +115 -0
  141. package/src/pr/pr-status.ts +787 -0
  142. package/src/pr/pr.ts +3642 -0
  143. package/src/pr/preflight.ts +1031 -0
  144. package/src/pr/publish-outcome.ts +361 -0
  145. package/src/pr/range.ts +119 -0
  146. package/src/pr/reverts-preflight.ts +606 -0
  147. package/src/pr/reverts.ts +377 -0
  148. package/src/pr/review-pr.ts +927 -0
  149. package/src/pr/status.ts +154 -0
  150. package/src/pr/target.ts +388 -0
  151. package/src/pr/teardown.ts +437 -0
  152. package/src/pr/worktree-setup.ts +60 -0
  153. package/src/production-runtime.ts +1877 -0
  154. package/src/progress.ts +487 -0
  155. package/src/rereview/adjudicate.ts +89 -0
  156. package/src/rereview/classify.ts +362 -0
  157. package/src/rereview/identity.ts +211 -0
  158. package/src/rereview/plan.ts +308 -0
  159. package/src/rereview/prepare.ts +1025 -0
  160. package/src/rereview/state.ts +767 -0
  161. package/src/rereview/verify.ts +241 -0
  162. package/src/review/boundary.ts +105 -0
  163. package/src/review/consolidate.ts +246 -0
  164. package/src/review/dedupe.ts +368 -0
  165. package/src/review/drafts.ts +448 -0
  166. package/src/review/findings-conformance.ts +120 -0
  167. package/src/review/findings.ts +714 -0
  168. package/src/review/pipeline.ts +3977 -0
  169. package/src/review/preflight.ts +3575 -0
  170. package/src/review/prompt-set.ts +177 -0
  171. package/src/review/proof-refs.ts +187 -0
  172. package/src/review/report.ts +1821 -0
  173. package/src/review/review.ts +490 -0
  174. package/src/review/root-cause.ts +120 -0
  175. package/src/review/route-preflight.ts +289 -0
  176. package/src/review/run.ts +601 -0
  177. package/src/review/scout.ts +323 -0
  178. package/src/review/size-gate.ts +595 -0
  179. package/src/review/spec.ts +235 -0
  180. package/src/review/step-runner.ts +233 -0
  181. package/src/runner-authority.ts +596 -0
  182. package/src/security/binding-policy.ts +115 -0
  183. package/src/security/credential-broker.ts +773 -0
  184. package/src/security/evidence-redaction.ts +62 -0
  185. package/src/security/execution-authority.ts +27 -0
  186. package/src/security/redact.ts +71 -0
  187. package/src/security/workspace-read-broker.ts +466 -0
  188. package/src/server/client.ts +190 -0
  189. package/src/server/preflight.ts +217 -0
  190. package/src/server/server.ts +327 -0
  191. package/src/signal-handler.ts +50 -0
  192. package/src/store/activity.ts +413 -0
  193. package/src/store/backfill-preflight.ts +49 -0
  194. package/src/store/backfill.ts +141 -0
  195. package/src/store/gc-preflight.ts +206 -0
  196. package/src/store/gc.ts +424 -0
  197. package/src/store/metrics-preflight.ts +229 -0
  198. package/src/store/metrics.ts +236 -0
  199. package/src/store/preflight.ts +748 -0
  200. package/src/store/store.ts +693 -0
  201. package/src/system-tools.ts +355 -0
  202. package/src/transport-registry.ts +1124 -0
  203. package/src/transports/claude-code-cli.ts +1348 -0
  204. package/src/transports/opencode-admission.ts +515 -0
  205. package/src/transports/opencode-client.ts +3328 -0
  206. package/src/transports/opencode-evidence.ts +557 -0
  207. package/src/transports/opencode-mcp.ts +248 -0
  208. package/src/transports/opencode-sdk.ts +2294 -0
  209. package/src/transports/opencode-server.ts +535 -0
  210. package/src/triage/adjudication.ts +113 -0
  211. package/src/triage/reply.ts +125 -0
  212. package/src/triage/triage.ts +255 -0
  213. package/src/ui/activity.ts +173 -0
  214. package/src/ui/config-edit.ts +816 -0
  215. package/src/ui/config.ts +462 -0
  216. package/src/ui/menu.ts +1325 -0
  217. package/src/ui/plan.ts +1039 -0
  218. package/src/ui/primitives.ts +300 -0
  219. package/src/ui/progress.ts +298 -0
  220. package/src/ui/result.ts +552 -0
  221. package/src/ui/review-menu.ts +312 -0
  222. package/src/ui/select.ts +528 -0
  223. package/src/ui/tree.ts +178 -0
  224. package/src/uninstaller.ts +479 -0
  225. package/src/updater.ts +836 -0
  226. package/src/usage.ts +77 -0
  227. package/src/watch/preflight.ts +1389 -0
  228. package/src/watch/watch.ts +1235 -0
  229. package/src/wizard.ts +877 -0
@@ -0,0 +1,448 @@
1
+ // Hunter/refuter output handling: extraction from a session's final message
2
+ // and structural validation BEFORE anything reaches the pipeline. A step whose
3
+ // final text does not survive these checks is "not delivered" — the same role
4
+ // v1's draftDelivered() played for the monolithic session, applied per step.
5
+
6
+ import type {
7
+ CausalDisposition,
8
+ EvidenceClass,
9
+ Finding,
10
+ RunSummary,
11
+ Severity,
12
+ } from "./findings";
13
+ import { unresolvedProofRefs } from "./proof-refs";
14
+ import { isSafeSlug } from "./spec";
15
+
16
+ // What a hunter emits: a Finding minus the two fields the pipeline assigns
17
+ // later (tier at Step 7, refuter_verdict at Step 6).
18
+ export type DraftFinding = Omit<Finding, "tier" | "refuter_verdict">;
19
+
20
+ export interface HunterDraft {
21
+ findings: DraftFinding[];
22
+ }
23
+
24
+ // #214, widened by #299: a hunt that was given tools and whose transport
25
+ // observed zero tool calls is not a legal SUCCESS, whatever it returned. It is
26
+ // a review that did not look.
27
+ //
28
+ // #214 gated only the EMPTY array: a clean bill with no reading behind it.
29
+ // #299 (2026-10-01) closes the other half. The hunter contract
30
+ // (HUNTER_READ_REQUIREMENT, pipeline.ts) now requires reading the code, and
31
+ // says a finding whose proof was not read with a tool is not admissible; this
32
+ // gate is where the engine ENFORCES that contract. Observed 2026-10-01 in run
33
+ // `df63033a-2`: a logic hunter returned 1 finding with 0 tool calls,
34
+ // self-described as "inferred from the diff", and passed the empty-only gate.
35
+ //
36
+ // The cost is stated, not hidden: a rare real finding that was reachable from
37
+ // the diff alone is lost for that run. It is never lost silently. The step
38
+ // fails, the run goes partial, and no clean bill is posted.
39
+ //
40
+ // Unknown counts stay ungated: a transport that cannot observe tools must
41
+ // not invent a failure, and must not invent a pass by stamping a 0 it did
42
+ // not see. OpenCode stamps the count (including 0). Claude Code derives it from
43
+ // the CLI result's `num_turns` (#299) and omits it when that is not a valid
44
+ // integer. Scout is out of this rule because the engine forces `tools: []`.
45
+ //
46
+ // Only a parsed `{ findings: [...] }` can trip it. The refuter and verifier
47
+ // emit `results`, the summarizer `prose`/`score`, and the scout a bare lead
48
+ // list; none of them has a `findings` array, so none of them is reached.
49
+ export function isVacuousHunt(input: {
50
+ readonly tools: readonly string[];
51
+ readonly toolInvocations: number | undefined;
52
+ readonly parsed: unknown;
53
+ }): boolean {
54
+ if (input.toolInvocations === undefined) return false;
55
+ if (input.tools.length === 0) return false;
56
+ if (input.toolInvocations !== 0) return false;
57
+ if (typeof input.parsed !== "object" || input.parsed === null) {
58
+ return false;
59
+ }
60
+ return Array.isArray((input.parsed as { findings?: unknown }).findings);
61
+ }
62
+
63
+ // `downgraded-latent` (ROADMAP A2): the claim holds as a real defect, but
64
+ // nothing can execute it at this commit. Distinct from `refuted`, which
65
+ // deletes the finding — the G6 lesson is that a latent defect must stay
66
+ // visible. Maps to the same-named RefuterVerdict and lands advisory.
67
+ export type RefuterOutcome =
68
+ | "corroborated"
69
+ | "refuted"
70
+ | "inconclusive"
71
+ | "downgraded-latent";
72
+
73
+ export interface RefuterResult {
74
+ results: Array<{
75
+ finding_id: string;
76
+ outcome: RefuterOutcome;
77
+ proof_refs: string[];
78
+ }>;
79
+ }
80
+
81
+ // #152: the reviewed tree arrives as a predicate, never as a filesystem
82
+ // call from here — this module stays pure and the offline suite stays offline.
83
+ export interface DraftValidationOptions {
84
+ // Answers "does the reviewed tree contain this repo-relative path". ABSENT
85
+ // means the resolvability rule does not run at all, which is what keeps the
86
+ // lab, the probes and every offline caller behaving exactly as before.
87
+ resolveProofRef?: (path: string) => boolean;
88
+ }
89
+
90
+ export class DraftValidationError extends Error {}
91
+
92
+ // A citation nobody can resolve is not weaker evidence, it is NO evidence
93
+ // wearing the shape of some (#152) — so it fails the step the same way a
94
+ // duplicate verdict or a malformed draft does, and takes the existing retry.
95
+ function mustResolveProofRefs(
96
+ refs: readonly string[],
97
+ options: DraftValidationOptions | undefined,
98
+ label: string,
99
+ ): void {
100
+ const resolve = options?.resolveProofRef;
101
+ if (resolve === undefined) return;
102
+ const unresolved = unresolvedProofRefs(refs, resolve);
103
+ must(
104
+ unresolved.length === 0,
105
+ `${label} cite paths absent from the reviewed tree: ${unresolved.join(", ")}`,
106
+ );
107
+ }
108
+
109
+ function must(condition: boolean, message: string): void {
110
+ if (!condition) throw new DraftValidationError(message);
111
+ }
112
+
113
+ // An optional string field the model filled with `null`. Inline JSON gives a
114
+ // model no way to spell "absent", so `null` here means exactly what an absent
115
+ // key means — and it is NORMALISED away rather than rejected.
116
+ //
117
+ // That is a deliberate exception to this file's fail-loud default, on the same
118
+ // reasoning extractJsonObject already tolerates a fenced or prose-wrapped
119
+ // draft: the value is unambiguous, refusing it recovers nothing, and one
120
+ // must() throw discards every OTHER finding in the same draft and burns a paid
121
+ // retry. A hunter writing `"symbol": null` is ordinary model behaviour, not a
122
+ // corrupt draft.
123
+ //
124
+ // A present-but-wrong-typed value is NOT normalised. There is nothing to
125
+ // recover from `symbol: 42`, and left in place it reaches the renderer and
126
+ // throws the same TypeError this rule exists to prevent.
127
+ //
128
+ // PAID-FOR FAILURE (PR #50, 2026-08-23): a hunter emitted `"symbol": null`,
129
+ // neither validator looked at the field, the null was written into
130
+ // findings.json — the artifact the sibling lab validates — and then killed the
131
+ // POST at review/report.ts's oneLine(). The pipeline had already billed $3.77.
132
+ //
133
+ // Mutates IN PLACE: validateHunterDraft discards this function's return value,
134
+ // so rebuilding here would be silently inert. review/pipeline.ts stamps `hunter` onto
135
+ // the same extracted object the same way.
136
+ function normalizeOptionalString(
137
+ f: Record<string, unknown>,
138
+ key: string,
139
+ label: string,
140
+ ): void {
141
+ if (f[key] === null) {
142
+ delete f[key];
143
+ return;
144
+ }
145
+ must(
146
+ f[key] === undefined || typeof f[key] === "string",
147
+ `${label} must be a string when present`,
148
+ );
149
+ }
150
+
151
+ // Fence/prose-tolerant JSON extraction. Models occasionally wrap the mandated
152
+ // JSON-only final message in a code fence or a sentence of prose; both are
153
+ // recoverable without a retry. Anything not confidently readable returns
154
+ // undefined (never a guess) — the caller treats that as "not delivered".
155
+ export function extractJsonObject(finalText: string): unknown {
156
+ const direct = tryParse(finalText.trim());
157
+ if (direct !== undefined) return direct;
158
+
159
+ const fenced = finalText.match(/```(?:json)?\s*\n([\s\S]*?)\n\s*```/);
160
+ if (fenced?.[1]) {
161
+ const parsed = tryParse(fenced[1].trim());
162
+ if (parsed !== undefined) return parsed;
163
+ }
164
+
165
+ // Last resort: the largest balanced `{...}` span that parses. Covers "Here is
166
+ // the result: {...}". It used to be first-`{`-to-last-`}`, which a single
167
+ // brace in the surrounding prose broke: a hunter's closing note cited
168
+ // `${id}.${codec}`, the slice started inside that template literal, and a
169
+ // valid two-finding draft (one of them the planted defect) was rejected as a
170
+ // format violation (lab ledger, cost levers v3, musive #965, 2026-10-21).
171
+ // Largest, not first: a stray `{}` in the prose also parses, and must never
172
+ // win over the draft.
173
+ let best: { length: number; end: number; value: unknown } | undefined;
174
+ for (let start = finalText.indexOf("{"); start !== -1; ) {
175
+ const end = matchingBrace(finalText, start);
176
+ if (end !== -1 && (best === undefined || end - start + 1 > best.length)) {
177
+ const value = tryParse(finalText.slice(start, end + 1));
178
+ if (value !== undefined) best = { length: end - start + 1, end, value };
179
+ }
180
+ // Braces inside an object already parsed (a claim quoting code) cannot
181
+ // start a larger one, so they are skipped rather than rescanned.
182
+ const from = best !== undefined && best.end > start ? best.end : start;
183
+ start = finalText.indexOf("{", from + 1);
184
+ }
185
+ return best?.value;
186
+ }
187
+
188
+ // The index of the `}` closing the `{` at `start`, skipping braces inside JSON
189
+ // strings (a claim quoting `fn() {}` must not close the object early), or -1
190
+ // when the text ends first.
191
+ function matchingBrace(text: string, start: number): number {
192
+ let depth = 0;
193
+ let inString = false;
194
+ for (let i = start; i < text.length; i++) {
195
+ const ch = text[i];
196
+ if (inString) {
197
+ if (ch === "\\") i++;
198
+ else if (ch === '"') inString = false;
199
+ } else if (ch === '"') {
200
+ inString = true;
201
+ } else if (ch === "{") {
202
+ depth++;
203
+ } else if (ch === "}") {
204
+ depth--;
205
+ if (depth === 0) return i;
206
+ }
207
+ }
208
+ return -1;
209
+ }
210
+
211
+ function tryParse(text: string): unknown {
212
+ try {
213
+ const parsed: unknown = JSON.parse(text);
214
+ return typeof parsed === "object" && parsed !== null ? parsed : undefined;
215
+ } catch {
216
+ return undefined;
217
+ }
218
+ }
219
+
220
+ const SEVERITIES: Severity[] = ["BLOCKER", "CRITICAL", "WARNING", "SUGGESTION"];
221
+ const EVIDENCE_CLASSES: EvidenceClass[] = [
222
+ "deterministic",
223
+ "inferential",
224
+ "insufficient",
225
+ ];
226
+ const CAUSAL_DISPOSITIONS: CausalDisposition[] = [
227
+ "introduced",
228
+ "behavior-activated",
229
+ "worsened",
230
+ "pre-existing",
231
+ "base-only",
232
+ "unknown",
233
+ ];
234
+ const REFUTER_OUTCOMES: RefuterOutcome[] = [
235
+ "corroborated",
236
+ "refuted",
237
+ "inconclusive",
238
+ "downgraded-latent",
239
+ ];
240
+
241
+ export function validateSummary(candidate: unknown): RunSummary {
242
+ must(
243
+ typeof candidate === "object" && candidate !== null,
244
+ "summary must be an object",
245
+ );
246
+ const summary = candidate as Record<string, unknown>;
247
+ must(
248
+ typeof summary.prose === "string" && summary.prose.length > 0,
249
+ "summary.prose required",
250
+ );
251
+ must(
252
+ typeof summary.prose === "string" && summary.prose.length <= 1200,
253
+ "summary.prose must be at most 1200 characters",
254
+ );
255
+ must(
256
+ typeof summary.score === "number" &&
257
+ Number.isInteger(summary.score) &&
258
+ summary.score >= 1 &&
259
+ summary.score <= 5,
260
+ "summary.score must be an integer 1-5",
261
+ );
262
+ must(
263
+ typeof summary.score_reason === "string" && summary.score_reason.length > 0,
264
+ "summary.score_reason required",
265
+ );
266
+ must(
267
+ typeof summary.score_reason === "string" &&
268
+ summary.score_reason.length <= 400,
269
+ "summary.score_reason must be at most 400 characters",
270
+ );
271
+ const prose = summary.prose as string;
272
+ const scoreReason = summary.score_reason as string;
273
+ must(
274
+ !prose.includes("<!--") &&
275
+ !prose.includes("-->") &&
276
+ !scoreReason.includes("<!--") &&
277
+ !scoreReason.includes("-->"),
278
+ "summary strings must not contain HTML comment markers",
279
+ );
280
+ return summary as unknown as RunSummary;
281
+ }
282
+
283
+ export function validateDraftFinding(
284
+ candidate: unknown,
285
+ index: number,
286
+ options?: DraftValidationOptions,
287
+ ): DraftFinding {
288
+ must(
289
+ typeof candidate === "object" && candidate !== null,
290
+ `draft findings[${index}] must be an object`,
291
+ );
292
+ const f = candidate as Record<string, unknown>;
293
+ must(
294
+ typeof f.id === "string" && f.id.length > 0,
295
+ `draft findings[${index}].id required`,
296
+ );
297
+ // Drafts are always merged into a v1.1 document: mergeRunEnvelope
298
+ // (review/findings.ts) stamps SCHEMA_VERSION_V1_1 unconditionally, with no
299
+ // v1.0 production writer left (odd/tasks/logic-hunter.md T1 verified this
300
+ // in code before relying on it). So the draft validator accepts the full
301
+ // v1.1 range, 1-15, category 15 = "local logic error" included.
302
+ must(
303
+ typeof f.category === "number" && f.category >= 1 && f.category <= 15,
304
+ `draft findings[${index}].category must be 1-15`,
305
+ );
306
+ must(
307
+ typeof f.path === "string" && f.path.length > 0,
308
+ `draft findings[${index}].path required`,
309
+ );
310
+ must(
311
+ typeof f.line === "number",
312
+ `draft findings[${index}].line must be a number`,
313
+ );
314
+ must(
315
+ SEVERITIES.includes(f.severity as Severity),
316
+ `draft findings[${index}].severity invalid`,
317
+ );
318
+ must(
319
+ EVIDENCE_CLASSES.includes(f.evidence_class as EvidenceClass),
320
+ `draft findings[${index}].evidence_class invalid`,
321
+ );
322
+ must(
323
+ CAUSAL_DISPOSITIONS.includes(f.causal_disposition as CausalDisposition),
324
+ `draft findings[${index}].causal_disposition invalid`,
325
+ );
326
+ must(
327
+ typeof f.claim === "string" && f.claim.length > 0,
328
+ `draft findings[${index}].claim required`,
329
+ );
330
+ must(
331
+ Array.isArray(f.proof_refs),
332
+ `draft findings[${index}].proof_refs must be an array`,
333
+ );
334
+ must(
335
+ typeof f.hunter === "string" && isSafeSlug(f.hunter),
336
+ `draft findings[${index}].hunter invalid`,
337
+ );
338
+ must(
339
+ typeof f.hops_used === "number",
340
+ `draft findings[${index}].hops_used must be a number`,
341
+ );
342
+ must(
343
+ Array.isArray(f.hop_trail),
344
+ `draft findings[${index}].hop_trail must be an array`,
345
+ );
346
+ must(
347
+ typeof f.dedupe_key === "string" && f.dedupe_key.length > 0,
348
+ `draft findings[${index}].dedupe_key required`,
349
+ );
350
+ // Array.isArray above says nothing about what is INSIDE, and every element
351
+ // is rendered through oneLine() on the same paid posting path the null
352
+ // symbol crashed. Unlike an absent symbol a null element carries no
353
+ // recoverable meaning, so this one rejects.
354
+ must(
355
+ (f.proof_refs as unknown[]).every((ref) => typeof ref === "string"),
356
+ `draft findings[${index}].proof_refs must contain only strings`,
357
+ );
358
+ mustResolveProofRefs(
359
+ f.proof_refs as string[],
360
+ options,
361
+ `draft findings[${index}].proof_refs`,
362
+ );
363
+ // The only two optional keys on a DraftFinding. `root_cause_id` is normally
364
+ // engine-assigned (review/pipeline.ts), which does not stop a hunter emitting it.
365
+ normalizeOptionalString(f, "symbol", `draft findings[${index}].symbol`);
366
+ normalizeOptionalString(
367
+ f,
368
+ "root_cause_id",
369
+ `draft findings[${index}].root_cause_id`,
370
+ );
371
+ return f as unknown as DraftFinding;
372
+ }
373
+
374
+ export function validateHunterDraft(
375
+ candidate: unknown,
376
+ options?: DraftValidationOptions,
377
+ ): HunterDraft {
378
+ must(
379
+ typeof candidate === "object" && candidate !== null,
380
+ "hunter draft must be an object",
381
+ );
382
+ const d = candidate as Record<string, unknown>;
383
+ must(Array.isArray(d.findings), "hunter draft .findings must be an array");
384
+ (d.findings as unknown[]).forEach((f, i) => {
385
+ validateDraftFinding(f, i, options);
386
+ });
387
+ return d as unknown as HunterDraft;
388
+ }
389
+
390
+ // The prose contract is "one verdict per finding, never implied". Here that
391
+ // stops being an instruction and becomes an invariant: the id sets must match
392
+ // EXACTLY — a missing verdict, a duplicate, or a verdict for a finding never
393
+ // submitted each reject the whole result (→ step not delivered → retry path).
394
+ export function validateRefuterResult(
395
+ candidate: unknown,
396
+ submittedIds: string[],
397
+ options?: DraftValidationOptions,
398
+ ): RefuterResult {
399
+ must(
400
+ typeof candidate === "object" && candidate !== null,
401
+ "refuter result must be an object",
402
+ );
403
+ const d = candidate as Record<string, unknown>;
404
+ must(Array.isArray(d.results), "refuter result .results must be an array");
405
+ const seen = new Set<string>();
406
+ for (const [i, entry] of (d.results as unknown[]).entries()) {
407
+ must(
408
+ typeof entry === "object" && entry !== null,
409
+ `refuter results[${i}] must be an object`,
410
+ );
411
+ const r = entry as Record<string, unknown>;
412
+ must(
413
+ typeof r.finding_id === "string" && r.finding_id.length > 0,
414
+ `refuter results[${i}].finding_id required`,
415
+ );
416
+ must(
417
+ REFUTER_OUTCOMES.includes(r.outcome as RefuterOutcome),
418
+ `refuter results[${i}].outcome invalid`,
419
+ );
420
+ must(
421
+ Array.isArray(r.proof_refs),
422
+ `refuter results[${i}].proof_refs must be an array`,
423
+ );
424
+ // Preventive, not a live crash vector: only `outcome` is read off a
425
+ // refuter result today (review/pipeline.ts). Kept symmetric with the draft rule
426
+ // above so a future consumer cannot inherit the same class of defect.
427
+ must(
428
+ (r.proof_refs as unknown[]).every((ref) => typeof ref === "string"),
429
+ `refuter results[${i}].proof_refs must contain only strings`,
430
+ );
431
+ mustResolveProofRefs(
432
+ r.proof_refs as string[],
433
+ options,
434
+ `refuter results[${i}].proof_refs`,
435
+ );
436
+ const id = r.finding_id as string;
437
+ must(!seen.has(id), `refuter results duplicate verdict for ${id}`);
438
+ must(
439
+ submittedIds.includes(id),
440
+ `refuter results verdict for never-submitted ${id}`,
441
+ );
442
+ seen.add(id);
443
+ }
444
+ for (const id of submittedIds) {
445
+ must(seen.has(id), `refuter results missing verdict for ${id}`);
446
+ }
447
+ return d as unknown as RefuterResult;
448
+ }
@@ -0,0 +1,120 @@
1
+ // Immutable cross-repository conformance cases for findings schema v1.0/v1.1.
2
+ // Both pr-hero and deep-review parse fresh copies of these bytes and run their
3
+ // independent validators — duplicated fixtures drift; shared bytes do not.
4
+
5
+ export type FindingsConformanceExpectation = "accept" | "reject";
6
+
7
+ export interface FindingsConformanceCase {
8
+ readonly id: string;
9
+ readonly raw: string;
10
+ readonly expect: FindingsConformanceExpectation;
11
+ }
12
+
13
+ // Minimal shared finding object embedded in every case below.
14
+ const FINDING_V10 =
15
+ '{"id":"F001","category":1,"path":"src/a.ts","line":1,"severity":"BLOCKER","evidence_class":"deterministic","refuter_verdict":"not_submitted","causal_disposition":"introduced","claim":"x","proof_refs":[],"hunter":"reliability","tier":"blocking","hops_used":0,"hop_trail":[],"dedupe_key":"k"}';
16
+ const FINDING_V11_SECURITY =
17
+ '{"id":"F001","category":1,"path":"src/a.ts","line":1,"severity":"BLOCKER","evidence_class":"deterministic","refuter_verdict":"not_submitted","causal_disposition":"introduced","claim":"x","proof_refs":[],"hunter":"security","tier":"blocking","hops_used":0,"hop_trail":[],"dedupe_key":"k"}';
18
+ const FINDING_V11_CODE_QUALITY =
19
+ '{"id":"F001","category":1,"path":"src/a.ts","line":1,"severity":"BLOCKER","evidence_class":"deterministic","refuter_verdict":"not_submitted","causal_disposition":"introduced","claim":"x","proof_refs":[],"hunter":"code-quality","tier":"blocking","hops_used":0,"hop_trail":[],"dedupe_key":"k"}';
20
+ const FINDING_V11_BAD_HUNTER =
21
+ '{"id":"F001","category":1,"path":"src/a.ts","line":1,"severity":"BLOCKER","evidence_class":"deterministic","refuter_verdict":"not_submitted","causal_disposition":"introduced","claim":"x","proof_refs":[],"hunter":"Security","tier":"blocking","hops_used":0,"hop_trail":[],"dedupe_key":"k"}';
22
+
23
+ const TELEMETRY =
24
+ '{"index_ms":1,"index_mode":"fresh","index_disk_mb":1,"wall_ms":1,"tokens_in":1,"tokens_out":1,"tokens_total":2,"cost_usd_est":0.1}';
25
+
26
+ function envelope(
27
+ schemaVersion: string,
28
+ finding: string,
29
+ engine?: string,
30
+ ): string {
31
+ const engineField = engine === undefined ? "" : `,"engine":${engine}`;
32
+ return `{"schema_version":"${schemaVersion}","pr":1,"base_sha":"abc","head_sha":"def","model":"sonnet","iteration":1,"parity_hunter_fired":false,"run_status":"complete","telemetry":${TELEMETRY}${engineField},"findings":[${finding}],"debug":{"refuted":[]}}`;
33
+ }
34
+
35
+ export const FINDINGS_CONFORMANCE_CASES: readonly FindingsConformanceCase[] = [
36
+ {
37
+ id: "v10-minimal-closed-hunter",
38
+ raw: envelope("1.0.0", FINDING_V10),
39
+ expect: "accept",
40
+ },
41
+ {
42
+ id: "v10-optional-engine",
43
+ raw: envelope("1.0.0", FINDING_V10, '{"name":"pr-hero","version":"1.0.0"}'),
44
+ expect: "accept",
45
+ },
46
+ {
47
+ id: "v10-rejects-open-hunter",
48
+ raw: envelope("1.0.0", FINDING_V11_SECURITY),
49
+ expect: "reject",
50
+ },
51
+ {
52
+ id: "v11-arbitrary-specialty-slug",
53
+ raw: envelope(
54
+ "1.1.0",
55
+ FINDING_V11_SECURITY,
56
+ '{"name":"pr-hero","version":"1.0.0"}',
57
+ ),
58
+ expect: "accept",
59
+ },
60
+ {
61
+ id: "v11-hyphenated-specialty-slug",
62
+ raw: envelope(
63
+ "1.1.0",
64
+ FINDING_V11_CODE_QUALITY,
65
+ '{"name":"pr-hero","version":"1.0.0"}',
66
+ ),
67
+ expect: "accept",
68
+ },
69
+ {
70
+ id: "v11-optional-revision",
71
+ raw: envelope(
72
+ "1.1.0",
73
+ FINDING_V11_SECURITY,
74
+ '{"name":"pr-hero","version":"1.0.0","revision":"abc123"}',
75
+ ),
76
+ expect: "accept",
77
+ },
78
+ {
79
+ id: "v11-missing-engine",
80
+ raw: envelope("1.1.0", FINDING_V11_SECURITY),
81
+ expect: "reject",
82
+ },
83
+ {
84
+ id: "v11-invalid-hunter-slug",
85
+ raw: envelope(
86
+ "1.1.0",
87
+ FINDING_V11_BAD_HUNTER,
88
+ '{"name":"pr-hero","version":"1.0.0"}',
89
+ ),
90
+ expect: "reject",
91
+ },
92
+ {
93
+ id: "v11-engine-name-untrimmed",
94
+ raw: envelope(
95
+ "1.1.0",
96
+ FINDING_V11_SECURITY,
97
+ '{"name":" pr-hero","version":"1.0.0"}',
98
+ ),
99
+ expect: "reject",
100
+ },
101
+ {
102
+ id: "v11-engine-revision-control-char",
103
+ raw: envelope(
104
+ "1.1.0",
105
+ FINDING_V11_SECURITY,
106
+ '{"name":"pr-hero","version":"1.0.0","revision":"bad\\u0007"}',
107
+ ),
108
+ expect: "reject",
109
+ },
110
+ {
111
+ id: "unknown-schema-version",
112
+ raw: envelope("0.9.0", FINDING_V10),
113
+ expect: "reject",
114
+ },
115
+ {
116
+ id: "malformed-schema-version",
117
+ raw: envelope("1.0", FINDING_V10),
118
+ expect: "reject",
119
+ },
120
+ ] as const;