crysk 0.3.1 → 0.3.3

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 (80) hide show
  1. package/README.md +61 -37
  2. package/dist/SKILL-12as0f3q.md +74 -0
  3. package/dist/SKILL-2h445snn.md +140 -0
  4. package/dist/SKILL-6j27707y.md +140 -0
  5. package/dist/SKILL-6vy283pt.md +140 -0
  6. package/dist/SKILL-816621e5.md +74 -0
  7. package/dist/SKILL-bnh7nrjz.md +74 -0
  8. package/dist/SKILL-ebn0fqaq.md +140 -0
  9. package/dist/SKILL-fv8x6hhx.md +140 -0
  10. package/dist/SKILL-nv32jpc5.md +74 -0
  11. package/dist/SKILL-qnfc8yp3.md +539 -0
  12. package/dist/SKILL-xr56f0b6.md +140 -0
  13. package/dist/SKILL-yz6wk92g.md +542 -0
  14. package/dist/ci-admission-09k2ba89.md +126 -0
  15. package/dist/ci-admission-a6d0wk1c.md +128 -0
  16. package/dist/ci-admission-f19qh39t.md +128 -0
  17. package/dist/ci-admission-tcqsj7b2.md +126 -0
  18. package/dist/cli.js +11544 -10726
  19. package/dist/index.js +1578 -942
  20. package/dist/materiality-f1qwnvg1.md +27 -0
  21. package/dist/review-refuter-btpgnkcd.md +77 -0
  22. package/package.json +3 -2
  23. package/prompts/default/PROVENANCE.md +1 -0
  24. package/prompts/default/review-refuter.md +6 -0
  25. package/prompts/materiality.md +27 -0
  26. package/skills/crysk/SKILL.md +5 -5
  27. package/skills/crysk-ci-setup/SKILL.md +16 -10
  28. package/skills/crysk-ci-setup/references/ci-admission.md +4 -0
  29. package/skills/crysk-loop/SKILL.md +32 -5
  30. package/src/asset-manifest.ts +2 -0
  31. package/src/assets.ts +4 -1
  32. package/src/brand.ts +11 -9
  33. package/src/ci/cli-record.ts +1 -1
  34. package/src/ci/gates.ts +31 -0
  35. package/src/ci/outcome.ts +6 -5
  36. package/src/ci/override.ts +11 -10
  37. package/src/ci/publish.ts +44 -103
  38. package/src/ci/reporter.ts +34 -5
  39. package/src/ci/review-levels.ts +21 -0
  40. package/src/ci/setup.ts +1 -2
  41. package/src/commands/ci-setup.ts +21 -18
  42. package/src/commands/init.ts +21 -12
  43. package/src/commands/post.ts +17 -0
  44. package/src/compare/loop.ts +356 -0
  45. package/src/compare/materiality.ts +266 -0
  46. package/src/compare/noise.ts +166 -0
  47. package/src/diversity/projection.ts +3 -0
  48. package/src/doctor.ts +48 -29
  49. package/src/index.ts +1 -1
  50. package/src/menu-context.ts +1 -1
  51. package/src/model/routing.ts +62 -0
  52. package/src/pr/admission.ts +13 -1
  53. package/src/pr/discovery.ts +17 -5
  54. package/src/pr/inline.ts +15 -1
  55. package/src/pr/plan.ts +5 -0
  56. package/src/pr/post-floor.ts +30 -0
  57. package/src/pr/posting.ts +4 -0
  58. package/src/pr/pr-status.ts +14 -0
  59. package/src/pr/pr.ts +50 -34
  60. package/src/pr/preflight.ts +2 -2
  61. package/src/pr/publish-outcome.ts +4 -0
  62. package/src/pr/review-pr.ts +65 -26
  63. package/src/pr/target.ts +16 -3
  64. package/src/pr/teardown.ts +1 -1
  65. package/src/rereview/prepare.ts +16 -0
  66. package/src/rereview/state.ts +206 -25
  67. package/src/review/boundary.ts +5 -1
  68. package/src/review/dedupe.ts +48 -4
  69. package/src/review/findings.ts +47 -1
  70. package/src/review/materiality-gate.ts +158 -0
  71. package/src/review/pipeline.ts +581 -56
  72. package/src/review/preflight.ts +201 -28
  73. package/src/review/prompt-set.ts +12 -8
  74. package/src/review/report.ts +73 -10
  75. package/src/review/review.ts +30 -5
  76. package/src/review/route-preflight.ts +29 -1
  77. package/src/review/run.ts +56 -18
  78. package/src/ui/config.ts +8 -0
  79. package/src/updater.ts +1 -1
  80. package/src/wizard.ts +35 -9
@@ -19,6 +19,7 @@ import type {
19
19
  RoutingConfig,
20
20
  RunnerBackend,
21
21
  } from "#model/routing";
