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
@@ -42,6 +42,7 @@ import {
42
42
  LEGACY_BIN_NAME,
43
43
  matchMarkerPrefix,
44
44
  } from "../brand";
45
+ import { publishedText, redactSecrets } from "../security/published-text";
45
46
 
46
47
  export interface DiffStat {
47
48
  files: number;
@@ -961,7 +962,7 @@ function liveFindingLines(rereview: RereviewDelta | undefined): string[] {
961
962
  ? "⚠️ severity unavailable"
962
963
  : severityEmoji(row.sev);
963
964
  out.push(
964
- `- \`${row.status}\` ${badge} \`${loc}\` — ${liveClaimText(row.claim)} (${row.id})`,
965
+ `- \`${row.status}\` ${badge} ${code(loc)} — ${liveClaimText(row.claim)} (${row.id})`,
965
966
  );
966
967
  }
967
968
  out.push("");
@@ -1257,7 +1258,7 @@ function findingLocationLine(
1257
1258
  ): string {
1258
1259
  const loc = code(`${finding.path}:${finding.line}`);
1259
1260
  const linked =
1260
- linkLocation && webUrl !== undefined
1261
+ linkLocation && webUrl !== undefined && isLinkablePath(finding.path)
1261
1262
  ? `[${loc}](${blobUrl(webUrl, headSha, finding.path, `L${finding.line}`)})`
1262
1263
  : loc;
1263
1264
  // A POSITIVE type test, not `=== undefined`. Defence in depth: the draft and
@@ -1326,16 +1327,11 @@ function tierExplanationLines(finding: Finding): string[] {
1326
1327
 
1327
1328
  // The judge's reason is model text written about author-controlled input,
1328
1329
  // and it is posted. One line (a newline would end the list item and could
1329
- // start a forged header line), capped, with HTML comment delimiters broken so
1330
- // it can never open or close a marker the comment parsers read, and `@`
1331
- // defused so it cannot notify anyone.
1330
+ // start a forged header line) and capped; oneLine makes it safe to publish.
1332
1331
  const MATERIALITY_REASON_MAX = 280;
1333
1332
 
1334
1333
  function materialityReason(reason: string): string {
1335
- const flat = oneLine(reason)
1336
- .replaceAll("<!--", "<!‐‐")
1337
- .replaceAll("-->", "‐‐>")
1338
- .replaceAll("@", "@\u200b");
1334
+ const flat = oneLine(reason);
1339
1335
  return flat.length <= MATERIALITY_REASON_MAX
1340
1336
  ? flat
1341
1337
  : `${flat.slice(0, MATERIALITY_REASON_MAX - 1).trimEnd()}…`;
@@ -1351,7 +1347,7 @@ function promptToFixBlock(finding: Finding): string[] {
1351
1347
  "<details><summary>Prompt to fix with AI</summary>",
1352
1348
  "",
1353
1349
  "```",
1354
- `Fix this issue in ${finding.path} at line ${finding.line}:`,
1350
+ `Fix this issue in ${oneLine(finding.path)} at line ${finding.line}:`,
1355
1351
  "",
1356
1352
  oneLine(finding.claim),
1357
1353
  "```",
@@ -1520,7 +1516,7 @@ function renderRef(
1520
1516
  ): string {
1521
1517
  if (webUrl === undefined) return code(ref);
1522
1518
  const parsed = parseRefAnchor(ref);
1523
- if (parsed === null) return code(ref);
1519
+ if (parsed === null || !isLinkablePath(parsed.path)) return code(ref);
1524
1520
  const fragment =
1525
1521
  parsed.end === undefined
1526
1522
  ? `L${parsed.start}`
@@ -1559,6 +1555,27 @@ function parseRefAnchor(ref: string): {
1559
1555
  };
1560
1556
  }
1561
1557
 
1558
+ // A finding's path is whatever the model wrote; nothing checks that the file
1559
+ // exists. A span redacts it, but a link's href needs the original, so a path
1560
+ // carrying a secret gets no link.
1561
+ export function isLinkablePath(path: string): boolean {
1562
+ return redactSecrets(path) === path;
1563
+ }
1564
+
1565
+ // A path is author-controlled and lands in a Markdown link. `)` would end the
1566
+ // link and leave what follows as text, where `@name` is a real mention. Parens are
1567
+ // encoded by hand because encodeURIComponent leaves them. An unpaired surrogate
1568
+ // would make it throw, and a post that was paid for must not be lost to a path.
1569
+ function encodeBlobPath(path: string): string {
1570
+ return path
1571
+ .toWellFormed()
1572
+ .split("/")
1573
+ .map(encodeURIComponent)
1574
+ .join("/")
1575
+ .replaceAll("(", "%28")
1576
+ .replaceAll(")", "%29");
1577
+ }
1578
+
1562
1579
  // Exported for ui/result.ts, the second surface that links a finding to its
1563
1580
  // source. Deliberately SHARED rather than re-derived: the markdown report and
1564
1581
  // the terminal block must point a reader at the same bytes, and two copies of
@@ -1570,7 +1587,7 @@ export function blobUrl(
1570
1587
  path: string,
1571
1588
  fragment: string,
1572
1589
  ): string {
1573
- return `${webUrl}/blob/${sha}/${path}#${fragment}`;
1590
+ return `${webUrl}/blob/${sha}/${encodeBlobPath(path)}#${fragment}`;
1574
1591
  }
1575
1592
 
1576
1593
  function runLines(doc: FindingsDocument, meta: ReportMeta): string[] {
@@ -1809,9 +1826,12 @@ export function code(text: string): string {
1809
1826
  }
1810
1827
 
1811
1828
  // Claims arrive as free prose and sometimes carry newlines; a raw newline
1812
- // inside a list item silently ends the item.
1829
+ // inside a list item silently ends the item. Every piece of model text and every
1830
+ // span in this file passes through here, which makes this the one place it is
1831
+ // made safe to publish. The finding marker fingerprints the raw claim instead, so
1832
+ // a comment posted before this existed still matches its finding.
1813
1833
  function oneLine(text: string): string {
1814
- return text.replace(/\s+/g, " ").trim();
1834
+ return publishedText(text.replace(/\s+/g, " ").trim());
1815
1835
  }
1816
1836
 
1817
1837
  function usd(amount: number): string {
@@ -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
  }
@@ -0,0 +1,161 @@
1
+ // Text a model wrote about author-controlled input, on its way to a public
2
+ // surface: PR comments, the step summary, the state block. A pull request can
3
+ // steer what the model says, so GitHub must not act on any of it.
4
+ //
5
+ // WHY shapes and not the keyword rules of redact.ts: those are for error
6
+ // messages, where `password hunter2` is a leak. A finding is ABOUT code, so
7
+ // "the password field" and `const TOKEN = getToken()` have to survive it.
8
+ //
9
+ // WHY every repeat that can start at many positions has a bound: this runs on
10
+ // whatever the model printed, and one long word must not stall publication.
11
+ //
12
+ // What each defusal does was checked against GitHub's own renderer
13
+ // (`gh api markdown --mode gfm`), not assumed.
14
+
15
+ const REDACTED = "[REDACTED]";
16
+ const ZERO_WIDTH_SPACE = "\u200b";
17
+
18
+ // `(?<![A-Za-z0-9])` instead of `\b`: `\b` does not fire after `_`, and
19
+ // `_ghp_..._` is a token in Markdown emphasis.
20
+ const SECRET_SHAPES: readonly RegExp[] = [
21
+ /(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9_]{20,}/g,
22
+ /(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{20,}/g,
23
+ /(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{20,}/g,
24
+ /(?<![A-Za-z0-9])(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
25
+ // The prefixed form and the older unbroken form. A bare `sk-` plus hyphens is
26
+ // what a CSS class looks like.
27
+ /(?<![A-Za-z0-9])sk-(?:ant|proj|svcacct|admin)-[A-Za-z0-9_-]{16,}/g,
28
+ /(?<![A-Za-z0-9])sk-[A-Za-z0-9]{32,}/g,
29
+ /(?<![A-Za-z0-9])[sr]k_(?:live|test)_[A-Za-z0-9]{16,}/g,
30
+ /(?<![A-Za-z0-9])xox[abeoprs]-[A-Za-z0-9-]{10,}/g,
31
+ /(?<![A-Za-z0-9])AIza[A-Za-z0-9_-]{35}/g,
32
+ /(?<![A-Za-z0-9])npm_[A-Za-z0-9]{36}\b/g,
33
+ /(?<![A-Za-z0-9])eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}/g,
34
+ // A digit is required: `Bearer verifyAccessTokenSignature` names a function.
35
+ /(?<![A-Za-z0-9])Bearer\s+(?=[A-Za-z0-9._~+/=-]{0,512}\d)[A-Za-z0-9._~+/=-]{20,}/gi,
36
+ ];
37
+
38
+ // `user:password@`, or a long user-only token. `git@` is a username, and `$`,
39
+ // `{` and `<` mean a placeholder (`redis://:${REDIS_PASSWORD}@cache`).
40
+ const URL_CREDENTIALS =
41
+ /(?<![A-Za-z0-9+.-])([a-z][a-z0-9+.-]{0,30}:\/\/)(?:[^\s/?#${<]{0,256}:[^\s/?#${<]{1,256}|[^\s/?#${<:@]{20,256})@/gi;
42
+
43
+ // A secret name followed by a value. The name alone decides nothing, because code
44
+ // is full of these: `TOKEN=getToken`, `API_KEY = "x-api-key"`, `SECRET: Uint8Array`.
45
+ // So isSecretValue reads the value.
46
+ const SECRET_ASSIGNMENT =
47
+ /(?<![A-Za-z0-9_-])(["']?)((?:[A-Za-z0-9_-]{0,40}[_-])?(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|credentials?)(?:[_-][A-Za-z0-9_-]{0,40})?)\1(\s*[=:](?![=:])\s*)("[^"\n]{1,256}"|'[^'\n]{1,256}'|[^\s"',;]{1,256})/gi;
48
+
49
+ // A digit is the signal: a literal with one is rarely a word or an identifier. A
50
+ // password holds no such promise, so a password name also takes letters alone,
51
+ // unless the value only repeats the word (`PASSWORD = "password"`). This leaves
52
+ // letter-only values of other names, such as `API_KEY=hunter`: nothing tells them
53
+ // from `API_KEY=config`.
54
+ function isSecretValue(name: string, separator: string, raw: string): boolean {
55
+ const quoted = raw.startsWith('"') || raw.startsWith("'");
56
+ const value = quoted ? raw.slice(1, -1) : raw;
57
+ if (value.length < 6 || /^[\d_,.]+$/.test(value) || value.includes("$")) {
58
+ return false;
59
+ }
60
+ // `config/credentials:100-120` is a file and a line range, nothing else.
61
+ if (separator === ":" && /^\d+-\d+$/.test(value)) return false;
62
+ const colon = separator.includes(":");
63
+ if (!quoted) {
64
+ // Spaces around `=` are source code, and a bracket or a dot is an expression.
65
+ if (!colon && separator !== "=") return false;
66
+ if (/[.()[\]{}<>]/.test(value)) return false;
67
+ // A type annotation: `SECRET: Uint8Array`.
68
+ if (colon && /^[A-Z][a-z]/.test(value)) return false;
69
+ }
70
+ if (/\d/.test(value)) return true;
71
+ if (!/pass(?:word|wd)$/i.test(name) || /pass(?:word|wd)/i.test(value)) {
72
+ return false;
73
+ }
74
+ // `password: string` is a type. An upper-case name is a config key.
75
+ return quoted || !colon || name === name.toUpperCase();
76
+ }
77
+
78
+ const PEM_BEGIN = /-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----/g;
79
+ const PEM_END = /-----END [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----/g;
80
+ const PEM_BODY = /(?:\s*[A-Za-z0-9+/=]{16,})*/y;
81
+
82
+ // Up to the closing line, or, when that was cut off, across the base64 lines:
83
+ // half a private key is still a private key, and the sentence after it is not
84
+ // part of the key. A loop and not one regex, so many openers with no closer stay
85
+ // linear.
86
+ function redactPrivateKeys(text: string): string {
87
+ if (!text.includes("PRIVATE KEY")) return text;
88
+ let out = "";
89
+ let from = 0;
90
+ let noMoreEnds = false;
91
+ PEM_BEGIN.lastIndex = 0;
92
+ for (;;) {
93
+ const begin = PEM_BEGIN.exec(text);
94
+ if (begin === null) break;
95
+ let to = PEM_BEGIN.lastIndex;
96
+ let closed = false;
97
+ if (!noMoreEnds) {
98
+ PEM_END.lastIndex = to;
99
+ closed = PEM_END.test(text);
100
+ if (closed) to = PEM_END.lastIndex;
101
+ else noMoreEnds = true;
102
+ }
103
+ if (!closed) {
104
+ PEM_BODY.lastIndex = to;
105
+ PEM_BODY.test(text);
106
+ to = PEM_BODY.lastIndex;
107
+ }
108
+ out += text.slice(from, begin.index) + REDACTED;
109
+ from = to;
110
+ PEM_BEGIN.lastIndex = to;
111
+ }
112
+ return out + text.slice(from);
113
+ }
114
+
115
+ export function redactSecrets(text: string): string {
116
+ let out = redactPrivateKeys(text);
117
+ for (const shape of SECRET_SHAPES) out = out.replace(shape, REDACTED);
118
+ return out
119
+ .replace(URL_CREDENTIALS, `$1${REDACTED}@`)
120
+ .replace(
121
+ SECRET_ASSIGNMENT,
122
+ (
123
+ match: string,
124
+ quote: string,
125
+ name: string,
126
+ separator: string,
127
+ raw: string,
128
+ ) =>
129
+ isSecretValue(name, separator, raw)
130
+ ? `${quote}${name}${quote}${separator}${REDACTED}`
131
+ : match,
132
+ );
133
+ }
134
+
135
+ // A secret was removed from this text, so the words around it are not all the
136
+ // words the model wrote. A guard reading it for safety content must not treat it
137
+ // as complete.
138
+ export function wasRedacted(text: string): boolean {
139
+ return text.includes(REDACTED);
140
+ }
141
+
142
+ // A zero-width space reads the same and stops GitHub from parsing a mention, an
143
+ // image or a tag out of the text. Breaking `<` also means no model text can spell
144
+ // a marker the comment parsers read. `@` after a letter, digit or `/` is left
145
+ // alone because GitHub does not read it as a mention, and emails, URLs and
146
+ // `src/@types` stay copyable. `&` is broken because `&#64;octocat` IS a mention.
147
+ //
148
+ // Idempotent, because a posted claim is read back from its comment and rendered
149
+ // again.
150
+ function defuseMarkup(text: string): string {
151
+ return text
152
+ .replace(/(?<![A-Za-z0-9/])@(?!\u200b)/g, `@${ZERO_WIDTH_SPACE}`)
153
+ .replace(/&(?=#|commat)/gi, `&${ZERO_WIDTH_SPACE}`)
154
+ .replaceAll("![", `!${ZERO_WIDTH_SPACE}[`)
155
+ .replace(/<(?=[a-zA-Z/!?])/g, `<${ZERO_WIDTH_SPACE}`)
156
+ .replaceAll("-->", `--${ZERO_WIDTH_SPACE}>`);
157
+ }
158
+
159
+ export function publishedText(text: string): string {
160
+ return defuseMarkup(redactSecrets(text));
161
+ }
@@ -10,6 +10,7 @@
10
10
  // sides agree on.
11
11
  //
12
12
  import { MARKER_OPEN, matchMarkerPrefix } from "../brand";
13
+ import { publishedText } from "../security/published-text";
13
14
 
14
15
  // Disjoint from PR_COMMENT_MARKER_PREFIX and PR_FINDING_MARKER_PREFIX on
15
16
  // purpose, same reasoning as their own disjointness (pr/preflight.ts): a
@@ -129,7 +130,7 @@ export function renderTriageReplyBody(
129
130
  reasoning: string,
130
131
  ): string {
131
132
  const head = `${triageMarker(fields)}\n\n${triageBadge(fields)}`;
132
- const prose = reasoning.trim();
133
+ const prose = publishedText(reasoning.trim());
133
134
  return prose.length === 0 ? `${head}\n` : `${head}\n\n${prose}\n`;
134
135
  }
135
136
 
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.4.0";
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
  );