crysk 0.3.2 → 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.
@@ -315,7 +315,7 @@ Usage:
315
315
  crysk [options] Open interactive terminal user interface (TTY)
316
316
  crysk menu [options] Open interactive terminal user interface
317
317
  crysk review [options] Review a branch (zero flags inside a configured repo)
318
- 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
319
319
  crysk setup [options] Run interactive onboarding wizard
320
320
  crysk setup --ci [--force] [--level <l>] [--ci-mode <m>] [--billing <b>] [--budget-usd <n>]
321
321
  Scaffold .github/workflows/crysk.yml (or update
@@ -501,8 +501,10 @@ Options:
501
501
  deferred. Not required — deferred is a tag plus
502
502
  reasoning; the coding agent decides whether an issue
503
503
  exists
504
- --gotchas <file> Repo gotchas file (default: <repo>/.crysk/gotchas.md);
505
- 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
506
508
  --config <file> Local config (default: <repo>/.crysk/config.json) with
507
509
  agents_dir, default_base, parity_trigger_paths and
508
510
  suspicion_priors, optional summary settings, and
@@ -3419,11 +3421,17 @@ export function initConfigTemplate(input: InitTemplateInput): string {
3419
3421
  // dirty" has no way to connect the two.
3420
3422
  // `dirName` is the directory the command actually wrote into (an existing
3421
3423
  // legacy .prhero/ is updated in place), so the advice names a real path.
3422
- 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 {
3423
3431
  return (
3424
- `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 ` +
3425
3433
  "reads the checkout directly, so Crysk refuses to run on a dirty tree — " +
3426
- `and an untracked ${dirName}/ is exactly that.`
3434
+ `and an untracked ${reviewMd ? `${dirName}/ or REVIEW.md` : `${dirName}/`} is exactly that.`
3427
3435
  );
3428
3436
  }
3429
3437
 
@@ -3459,9 +3467,40 @@ verbatim into every hunter's system prompt, so keep them short and true.
3459
3467
  - <subsystem>: <the naming/ownership rule a newcomer would violate>
3460
3468
  `;
3461
3469
 
3462
- // `pr-hero setup`'s fallback scaffold (wizard.ts writes it when onboarding
3463
- // collected zero invariants). It lives here, beside GOTCHAS_TEMPLATE, so the
3464
- // 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.
3465
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`;
3466
3505
 
3467
3506
  // Every non-blank line the two scaffolds write, minus the marker line. A file
@@ -3476,10 +3515,13 @@ export const SETUP_GOTCHAS_FALLBACK = `<!-- ${GOTCHAS_PLACEHOLDER_MARKER}: zero
3476
3515
  // setup fallback's sentence did, in 60c28c6.)
3477
3516
  const RETIRED_SCAFFOLD_LINES = [
3478
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.",
3479
3521
  ];
3480
3522
 
3481
3523
  const SCAFFOLD_BODY_LINES = new Set([
3482
- ...[GOTCHAS_TEMPLATE, SETUP_GOTCHAS_FALLBACK]
3524
+ ...[GOTCHAS_TEMPLATE, SETUP_GOTCHAS_FALLBACK, REVIEW_MD_TEMPLATE]
3483
3525
  .flatMap((scaffold) => scaffold.split("\n"))
3484
3526
  .map((line) => line.trim())
3485
3527
  .filter(
@@ -3516,6 +3558,34 @@ export function gotchasUnusableReason(
3516
3558
  return undefined;
3517
3559
  }
3518
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
+
3519
3589
  // `pr-hero init`'s closing instruction block, as data.
3520
3590
  //
3521
3591
  // WHY it is a function of the outcome rather than a constant: `init` never
@@ -3535,12 +3605,14 @@ export function gotchasUnusableReason(
3535
3605
  // The union is discriminated rather than a pair of optional fields on
3536
3606
  // purpose: there is no `{ written: true, contents }` to get wrong, and no
3537
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.
3538
3610
  export function initGotchasInstructions(
3539
3611
  outcome: { written: true } | { written: false; contents: string },
3540
- dirName: string = REPO_DIR_NAME,
3612
+ file: string,
3541
3613
  ): string[] {
3542
3614
  if (outcome.written) {
3543
- // 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
3544
3616
  // carry `<subsystem>` lines and the marker.
3545
3617
  //
3546
3618
  // "refuses to run without it" was true of an ABSENT file and false of the
@@ -3549,25 +3621,30 @@ export function initGotchasInstructions(
3549
3621
  // placeholders. The marker is what makes the old sentence true, so the
3550
3622
  // instruction has to name the marker.
3551
3623
  return [
3552
- `Then edit ${dirName}/gotchas.md — two steps, both required:`,
3624
+ `Then edit ${file} — two steps, both required:`,
3553
3625
  " 1. replace the <subsystem> lines with facts about this repo",
3554
3626
  ` 2. delete the \`${GOTCHAS_PLACEHOLDER_MARKER}\` marker line at the top`,
3555
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
+ "",
3556
3632
  "Crysk refuses to review while that marker is present. It is not " +
3557
3633
  "pedantry: the file above is non-empty, so without the marker a " +
3558
3634
  "review would bill in full for hunters primed with placeholder text " +
3559
- "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.",
3560
3637
  ];
3561
3638
  }
