crysk 0.6.1 → 0.8.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 (179) hide show
  1. package/README.md +28 -22
  2. package/dist/SKILL-1q3658n0.md +74 -0
  3. package/dist/SKILL-25j4q9b8.md +143 -0
  4. package/dist/SKILL-32cmme3j.md +143 -0
  5. package/dist/SKILL-4747bhne.md +143 -0
  6. package/dist/SKILL-4jc3sv23.md +74 -0
  7. package/dist/SKILL-c0492rch.md +540 -0
  8. package/dist/SKILL-d1nzkhhr.md +74 -0
  9. package/dist/SKILL-f8p7kvx0.md +143 -0
  10. package/dist/SKILL-gxd45g38.md +553 -0
  11. package/dist/SKILL-rec41991.md +66 -0
  12. package/dist/SKILL-zze8zj5g.md +536 -0
  13. package/dist/adjudicator-eckqh14e.md +78 -0
  14. package/dist/ci-admission-qn797a6c.md +128 -0
  15. package/dist/cli.js +18608 -18523
  16. package/dist/consolidate-4xw1pkg7.md +24 -0
  17. package/dist/deep-review-logic-dgr112y1.md +196 -0
  18. package/dist/deep-review-logic-fck5z4xe.md +197 -0
  19. package/dist/deep-review-logic-h1fpamfh.md +192 -0
  20. package/dist/deep-review-logic-m4vk5683.md +196 -0
  21. package/dist/deep-review-logic-z63kmgmc.md +157 -0
  22. package/dist/deep-review-parity-7x7s5d81.md +148 -0
  23. package/dist/deep-review-parity-9wxmynsc.md +115 -0
  24. package/dist/deep-review-parity-bwwe7cx6.md +152 -0
  25. package/dist/deep-review-parity-e50pw3pk.md +117 -0
  26. package/dist/deep-review-parity-ennmm9m1.md +151 -0
  27. package/{prompts/default/deep-review-parity.md → dist/deep-review-parity-h7y6y2he.md} +14 -16
  28. package/dist/deep-review-parity-xg6wy69c.md +151 -0
  29. package/dist/deep-review-reliability-6h3c4gmw.md +125 -0
  30. package/dist/deep-review-reliability-dcjab69x.md +122 -0
  31. package/dist/deep-review-reliability-ec7b5pbk.md +159 -0
  32. package/dist/deep-review-reliability-hvasvmt9.md +153 -0
  33. package/dist/deep-review-reliability-mjnayxmt.md +158 -0
  34. package/dist/deep-review-reliability-mm7fnayf.md +124 -0
  35. package/dist/deep-review-reliability-xk4xvc2w.md +158 -0
  36. package/dist/deep-review-resilience-0esd5qeh.md +148 -0
  37. package/dist/deep-review-resilience-envgcmpy.md +115 -0
  38. package/dist/deep-review-resilience-fgx8ythf.md +151 -0
  39. package/dist/deep-review-resilience-mq5qa6ad.md +152 -0
  40. package/dist/deep-review-resilience-pwh1gawp.md +151 -0
  41. package/dist/deep-review-resilience-s9n21dkx.md +117 -0
  42. package/dist/deep-review-resilience-vz4qskea.md +119 -0
  43. package/dist/deep-review-security-1vwjdc9q.md +205 -0
  44. package/dist/deep-review-security-x1cc1z00.md +205 -0
  45. package/dist/index.js +590 -485
  46. package/dist/opencode-ci-jc8mf4wn.md +106 -0
  47. package/dist/opencode-ci-qrcv7a99.md +106 -0
  48. package/dist/opencode-ci-rdpcc7xc.md +106 -0
  49. package/dist/opencode-ci-yt0k74t0.md +106 -0
  50. package/dist/review-refuter-7qffwtzz.md +77 -0
  51. package/dist/verifier-tyh8r45v.md +40 -0
  52. package/dist/verifier-xf4xj701.md +40 -0
  53. package/dist/workflow-andv2dvm.yml +158 -0
  54. package/package.json +1 -1
  55. package/prompts/consolidate.md +1 -1
  56. package/prompts/default/PROVENANCE.md +6 -0
  57. package/prompts/default/deep-review-logic.md +56 -15
  58. package/prompts/default/deep-review-reliability.md +64 -30
  59. package/prompts/default/deep-review-resilience.md +71 -37
  60. package/prompts/default/deep-review-security.md +205 -0
  61. package/prompts/default/review-refuter.md +1 -1
  62. package/prompts/verifier.md +40 -0
  63. package/skills/crysk/SKILL.md +6 -6
  64. package/skills/crysk-ci-setup/SKILL.md +32 -33
  65. package/skills/crysk-ci-setup/assets/workflow.yml +5 -10
  66. package/skills/crysk-ci-setup/references/ci-admission.md +5 -5
  67. package/skills/crysk-ci-setup/references/opencode-ci.md +6 -6
  68. package/skills/crysk-loop/SKILL.md +37 -54
  69. package/skills/crysk-loop/adjudicator.md +10 -18
  70. package/skills/crysk-pr/SKILL.md +1 -1
  71. package/src/asset-manifest.ts +6 -6
  72. package/src/assets.ts +4 -4
  73. package/src/brand.ts +20 -30
  74. package/src/ci/gates.ts +155 -192
  75. package/src/ci/outcome.ts +4 -31
  76. package/src/ci/platform-limits.ts +135 -0
  77. package/src/ci/platform-report.ts +212 -126
  78. package/src/ci/platform.ts +28 -26
  79. package/src/ci/reporter.ts +25 -26
  80. package/src/ci/review-admission.ts +1 -2
  81. package/src/ci/review-levels.ts +12 -53
  82. package/src/ci/setup.ts +96 -66
  83. package/src/ci/trace-bundle.ts +11 -27
  84. package/src/ci/trace-transcripts.ts +4 -6
  85. package/src/ci/trigger.ts +3 -5
  86. package/src/cli.ts +6 -5
  87. package/src/commands/ci-setup-questions.ts +2 -55
  88. package/src/commands/ci-setup.ts +2 -26
  89. package/src/commands/triage.ts +131 -38
  90. package/src/commands/usage.ts +0 -1
  91. package/src/compare/compare.ts +3 -3
  92. package/src/compare/floor-test.ts +30 -201
  93. package/src/compare/hunter-exam.ts +631 -0
  94. package/src/config/config.ts +6 -30
  95. package/src/diversity/accounting.ts +0 -26
  96. package/src/diversity/benchmark.ts +1 -17
  97. package/src/diversity/identity.ts +0 -14
  98. package/src/diversity/pipeline-integration.ts +0 -29
  99. package/src/doctor.ts +3 -6
  100. package/src/execution/claude-session-trace.ts +7 -2
  101. package/src/execution/contracts.ts +15 -9
  102. package/src/execution/harness.ts +165 -187
  103. package/src/execution/spend-limiter.ts +39 -131
  104. package/src/execution/usage-facts.ts +397 -0
  105. package/src/execution/usage-normalized.ts +33 -86
  106. package/src/harness/materiality-judge.ts +0 -5
  107. package/src/harness/pipeline-plan.ts +0 -3
  108. package/src/harness/replay-rows.ts +0 -5
  109. package/src/harness/route-runner.ts +2 -2
  110. package/src/harness/single-step.ts +3 -9
  111. package/src/index.ts +1 -1
  112. package/src/mcp/preflight.ts +2 -2
  113. package/src/model/catalog.ts +1 -3
  114. package/src/model/free-discovery.ts +11 -78
  115. package/src/model/model-name.ts +16 -5
  116. package/src/model/profiles/claude.ts +1 -2
  117. package/src/model/profiles/openai.ts +1 -2
  118. package/src/model/profiles.ts +2 -3
  119. package/src/model/provider-capabilities.ts +16 -55
  120. package/src/model/routing.ts +39 -36
  121. package/src/pr/admission.ts +6 -6
  122. package/src/pr/answered-findings.ts +8 -4
  123. package/src/pr/ci-publish.ts +0 -2
  124. package/src/pr/discovery.ts +4 -25
  125. package/src/pr/plan.ts +40 -121
  126. package/src/pr/pr-status.ts +14 -2
  127. package/src/pr/pr.ts +1 -1
  128. package/src/pr/preflight.ts +44 -15
  129. package/src/pr/publish-outcome.ts +1 -19
  130. package/src/pr/review-pr.ts +15 -47
  131. package/src/pr/target.ts +76 -82
  132. package/src/production-runtime.ts +52 -114
  133. package/src/progress.ts +0 -54
  134. package/src/rereview/prepare.ts +4 -1
  135. package/src/rereview/state.ts +1 -1
  136. package/src/rereview/verify.ts +15 -9
  137. package/src/review/boundary.ts +5 -8
  138. package/src/review/drafts.ts +3 -3
  139. package/src/review/findings-conformance.ts +1 -1
  140. package/src/review/findings.ts +0 -4
  141. package/src/review/pipeline.ts +194 -407
  142. package/src/review/preflight.ts +175 -201
  143. package/src/review/prompt-set.ts +1 -2
  144. package/src/review/report.ts +2 -162
  145. package/src/review/review.ts +25 -74
  146. package/src/review/route-preflight.ts +19 -35
  147. package/src/review/run.ts +37 -73
  148. package/src/review/size-gate.ts +3 -3
  149. package/src/review/spec.ts +6 -11
  150. package/src/review/step-runner.ts +4 -4
  151. package/src/runner-authority.ts +10 -9
  152. package/src/security/credential-broker.ts +5 -6
  153. package/src/server/preflight.ts +0 -1
  154. package/src/server/server.ts +17 -6
  155. package/src/store/activity.ts +1 -2
  156. package/src/store/backfill-preflight.ts +0 -3
  157. package/src/store/backfill.ts +0 -1
  158. package/src/store/metrics-preflight.ts +4 -14
  159. package/src/store/metrics.ts +5 -5
  160. package/src/store/preflight.ts +0 -13
  161. package/src/store/store.ts +11 -12
  162. package/src/transport-registry.ts +6 -30
  163. package/src/transports/claude-code-cli.ts +149 -215
  164. package/src/transports/opencode-client.ts +4 -24
  165. package/src/transports/opencode-sdk.ts +17 -112
  166. package/src/triage/plain-reply.ts +37 -0
  167. package/src/ui/activity.ts +1 -6
  168. package/src/ui/config-edit.ts +14 -67
  169. package/src/ui/config.ts +3 -8
  170. package/src/ui/plan.ts +11 -198
  171. package/src/ui/progress.ts +3 -49
  172. package/src/ui/result.ts +18 -77
  173. package/src/ui/review-menu.ts +3 -12
  174. package/src/ui/select.ts +9 -79
  175. package/src/updater.ts +1 -1
  176. package/src/usage.ts +1 -7
  177. package/prompts/scout.md +0 -140
  178. package/src/ci/platform-estimate.ts +0 -111
  179. package/src/review/scout.ts +0 -323
package/README.md CHANGED
@@ -9,7 +9,9 @@ finding, and deterministic code — never a model — assigns blocking/advisory
9
9
  Its measured profile, stated up front: **high precision, narrow coverage**. What it reports is
10
10
  almost always real (13% false positives measured). Its hunters check value contracts across the diff
11
11
  (units, domain, conversions, what consumers assume), resilience (lookup and dedupe keys, retries and
12
- locks, CI guards, test isolation), local logic errors, and access-control parity with sibling code;
12
+ locks, CI guards, test isolation), local logic errors, and trust boundaries (outside input reaching a
13
+ query, command, file path or server-side request; missing or misplaced permission checks; a hunter
14
+ added 2026-11-15, after that measurement);
13
15
  stale state, races and component lifecycle have no dedicated hunter since 2026-11-08. It says nothing
