crysk 0.0.0-stage → 0.3.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 (229) hide show
  1. package/LICENSE +176 -0
  2. package/README.md +610 -2
  3. package/bin/pr-hero.js +166 -0
  4. package/config/models/anthropic.json +5 -0
  5. package/dist/SKILL-7e3725zn.md +496 -0
  6. package/dist/SKILL-7q35wcaz.md +66 -0
  7. package/dist/SKILL-9at22381.md +74 -0
  8. package/dist/SKILL-ex2hxxh3.md +134 -0
  9. package/dist/adjudicator-dtg2axnh.md +86 -0
  10. package/dist/admission-config.example-a9vqmmad.json +9 -0
  11. package/dist/ci-admission-camfbx2b.md +122 -0
  12. package/dist/cli.js +42292 -0
  13. package/dist/consolidate-ac0mnfyj.md +24 -0
  14. package/dist/deep-review-lifecycle-m698ybjp.md +362 -0
  15. package/dist/deep-review-logic-a6b1gczf.md +156 -0
  16. package/dist/deep-review-parity-0ec904db.md +120 -0
  17. package/dist/deep-review-reliability-qyakbjb9.md +125 -0
  18. package/dist/deep-review-resilience-3tz8y26e.md +118 -0
  19. package/dist/index.js +20190 -0
  20. package/dist/opencode-ci-7b0be64p.md +141 -0
  21. package/dist/review-refuter-j4e9gezy.md +71 -0
  22. package/dist/scout-yvp153q7.md +140 -0
  23. package/dist/summarizer-zca44nxa.md +18 -0
  24. package/dist/workflow-w1g9szna.yml +151 -0
  25. package/package.json +82 -4
  26. package/prompts/consolidate.md +24 -0
  27. package/prompts/default/PROVENANCE.md +18 -0
  28. package/prompts/default/deep-review-lifecycle.md +362 -0
  29. package/prompts/default/deep-review-logic.md +156 -0
  30. package/prompts/default/deep-review-parity.md +120 -0
  31. package/prompts/default/deep-review-reliability.md +125 -0
  32. package/prompts/default/deep-review-resilience.md +118 -0
  33. package/prompts/default/review-refuter.md +71 -0
  34. package/prompts/scout.md +140 -0
  35. package/prompts/summarizer.md +18 -0
  36. package/skills/crysk/SKILL.md +74 -0
  37. package/skills/crysk-ci-setup/SKILL.md +134 -0
  38. package/skills/crysk-ci-setup/assets/admission-config.example.json +9 -0
  39. package/skills/crysk-ci-setup/assets/workflow.yml +151 -0
  40. package/skills/crysk-ci-setup/references/ci-admission.md +122 -0
  41. package/skills/crysk-ci-setup/references/opencode-ci.md +141 -0
  42. package/skills/crysk-loop/SKILL.md +496 -0
  43. package/skills/crysk-loop/adjudicator.md +86 -0
  44. package/skills/crysk-pr/SKILL.md +66 -0
  45. package/src/agent-env.ts +1084 -0
  46. package/src/asset-manifest.ts +83 -0
  47. package/src/assets.d.ts +6 -0
  48. package/src/assets.ts +183 -0
  49. package/src/brand-paths.ts +155 -0
  50. package/src/brand.ts +255 -0
  51. package/src/ci/admission-ledger.ts +350 -0
  52. package/src/ci/classify-error.ts +73 -0
  53. package/src/ci/cli-record.ts +271 -0
  54. package/src/ci/force-comment.ts +39 -0
  55. package/src/ci/gates.ts +923 -0
  56. package/src/ci/outcome.ts +2181 -0
  57. package/src/ci/override.ts +187 -0
  58. package/src/ci/publish.ts +1639 -0
  59. package/src/ci/reporter.ts +626 -0
  60. package/src/ci/review-admission.ts +901 -0
  61. package/src/ci/review-levels.ts +310 -0
  62. package/src/ci/review-policy.ts +18 -0
  63. package/src/ci/review-risk.ts +184 -0
  64. package/src/ci/setup.ts +844 -0
  65. package/src/ci/trigger.ts +1353 -0
  66. package/src/cli.ts +348 -0
  67. package/src/commands/activity.ts +67 -0
  68. package/src/commands/ci-setup-questions.ts +397 -0
  69. package/src/commands/ci-setup.ts +381 -0
  70. package/src/commands/config.ts +99 -0
  71. package/src/commands/doctor.ts +108 -0
  72. package/src/commands/init.ts +139 -0
  73. package/src/commands/mcp.ts +10 -0
  74. package/src/commands/menu.ts +129 -0
  75. package/src/commands/post.ts +302 -0
  76. package/src/commands/skills.ts +83 -0
  77. package/src/commands/status.ts +173 -0
  78. package/src/commands/triage.ts +342 -0
  79. package/src/commands/uninstall.ts +37 -0
  80. package/src/commands/upgrade.ts +214 -0
  81. package/src/commands/usage.ts +98 -0
  82. package/src/compare/compare.ts +28 -0
  83. package/src/compare/floor-test.ts +471 -0
  84. package/src/compare/martian-adapter.ts +80 -0
  85. package/src/config/config.ts +267 -0
  86. package/src/corpus/corpus.ts +1094 -0
  87. package/src/corpus/preflight.ts +1789 -0
  88. package/src/diversity/accounting.ts +90 -0
  89. package/src/diversity/adjudication.ts +145 -0
  90. package/src/diversity/admission.ts +60 -0
  91. package/src/diversity/benchmark.ts +195 -0
  92. package/src/diversity/clustering.ts +285 -0
  93. package/src/diversity/errors.ts +7 -0
  94. package/src/diversity/identity.ts +285 -0
  95. package/src/diversity/index.ts +11 -0
  96. package/src/diversity/pipeline-integration.ts +448 -0
  97. package/src/diversity/projection.ts +57 -0
  98. package/src/diversity/self-contained.ts +68 -0
  99. package/src/diversity/target-validation.ts +179 -0
  100. package/src/doctor-migration.ts +209 -0
  101. package/src/doctor.ts +723 -0
  102. package/src/errors.ts +83 -0
  103. package/src/execution/admission.ts +75 -0
  104. package/src/execution/atomic-write.ts +35 -0
  105. package/src/execution/attempt-evidence.ts +415 -0
  106. package/src/execution/bucket-id.ts +136 -0
  107. package/src/execution/concurrency-limiter.ts +175 -0
  108. package/src/execution/contracts.ts +443 -0
  109. package/src/execution/failure-classification.ts +42 -0
  110. package/src/execution/failure-policy.ts +240 -0
  111. package/src/execution/harness.ts +2548 -0
  112. package/src/execution/settlement.ts +348 -0
  113. package/src/execution/spawned-process.ts +66 -0
  114. package/src/execution/spend-limiter.ts +424 -0
  115. package/src/execution/step-artifacts.ts +55 -0
  116. package/src/execution/usage-normalized.ts +469 -0
  117. package/src/git/git.ts +396 -0
  118. package/src/git/identity.ts +64 -0
  119. package/src/git/refs.ts +140 -0
  120. package/src/home-preflight.ts +443 -0
  121. package/src/home.ts +243 -0
  122. package/src/ignore-file.ts +336 -0
  123. package/src/ignore-read.ts +118 -0
  124. package/src/index.ts +34 -0
  125. package/src/legacy-launchd.ts +29 -0
  126. package/src/mcp/mcp.ts +150 -0
  127. package/src/mcp/preflight.ts +407 -0
  128. package/src/menu-context.ts +192 -0
  129. package/src/model/catalog.ts +251 -0
  130. package/src/model/exec-snapshots.ts +390 -0
  131. package/src/model/free-discovery.ts +302 -0
  132. package/src/model/provider-capabilities.ts +814 -0
  133. package/src/model/routing.ts +600 -0
  134. package/src/pr/admission.ts +847 -0
  135. package/src/pr/ci-admission-gate.ts +665 -0
  136. package/src/pr/ci-publish.ts +76 -0
  137. package/src/pr/discovery.ts +432 -0
  138. package/src/pr/inline.ts +507 -0
  139. package/src/pr/plan.ts +366 -0
  140. package/src/pr/posting.ts +115 -0
  141. package/src/pr/pr-status.ts +787 -0
  142. package/src/pr/pr.ts +3642 -0
  143. package/src/pr/preflight.ts +1031 -0
  144. package/src/pr/publish-outcome.ts +361 -0
  145. package/src/pr/range.ts +119 -0
  146. package/src/pr/reverts-preflight.ts +606 -0
  147. package/src/pr/reverts.ts +377 -0
  148. package/src/pr/review-pr.ts +927 -0
  149. package/src/pr/status.ts +154 -0
  150. package/src/pr/target.ts +388 -0
  151. package/src/pr/teardown.ts +437 -0
  152. package/src/pr/worktree-setup.ts +60 -0
  153. package/src/production-runtime.ts +1877 -0
  154. package/src/progress.ts +487 -0
  155. package/src/rereview/adjudicate.ts +89 -0
  156. package/src/rereview/classify.ts +362 -0
  157. package/src/rereview/identity.ts +211 -0
  158. package/src/rereview/plan.ts +308 -0
  159. package/src/rereview/prepare.ts +1025 -0
  160. package/src/rereview/state.ts +767 -0
  161. package/src/rereview/verify.ts +241 -0
  162. package/src/review/boundary.ts +105 -0
  163. package/src/review/consolidate.ts +246 -0
  164. package/src/review/dedupe.ts +368 -0
  165. package/src/review/drafts.ts +448 -0
  166. package/src/review/findings-conformance.ts +120 -0
  167. package/src/review/findings.ts +714 -0
  168. package/src/review/pipeline.ts +3977 -0
  169. package/src/review/preflight.ts +3575 -0
  170. package/src/review/prompt-set.ts +177 -0
  171. package/src/review/proof-refs.ts +187 -0
  172. package/src/review/report.ts +1821 -0
  173. package/src/review/review.ts +490 -0
  174. package/src/review/root-cause.ts +120 -0
  175. package/src/review/route-preflight.ts +289 -0
  176. package/src/review/run.ts +601 -0
  177. package/src/review/scout.ts +323 -0
  178. package/src/review/size-gate.ts +595 -0
  179. package/src/review/spec.ts +235 -0
  180. package/src/review/step-runner.ts +233 -0
  181. package/src/runner-authority.ts +596 -0
  182. package/src/security/binding-policy.ts +115 -0
  183. package/src/security/credential-broker.ts +773 -0
  184. package/src/security/evidence-redaction.ts +62 -0
  185. package/src/security/execution-authority.ts +27 -0
  186. package/src/security/redact.ts +71 -0
  187. package/src/security/workspace-read-broker.ts +466 -0
  188. package/src/server/client.ts +190 -0
  189. package/src/server/preflight.ts +217 -0
  190. package/src/server/server.ts +327 -0
  191. package/src/signal-handler.ts +50 -0
  192. package/src/store/activity.ts +413 -0
  193. package/src/store/backfill-preflight.ts +49 -0
  194. package/src/store/backfill.ts +141 -0
  195. package/src/store/gc-preflight.ts +206 -0
  196. package/src/store/gc.ts +424 -0
  197. package/src/store/metrics-preflight.ts +229 -0
  198. package/src/store/metrics.ts +236 -0
  199. package/src/store/preflight.ts +748 -0
  200. package/src/store/store.ts +693 -0
  201. package/src/system-tools.ts +355 -0
  202. package/src/transport-registry.ts +1124 -0
  203. package/src/transports/claude-code-cli.ts +1348 -0
  204. package/src/transports/opencode-admission.ts +515 -0
  205. package/src/transports/opencode-client.ts +3328 -0
  206. package/src/transports/opencode-evidence.ts +557 -0
  207. package/src/transports/opencode-mcp.ts +248 -0
  208. package/src/transports/opencode-sdk.ts +2294 -0
  209. package/src/transports/opencode-server.ts +535 -0
  210. package/src/triage/adjudication.ts +113 -0
  211. package/src/triage/reply.ts +125 -0
  212. package/src/triage/triage.ts +255 -0
  213. package/src/ui/activity.ts +173 -0
  214. package/src/ui/config-edit.ts +816 -0
  215. package/src/ui/config.ts +462 -0
  216. package/src/ui/menu.ts +1325 -0
  217. package/src/ui/plan.ts +1039 -0
  218. package/src/ui/primitives.ts +300 -0
  219. package/src/ui/progress.ts +298 -0
  220. package/src/ui/result.ts +552 -0
  221. package/src/ui/review-menu.ts +312 -0
  222. package/src/ui/select.ts +528 -0
  223. package/src/ui/tree.ts +178 -0
  224. package/src/uninstaller.ts +479 -0
  225. package/src/updater.ts +836 -0
  226. package/src/usage.ts +77 -0
  227. package/src/watch/preflight.ts +1389 -0
  228. package/src/watch/watch.ts +1235 -0
  229. package/src/wizard.ts +877 -0