22
+ import { POST_MIN_SEVERITIES, type PostMinSeverity } from "#pr/post-floor";
22
23
  import type { SuspicionPrior } from "#review/prompt-set";
23
24
  import { type AgentSpec, isSafeSlug, type ReviewSpec } from "#review/spec";
24
25
  import {
@@ -314,7 +315,7 @@ Usage:
314
315
  crysk [options] Open interactive terminal user interface (TTY)
315
316
  crysk menu [options] Open interactive terminal user interface
316
317
  crysk review [options] Review a branch (zero flags inside a configured repo)
317
- crysk init [options] Scaffold <repo>/.crysk/ (config.json + gotchas.md)
318
+ crysk init [options] Scaffold <repo>/.crysk/config.json, and a root REVIEW.md when the repo has no review instructions
318
319
  crysk setup [options] Run interactive onboarding wizard
319
320
  crysk setup --ci [--force] [--level <l>] [--ci-mode <m>] [--billing <b>] [--budget-usd <n>]
320
321
  Scaffold .github/workflows/crysk.yml (or update
@@ -500,8 +501,10 @@ Options:
500
501
  deferred. Not required — deferred is a tag plus
501
502
  reasoning; the coding agent decides whether an issue
502
503
  exists
503
- --gotchas <file> Repo gotchas file (default: <repo>/.crysk/gotchas.md);
504
- supply it from outside to review a tree you cannot dirty
504
+ --gotchas <file> Review instructions file, overriding <repo>/REVIEW.md and
505
+ <repo>/.crysk/gotchas.md (default: REVIEW.md, else
506
+ gotchas.md, else none); supply it from outside to review
507
+ a tree you cannot dirty
505
508
  --config <file> Local config (default: <repo>/.crysk/config.json) with
506
509
  agents_dir, default_base, parity_trigger_paths and
507
510
  suspicion_priors, optional summary settings, and
@@ -2178,7 +2181,15 @@ export const CONFIG_DIRECTION: Record<keyof LocalConfig, ConfigDirection> = {
2178
2181
  max_changed_lines: "capped",
2179
2182
  max_changed_files: "capped",
2180
2183
  scout: "capped",
2184
+ // `capped` like the scout, for the same reason: switching it on adds one
2185
+ // judge spawn per blocking finding, so a committed file may turn it off but
2186
+ // never on against the operator's global ceiling.
2187
+ materiality_gate: "capped",
2181
2188
  post: "capped",
2189
+ // `person`: a global floor applies to every repo, and a repo file overrides
2190
+ // it either way. It changes only what a PR shows, never what a review costs,
2191
+ // so the spend asymmetry behind `capped` does not apply.
2192
+ post_min_severity: "person",
2182
2193
  ci_review_policy: "repo",
2183
2194
  ci_max_attempts: "repo",
2184
2195
  ci_max_reviews: "repo",
@@ -2219,7 +2230,12 @@ export interface LocalConfig {
2219
2230
  max_changed_lines?: number;
2220
2231
  max_changed_files?: number;
2221
2232
  scout?: boolean;
2233
+ // Opt-in judge that demotes immaterial blocking findings to advisory
2234
+ // (review/materiality-gate.ts). Absent means off.
2235
+ materiality_gate?: boolean;
2222
2236
  post?: boolean;
2237
+ // The lowest finding a PR review posts (pr/post-floor.ts). Absent posts all.
2238
+ post_min_severity?: PostMinSeverity;
2223
2239
  // CI admission: when to spend on a synchronize push (see ci/review-admission.ts).
2224
2240
  ci_review_policy?: CiReviewPolicyMode;
2225
2241
  ci_max_attempts?: number;
@@ -2458,7 +2474,13 @@ function parseConfigLayer(
2458
2474
  file,
2459
2475
  );
2460
2476
  const scout = parseOptionalBoolean(config.scout, "scout", file);
2477
+ const materialityGate = parseOptionalBoolean(
2478
+ config.materiality_gate,
2479
+ "materiality_gate",
2480
+ file,
2481
+ );
2461
2482
  const post = parseOptionalBoolean(config.post, "post", file);
2483
+ const postMinSeverity = parsePostMinSeverity(config.post_min_severity, file);
2462
2484
  const ciReviewPolicy = parseCiReviewPolicyMode(config.ci_review_policy, file);
2463
2485
  const ciMaxAttempts = parseCiAdmissionInteger(
2464
2486
  config.ci_max_attempts,
@@ -2528,7 +2550,13 @@ function parseConfigLayer(
2528
2550
  ? {}
2529
2551
  : { max_changed_files: maxChangedFiles }),
2530
2552
  ...(scout === undefined ? {} : { scout }),
2553
+ ...(materialityGate === undefined
2554
+ ? {}
2555
+ : { materiality_gate: materialityGate }),
2531
2556
  ...(post === undefined ? {} : { post }),
2557
+ ...(postMinSeverity === undefined
2558
+ ? {}
2559
+ : { post_min_severity: postMinSeverity }),
2532
2560
  ...(ciReviewPolicy === undefined
2533
2561
  ? {}
2534
2562
  : { ci_review_policy: ciReviewPolicy }),
@@ -2863,6 +2891,22 @@ function parseCiAdmissionInteger(
2863
2891
  return parsed;
2864
2892
  }
2865
2893
 
2894
+ function parsePostMinSeverity(
2895
+ value: unknown,
2896
+ file: string,
2897
+ ): PostMinSeverity | undefined {
2898
+ if (value === undefined) return undefined;
2899
+ if (
2900
+ typeof value !== "string" ||
2901
+ !(POST_MIN_SEVERITIES as readonly string[]).includes(value)
2902
+ ) {
2903
+ throw new CliUsageError(
2904
+ `${file} post_min_severity must be one of: ${POST_MIN_SEVERITIES.join(", ")}`,
2905
+ );
2906
+ }
2907
+ return value as PostMinSeverity;
2908
+ }
2909
+
2866
2910
  function parseCiReviewPolicyMode(
2867
2911
  value: unknown,
2868
2912
  file: string,
@@ -2927,6 +2971,14 @@ export function resolveScout(
2927
2971
  return options.scout ?? config.scout ?? false;
2928
2972
  }
2929
2973
 
2974
+ // No CLI flag on purpose: the gate is opt-in through config only, so the
2975
+ // merged config is the whole answer and absent means off.
2976
+ export function resolveMaterialityGate(
2977
+ config: Pick<ConfigLayer, "materiality_gate">,
2978
+ ): boolean {
2979
+ return config.materiality_gate ?? false;
2980
+ }
2981
+
2930
2982
  export function resolvePost(
2931
2983
  options: Pick<CliOptions, "post">,
2932
2984
  config: Pick<ConfigLayer, "post">,
@@ -3089,12 +3141,23 @@ export function mergeConfig(
3089
3141
  (layer) => layer.scout,
3090
3142
  (a, b) => a && b,
3091
3143
  );
3144
+ const materialityGate = foldKey(
3145
+ layers,
3146
+ CONFIG_DIRECTION.materiality_gate,
3147
+ (layer) => layer.materiality_gate,
3148
+ (a, b) => a && b,
3149
+ );
3092
3150
  const post = foldKey(
3093
3151
  layers,
3094
3152
  CONFIG_DIRECTION.post,
3095
3153
  (layer) => layer.post,
3096
3154
  (a, b) => a && b,
3097
3155
  );
3156
+ const postMinSeverity = foldKey(
3157
+ layers,
3158
+ CONFIG_DIRECTION.post_min_severity,
3159
+ (layer) => layer.post_min_severity,
3160
+ );
3098
3161
  const routing = foldKey(
3099
3162
  layers,
3100
3163
  CONFIG_DIRECTION.routing,
@@ -3178,7 +3241,13 @@ export function mergeConfig(
3178
3241
  ? {}
3179
3242
  : { max_changed_files: maxFiles.value }),
3180
3243
  ...(scout.value === undefined ? {} : { scout: scout.value }),
3244
+ ...(materialityGate.value === undefined
3245
+ ? {}
3246
+ : { materiality_gate: materialityGate.value }),
3181
3247
  ...(post.value === undefined ? {} : { post: post.value }),
3248
+ ...(postMinSeverity.value === undefined
3249
+ ? {}
3250
+ : { post_min_severity: postMinSeverity.value }),
3182
3251
  ...(ciReviewPolicy.value === undefined
3183
3252
  ? {}
3184
3253
  : { ci_review_policy: ciReviewPolicy.value }),
@@ -3218,7 +3287,9 @@ export function mergeConfig(
3218
3287
  max_changed_lines: maxLines.source,
3219
3288
  max_changed_files: maxFiles.source,
3220
3289
  scout: scout.source,
3290
+ materiality_gate: materialityGate.source,
3221
3291
  post: post.source,
3292
+ post_min_severity: postMinSeverity.source,
3222
3293
  ci_review_policy: ciReviewPolicy.source,
3223
3294
  ci_max_attempts: ciMaxAttempts.source,
3224
3295
  ci_max_reviews: ciMaxReviews.source,
@@ -3350,11 +3421,17 @@ export function initConfigTemplate(input: InitTemplateInput): string {
3350
3421
  // dirty" has no way to connect the two.
3351
3422
  // `dirName` is the directory the command actually wrote into (an existing
3352
3423
  // legacy .prhero/ is updated in place), so the advice names a real path.
3353
- export function initGitReminder(dirName: string = REPO_DIR_NAME): string {
3424
+ // `reviewMd`: init also wrote a root REVIEW.md. That one is never offered
3425
+ // .gitignore — CI reads it from the branch, so an ignored REVIEW.md is one no
3426
+ // pull request review ever sees.
3427
+ export function initGitReminder(
3428
+ dirName: string = REPO_DIR_NAME,
3429
+ reviewMd = false,
3430
+ ): string {
3354
3431
  return (
3355
- `Now either commit ${dirName}/ or add it to .gitignore. Every review step ` +
3432
+ `Now either commit ${dirName}/ or add it to .gitignore${reviewMd ? ", and commit REVIEW.md" : ""}. Every review step ` +
3356
3433
  "reads the checkout directly, so Crysk refuses to run on a dirty tree — " +
3357
- `and an untracked ${dirName}/ is exactly that.`
3434
+ `and an untracked ${reviewMd ? `${dirName}/ or REVIEW.md` : `${dirName}/`} is exactly that.`
3358
3435
  );
3359
3436
  }
3360
3437
 
@@ -3390,9 +3467,40 @@ verbatim into every hunter's system prompt, so keep them short and true.
3390
3467
  - <subsystem>: <the naming/ownership rule a newcomer would violate>
3391
3468
  `;
3392
3469
 
3393
- // `pr-hero setup`'s fallback scaffold (wizard.ts writes it when onboarding
3394
- // collected zero invariants). It lives here, beside GOTCHAS_TEMPLATE, so the
3395
- // gate below can recognise both scaffolds from one place.
3470
+ // What `init` and `setup` scaffold today (odd/tasks/review-md.md S7): a root
3471
+ // REVIEW.md, the file name Claude Code Review reads. Same marker, same
3472
+ // `<subsystem>` placeholder lines as GOTCHAS_TEMPLATE, so the gate below
3473
+ // recognises it by both signals. The facts sections reach the hunters and the
3474
+ // refuter; the "Not blocking here" section is read by the materiality judge,
3475
+ // which only runs with `materiality_gate` on, only on blocking findings, and
3476
+ // only for the bounded classes OWNER_INSTRUCTIONS_RULE names (S5).
3477
+ export const REVIEW_MD_TEMPLATE = `<!-- ${GOTCHAS_PLACEHOLDER_MARKER}: delete THIS line once the instructions below are real — Crysk refuses to review while it is here. -->
3478
+ # Review instructions
3479
+
3480
+ Facts and rules a reviewer cannot infer from the diff alone. Crysk gives this
3481
+ file verbatim to every hunter and to the refuter, so keep it short and true.
3482
+
3483
+ ## Looks wrong, is deliberate
3484
+
3485
+ - <subsystem>: <the thing that looks like a bug but is deliberate, and why>
3486
+
3487
+ ## Always check
3488
+
3489
+ - <subsystem>: <the invariant that is enforced somewhere the diff does not show>
3490
+ - <subsystem>: <the naming/ownership rule a newcomer would violate>
3491
+
3492
+ ## Not blocking here
3493
+
3494
+ - <style, naming, test-hygiene, generated-code or dev-script findings this repository does not want blocking or posted, and why>
3495
+
3496
+ (This section is applied by the materiality judge, which runs only with
3497
+ \`materiality_gate\` on, only to blocking findings, and only to those classes:
3498
+ it never demotes a logic, correctness, data, contract or security finding.)
3499
+ `;
3500
+
3501
+ // The fallback `pr-hero setup` wrote into `.crysk/gotchas.md` before setup
3502
+ // scaffolded REVIEW.md. Nothing writes it any more; repos still have it
3503
+ // committed, so the gate below keeps recognising it.
3396
3504
  export const SETUP_GOTCHAS_FALLBACK = `<!-- ${GOTCHAS_PLACEHOLDER_MARKER}: zero invariants defined during onboarding -->\n\n# Repository Gotchas & Invariants\n\n(No invariants defined during onboarding. Replace this with your project's real failure modes, then delete the marker line at the top — Crysk refuses to review while it is there.)\n`;
3397
3505
 
3398
3506
  // Every non-blank line the two scaffolds write, minus the marker line. A file
@@ -3407,10 +3515,13 @@ export const SETUP_GOTCHAS_FALLBACK = `<!-- ${GOTCHAS_PLACEHOLDER_MARKER}: zero
3407
3515
  // setup fallback's sentence did, in 60c28c6.)
3408
3516
  const RETIRED_SCAFFOLD_LINES = [
3409
3517
  "(No invariants defined during onboarding. Edit this file with project failure modes.)",
3518
+ // The first REVIEW_MD_TEMPLATE (b8c35d3), before its policy sections.
3519
+ "Facts a reviewer cannot infer from the diff alone. Crysk injects this file",
3520
+ "verbatim into every hunter's system prompt, so keep it short and true.",
3410
3521
  ];
3411
3522
 
3412
3523
  const SCAFFOLD_BODY_LINES = new Set([
3413
- ...[GOTCHAS_TEMPLATE, SETUP_GOTCHAS_FALLBACK]
3524
+ ...[GOTCHAS_TEMPLATE, SETUP_GOTCHAS_FALLBACK, REVIEW_MD_TEMPLATE]
3414
3525
  .flatMap((scaffold) => scaffold.split("\n"))
3415
3526
  .map((line) => line.trim())
3416
3527
  .filter(
@@ -3447,6 +3558,34 @@ export function gotchasUnusableReason(
3447
3558
  return undefined;
3448
3559
  }
3449
3560
 
3561
+ // The owner text the materiality judge reads as POLICY, or undefined when the
3562
+ // file holds no line of the owner's own (PR #464 F001, #465). A file that
3563
+ // passes the gate can still keep template text — the "Not blocking here"
3564
+ // placeholder above all, which names the demotable classes and would read as
3565
+ // the owner opting them out. So the `- <…>` placeholder bullets our scaffolds
3566
+ // wrote are dropped; headings and any other line stay, because a real
3567
+ // "- style findings" line means nothing without its "## Not blocking here"
3568
+ // heading. What is left is sent only when at least one line is neither a
3569
+ // heading nor a scaffold line: a renamed title over an untouched template is
3570
+ // all template, and sends nothing. A file with no placeholder is sent as
3571
+ // written, so the measured exam arms are unchanged. Facts-only readers
3572
+ // (hunters, refuter) still get the file as written.
3573
+ export function ownerPolicyText(text: string): string | undefined {
3574
+ const kept = text.split("\n").filter((line) => {
3575
+ const trimmed = line.trim();
3576
+ return !(trimmed.startsWith("- <") && SCAFFOLD_BODY_LINES.has(trimmed));
3577
+ });
3578
+ const ownLine = kept.some((line) => {
3579
+ const trimmed = line.trim();
3580
+ return (
3581
+ trimmed !== "" &&
3582
+ !trimmed.startsWith("#") &&
3583
+ !SCAFFOLD_BODY_LINES.has(trimmed)
3584
+ );
3585
+ });
3586
+ return ownLine ? kept.join("\n") : undefined;
3587
+ }
3588
+
3450
3589
  // `pr-hero init`'s closing instruction block, as data.
3451
3590
  //
3452
3591
  // WHY it is a function of the outcome rather than a constant: `init` never
@@ -3466,12 +3605,14 @@ export function gotchasUnusableReason(
3466
3605
  // The union is discriminated rather than a pair of optional fields on
3467
3606
  // purpose: there is no `{ written: true, contents }` to get wrong, and no
3468
3607
  // kept arm that forgot to pass the bytes.
3608
+ // `file` is the repo-relative path the block is about — `REVIEW.md` when this
3609
+ // run wrote it, or whichever instructions file `init` found and kept.
3469
3610
  export function initGotchasInstructions(
3470
3611
  outcome: { written: true } | { written: false; contents: string },
3471
- dirName: string = REPO_DIR_NAME,
3612
+ file: string,
3472
3613
  ): string[] {
3473
3614
  if (outcome.written) {
3474
- // Safe ONLY on this arm: the file is GOTCHAS_TEMPLATE, so it really does
3615
+ // Safe ONLY on this arm: the file is REVIEW_MD_TEMPLATE, so it really does
3475
3616
  // carry `<subsystem>` lines and the marker.
3476
3617
  //
3477
3618
  // "refuses to run without it" was true of an ABSENT file and false of the
@@ -3480,25 +3621,30 @@ export function initGotchasInstructions(
3480
3621
  // placeholders. The marker is what makes the old sentence true, so the
3481
3622
  // instruction has to name the marker.
3482
3623
  return [
3483
- `Then edit ${dirName}/gotchas.md — two steps, both required:`,
3624
+ `Then edit ${file} — two steps, both required:`,
3484
3625
  " 1. replace the <subsystem> lines with facts about this repo",
3485
3626
  ` 2. delete the \`${GOTCHAS_PLACEHOLDER_MARKER}\` marker line at the top`,
3486
3627
  "",
3628
+ 'The "Not blocking here" section is optional: fill it only if you turn on',
3629
+ "`materiality_gate`, otherwise delete it. Its placeholder line is never sent",
3630
+ "to the judge as policy.",
3631
+ "",
3487
3632
  "Crysk refuses to review while that marker is present. It is not " +
3488
3633
  "pedantry: the file above is non-empty, so without the marker a " +
3489
3634
  "review would bill in full for hunters primed with placeholder text " +
3490
- "and report a clean-LOOKING result.",
3635
+ "and report a clean-LOOKING result. If you would rather not keep " +
3636
+ "review instructions, delete the file instead.",
3491
3637
  ];
3492
3638
  }
3493
3639
 
3494
3640
  const reason = gotchasUnusableReason(outcome.contents);
3495
3641
  if (reason === "placeholder") {
3496
3642
  // NOT "replace the <subsystem> lines": a kept scaffold may be `pr-hero
3497
- // setup`'s fallback (wizard.ts), which carries the marker and has no
3643
+ // setup`'s old fallback, which carries the marker and has no
3498
3644
  // `<subsystem>` lines at all. Naming them would be this same defect one
3499
3645
  // layer down.
3500
3646
  return [
3501
- `The ${dirName}/gotchas.md already on disk is still a scaffold: it carries ` +
3647
+ `The ${file} already on disk is still a scaffold: it carries ` +
3502
3648
  `the \`${GOTCHAS_PLACEHOLDER_MARKER}\` marker line or nothing but the ` +
3503
3649
  "scaffold's own lines, and Crysk refuses to review it.",
3504
3650
  "",
@@ -3510,39 +3656,53 @@ export function initGotchasInstructions(
3510
3656
  // No marker in an empty file, so nothing to delete — saying otherwise
3511
3657
  // would send the reader looking for a line that is not there.
3512
3658
  return [
3513
- `The ${dirName}/gotchas.md already on disk is empty, and Crysk refuses ` +
3514
- "to review without gotchas: an empty file makes the whole review a " +
3515
- "zero-cost no-op that LOOKS like a clean result.",
3659
+ `The ${file} already on disk is empty, and Crysk refuses to review ` +
3660
+ "with it: an empty file makes the whole review a zero-cost no-op " +
3661
+ "that LOOKS like a clean result.",
3516
3662
  "",
3517
3663
  "Write facts about THIS repo into it — the deliberate oddities, the " +
3518
- "invariants enforced somewhere the diff does not show.",
3664
+ "invariants enforced somewhere the diff does not show — or delete it " +
3665
+ "to review with the default guidance only.",
3519
3666
  ];
3520
3667
  }
3521
3668
  // Deliberately modest wording. The gate proves only that the file is
3522
3669
  // non-empty and marker-free; it does not prove the contents are good, so
3523
3670
  // this line reports the gate and claims nothing beyond it.
3524
3671
  return [
3525
- `The ${dirName}/gotchas.md already on disk passes the gotchas gate and will ` +
3672
+ `The ${file} already on disk passes the review-instructions gate and will ` +
3526
3673
  "be used as-is.",
3527
3674
  ];
3528
3675
  }
3529
3676
 
3677
+ // What the hunters' gotchas block holds when the repository has neither a
3678
+ // REVIEW.md nor a gotchas file (odd/tasks/review-md.md S3). Said out loud so
3679
+ // the block is never an unexplained empty tag a model could read as truncation.
3680
+ export const NO_REVIEW_INSTRUCTIONS =
3681
+ "This repository provides no review instructions (no REVIEW.md or gotchas file).";
3682
+
3530
3683
  // The pipeline treats unusable gotchas as a fail-loud abort and returns a
3531
3684
  // zero-cost partial run. Correct, but a bare "partial, 0 findings" tells the
3532
- // user nothing — so the CLI checks first and explains.
3685
+ // user nothing — so the CLI checks first and explains. `present` splits the
3686
+ // "empty" reason: a file that exists (REVIEW.md or gotchas) is told to hold
3687
+ // real content or go away; only a path naming no file — an explicit
3688
+ // `--gotchas` typo, since the resolver never returns an absent default — gets
3689
+ // the template to create one.
3533
3690
  export function gotchasErrorMessage(
3534
3691
  gotchasPath: string,
3535
3692
  reason: GotchasUnusableReason,
3693
+ present: boolean,
3536
3694
  ): string {
3537
3695
  const why = [
3538
- "Gotchas are the repo-specific facts a hunter cannot infer from the diff",
3539
- "— deliberate oddities, invariants enforced elsewhere, conventions worth",
3540
- "more than they look. They are injected verbatim into every hunter's",
3541
- "system prompt, and the engine refuses to run without them.",
3696
+ "Review instructions (REVIEW.md, or the older gotchas file) are the",
3697
+ "repo-specific facts a hunter cannot infer from the diff — deliberate",
3698
+ "oddities, invariants enforced elsewhere, conventions worth more than",
3699
+ "they look. They are injected verbatim into every hunter's system prompt.",
3700
+ "A repo may have no such file at all, but one that exists must hold real",
3701
+ "content.",
3542
3702
  ];
3543
3703
  if (reason === "placeholder") {
3544
3704
  return [
3545
- `gotchas file is still the scaffold nobody filled in: ${gotchasPath}`,
3705
+ `review instructions file is still the scaffold nobody filled in: ${gotchasPath}`,
3546
3706
  "",
3547
3707
  ...why,
3548
3708
  "",
@@ -3552,7 +3712,20 @@ export function gotchasErrorMessage(
3552
3712
  "placeholder text, and return a clean-LOOKING result.",
3553
3713
  "",
3554
3714
  "Replace the placeholder lines with facts about THIS repo, and delete",
3555
- "the marker line at the top if it is still there.",
3715
+ "the marker line at the top if it is still there — or delete the file",
3716
+ "to review with the default guidance only.",
3717
+ ].join("\n");
3718
+ }
3719
+ if (present) {
3720
+ return [
3721
+ `empty review instructions file: ${gotchasPath}`,
3722
+ "",
3723
+ ...why,
3724
+ "An empty file makes the whole review a zero-cost no-op that LOOKS like a",
3725
+ "clean result.",
3726
+ "",
3727
+ "Write facts and rules about THIS repo into it, or delete it to review",
3728
+ "with the default guidance only.",
3556
3729
  ].join("\n");
3557
3730
  }
3558
3731
  return [
@@ -113,19 +113,23 @@ export function renderPriorsBlock(priors: SuspicionPrior[]): string {
113
113
  // they are not — but because a uniform rule is enforceable and a rule with
114
114
  // exceptions is a rule someone forgets (§3.4). `nonce` is REQUIRED, so a future
115
115
  // caller cannot reach this substitution without one.
116
+ // The replacements are FUNCTIONS, not strings: a string replacement treats
117
+ // `$$`, `$&`, `` $` `` and `$'` as substitution patterns, so a gotchas or
118
+ // REVIEW.md line with Postgres dollar-quoting would be halved, or splice the
119
+ // body around the anchor into the block. A function's return is inserted as is.
116
120
  export function renderAgentBody(
117
121
  body: string,
118
122
  context: { priors: SuspicionPrior[]; gotchas: string; nonce: string },
119
123
  ): string {
124
+ const priors = wrapBlock(
125
+ "priors",
126
+ context.nonce,
127
+ renderPriorsBlock(context.priors),
128
+ );
129
+ const gotchas = wrapBlock("gotchas", context.nonce, context.gotchas);
120
130
  return body
121
- .replaceAll(
122
- "{{PRIORS}}",
123
- wrapBlock("priors", context.nonce, renderPriorsBlock(context.priors)),
124
- )
125
- .replaceAll(
126
- "{{GOTCHAS}}",
127
- wrapBlock("gotchas", context.nonce, context.gotchas),
128
- );
131
+ .replaceAll("{{PRIORS}}", () => priors)
132
+ .replaceAll("{{GOTCHAS}}", () => gotchas);
129
133
  }
130
134
 
131
135
  // The prompt set's identity, and the reason it exists is M6's central claim:
@@ -9,6 +9,7 @@
9
9
 
10
10
  import { listPaths } from "#git/refs";
11
11
  import type { ResolvedModelRoute, ResolvedStepRoute } from "#model/routing";
12
+ import type { PostMinSeverity } from "#pr/post-floor";
12
13
  import {
13
14
  type CiMode,
14
15
  findingMarker,
@@ -20,13 +21,14 @@ import {
20
21
  type RecoveredSeverity,
21
22
  SEVERITY_UNRECOVERABLE,
22
23
  } from "#rereview/classify";
23
- import type {
24
- Finding,
25
- FindingsDocument,
26
- RefuterVerdict,
27
- RunStatus,
28
- Severity,
29
- Tier,
24
+ import {
25
+ type Finding,
26
+ type FindingsDocument,
27
+ isCausallyExempt,
28
+ type RefuterVerdict,
29
+ type RunStatus,
30
+ type Severity,
31
+ type Tier,
30
32
  } from "#review/findings";
31
33
  import {
32
34
  clusterByRootCause,
@@ -726,6 +728,9 @@ export function renderPrComment(
726
728
  // compacts from the last entry backwards, one entry at a time, until the
727
729
  // body fits. Omitted or past the end, the section is byte-identical.
728
730
  compactFrom?: number,
731
+ // Findings below `post_min_severity` (pr/post-floor.ts): left out of `doc`
732
+ // by the caller, counted here in one line so the summary says they exist.
733
+ notPosted?: { count: number; floor: PostMinSeverity },
729
734
  ): string {
730
735
  // Normalize away one trailing slash so `gh repo view` output and a
731
736
  // hand-typed URL build the same links.
@@ -875,12 +880,23 @@ export function renderPrComment(
875
880
  // Item 7 C7: zero new findings is also not a clean bill when priors
876
881
  // remain live (carried / unconfirmed / deferred / suppressed) or this
877
882
  // run returned / re-tiered a prior. MatchResult.resolved cannot say so.
878
- out.push(cleanBillLine(doc.run_status, delta?.rereview));
883
+ const cleanBill = cleanBillLine(doc.run_status, delta?.rereview);
884
+ // The ✅ claims nothing was found. With findings held back by the floor
885
+ // that claim is false, so it narrows to what the floor let through.
886
+ out.push(
887
+ notPosted !== undefined && cleanBill === CLEAN_BILL
888
+ ? `No findings at or above ${code(notPosted.floor)} severity.`
889
+ : cleanBill,
890
+ );
879
891
  out.push("");
880
892
  } else {
881
893
  out.push(...findingIndexLines(doc.findings, commentUrlByFindingId));
882
894
  out.push("");
883
895
  }
896
+ if (notPosted !== undefined) {
897
+ out.push(notPostedLine(notPosted));
898
+ out.push("");
899
+ }
884
900
  out.push(...liveFindingLines(delta?.rereview));
885
901
  if (outsideDiffFindings.length > 0) {
886
902
  out.push(
@@ -1058,7 +1074,21 @@ function cleanBillLine(
1058
1074
  if (!rereviewIsClean(rereview) && rereview !== undefined) {
1059
1075
  return `No new findings this delta. Live: ${liveBits(rereview).join(" · ")}.`;
1060
1076
  }
1061
- return "✅ Crysk reviewed this PR and found nothing to report.";
1077
+ return CLEAN_BILL;
1078
+ }
1079
+
1080
+ const CLEAN_BILL = "✅ Crysk reviewed this PR and found nothing to report.";
1081
+
1082
+ function notPostedLine(notPosted: {
1083
+ count: number;
1084
+ floor: PostMinSeverity;
1085
+ }): string {
1086
+ const noun = notPosted.count === 1 ? "finding" : "findings";
1087
+ const what = notPosted.floor === "blocking" ? "advisory" : "lower-severity";
1088
+ return (
1089
+ `${notPosted.count} ${what} ${noun} not posted ` +
1090
+ `(${code(`post_min_severity: ${notPosted.floor}`)}).`
1091
+ );
1062
1092
  }
1063
1093
 
1064
1094
  function deltaLine(delta: PrCommentDelta): string {
@@ -1255,6 +1285,22 @@ function tierExplanationLines(finding: Finding): string[] {
1255
1285
  const isBlockerClass =
1256
1286
  finding.severity === "BLOCKER" || finding.severity === "CRITICAL";
1257
1287
  if (!isBlockerClass || finding.tier !== "advisory") return [];
1288
+ // FIRST, ahead of the refuter text: a finding the materiality gate demoted
1289
+ // may carry a `corroborated` verdict, and "the refuter returned
1290
+ // corroborated" would explain nothing about why it is advisory.
1291
+ if (finding.materiality?.label === "immaterial") {
1292
+ return [
1293
+ "⚖️ Demoted to advisory — not material under normal use: " +
1294
+ materialityReason(finding.materiality.reason),
1295
+ ];
1296
+ }
1297
+ // #457: a finding the PR did not cause is advisory whatever the refuter
1298
+ // said, so the refuter text would explain nothing about its tier.
1299
+ if (isCausallyExempt(finding)) {
1300
+ return [
1301
+ "⚖️ Advisory — this PR did not introduce it, so it does not block the gate",
1302
+ ];
1303
+ }
1258
1304
  // `not_submitted` never reached the refuter, so "the refuter returned" it
1259
1305
  // would be false, and printing the engine's word here would contradict the
1260
1306
  // header, which says `refuter: unchecked` (refuterLabel).
@@ -1278,6 +1324,23 @@ function tierExplanationLines(finding: Finding): string[] {
1278
1324
  return lines;
1279
1325
  }
1280
1326
 
1327
+ // The judge's reason is model text written about author-controlled input,
1328
+ // and it is posted. One line (a newline would end the list item and could
1329
+ // start a forged header line), capped, with HTML comment delimiters broken so
1330
+ // it can never open or close a marker the comment parsers read, and `@`
1331
+ // defused so it cannot notify anyone.
1332
+ const MATERIALITY_REASON_MAX = 280;
1333
+
1334
+ function materialityReason(reason: string): string {
1335
+ const flat = oneLine(reason)
1336
+ .replaceAll("<!--", "<!‐‐")
1337
+ .replaceAll("-->", "‐‐>")
1338
+ .replaceAll("@", "@\u200b");
1339
+ return flat.length <= MATERIALITY_REASON_MAX
1340
+ ? flat
1341
+ : `${flat.slice(0, MATERIALITY_REASON_MAX - 1).trimEnd()}…`;
1342
+ }
1343
+
1281
1344
  // Item "Prompt to fix with AI" (Juanma's PR #2 feedback): a copy-pasteable
1282
1345
  // prompt, not a deep link — Greptile's equivalent hands off to a hosted IDE
1283
1346
  // integration this project does not have, and inventing a link to a service
@@ -1741,7 +1804,7 @@ function commentDisclaimer(ciMode: CiMode): string {
1741
1804
  // Hunter-authored text lands inside code spans and list items. A stray
1742
1805
  // backtick in a path or proof_ref would break out of its span and mangle
1743
1806
  // every line after it, so spans are built here and never by hand.
1744
- function code(text: string): string {
1807
+ export function code(text: string): string {
1745
1808
  return `\`${oneLine(text).replaceAll("`", "'")}\``;
1746
1809
  }
1747
1810