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.
- package/README.md +52 -32
- package/dist/SKILL-12as0f3q.md +74 -0
- package/dist/SKILL-2h445snn.md +140 -0
- package/dist/SKILL-6vy283pt.md +140 -0
- package/dist/SKILL-ebn0fqaq.md +140 -0
- package/dist/ci-admission-a6d0wk1c.md +128 -0
- package/dist/cli.js +11559 -11422
- package/dist/index.js +123 -40
- package/dist/review-refuter-btpgnkcd.md +77 -0
- package/package.json +1 -1
- package/prompts/default/PROVENANCE.md +1 -0
- package/prompts/default/review-refuter.md +6 -0
- package/skills/crysk/SKILL.md +3 -3
- package/skills/crysk-ci-setup/SKILL.md +3 -3
- package/skills/crysk-ci-setup/references/ci-admission.md +1 -1
- package/src/assets.ts +1 -1
- package/src/ci/outcome.ts +4 -4
- package/src/commands/ci-setup.ts +21 -18
- package/src/commands/init.ts +21 -12
- package/src/doctor.ts +48 -29
- package/src/index.ts +1 -1
- package/src/menu-context.ts +1 -1
- package/src/pr/target.ts +16 -3
- package/src/review/boundary.ts +2 -1
- package/src/review/materiality-gate.ts +25 -1
- package/src/review/pipeline.ts +60 -15
- package/src/review/preflight.ts +132 -28
- package/src/review/prompt-set.ts +12 -8
- package/src/review/review.ts +14 -5
- package/src/review/run.ts +54 -18
- package/src/updater.ts +1 -1
- package/src/wizard.ts +35 -9
package/src/review/preflight.ts
CHANGED
|
@@ -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/
|
|
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>
|
|
505
|
-
|
|
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
|
-
|
|
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
|
-
// `
|
|
3463
|
-
//
|
|
3464
|
-
//
|
|
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
|
-
|
|
3612
|
+
file: string,
|
|
3541
3613
|
): string[] {
|
|
3542
3614
|
if (outcome.written) {
|
|
3543
|
-
// Safe ONLY on this arm: the file is
|
|
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 ${
|
|
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
|
|
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 ${
|
|
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 ${
|
|
3583
|
-
"
|
|
3584
|
-
"
|
|
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 ${
|
|
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
|
-
"
|
|
3608
|
-
"
|
|
3609
|
-
"
|
|
3610
|
-
"
|
|
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
|
-
`
|
|
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 [
|
package/src/review/prompt-set.ts
CHANGED
|
@@ -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
|
-
|
|
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:
|
package/src/review/review.ts
CHANGED
|
@@ -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
|
|
155
|
-
// abort: the pipeline is right to
|
|
156
|
-
// zero-cost partial run, which reads like
|
|
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
|
|
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
|
|
158
|
-
//
|
|
159
|
-
//
|
|
160
|
-
//
|
|
161
|
-
//
|
|
162
|
-
// it.
|
|
163
|
-
|
|
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
|
|
167
|
-
):
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
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
|
-
//
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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 = `#
|
|
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 =
|
|
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(
|
|
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
|
|
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(
|
|
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
|
|
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
|
);
|