package/README.md CHANGED
@@ -1,3 +1,611 @@
1
- # Temporary Holding Version
1
+ # Crysk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A multi-agent PR-review engine. Specialty hunter agents fan out in parallel over a repo checkout and
4
+ its diff, a mechanical dedupe merges their drafts, an adversarial refuter challenges every severe
5
+ finding, and deterministic code — never a model — assigns blocking/advisory tiers.
6
+
7
+ Its measured profile, stated up front: **high precision, narrow coverage**. What it reports is
8
+ almost always real (13% false positives measured); it specializes in lifecycle and state-machine
9
+ defects — stuck loading latches, missing cleanups, re-entrancy, stalls — and says nothing about
10
+ style or convention. Locally it is an **assistant, not a merge gate**: every report closes with that
11
+ disclaimer, and nothing it prints blocks a merge. In CI its commit status is a gate by default: require the
12
+ `crysk` check in branch protection, and blocking findings block the merge. `mode: advisory` keeps that check
13
+ green.
14
+
15
+ > **Renamed from pr-hero.** Crysk used to be `pr-hero`. The package is now `crysk` (`npm install -g crysk`,
16
+ > `npx -y crysk`), and the `pr-hero` command stays as an alias for one version. What an install made under the
17
+ > old name wrote is still read for one version: `/pr-hero …` comments, `PRHERO_*` variables, `<!-- pr-hero-…`
18
+ > markers, the `pr-hero` status check, `~/.prhero`, `.prhero/` and `.prheroignore`. A workflow file scaffolded
19
+ > before the rename only answers `/pr-hero …`: re-run `crysk ci init --force` for it to accept `/crysk …` too.
20
+ > The repository moved to `cryskai/crysk` and new workflows use `uses: cryskai/crysk@v0`. `juanmaagd/pr-hero` stays as a mirror with the same tags and releases, so a workflow that still says `uses: juanmaagd/pr-hero@v0` keeps working.
21
+
22
+ ## Two ways to use it
23
+
24
+ - **Local CLI**: install Crysk on your machine and review branches or PRs from your terminal.
25
+ Start at [Requirements](#requirements).
26
+ - **CI only, no local install**: install the skills into your coding agent, add one workflow file
27
+ to the repository, and every pull request is reviewed in GitHub Actions. Nothing below
28
+ Requirements applies to this path. It is described next.
29
+
30
+ ### CI only: skills plus one workflow
31
+
32
+ You need Node (for `npx`), an authenticated `gh`, and a GitHub repository with Actions enabled. You do
33
+ **not** need Bun, the Claude Code CLI, or a global Crysk install: the review runs on the GitHub
34
+ runner, which installs its own runtime. `npx -y crysk setup --ci` checks `gh` for you: when it is
35
+ missing or logged out, it says why it is needed and prints the commands, and in a terminal it offers
36
+ to install it (macOS with Homebrew) and to run `gh auth login`. It never blocks the setup.
37
+
38
+ 1. **Install the skills** into your coding agent from [skills.sh](https://skills.sh/cryskai/crysk):
39
+
40
+ ```bash
41
+ npx skills add cryskai/crysk
42
+ ```
43
+
44
+ `crysk-ci-setup` sets up the workflow, `crysk-pr` opens a PR and waits for its review, and
45
+ `crysk-loop` answers the findings. `crysk` covers the local CLI, which this path does not use.
46
+
47
+ 2. **Ask your agent to set up Crysk CI** in the repository. `crysk-ci-setup` first asks you how
48
+ re-reviews should work: a level (minimal, balanced, thorough or manual), gate or advisory, how CI
49
+ pays (a subscription gets no spend ceiling, an API key gets one you choose), the changed-lines
50
+ threshold above which a PR is skipped (default 4000, on any billing), and whether to tune the
51
+ advanced settings (score weights, observe-only, trusted actors, files limit, exclusions). Then it runs
52
+ `npx -y crysk setup --ci` with your answers (writes `.github/workflows/crysk.yml`, or updates an existing `pr-hero.yml` in place, and the
53
+ level's keys in `.crysk/config.json`, and prints a summary) and `npx -y crysk init`
54
+ (writes `.crysk/gotchas.md`), writes the repository gotchas, and stores
55
+ one secret with `gh secret set`: `CLAUDE_CODE_OAUTH_TOKEN` (subscription; `claude setup-token`
56
+ prints it on any machine that has the Claude Code CLI, so this one does not need it) or
57
+ `ANTHROPIC_API_KEY` (pay as you go). Without an agent, run the same
58
+ commands yourself and follow the [Quick path](docs/github-actions.md#quick-path).
59
+
60
+ 3. **Merge the workflow and `.crysk/` into the default branch.** A comment-triggered run
61
+ (`/crysk review`) reads both from the base branch, so it starts nothing until the workflow is
62
+ there, and fails `PRH-GOTCHAS-MISSING` until `.crysk/` is.
63
+ Then require the `crysk` status check in branch protection (`pr-hero` is still posted for one version) if you want it to block merges.
64
+
65
+ 4. **Open pull requests as usual.** Every new PR gets a review posted as PR comments; later pushes
66
+ follow the level you chose (balanced re-reviews a push only when it is risky or the last pass
67
+ found enough, at most 2 automatic passes), and a PR above the size threshold is skipped. Comment
68
+ `/crysk review` to review a skipped push anyway. Ask your agent
69
+ to open the PR (`crysk-pr`), and it waits for the review with `npx -y crysk status --pr <n>
70
+ --wait --json`, then hands the findings to `crysk-loop`, which replies to each one in its
71
+ thread and pushes the fixes.
72
+
73
+ Everything about the workflow (credentials, OpenCode routing, spend limits, the gate, error codes)
74
+ is in [`docs/github-actions.md`](docs/github-actions.md).
75
+
76
+ ## Requirements
77
+
78
+ These apply to the local CLI. The [CI-only path](#ci-only-skills-plus-one-workflow) needs none of them
79
+ on your machine.
80
+
81
+ Crysk does not call any model API of its own. It **spawns the Claude Code CLI as a subprocess** and
82
+ inherits that CLI's authentication. `claude` is the engine; everything else here is plumbing.
83
+
84
+ | Dependency | Needed for | Without it |
85
+ | --- | --- | --- |
86
+ | **Claude Code CLI**, installed *and authenticated* | everything | nothing runs — it is the engine |
87
+ | **git** | everything | nothing runs |
88
+ | **Bun ≥ 1.3** on `PATH` | install options B and C only | option A carries its own runtime |
89
+ | **GitHub CLI (`gh`)**, authenticated | `review --pr`, `--post`, `watch`, `reverts`, `corpus` | local review still works in full |
90
+ | **codegraph** | optional code intelligence | hunters navigate with git and grep, with less structural context |
91
+
92
+ Run `crysk doctor` first: it checks every one of these and prints what is missing. The one thing it
93
+ cannot check is Bun — on an npm or source install the launcher itself is a Bun script, so a missing
94
+ Bun fails *before* any Crysk code runs, with `env: bun: No such file or directory`. Install Bun
95
+ (`brew install oven-sh/bun/bun`, or `curl -fsSL https://bun.sh/install | bash`) or use option A,
96
+ whose binary needs no Bun on your machine.
97
+
98
+ ### What a review bills against
99
+
100
+ Crysk inherits whatever authentication your `claude` CLI already uses:
101
+
102
+ - **Signed in with a Claude subscription** → runs consume your **subscription quota**. No per-token
103
+ invoice arrives.
104
+ - **`ANTHROPIC_API_KEY` exported in the environment** → `claude` picks it up and the same runs are
105
+ **billed as API usage**.
106
+
107
+ The dollar figures Crysk prints — the cost band before a run, `crysk usage` after one — are
108
+ always a **token-derived estimate**, because that is the only unit comparable across both models. On
109
+ a subscription, read them as "how much of my window will this consume", not as a bill. If you keep an
110
+ `ANTHROPIC_API_KEY` in a project `.env`, be deliberate about sourcing it into the shell you launch
111
+ Crysk from: that single step is what moves a run from quota to invoice.
112
+
113
+ ## Installation
114
+
115
+ ```bash
116
+ # Option A: Standalone binary (macOS / Linux, bundles its own Bun — still needs claude and git)
117
+ curl -fsSL https://raw.githubusercontent.com/cryskai/crysk/main/install.sh | bash
118
+
119
+ # Option B: Global npm install (brings Bun 1.3.14 as an optional dependency, or uses
120
+ # the Bun >= 1.3 on PATH when npm skips optional dependencies)
121
+ npm install -g crysk
122
+
123
+ # Option D: No install, for an agent or a one-off run (needs only Node). It cannot
124
+ # register the MCP server or the launchd agents: npx's cache is temporary, so those
125
+ # refuse and ask for option B. The launcher uses the bundled Bun only when it runs
126
+ # (`bun --version` is checked first), otherwise the Bun on PATH, and exits 127 naming both if neither works.
127
+ npx crysk doctor
128
+
129
+ # Option C: From source / development (the bin runs on Node; on a machine with Bun
130
+ # and no Node, run `bun bin/pr-hero.js` or use option A)
131
+ git clone https://github.com/cryskai/crysk.git && cd crysk
132
+ bun install && bun link
133
+ ```
134
+
135
+ See [Requirements](#requirements) above — `claude` and `git` are needed by every option.
136
+
137
+ ## From install to first review
138
+
139
+ Only want the CI review? You do not need to install anything: see [GitHub Actions — Quick path](docs/github-actions.md#quick-path) (`npx -y crysk setup --ci`, `npx -y crysk init`, one secret).
140
+
141
+ Seven steps, in this order. Steps 2, 5 and 6 are the ones that get skipped, and
142
+ each one breaks the step after it.
143
+
144
+ ```bash
145
+ # 1. Install (option A shown; B and C put crysk on PATH themselves)
146
+ curl -fsSL https://raw.githubusercontent.com/cryskai/crysk/main/install.sh | bash
147
+
148
+ # 2. Put it on THIS shell's PATH. The installer edited your rc file, and an rc
149
+ # file only reaches shells started after it — the one you are in is not one.
150
+ # (The installer prints the exact line. It is ~/.crysk/bin, or ~/.prhero/bin
151
+ # on a machine that already had a ~/.prhero from before the rename.)
152
+ export PATH="$HOME/.crysk/bin:$PATH" # fish: set -gx PATH $HOME/.crysk/bin $PATH
153
+
154
+ # 3. What is installed, what is missing, what blocks a review.
155
+ crysk doctor
156
+
157
+ # 4. Skills + MCP registration, and — inside a git repo — scaffold .crysk/.
158
+ cd /path/to/your-repo && crysk setup
159
+
160
+ # 5. Track that scaffold, or ignore it. Local review refuses to run on a dirty
161
+ # tree, and an untracked .crysk/ is a dirty tree.
162
+ git add .crysk && git commit -m "chore: crysk config" # or: echo '.crysk/' >> .gitignore
163
+
164
+ # 6. Replace the placeholder gotchas with real ones. Not paperwork — see below.
165
+ $EDITOR .crysk/gotchas.md
166
+
167
+ # 7. Review the checked-out branch against its merge base.
168
+ crysk review
169
+ ```
170
+
171
+ **On step 4.** `setup` is fully non-interactive — it asks nothing and is safe to run
172
+ unattended. It is also optional for reviewing: `review` never checks whether it ran,
173
+ only `crysk doctor` reports it. What it buys is the skills, the MCP registration and
174
+ the repo scaffold; skip it and you scaffold the repo yourself with `crysk init`. It does
175
+ **not** commit or `.gitignore` what it scaffolds, which is why step 5 exists.
176
+
177
+ **Skill drift.** `setup` (and `upgrade`) installs the bundled skills into each agent's skills
178
+ directory. A skill copy that differs from the bundled one and has no recorded digest is kept as it is and reported as drift, never overwritten, so your local edits survive; `crysk setup` prints each kept skill, and `crysk upgrade` replaces it.
179
+
180
+ **Skills without Crysk.** The public skills are also on
181
+ [skills.sh](https://skills.sh/cryskai/crysk), installable into any agent with the
182
+ [skills CLI](https://github.com/vercel-labs/skills):
183
+
184
+ ```bash
185
+ npx skills add cryskai/crysk # pick interactively
186
+ npx skills add cryskai/crysk --skill crysk # or crysk-pr, crysk-loop, crysk-ci-setup
187
+ ```
188
+
189
+ **On step 6.** `gotchas.md` is injected verbatim into every hunter's system prompt, and
190
+ what `setup`/`init` write there is a placeholder: `- <subsystem>: <the thing that looks
191
+ like a bug but is deliberate, and why>`. A review that reads *that* is a review billed in
192
+ full by hunters who know nothing about your repo, and it comes back looking clean. So
193
+ Crysk refuses to run while the scaffold's `human-attention-required` marker line is
194
+ still present. Write a handful of true lines, delete the marker.
195
+
196
+ Other entry points, once the above works:
197
+
198
+ ```bash
199
+ crysk # the interactive TUI menu, in a TTY
200
+ crysk review --pr # the current branch's PR, in an isolated worktree
201
+ crysk review --pr 123 # any PR by number
202
+ ```
203
+
204
+ > **Breaking change in v2.0**: Invoking `crysk` with zero arguments in a TTY now opens the **interactive TUI menu** instead of implicitly starting a local `review`. In non-interactive environments, it prints the help text and exits with code 2. Set `CRYSK_NO_TUI=1` (`PRHERO_NO_TUI=1` still works) to bypass the TUI in automation.
205
+
206
+ Every paid run prints a plan and a cost band, then asks for confirmation (`--yes` skips the prompt).
207
+
208
+ ### For AI agents
209
+
210
+ You are most likely here because someone told you to install Crysk and review a repo.
211
+ Four things go wrong when an agent runs the sequence above:
212
+
213
+ 1. **Step 2 is not optional, and not deferrable.** If each of your commands runs in its own
214
+ shell, an `export PATH=...` in one does not reach the next. Either prepend the export to
215
+ every Crysk invocation, or call the binary by absolute path: `~/.crysk/bin/crysk` (`~/.prhero/bin/pr-hero` on an install from before the rename).
216
+ 2. **Step 5 is yours.** `crysk setup` scaffolds `.crysk/` and neither commits nor
217
+ ignores it, so the next `crysk review` fails the clean-tree gate — on files `setup`
218
+ itself created. Commit them or add `.crysk/` to `.gitignore` before reviewing.
219
+ 3. **Write the gotchas yourself (step 6).** You have the repository in context, which makes
220
+ you the best gotchas author available. Read the code and write the real ones: the
221
+ deliberate oddity that looks like a bug, the invariant enforced in a file the diff never
222
+ shows, the ownership rule a newcomer would violate. Leaving the placeholder is not a
223
+ softer option — the review is refused until you replace it and delete the
224
+ `human-attention-required` marker line.
225
+ 4. **You cannot authenticate `claude`. Stop and ask the human.** Crysk spawns the Claude
226
+ Code CLI and inherits its authentication; there is no Crysk-side key to set. If
227
+ `crysk doctor` reports `claude` missing or unauthenticated, say so and wait — every
228
+ step after it fails until a person fixes it.
229
+
230
+ ## Configuration — two layers
231
+
232
+ There are two config files, and the difference between them is *who they belong to*:
233
+
234
+ | File | Whose | Committed? |
235
+ | --- | --- | --- |
236
+ | `~/.crysk/config.json` (or `~/.prhero/config.json` on an install from before the rename) | **yours**, across every repo on this machine | no — it is your machine |
237
+ | `<repo>/.crysk/config.json` | **the team's** | yes, normally — it is shared through git |
238
+
239
+ `crysk init` creates the repo file and `gotchas.md`, and never overwrites existing ones —
240
+ `crysk setup` scaffolds the same two files when it runs inside a git repo, so a repo you set up
241
+ needs no separate `init`. (Running `init` afterwards is harmless: it keeps what exists and reprints
242
+ the git reminder.) Commit `.crysk/` or add it to `.gitignore` — an untracked one trips local
243
+ mode's clean-tree gate.
244
+
245
+ **Old directory names.** The directories used to be `~/.prhero/` and `<repo>/.prhero/`, and the ignore file
246
+ `.prheroignore`. Those are still read, for one version, when the new name does not exist. Nothing is moved for
247
+ you: `crysk doctor` prints the full procedure for your machine. For the home that is the `mv ~/.prhero ~/.crysk`
248
+ plus whatever still points at the old path (the `.prhero/bin` PATH line, the launchd agents, the MCP registration),
249
+ and for a repo `git mv .prhero .crysk` (plain `mv` plus a `.gitignore` edit if the directory is not tracked) and
250
+ `git mv .prheroignore .cryskignore`. A new-named directory only wins while it holds Crysk's own files
251
+ (`~/.crysk` needs a `config.json`, `prhero.db`, `repos/` and the like; `<repo>/.crysk` needs `config.json` or
252
+ `gotchas.md`), so an empty `~/.crysk` never hides a `~/.prhero` in use. Do not create `~/.crysk` by hand while
253
+ `~/.prhero` is in use. When both hold files, the `.crysk` one wins and the old one is ignored.
254
+
255
+ **Run `crysk config` to see which layer decided what.** It lists every key with its value, the
256
+ layer it came from, and both file paths whether or not they exist. It never edits anything.
257
+
258
+ Routing a model to a specific backend/provider, and how Crysk reads credentials for each backend,
259
+ are their own topic — see [`docs/configuration.md`](docs/configuration.md).
260
+
261
+ ### The one rule
262
+
263
+ > The more specific layer wins — **except** where the less specific one is protecting your money.
264
+
265
+ So the team file usually beats your global one. The exception exists because a committed file must
266
+ never be able to enlarge *your* bill: on the two keys that spend, the team can only ask for **less**.
267
+
268
+ ### `config.json` keys
269
+
270
+ | Key | Where it can live | What it does |
271
+ | --- | --- | --- |
272
+ | `agents_dir` | both | Directory holding the agent prompt files (`deep-review-*.md`, `review-*.md`). Relative paths resolve against **the file that named it**. |
273
+ | `default_base` | **repo only** | Base ref when `--base` is not given (e.g. `"dev"`). Without it: the remote head (`origin/HEAD`), then `main`. Rejected in the global file on purpose — see below. |
274
+ | `parity_trigger_paths` | **repo only** | Glob list. The parity hunter runs only when a changed path matches one — no globs, no parity hunter. |
275
+ | `suspicion_priors` | **repo only** | `[{path, weight, reason}]` hints injected into hunter prompts — point them at your known hotspots. |
276
+ | `summary.enabled` | both — team may only turn it **off** | Whether the engine-owned summarizer runs. Defaults to `true`, because it spends money and a silent opt-out would make the bill differ from the plan. |
277
+ | `summary.model` | both | Model for that step. Defaults to whatever `prompts/summarizer.md` declares (`haiku`). |
278
+ | `max_verification_steps` | both — team may only **lower** it | Cap on re-review verification spawns (item 7). Defaults to `8`; `0` is legal and pauses verification. |
279
+ | `max_concurrent_steps` | both — team may only **lower** it | Cap on steps (hunters, refuters, verify, scout, summarizer) in flight at once. Unset means unlimited. Set it below a provider's concurrency limit (e.g. `8` for one that allows 10 in-flight requests) so a refuter fan-out does not draw HTTP 429s. |
280
+ | `max_changed_lines` | both — team may only **lower** it | Line budget threshold before the size gate skips a review. Defaults to `4000`; `0` disables line budget check. |
281
+ | `max_changed_files` | both — team may only **lower** it | File count budget threshold before the size gate skips a review. Defaults to `150`; `0` disables file budget check. |
282
+ | `scout` | both — team may only turn it **off** | Whether the reconnaissance scout hunter runs before review. Defaults to `false`. |
283
+ | `post` | both — team may only turn it **off** | Whether review reports publish as GitHub PR comments by default. Defaults to `false`. |
284
+
285
+ **Why `default_base` is repo-only, since it is the one restriction that looks arbitrary:** the
286
+ resolver checks the config value *before* the remote head. A global `default_base` would therefore
287
+ preempt autodetection on every repo that stays quiet, so the first repo whose default branch differs
288
+ would silently review the wrong commit range — with a plausible branch name on the plan card.
289
+
290
+ **Flags always win, and may exceed a cap.** A flag is you typing an intent in front of the cost band,
291
+ which is a different thing from a committed file asking on your behalf. `--agents` overrides
292
+ `agents_dir` (then the repo file, then the global, then `CRYSK_AGENTS_DIR`, or `PRHERO_AGENTS_DIR` on an install from before the rename); `--base` overrides
293
+ `default_base`; `--summary` / `--no-summary` and `--model` override the summary keys.
294
+
295
+ ### `gotchas.md`
296
+
297
+ Repo-specific traps the hunters must know (fragile invariants, deliberate oddities, past incidents).
298
+ **Required, and it must be real** — not merely non-empty. The file `init`/`setup` scaffold carries a
299
+ `human-attention-required` marker line, and `review` and `doctor` both refuse it by name: a
300
+ placeholder passes any emptiness check while telling every hunter nothing, which buys a full-price
301
+ review that reports clean. Replace the `<subsystem>` lines with facts about your repo, then delete
302
+ the marker line. Reviewing a tree you cannot write to? Supply it from outside with
303
+ `--gotchas <file>` (and `--config <file>`).
304
+
305
+ ## Commands
306
+
307
+ | Command | What it does |
308
+ | --- | --- |
309
+ | `crysk` / `crysk menu` | Open the interactive terminal user interface (TUI) with context-aware navigation, review launcher, and submenus. |
310
+ | `crysk review` | Review the checked-out branch against the merge base with `--base`. Requires a clean tree sitting on `--head` (default `HEAD`). |
311
+ | `crysk review --pr [n]` | Review a GitHub PR: by number, or — bare, no number — the PR that belongs to the current branch (errors loudly if it has none). Resolves the range through `gh`, runs in a detached worktree with its own codegraph index, then records the result in the run's `findings.json`. |
312
+ | `crysk review --pr <n> --post` | Same, then publish the report as **one** marked PR comment — re-runs update it in place, never stack. |
313
+ | `crysk doctor` | Run diagnostic environment and dependency checks (git, claude auth, gh, codegraph, config). Works inside or outside a repository. |
314
+ | `crysk setup` | Machine-level onboarding: skill synchronization and MCP registration — and, when run inside a git repo, it also scaffolds that repo's `.crysk/config.json` and `.crysk/gotchas.md`, so no separate `init` is needed there. Fully non-interactive. It does **not** commit or `.gitignore` what it scaffolds; do that yourself before reviewing. |
315
+ | `crysk activity [--kill <pid>]` | Inspect running reviews (with elapsed time, PID, repo/PR), watcher spend against daily cap, and completed run history. `--kill <pid>` safely terminates a running review. |
316
+ | `crysk post --pr <n> --from <run-dir>` | Replay-publish a previous run's findings onto the PR (same plan as `--pr --post`). `--dry-run` previews at $0. |
317
+ | `crysk triage reply --pr <n> --from <run-dir> --finding F00N --tag <tag> --body-file <path>` | Post one triage reply. The driver picks the parent from the posted `<!-- crysk-finding` marker (never path/line), renders the marker + badge, posts, and resolves the inline review thread. Reads `anchor.patch` (else `diff.patch`) from the run dir to remap post lines the same way `--post` does. `--body-file` is reasoning only. |
318
+ | `crysk status --pr <n> [--wait] [--json]` | Read-only, through `gh` only: the PR's Crysk gate, its posted findings, and a `next_action` (`wait`, `review`, `triage`, `fix`, `recheck`, `override-or-fix`, `done`). `--wait` polls until an in-flight or newly-triggered review settles before emitting (a review that has not posted its first status within 3 minutes is not waited for: counted from the `/crysk` (or `/pr-hero`) comment, or, after a push, from when `--wait` starts; a run still queued after that returns the current status); `--json` prints one `pr-hero.status/v1` object on stdout. See [`docs/github-actions.md`](docs/github-actions.md#reading-a-pr-with-crysk-status). |
319
+ | `crysk config` | Read-only, $0: every config key with its value and **which layer decided it** (`repo` / `global` / `capped` / `default`), plus both file paths whether or not they exist. |
320
+ | `crysk config set <key> <val> [--person\|--team\|--watch]` | Set a scalar configuration value in the selected layer (defaults to `--person`). Capped team keys accept and annotate over-ceiling values. |
321
+ | `crysk config unset <key> [--person\|--team\|--watch]` | Remove a configuration value from the selected layer. |
322
+ | `crysk config --edit` | Open the interactive configuration editor across Person, Team, and Watcher layers with buffered draft editing, Save/Discard/Clear actions, and capped ceiling annotations. |
323
+ | `crysk upgrade [--check]` | Upgrade `crysk` to the latest release and reconcile installed skills and MCP registrations. `--check` checks for updates without installing. |
324
+ | `crysk uninstall [--purge]` | Managed uninstallation: unloads launchd background daemons, cleans up skills, unregisters MCPs, and optionally purges `~/.crysk` with `--purge`. |
325
+ | `crysk init` | Scaffold `.crysk/` in the current repo — the command for every repo after the one you ran `setup` in. Omits keys your global file already supplies, so a new repo does not re-state what you have already said once. Idempotent: existing files are kept untouched, and it reprints the commit-or-ignore reminder. |
326
+ | `crysk watch add` | Opt the current repo (or `--repo <path>`) into the watcher; `--post` makes its reviews publish to the PR. Idempotent — re-adding updates the post flag. See [Watching PRs automatically](#watching-prs-automatically--crysk-watch). |
327
+ | `crysk watch remove` | Take the current repo (or `--repo <path>`) back out. Idempotent — removing what is not listed just says so. |
328
+ | `crysk watch status` | Read-only, $0: config summary, today's launches vs the cap, launchd state, lock, last activity. |
329
+ | `crysk watch --once` | Run ONE watcher tick: scan the watched repos, pick the next unreviewed open PR, review it. `--dry-run` shows the whole decision for $0. |
330
+ | `crysk watch install` | Install the macOS launchd agent that runs a tick every `--interval` minutes (default 15). **This is the opt-in to automatic spend.** |
331
+ | `crysk watch uninstall` | Unload and remove that agent. |
332
+ | `crysk gc` | Collect worktrees under `~/.crysk` that are merged/closed or idle >72h. `--dry-run` prints the table and removes nothing. `--repo <clone>` scopes to one origin; default is the whole home. Also removes leftover verified execution snapshots under `$TMPDIR/prhero-exec-snapshots` (dead owner process or older than 6h). |
333
+ | `crysk gc install` | Install the macOS launchd agent that runs `crysk gc` every `--interval` minutes (default 360 = 6h). No reviews, no `watch.json`, no daily cap — the $0 sweeper so trees do not wait for a review or the watcher. |
334
+ | `crysk gc uninstall` | Unload and remove that GC agent. |
335
+ | `crysk gc status` | Read-only, $0: whether the GC agent is installed, its interval, plist, and tick log. |
336
+ | `crysk usage [--all]` | Read-only, $0: print the observability store's per-run rows (cost, tokens, findings) — every completed review, local and PR, auto-ingests into one global `~/.crysk/metrics.db`. Scoped to the current checkout's origin by default; `--all` shows every origin instead. |
337
+
338
+ Flags worth knowing: `--dry-run` (plan + cost band, creates nothing), `--yes`, `--model <m>`,
339
+ `--scout` / `--no-scout` (toggle pre-hunt reconnaissance scout),
340
+ `--no-shared-prefix` (turn off the default shared hunter prefix: hunters share one cached system prompt
341
+ holding the patch, their roles move to the user message and a one-turn warm-up writes the cache first; Anthropic routes only,
342
+ since other providers already cache each hunter's own loop),
343
+ `--post` / `--no-post` (toggle PR comment publishing),
344
+ `--force` (local only: review this diff even when the size gate would skip it;
345
+ in GitHub Actions the same forced re-review is a `/crysk review` comment on the pull request,
346
+ which runs on the Actions runner; `/crysk override` instead unlocks a red gate with no review),
347
+ `--full` (run un-capped refuter verification steps),
348
+ `--no-summary` (skip the summarizer; see `summary` in config above),
349
+ `--out <dir>` (run dir for `review`),
350
+ `--all` (`usage` only: every origin instead of just this checkout's).
351
+ `crysk --help` lists everything.
352
+
353
+ ### PR mode, in one paragraph
354
+
355
+ `--pr` resolves the range from the PR itself: a merged PR diffs from its merge commit's first parent
356
+ (the base as it was when the PR landed — merge, squash and rebase all converge at the fork point),
357
+ an open one from the recorded base tip. The review runs in a worktree at
358
+ `~/.crysk/repos/<origin>/worktrees/pr-<n>` — your checkout, your index and your uncommitted work are
359
+ never touched, and reviews run while you keep working. Two checkouts of the same GitHub repo share
360
+ one worktree. Worktrees are kept and reused across re-runs until GC (`crysk gc`: merged/closed or
361
+ 72h idle). That collector is not a background timer — it runs when you invoke it, at the end of
362
+ `review --pr`, on a watcher tick, or on a schedule via `crysk gc install` (macOS launchd, default
363
+ every 6h, no reviews, no `watch.json`). Each run prints the cleanup command (`git worktree remove --force …` — never `rm -rf`, a live
364
+ codegraph daemon holds a socket in there).
365
+
366
+ ## When to run it
367
+
368
+ Reviews launch two ways: **by hand**, or through the opt-in local watcher (`crysk watch`, below)
369
+ — nothing else ever fires on its own. The two moments where a manual run makes sense:
370
+
371
+ 1. **Before opening the PR** — `crysk review` on your branch. The cheapest moment to catch
372
+ something: you are still in context and nothing is published yet.
373
+ 2. **On an existing PR** — the moment it opens, standing on its branch, the whole command is:
374
+
375
+ ```bash
376
+ crysk review --pr --post
377
+ ```
378
+
379
+ Bare `--pr` resolves the branch's own PR (loud error if there is none), the review runs in its
380
+ worktree while you keep working, and `--post` publishes the one marked comment. A PR number works
381
+ anywhere (`--pr <n>`), no matter what you have checked out.
382
+
383
+ ### Automation and CI — status
384
+
385
+ | Stage | Status |
386
+ | --- | --- |
387
+ | Manual CLI (`review`, `--pr`, `--post`) | **Available now** — this README. |
388
+ | Auto-trigger on new PRs / new pushes (local watcher) | **Available now** — `crysk watch`, below. Deliberately opt-in: every review spends real money, so nothing fires until you `watch add` a repo AND `watch install` the agent. |
389
+ | CI mode (GitHub Actions) | **Available now** — official `action.yml` at the repo root, canonical `.github/workflows/crysk.yml` (a repo that already has `pr-hero.yml` keeps it), full setup in [`docs/github-actions.md`](docs/github-actions.md). The commit-status gate (`mode: gate`, the default; `mode: advisory` opts out), exit 0 on findings, the size/budget gates, and `crysk setup --ci` scaffolding all apply. |
390
+ | Required status check that blocks merges | **Available in CI** — the `crysk` commit status is the check (`mode: gate`, the default; `pr-hero` is still posted for one version). Require it in branch protection. Fail-closed for a head with no run stays deferred. |
391
+
392
+ ## Watching PRs automatically — `crysk watch`
393
+
394
+ The watcher is a **tick, not a daemon**: `crysk watch --once` makes one pass — list open PRs in
395
+ each configured repo, skip what is already covered, launch **at most one** review — and exits.
396
+ launchd (installed below) fires a tick every N minutes and is the supervisor. Drafts are skipped,
397
+ and each PR is reviewed **once** by default — see the `on_push` knob below.
398
+
399
+ ### Opt in
400
+
401
+ ```bash
402
+ cd /path/to/your-repo
403
+ crysk init # once per repo, if .crysk/ does not exist yet
404
+ crysk watch add --post # opt THIS repo in; --post publishes each review to its PR
405
+ crysk watch install # start ticking — this is the moment automatic spending starts
406
+ crysk watch status # anytime: config, cap usage, launchd, lock, last activity
407
+ ```
408
+
409
+ A repo is watched **only** if added (`--repo <path>` works from anywhere; `watch remove` takes it
410
+ back out; both are idempotent). Preview any tick for $0 first: `crysk watch --once --dry-run`
411
+ prints every candidate, every skip and its reason (draft / reviewed-local / reviewed-remote /
412
+ in-flight / attempts / cap / window), and the one (pr, head) a real tick would launch. `install` accepts
413
+ `--interval <min>` (default 15) and captures your current `PATH` (launchd's own PATH knows nothing
414
+ of `bun`, `gh`, `claude` or `codegraph`) — re-run `install` after moving tools around;
415
+ `watch uninstall` stops the schedule.
416
+
417
+ Worktree GC is a **separate** agent: `crysk gc install` (default every 6 hours, `--interval` in
418
+ minutes). It runs `crysk gc` — no reviews, no `watch.json`, no daily cap. Preview with
419
+ `crysk gc --dry-run`; `gc status` / `gc uninstall` match the watcher verbs.
420
+
421
+ ### The underlying file — `~/.crysk/watch.json`
422
+
423
+ `watch add`/`watch remove` own the repo list — there is no need to edit the file by hand for
424
+ membership, and their rewrites preserve any keys they do not know. The two global knobs are still
425
+ plain JSON you may tune directly:
426
+
427
+ ```json
428
+ {
429
+ "repos": [{ "path": "~/Desktop/your-repo", "post": true }],
430
+ "daily_cap": 5,
431
+ "window": { "start": "09:00", "end": "19:00" }
432
+ }
433
+ ```
434
+
435
+ | Key | Default | What it does |
436
+ | --- | --- | --- |
437
+ | `repos[].path` | — | Operator checkout of a repo to watch (its `.crysk/` config and gotchas are used, exactly like `review --pr`). Managed by `watch add`/`remove`. |
438
+ | `repos[].post` | `false` | Pass `--post` to the spawned review — publish each result as the PR's one marked comment. Managed by `watch add [--post]`. |
439
+ | `repos[].on_push` | `false` | Re-review the repo's PRs on every new push. Default: one review per PR — see below. Managed by `watch add [--on-push]`. |
440
+ | `daily_cap` | `5` | Global max reviews launched per local calendar day, across all repos. `0` pauses launching entirely. |
441
+ | `window` | `null` (always) | Local-time window outside which ticks do nothing, e.g. `{"start":"09:00","end":"19:00"}`. Overnight windows (`start` > `end`) work. |
442
+
443
+ ### One review per PR — the `on_push` knob
444
+
445
+ By default a push to an already-reviewed PR does **not** re-trigger a review: an active PR takes
446
+ many pushes, and re-billing $2–5 for each would drain the cap on one PR's churn. The posted
447
+ comment names the exact sha it reviewed, so it never lies about coverage — a reader sees at a
448
+ glance that later pushes are unreviewed. When the new head deserves a fresh pass, run it by hand
449
+ (`crysk review --pr <n> --post`); `crysk watch add --on-push` restores per-push re-review for
450
+ a repo that wants it. Planned follow-up: a cheap independent judge that reacts to pushes by
451
+ checking whether the new head addressed the posted findings and replies in-thread, instead of
452
+ re-reviewing from scratch.
453
+
454
+ ### What keeps the bill bounded
455
+
456
+ - **The cap and the window** exist because the watcher and your interactive Claude sessions share
457
+ the same subscription quota — a runaway watcher would starve the work you are actually doing.
458
+ The cap is counted from `~/.crysk/watch.log` (the `launched` lines ARE the counter), and a
459
+ launch is logged *before* it starts, so even a crashed review counts.
460
+ - **Max 2 attempts per (pr, head)**: a PR that keeps killing the review is dropped until it gets
461
+ a new push, instead of eating the cap every day.
462
+ - **Cross-machine guard**: a posted Crysk comment declares which head it reviewed; any watcher
463
+ that sees the current head already declared skips the PR (and under the one-review-per-PR
464
+ default, any Crysk comment at all is proof enough). A fresh pending `crysk` commit status
465
+ on the head (the yellow dot while a review is running) skips as `in-flight`.
466
+
467
+ ### Operating model and honest limits
468
+
469
+ Run **one watcher per repo per team**. The comment-based cross-machine guard only protects repos
470
+ with `post: true`, and only after the first comment lands. A pending `crysk` commit status
471
+ closes the rest of the race once either review has started — two watchers can still duplicate
472
+ if both launch before either posts `pending`. With `post: true` the PR still converges to a
473
+ single comment. Not macOS? `watch --once` from cron works the same —
474
+ the PID lockfile keeps overlapping ticks from doubling up. Logs: structured events in
475
+ `~/.crysk/watch.log`, raw tick/review output in `~/.crysk/launchd.log`.
476
+
477
+ ## What a run produces
478
+
479
+ Run artifacts land **outside** the repo, in `~/.crysk/repos/<origin>/runs/<run>/`:
480
+
481
+ | File | What it is |
482
+ | --- | --- |
483
+ | `report.md` | The human-readable review. |
484
+ | `findings.json` | The machine artifact (schema v1.0.0): findings, tiers, refuter verdicts, usage, provenance. |
485
+ | `diff.patch`, `pipeline.json`, `steps/` | The exact diff reviewed — after exclusions, so it is byte-for-byte what the hunters read — plus pipeline provenance (including the excluded paths), per-agent drafts and logs. |
486
+ | `diff.raw.patch` | The unfiltered diff of the same range. Written **only** when exclusions actually dropped a file, since otherwise it would duplicate `diff.patch`. |
487
+ | `anchor.patch` | The full PR diff (merge-base..head, after exclusions) that inline comments anchor against. On a first review it equals `diff.patch`; on an incremental re-review `diff.patch` is only the push delta, and this file still covers the whole PR, so a finding on an untouched line of the PR gets a review thread. |
488
+
489
+ ## Cost and expectations
490
+
491
+ - **$2–5 per review** of a typical PR-sized diff — the floor is real, because hunters read the tree,
492
+ not just the diff — and larger trees cost more (a 45-file tree measured $11–15). Wall time is
493
+ minutes, not seconds: ~10 for a small diff, up to ~25 measured on a large tree. The printed band
494
+ is an order-of-magnitude guide, not a quote — the same tree has billed 34% apart across runs.
495
+ ### The size gate — a cost gate, not a quality gate
496
+
497
+ Past a size threshold Crysk **skips the review** instead of running it. Small trees bill $1.9–$4.8;
498
+ the 45-file / +2775 −1237 bench tree billed $6.58–$17.92 across 18 iterations — the cost roughly
499
+ triples *and* its spread widens to ~2.7x. The gate exists because that bill is unpredictable, and
500
+ because an unattended watcher must not be the thing that discovers it.
501
+
502
+ **It is not a claim about quality.** We have no evidence that a bigger diff reviews worse: attention
503
+ dilution was tested and falsified (`fixtures/scale-probe.ts`), and the one measured Greptile-only
504
+ miss came from a 7-file PR. If a large diff is worth its price, review it anyway.
505
+ Locally that is `--force`. In GitHub Actions it is a pull request comment, `/crysk review`,
506
+ from a user with write access (a workflow scaffolded before the comment trigger uses
507
+ `gh workflow run pr-hero-force.yml -f pr=<n>` instead). The comment does not review on your
508
+ machine; the Actions runner does. It also clears the CI admission rules and the budget ceiling for
509
+ that one run. `gh run rerun` on a skipped run does not: it measures the gates again and skips again.
510
+
511
+ The gate counts **effective** changed lines (insertions + deletions) and files — excluded content is
512
+ subtracted first, so a regenerated lockfile beside a ten-line change does not trip it. Excluded by
513
+ default: `bun.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`, `go.sum`,
514
+ `*.min.js`, `*.min.css`, `*.snap`. A repo can add its own exclusions with `.cryskignore` — see
515
+ below.
516
+
517
+ Those exclusions come out of the **reviewed diff itself**: `diff.patch` is what the hunters are
518
+ handed, so the number the gate measures is the number that gets paid for. If every changed file is
519
+ excluded, there is nothing to review — Crysk exits without spawning anything.
520
+
521
+ ### `.cryskignore` — repo-defined exclusions
522
+
523
+ A `.cryskignore` file at the **repo root** adds your own exclusions on top of the 9 defaults above.
524
+ The dialect is a **subset of gitignore(5)**, not a full reimplementation — most everyday patterns
525
+ work exactly like `.gitignore`, but two things are worth knowing before you rely on it:
526
+
527
+ - **Only one file, at the repo root, is read.** Nested per-directory `.cryskignore` files (the way
528
+ git supports a `.gitignore` in every directory) are **not** read. A file at
529
+ `openspec/.cryskignore` is silently ignored — put every rule in the one at the repo root instead.
530
+ - **Matching is case-sensitive**, matching git's own behavior. This is a deliberate departure from
531
+ the `ignore` npm package (the common JS gitignore implementation), which is case-insensitive by
532
+ default — if that is where your intuition comes from, `README.md` will not match `readme.md` here.
533
+
534
+ Supported: comments (`#`) and blank lines, negation (`!pattern` re-includes), anchoring
535
+ (a leading or interior `/`), trailing-slash directory-only rules, `*`/`?`/`[a-z]`-style classes,
536
+ `**` at any position (including matching zero directories), and literal `{`/`}` (this dialect has no
537
+ brace-alternation syntax — braces are always literal characters, unlike some glob libraries).
538
+ The **last matching rule wins**, builtins evaluated first, then your file's rules in order — so a
539
+ rule can re-include one of the 9 defaults (`!bun.lock`) or exclude something the defaults do not.
540
+
541
+ One documented deviation from real git: unlike `git`, which cannot re-include a file whose parent
542
+ directory is itself excluded (gitignore(5) states this outright — it is a tree-walk optimization),
543
+ this engine matches a finite diff file list, not a tree walk, so `docs/` then `!docs/keep.md` DOES
544
+ re-include `docs/keep.md` here.
545
+
546
+ Under CI (GitHub Actions, or any `CI`/`GITHUB_ACTIONS` environment), `.cryskignore` is read from
547
+ the PR's **base ref**, never the PR's own branch — a PR cannot widen its own exclusions to hide
548
+ changes from its own review. Local review, and local `--pr <n>` review without CI, read it from your
549
+ working tree instead. A malformed file aborts the whole review before anything is spent, naming the
550
+ file, line number, and offending text.
551
+
552
+ `crysk watch` honors `.cryskignore` too, in its per-tick scheduling filter (both the aggregate
553
+ check and the per-file rescue), and in a one-call pre-launch check that catches a PR whose files are
554
+ all excluded but whose aggregate alone would not have flagged it. It reads `.cryskignore` from the
555
+ watched repo's own working tree on the machine running the watcher — never a base ref — because the
556
+ watcher runs from an operator's own checkout of a repo that operator explicitly opted in, with no PR
557
+ author supplying that checkout the way CI's PR-triggered runs have one.
558
+
559
+ The count is also **whitespace-blind wherever git is reachable** (local mode and PR mode count from
560
+ `git diff -w --ignore-blank-lines --numstat`), so a formatter or linter sweep does not consume the
561
+ budget. Two paths cannot be: `--pr <n> --dry-run` and the watcher's per-tick checks read GitHub's own
562
+ counters, which carry no whitespace information — both label their verdict an estimate, and both can
563
+ only ever over-count, never under-count.
564
+
565
+ | Profile | Lines | Files | For |
566
+ | --- | --- | --- | --- |
567
+ | Conservative | `--max-changed-lines 800` | `--max-changed-files 150` | Tight budget; only small PRs auto-review. |
568
+ | **Default (shipped)** | **4000** | **150** | Everyday PRs pass; only very large trees are skipped. |
569
+ | Permissive | `--max-changed-lines 0` | `--max-changed-files 150` | You would rather pay than skip — disables the line limit. |
570
+
571
+ ```bash
572
+ crysk review --pr 42 --dry-run # prints the gate verdict, spends nothing
573
+ crysk review --pr 42 --force # local: review it anyway (does NOT skip the cost prompt)
574
+ gh pr comment 42 --body "/crysk review" # CI: same forced re-review, on the Actions runner
575
+ gh pr comment 42 --body "/crysk override" # CI: unlock a red gate on this head, no review, $0
576
+ gh pr comment 42 --body "/crysk stop" # CI: skip automatic reviews on later pushes, until /crysk review
577
+ crysk review --pr 42 --max-changed-lines 0 # 0 disables that limit entirely
578
+ crysk watch add --max-changed-lines 800 # per-repo threshold for the watcher
579
+ ```
580
+
581
+ A skipped review exits 1 with a one-line reason and no stack. In watch mode it logs
582
+ `skipped … reason=too-large` (or `reason=nothing-to-review`, when every changed file is excluded)
583
+ and costs nothing further: it does **not** consume a poison-PR attempt,
584
+ writes no review marker, and does not arm the one-review-per-PR state — a force-push that shrinks the
585
+ PR makes it eligible again on the next tick, because the gate is recomputed every tick.
586
+
587
+ - Findings vary run to run on the same tree. That is the nature of the instrument: treat single
588
+ runs as evidence, not verdicts, and triage before acting.
589
+ - Verify what it reports. Findings are claims with cited code, tiered by deterministic rules — the
590
+ report says so itself. An advisory report reads *assistant report, not a merge gate; every line is a claim to
591
+ verify.* A CI report in gate mode backs the `crysk` commit status, the required check: a blocking finding
592
+ sets that status to failure.
593
+
594
+ ## Isolation model
595
+
596
+ Spawned agents run with a read-only tool surface (Read/Grep/Glob plus the codegraph MCP server and
597
+ nothing else): no Write, no Bash, no network tools, `--strict-mcp-config`, no user settings. The
598
+ driver owns every file write and all `gh`/`git` I/O. In PR mode the reviewed tree is a detached
599
+ worktree containing only tracked bytes at the PR's head — agents never see your working copy.
600
+
601
+ ## Development
602
+
603
+ ```bash
604
+ bun test # offline test suite — no network, no spawns, fake runners
605
+ bun run typecheck # tsc --noEmit, strict
606
+ bun run check # biome over src + test
607
+ ```
608
+
609
+ The architecture in one line each lives in `CLAUDE.md`; the stage plan lives in `ROADMAP.md`,
610
+ and the earlier phases in `docs/history/`. The short version: the flow is data (`ReviewSpec`), agents are
611
+ prompt files, orchestration is testable TypeScript — models judge, code governs.