crysk 0.3.2 → 0.4.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 (66) hide show
  1. package/README.md +52 -32
  2. package/dist/SKILL-12as0f3q.md +74 -0
  3. package/dist/SKILL-2h445snn.md +140 -0
  4. package/dist/SKILL-6vy283pt.md +140 -0
  5. package/dist/SKILL-dsnffnfp.md +140 -0
  6. package/dist/SKILL-ebn0fqaq.md +140 -0
  7. package/dist/SKILL-gnrbph72.md +140 -0
  8. package/dist/SKILL-kq0xejn3.md +553 -0
  9. package/dist/SKILL-qaqsbygw.md +66 -0
  10. package/dist/SKILL-vws0aqb8.md +553 -0
  11. package/dist/ci-admission-a6d0wk1c.md +128 -0
  12. package/dist/ci-admission-t0f5qwth.md +128 -0
  13. package/dist/cli.js +14567 -14177
  14. package/dist/index.js +270 -56
  15. package/dist/review-refuter-btpgnkcd.md +77 -0
  16. package/package.json +2 -2
  17. package/prompts/default/PROVENANCE.md +1 -0
  18. package/prompts/default/review-refuter.md +6 -0
  19. package/skills/crysk/SKILL.md +3 -3
  20. package/skills/crysk-ci-setup/SKILL.md +4 -4
  21. package/skills/crysk-ci-setup/references/ci-admission.md +2 -2
  22. package/skills/crysk-loop/SKILL.md +19 -8
  23. package/skills/crysk-pr/SKILL.md +1 -1
  24. package/src/assets.ts +2 -2
  25. package/src/ci/gates.ts +9 -6
  26. package/src/ci/outcome.ts +4 -4
  27. package/src/ci/platform-config.ts +127 -0
  28. package/src/ci/platform-report.ts +702 -0
  29. package/src/ci/platform.ts +449 -0
  30. package/src/ci/reporter.ts +9 -7
  31. package/src/ci/review-admission.ts +8 -4
  32. package/src/ci/setup.ts +112 -9
  33. package/src/commands/ci-setup.ts +21 -18
  34. package/src/commands/init.ts +21 -12
  35. package/src/compare/loop.ts +9 -1
  36. package/src/compare/martian-adapter.ts +1 -1
  37. package/src/doctor.ts +48 -29
  38. package/src/index.ts +1 -1
  39. package/src/menu-context.ts +1 -1
  40. package/src/pr/admission.ts +53 -11
  41. package/src/pr/ci-admission-gate.ts +2 -1
  42. package/src/pr/finding-state-record.ts +58 -0
  43. package/src/pr/gate-record.ts +22 -0
  44. package/src/pr/inline.ts +3 -0
  45. package/src/pr/posting.ts +4 -0
  46. package/src/pr/pr-status.ts +27 -7
  47. package/src/pr/pr.ts +39 -8
  48. package/src/pr/preflight.ts +43 -1
  49. package/src/pr/publish-outcome.ts +10 -2
  50. package/src/pr/review-pr.ts +5 -3
  51. package/src/pr/target.ts +16 -3
  52. package/src/rereview/classify.ts +4 -0
  53. package/src/rereview/prepare.ts +47 -22
  54. package/src/rereview/state.ts +34 -8
  55. package/src/review/boundary.ts +2 -1
  56. package/src/review/materiality-gate.ts +25 -1
  57. package/src/review/pipeline.ts +60 -15
  58. package/src/review/preflight.ts +132 -28
  59. package/src/review/prompt-set.ts +12 -8
  60. package/src/review/report.ts +34 -14
  61. package/src/review/review.ts +14 -5
  62. package/src/review/run.ts +54 -18
  63. package/src/security/published-text.ts +161 -0
  64. package/src/triage/triage.ts +2 -1
  65. package/src/updater.ts +1 -1
  66. package/src/wizard.ts +35 -9
package/src/ci/setup.ts CHANGED
@@ -38,6 +38,13 @@ import {
38
38
  } from "node:fs/promises";
39
39
  import path from "node:path";