14
16
  about style or convention. Locally it is an **assistant, not a merge gate**: every report closes with that
15
17
  disclaimer, and nothing it prints blocks a merge. In CI its commit status is a gate by default: require the
@@ -18,9 +20,9 @@ green.
18
20
 
19
21
  > **Renamed from pr-hero.** Crysk used to be `pr-hero`. The package is now `crysk` (`npm install -g crysk`,
20
22
  > `npx -y crysk`), and the `pr-hero` command stays as an alias for one version. What an install made under the
21
- > old name wrote is still read for one version: `/pr-hero …` comments, `PRHERO_*` variables, `<!-- pr-hero-…`
23
+ > old name wrote is still read for one version: `PRHERO_*` variables, `<!-- pr-hero-…`
22
24
  > markers, `pr-hero` commit statuses (read, no longer written), `~/.prhero`, `.prhero/` and `.prheroignore`. A workflow file scaffolded
23
- > before the rename only answers `/pr-hero …`: re-run `crysk ci init --force` for it to accept `/crysk …` too.
25
+ > before the rename only answers `/pr-hero …`, which is no longer a command: re-run `crysk ci init --force` for it to accept `/crysk …`.
24
26
  > 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.
25
27
 
26
28
  ## Two ways to use it
@@ -49,8 +51,7 @@ to install it (macOS with Homebrew) and to run `gh auth login`. It never blocks
49
51
  `crysk-loop` answers the findings. `crysk` covers the local CLI, which this path does not use.
50
52
 
51
53
  2. **Ask your agent to set up Crysk CI** in the repository. `crysk-ci-setup` first asks you how
52
- re-reviews should work: a level (minimal, balanced, thorough or manual), gate or advisory, how CI
53
- pays (a subscription gets no spend ceiling, an API key gets one you choose), the changed-lines
54
+ re-reviews should work: a level (minimal, balanced, thorough or manual), gate or advisory, the changed-lines
54
55
  threshold above which a PR is skipped (default 4000, on any billing), and whether to tune the
55
56
  advanced settings (score weights, observe-only, trusted actors, files limit, exclusions). Then it runs
