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
package/src/ci/outcome.ts CHANGED
@@ -274,7 +274,7 @@ export interface CliRecord {
274
274
  | "yielded"
275
275
  | "error";
276
276
  // Only for outcome "skipped".
277
- skip?: "size" | "budget" | "coverage" | "manual-required";
277
+ skip?: "size" | "budget" | "coverage" | "manual-required" | "excluded";
278
278
  // The head the CLI reviewed or resolved, when it knows one. 40 lowercase hex.
279
279
  // Required for "reviewing": the head the CLI is about to post its pending
280
280
  // status on (the head it holds the review lock for).
@@ -597,6 +597,7 @@ const CLI_SKIPS: readonly NonNullable<CliRecord["skip"]>[] = [
597
597
  "budget",
598
598
  "coverage",
599
599
  "manual-required",
600
+ "excluded",
600
601
  ];
601
602
  const CLI_HEAD_PATTERN = /^[0-9a-f]{40}$/;
602
603
 
@@ -1505,13 +1506,13 @@ export const ERROR_CATALOG: Readonly<Record<ErrorCode, CatalogEntry>> = {
1505
1506
  "PRH-GOTCHAS-MISSING": {
1506
1507
  level: "error",
1507
1508
  owner: "config",
1508
- what: ".crysk/gotchas.md is missing or still the scaffold",
1509
+ what: "the review instructions file (REVIEW.md or .crysk/gotchas.md) is empty or still the scaffold",
1509
1510
  variants: single(
1510
- "reviews need real repository facts to be accurate",
1511
+ "a file that exists must hold real repository rules; with no file at all the review runs on the default guidance",
1511
1512
  [
1512
- "Run `npx -y crysk init` in a clone of the repository (it creates .crysk/config.json and .crysk/gotchas.md), then write real facts about this repository, delete the scaffold marker line if it is there, and commit the file to the base branch (comment-triggered runs read the base branch).",
1513
+ "Write real rules and facts about this repository into the file (REVIEW.md at the repository root, or .crysk/gotchas.md), delete the scaffold marker line if it is there, and commit it to the base branch (comment-triggered runs read the base branch). Or delete the file to review with the default guidance only.",
1513
1514
  ],
1514
- "write real facts into .crysk/gotchas.md, remove the scaffold marker line if present, and commit it to the base branch",
1515
+ "write real rules into REVIEW.md or .crysk/gotchas.md (remove the scaffold marker line if present) and commit it to the base branch, or delete the file",
1515
1516
  ),
1516
1517
  },
1517
1518
  "PRH-CONFIG-INVALID": {
@@ -126,16 +126,17 @@ export function overrideActorOf(description: string): string | null {
126
126
  // as preflight.ts's latestStatusInContext except on a tie, where that one takes the later row
127
127
  // (`>=`). This module cannot import it. The publisher's reads use this one too.
128
128
  //
129
- // WHY one context means two names: for one version the gate is written on `crysk` and on the
130
- // legacy `pr-hero`, and an older action still writes only `pr-hero`. The newest row across both
131
- // names is the gate, so an override posted by an older action still beats a newer-version
132
- // verdict that is older than it. Two rows with the same time are a pair one run wrote, with
133
- // identical content, so either would do; the crysk row is taken so the answer never depends
134
- // on the order of the list.
135
- // A half-landed pair. Every write posts both names, so a name whose newest row is still
136
- // pending while the other name holds a later settled row missed that write. The settled
137
- // row is the verdict (a finished review, or a human's override), and the stuck name is
138
- // what a repair copies it onto. Undefined when the two names agree.
129
+ // WHY one context means two names: since #457 the gate is written on `crysk` alone, but a head
130
+ // reviewed before that change carries rows on the legacy `pr-hero` too, and an older action
131
+ // still writes only `pr-hero`. The newest row across both names is the gate, so an override
132
+ // posted by an older action still beats a newer-version verdict that is older than it. Two
133
+ // rows with the same time are a pair a run before #457 wrote, with identical content, so
134
+ // either would do; the crysk row is taken so the answer never depends on the order of the list.
135
+ // A stranded pair: a name whose newest row is still pending while the other name holds a later
136
+ // settled row. It comes from a pair a run before #457 half-landed, or from an older action's
137
+ // `pr-hero` verdict over this version's `crysk` pending. The settled row is the verdict (a
138
+ // finished review, or a human's override). A repair copies it onto a stuck `crysk` only: the
139
+ // legacy name is never written. Undefined when the two names agree.
139
140
  export function strandedStatusPair<T extends OverrideStatusFact>(
140
141
  statuses: readonly T[],
141
142
  context: string,
package/src/ci/publish.ts CHANGED
@@ -56,7 +56,6 @@ import {
56
56
  MARKER_OPEN,
57
57
  matchMarkerPrefix,
58
58
  STATUS_CONTEXT,
59
- statusContextForms,
60
59
  } from "../brand";
61
60
  import type {
62
61
  CliRecord,
@@ -616,43 +615,17 @@ function workflowCommand(
616
615
  return `::${command} title=crysk::${escaped}\n`;
617
616
  }
618
617
 
619
- // The status write, on BOTH names of its context: the new one, then the legacy `pr-hero` one
620
- // (statusContextForms). Users have `pr-hero` as a required check in branch protection, and a
621
- // head that stops getting it blocks every PR, so the publisher keeps writing it for one version.
622
- // A failed write never skips the other: the required check may be either name. The first
623
- // failure is the one reported, so the renderer sees the same answer a single write gave.
618
+ // The status write: one POST on `status.context`, the crysk name, retried once unless
619
+ // `attempts` is 1. Since #457 the legacy `pr-hero` context is never written, only read
620
+ // (isStatusContext), so a branch protection that still requires `pr-hero` must switch to
621
+ // `crysk`. Returns the failure's HTTP status when gh printed one, so the renderer can pick
622
+ // the permission or the server wording.
624
623
  function postStatus(
625
624
  deps: PublishDeps,
626
625
  repository: string,
627
626
  headSha: string,
628
627
  status: StatusPost,
629
628
  attempts = 2,
630
- ): { ok: true } | { ok: false; httpStatus: number | undefined } {
631
- let failure: { ok: false; httpStatus: number | undefined } | undefined;
632
- for (const context of statusContextForms(status.context)) {
633
- const posted = postStatusOn(
634
- deps,
635
- repository,
636
- headSha,
637
- status,
638
- context,
639
- attempts,
640
- );
641
- if (!posted.ok) failure ??= posted;
642
- }
643
- return failure ?? { ok: true };
644
- }
645
-
646
- // One write on one context, retried once unless `attempts` is 1. Returns the failure's HTTP
647
- // status when gh printed one, so the renderer can pick the permission or the server
648
- // wording.
649
- function postStatusOn(
650
- deps: PublishDeps,
651
- repository: string,
652
- headSha: string,
653
- status: StatusPost,
654
- context: string,
655
- attempts: number,
656
629
  ): { ok: true } | { ok: false; httpStatus: number | undefined } {
657
630
  const args = [
658
631
  "api",
@@ -660,7 +633,7 @@ function postStatusOn(
660
633
  "-f",
661
634
  `state=${status.state}`,
662
635
  "-f",
663
- `context=${context}`,
636
+ `context=${status.context}`,
664
637
  "-f",
665
638
  `description=${status.description}`,
666
639
  "-f",
@@ -1112,13 +1085,15 @@ function parseStatusRow(line: string): HeadStatusRow | undefined {
1112
1085
  // The head's newest pr-hero status, as the three states the table needs. The newest row is
1113
1086
  // picked by its time, not by its place in the answer. A failed read, no pr-hero row, or a
1114
1087
  // state the table does not name is unknown, which the table answers with the status.
1115
- // Copies the verdict of a half-landed pair onto the name that missed it (strandedStatusPair).
1116
- // The stuck name may be the repository's required check, and the readers below take the
1117
- // newest row across both names, so nothing else would ever settle it. Only the stuck name
1118
- // is written: the verdict, which may be a human's override, is never replaced. A failed
1119
- // copy is a warning, and the run goes on as it would have. Returns the verdict whenever
1120
- // the pair is stranded, copied or not: it, not the stuck pending row, is the gate's state,
1121
- // and the readers' newest-row pick could still choose the stuck row on a same-second tie.
1088
+ // Copies the verdict of a stranded pair onto crysk when crysk is the name that missed it
1089
+ // (strandedStatusPair): a crysk pending behind a later pr-hero verdict an older action or a
1090
+ // run before #457 wrote. crysk is the required check, and the readers below take the newest
1091
+ // row across both names, so nothing else would ever settle it. Only crysk is written: the
1092
+ // verdict, which may be a human's override, is never replaced, and a stuck legacy `pr-hero`
1093
+ // row is left as it is, because the legacy name is never written since #457. A failed copy is
1094
+ // a warning, and the run goes on as it would have. Returns the verdict whenever the pair is
1095
+ // stranded, copied or not: it, not the stuck pending row, is the gate's state, and the
1096
+ // readers' newest-row pick could still choose the stuck row on a same-second tie.
1122
1097
  function repairStrandedPair(
1123
1098
  deps: PublishDeps,
1124
1099
  repo: string,
@@ -1127,6 +1102,7 @@ function repairStrandedPair(
1127
1102
  ): HeadStatusRow | undefined {
1128
1103
  const pair = strandedStatusPair(statuses, STATUS_CONTEXT);
1129
1104
  if (pair === undefined) return undefined;
1105
+ if (pair.stranded.context !== STATUS_CONTEXT) return pair.verdict;
1130
1106
  const state = pair.verdict.state;
1131
1107
  const description = pair.verdict.description;
1132
1108
  // A verdict this step cannot reproduce faithfully is not copied: a blank description
@@ -1138,19 +1114,12 @@ function repairStrandedPair(
1138
1114
  ) {
1139
1115
  return pair.verdict;
1140
1116
  }
1141
- const posted = postStatusOn(
1142
- deps,
1143
- repo,
1144
- sha,
1145
- {
1146
- state,
1147
- context: STATUS_CONTEXT,
1148
- description,
1149
- targetUrl: pair.verdict.targetUrl ?? actionsRunUrl(deps.env) ?? "",
1150
- },
1151
- pair.stranded.context,
1152
- 2,
1153
- );
1117
+ const posted = postStatus(deps, repo, sha, {
1118
+ state,
1119
+ context: STATUS_CONTEXT,
1120
+ description,
1121
+ targetUrl: pair.verdict.targetUrl ?? actionsRunUrl(deps.env) ?? "",
1122
+ });
1154
1123
  deps.stdout(
1155
1124
  posted.ok
1156
1125
  ? workflowCommand(
@@ -1237,30 +1206,19 @@ function overrideDescription(actor: string): string {
1237
1206
  // an override the status never received would be a false record.
1238
1207
  function overrideCommentBody(
1239
1208
  plan: Extract<Publication, { kind: "override" }>,
1240
- landed: readonly string[],
1209
+ landed: boolean,
1241
1210
  at: Date,
1242
1211
  ): string {
1243
1212
  const when = `${at.toISOString().slice(0, 16).replace("T", " ")} UTC`;
1244
1213
  const marker = `${MARKER_OPEN}override head=${plan.headSha ?? "unknown"} run=${plan.runId} attempt=${plan.runAttempt} -->`;
1245
- if (landed.length > 0 && plan.headSha !== undefined) {
1246
- // Name exactly the contexts that were written: a branch protection that requires the
1247
- // other one is still blocked, and this comment is never cleaned up (#435 F001).
1248
- const names = landed.map((context) => `\`${context}\``).join(" and ");
1249
- const missed = statusContextForms(STATUS_CONTEXT).filter(
1250
- (context) => !landed.includes(context),
1251
- );
1252
- const missedNote =
1253
- missed.length === 0
1254
- ? ""
1255
- : ` The ${missed.map((context) => `\`${context}\``).join(" and ")} status could not be written, so a rule that requires it is still blocked: comment ${commandHint(OVERRIDE_COMMAND)} again to retry.`;
1214
+ if (landed && plan.headSha !== undefined) {
1215
+ // Names the one context written: since #457 an override posts `crysk` alone, and this
1216
+ // comment is never cleaned up, so it must not claim a legacy `pr-hero` status.
1256
1217
  return [
1257
1218
  marker,
1258
1219
  "",
1259
- (landed.includes(STATUS_CONTEXT)
1260
- ? `Crysk's gate was overridden by @${plan.actor} on head \`${plan.headSha}\` at ${when}. `
1261
- : `@${plan.actor}'s override of Crysk's gate on head \`${plan.headSha}\` at ${when} landed only in part. `) +
1262
- `The ${names} status${landed.length > 1 ? "es" : ""} on that head ${landed.length > 1 ? "are" : "is"} now success, with no review of this head.` +
1263
- missedNote +
1220
+ `Crysk's gate was overridden by @${plan.actor} on head \`${plan.headSha}\` at ${when}. ` +
1221
+ `The \`${STATUS_CONTEXT}\` status on that head is now success, with no review of this head.` +
1264
1222
  ` A new push or a later ${commandHint(REVIEW_COMMAND)} on this head replaces it.`,
1265
1223
  ].join("\n");
1266
1224
  }
@@ -1283,41 +1241,26 @@ function publishOverride(
1283
1241
  deps: PublishDeps,
1284
1242
  plan: Extract<Publication, { kind: "override" }>,
1285
1243
  ): number {
1286
- const landed: string[] = [];
1244
+ let landed = false;
1287
1245
  let exitCode = 0;
1288
1246
  if (plan.headSha !== undefined) {
1289
- // Each context is written on its own (postStatus would fold the pair into one answer):
1290
- // when one lands and the other fails, the head IS overridden on the one that landed, and
1291
- // the permanent audit comment must say so (#434 F001). The failed half is still reported.
1292
- let failure: { ok: false; httpStatus: number | undefined } | undefined;
1293
- for (const context of statusContextForms(STATUS_CONTEXT)) {
1294
- const posted = postStatusOn(
1295
- deps,
1296
- plan.repository,
1297
- plan.headSha,
1298
- {
1299
- state: "success",
1300
- context: STATUS_CONTEXT,
1301
- description: overrideDescription(plan.actor),
1302
- targetUrl: plan.runUrl,
1303
- },
1304
- context,
1305
- 2,
1306
- );
1307
- if (posted.ok) landed.push(context);
1308
- else failure ??= posted;
1309
- }
1310
- if (landed.includes(STATUS_CONTEXT)) {
1247
+ // One write, on crysk alone (#457): the legacy `pr-hero` context is no longer posted.
1248
+ const posted = postStatus(deps, plan.repository, plan.headSha, {
1249
+ state: "success",
1250
+ context: STATUS_CONTEXT,
1251
+ description: overrideDescription(plan.actor),
1252
+ targetUrl: plan.runUrl,
1253
+ });
1254
+ landed = posted.ok;
1255
+ if (posted.ok) {
1311
1256
  // WHY here, right after the success and before the audit comment: the crysk gate is
1312
- // green now, so an earlier run's outcome comment contradicts it. When only the legacy
1313
- // pr-hero status landed, crysk is still red and that comment still explains why. The audit comment does not
1314
- // gate this cleanup, and its warnings never change the exit code (as for a review).
1257
+ // green now, so an earlier run's outcome comment contradicts it. The audit comment does
1258
+ // not gate this cleanup, and its warnings never change the exit code (as for a review).
1315
1259
  cleanupOlderOutcomes(deps, plan);
1316
- }
1317
- if (failure !== undefined) {
1260
+ } else {
1318
1261
  reportStatusWriteFailure(
1319
1262
  deps,
1320
- failure.httpStatus,
1263
+ posted.httpStatus,
1321
1264
  plan.runId,
1322
1265
  plan.runUrl,
1323
1266
  );
@@ -1327,11 +1270,9 @@ function publishOverride(
1327
1270
  deps.stdout(
1328
1271
  workflowCommand(
1329
1272
  "notice",
1330
- landed.includes(STATUS_CONTEXT)
1273
+ landed
1331
1274
  ? `crysk gate overridden by @${plan.actor} on head ${plan.headSha}.`
1332
- : landed.length > 0
1333
- ? `crysk override by @${plan.actor} set only the ${landed.join(", ")} status on head ${plan.headSha}.`
1334
- : `crysk override by @${plan.actor} set no commit status.`,
1275
+ : `crysk override by @${plan.actor} set no commit status.`,
1335
1276
  ),
1336
1277
  );
1337
1278
  const at = (deps.now ?? (() => new Date()))();
@@ -31,10 +31,12 @@
31
31
  // multiple output keys written across several tool calls). An overwrite here
32
32
  // would silently destroy an earlier step's contribution to the same file.
33
33
  import { appendFile } from "node:fs/promises";
34
+ import { listPaths } from "#git/refs";
34
35
  import type { CiMode } from "#pr/preflight";
35
36
  import type { Finding, Severity } from "#review/findings";
36
37
  import {
37
38
  blobUrl,
39
+ code,
38
40
  formatElapsed,
39
41
  type PrCommentDelta,
40
42
  severityEmoji,
@@ -155,6 +157,12 @@ interface CiSkipBudgetSummary {
155
157
  budgetUsd: number;
156
158
  }
157
159
 
160
+ interface CiSkipExcludedSummary {
161
+ kind: "skipped-excluded";
162
+ prNumber: number;
163
+ excludedPaths: string[];
164
+ }
165
+
158
166
  interface CiSkipCoverageSummary {
159
167
  kind: "skipped-coverage";
160
168
  prNumber: number;
@@ -198,6 +206,7 @@ export type CiSummaryData =
198
206
  | CiReviewSummary
199
207
  | CiSkipSizeSummary
200
208
  | CiSkipBudgetSummary
209
+ | CiSkipExcludedSummary
201
210
  | CiSkipCoverageSummary
202
211
  | CiManualRequiredSummary;
203
212
 
@@ -336,6 +345,24 @@ function skipBudgetLines(data: CiSkipBudgetSummary): string[] {
336
345
  ];
337
346
  }
338
347
 
348
+ // #317: not a review held back but a diff with nothing in scope, so the heading
349
+ // is a plain fact, not a warning, and the wording never says "found nothing":
350
+ // nothing was looked at.
351
+ function skipExcludedLines(data: CiSkipExcludedSummary): string[] {
352
+ return [
353
+ `### Crysk: nothing to review — PR #${data.prNumber}`,
354
+ "",
355
+ "**Reason:** every changed file is excluded from review by the ignore " +
356
+ "rules (`.cryskignore` and the shipped defaults).",
357
+ "",
358
+ // Capped like every other path list (listPaths), and each path through
359
+ // code(): the paths are the author's, and a backtick would break the span.
360
+ listPaths(data.excludedPaths.map(code)),
361
+ "",
362
+ "Nothing was spawned and nothing was spent.",
363
+ ];
364
+ }
365
+
339
366
  function admissionMetricRows(
340
367
  data: CiSkipCoverageSummary | CiManualRequiredSummary,
341
368
  ): string[] {
@@ -466,11 +493,13 @@ export function renderStepSummary(
466
493
  ? skipSizeLines(data)
467
494
  : data.kind === "skipped-budget"
468
495
  ? skipBudgetLines(data)
469
- : data.kind === "skipped-coverage"
470
- ? skipCoverageLines(data)
471
- : data.kind === "manual-required"
472
- ? manualRequiredLines(data)
473
- : reviewedLines(data);
496
+ : data.kind === "skipped-excluded"
497
+ ? skipExcludedLines(data)
498
+ : data.kind === "skipped-coverage"
499
+ ? skipCoverageLines(data)
500
+ : data.kind === "manual-required"
501
+ ? manualRequiredLines(data)
502
+ : reviewedLines(data);
474
503
  const out = [...body, "---", "", footerFor(ciMode)];
475
504
  return `${out.join("\n").trimEnd()}\n`;
476
505
  }
@@ -8,6 +8,7 @@
8
8
  // keys it sets are always written to .crysk/config.json, so what a repo does
9
9
  // is visible in the file it versions, never inherited silently.
10
10
 
11
+ import type { PostMinSeverity } from "#pr/post-floor";
11
12
  import { DEFAULT_SIZE_GATE } from "#review/size-gate";
12
13
  import { CI_DEFAULT_METERED_BUDGET_USD } from "./gates";
13
14
  import {
@@ -236,6 +237,12 @@ export interface ConfigPlan {
236
237
  remove: string[];
237
238
  }
238
239
 
240
+ // What setup writes for `post_min_severity`. The engine's own default stays
241
+ // "post everything", so a repo changes only when setup runs on it: a new repo,
242
+ // or a re-run (`--force` included) on one whose config has no floor yet. Filled
243
+ // only when absent, so a floor someone chose is never reset.
244
+ export const RECOMMENDED_POST_MIN_SEVERITY: PostMinSeverity = "warning";
245
+
239
246
  export function configPlan(choices: CiSetupChoices): ConfigPlan {
240
247
  const { ignorePatterns: _ignored, ...advanced } = choices.advanced;
241
248
  const set: Record<string, unknown> = {};
@@ -251,6 +258,7 @@ export function configPlan(choices: CiSetupChoices): ConfigPlan {
251
258
  } else fillIfAbsent.push(levelKeys);
252
259
  if (choices.chosen.maxChangedLines) Object.assign(set, lineKeys);
253
260
  else fillIfAbsent.push(lineKeys);
261
+ fillIfAbsent.push({ post_min_severity: RECOMMENDED_POST_MIN_SEVERITY });
254
262
  // An advanced key is present only because someone gave it.
255
263
  for (const [key, value] of Object.entries(advanced)) {
256
264
  if (value !== undefined) set[key] = value;
@@ -303,8 +311,21 @@ export function renderChoicesSummary(
303
311
  ` observe only ${a.ci_admission_observe_only === true ? "yes: skip decisions are logged, every push is reviewed" : "no"}`,
304
312
  ` trusted actors ${a.ci_trusted_actors && a.ci_trusted_actors.length > 0 ? a.ci_trusted_actors.join(", ") : "none beyond the workflow actor"}`,
305
313
  ` size limit ${"max_changed_lines" in kept ? `${JSON.stringify(kept.max_changed_lines)} changed lines (kept)` : choices.maxChangedLines === 0 ? "no changed-lines limit (0)" : `${choices.maxChangedLines} changed lines`}, ${a.max_changed_files === undefined ? "files resolved from how the review is paid" : `${a.max_changed_files} files`}`,
314
+ ` posting ${postingLine(effective.post_min_severity)}`,
306
315
  ` exclusions ${a.ignorePatterns && a.ignorePatterns.length > 0 ? `${a.ignorePatterns.join(", ")} (.cryskignore)` : "none added (.cryskignore)"}`,
307
316
  "Change them later in the repo config (.crysk/config.json, or .prhero/config.json in a repo set up before the rename) and the review workflow (.github/workflows/crysk.yml, or pr-hero.yml in a repo set up before the rename) (`npx -y crysk config` shows the effective values).",
308
317
  ];
309
318
  return lines;
310
319
  }
320
+
321
+ // Read off the file as written, so a floor set by hand is reported as it stands.
322
+ function postingLine(value: unknown): string {
323
+ if (value === "blocking") {
324
+ return "blocking findings only; advisory ones are counted in the summary (post_min_severity)";
325
+ }
326
+ if (value === "warning") {
327
+ return "every finding except advisory suggestions, which are counted in the summary (post_min_severity)";
328
+ }
329
+ if (value === "suggestion") return "every finding (post_min_severity)";
330
+ return "every finding (post_min_severity unset)";
331
+ }
package/src/ci/setup.ts CHANGED
@@ -12,8 +12,7 @@
12
12
  // caller points it at (via `crysk setup --ci` / `crysk ci init`); a repo that
13
13
  // already has the pre-rename `pr-hero.yml` keeps that file, updated in place.
14
14
  // Pillar 3 Phase 5 (tasks.md 5.2) reuses this SAME function to produce this
15
- // repo's own canonical example workflow (which stays at `pr-hero.yml`: this
16
- // repo is the existing-repo case), rather than
15
+ // repo's own canonical example workflow (at `crysk.yml`), rather than
17
16
  // hand-authoring a second copy that could silently drift from what every
18
17
  // caller of `setup --ci` actually gets — test/packaging.test.ts asserts the
19
18
  // committed file's bytes equal generateCiWorkflowTemplate()'s output exactly.
@@ -21,6 +21,7 @@ import {
21
21
  GOTCHAS_PLACEHOLDER_MARKER,
22
22
  gotchasUnusableReason,
23
23
  } from "#review/preflight";
24
+ import { REVIEW_MD_FILE_NAME, resolveReviewInstructions } from "#review/run";
24
25
  import { log } from "#ui/primitives";
25
26
  import {
26
27
  duplicateWorkflowProblem,
@@ -341,26 +342,28 @@ export async function ciSetupCommand(
341
342
  : "ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN)"
342
343
  }`,
343
344
  );
344
- // The first PR of a new repository goes red without gotchas: every hunter's
345
- // prompt carries them, and PRH-GOTCHAS-MISSING refuses the review while the
346
- // file is absent or still the scaffold. So the init steps print only then;
347
- // a repo that already wrote real gotchas is not told to write them again.
348
- // Asked through gotchasUnusableReason, the one gate the review itself uses,
349
- // so a scaffold with no marker line gets the steps it will need.
350
- const gotchasPath = path.join(resolveRepoDir(repoRoot), "gotchas.md");
351
- const gotchas = (await Bun.file(gotchasPath).exists())
352
- ? await Bun.file(gotchasPath).text()
353
- : undefined;
354
- if (gotchas === undefined || gotchasUnusableReason(gotchas) !== undefined) {
345
+ // Review instructions are optional (odd/tasks/review-md.md S3): with none
346
+ // the review runs on the default guidance, so a repo without a file gets a
347
+ // recommendation, not a required step. A file that exists but is empty or
348
+ // still the scaffold turns the first PR red (PRH-GOTCHAS-MISSING), so that
349
+ // one gets the fix steps. Asked through the resolver and the gate the review
350
+ // itself uses, so this advice cannot disagree with the run.
351
+ const instructions = resolveReviewInstructions(undefined, repoRoot);
352
+ if (instructions.path === undefined) {
355
353
  log(
356
- `${next()} Run \`npx -y crysk init\` in a clone of the repository (it creates ${repoDirName}/gotchas.md; the config.json written above is kept as it is)`,
357
- );
358
- log(
359
- `${next()} Replace the placeholder lines in ${repoDirName}/gotchas.md with real facts about this repository, and delete the ${GOTCHAS_PLACEHOLDER_MARKER} marker line if it is there: Crysk refuses to review the scaffold`,
360
- );
361
- log(
362
- `${next()} Commit ${repoDirName}/ to the default branch (comment-triggered runs read the base branch)`,
354
+ `${next()} Optional, recommended: add a ${REVIEW_MD_FILE_NAME} at the repository root with the facts a reviewer cannot infer from the diff (\`npx -y crysk init\` scaffolds one), and commit it to the default branch (comment-triggered runs read the base branch)`,
363
355
  );
356
+ } else {
357
+ const label = path.relative(repoRoot, instructions.path);
358
+ const text = await Bun.file(instructions.path).text();
359
+ if (gotchasUnusableReason(text) !== undefined) {
360
+ log(
361
+ `${next()} Write real facts about this repository into ${label} (replace any placeholder lines and delete the ${GOTCHAS_PLACEHOLDER_MARKER} marker line if it is there), or delete ${label}: Crysk refuses to review an empty or scaffold file`,
362
+ );
363
+ log(
364
+ `${next()} Commit ${label} to the default branch (comment-triggered runs read the base branch)`,
365
+ );
366
+ }
364
367
  }
365
368
  // The check to require is `crysk` (the commit status, the gate), not the
366
369
  // `review` job, which stays green even when it finds blocking issues.
@@ -8,20 +8,23 @@ import { resolveBaseRef } from "#git/refs";
8
8
  import {
9
9
  BUNDLED_AGENTS_DIR_LABEL,
10
10
  type CliOptions,
11
- GOTCHAS_TEMPLATE,
12
11
  initConfigTemplate,
13
12
  initGitReminder,
14
13
  initGotchasInstructions,
15
14
  initTemplateOmissions,
15
+ REVIEW_MD_TEMPLATE,
16
16
  } from "#review/preflight";
17
+ import { REVIEW_MD_FILE_NAME, resolveReviewInstructions } from "#review/run";
17
18
  import { log } from "#ui/primitives";
18
19
  import { readBrandEnv } from "../brand";
19
20
  import { resolveRepoDir } from "../brand-paths";
20
21
 
21
22
  // `pr-hero init` — the other half of making `pr-hero review` a zero-flag
22
- // command. It writes the two files local mode looks for and nothing else, and
23
- // it never overwrites: a config or a gotchas file already on disk is the
24
- // user's work, and the whole value of gotchas is that a human wrote them.
23
+ // command. It writes the repo config and, when the repo has no review
24
+ // instructions yet, a root REVIEW.md scaffold — and it never overwrites: a
25
+ // config or an instructions file already on disk is the user's work, and the
26
+ // whole value of the instructions is that a human wrote them. An existing
27
+ // `.crysk/gotchas.md` counts: writing a REVIEW.md beside it would shadow it.
25
28
  export async function init(options: CliOptions): Promise<number> {
26
29
  const repoRoot = await resolveRepoRoot(options.repo);
27
30
  const dir = resolveRepoDir(repoRoot);
@@ -65,12 +68,14 @@ export async function init(options: CliOptions): Promise<number> {
65
68
  // team file — the global layer is the operator's own, and scaffolding it
66
69
  // from inside a repo would be this command reaching outside its checkout.
67
70
  const repoConfigPath = path.join(dir, "config.json");
68
- const gotchasPath = path.join(dir, "gotchas.md");
71
+ const existing = resolveReviewInstructions(undefined, repoRoot);
72
+ const instructionsPath =
73
+ existing.path ?? path.join(repoRoot, REVIEW_MD_FILE_NAME);
69
74
  const wrote: string[] = [];
70
75
  const kept: string[] = [];
71
76
  for (const [file, contents] of [
72
77
  [repoConfigPath, initConfigTemplate(templateInput)],
73
- [gotchasPath, GOTCHAS_TEMPLATE],
78
+ [instructionsPath, REVIEW_MD_TEMPLATE],
74
79
  ] as const) {
75
80
  if (existsSync(file)) {
76
81
  kept.push(file);
@@ -111,15 +116,16 @@ export async function init(options: CliOptions): Promise<number> {
111
116
  // Unconditional on purpose, and NOT "consistency-fixed" below: this is
112
117
  // advice ("commit the config dir or ignore it"), true in every state this command
113
118
  // can leave the repo in. It asserts nothing about the contents of a file.
114
- log(initGitReminder(path.basename(dir)));
119
+ const reviewMdWritten = wrote.includes(instructionsPath);
120
+ log(initGitReminder(path.basename(dir), reviewMdWritten));
115
121
  log();
116
122
  // The block that follows DOES assert file contents, and the write above is
117
123
  // skipped whenever the file already exists — so it is a function of which of
118
- // `wrote`/`kept` the gotchas file landed in, never a constant. Printed
124
+ // `wrote`/`kept` the instructions file landed in, never a constant. Printed
119
125
  // unconditionally it told a repo with real gotchas to delete a marker line
120
126
  // that is not in its file. When the file was kept, the only honest source
121
127
  // for what to say about it is the gate itself, over the bytes on disk.
122
- const gotchasOutcome = wrote.includes(gotchasPath)
128
+ const gotchasOutcome = reviewMdWritten
123
129
  ? ({ written: true } as const)
124
130
  : ({
125
131
  written: false,
@@ -127,12 +133,15 @@ export async function init(options: CliOptions): Promise<number> {
127
133
  // kept — and a read that loses that race must not turn `init` into a
128
134
  // crash. An empty read renders the "empty" arm, which is the correct
129
135
  // advice for a file that is no longer there.
130
- contents: await Bun.file(gotchasPath)
136
+ contents: await Bun.file(instructionsPath)
131
137
  .text()
132
138
  .catch(() => ""),
133
139
  } as const);
134
- const dirName = path.basename(dir);
135
- for (const line of initGotchasInstructions(gotchasOutcome, dirName)) {
140
+ const instructionsLabel = path.relative(repoRoot, instructionsPath);
141
+ for (const line of initGotchasInstructions(
142
+ gotchasOutcome,
143
+ instructionsLabel,
144
+ )) {
136
145
  log(line);
137
146
  }
138
147
  return 0;