40
40
  import type { ErrorClass, SetupRecord } from "#ci/outcome";
41
+ import { appendGithubOutput } from "#ci/platform";
42
+ import {
43
+ assertPlatformPerson,
44
+ deliverPlatformRepoLayer,
45
+ PlatformConfigError,
46
+ readPlatformConfig,
47
+ } from "#ci/platform-config";
41
48
  import type { ConfigPlan } from "#ci/review-levels";
42
49
  import {
43
50
  OVERRIDE_COMMAND,
@@ -45,6 +52,7 @@ import {
45
52
  REVIEW_COMMAND,
46
53
  recordTempPath,
47
54
  } from "#ci/trigger";
55
+ import { resolveRepoRoot } from "#git/git";
48
56
  import { parseLocalConfig, parseRoutingConfig } from "#review/preflight";
49
57
  import { commandForms } from "../brand";
50
58
  import {
@@ -649,6 +657,13 @@ export interface MaterializeCiOpenCodeDataOptions {
649
657
  opencodeAuth?: string;
650
658
  home?: string;
651
659
  env?: Readonly<Record<string, string | undefined>>;
660
+ // Platform mode: the person layer the Crysk platform returned (`{}` when it
661
+ // sent none). Written into the same personal file as `routing`; its own
662
+ // `routing` wins over the input. Present means platform mode, in which the
663
+ // personal file belongs to this run: a file an earlier run left behind is
664
+ // removed when nothing is to be written, so it can never be read as this run's
665
+ // person layer on a runner whose HOME outlives the job.
666
+ platformPerson?: Record<string, unknown>;
652
667
  }
653
668
 
654
669
  // The file the publisher reads when this step fails on a malformed input, and
@@ -688,6 +703,8 @@ function messageOf(error: unknown): string {
688
703
  // directory — empty/unset fails loud with no cwd fallback, because falling
689
704
  // back would write routing into the checkout (.prhero/config.json), which
690
705
  // the repo parser rejects. Never log the auth blob; never inject readerFn.
706
+ // In platform mode the platform's person layer joins the routing in that one
707
+ // file; `routing` is the platform's when it sent one, else the input's, as today.
691
708
  export async function materializeCiOpenCodeData(
692
709
  options: MaterializeCiOpenCodeDataOptions = {},
693
710
  ): Promise<void> {
@@ -701,9 +718,14 @@ export async function materializeCiOpenCodeData(
701
718
 
702
719
  const routingRaw = options.routing ?? env.ROUTING_INPUT ?? "";
703
720
  const authRaw = options.opencodeAuth ?? env.OPENCODE_AUTH_INPUT ?? "";
721
+ const platformMode = options.platformPerson !== undefined;
722
+ const platformPerson = options.platformPerson ?? {};
723
+ // The input is parsed only when it is the one that will be written: a
724
+ // routing the platform overrides is not this run's configuration.
725
+ const platformRouting = platformPerson.routing !== undefined;
704
726
 
705
727
  let routingConfig: ReturnType<typeof parseRoutingConfig> | null = null;
706
- if (routingRaw.trim() !== "") {
728
+ if (routingRaw.trim() !== "" && !platformRouting) {
707
729
  let parsed: unknown;
708
730
  try {
709
731
  parsed = JSON.parse(routingRaw);
@@ -760,13 +782,20 @@ export async function materializeCiOpenCodeData(
760
782
  authBody = authRaw;
761
783
  }
762
784
 
763
- if (routingConfig !== null) {
764
- const layout = prheroLayout(home);
765
- await mkdir(layout.dir, { recursive: true });
766
- await writeFile(
767
- layout.reviewConfigPath,
768
- `${JSON.stringify({ routing: routingConfig }, null, 2)}\n`,
769
- );
785
+ const personFile = prheroLayout(home).reviewConfigPath;
786
+ // Validated whole by the engine's person parser before anything is written.
787
+ if (Object.keys(platformPerson).length > 0) {
788
+ assertPlatformPerson(platformPerson, personFile);
789
+ }
790
+ const personBody: Record<string, unknown> = {
791
+ ...platformPerson,
792
+ ...(routingConfig === null ? {} : { routing: routingConfig }),
793
+ };
794
+ if (Object.keys(personBody).length > 0) {
795
+ await mkdir(path.dirname(personFile), { recursive: true });
796
+ await writeFile(personFile, `${JSON.stringify(personBody, null, 2)}\n`);
797
+ } else if (platformMode) {
798
+ await rm(personFile, { force: true });
770
799
  }
771
800
 
772
801
  if (authBody !== undefined) {
@@ -780,6 +809,48 @@ export async function materializeCiOpenCodeData(
780
809
  interface CiOpenCodeSetupDeps {
781
810
  env: Readonly<Record<string, string | undefined>>;
782
811
  stderr: (text: string) => void;
812
+ // Where the checkout is (the engine resolves its operator root from here).
813
+ cwd: string;
814
+ appendOutput: (text: string) => void;
815
+ }
816
+
817
+ // Workflow-command data escaping, as the runner's own toolkit does it.
818
+ function escapeCommandData(text: string): string {
819
+ return text.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
820
+ }
821
+
822
+ // Platform mode only (the connect step announced a config file): the repo layer
823
+ // the platform sent reaches the run step as the `repo-config` output, which it
824
+ // passes as `--config`, but ONLY when the checkout has no repo config of its own.
825
+ // Returns whether the layer it delivered sets `post`.
826
+ async function deliverPlatformRepo(
827
+ deps: CiOpenCodeSetupDeps,
828
+ platformFile: string,
829
+ repo: Record<string, unknown>,
830
+ ): Promise<boolean> {
831
+ if (Object.keys(repo).length === 0) return false;
832
+ let root: string;
833
+ try {
834
+ root = await resolveRepoRoot(deps.cwd);
835
+ } catch (error) {
836
+ throw new PlatformConfigError(
837
+ `the checked-out repository could not be found to decide whether it has its own config: ${messageOf(error)}`,
838
+ );
839
+ }
840
+ const result = await deliverPlatformRepoLayer({
841
+ repo,
842
+ root,
843
+ dir: path.dirname(platformFile),
844
+ });
845
+ if (result.status === "repo-file-wins") {
846
+ deps.stderr(
847
+ `::notice::${escapeCommandData(`Crysk platform config: this repository has its own ${path.relative(root, result.file)}, so it is used as is and the platform's repository settings are ignored.`)}\n`,
848
+ );
849
+ } else if (result.status === "written") {
850
+ deps.appendOutput(`repo-config=${result.file}\n`);
851
+ return repo.post !== undefined;
852
+ }
853
+ return false;
783
854
  }
784
855
 
785
856
  // WHY tmp then rename, the same as the trigger's record: the publisher reads the
@@ -807,12 +878,41 @@ async function writeSetupRecord(
807
878
  // any other failure (HOME, a write) stays unclassified, with no record.
808
879
  async function runCiOpenCodeSetup(deps: CiOpenCodeSetupDeps): Promise<number> {
809
880
  try {
810
- await materializeCiOpenCodeData({ env: deps.env });
881
+ const platformFile = deps.env.CRYSK_PLATFORM_CONFIG_FILE ?? "";
882
+ const platform =
883
+ platformFile === "" ? undefined : readPlatformConfig(platformFile);
884
+ // The connect step announces a config file only when the platform sent
885
+ // configuration, so a connected run with none is told apart by this
886
+ // presence boolean: it still owns the personal file (see the option).
887
+ const platformMode =
888
+ platform !== undefined || deps.env.CRYSK_PLATFORM_CONNECTED === "true";
889
+ await materializeCiOpenCodeData({
890
+ env: deps.env,
891
+ ...(platformMode ? { platformPerson: platform?.person ?? {} } : {}),
892
+ });
893
+ // WHY the run step needs to know: it passes `--post` whenever the `post`
894
+ // input is true (the default), and an explicit CLI option outranks the
895
+ // config, so a `post` the platform set would never take effect.
896
+ let postFromPlatform = platform?.person.post !== undefined;
897
+ if (platform !== undefined) {
898
+ const repoPost = await deliverPlatformRepo(
899
+ deps,
900
+ platformFile,
901
+ platform.repo,
902
+ );
903
+ postFromPlatform ||= repoPost;
904
+ }
905
+ if (postFromPlatform) deps.appendOutput("post-from-platform=true\n");
811
906
  return 0;
812
907
  } catch (error) {
813
908
  deps.stderr(
814
909
  `crysk: failed to materialize OpenCode CI data: ${messageOf(error)}\n`,
815
910
  );
911
+ if (error instanceof PlatformConfigError) {
912
+ deps.stderr(
913
+ `::error::${escapeCommandData(`Crysk platform mode failed: ${messageOf(error)}`)}\n`,
914
+ );
915
+ }
816
916
  const outcomeDir = deps.env.CRYSK_OUTCOME_DIR ?? "";
817
917
  if (error instanceof SetupInputError && outcomeDir !== "") {
818
918
  try {
@@ -838,6 +938,9 @@ if (import.meta.main) {
838
938
  stderr: (text) => {
839
939
  process.stderr.write(text);
840
940
  },
941
+ cwd: process.cwd(),
942
+ appendOutput: (text) =>
943
+ appendGithubOutput(process.env.GITHUB_OUTPUT, text),
841
944
  }),
842
945
  );
843
946
  }
@@ -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;
@@ -7,6 +7,8 @@
7
7
  // "carried from <sha>" is a prior verdict copied to a new head (not a review),
8
8
  // "overridden" and "stopped by a maintainer" are a human ending the loop.
9
9
 
10
+ import { isManualReviewHold } from "#pr/preflight";
11
+
10
12
  export interface RawStatus {
11
13
  createdAt: string;
12
14
  context: string;
@@ -40,6 +42,7 @@ type GateEvent =
40
42
  | "unverified-fixes"
41
43
  | "budget-carried"
42
44
  | "error"
45
+ | "held"
43
46
  | "pending"
44
47
  | "other-success"
45
48
  | "other-failure";
@@ -55,7 +58,11 @@ export function classifyStatus(status: RawStatus): GateEvent {
55
58
  const d = status.description ?? "";
56
59
  switch (status.state) {
57
60
  case "pending":
58
- return "pending";
61
+ // Since Stage 2 #12 a capped rule (budget used up, manual_only) holds the head pending until a
62
+ // human acts. No run holds it, so it is not a review in flight: it is a head that is not green.
63
+ return isManualReviewHold({ state: status.state, description: d })
64
+ ? "held"
65
+ : "pending";
59
66
  case "error":
60
67
  return "error";
61
68
  case "success":
@@ -145,6 +152,7 @@ const NOT_GREEN = new Set<GateEvent>([
145
152
  "budget-exhausted",
146
153
  "size-skipped",
147
154
  "error",
155
+ "held",
148
156
  "other-failure",
149
157
  ]);
150
158
 
@@ -1,6 +1,6 @@
1
1
  // Project a pr-hero findings.json onto Martian's offline candidate shape.
2
2
  // Pure: no I/O, no judge, no precision/recall. The judge is theirs; this
3
- // only makes our artifacts injectable. See docs/martian-bench.md.
3
+ // only makes our artifacts injectable. See benchmarks/martian/README.md.
4
4
 
5
5
  import type { Finding } from "#review/findings";
6
6
 
package/src/doctor.ts CHANGED
@@ -13,7 +13,11 @@ import {
13
13
  localReviewSpec,
14
14
  resolveAgentsDirSetting,
15
15
  } from "#review/preflight";
16
- import { resolveGotchasPath } from "#review/run";
16
+ import {
17
+ REVIEW_MD_FILE_NAME,
18
+ resolveReviewInstructions,
19
+ shadowedGotchasNotice,
20
+ } from "#review/run";
17
21
  import {
18
22
  detectAgentEnvironments,
19
23
  inspectMcpRegistration,
@@ -437,39 +441,54 @@ export async function runDoctor(
437
441
  }
438
442
  }
439
443
 
440
- // 3. Gotchas check (only when repo root is supplied or discovered)
444
+ // 3. Review instructions check: REVIEW.md, else gotchas (only when repo root
445
+ // is supplied or discovered). Same resolver and predicate the review gates
446
+ // use, and that is the point: a doctor that answers this question its own
447
+ // way eventually green-lights a file the very next command refuses, or
448
+ // blocks on an absence the review accepts, and the user then hunts for the
449
+ // problem somewhere it is not.
441
450
  if (repoDir) {
442
- const gotchasPath = resolveGotchasPath(undefined, repoDir, exists);
443
- const gotchasContent = exists(gotchasPath)
444
- ? readFile(gotchasPath)
445
- : undefined;
446
- // Same predicate the review gates use, and that is the point: a doctor
447
- // that answers this question its own way eventually green-lights a file
448
- // the very next command refuses, and the user then hunts for the problem
449
- // somewhere it is not.
450
- const unusable = gotchasUnusableReason(gotchasContent ?? "");
451
- if (unusable === "placeholder") {
451
+ const instructions = resolveReviewInstructions(undefined, repoDir, exists);
452
+ if (instructions.path === undefined) {
452
453
  checks.push({
453
454
  name: "gotchas",
454
- severity: "blocking",
455
- message: `Repository gotchas file (${repoDirName}/gotchas.md) is still the untouched scaffold`,
456
- hint:
457
- `Replace the placeholder lines with real repository invariants, and delete the \`${GOTCHAS_PLACEHOLDER_MARKER}\` ` +
458
- "marker line at the top if it is still there — Crysk refuses to review the scaffold.",
459
- });
460
- } else if (unusable !== undefined) {
461
- checks.push({
462
- name: "gotchas",
463
- severity: "blocking",
464
- message: `Repository gotchas file (${repoDirName}/gotchas.md) is empty or missing`,
465
- hint: `Create and populate ${repoDirName}/gotchas.md with repository-specific invariants and failure traps.`,
455
+ severity: "degraded",
456
+ message: `No review instructions (${REVIEW_MD_FILE_NAME} or ${repoDirName}/gotchas.md): reviews run with the default guidance only`,
457
+ hint: `Add a ${REVIEW_MD_FILE_NAME} at the repository root with the facts the diff does not show: deliberate oddities, invariants enforced elsewhere, conventions a newcomer would break.`,
466
458
  });
467
459
  } else {
468
- checks.push({
469
- name: "gotchas",
470
- severity: "healthy",
471
- message: `Repository gotchas present (${repoDirName}/gotchas.md)`,
472
- });
460
+ const label = path.relative(repoDir, instructions.path);
461
+ const unusable = gotchasUnusableReason(readFile(instructions.path) ?? "");
462
+ if (unusable === "placeholder") {
463
+ checks.push({
464
+ name: "gotchas",
465
+ severity: "blocking",
466
+ message: `Repository review instructions (${label}) are still the untouched scaffold`,
467
+ hint:
468
+ `Replace the placeholder lines with real repository rules and invariants, and delete the \`${GOTCHAS_PLACEHOLDER_MARKER}\` ` +
469
+ "marker line at the top if it is still there — Crysk refuses to review the scaffold.",
470
+ });
471
+ } else if (unusable !== undefined) {
472
+ checks.push({
473
+ name: "gotchas",
474
+ severity: "blocking",
475
+ message: `Repository review instructions (${label}) are empty`,
476
+ hint: `Write repository-specific rules and invariants into ${label}, or delete it to review with the default guidance only.`,
477
+ });
478
+ } else if (instructions.shadowed !== undefined) {
479
+ checks.push({
480
+ name: "gotchas",
481
+ severity: "degraded",
482
+ message: shadowedGotchasNotice(instructions.shadowed),
483
+ hint: `Move what ${path.relative(repoDir, instructions.shadowed)} says into ${REVIEW_MD_FILE_NAME}, then delete it.`,
484
+ });
485
+ } else {
486
+ checks.push({
487
+ name: "gotchas",
488
+ severity: "healthy",
489
+ message: `Repository review instructions present (${label})`,
490
+ });
491
+ }
473
492
  }
474
493
  }
475
494
 
package/src/index.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  // Public API surface; the deep-review lab consumes exactly these exports.
3
3
 
4
4
  export const ENGINE_NAME = "pr-hero";
5
- export const ENGINE_VERSION = "0.3.2";
5
+ export const ENGINE_VERSION = "0.4.0";
6
6
 
7
7
  // errors and git/refs used to reach this surface only through re-exports in
8
8
  // review/preflight.ts; they are exported directly now that those re-exports
@@ -120,7 +120,7 @@ export function getMenuOptions(
120
120
  items.push({
121
121
  id: "init",
122
122
  label: "Initialize repo",
123
- desc: "Scaffold <repo>/.crysk/ config & gotchas",
123
+ desc: "Scaffold <repo>/.crysk/ config and a REVIEW.md",
124
124
  cliHint: "init",
125
125
  action: "init",
126
126
  });
@@ -38,6 +38,8 @@ import {
38
38
  type CommitStatusFact,
39
39
  clipStatusDescription,
40
40
  commitStatusRequest,
41
+ heldVerdictSha,
42
+ manualReviewHoldDescription,
41
43
  partialReviewAgainDescription,
42
44
  partialReviewDescription,
43
45
  prHtmlUrl,
@@ -318,7 +320,7 @@ export interface AdmissionStatusInput {
318
320
  }
319
321
 
320
322
  export interface AdmissionStatusDecision {
321
- state: "success" | "failure";
323
+ state: "success" | "failure" | "pending";
322
324
  description: string;
323
325
  }
324
326
 
@@ -335,13 +337,21 @@ type CarriedReason = Exclude<AdmissionStatusReason, "same-head">;
335
337
 
336
338
  // Every rule that skips a review carries the last verdict the same way (budget-exhausted-carry S2): the
337
339
  // rule is respected, so no review runs, and the head reads what the last review decided. Same-head is the
338
- // one exception: that head's own status already exists.
340
+ // one exception: that head's own status already exists. A capped rule holds a green (holdsForManualReview).
339
341
  function isCarriedReason(
340
342
  reason: AdmissionStatusReason,
341
343
  ): reason is CarriedReason {
342
344
  return reason !== "same-head";
343
345
  }
344
346
 
347
+ // ROADMAP Stage 2 #12: the rules that cap automatic reviews. Under them no later push is reviewed on its
348
+ // own, so carrying a green would let code no review read merge (measured: one PR merged green over 11
349
+ // unreviewed commits).
350
+ // The head waits for a manual review instead; a red still carries, since it already blocks.
351
+ function holdsForManualReview(reason: CarriedReason): boolean {
352
+ return reason === "max-attempts-exhausted" || reason === "manual-only-policy";
353
+ }
354
+
345
355
  // The readers below rewrite a legacy `pr-hero` lead into `crysk` first (canonicalStatusText), so the
346
356
  // patterns and the builders speak one spelling.
347
357
  const BLOCKING_COUNT = /^crysk: (\d+) blocking finding\(s\)/;
@@ -601,6 +611,12 @@ export function admissionSkipDecision(
601
611
  const verdict = newestCarriedVerdict(input.carried.statuses);
602
612
  if (verdict === undefined) return failClosed(label);
603
613
  if (verdict.state === "success") {
614
+ if (holdsForManualReview(input.reason)) {
615
+ return {
616
+ state: "pending",
617
+ description: manualReviewHoldDescription(label, input.carried.sha),
618
+ };
619
+ }
604
620
  // A carried unverified green stays unverified: chaining it never turns it into a green a review earned.
605
621
  const answeredCount = answeredCountIn(verdict.description ?? "");
606
622
  return {
@@ -638,6 +654,12 @@ export function admissionSkipDecision(
638
654
  answered.blocking > 0 &&
639
655
  answered.blocking >= blocking
640
656
  ) {
657
+ if (holdsForManualReview(input.reason)) {
658
+ return {
659
+ state: "pending",
660
+ description: manualReviewHoldDescription(label, input.carried.sha),
661
+ };
662
+ }
641
663
  return {
642
664
  state: "success",
643
665
  description: unverifiedFixesDescription(
@@ -676,6 +698,10 @@ const CARRY_WALK_CAP = 20;
676
698
  // missing from the list fails closed.
677
699
  // WHY a failed read ends the walk: a commit whose statuses did not read is not a commit with no verdict,
678
700
  // so skipping it would carry an older verdict across a read that never happened.
701
+ // WHY a hold redirects the walk (Stage 2 #12): a hold is no verdict, but it names the commit whose verdict
702
+ // it held. Under a used-up budget every push is held, so without the jump a PR with more commits since its
703
+ // last review than the cap would fail closed red although that review is still on the PR. The jump only
704
+ // ever moves to an older commit, so the walk ends, and the cap restarts from the commit it lands on.
679
705
  async function findCarriedVerdict(input: {
680
706
  operatorRoot: string;
681
707
  prNumber: number;
@@ -690,17 +716,33 @@ async function findCarriedVerdict(input: {
690
716
  if (shas === null) return null;
691
717
  const headIndex = shas.indexOf(input.headSha);
692
718
  if (headIndex < 0) return null;
693
- const earlier = shas.slice(0, headIndex).reverse().slice(0, CARRY_WALK_CAP);
694
- for (const sha of earlier) {
695
- const statuses = await input.readStatuses(input.operatorRoot, sha, {
696
- spawnFn: input.spawnFn,
697
- });
698
- if (statuses === null) return null;
699
- if (newestCarriedVerdict(statuses) !== undefined) {
700
- return { sha, statuses, older: earlier.slice(earlier.indexOf(sha) + 1) };
719
+ let end = headIndex;
720
+ walk: while (true) {
721
+ const earlier = shas.slice(0, end).reverse().slice(0, CARRY_WALK_CAP);
722
+ for (const sha of earlier) {
723
+ const statuses = await input.readStatuses(input.operatorRoot, sha, {
724
+ spawnFn: input.spawnFn,
725
+ });
726
+ if (statuses === null) return null;
727
+ if (newestCarriedVerdict(statuses) !== undefined) {
728
+ return {
729
+ sha,
730
+ statuses,
731
+ older: earlier.slice(earlier.indexOf(sha) + 1),
732
+ };
733
+ }
734
+ const newest = newestStatusInContext(statuses, COMMIT_STATUS_CONTEXT);
735
+ const held = newest === undefined ? null : heldVerdictSha(newest);
736
+ if (held !== null) {
737
+ const target = shas.findIndex((s) => s.startsWith(held));
738
+ if (target >= 0 && target < shas.indexOf(sha)) {
739
+ end = target + 1;
740
+ continue walk;
741
+ }
742
+ }
701
743
  }
744
+ return null;
702
745
  }
703
- return null;
704
746
  }
705
747
 
706
748
  // WHY the head's override holds: a human's `/pr-hero override` on this head is the decision for it. A
@@ -176,6 +176,7 @@ export async function evaluateCiAdmissionGate(input: {
176
176
  }
177
177
  const trustedActors = resolveCiTrustedActors({
178
178
  githubActor: process.env.GITHUB_ACTOR,
179
+ platformActor: process.env.CRYSK_PLATFORM_ACTOR,
179
180
  extra: config.ci_trusted_actors,
180
181
  });
181
182
  const allComments = [...reviewComments, ...issueComments];
@@ -387,7 +388,7 @@ export async function evaluateCiAdmissionGate(input: {
387
388
  advisoryCount: admissionVerdict.prior.advisory,
388
389
  });
389
390
  // S2: manual-required carries the last verdict like every other skip (publishCiSkip,
390
- // admissionSkipDecision); a carried red with every blocking finding answered turns green, unverified.
391
+ // admissionSkipDecision), except a green: Stage 2 #12 holds it pending for a manual review.
391
392
  const plan = planCiReviewManualRequired({
392
393
  prNumber,
393
394
  verdict: admissionVerdict,