56
57
  `npx -y crysk setup --ci` with your answers (writes `.github/workflows/crysk.yml`, or updates an existing `pr-hero.yml` in place, and the
@@ -115,10 +116,10 @@ not used: on macOS a Claude login always counts. To bill the key, put it first i
115
116
  `{"credentials": {"claude": ["api_key", "subscription"]}}`. The Claude CLI child sees only the chosen
116
117
  credential.
117
118
 
118
- The dollar figures Crysk prints — the cost band before a run, `crysk usage` after one — are
119
- always a **token-derived estimate**, because that is the only unit comparable across both models. On
120
- a subscription, read them as "how much of my window will this consume", not as a bill. A step on an
121
- OpenCode model bills to that provider's credential instead (see [`docs/configuration.md`](docs/configuration.md)).
119
+ Crysk prints no dollar figure: neither the plan before a run nor the result after one shows a cost. The Crysk
120
+ platform prices every run from the tokens and models the engine reports, and owns the dollar limits (see
121
+ [`docs/github-actions.md`](docs/github-actions.md#spend-controls)). A step on an OpenCode model bills to that
122
+ provider's credential instead (see [`docs/configuration.md`](docs/configuration.md)).
122
123
 
123
124
  ## Installation
124
125
 
@@ -215,7 +216,7 @@ crysk review --pr 123 # any PR by number
215
216
 
216
217
  > **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.
217
218
 
218
- Every paid run prints a plan and a cost band, then asks for confirmation (`--yes` skips the prompt).
219
+ Every run prints a plan, then asks for confirmation (`--yes` skips the prompt).
219
220
 
220
221
  ### For AI agents
221
222
 
@@ -285,17 +286,17 @@ never be able to enlarge *your* bill: on the two keys that spend, the team can o
285
286
  | --- | --- | --- |
286
287
  | `agents_dir` | both | Directory holding the agent prompt files (`deep-review-*.md`, `review-*.md`). Relative paths resolve against **the file that named it**. |
287
288
  | `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. |
288
- | `parity_trigger_paths` | **repo only** | Glob list. The parity hunter runs only when a changed path matches one — no globs, no parity hunter. |
289
289
  | `suspicion_priors` | **repo only** | `[{path, weight, reason}]` hints injected into hunter prompts — point them at your known hotspots. |
290
290
  | `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. |
291
- | `models` | **global only** | The models per role (`default`, `hunter.<key>`, `refuter`, `consolidate`, `scout`, `summary`, `judge`), each a list of one to three tried in order, e.g. `{"summary": ["claude:haiku-latest"]}`. Unset, each step runs the model its prompt declares. See [Models](docs/configuration.md#models). `summary.model` is gone: `"haiku"` still reads, with a warning; anything else is refused. |
291
+ | `models` | **global only** | The models per role (`default`, `hunter.<key>`, `refuter`, `consolidate`, `summary`, `judge`), each a list of one to three tried in order, e.g. `{"summary": ["claude:haiku-latest"]}`. Unset, each step runs the model its prompt declares. See [Models](docs/configuration.md#models). `summary.model` is gone: `"haiku"` still reads, with a warning; anything else is refused. `models.scout` is still accepted and ignored, with a warning: the scout stage was removed. |
292
292
  | `profile` | **global only** | The ready-made models for every role: `claude` (the default) or `openai`, e.g. `"profile": "openai"`. `models` still wins role by role. See [Profiles](docs/configuration.md#profiles). |
293
293
  | `credentials` | **global only** | Which Claude credential a run uses, in order: `{"claude": ["subscription", "api_key"]}` (the default). See [Credentials](docs/configuration.md#credentials). |
294
294
  | `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. |
295
- | `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. |
295
+ | `max_concurrent_steps` | both — team may only **lower** it | Cap on steps (hunters, refuters, verify, 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. |
296
296
  | `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. |
297
297
  | `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. |
298
- | `scout` | both — team may only turn it **off** | Whether the reconnaissance scout hunter runs before review. Defaults to `false`. |
298
+ | `scout` | both | Removed. The key is still accepted and ignored, with a warning (`scout is ignored: the scout stage was removed`); `crysk config set scout` is refused. |
299
+ | `parity_trigger_paths` | both | Removed with the parity hunter. The key is still accepted and ignored, with a warning (`parity_trigger_paths is ignored: the parity hunter was removed`); `crysk config set parity_trigger_paths` is refused. |
299
300
  | `materiality_gate` | both — team may only turn it **off** | Defaults to `false`. When `true`, an extra isolated judge checks each blocking finding against Crysk's posting policy; a finding judged not material under normal use is posted as advisory instead of blocking. Findings about security, credentials or data loss are never demoted. Adds one judge call per blocking finding. It runs only on its profile's judge models (Claude sonnet or opus on `claude`, OpenAI Terra on `openai`); on any other route findings stay blocking. Known limitation: on a re-review, a finding that was blocking on an earlier head still counts toward the gate. |
300
301
  | `post` | both — team may only turn it **off** | Whether review reports publish as GitHub PR comments by default. Defaults to `false`. |
301
302
  | `post_min_severity` | both — the repo file wins either way | The lowest finding a PR review posts: `suggestion` (everything), `warning` (hides advisory suggestions) or `blocking` (hides every advisory finding). A blocking finding always posts. Hidden findings get no comment; the summary counts them in one line. The gate and local reports still see every finding; re-review admission scores only what was posted, so a hidden finding never triggers a re-review. Unset posts everything; `setup --ci` writes the recommended `warning` when the file has no value. |
@@ -305,7 +306,7 @@ resolver checks the config value *before* the remote head. A global `default_bas
305
306
  preempt autodetection on every repo that stays quiet, so the first repo whose default branch differs
306
307
  would silently review the wrong commit range — with a plausible branch name on the plan card.
307
308
 
308
- **Flags always win, and may exceed a cap.** A flag is you typing an intent in front of the cost band,
309
+ **Flags always win, and may exceed a cap.** A flag is you typing an intent in front of the plan,
309
310
  which is a different thing from a committed file asking on your behalf. `--agents` overrides
310
311
  `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
311
312
  `default_base`; `--summary` / `--no-summary` and `--model` override the summary keys.
@@ -367,10 +368,10 @@ default branch.
367
368
  | `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. |
368
369
  | `crysk gc uninstall` | Unload and remove that GC agent. |
369
370
  | `crysk gc status` | Read-only, $0: whether the GC agent is installed, its interval, plist, and tick log. |
370
- | `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. |
371
+ | `crysk usage [--all]` | Read-only, $0: print the observability store's per-run rows (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. |
371
372
 
372
- Flags worth knowing: `--dry-run` (plan + cost band, creates nothing), `--yes`, `--model <m>`,
373
- `--scout` / `--no-scout` (toggle pre-hunt reconnaissance scout),
373
+ Flags worth knowing: `--dry-run` (the plan, creates nothing), `--yes`, `--model <m>`,
374
+ `--scout`, `--no-scout` and `--scout-model` (accepted and ignored, with a warning: the scout stage was removed),
374
375
  `--no-shared-prefix` (turn off the default shared hunter prefix: hunters share one cached system prompt
375
376
  holding the patch, their roles move to the user message and a one-turn warm-up writes the cache first; Anthropic routes only,
376
377
  since other providers already cache each hunter's own loop),
@@ -535,10 +536,15 @@ A script that merges on success should treat only `0` as a finished review.
535
536
 
536
537
  ## Cost and expectations
537
538
 
539
+ The figures in this section are **measured history**, kept as the evidence behind the size gate. The engine
540
+ no longer prints, stores or limits dollars: the Crysk platform prices a platform run from the usage the
541
+ engine reports and shows what a review cost (dashboard, per pull request and in insights).
542
+
538
543
  - **$2–5 per review** of a typical PR-sized diff — the floor is real, because hunters read the tree,
539
544
  not just the diff — and larger trees cost more (a 45-file tree measured $11–15). Wall time is
540
- minutes, not seconds: ~10 for a small diff, up to ~25 measured on a large tree. The printed band
541
- is an order-of-magnitude guide, not a quote — the same tree has billed 34% apart across runs.
545
+ minutes, not seconds: ~10 for a small diff, up to ~25 measured on a large tree. These are an
546
+ order-of-magnitude guide, not a quote — the same tree has billed 34% apart across runs.
547
+
542
548
  ### The size gate — a cost gate, not a quality gate
543
549
 
544
550
  Past a size threshold Crysk **skips the review** instead of running it. Small trees bill $1.9–$4.8;
@@ -552,7 +558,7 @@ miss came from a 7-file PR. If a large diff is worth its price, review it anyway
552
558
  Locally that is `--force`. In GitHub Actions it is a pull request comment, `/crysk review`,
553
559
  from a user with write access (a workflow scaffolded before the comment trigger uses
554
560
  `gh workflow run pr-hero-force.yml -f pr=<n>` instead). The comment does not review on your
555
- machine; the Actions runner does. It also clears the CI admission rules and the budget ceiling for
561
+ machine; the Actions runner does. It also clears the CI admission rules and the platform's dollar limits for
556
562
  that one run. `gh run rerun` on a skipped run does not: it measures the gates again and skips again.
557
563
 
558
564
  The gate counts **effective** changed lines (insertions + deletions) and files — excluded content is
@@ -617,7 +623,7 @@ only ever over-count, never under-count.
617
623
 
618
624
  ```bash
619
625
  crysk review --pr 42 --dry-run # prints the gate verdict, spends nothing
620
- crysk review --pr 42 --force # local: review it anyway (does NOT skip the cost prompt)
626
+ crysk review --pr 42 --force # local: review it anyway (does NOT skip the confirmation prompt)
621
627
  gh pr comment 42 --body "/crysk review" # CI: same forced re-review, on the Actions runner
622
628
  gh pr comment 42 --body "/crysk override" # CI: unlock a red gate on this head, no review, $0
623
629
  gh pr comment 42 --body "/crysk stop" # CI: skip automatic reviews on later pushes, until /crysk review
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: crysk
3
+ description: "Trigger: use or configure Crysk locally — change the review model or backend per role (models, fallback models, OpenCode, DeepSeek, custom model), effort, credentials order, config.json keys, REVIEW.md / gotchas.md, .cryskignore, size gate, run a review, `crysk watch/gc`, `crysk doctor/config`. Not CI (crysk-ci-setup) and not answering findings (crysk-loop)."
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: juanmaagd
7
+ version: "1.0"
8
+ ---
9
+
10
+ ## Activation Contract
11
+
12
+ Load when the user wants to **operate or configure Crysk on their machine or repo**:
13
+ - Change which model or backend a step runs on (per role, with fallbacks: OpenCode, DeepSeek, a pinned Claude version).
14
+ - Tune effort, caps, the size gate, `.cryskignore`, `REVIEW.md` / `gotchas.md`, or any `config.json` key.
15
+ - Run a review (local branch or `--pr <n>`), understand its cost, or read its artifacts.
16
+ - Set up the watcher (`crysk watch`) or worktree GC (`crysk gc`).
17
+ - Diagnose a broken install or a refused run (`crysk doctor`, `crysk config`).
18
+
19
+ Route away: GitHub Actions, `CRYSK_*` secrets, `CRYSK_MODELS`, `/crysk review` comments → load `crysk-ci-setup`. Replying to posted `<!-- crysk-finding` comments → load `crysk-loop`.
20
+
21
+ ## Source of Truth
22
+
23
+ This skill holds the mental model and the traps, not the reference. Before acting, read the live state, and for detail follow the linked section — do not answer from memory:
24
+ - `crysk config` — every key, its effective value, and **which layer decided it**. Read-only, $0.
25
+ - `crysk --help` — the installed version's real commands and flags.
26
+ - The docs on GitHub (they are not shipped in the npm package): [README](https://github.com/cryskai/crysk/blob/main/README.md), [configuration.md](https://github.com/cryskai/crysk/blob/main/docs/configuration.md).
27
+
28
+ If Crysk is not on `PATH`, run every command as `npx -y crysk <command>` (Node is enough). An install from before the rename (the package used to be `pr-hero`) still answers to `pr-hero`; either command is the same program.
29
+
30
+ ## Mental Model
31
+
32
+ - **Two config files, owned by different people.** `~/.crysk/config.json` is the person's (never committed; `~/.prhero/config.json` on an install from before the rename — never create `~/.crysk` by hand while `~/.prhero` is in use, the CLI would switch homes); `<repo>/.crysk/config.json` is the team's (committed). `~/.crysk/watch.json` holds the watcher.
33
+ - **The one rule:** the repo file beats the global one, **except on capped keys** (`max_*`, and the on/off switches `summary.enabled`, `materiality_gate`, `post`): there the team can only ask for *less*, so a committed file never enlarges a person's bill.
34
+ - **Some keys live in exactly one layer** and the parser refuses the other by name: `models` and `credentials` are person-only; `default_base`, `parity_trigger_paths`, `suspicion_priors` are repo-only. `--config <file>` replaces the repo layer only.
35
+ - **Flags always win**, and may exceed a cap (`--base`, `--agents`, `--model`, `--summary`/`--no-summary`, `--force`).
36
+ - **Models are assigned per role.** `models` maps a role (`default`, `hunter.<key>` per hunter, `refuter`, which also covers the re-review verifier and the CI adjudicator, `consolidate`, `summary`, `judge`) to a list of one to three models tried in order; a role not listed uses `default`. With no `models`, each step runs its prompt's model: hunters and consolidation `claude:sonnet-latest`, the refuter `claude:opus-latest`, the summarizer `claude:haiku-latest`. A model name carries its backend: `claude:<sonnet|opus|haiku|fable>-latest` (newest version), `claude:claude-…` (pinned), `opencode:<provider>/<model>`. The old `routing` key is gone and refused with the `models` form to write; `summary.model` is gone too (`"haiku"`, which `crysk init` used to write, still reads with a warning). The scout stage was removed: `--scout`, `--no-scout`, `--scout-model`, the `scout` key and `models.scout` are still accepted and ignored, each with a warning, and `crysk config set scout` is refused.
37
+ - **Crysk never stores a credential.** It reads the Claude CLI's login, `CRYSK_CLAUDE_*` (or `ANTHROPIC_API_KEY` / `CLAUDE_CODE_OAUTH_TOKEN`) variables, or OpenCode's `auth.json`, and projects an ephemeral copy into each step. A run uses one Claude credential, the first set in `credentials.claude` (default `["subscription", "api_key"]`).
38
+
39
+ ## Hard Rules
40
+
41
+ - **Never print, `cat`, commit, or log credentials** — Keychain records, API keys, or `auth.json` contents. Inspect `auth.json` provider **keys and `type` only**.
42
+ - **Read before writing, verify after:** run `crysk config` before a change and again after it; finish with `crysk doctor`, and `crysk review --dry-run` when the change touches models or credentials.
43
+ - **Prefer the CLI to hand edits:** scalar keys go through `crysk config set|unset <key> <val> [--person|--team|--watch]` (or `crysk config --edit`). `models` and `credentials` are objects, so they are written by hand into `~/.crysk/config.json` — keep the file valid JSON and preserve every other key.
44
+ - **Never spend without consent:** a real `crysk review`, `crysk watch install` (starts automatic spending) or `--force` past the size gate runs only after the user confirms. `--dry-run` variants are free.
45
+ - **Never invent a model id.** The bundled catalog only knows the Claude aliases; an OpenCode model must be spelled exactly as `opencode models <provider>` lists it, and a typo fails at the provider, not at Crysk.
46
+ - **You cannot authenticate `claude` for the user.** If `doctor` reports it missing or unauthenticated, say so and stop.
47
+
48
+ ## Recipes
49
+
50
+ **Models per role** — [Models](https://github.com/cryskai/crysk/blob/main/docs/configuration.md#models), [Fallback models](https://github.com/cryskai/crysk/blob/main/docs/configuration.md#fallback-models)
51
+ 1. Ask: which roles to move (`default` for all, or `hunter.<key>`, `refuter`, `summary`, …), which model for each and which fallbacks, and whether metered spend is acceptable.
52
+ 2. Write `models` in `~/.crysk/config.json` (or `~/.prhero/config.json` if that is the home in use), e.g. `{"models": {"default": ["opencode:deepseek/deepseek-v4-flash", "claude:sonnet-latest"], "refuter": ["claude:opus-latest"]}}`. Write `claude:sonnet-latest`, never a bare `claude:sonnet` (refused); a full `claude-*` id pins a version.
53
+ 3. Traps: at most 3 models per role and none twice; a role not listed uses `default`, except the materiality judge, which runs only `claude:sonnet-latest` or `claude:opus-latest` and never inherits `default`; the next model is tried only on a provider failure (rate limit, quota, network, timeout, model unavailable; a refused login skips the models on the same credential), never on a bad answer; each fallback can bill and take the step's full time again. Several OpenCode providers may be mixed in one review. A local `auth.json` `openai` record must be `type: "oauth"` (the subscription); an `openai` API key there is refused.
54
+ 4. Verify: `crysk config`, `crysk doctor`, then a **local** `crysk review --dry-run` (PR-mode dry-run returns before route admission, so it can look clean on a plan that will be refused).
55
+
56
+ **Effort** — [Effort](https://github.com/cryskai/crysk/blob/main/docs/configuration.md#effort): per model, as a `models` entry `{"model": "claude:opus-latest", "effort": "max"}`; otherwise the `effort:` frontmatter of a prompt in a custom `agents_dir`, then the role default (hunters `xhigh`, refuter `high`). Claude levels are `low|medium|high|xhigh|max` (`ultracode` is refused). On OpenCode the effort is the model's variant, as OpenCode names it; the review refuses, before spending, a variant `opencode models <provider> --verbose` does not list. The `#variant` suffix is gone. `models.judge` and `--model` take no effort.
57
+
58
+ **Credentials / billing** — [Credentials](https://github.com/cryskai/crysk/blob/main/docs/configuration.md#credentials): one Claude credential per run, the first set in `credentials.claude` (default `["subscription", "api_key"]`; on macOS a Claude login always counts as the subscription). To bill an API key with a login present, write `{"credentials": {"claude": ["api_key", "subscription"]}}`. The Claude child sees only the chosen one. For OpenCode on this machine, only an `openai` entry of `type: "oauth"` is a subscription; every other provider is a metered API token unless its catalog prices the model at $0.
59
+
60
+ **Caps, size gate, exclusions** — [config.json keys](https://github.com/cryskai/crysk/blob/main/README.md#configjson-keys), [size gate](https://github.com/cryskai/crysk/blob/main/README.md#the-size-gate--a-cost-gate-not-a-quality-gate), [.cryskignore](https://github.com/cryskai/crysk/blob/main/README.md#cryskignore--repo-defined-exclusions): `max_changed_lines`/`max_changed_files` skip oversized diffs (a cost gate, not a quality one); `max_concurrent_steps` keeps the fan-out under a provider's rate limit; `max_verification_steps` (default `8`, `0` pauses) caps how many prior open findings a re-review spawns verifier steps for. `post_min_severity` (`suggestion` | `warning` | `blocking`, unset posts everything; `setup --ci` writes `warning`) is the lowest finding a PR review posts: hidden findings get no comment and the summary counts them, the gate is unchanged (a blocking finding always posts), and re-review admission scores only what was posted. Only the repo-root `.cryskignore` is read, and matching is case-sensitive.
61
+
62
+ **REVIEW.md / gotchas.md** — [REVIEW.md and gotchas.md](https://github.com/cryskai/crysk/blob/main/README.md#reviewmd-and-gotchasmd): optional; a root `REVIEW.md` wins over `.crysk/gotchas.md`. A file that exists must be real: read the code and write the actual traps, then delete the `human-attention-required` marker line, or `review` and `doctor` refuse it. With neither file the review runs on the default guidance.
63
+
64
+ **Running a review** — [Commands](https://github.com/cryskai/crysk/blob/main/README.md#commands): `.crysk/` must be committed or gitignored (clean-tree gate). Expect roughly $2–5 and ~10 minutes per typical PR; the printed band ignores billing mode. Artifacts land in `~/.crysk/repos/<origin>/runs/<run>/`. To check or wait on a PR's CI review state deterministically ($0, via `gh`), run `pr-hero status --pr <n> [--wait] [--json]`.
65
+
66
+ **Watcher / GC** — [crysk watch](https://github.com/cryskai/crysk/blob/main/README.md#watching-prs-automatically--crysk-watch): `watch add [--post]`, preview with `watch --once --dry-run`, and only then `watch install`. `daily_cap` and `window` live in `~/.crysk/watch.json`. GC is separate: `crysk gc install`.
67
+
68
+ ## Output Contract
69
+
70
+ Report back to the user:
71
+ 1. What changed: the file and layer, and the keys touched (never credential values).
72
+ 2. The `crysk config` lines proving the new effective value and its layer.
73
+ 3. `doctor` / `--dry-run` result, and whether the next real run is subscription, metered, or free.
74
+ 4. Anything left for the human: authenticating `claude`, committing `.crysk/`, confirming spend.
@@ -0,0 +1,143 @@
1
+ ---
2
+ name: crysk-ci-setup
3
+ description: "Trigger: setup CI, add Crysk to CI, GitHub Actions review, CRYSK_* secrets, crysk-secrets, CRYSK_MODELS, models per role in CI, OpenCode, DeepSeek, CRYSK-INPUT-REMOVED, old OPENCODE_AUTH_JSON / CRYSK_ROUTING workflows, admission policy, configure CI workflow, retrigger, force review, skipped review, /crysk review, /crysk override, pr-hero-force, too many findings, noisy review, post_min_severity, materiality_gate. Scaffolds the one workflow, secrets, models variables, admission config, and the posting and noise settings."
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: juanmaagd
7
+ version: "4.0"
8
+ ---
9
+
10
+ ## Activation Contract
11
+
12
+ Load when the user asks to:
13
+ - Add Crysk to GitHub Actions CI, scaffold `.github/workflows/crysk.yml`, or configure secrets. No local install is needed: the workflow file is the whole install.
14
+ - Configure the models per role in CI, or **OpenCode** (`CRYSK_MODELS`, `CRYSK_OPENCODE_*` secrets, DeepSeek, mixed Claude+OpenCode, fallbacks).
15
+ - Move a workflow off the removed inputs (`CRYSK-INPUT-REMOVED`: `claude-token`, `anthropic-api-key`, `opencode-auth` with the `OPENCODE_AUTH_JSON` secret, `routing` with the `CRYSK_ROUTING` variable).
16
+ - Tune CI spend / re-review / admission policy.
17
+ - Retrigger a skipped CI review (size, admission, or budget) without running the review locally.
18
+ - Reduce review noise: fewer comments (`post_min_severity`) or fewer blocking findings that are real but improbable (`materiality_gate`).
19
+
20
+ ## Hard Rules
21
+
22
+ - **Zero secret leakage:** NEVER print, `cat`, commit, or log API keys, tokens, or an OpenCode `auth.json` record. Reference `${{ secrets.* }}` names only. Inspect `auth.json` **keys and `type` only**.
23
+ - **One `CRYSK_*` secret per credential, nothing else:** `CRYSK_CLAUDE_OAUTH_TOKEN` (subscription), `CRYSK_CLAUDE_API_KEY`, `CRYSK_OPENCODE_<P>_API_KEY` per OpenCode provider, `CRYSK_OPENCODE_OPENAI_OAUTH` for an OpenAI subscription. The workflow names each one in its `crysk-secrets` block, never `toJSON(secrets)`. The old `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY` and `OPENCODE_AUTH_JSON` secrets and the `CRYSK_ROUTING` variable are read by nothing. Models per role go in the public variable `CRYSK_MODELS` (no credentials in it), the Claude order in `CRYSK_CREDENTIALS`, the OpenCode providers in `CRYSK_OPENCODE_PROVIDERS`.
24
+ - **No install needed:** run every Crysk command as `npx -y crysk <command>` (Node is enough; the package brings its own Bun). A global `crysk` on PATH is the same command. CI itself needs no local CLI at all: the workflow runs the action. `npx -y crysk skills install` installs the Crysk, triage, and CI-setup skills into every detected coding agent, with no TTY and no MCP or launchd registration (neither is needed for the CI loop, and npx's temporary cache refuses them).
25
+ - **Deterministic scaffolding:** Run `npx -y crysk setup --ci` (or `npx -y crysk ci init`) with the interview's flags. It writes the one workflow file, `.github/workflows/crysk.yml` (a repo that already has `pr-hero.yml` keeps it: `--force` rewrites it in place, and setup refuses to add a second file beside it). Do not fabricate it from memory. Fallback: copy `assets/workflow.yml`. Never scaffold a `pr-hero-force.yml`; it is retired.
26
+ - **`fetch-depth: 0` is mandatory** on `actions/checkout@v4`.
27
+ - **Gate mode:** the `crysk` commit status is the required check (the legacy `pr-hero` status is no longer posted). The scaffold writes `mode: gate` explicitly: blocking findings, a size or spend-ceiling skip, and a crash set it red. Every review rule that skips a push (low-risk delta, once per PR, `/crysk stop`, the attempt budget used up, `manual_only`) carries the last verdict; answered blocking findings turn a carried red green, marked unverified. Under the attempt budget used up or `manual_only`, that green is held `pending` instead, so a push past the budget or under `manual_only` never turns green without a `/crysk review` or a `/crysk override`. `mode: advisory` keeps it green for a finished review. The job's exit code stays `0` on findings either way, so do not gate on the job.
28
+ - **Required permissions:** `contents: read`, `pull-requests: write`, `issues: write`, `statuses: write`, **`checks: write`**, **`actions: read`** (the admission gate lists past runs; a private repo 403s without it). Template in `assets/workflow.yml` includes all six.
29
+ - **Retrigger is a PR comment: `gh pr comment <n> --body "/crysk review"`.** GitHub Actions runs the review on the runner with `--force`. The comment must be exactly `/crysk review` (or `/crysk review --full`; `/pr-hero review` on a workflow scaffolded before the rename, see the `/crysk` vs `/pr-hero` bullet), and its author needs write access; the action refuses anyone else. Do not run `crysk review --force` locally when the review should happen in CI. `gh run rerun` on a skipped run re-evaluates the gates and does not force. In this repo a comment run checks out the PR head commit before `uses: ./`, so it runs the PR's own engine, not the default branch's.
30
+ - **`/crysk recheck` re-reviews the head and asks the CI adjudicator to rule on pending dismissals.** It is `/crysk review` plus `--adjudicate`, with the same permission check and reaction; refused on fork pull requests. See `docs/github-actions.md` ("Rechecking a dismissal").
31
+ - **`/crysk stop` stops automatic reviews on the PR.** Post it before a push that should not be reviewed: CI admission skips every later automatic review, carrying the last verdict, until a `/crysk review` or `/crysk recheck` comment. It counts only from a user with write access (checked at admission), starts no run, and never turns the gate green. See `docs/github-actions.md` ("Stopping automatic reviews").
32
+ - **`--force` never widens discovery; `--full` does.** When a prior review of the same head was hollow or wrong and re-runs report "No changes to discover", comment `/crysk review --full`. It passes `--full`, which re-discovers the whole PR range.
33
+ - **When the comment trigger takes effect:** GitHub reads a comment-triggered workflow from the **default branch** (for this repo, `main`, not `dev`), so `/crysk review` works only once the workflow file (`crysk.yml`, or `pr-hero.yml` in a repo set up before the rename) with its `issue_comment` trigger is merged there; a user repo also needs an action release that handles the comment, through the `@v0` it pins.
34
+ - **`/crysk` vs `/pr-hero`:** the commands are `/crysk review`, `/crysk recheck`, `/crysk override` and `/crysk stop`; the action still accepts `/pr-hero …` for one version. A `pr-hero.yml` scaffolded before the rename filters only `/pr-hero …`, so a `/crysk …` comment starts nothing there: re-run `npx -y crysk ci init --force` to accept both, which also moves the workflow to the `CRYSK_*` secrets.
35
+ - **Legacy scaffolds:** a `pr-hero.yml` scaffolded before the comment trigger has no `issue_comment` listener, so a comment does nothing. There, use `gh workflow run pr-hero-force.yml -f pr=<n>` (add `-f full=true` to re-discover), or re-scaffold with `npx -y crysk ci init --force`, which leaves `pr-hero-force.yml` in place.
36
+ - **Minimum action version:** this workflow listens to comments, and only an action release that ships the comment handling checks the command and the commenter's write access. An older action reviews on ANY comment starting with `/crysk review`, from anyone who can comment. Never pair this workflow with an older action; a pinned tag or sha must be at or after that release.
37
+ - **Older heads (this repo):** a comment run loads the PR head's own `action.yml`, so on a head from before the comment handling it reviews without reading the comment (no force, no `--full`); merge or rebase the PR onto a base that has it first.
38
+ - **Trust (this repo):** a comment run runs the PR head's code, including its `bun install`, with the workflow's secrets, so write access is checked twice: by the workflow's pre-checkout step (fail closed, before any head code runs) and again by the head's `action.yml`.
39
+ - **Admission config is repo-level:** Write `.crysk/config.json` on the default branch. That file **rejects** `models` and `credentials`: they are person-layer only (`$HOME/.crysk/config.json` on the runner, written from `vars.CRYSK_MODELS` and `vars.CRYSK_CREDENTIALS`).
40
+ - **`.cryskignore` is read from the base ref, not the PR branch, in CI.**
41
+ - **Models and OpenCode are DATA:** the scaffold passes `models: ${{ vars.CRYSK_MODELS }}`, `credentials: ${{ vars.CRYSK_CREDENTIALS }}` and five OpenCode slot lines driven by `vars.CRYSK_OPENCODE_PROVIDERS`. Unset `CRYSK_MODELS` = Claude CI. Never a per-provider Action input. A repository connected to the Crysk platform takes its models from the platform, which wins over the inputs.
42
+ - **OpenCode procedure:** when OpenCode or mixed backends are in scope, follow `references/opencode-ci.md` before setting GitHub DATA (roles, model names, one secret per provider, the providers variable).
43
+
44
+ ## Decision Gates
45
+
46
+ | Condition | Action |
47
+ |---|---|
48
+ | `gh auth status` succeeds | Offer `gh secret set` / `gh variable set` |
49
+ | `gh` missing/unauthenticated | Link to repo Settings → Secrets and variables → Actions (Variables tab for `CRYSK_MODELS`, `CRYSK_CREDENTIALS`, `CRYSK_OPENCODE_PROVIDERS`) |
50
+ | Credential: Claude | **`CRYSK_CLAUDE_OAUTH_TOKEN`** — subscription (`claude setup-token` only, NOT keychain). **`CRYSK_CLAUDE_API_KEY`** — pay-as-you-go. Both set: the subscription runs unless `CRYSK_CREDENTIALS` is `{"claude": ["api_key", "subscription"]}`. |
51
+ | Credential: OpenCode | Read `references/opencode-ci.md`. One `CRYSK_OPENCODE_<P>_API_KEY` per provider + `CRYSK_MODELS` + `CRYSK_OPENCODE_PROVIDERS`. Any `CRYSK_*` credential counts; with none, the run fails red with the `gh secret set` commands. |
52
+ | openai in CI | `CRYSK_OPENCODE_OPENAI_API_KEY` runs metered; `CRYSK_OPENCODE_OPENAI_OAUTH` (base64 of the `openai` record of OpenCode's `auth.json`) is the ChatGPT subscription and wins when both are set. `_OAUTH` works for openai only. |
53
+ | Workflow red with `CRYSK-INPUT-REMOVED` | It still passes `claude-token`, `anthropic-api-key`, `opencode-auth` or `routing`. `npx -y crysk ci init --force`, then set the `CRYSK_*` secrets and variables it prints. |
54
+ | Different models per step | `CRYSK_MODELS` maps roles to lists: `default`, `hunter.<key>`, `refuter`, `consolidate`, `summary`, `judge`. Any role left on a `claude:` model needs a Claude secret; OpenCode-only = every role on OpenCode, e.g. `{"default": ["opencode:deepseek/deepseek-v4-flash"]}` (`references/opencode-ci.md`). |
55
+ | Several OpenCode providers in one run | Supported: up to 5 providers through the workflow's slots, each model on its own provider's secret, as primary or fallback. |
56
+ | OpenCode CLI pin | Action installs **1.18.30** iff the setup step wrote an OpenCode auth file OR the models in effect name `opencode:`. Never `latest`. |
57
+ | Fork PRs | Their pushes skip (no secrets). A user with write access comments `/crysk review`, and that run (base context, with secrets) reviews the fork head. Review `if` never reads `secrets`; the action checks for a `CRYSK_*` credential in `crysk-secrets` (or a login file already on the runner). |
58
+ | Spend gates | Defaults: `budget-usd: 12.00` on metered routes (the run chose `CRYSK_CLAUDE_API_KEY`, **or** an OpenCode auth file was built), `max-changed-lines: 4000` and `max-changed-files: 50` on metered routes only; a Claude subscription route has no size limit unless the workflow or `.crysk/config.json` sets one. A subscription run stays unlimited unless an OpenCode auth file is also present. |
59
+ | Existing workflow | `setup --ci` skips; ask before `--force` |
60
+ | First-time admission | Recommend `ci_admission_observe_only: true` — `references/ci-admission.md` |
61
+ | User wants max CI spend | Lower `ci_max_attempts` and/or raise `ci_rereview_min_score` |
62
+ | Custom bot posts findings | Add login to `ci_trusted_actors` |
63
+ | Too many advisory comments on PRs | Raise the posting floor: `post_min_severity: "blocking"` in `.crysk/config.json` posts only blocking findings (`"warning"`, the recommended floor setup writes, hides advisory suggestions only). Blocking findings always post; the gate is unchanged. |
64
+ | Blocking findings that are real but improbable keep PRs red ("an edge case that never happens") | Offer `materiality_gate: true` in `.crysk/config.json` (opt-in, off by default). An isolated judge checks each blocking finding against Crysk's posting policy; one judged not material under normal use posts as advisory and does not block. Security, credential and data-loss findings are never demoted, and any judge failure keeps the finding blocking. Cost: one sonnet call per blocking finding (about 1 per PR, roughly +$0.015 notional and +10 s per review). Pair it with `post_min_severity: "blocking"` to hide the demoted ones entirely. |
65
+ | `materiality_gate` is on but nothing is ever demoted | Read the `materiality` record in the run's `pipeline.json` (in the `crysk-run-*` artifact). `unsupported_route`: the judge runs only on `claude:sonnet-latest` or `claude:opus-latest`, so a `models.judge` in `CRYSK_MODELS` that lists neither stands it down; remove that role or list one of the two. `ceiling`: the pipeline ceiling left no room for one judge wave (about 9 minutes). `ran` with `judged: 0`: the run had no blocking finding the safety guard leaves unprotected, so there was nothing to judge. `skipped` on a re-review with no new commits to review is expected (the judge is left out when nothing new is hunted). `skipped` anywhere else means the key did not reach the run: the repo config must be on the PR's base branch (CI reads it from there) and a global config must not set it `false` (the key is capped). |
66
+ | CI skipped (size, admission, or budget) | `gh pr comment <n> --body "/crysk review"`. The review runs on GitHub Actions. Do not run `crysk review --force` locally for this. Legacy scaffold (no `issue_comment` trigger): `gh workflow run pr-hero-force.yml -f pr=<n>`. |
67
+ | Gate is red with blocking findings the team accepts | `gh pr comment <n> --body "/crysk override"` (write access, same-repo PRs only, valid for that head only; a same-head `/crysk review` keeps it red). |
68
+ | Prior review of the same head was hollow or wrong; re-runs say "No changes to discover" | `gh pr comment <n> --body "/crysk review --full"`. A plain `/crysk review` keeps the narrowed discovery. |
69
+ | Gate red: `crysk: review partial (N of M hunters failed, set abc123) — /pr-hero review retries it` | Some hunters failed and nothing blocking was found. `gh pr comment <n> --body "/crysk review"`. If the same hunters fail every run, fix their route (model, credential) or override. |
70
+ | Gate red: `crysk: review partial again (N of M hunters failed, set abc123) — fix the failing route or /pr-hero override` | The previous review of this head was partial with the same hunters failing, so a retry already failed the same way. Fix the failing hunter's route (model, credential), or `gh pr comment <n> --body "/crysk override"`. `crysk status` answers `override-or-fix`. |
71
+ | Gate error: `CRYSK-CANCELLED: not reviewed — /pr-hero review reviews this head` | The review run was cancelled (a newer push, or by hand). Comment `/crysk review` to review the head. |
72
+ | `CRYSK-MODEL-UNAVAILABLE` (lead "Provider <name>:") | Every hunter's route names a model the provider does not serve. Fix the model id in `CRYSK_MODELS` (check `opencode models <provider>`). |
73
+ | `CRYSK-CRED-UNUSABLE` ("The route <provider>/<model> has no usable credential record") | No `CRYSK_OPENCODE_<P>_API_KEY` reached the run for that provider: set it, add its token to `CRYSK_OPENCODE_PROVIDERS`, or move that model elsewhere in `CRYSK_MODELS`. |
74
+ | `CRYSK-CONFIG-INVALID` naming the `models` or `credentials` input | `CRYSK_MODELS` or `CRYSK_CREDENTIALS` is not valid JSON or breaks a rule (the step's log names the entry). Check the same object locally under `models` / `credentials` in `~/.crysk/config.json` with `npx -y crysk config`, then set the variable again. |
75
+ | Blocking findings answered `dismissed`, gate still red | `gh pr comment <n> --body "/crysk recheck"`: the CI adjudicator rules on each dismissal (at most 5 per run). On `upheld`, comment `/crysk review`: that next review stops counting it. `deferred` / `misclassified` never clear the gate. |
76
+ | Gate error: `CRYSK-GOTCHAS-MISSING` ("the review instructions file (REVIEW.md or .crysk/gotchas.md) is empty or still the scaffold") | Write real facts into that file and delete the `human-attention-required` marker line (or delete the file to review with the default guidance), commit it to the default branch, then comment `/crysk review`. |
77
+ | Gate error: `CRYSK-HUNTERS-FAILED` (every hunter failed) | Check the route and credential first (the `CRYSK-CRED-UNUSABLE` and `CRYSK-MODEL-UNAVAILABLE` rows). Free OpenCode models fail intermittently: comment `/crysk review` to retry. |
78
+ | A `/crysk review` comment did nothing | The workflow is not on the default branch yet, the comment is not exact, the author lacks write access, or the workflow predates the comment trigger (re-scaffold with `--force`). |
79
+
80
+ ## Review Settings Interview (ask the human, never choose for them)
81
+
82
+ Before step 4, ask the human these questions in their language. Use the native question UI when available (one grouped interaction is fine). Do not pick an answer for them, and do not skip a question because a default exists: the point is that they know these settings exist.
83
+
84
+ 1. **Re-review level** (how Crysk reviews new pushes on an open PR):
85
+ - **Minimal**: one automatic review per PR; later pushes only on a `/crysk review` comment.
86
+ - **Balanced (recommended)**: re-review when the push touches risky files or the previous pass found enough (score >= 4); at most 2 automatic passes.
87
+ - **Thorough**: review every push, up to 4 automatic passes. Most coverage, most cost.
88
+ - **Manual**: nothing automatic after the first review; every re-review starts with `/crysk review`.
89
+ 2. **Gate or advisory**: gate turns the `crysk` check red on blocking findings (require it in branch protection to block merges); advisory keeps it green.
90
+ 3. **How CI pays**:
91
+ - **Claude subscription** (`CRYSK_CLAUDE_OAUTH_TOKEN`): do not ask for a budget. Tell them no `budget-usd` is written: a subscription review spends quota, not dollars, and CI applies no ceiling while the run uses the subscription and no `CRYSK_OPENCODE_*` secret builds an OpenCode auth file (an OpenCode model brings back the $12 ceiling, so a subscription mixed with OpenCode is the API-key answer). An API key kept beside it is not used unless `CRYSK_CREDENTIALS` puts `api_key` first.
92
+ - **API key** (`CRYSK_CLAUDE_API_KEY` or an OpenCode provider): ask for the spend ceiling per review in USD (default 12, `0` = none).
93
+ 4. **Changed-lines threshold**: a PR with more changed lines is skipped, not reviewed. Ask on any billing (default 4000, `0` = no limit, only if they say so): unlike the budget it matters on a subscription too, where an unset threshold means no limit at all.
94
+ 5. **Advanced settings**: name them, then ask whether to review them now. Each keeps a working default if skipped:
95
+ - score weights: blocking 2, advisory 1 (integers >= 1; `ci_blocking_weight`, `ci_advisory_weight`), and the score floor 4 (`ci_rereview_min_score`); used only by the risk-aware and thresholded policies;
96
+ - observe only (`ci_admission_observe_only`): log what the rules would skip, but review every push; good for one PR cycle;
97
+ - trusted actors (`ci_trusted_actors`): extra GitHub logins whose Crysk markers count;
98
+ - changed-files limit (`max_changed_files`): a PR touching more files is skipped; unset = none on a subscription, 50 on an API key;
99
+ - exclusions: patterns in `.cryskignore` (gitignore syntax) the review never reads;
100
+ - posting floor (`post_min_severity`): `suggestion` posts everything, `warning` (recommended, and what setup writes when the key is absent) hides advisory suggestions, `blocking` posts only blocking findings. Hidden findings are counted in the summary comment, and the gate is unchanged;
101
+ - materiality gate (`materiality_gate`, off unless they say yes): blocking findings that are real but not material under normal use are posted as advisory instead of blocking, judged by an isolated sonnet call per blocking finding against Crysk's posting policy; security, credential and data-loss findings are never demoted. Tell them the cost (about one call per PR, +$0.015 notional, +10 s), that it runs on Claude only (`claude:sonnet-latest`, or `claude:opus-latest` through `models.judge`), so it needs a Claude secret, and the known limit: on a re-review, a finding that already blocked on an earlier push still counts toward the gate.
102
+
103
+ **On a re-run** (`.crysk/config.json` already has re-review keys, or the workflow already exists), first show the human the current values (`npx -y crysk config`) and offer **Keep current settings** for the level and for the line threshold. When they keep them, omit `--level` / `--max-changed-lines`: passing a flag overwrites that group, including a tuned `max_verification_steps`.
104
+
105
+ Then pass the answers to the scaffold as flags, never as hand-written YAML:
106
+
107
+ ```bash
108
+ npx -y crysk setup --ci --level <minimal|balanced|thorough|manual> --ci-mode <gate|advisory> --billing <subscription|api> --max-changed-lines <n> [--budget-usd <n>]
109
+ ```
110
+
111
+ It writes the workflow, merges the level's keys into `.crysk/config.json` (keeping other keys), and prints a summary of every setting. **Never run it without these flags**: with none it applies balanced and gate, and its summary says nobody chose them. Write any advanced answers into `.crysk/config.json` (and `.cryskignore`) afterwards. The summary `setup --ci` printed predates those edits, so when there were any, show the human the effective settings from `npx -y crysk config` instead. Otherwise show the printed summary, including any `Changed` and `Kept existing` lines: on a re-run (for example `--force` to refresh an old workflow) only the groups a flag names are overwritten, and keys nobody chose stay as the file had them; the workflow keeps its old `mode` and `budget-usd` unless `--ci-mode` or `--billing` / `--budget-usd` is passed. In a terminal, every question defaults to the repository's current value. Details: `references/ci-admission.md`.
112
+
113
+ ## Execution Steps
114
+
115
+ 1. **Inspect repo:** `git rev-parse --is-inside-work-tree`, `git remote get-url origin`, `gh auth status`.
116
+ 2. **Credential path:** Claude-only → skip OpenCode. OpenCode or mix → **read `references/opencode-ci.md`** and execute it (models per role, one secret per provider, the providers variable).
117
+ 3. **Claude secret (if used):** `gh secret set CRYSK_CLAUDE_OAUTH_TOKEN` or `CRYSK_CLAUDE_API_KEY` (secure input, never print).
118
+ 4. **Workflow:** run the interview above, then `npx -y crysk setup --ci` with its flags. It writes `.github/workflows/crysk.yml` (or rewrites an existing `pr-hero.yml` in place) and the level keys in `.crysk/config.json`, and its next steps print the `gh secret set` / `gh variable set` commands for the person's `~/.crysk/config.json` (models, credentials, OpenCode providers); run the ones the human agrees to. Confirm `checks: write` and `actions: read`, both `pull_request` and `issue_comment` triggers, the `crysk-secrets: |` block and the `models` / `credentials` lines. `--force` if an old template lacks them (an old `credentials` job, a missing `issue_comment` trigger, or `claude-token` / `routing` lines mean it predates the current workflow).
119
+ 5. **Review instructions (optional, recommended before the first review):** if the default branch has neither a root `REVIEW.md` nor `.crysk/gotchas.md`, run `npx -y crysk init` in the clone; it scaffolds `REVIEW.md` (an existing `.crysk/gotchas.md` is kept, and no `REVIEW.md` is written beside it). The agent writes the facts from the repository it has in context, not from the template: the deliberate oddity that looks like a bug, the invariant enforced outside the diff, the ownership rule a newcomer would break. The hunters and the refuter read the file as facts; the "Not blocking here" section is applied only by the materiality judge (`materiality_gate: true`, blocking findings only, and only to style, naming, test-hygiene, generated-code and dev-script findings), so fill it only when the human asked for that gate, and delete it otherwise. Delete the `human-attention-required` marker line (Crysk refuses to review while it is there), then commit the file to the default branch. With no file the review runs on the default guidance; an empty or scaffold file fails the run `CRYSK-GOTCHAS-MISSING`.
120
+ 6. **Require the check:** in branch protection, require the `crysk` status check (the gate), not the `review` job. The legacy `pr-hero` status is no longer posted, so a repository that still requires it is blocked until the rule moves to `crysk`. A private repository on GitHub Free cannot require status checks (HTTP 403): report that the gate is advisory there. With `gh`, and only after asking the human: read the current protection first (`gh api repos/<o>/<r>/branches/<default>/protection`), because the PUT replaces all of it; then `gh api -X PUT repos/<o>/<r>/branches/<default>/protection` with `required_status_checks` contexts `["crysk"]`.
121
+ 7. **Advanced settings:** write the answers from interview question 5 into `.crysk/config.json` (and `.cryskignore`), including `post_min_severity` when they chose a floor other than `warning` and `materiality_gate: true` only when they said yes; commit both to the default branch, and to any other branch PRs target (CI reads the config from the PR's base branch, so it applies from the next PR after the merge). **No `models` or `credentials` key there** (the repo parser refuses them). `npx -y crysk config` to verify.
122
+ 8. **Verify:** `npx -y crysk doctor`. `git status`. Confirm no echoed secret, and when OpenCode is on, that every `opencode:` model id in `CRYSK_MODELS` is one `opencode models <provider>` lists and each provider's token is in `CRYSK_OPENCODE_PROVIDERS`.
123
+ 9. **Deploy:** Offer commit. Open a **same-repo** test PR (forks skip).
124
+
125
+ ## Output Contract
126
+
127
+ Report:
128
+ - Secret status (set or manual link). Names only: which `CRYSK_*` secrets exist (`gh secret list`). Never values.
129
+ - Models (if set): the `CRYSK_MODELS` and `CRYSK_CREDENTIALS` JSON (no credentials in them), and for OpenCode the `CRYSK_OPENCODE_PROVIDERS` tokens and that each model id matches `opencode models <provider>`.
130
+ - Workflow path (`crysk.yml`, or the pre-rename `pr-hero.yml`; both present means two reviews per PR, delete one) and whether `checks: write`, `actions: read`, the `issue_comment` trigger, the `crysk-secrets` block and the `models` / `credentials` lines are present, with no removed input left.
131
+ - The review settings summary `setup --ci` printed (level, gate, budget, advanced settings), and which ones the human chose, including the posting floor (`post_min_severity`) and whether `materiality_gate` is on. Confirm repo `.crysk/config.json` has no `models` or `credentials` key.
132
+ - `npx -y crysk doctor` / `npx -y crysk config` outcome.
133
+ - Whether the default branch has a real `REVIEW.md` or `.crysk/gotchas.md` (no `human-attention-required` marker line), or neither (reviews run on the default guidance).
134
+ - Whether `crysk` is a required check (or only the legacy `pr-hero`, which should move to `crysk`), or that the repository cannot require one (private repository on GitHub Free).
135
+ - Next steps: merge the workflow to the default branch (the comment trigger needs it there), open a same-repo test PR, when to turn off observe-only. If CI skipped, the override is `gh pr comment <n> --body "/crysk review"`.
136
+
137
+ ## References
138
+
139
+ - `assets/workflow.yml` — the one review workflow (`pull_request` + `issue_comment` for `/crysk review`).
140
+ - `assets/admission-config.example.json` — starter `.crysk/config.json`.
141
+ - `references/ci-admission.md` — admission keys, modes, rollout, ledger.
142
+ - `references/opencode-ci.md` — OpenCode secrets and variables, models per role, pin, openai vs deepseek.
143
+ - `docs/github-actions.md` — full CI integration docs.
@@ -0,0 +1,143 @@
1
+ ---
2
+ name: crysk-ci-setup
3
+ description: "Trigger: setup CI, add Crysk to CI, GitHub Actions review, CRYSK_* secrets, crysk-secrets, CRYSK_MODELS, models per role in CI, OpenCode, DeepSeek, CRYSK-INPUT-REMOVED, old OPENCODE_AUTH_JSON / CRYSK_ROUTING workflows, admission policy, configure CI workflow, retrigger, force review, skipped review, /crysk review, /crysk override, pr-hero-force, too many findings, noisy review, post_min_severity, materiality_gate. Scaffolds the one workflow, secrets, models variables, admission config, and the posting and noise settings."
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: juanmaagd
7
+ version: "4.0"
8
+ ---
9
+
10
+ ## Activation Contract
11
+
12
+ Load when the user asks to:
13
+ - Add Crysk to GitHub Actions CI, scaffold `.github/workflows/crysk.yml`, or configure secrets. No local install is needed: the workflow file is the whole install.
14
+ - Configure the models per role in CI, or **OpenCode** (`CRYSK_MODELS`, `CRYSK_OPENCODE_*` secrets, DeepSeek, mixed Claude+OpenCode, fallbacks).
15
+ - Move a workflow off the removed inputs (`CRYSK-INPUT-REMOVED`: `claude-token`, `anthropic-api-key`, `opencode-auth` with the `OPENCODE_AUTH_JSON` secret, `routing` with the `CRYSK_ROUTING` variable).
16
+ - Tune CI spend / re-review / admission policy.
17
+ - Retrigger a skipped CI review (size, admission, or budget) without running the review locally.
18
+ - Reduce review noise: fewer comments (`post_min_severity`) or fewer blocking findings that are real but improbable (`materiality_gate`).
19
+
20
+ ## Hard Rules
21
+
22
+ - **Zero secret leakage:** NEVER print, `cat`, commit, or log API keys, tokens, or an OpenCode `auth.json` record. Reference `${{ secrets.* }}` names only. Inspect `auth.json` **keys and `type` only**.
23
+ - **One `CRYSK_*` secret per credential, nothing else:** `CRYSK_CLAUDE_OAUTH_TOKEN` (subscription), `CRYSK_CLAUDE_API_KEY`, `CRYSK_OPENCODE_<P>_API_KEY` per OpenCode provider, `CRYSK_OPENCODE_OPENAI_OAUTH` for an OpenAI subscription. The workflow names each one in its `crysk-secrets` block, never `toJSON(secrets)`. The old `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY` and `OPENCODE_AUTH_JSON` secrets and the `CRYSK_ROUTING` variable are read by nothing. Models per role go in the public variable `CRYSK_MODELS` (no credentials in it), the Claude order in `CRYSK_CREDENTIALS`, the OpenCode providers in `CRYSK_OPENCODE_PROVIDERS`.
24
+ - **No install needed:** run every Crysk command as `npx -y crysk <command>` (Node is enough; the package brings its own Bun). A global `crysk` on PATH is the same command. CI itself needs no local CLI at all: the workflow runs the action. `npx -y crysk skills install` installs the Crysk, triage, and CI-setup skills into every detected coding agent, with no TTY and no MCP or launchd registration (neither is needed for the CI loop, and npx's temporary cache refuses them).
25
+ - **Deterministic scaffolding:** Run `npx -y crysk setup --ci` (or `npx -y crysk ci init`) with the interview's flags. It writes the one workflow file, `.github/workflows/crysk.yml` (a repo that already has `pr-hero.yml` keeps it: `--force` rewrites it in place, and setup refuses to add a second file beside it). Do not fabricate it from memory. Fallback: copy `assets/workflow.yml`. Never scaffold a `pr-hero-force.yml`; it is retired.
26
+ - **`fetch-depth: 0` is mandatory** on `actions/checkout@v4`.
27
+ - **Gate mode:** the `crysk` commit status is the required check (the legacy `pr-hero` status is no longer posted). The scaffold writes `mode: gate` explicitly: blocking findings, a size or spend-ceiling skip, and a crash set it red. Every review rule that skips a push (low-risk delta, once per PR, `/crysk stop`, the attempt budget used up, `manual_only`) carries the last verdict; answered blocking findings turn a carried red green, marked unverified. Under the attempt budget used up or `manual_only`, that green is held `pending` instead, so a push past the budget or under `manual_only` never turns green without a `/crysk review` or a `/crysk override`. `mode: advisory` keeps it green for a finished review. The job's exit code stays `0` on findings either way, so do not gate on the job.
28
+ - **Required permissions:** `contents: read`, `pull-requests: write`, `issues: write`, `statuses: write`, **`checks: write`**, **`actions: read`** (the admission gate lists past runs; a private repo 403s without it). Template in `assets/workflow.yml` includes all six.
29
+ - **Retrigger is a PR comment: `gh pr comment <n> --body "/crysk review"`.** GitHub Actions runs the review on the runner with `--force`. The comment must be exactly `/crysk review` (or `/crysk review --full`; `/pr-hero review` on a workflow scaffolded before the rename, see the `/crysk` vs `/pr-hero` bullet), and its author needs write access; the action refuses anyone else. Do not run `crysk review --force` locally when the review should happen in CI. `gh run rerun` on a skipped run re-evaluates the gates and does not force. In this repo a comment run checks out the PR head commit before `uses: ./`, so it runs the PR's own engine, not the default branch's.
30
+ - **`/crysk recheck` re-reviews the head and asks the CI adjudicator to rule on pending dismissals.** It is `/crysk review` plus `--adjudicate`, with the same permission check and reaction; refused on fork pull requests. See `docs/github-actions.md` ("Rechecking a dismissal").
31
+ - **`/crysk stop` stops automatic reviews on the PR.** Post it before a push that should not be reviewed: CI admission skips every later automatic review, carrying the last verdict, until a `/crysk review` or `/crysk recheck` comment. It counts only from a user with write access (checked at admission), starts no run, and never turns the gate green. See `docs/github-actions.md` ("Stopping automatic reviews").
32
+ - **`--force` never widens discovery; `--full` does.** When a prior review of the same head was hollow or wrong and re-runs report "No changes to discover", comment `/crysk review --full`. It passes `--full`, which re-discovers the whole PR range.
33
+ - **When the comment trigger takes effect:** GitHub reads a comment-triggered workflow from the **default branch** (for this repo, `main`, not `dev`), so `/crysk review` works only once the workflow file (`crysk.yml`, or `pr-hero.yml` in a repo set up before the rename) with its `issue_comment` trigger is merged there; a user repo also needs an action release that handles the comment, through the `@v0` it pins.
34
+ - **`/crysk` vs `/pr-hero`:** the commands are `/crysk review`, `/crysk recheck`, `/crysk override` and `/crysk stop`; the action still accepts `/pr-hero …` for one version. A `pr-hero.yml` scaffolded before the rename filters only `/pr-hero …`, so a `/crysk …` comment starts nothing there: re-run `npx -y crysk ci init --force` to accept both, which also moves the workflow to the `CRYSK_*` secrets.
35
+ - **Legacy scaffolds:** a `pr-hero.yml` scaffolded before the comment trigger has no `issue_comment` listener, so a comment does nothing. There, use `gh workflow run pr-hero-force.yml -f pr=<n>` (add `-f full=true` to re-discover), or re-scaffold with `npx -y crysk ci init --force`, which leaves `pr-hero-force.yml` in place.
36
+ - **Minimum action version:** this workflow listens to comments, and only an action release that ships the comment handling checks the command and the commenter's write access. An older action reviews on ANY comment starting with `/crysk review`, from anyone who can comment. Never pair this workflow with an older action; a pinned tag or sha must be at or after that release.
37
+ - **Older heads (this repo):** a comment run loads the PR head's own `action.yml`, so on a head from before the comment handling it reviews without reading the comment (no force, no `--full`); merge or rebase the PR onto a base that has it first.
38
+ - **Trust (this repo):** a comment run runs the PR head's code, including its `bun install`, with the workflow's secrets, so write access is checked twice: by the workflow's pre-checkout step (fail closed, before any head code runs) and again by the head's `action.yml`.
39
+ - **Admission config is repo-level:** Write `.crysk/config.json` on the default branch. That file **rejects** `models` and `credentials`: they are person-layer only (`$HOME/.crysk/config.json` on the runner, written from `vars.CRYSK_MODELS` and `vars.CRYSK_CREDENTIALS`).
40
+ - **`.cryskignore` is read from the base ref, not the PR branch, in CI.**
41
+ - **Models and OpenCode are DATA:** the scaffold passes `models: ${{ vars.CRYSK_MODELS }}`, `credentials: ${{ vars.CRYSK_CREDENTIALS }}` and five OpenCode slot lines driven by `vars.CRYSK_OPENCODE_PROVIDERS`. Unset `CRYSK_MODELS` = Claude CI. Never a per-provider Action input. A repository connected to the Crysk platform takes its models from the platform, which wins over the inputs.
42
+ - **OpenCode procedure:** when OpenCode or mixed backends are in scope, follow `references/opencode-ci.md` before setting GitHub DATA (roles, model names, one secret per provider, the providers variable).
43
+
44
+ ## Decision Gates
45
+
46
+ | Condition | Action |
47
+ |---|---|
48
+ | `gh auth status` succeeds | Offer `gh secret set` / `gh variable set` |
49
+ | `gh` missing/unauthenticated | Link to repo Settings → Secrets and variables → Actions (Variables tab for `CRYSK_MODELS`, `CRYSK_CREDENTIALS`, `CRYSK_OPENCODE_PROVIDERS`) |
50
+ | Credential: Claude | **`CRYSK_CLAUDE_OAUTH_TOKEN`** — subscription (`claude setup-token` only, NOT keychain). **`CRYSK_CLAUDE_API_KEY`** — pay-as-you-go. Both set: the subscription runs unless `CRYSK_CREDENTIALS` is `{"claude": ["api_key", "subscription"]}`. |
51
+ | Credential: OpenCode | Read `references/opencode-ci.md`. One `CRYSK_OPENCODE_<P>_API_KEY` per provider + `CRYSK_MODELS` + `CRYSK_OPENCODE_PROVIDERS`. Any `CRYSK_*` credential counts; with none, the run fails red with the `gh secret set` commands. |
52
+ | openai in CI | `CRYSK_OPENCODE_OPENAI_API_KEY` runs metered; `CRYSK_OPENCODE_OPENAI_OAUTH` (base64 of the `openai` record of OpenCode's `auth.json`) is the ChatGPT subscription and wins when both are set. `_OAUTH` works for openai only. |
53
+ | Workflow red with `CRYSK-INPUT-REMOVED` | It still passes `claude-token`, `anthropic-api-key`, `opencode-auth` or `routing`. `npx -y crysk ci init --force`, then set the `CRYSK_*` secrets and variables it prints. |
54
+ | Different models per step | `CRYSK_MODELS` maps roles to lists: `default`, `hunter.<key>`, `refuter`, `consolidate`, `scout`, `summary`, `judge`. Any role left on a `claude:` model needs a Claude secret; OpenCode-only = every role on OpenCode, e.g. `{"default": ["opencode:deepseek/deepseek-v4-flash"]}` (`references/opencode-ci.md`). |
55
+ | Several OpenCode providers in one run | Supported: up to 5 providers through the workflow's slots, each model on its own provider's secret, as primary or fallback. |
56
+ | OpenCode CLI pin | Action installs **1.18.30** iff the setup step wrote an OpenCode auth file OR the models in effect name `opencode:`. Never `latest`. |
57
+ | Fork PRs | Their pushes skip (no secrets). A user with write access comments `/crysk review`, and that run (base context, with secrets) reviews the fork head. Review `if` never reads `secrets`; the action checks for a `CRYSK_*` credential in `crysk-secrets` (or a login file already on the runner). |
58
+ | Spend gates | Defaults: `budget-usd: 12.00` on metered routes (the run chose `CRYSK_CLAUDE_API_KEY`, **or** an OpenCode auth file was built), `max-changed-lines: 4000` and `max-changed-files: 50` on metered routes only; a Claude subscription route has no size limit unless the workflow or `.crysk/config.json` sets one. A subscription run stays unlimited unless an OpenCode auth file is also present. |
59
+ | Existing workflow | `setup --ci` skips; ask before `--force` |
60
+ | First-time admission | Recommend `ci_admission_observe_only: true` — `references/ci-admission.md` |
61
+ | User wants max CI spend | Lower `ci_max_attempts` and/or raise `ci_rereview_min_score` |
62
+ | Custom bot posts findings | Add login to `ci_trusted_actors` |
63
+ | Too many advisory comments on PRs | Raise the posting floor: `post_min_severity: "blocking"` in `.crysk/config.json` posts only blocking findings (`"warning"`, the recommended floor setup writes, hides advisory suggestions only). Blocking findings always post; the gate is unchanged. |
64
+ | Blocking findings that are real but improbable keep PRs red ("an edge case that never happens") | Offer `materiality_gate: true` in `.crysk/config.json` (opt-in, off by default). An isolated judge checks each blocking finding against Crysk's posting policy; one judged not material under normal use posts as advisory and does not block. Security, credential and data-loss findings are never demoted, and any judge failure keeps the finding blocking. Cost: one sonnet call per blocking finding (about 1 per PR, roughly +$0.015 notional and +10 s per review). Pair it with `post_min_severity: "blocking"` to hide the demoted ones entirely. |
65
+ | `materiality_gate` is on but nothing is ever demoted | Read the `materiality` record in the run's `pipeline.json` (in the `crysk-run-*` artifact). `unsupported_route`: the judge runs only on `claude:sonnet-latest` or `claude:opus-latest`, so a `models.judge` in `CRYSK_MODELS` that lists neither stands it down; remove that role or list one of the two. `ceiling`: the pipeline ceiling left no room for one judge wave (about 9 minutes). `ran` with `judged: 0`: the run had no blocking finding the safety guard leaves unprotected, so there was nothing to judge. `skipped` on a re-review with no new commits to review is expected (the judge is left out when nothing new is hunted). `skipped` anywhere else means the key did not reach the run: the repo config must be on the PR's base branch (CI reads it from there) and a global config must not set it `false` (the key is capped). |
66
+ | CI skipped (size, admission, or budget) | `gh pr comment <n> --body "/crysk review"`. The review runs on GitHub Actions. Do not run `crysk review --force` locally for this. Legacy scaffold (no `issue_comment` trigger): `gh workflow run pr-hero-force.yml -f pr=<n>`. |
67
+ | Gate is red with blocking findings the team accepts | `gh pr comment <n> --body "/crysk override"` (write access, same-repo PRs only, valid for that head only; a same-head `/crysk review` keeps it red). |
68
+ | Prior review of the same head was hollow or wrong; re-runs say "No changes to discover" | `gh pr comment <n> --body "/crysk review --full"`. A plain `/crysk review` keeps the narrowed discovery. |
69
+ | Gate red: `crysk: review partial (N of M hunters failed, set abc123) — /pr-hero review retries it` | Some hunters failed and nothing blocking was found. `gh pr comment <n> --body "/crysk review"`. If the same hunters fail every run, fix their route (model, credential) or override. |
70
+ | Gate red: `crysk: review partial again (N of M hunters failed, set abc123) — fix the failing route or /pr-hero override` | The previous review of this head was partial with the same hunters failing, so a retry already failed the same way. Fix the failing hunter's route (model, credential), or `gh pr comment <n> --body "/crysk override"`. `crysk status` answers `override-or-fix`. |
71
+ | Gate error: `CRYSK-CANCELLED: not reviewed — /pr-hero review reviews this head` | The review run was cancelled (a newer push, or by hand). Comment `/crysk review` to review the head. |
72
+ | `CRYSK-MODEL-UNAVAILABLE` (lead "Provider <name>:") | Every hunter's route names a model the provider does not serve. Fix the model id in `CRYSK_MODELS` (check `opencode models <provider>`). |
73
+ | `CRYSK-CRED-UNUSABLE` ("The route <provider>/<model> has no usable credential record") | No `CRYSK_OPENCODE_<P>_API_KEY` reached the run for that provider: set it, add its token to `CRYSK_OPENCODE_PROVIDERS`, or move that model elsewhere in `CRYSK_MODELS`. |
74
+ | `CRYSK-CONFIG-INVALID` naming the `models` or `credentials` input | `CRYSK_MODELS` or `CRYSK_CREDENTIALS` is not valid JSON or breaks a rule (the step's log names the entry). Check the same object locally under `models` / `credentials` in `~/.crysk/config.json` with `npx -y crysk config`, then set the variable again. |
75
+ | Blocking findings answered `dismissed`, gate still red | `gh pr comment <n> --body "/crysk recheck"`: the CI adjudicator rules on each dismissal (at most 5 per run). On `upheld`, comment `/crysk review`: that next review stops counting it. `deferred` / `misclassified` never clear the gate. |
76
+ | Gate error: `CRYSK-GOTCHAS-MISSING` ("the review instructions file (REVIEW.md or .crysk/gotchas.md) is empty or still the scaffold") | Write real facts into that file and delete the `human-attention-required` marker line (or delete the file to review with the default guidance), commit it to the default branch, then comment `/crysk review`. |
77
+ | Gate error: `CRYSK-HUNTERS-FAILED` (every hunter failed) | Check the route and credential first (the `CRYSK-CRED-UNUSABLE` and `CRYSK-MODEL-UNAVAILABLE` rows). Free OpenCode models fail intermittently: comment `/crysk review` to retry. |
78
+ | A `/crysk review` comment did nothing | The workflow is not on the default branch yet, the comment is not exact, the author lacks write access, or the workflow predates the comment trigger (re-scaffold with `--force`). |
79
+
80
+ ## Review Settings Interview (ask the human, never choose for them)
81
+
82
+ Before step 4, ask the human these questions in their language. Use the native question UI when available (one grouped interaction is fine). Do not pick an answer for them, and do not skip a question because a default exists: the point is that they know these settings exist.
83
+
84
+ 1. **Re-review level** (how Crysk reviews new pushes on an open PR):
85
+ - **Minimal**: one automatic review per PR; later pushes only on a `/crysk review` comment.
86
+ - **Balanced (recommended)**: re-review when the push touches risky files or the previous pass found enough (score >= 4); at most 2 automatic passes.
87
+ - **Thorough**: review every push, up to 4 automatic passes. Most coverage, most cost.
88
+ - **Manual**: nothing automatic after the first review; every re-review starts with `/crysk review`.
89
+ 2. **Gate or advisory**: gate turns the `crysk` check red on blocking findings (require it in branch protection to block merges); advisory keeps it green.
90
+ 3. **How CI pays**:
91
+ - **Claude subscription** (`CRYSK_CLAUDE_OAUTH_TOKEN`): do not ask for a budget. Tell them no `budget-usd` is written: a subscription review spends quota, not dollars, and CI applies no ceiling while the run uses the subscription and no `CRYSK_OPENCODE_*` secret builds an OpenCode auth file (an OpenCode model brings back the $12 ceiling, so a subscription mixed with OpenCode is the API-key answer). An API key kept beside it is not used unless `CRYSK_CREDENTIALS` puts `api_key` first.
92
+ - **API key** (`CRYSK_CLAUDE_API_KEY` or an OpenCode provider): ask for the spend ceiling per review in USD (default 12, `0` = none).
93
+ 4. **Changed-lines threshold**: a PR with more changed lines is skipped, not reviewed. Ask on any billing (default 4000, `0` = no limit, only if they say so): unlike the budget it matters on a subscription too, where an unset threshold means no limit at all.
94
+ 5. **Advanced settings**: name them, then ask whether to review them now. Each keeps a working default if skipped:
95
+ - score weights: blocking 2, advisory 1 (integers >= 1; `ci_blocking_weight`, `ci_advisory_weight`), and the score floor 4 (`ci_rereview_min_score`); used only by the risk-aware and thresholded policies;
96
+ - observe only (`ci_admission_observe_only`): log what the rules would skip, but review every push; good for one PR cycle;
97
+ - trusted actors (`ci_trusted_actors`): extra GitHub logins whose Crysk markers count;
98
+ - changed-files limit (`max_changed_files`): a PR touching more files is skipped; unset = none on a subscription, 50 on an API key;
99
+ - exclusions: patterns in `.cryskignore` (gitignore syntax) the review never reads;
100
+ - posting floor (`post_min_severity`): `suggestion` posts everything, `warning` (recommended, and what setup writes when the key is absent) hides advisory suggestions, `blocking` posts only blocking findings. Hidden findings are counted in the summary comment, and the gate is unchanged;
101
+ - materiality gate (`materiality_gate`, off unless they say yes): blocking findings that are real but not material under normal use are posted as advisory instead of blocking, judged by an isolated sonnet call per blocking finding against Crysk's posting policy; security, credential and data-loss findings are never demoted. Tell them the cost (about one call per PR, +$0.015 notional, +10 s), that it runs on Claude only (`claude:sonnet-latest`, or `claude:opus-latest` through `models.judge`), so it needs a Claude secret, and the known limit: on a re-review, a finding that already blocked on an earlier push still counts toward the gate.
102
+
103
+ **On a re-run** (`.crysk/config.json` already has re-review keys, or the workflow already exists), first show the human the current values (`npx -y crysk config`) and offer **Keep current settings** for the level and for the line threshold. When they keep them, omit `--level` / `--max-changed-lines`: passing a flag overwrites that group, including a tuned `max_verification_steps`.
104
+
105
+ Then pass the answers to the scaffold as flags, never as hand-written YAML:
106
+
107
+ ```bash
108
+ npx -y crysk setup --ci --level <minimal|balanced|thorough|manual> --ci-mode <gate|advisory> --billing <subscription|api> --max-changed-lines <n> [--budget-usd <n>]
109
+ ```
110
+
111
+ It writes the workflow, merges the level's keys into `.crysk/config.json` (keeping other keys), and prints a summary of every setting. **Never run it without these flags**: with none it applies balanced and gate, and its summary says nobody chose them. Write any advanced answers into `.crysk/config.json` (and `.cryskignore`) afterwards. The summary `setup --ci` printed predates those edits, so when there were any, show the human the effective settings from `npx -y crysk config` instead. Otherwise show the printed summary, including any `Changed` and `Kept existing` lines: on a re-run (for example `--force` to refresh an old workflow) only the groups a flag names are overwritten, and keys nobody chose stay as the file had them; the workflow keeps its old `mode` and `budget-usd` unless `--ci-mode` or `--billing` / `--budget-usd` is passed. In a terminal, every question defaults to the repository's current value. Details: `references/ci-admission.md`.
112
+
113
+ ## Execution Steps
114
+
115
+ 1. **Inspect repo:** `git rev-parse --is-inside-work-tree`, `git remote get-url origin`, `gh auth status`.
116
+ 2. **Credential path:** Claude-only → skip OpenCode. OpenCode or mix → **read `references/opencode-ci.md`** and execute it (models per role, one secret per provider, the providers variable).
117
+ 3. **Claude secret (if used):** `gh secret set CRYSK_CLAUDE_OAUTH_TOKEN` or `CRYSK_CLAUDE_API_KEY` (secure input, never print).
118
+ 4. **Workflow:** run the interview above, then `npx -y crysk setup --ci` with its flags. It writes `.github/workflows/crysk.yml` (or rewrites an existing `pr-hero.yml` in place) and the level keys in `.crysk/config.json`, and its next steps print the `gh secret set` / `gh variable set` commands for the person's `~/.crysk/config.json` (models, credentials, OpenCode providers); run the ones the human agrees to. Confirm `checks: write` and `actions: read`, both `pull_request` and `issue_comment` triggers, the `crysk-secrets: |` block and the `models` / `credentials` lines. `--force` if an old template lacks them (an old `credentials` job, a missing `issue_comment` trigger, or `claude-token` / `routing` lines mean it predates the current workflow).
119
+ 5. **Review instructions (optional, recommended before the first review):** if the default branch has neither a root `REVIEW.md` nor `.crysk/gotchas.md`, run `npx -y crysk init` in the clone; it scaffolds `REVIEW.md` (an existing `.crysk/gotchas.md` is kept, and no `REVIEW.md` is written beside it). The agent writes the facts from the repository it has in context, not from the template: the deliberate oddity that looks like a bug, the invariant enforced outside the diff, the ownership rule a newcomer would break. The hunters and the refuter read the file as facts; the "Not blocking here" section is applied only by the materiality judge (`materiality_gate: true`, blocking findings only, and only to style, naming, test-hygiene, generated-code and dev-script findings), so fill it only when the human asked for that gate, and delete it otherwise. Delete the `human-attention-required` marker line (Crysk refuses to review while it is there), then commit the file to the default branch. With no file the review runs on the default guidance; an empty or scaffold file fails the run `CRYSK-GOTCHAS-MISSING`.
120
+ 6. **Require the check:** in branch protection, require the `crysk` status check (the gate), not the `review` job. The legacy `pr-hero` status is no longer posted, so a repository that still requires it is blocked until the rule moves to `crysk`. A private repository on GitHub Free cannot require status checks (HTTP 403): report that the gate is advisory there. With `gh`, and only after asking the human: read the current protection first (`gh api repos/<o>/<r>/branches/<default>/protection`), because the PUT replaces all of it; then `gh api -X PUT repos/<o>/<r>/branches/<default>/protection` with `required_status_checks` contexts `["crysk"]`.
121
+ 7. **Advanced settings:** write the answers from interview question 5 into `.crysk/config.json` (and `.cryskignore`), including `post_min_severity` when they chose a floor other than `warning` and `materiality_gate: true` only when they said yes; commit both to the default branch, and to any other branch PRs target (CI reads the config from the PR's base branch, so it applies from the next PR after the merge). **No `models` or `credentials` key there** (the repo parser refuses them). `npx -y crysk config` to verify.
122
+ 8. **Verify:** `npx -y crysk doctor`. `git status`. Confirm no echoed secret, and when OpenCode is on, that every `opencode:` model id in `CRYSK_MODELS` is one `opencode models <provider>` lists and each provider's token is in `CRYSK_OPENCODE_PROVIDERS`.
123
+ 9. **Deploy:** Offer commit. Open a **same-repo** test PR (forks skip).
124
+
125
+ ## Output Contract
126
+
127
+ Report:
128
+ - Secret status (set or manual link). Names only: which `CRYSK_*` secrets exist (`gh secret list`). Never values.
129
+ - Models (if set): the `CRYSK_MODELS` and `CRYSK_CREDENTIALS` JSON (no credentials in them), and for OpenCode the `CRYSK_OPENCODE_PROVIDERS` tokens and that each model id matches `opencode models <provider>`.
130
+ - Workflow path (`crysk.yml`, or the pre-rename `pr-hero.yml`; both present means two reviews per PR, delete one) and whether `checks: write`, `actions: read`, the `issue_comment` trigger, the `crysk-secrets` block and the `models` / `credentials` lines are present, with no removed input left.
131
+ - The review settings summary `setup --ci` printed (level, gate, budget, advanced settings), and which ones the human chose, including the posting floor (`post_min_severity`) and whether `materiality_gate` is on. Confirm repo `.crysk/config.json` has no `models` or `credentials` key.
132
+ - `npx -y crysk doctor` / `npx -y crysk config` outcome.
133
+ - Whether the default branch has a real `REVIEW.md` or `.crysk/gotchas.md` (no `human-attention-required` marker line), or neither (reviews run on the default guidance).
134
+ - Whether `crysk` is a required check (or only the legacy `pr-hero`, which should move to `crysk`), or that the repository cannot require one (private repository on GitHub Free).
135
+ - Next steps: merge the workflow to the default branch (the comment trigger needs it there), open a same-repo test PR, when to turn off observe-only. If CI skipped, the override is `gh pr comment <n> --body "/crysk review"`.
136
+
137
+ ## References
138
+
139
+ - `assets/workflow.yml` — the one review workflow (`pull_request` + `issue_comment` for `/crysk review`).
140
+ - `assets/admission-config.example.json` — starter `.crysk/config.json`.
141
+ - `references/ci-admission.md` — admission keys, modes, rollout, ledger.
142
+ - `references/opencode-ci.md` — OpenCode secrets and variables, models per role, pin, openai vs deepseek.
143
+ - `docs/github-actions.md` — full CI integration docs.