3562
3639
 
3563
3640
  const reason = gotchasUnusableReason(outcome.contents);
3564
3641
  if (reason === "placeholder") {
3565
3642
  // NOT "replace the <subsystem> lines": a kept scaffold may be `pr-hero
3566
- // setup`'s fallback (wizard.ts), which carries the marker and has no
3643
+ // setup`'s old fallback, which carries the marker and has no
3567
3644
  // `<subsystem>` lines at all. Naming them would be this same defect one
3568
3645
  // layer down.
3569
3646
  return [
3570
- `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 ` +
3571
3648
  `the \`${GOTCHAS_PLACEHOLDER_MARKER}\` marker line or nothing but the ` +
3572
3649
  "scaffold's own lines, and Crysk refuses to review it.",
3573
3650
  "",
@@ -3579,39 +3656,53 @@ export function initGotchasInstructions(
3579
3656
  // No marker in an empty file, so nothing to delete — saying otherwise
3580
3657
  // would send the reader looking for a line that is not there.
3581
3658
  return [
3582
- `The ${dirName}/gotchas.md already on disk is empty, and Crysk refuses ` +
3583
- "to review without gotchas: an empty file makes the whole review a " +
3584
- "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.",
3585
3662
  "",
3586
3663
  "Write facts about THIS repo into it — the deliberate oddities, the " +
3587
- "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.",
3588
3666
  ];
3589
3667
  }
3590
3668
  // Deliberately modest wording. The gate proves only that the file is
3591
3669
  // non-empty and marker-free; it does not prove the contents are good, so
3592
3670
  // this line reports the gate and claims nothing beyond it.
3593
3671
  return [
3594
- `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 ` +
3595
3673
  "be used as-is.",
3596
3674
  ];
3597
3675
  }
3598
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
+
3599
3683
  // The pipeline treats unusable gotchas as a fail-loud abort and returns a
3600
3684
  // zero-cost partial run. Correct, but a bare "partial, 0 findings" tells the
3601
- // 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.
3602
3690
  export function gotchasErrorMessage(
3603
3691
  gotchasPath: string,
3604
3692
  reason: GotchasUnusableReason,
3693
+ present: boolean,
3605
3694
  ): string {
3606
3695
  const why = [
3607
- "Gotchas are the repo-specific facts a hunter cannot infer from the diff",
3608
- "— deliberate oddities, invariants enforced elsewhere, conventions worth",
3609
- "more than they look. They are injected verbatim into every hunter's",
3610
- "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.",
3611
3702
  ];
3612
3703
  if (reason === "placeholder") {
3613
3704
  return [
3614
- `gotchas file is still the scaffold nobody filled in: ${gotchasPath}`,
3705
+ `review instructions file is still the scaffold nobody filled in: ${gotchasPath}`,
3615
3706
  "",
3616
3707
  ...why,
3617
3708
  "",
@@ -3621,7 +3712,20 @@ export function gotchasErrorMessage(
3621
3712
  "placeholder text, and return a clean-LOOKING result.",
3622
3713
  "",
3623
3714
  "Replace the placeholder lines with facts about THIS repo, and delete",
3624
- "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.",
3625
3729
  ].join("\n");
3626
3730
  }
3627
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:
@@ -49,12 +49,14 @@ import {
49
49
  computeDiffStatAndSizeGate,
50
50
  enforceCapabilityGate,
51
51
  loadRunConfig,
52
+ NO_INSTRUCTIONS_NOTICE,
52
53
  prepareRunnerForRoute,
53
- resolveGotchasPath,
54
54
  resolveParityFires,
55
55
  resolvePipelineRoute,
56
56
  resolvePromptSet,
57
+ resolveReviewInstructions,
57
58
  selectActiveHunters,
59
+ shadowedGotchasNotice,
58
60
  validateGotchas,
59
61
  writeMcpConfig,
60
62
  writeRunFindings,
@@ -151,16 +153,23 @@ export async function review(options: CliOptions): Promise<number> {
151
153
  );
152
154
  const { dir: agentsDir, source: agentsDirSource } = agents;
153
155
 
154
- // 7 — gotchas. Checked HERE rather than left to the pipeline's fail-loud
155
- // abort: the pipeline is right to refuse, but all it can return is a
156
- // zero-cost partial run, which reads like a clean review to a human.
156
+ // 7 — review instructions (REVIEW.md, else gotchas). Checked HERE rather
157
+ // than left to the pipeline's fail-loud abort: the pipeline is right to
158
+ // refuse, but all it can return is a zero-cost partial run, which reads like
159
+ // a clean review to a human. Neither file existing is allowed (the review
160
+ // runs with the default guidance); a present one must be real.
157
161
  //
158
162
  // `--gotchas` exists because requiring the file INSIDE the reviewed tree
159
163
  // makes two legitimate cases impossible: reviewing a historical commit (the
160
164
  // file would be an untracked addition, and the clean-tree gate rightly
161
165
  // refuses), and reviewing a repo you do not control. The gotchas describe
162
166
  // the repo, not the commit, so they do not belong to the checkout.
163
- const gotchasPath = resolveGotchasPath(options.gotchas, repoRoot);
167
+ const instructions = resolveReviewInstructions(options.gotchas, repoRoot);
168
+ if (instructions.shadowed !== undefined) {
169
+ log(shadowedGotchasNotice(instructions.shadowed));
170
+ }
171
+ if (instructions.path === undefined) log(NO_INSTRUCTIONS_NOTICE);
172
+ const gotchasPath = instructions.path;
164
173
  await validateGotchas(gotchasPath);
165
174
 
166
175
  // 7.5 — `.prheroignore`, read from the WORKING TREE. Local review has no
package/src/review/run.ts CHANGED
@@ -14,6 +14,7 @@
14
14
  // registerActiveRun and the try/finally around runPipeline stay call-site
15
15
  // owned: their POSITION differs between the orchestrators, not their data.
16
16
 
17
+ import { existsSync } from "node:fs";
17
18
  import path from "node:path";
18
19
  import {
19
20
  type EffectiveConfig,
@@ -154,33 +155,68 @@ export function assertDistinctRange(baseSha: string, headSha: string): void {
154
155
  }
155
156
  }
156
157
 
157
- // The gotchas file path: an explicit `--gotchas` flag always wins (resolved
158
- // against cwd, exactly like path.resolve did inline); otherwise it is
159
- // `<root>/.crysk/gotchas.md` (or the legacy `.prhero/`). `root` is the caller's own root — repoRoot in
160
- // review(), operatorRoot in reviewPr(), repoDir in doctor.ts's default-branch
161
- // check — never resolved here, so this stays agnostic of which mode called
162
- // it.
163
- export function resolveGotchasPath(
158
+ // The repository's review instructions (odd/tasks/review-md.md S2/S3). An
159
+ // explicit `--gotchas` flag always wins (resolved against cwd). Otherwise a
160
+ // root `REVIEW.md` — the format Claude Code Review reads — and only when it is
161
+ // absent `<root>/.crysk/gotchas.md` (or the legacy `.prhero/`). One file is
162
+ // effective, never both: a present REVIEW.md that is empty or still a scaffold
163
+ // is refused, it does not fall through to gotchas.md (the same rule the ignore
164
+ // file keeps, git.ts readBaseRefIgnoreRules). `shadowed` names a gotchas file
165
+ // REVIEW.md overrides, so the shells can say it is ignored instead of the
166
+ // hunters silently losing it. `path: undefined` means neither file exists:
167
+ // the review runs with the default guidance only. `root` is the caller's own
168
+ // root — repoRoot in review(), operatorRoot in reviewPr(), repoDir in
169
+ // doctor.ts — never resolved here.
170
+ export const REVIEW_MD_FILE_NAME = "REVIEW.md";
171
+
172
+ export interface ReviewInstructions {
173
+ path: string | undefined;
174
+ shadowed?: string;
175
+ }
176
+
177
+ export function resolveReviewInstructions(
164
178
  flag: string | undefined,
165
179
  root: string,
166
- exists?: (p: string) => boolean,
167
- ): string {
168
- return flag !== undefined
169
- ? path.resolve(flag)
170
- : path.join(resolveRepoDir(root, exists), "gotchas.md");
180
+ exists: (p: string) => boolean = existsSync,
181
+ ): ReviewInstructions {
182
+ if (flag !== undefined) return { path: path.resolve(flag) };
183
+ const reviewMd = path.join(root, REVIEW_MD_FILE_NAME);
184
+ const gotchas = path.join(resolveRepoDir(root, exists), "gotchas.md");
185
+ if (exists(reviewMd)) {
186
+ return exists(gotchas)
187
+ ? { path: reviewMd, shadowed: gotchas }
188
+ : { path: reviewMd };
189
+ }
190
+ return { path: exists(gotchas) ? gotchas : undefined };
171
191
  }
172
192
 
173
- // Byte-identical gotchas read + validation in both orchestrators. Neither
174
- // caller reads the text afterward (only `gotchasPath` goes on to the
175
- // pipeline), so this validates and returns nothing.
176
- export async function validateGotchas(gotchasPath: string): Promise<void> {
193
+ // The one line every shell prints when REVIEW.md shadows a gotchas file.
194
+ export function shadowedGotchasNotice(shadowed: string): string {
195
+ return `${path.basename(shadowed)} ignored: ${REVIEW_MD_FILE_NAME} takes precedence (${shadowed})`;
196
+ }
197
+
198
+ // What every shell prints when the repo has no instructions file: the run
199
+ // still spends, so the absence must not be silent (a misnamed `review.md` or a
200
+ // file missing from the default branch would otherwise look like a normal run).
201
+ export const NO_INSTRUCTIONS_NOTICE = `no review instructions found (${REVIEW_MD_FILE_NAME} or .crysk/gotchas.md): reviewing with the default guidance only`;
202
+
203
+ // Byte-identical instructions read + validation in both orchestrators. Neither
204
+ // caller reads the text afterward (only the path goes on to the pipeline), so
205
+ // this validates and returns nothing. No path is the opt-out (S3) and passes;
206
+ // a path whose file is missing — only an explicit `--gotchas` can name one —
207
+ // reads as empty and is refused, as it always was.
208
+ export async function validateGotchas(
209
+ gotchasPath: string | undefined,
210
+ ): Promise<void> {
211
+ if (gotchasPath === undefined) return;
177
212
  const file = Bun.file(gotchasPath);
178
- const gotchas = (await file.exists()) ? await file.text() : "";
213
+ const present = await file.exists();
214
+ const gotchas = present ? await file.text() : "";
179
215
  const unusable = gotchasUnusableReason(gotchas);
180
216
  if (unusable !== undefined) {
181
217
  // The class carries the gate's reason into cli.json (T2d-1). Both reasons render
182
218
  // the one gotchas code today; the reason stays on the record for that reason only.
183
- throw new CliError(gotchasErrorMessage(gotchasPath, unusable), {
219
+ throw new CliError(gotchasErrorMessage(gotchasPath, unusable, present), {
184
220
  cls: { kind: "gotchas", reason: unusable },
185
221
  });
186
222
  }
package/src/updater.ts CHANGED
@@ -54,7 +54,7 @@ export function detectInstallMethod(
54
54
  ): InstallMethod {
55
55
  const home = options.home ?? os.homedir();
56
56
  const execPath = options.execPath ?? process.execPath;
57
- const version = options.version ?? "0.3.2";
57
+ const version = options.version ?? "0.3.3";
58
58
  const exists = options.exists ?? existsSync;
59
59
 
60
60
  const isSource =
package/src/wizard.ts CHANGED
@@ -5,8 +5,9 @@ import {
5
5
  GOTCHAS_PLACEHOLDER_MARKER,
6
6
  initConfigTemplate,
7
7
  initGitReminder,
8
- SETUP_GOTCHAS_FALLBACK,
8
+ REVIEW_MD_TEMPLATE,
9
9
  } from "#review/preflight";
10
+ import { REVIEW_MD_FILE_NAME, resolveReviewInstructions } from "#review/run";
10
11
  import {
11
12
  type AgentEnvDetection,
12
13
  detectAgentEnvironments,
@@ -82,6 +83,11 @@ export interface WizardState {
82
83
  // The directory step 4 wrote into (.crysk, or a legacy .prhero updated in
83
84
  // place), so the closing advice names a path that exists.
84
85
  repoDirName?: string;
86
+ // The instructions file step 4 scaffolded or found (repo-relative), and
87
+ // whether this run wrote a root REVIEW.md — which the git reminder must
88
+ // name, since it is untracked outside the config dir.
89
+ instructionsFile?: string;
90
+ reviewMdWritten?: boolean;
85
91
  // "this run wrote the PLACEHOLDER gotchas file" — the no-entries fallback
86
92
  // branch, the only one that emits GOTCHAS_PLACEHOLDER_MARKER. Writing
87
93
  // `gotchas.md` is not enough: with entries collected, the file written is
@@ -620,7 +626,16 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
620
626
 
621
627
  const repoDir = resolveRepoDir(cwd, exists);
622
628
  const configPath = path.join(repoDir, "config.json");
623
- const gotchasPath = path.join(repoDir, "gotchas.md");
629
+ // REVIEW.md at the root unless the repo already has instructions: an
630
+ // existing gotchas file is the user's work, and a REVIEW.md written
631
+ // beside it would shadow it (odd/tasks/review-md.md S2/S7).
632
+ const existingInstructions = resolveReviewInstructions(
633
+ undefined,
634
+ cwd,
635
+ exists,
636
+ );
637
+ const gotchasPath =
638
+ existingInstructions.path ?? path.join(cwd, REVIEW_MD_FILE_NAME);
624
639
 
625
640
  const isGit = await exec(["git", "rev-parse", "--is-inside-work-tree"], {
626
641
  cwd,
@@ -633,6 +648,7 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
633
648
  // one. These start false and are set by the branch that actually writes.
634
649
  let workspaceFilesWritten = false;
635
650
  let placeholderGotchasWritten = false;
651
+ let reviewMdWritten = false;
636
652
 
637
653
  if (isRepo) {
638
654
  // 1. Write <repo dir>/config.json if not present
@@ -644,15 +660,15 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
644
660
  workspaceFilesWritten = true;
645
661
  }
646
662
 
647
- // 2. Write <repo dir>/gotchas.md if not present
663
+ // 2. Write the root REVIEW.md if the repo has no instructions yet
648
664
  if (!exists(gotchasPath)) {
649
665
  let gotchasContent: string;
650
666
  if (state.gotchas.entries && state.gotchas.entries.length > 0) {
651
- gotchasContent = `# Repository Gotchas & Invariants\n\n${state.gotchas.entries.map((e) => `- ${e}`).join("\n")}\n`;
667
+ gotchasContent = `# Review instructions\n\n${state.gotchas.entries.map((e) => `- ${e}`).join("\n")}\n`;
652
668
  } else {
653
669
  // Shared with the gotchas gate (preflight.ts), so the gate still
654
670
  // recognises this scaffold after its marker line is deleted.
655
- gotchasContent = SETUP_GOTCHAS_FALLBACK;
671
+ gotchasContent = REVIEW_MD_TEMPLATE;
656
672
  // Set HERE, in the branch that emits the marker, and nowhere
657
673
  // else: it is the marker that makes step 5's placeholder warning
658
674
  // true, so the flag is set by the code that writes the marker.
@@ -660,6 +676,7 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
660
676
  }
661
677
  await writeFile(gotchasPath, gotchasContent);
662
678
  workspaceFilesWritten = true;
679
+ reviewMdWritten = existingInstructions.path === undefined;
663
680
  }
664
681
  }
665
682
 
@@ -675,6 +692,9 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
675
692
  let workspaceCommitted = false;
676
693
  if (isRepo && state.commitChoice === "commit") {
677
694
  await exec(["git", "add", path.basename(repoDir)], { cwd });
695
+ if (exists(path.join(cwd, REVIEW_MD_FILE_NAME))) {
696
+ await exec(["git", "add", REVIEW_MD_FILE_NAME], { cwd });
697
+ }
678
698
  const commitRes = await exec(
679
699
  [
680
700
  "git",
@@ -699,6 +719,8 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
699
719
  return {
700
720
  workspaceFilesWritten,
701
721
  repoDirName: path.basename(repoDir),
722
+ instructionsFile: path.relative(cwd, gotchasPath),
723
+ reviewMdWritten,
702
724
  placeholderGotchasWritten,
703
725
  setupStateWritten: true,
704
726
  workspaceCommitted,
@@ -710,10 +732,12 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
710
732
  ): string[] {
711
733
  const lines: string[] = [];
712
734
  const bold = (s: string) => (opts.styles ? `\x1b[1m${s}\x1b[0m` : s);
713
- lines.push(bold("Step 4/5: Workspace Configuration & Gotchas"));
735
+ lines.push(
736
+ bold("Step 4/5: Workspace Configuration & Review Instructions"),
737
+ );
714
738
  lines.push("");
715
739
  lines.push(
716
- " Scaffolding config.json and gotchas.md in .crysk/ (or the .prhero/ the repo already has)",
740
+ " Scaffolding config.json in .crysk/ (or the .prhero/ the repo already has) and a REVIEW.md, unless the repo already has review instructions",
717
741
  );
718
742
  return lines;
719
743
  },
@@ -798,7 +822,9 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
798
822
  lines.push("");
799
823
  }
800
824
  if (needsGitStep) {
801
- lines.push(` ${initGitReminder(repoDirName)}`);
825
+ lines.push(
826
+ ` ${initGitReminder(repoDirName, state.reviewMdWritten === true)}`,
827
+ );
802
828
  lines.push("");
803
829
  }
804
830
  if (needsGotchasStep) {
@@ -813,7 +839,7 @@ export const WIZARD_STEPS: readonly WizardStepDescriptor[] = [
813
839
  // which is the same untestable-by-design trap this slice exists to
814
840
  // remove.
815
841
  lines.push(
816
- ` Write REAL gotchas in ${repoDirName}/gotchas.md — the one just ` +
842
+ ` Write REAL review instructions in ${state.instructionsFile ?? REVIEW_MD_FILE_NAME} — the one just ` +
817
843
  "scaffolded is a placeholder, and Crysk refuses to review " +
818
844
  `while its \`${GOTCHAS_PLACEHOLDER_MARKER}\` marker line is there.`,
819
845
  );