crysk 0.3.2 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -32
- package/dist/SKILL-12as0f3q.md +74 -0
- package/dist/SKILL-2h445snn.md +140 -0
- package/dist/SKILL-6vy283pt.md +140 -0
- package/dist/SKILL-dsnffnfp.md +140 -0
- package/dist/SKILL-ebn0fqaq.md +140 -0
- package/dist/SKILL-gnrbph72.md +140 -0
- package/dist/SKILL-kq0xejn3.md +553 -0
- package/dist/SKILL-qaqsbygw.md +66 -0
- package/dist/SKILL-vws0aqb8.md +553 -0
- package/dist/ci-admission-a6d0wk1c.md +128 -0
- package/dist/ci-admission-t0f5qwth.md +128 -0
- package/dist/cli.js +14567 -14177
- package/dist/index.js +270 -56
- package/dist/review-refuter-btpgnkcd.md +77 -0
- package/package.json +2 -2
- package/prompts/default/PROVENANCE.md +1 -0
- package/prompts/default/review-refuter.md +6 -0
- package/skills/crysk/SKILL.md +3 -3
- package/skills/crysk-ci-setup/SKILL.md +4 -4
- package/skills/crysk-ci-setup/references/ci-admission.md +2 -2
- package/skills/crysk-loop/SKILL.md +19 -8
- package/skills/crysk-pr/SKILL.md +1 -1
- package/src/assets.ts +2 -2
- package/src/ci/gates.ts +9 -6
- package/src/ci/outcome.ts +4 -4
- package/src/ci/platform-config.ts +127 -0
- package/src/ci/platform-report.ts +702 -0
- package/src/ci/platform.ts +449 -0
- package/src/ci/reporter.ts +9 -7
- package/src/ci/review-admission.ts +8 -4
- package/src/ci/setup.ts +112 -9
- package/src/commands/ci-setup.ts +21 -18
- package/src/commands/init.ts +21 -12
- package/src/compare/loop.ts +9 -1
- package/src/compare/martian-adapter.ts +1 -1
- package/src/doctor.ts +48 -29
- package/src/index.ts +1 -1
- package/src/menu-context.ts +1 -1
- package/src/pr/admission.ts +53 -11
- package/src/pr/ci-admission-gate.ts +2 -1
- package/src/pr/finding-state-record.ts +58 -0
- package/src/pr/gate-record.ts +22 -0
- package/src/pr/inline.ts +3 -0
- package/src/pr/posting.ts +4 -0
- package/src/pr/pr-status.ts +27 -7
- package/src/pr/pr.ts +39 -8
- package/src/pr/preflight.ts +43 -1
- package/src/pr/publish-outcome.ts +10 -2
- package/src/pr/review-pr.ts +5 -3
- package/src/pr/target.ts +16 -3
- package/src/rereview/classify.ts +4 -0
- package/src/rereview/prepare.ts +47 -22
- package/src/rereview/state.ts +34 -8
- package/src/review/boundary.ts +2 -1
- package/src/review/materiality-gate.ts +25 -1
- package/src/review/pipeline.ts +60 -15
- package/src/review/preflight.ts +132 -28
- package/src/review/prompt-set.ts +12 -8
- package/src/review/report.ts +34 -14
- package/src/review/review.ts +14 -5
- package/src/review/run.ts +54 -18
- package/src/security/published-text.ts +161 -0
- package/src/triage/triage.ts +2 -1
- package/src/updater.ts +1 -1
- package/src/wizard.ts +35 -9
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: crysk-ci-setup
|
|
3
|
+
description: "Trigger: setup CI, add Crysk to CI, GitHub Actions review, OpenCode, OPENCODE_AUTH_JSON, CRYSK_ROUTING, DeepSeek, 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, routing, admission config, and the posting and noise settings."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: juanmaagd
|
|
7
|
+
version: "3.3"
|
|
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 **OpenCode** in CI (`OPENCODE_AUTH_JSON`, `CRYSK_ROUTING`, DeepSeek, mixed Claude+OpenCode).
|
|
15
|
+
- Tune CI spend / re-review / admission policy.
|
|
16
|
+
- Retrigger a skipped CI review (size, admission, or budget) without running the review locally.
|
|
17
|
+
- Reduce review noise: fewer comments (`post_min_severity`) or fewer blocking findings that are real but improbable (`materiality_gate`).
|
|
18
|
+
|
|
19
|
+
## Hard Rules
|
|
20
|
+
|
|
21
|
+
- **Zero secret leakage:** NEVER print, `cat`, commit, or log API keys, tokens, or `OPENCODE_AUTH_JSON`. Reference `${{ secrets.* }}` names only. Inspect `auth.json` **keys and `type` only**.
|
|
22
|
+
- **No per-provider GitHub secrets:** Do not create `OPENAI_API_KEY` or `DEEPSEEK_API_KEY`. One secret `OPENCODE_AUTH_JSON` (whole store or a CI-only subset) + public variable `CRYSK_ROUTING`. Cap 48 KB each.
|
|
23
|
+
- **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).
|
|
24
|
+
- **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.
|
|
25
|
+
- **`fetch-depth: 0` is mandatory** on `actions/checkout@v4`.
|
|
26
|
+
- **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.
|
|
27
|
+
- **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.
|
|
28
|
+
- **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.
|
|
29
|
+
- **`/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").
|
|
30
|
+
- **`/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").
|
|
31
|
+
- **`--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.
|
|
32
|
+
- **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.
|
|
33
|
+
- **`/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. The same rename moved `PRHERO_ROUTING` to `CRYSK_ROUTING` (the new workflow reads it first, then the old name).
|
|
34
|
+
- **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.
|
|
35
|
+
- **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.
|
|
36
|
+
- **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.
|
|
37
|
+
- **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`.
|
|
38
|
+
- **Admission config is repo-level:** Write `.crysk/config.json` on the default branch. That file **rejects** `routing`. Person-layer only (`$HOME/.crysk/config.json` on the runner, from `vars.CRYSK_ROUTING`).
|
|
39
|
+
- **`.cryskignore` is read from the base ref, not the PR branch, in CI.**
|
|
40
|
+
- **OpenCode is DATA:** quoted `routing: "${{ vars.CRYSK_ROUTING || vars.PRHERO_ROUTING }}"` + `opencode-auth: ${{ secrets.OPENCODE_AUTH_JSON }}`. Unset both = Claude CI. Never a per-provider Action input. Never echo the auth blob.
|
|
41
|
+
- **OpenCode procedure:** when OpenCode or mixed backends are in scope, follow `references/opencode-ci.md` before setting GitHub DATA (strip personal OAuth, `modelSnapshot`, logical vs role).
|
|
42
|
+
|
|
43
|
+
## Decision Gates
|
|
44
|
+
|
|
45
|
+
| Condition | Action |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `gh auth status` succeeds | Offer `gh secret set` / `gh variable set` |
|
|
48
|
+
| `gh` missing/unauthenticated | Link to repo Settings → Secrets and variables → Actions (Variables tab for routing) |
|
|
49
|
+
| Credential: Claude | **`CLAUDE_CODE_OAUTH_TOKEN`** — subscription (`claude setup-token` only, NOT keychain). **`ANTHROPIC_API_KEY`** — pay-as-you-go. |
|
|
50
|
+
| Credential: OpenCode | Read `references/opencode-ci.md`. Secret + variable. Any one of the three secrets counts as a credential; with none, the run fails red with the `gh secret set` commands. |
|
|
51
|
+
| openai API key in CI | **Refuse.** openai → ChatGPT OAuth mapping; `type:"api"` is refused. Use a non-openai API token (tested: deepseek). |
|
|
52
|
+
| Hunters OpenCode / refuter Claude | DATA can: map only `sonnet`. Routing is by logical model, not role; hunters declare `sonnet`, refuter `opus`, summarizer `haiku`. The unmapped `opus` refuter falls through to the Claude CLI (current behavior), so keep a Claude secret. OpenCode-only (no Claude secret): use a `default` route or map all three aliases, never `sonnet` alone (`references/opencode-ci.md`). |
|
|
53
|
+
| Mixed OpenCode providers in one run | Out of scope (#195). One OpenCode provider per run. Mixed `claude-code` + one OpenCode provider is legal. |
|
|
54
|
+
| OpenCode CLI pin | Action installs **1.18.30** iff `opencode-auth != ''` OR routing contains `opencode`. Never `latest`. |
|
|
55
|
+
| 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 credentials (Anthropic **or** Claude OAuth **or** `OPENCODE_AUTH_JSON`). |
|
|
56
|
+
| Spend gates | Defaults: `budget-usd: 10.00` on metered routes (Anthropic key **or** OpenCode auth file), `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. Claude-only OAuth stays unlimited-subscription unless OpenCode auth is also present. |
|
|
57
|
+
| Existing workflow | `setup --ci` skips; ask before `--force` |
|
|
58
|
+
| First-time admission | Recommend `ci_admission_observe_only: true` — `references/ci-admission.md` |
|
|
59
|
+
| User wants max CI spend | Lower `ci_max_attempts` and/or raise `ci_rereview_min_score` |
|
|
60
|
+
| Custom bot posts findings | Add login to `ci_trusted_actors` |
|
|
61
|
+
| 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. |
|
|
62
|
+
| 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. |
|
|
63
|
+
| `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 the Claude Code CLI talking to Anthropic directly, so a `CRYSK_ROUTING` that sends `sonnet` to OpenCode or through a gateway stands it down; keep a direct Claude route for `sonnet` or accept the gate off. `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). |
|
|
64
|
+
| 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>`. |
|
|
65
|
+
| 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). |
|
|
66
|
+
| 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. |
|
|
67
|
+
| 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. |
|
|
68
|
+
| 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`. |
|
|
69
|
+
| Gate error: `PRH-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. |
|
|
70
|
+
| `PRH-MODEL-UNAVAILABLE` (lead "Provider <name>:") | Every hunter's route names a model the provider does not serve. Fix the model id in `CRYSK_ROUTING` (check `opencode models`). |
|
|
71
|
+
| `PRH-CRED-UNUSABLE` ("The route <provider>/<model> has no usable credential record") | `OPENCODE_AUTH_JSON` has no record for that provider. Add it to the blob, or route that model elsewhere. |
|
|
72
|
+
| 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. |
|
|
73
|
+
| Gate error: `PRH-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`. |
|
|
74
|
+
| Gate error: `PRH-HUNTERS-FAILED` (every hunter failed) | Check the route and credential first (the `PRH-CRED-UNUSABLE` and `PRH-MODEL-UNAVAILABLE` rows). Free OpenCode models fail intermittently: comment `/crysk review` to retry. |
|
|
75
|
+
| 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`). |
|
|
76
|
+
|
|
77
|
+
## Review Settings Interview (ask the human, never choose for them)
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
1. **Re-review level** (how Crysk reviews new pushes on an open PR):
|
|
82
|
+
- **Minimal**: one automatic review per PR; later pushes only on a `/crysk review` comment.
|
|
83
|
+
- **Balanced (recommended)**: re-review when the push touches risky files or the previous pass found enough (score >= 4); at most 2 automatic passes.
|
|
84
|
+
- **Thorough**: review every push, up to 4 automatic passes. Most coverage, most cost.
|
|
85
|
+
- **Manual**: nothing automatic after the first review; every re-review starts with `/crysk review`.
|
|
86
|
+
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.
|
|
87
|
+
3. **How CI pays**:
|
|
88
|
+
- **Claude subscription** (`CLAUDE_CODE_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 repo has neither an `ANTHROPIC_API_KEY` nor an `OPENCODE_AUTH_JSON` secret (either one makes CI metered and brings back the $10 ceiling, so a subscription mixed with OpenCode is the API-key answer).
|
|
89
|
+
- **API key** (`ANTHROPIC_API_KEY` or an OpenCode provider): ask for the spend ceiling per review in USD (default 10, `0` = none).
|
|
90
|
+
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.
|
|
91
|
+
5. **Advanced settings**: name them, then ask whether to review them now. Each keeps a working default if skipped:
|
|
92
|
+
- 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;
|
|
93
|
+
- observe only (`ci_admission_observe_only`): log what the rules would skip, but review every push; good for one PR cycle;
|
|
94
|
+
- trusted actors (`ci_trusted_actors`): extra GitHub logins whose Crysk markers count;
|
|
95
|
+
- changed-files limit (`max_changed_files`): a PR touching more files is skipped; unset = none on a subscription, 50 on an API key;
|
|
96
|
+
- exclusions: patterns in `.cryskignore` (gitignore syntax) the review never reads;
|
|
97
|
+
- 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;
|
|
98
|
+
- 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 needs a direct Claude route for `sonnet`, and the known limit: on a re-review, a finding that already blocked on an earlier push still counts toward the gate.
|
|
99
|
+
|
|
100
|
+
**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`.
|
|
101
|
+
|
|
102
|
+
Then pass the answers to the scaffold as flags, never as hand-written YAML:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npx -y crysk setup --ci --level <minimal|balanced|thorough|manual> --ci-mode <gate|advisory> --billing <subscription|api> --max-changed-lines <n> [--budget-usd <n>]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
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`.
|
|
109
|
+
|
|
110
|
+
## Execution Steps
|
|
111
|
+
|
|
112
|
+
1. **Inspect repo:** `git rev-parse --is-inside-work-tree`, `git remote get-url origin`, `gh auth status`.
|
|
113
|
+
2. **Credential path:** Claude-only → skip OpenCode. OpenCode or mix → **read `references/opencode-ci.md`** and execute it (metadata inspect, CI-only blob, secret, routing with `modelSnapshot`).
|
|
114
|
+
3. **Claude secret (if used):** `gh secret set CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` (secure input, never print).
|
|
115
|
+
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`. Confirm `checks: write` and `actions: read`, both `pull_request` and `issue_comment` triggers, quoted `routing` / `opencode-auth`. `--force` if an old template lacks them (an old `credentials` job or a missing `issue_comment` trigger means it predates the single workflow).
|
|
116
|
+
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 `PRH-GOTCHAS-MISSING`.
|
|
117
|
+
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"]`.
|
|
118
|
+
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 `routing` key.** `npx -y crysk config` to verify.
|
|
119
|
+
8. **Verify:** `npx -y crysk doctor`. `git status`. Confirm no openai `type:"api"` blob, no echoed auth, `modelSnapshot` matches `opencode models` when OpenCode is on.
|
|
120
|
+
9. **Deploy:** Offer commit. Open a **same-repo** test PR (forks skip).
|
|
121
|
+
|
|
122
|
+
## Output Contract
|
|
123
|
+
|
|
124
|
+
Report:
|
|
125
|
+
- Secret status (set or manual link). Names only: which of `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` / `OPENCODE_AUTH_JSON` exist. Never values.
|
|
126
|
+
- OpenCode (if in scope): `OPENCODE_AUTH_JSON` set; blob providers **names + type only**; whether the blob was stripped to one CI provider; `CRYSK_ROUTING` JSON (no credentials); `modelSnapshot` vs `opencode models`.
|
|
127
|
+
- 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, and quoted `routing` / `opencode-auth` are present.
|
|
128
|
+
- 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 `routing` key.
|
|
129
|
+
- `npx -y crysk doctor` / `npx -y crysk config` outcome.
|
|
130
|
+
- 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).
|
|
131
|
+
- 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).
|
|
132
|
+
- 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"`.
|
|
133
|
+
|
|
134
|
+
## References
|
|
135
|
+
|
|
136
|
+
- `assets/workflow.yml` — the one review workflow (`pull_request` + `issue_comment` for `/crysk review`).
|
|
137
|
+
- `assets/admission-config.example.json` — starter `.crysk/config.json`.
|
|
138
|
+
- `references/ci-admission.md` — admission keys, modes, rollout, ledger.
|
|
139
|
+
- `references/opencode-ci.md` — OpenCode secret/variable procedure, routing, pin, openai vs deepseek.
|
|
140
|
+
- `docs/github-actions.md` — full CI integration docs.
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: crysk-ci-setup
|
|
3
|
+
description: "Trigger: setup CI, add Crysk to CI, GitHub Actions review, OpenCode, OPENCODE_AUTH_JSON, CRYSK_ROUTING, DeepSeek, 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, routing, admission config, and the posting and noise settings."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: juanmaagd
|
|
7
|
+
version: "3.3"
|
|
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 **OpenCode** in CI (`OPENCODE_AUTH_JSON`, `CRYSK_ROUTING`, DeepSeek, mixed Claude+OpenCode).
|
|
15
|
+
- Tune CI spend / re-review / admission policy.
|
|
16
|
+
- Retrigger a skipped CI review (size, admission, or budget) without running the review locally.
|
|
17
|
+
- Reduce review noise: fewer comments (`post_min_severity`) or fewer blocking findings that are real but improbable (`materiality_gate`).
|
|
18
|
+
|
|
19
|
+
## Hard Rules
|
|
20
|
+
|
|
21
|
+
- **Zero secret leakage:** NEVER print, `cat`, commit, or log API keys, tokens, or `OPENCODE_AUTH_JSON`. Reference `${{ secrets.* }}` names only. Inspect `auth.json` **keys and `type` only**.
|
|
22
|
+
- **No per-provider GitHub secrets:** Do not create `OPENAI_API_KEY` or `DEEPSEEK_API_KEY`. One secret `OPENCODE_AUTH_JSON` (whole store or a CI-only subset) + public variable `CRYSK_ROUTING`. Cap 48 KB each.
|
|
23
|
+
- **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).
|
|
24
|
+
- **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.
|
|
25
|
+
- **`fetch-depth: 0` is mandatory** on `actions/checkout@v4`.
|
|
26
|
+
- **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. `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.
|
|
27
|
+
- **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.
|
|
28
|
+
- **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.
|
|
29
|
+
- **`/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").
|
|
30
|
+
- **`/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").
|
|
31
|
+
- **`--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.
|
|
32
|
+
- **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.
|
|
33
|
+
- **`/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. The same rename moved `PRHERO_ROUTING` to `CRYSK_ROUTING` (the new workflow reads it first, then the old name).
|
|
34
|
+
- **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.
|
|
35
|
+
- **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.
|
|
36
|
+
- **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.
|
|
37
|
+
- **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`.
|
|
38
|
+
- **Admission config is repo-level:** Write `.crysk/config.json` on the default branch. That file **rejects** `routing`. Person-layer only (`$HOME/.crysk/config.json` on the runner, from `vars.CRYSK_ROUTING`).
|
|
39
|
+
- **`.cryskignore` is read from the base ref, not the PR branch, in CI.**
|
|
40
|
+
- **OpenCode is DATA:** quoted `routing: "${{ vars.CRYSK_ROUTING || vars.PRHERO_ROUTING }}"` + `opencode-auth: ${{ secrets.OPENCODE_AUTH_JSON }}`. Unset both = Claude CI. Never a per-provider Action input. Never echo the auth blob.
|
|
41
|
+
- **OpenCode procedure:** when OpenCode or mixed backends are in scope, follow `references/opencode-ci.md` before setting GitHub DATA (strip personal OAuth, `modelSnapshot`, logical vs role).
|
|
42
|
+
|
|
43
|
+
## Decision Gates
|
|
44
|
+
|
|
45
|
+
| Condition | Action |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `gh auth status` succeeds | Offer `gh secret set` / `gh variable set` |
|
|
48
|
+
| `gh` missing/unauthenticated | Link to repo Settings → Secrets and variables → Actions (Variables tab for routing) |
|
|
49
|
+
| Credential: Claude | **`CLAUDE_CODE_OAUTH_TOKEN`** — subscription (`claude setup-token` only, NOT keychain). **`ANTHROPIC_API_KEY`** — pay-as-you-go. |
|
|
50
|
+
| Credential: OpenCode | Read `references/opencode-ci.md`. Secret + variable. Any one of the three secrets counts as a credential; with none, the run fails red with the `gh secret set` commands. |
|
|
51
|
+
| openai API key in CI | **Refuse.** openai → ChatGPT OAuth mapping; `type:"api"` is refused. Use a non-openai API token (tested: deepseek). |
|
|
52
|
+
| Hunters OpenCode / refuter Claude | DATA can: map only `sonnet`. Routing is by logical model, not role; hunters declare `sonnet`, refuter `opus`, summarizer `haiku`. The unmapped `opus` refuter falls through to the Claude CLI (current behavior), so keep a Claude secret. OpenCode-only (no Claude secret): use a `default` route or map all three aliases, never `sonnet` alone (`references/opencode-ci.md`). |
|
|
53
|
+
| Mixed OpenCode providers in one run | Out of scope (#195). One OpenCode provider per run. Mixed `claude-code` + one OpenCode provider is legal. |
|
|
54
|
+
| OpenCode CLI pin | Action installs **1.18.30** iff `opencode-auth != ''` OR routing contains `opencode`. Never `latest`. |
|
|
55
|
+
| 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 credentials (Anthropic **or** Claude OAuth **or** `OPENCODE_AUTH_JSON`). |
|
|
56
|
+
| Spend gates | Defaults: `budget-usd: 10.00` on metered routes (Anthropic key **or** OpenCode auth file), `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. Claude-only OAuth stays unlimited-subscription unless OpenCode auth is also present. |
|
|
57
|
+
| Existing workflow | `setup --ci` skips; ask before `--force` |
|
|
58
|
+
| First-time admission | Recommend `ci_admission_observe_only: true` — `references/ci-admission.md` |
|
|
59
|
+
| User wants max CI spend | Lower `ci_max_attempts` and/or raise `ci_rereview_min_score` |
|
|
60
|
+
| Custom bot posts findings | Add login to `ci_trusted_actors` |
|
|
61
|
+
| 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. |
|
|
62
|
+
| 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. |
|
|
63
|
+
| `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 the Claude Code CLI talking to Anthropic directly, so a `CRYSK_ROUTING` that sends `sonnet` to OpenCode or through a gateway stands it down; keep a direct Claude route for `sonnet` or accept the gate off. `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). |
|
|
64
|
+
| 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>`. |
|
|
65
|
+
| 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). |
|
|
66
|
+
| 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. |
|
|
67
|
+
| 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. |
|
|
68
|
+
| 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`. |
|
|
69
|
+
| Gate error: `PRH-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. |
|
|
70
|
+
| `PRH-MODEL-UNAVAILABLE` (lead "Provider <name>:") | Every hunter's route names a model the provider does not serve. Fix the model id in `CRYSK_ROUTING` (check `opencode models`). |
|
|
71
|
+
| `PRH-CRED-UNUSABLE` ("The route <provider>/<model> has no usable credential record") | `OPENCODE_AUTH_JSON` has no record for that provider. Add it to the blob, or route that model elsewhere. |
|
|
72
|
+
| 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. |
|
|
73
|
+
| Gate error: `PRH-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`. |
|
|
74
|
+
| Gate error: `PRH-HUNTERS-FAILED` (every hunter failed) | Check the route and credential first (the `PRH-CRED-UNUSABLE` and `PRH-MODEL-UNAVAILABLE` rows). Free OpenCode models fail intermittently: comment `/crysk review` to retry. |
|
|
75
|
+
| 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`). |
|
|
76
|
+
|
|
77
|
+
## Review Settings Interview (ask the human, never choose for them)
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
1. **Re-review level** (how Crysk reviews new pushes on an open PR):
|
|
82
|
+
- **Minimal**: one automatic review per PR; later pushes only on a `/crysk review` comment.
|
|
83
|
+
- **Balanced (recommended)**: re-review when the push touches risky files or the previous pass found enough (score >= 4); at most 2 automatic passes.
|
|
84
|
+
- **Thorough**: review every push, up to 4 automatic passes. Most coverage, most cost.
|
|
85
|
+
- **Manual**: nothing automatic after the first review; every re-review starts with `/crysk review`.
|
|
86
|
+
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.
|
|
87
|
+
3. **How CI pays**:
|
|
88
|
+
- **Claude subscription** (`CLAUDE_CODE_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 repo has neither an `ANTHROPIC_API_KEY` nor an `OPENCODE_AUTH_JSON` secret (either one makes CI metered and brings back the $10 ceiling, so a subscription mixed with OpenCode is the API-key answer).
|
|
89
|
+
- **API key** (`ANTHROPIC_API_KEY` or an OpenCode provider): ask for the spend ceiling per review in USD (default 10, `0` = none).
|
|
90
|
+
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.
|
|
91
|
+
5. **Advanced settings**: name them, then ask whether to review them now. Each keeps a working default if skipped:
|
|
92
|
+
- 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;
|
|
93
|
+
- observe only (`ci_admission_observe_only`): log what the rules would skip, but review every push; good for one PR cycle;
|
|
94
|
+
- trusted actors (`ci_trusted_actors`): extra GitHub logins whose Crysk markers count;
|
|
95
|
+
- changed-files limit (`max_changed_files`): a PR touching more files is skipped; unset = none on a subscription, 50 on an API key;
|
|
96
|
+
- exclusions: patterns in `.cryskignore` (gitignore syntax) the review never reads;
|
|
97
|
+
- 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;
|
|
98
|
+
- 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 needs a direct Claude route for `sonnet`, and the known limit: on a re-review, a finding that already blocked on an earlier push still counts toward the gate.
|
|
99
|
+
|
|
100
|
+
**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`.
|
|
101
|
+
|
|
102
|
+
Then pass the answers to the scaffold as flags, never as hand-written YAML:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npx -y crysk setup --ci --level <minimal|balanced|thorough|manual> --ci-mode <gate|advisory> --billing <subscription|api> --max-changed-lines <n> [--budget-usd <n>]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
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`.
|
|
109
|
+
|
|
110
|
+
## Execution Steps
|
|
111
|
+
|
|
112
|
+
1. **Inspect repo:** `git rev-parse --is-inside-work-tree`, `git remote get-url origin`, `gh auth status`.
|
|
113
|
+
2. **Credential path:** Claude-only → skip OpenCode. OpenCode or mix → **read `references/opencode-ci.md`** and execute it (metadata inspect, CI-only blob, secret, routing with `modelSnapshot`).
|
|
114
|
+
3. **Claude secret (if used):** `gh secret set CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` (secure input, never print).
|
|
115
|
+
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`. Confirm `checks: write` and `actions: read`, both `pull_request` and `issue_comment` triggers, quoted `routing` / `opencode-auth`. `--force` if an old template lacks them (an old `credentials` job or a missing `issue_comment` trigger means it predates the single workflow).
|
|
116
|
+
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 file is injected verbatim into every hunter's prompt; it does not filter findings yet. 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 `PRH-GOTCHAS-MISSING`.
|
|
117
|
+
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"]`.
|
|
118
|
+
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 `routing` key.** `npx -y crysk config` to verify.
|
|
119
|
+
8. **Verify:** `npx -y crysk doctor`. `git status`. Confirm no openai `type:"api"` blob, no echoed auth, `modelSnapshot` matches `opencode models` when OpenCode is on.
|
|
120
|
+
9. **Deploy:** Offer commit. Open a **same-repo** test PR (forks skip).
|
|
121
|
+
|
|
122
|
+
## Output Contract
|
|
123
|
+
|
|
124
|
+
Report:
|
|
125
|
+
- Secret status (set or manual link). Names only: which of `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` / `OPENCODE_AUTH_JSON` exist. Never values.
|
|
126
|
+
- OpenCode (if in scope): `OPENCODE_AUTH_JSON` set; blob providers **names + type only**; whether the blob was stripped to one CI provider; `CRYSK_ROUTING` JSON (no credentials); `modelSnapshot` vs `opencode models`.
|
|
127
|
+
- 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, and quoted `routing` / `opencode-auth` are present.
|
|
128
|
+
- 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 `routing` key.
|
|
129
|
+
- `npx -y crysk doctor` / `npx -y crysk config` outcome.
|
|
130
|
+
- 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).
|
|
131
|
+
- 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).
|
|
132
|
+
- 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"`.
|
|
133
|
+
|
|
134
|
+
## References
|
|
135
|
+
|
|
136
|
+
- `assets/workflow.yml` — the one review workflow (`pull_request` + `issue_comment` for `/crysk review`).
|
|
137
|
+
- `assets/admission-config.example.json` — starter `.crysk/config.json`.
|
|
138
|
+
- `references/ci-admission.md` — admission keys, modes, rollout, ledger.
|
|
139
|
+
- `references/opencode-ci.md` — OpenCode secret/variable procedure, routing, pin, openai vs deepseek.
|
|
140
|
+
- `docs/github-actions.md` — full CI integration docs.
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: crysk-ci-setup
|
|
3
|
+
description: "Trigger: setup CI, add Crysk to CI, GitHub Actions review, OpenCode, OPENCODE_AUTH_JSON, CRYSK_ROUTING, DeepSeek, 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, routing, admission config, and the posting and noise settings."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: juanmaagd
|
|
7
|
+
version: "3.3"
|
|
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 **OpenCode** in CI (`OPENCODE_AUTH_JSON`, `CRYSK_ROUTING`, DeepSeek, mixed Claude+OpenCode).
|
|
15
|
+
- Tune CI spend / re-review / admission policy.
|
|
16
|
+
- Retrigger a skipped CI review (size, admission, or budget) without running the review locally.
|
|
17
|
+
- Reduce review noise: fewer comments (`post_min_severity`) or fewer blocking findings that are real but improbable (`materiality_gate`).
|
|
18
|
+
|
|
19
|
+
## Hard Rules
|
|
20
|
+
|
|
21
|
+
- **Zero secret leakage:** NEVER print, `cat`, commit, or log API keys, tokens, or `OPENCODE_AUTH_JSON`. Reference `${{ secrets.* }}` names only. Inspect `auth.json` **keys and `type` only**.
|
|
22
|
+
- **No per-provider GitHub secrets:** Do not create `OPENAI_API_KEY` or `DEEPSEEK_API_KEY`. One secret `OPENCODE_AUTH_JSON` (whole store or a CI-only subset) + public variable `CRYSK_ROUTING`. Cap 48 KB each.
|
|
23
|
+
- **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).
|
|
24
|
+
- **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.
|
|
25
|
+
- **`fetch-depth: 0` is mandatory** on `actions/checkout@v4`.
|
|
26
|
+
- **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` until a maintainer comments `/crysk review` or `/crysk override`, so no push merges green without a review. `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.
|
|
27
|
+
- **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.
|
|
28
|
+
- **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.
|
|
29
|
+
- **`/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").
|
|
30
|
+
- **`/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").
|
|
31
|
+
- **`--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.
|
|
32
|
+
- **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.
|
|
33
|
+
- **`/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. The same rename moved `PRHERO_ROUTING` to `CRYSK_ROUTING` (the new workflow reads it first, then the old name).
|
|
34
|
+
- **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.
|
|
35
|
+
- **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.
|
|
36
|
+
- **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.
|
|
37
|
+
- **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`.
|
|
38
|
+
- **Admission config is repo-level:** Write `.crysk/config.json` on the default branch. That file **rejects** `routing`. Person-layer only (`$HOME/.crysk/config.json` on the runner, from `vars.CRYSK_ROUTING`).
|
|
39
|
+
- **`.cryskignore` is read from the base ref, not the PR branch, in CI.**
|
|
40
|
+
- **OpenCode is DATA:** quoted `routing: "${{ vars.CRYSK_ROUTING || vars.PRHERO_ROUTING }}"` + `opencode-auth: ${{ secrets.OPENCODE_AUTH_JSON }}`. Unset both = Claude CI. Never a per-provider Action input. Never echo the auth blob.
|
|
41
|
+
- **OpenCode procedure:** when OpenCode or mixed backends are in scope, follow `references/opencode-ci.md` before setting GitHub DATA (strip personal OAuth, `modelSnapshot`, logical vs role).
|
|
42
|
+
|
|
43
|
+
## Decision Gates
|
|
44
|
+
|
|
45
|
+
| Condition | Action |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `gh auth status` succeeds | Offer `gh secret set` / `gh variable set` |
|
|
48
|
+
| `gh` missing/unauthenticated | Link to repo Settings → Secrets and variables → Actions (Variables tab for routing) |
|
|
49
|
+
| Credential: Claude | **`CLAUDE_CODE_OAUTH_TOKEN`** — subscription (`claude setup-token` only, NOT keychain). **`ANTHROPIC_API_KEY`** — pay-as-you-go. |
|
|
50
|
+
| Credential: OpenCode | Read `references/opencode-ci.md`. Secret + variable. Any one of the three secrets counts as a credential; with none, the run fails red with the `gh secret set` commands. |
|
|
51
|
+
| openai API key in CI | **Refuse.** openai → ChatGPT OAuth mapping; `type:"api"` is refused. Use a non-openai API token (tested: deepseek). |
|
|
52
|
+
| Hunters OpenCode / refuter Claude | DATA can: map only `sonnet`. Routing is by logical model, not role; hunters declare `sonnet`, refuter `opus`, summarizer `haiku`. The unmapped `opus` refuter falls through to the Claude CLI (current behavior), so keep a Claude secret. OpenCode-only (no Claude secret): use a `default` route or map all three aliases, never `sonnet` alone (`references/opencode-ci.md`). |
|
|
53
|
+
| Mixed OpenCode providers in one run | Out of scope (#195). One OpenCode provider per run. Mixed `claude-code` + one OpenCode provider is legal. |
|
|
54
|
+
| OpenCode CLI pin | Action installs **1.18.30** iff `opencode-auth != ''` OR routing contains `opencode`. Never `latest`. |
|
|
55
|
+
| 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 credentials (Anthropic **or** Claude OAuth **or** `OPENCODE_AUTH_JSON`). |
|
|
56
|
+
| Spend gates | Defaults: `budget-usd: 10.00` on metered routes (Anthropic key **or** OpenCode auth file), `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. Claude-only OAuth stays unlimited-subscription unless OpenCode auth is also present. |
|
|
57
|
+
| Existing workflow | `setup --ci` skips; ask before `--force` |
|
|
58
|
+
| First-time admission | Recommend `ci_admission_observe_only: true` — `references/ci-admission.md` |
|
|
59
|
+
| User wants max CI spend | Lower `ci_max_attempts` and/or raise `ci_rereview_min_score` |
|
|
60
|
+
| Custom bot posts findings | Add login to `ci_trusted_actors` |
|
|
61
|
+
| 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. |
|
|
62
|
+
| 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. |
|
|
63
|
+
| `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 the Claude Code CLI talking to Anthropic directly, so a `CRYSK_ROUTING` that sends `sonnet` to OpenCode or through a gateway stands it down; keep a direct Claude route for `sonnet` or accept the gate off. `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). |
|
|
64
|
+
| 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>`. |
|
|
65
|
+
| 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). |
|
|
66
|
+
| 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. |
|
|
67
|
+
| 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. |
|
|
68
|
+
| 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`. |
|
|
69
|
+
| Gate error: `PRH-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. |
|
|
70
|
+
| `PRH-MODEL-UNAVAILABLE` (lead "Provider <name>:") | Every hunter's route names a model the provider does not serve. Fix the model id in `CRYSK_ROUTING` (check `opencode models`). |
|
|
71
|
+
| `PRH-CRED-UNUSABLE` ("The route <provider>/<model> has no usable credential record") | `OPENCODE_AUTH_JSON` has no record for that provider. Add it to the blob, or route that model elsewhere. |
|
|
72
|
+
| 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. |
|
|
73
|
+
| Gate error: `PRH-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`. |
|
|
74
|
+
| Gate error: `PRH-HUNTERS-FAILED` (every hunter failed) | Check the route and credential first (the `PRH-CRED-UNUSABLE` and `PRH-MODEL-UNAVAILABLE` rows). Free OpenCode models fail intermittently: comment `/crysk review` to retry. |
|
|
75
|
+
| 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`). |
|
|
76
|
+
|
|
77
|
+
## Review Settings Interview (ask the human, never choose for them)
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
1. **Re-review level** (how Crysk reviews new pushes on an open PR):
|
|
82
|
+
- **Minimal**: one automatic review per PR; later pushes only on a `/crysk review` comment.
|
|
83
|
+
- **Balanced (recommended)**: re-review when the push touches risky files or the previous pass found enough (score >= 4); at most 2 automatic passes.
|
|
84
|
+
- **Thorough**: review every push, up to 4 automatic passes. Most coverage, most cost.
|
|
85
|
+
- **Manual**: nothing automatic after the first review; every re-review starts with `/crysk review`.
|
|
86
|
+
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.
|
|
87
|
+
3. **How CI pays**:
|
|
88
|
+
- **Claude subscription** (`CLAUDE_CODE_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 repo has neither an `ANTHROPIC_API_KEY` nor an `OPENCODE_AUTH_JSON` secret (either one makes CI metered and brings back the $10 ceiling, so a subscription mixed with OpenCode is the API-key answer).
|
|
89
|
+
- **API key** (`ANTHROPIC_API_KEY` or an OpenCode provider): ask for the spend ceiling per review in USD (default 10, `0` = none).
|
|
90
|
+
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.
|
|
91
|
+
5. **Advanced settings**: name them, then ask whether to review them now. Each keeps a working default if skipped:
|
|
92
|
+
- 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;
|
|
93
|
+
- observe only (`ci_admission_observe_only`): log what the rules would skip, but review every push; good for one PR cycle;
|
|
94
|
+
- trusted actors (`ci_trusted_actors`): extra GitHub logins whose Crysk markers count;
|
|
95
|
+
- changed-files limit (`max_changed_files`): a PR touching more files is skipped; unset = none on a subscription, 50 on an API key;
|
|
96
|
+
- exclusions: patterns in `.cryskignore` (gitignore syntax) the review never reads;
|
|
97
|
+
- 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;
|
|
98
|
+
- 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 needs a direct Claude route for `sonnet`, and the known limit: on a re-review, a finding that already blocked on an earlier push still counts toward the gate.
|
|
99
|
+
|
|
100
|
+
**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`.
|
|
101
|
+
|
|
102
|
+
Then pass the answers to the scaffold as flags, never as hand-written YAML:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npx -y crysk setup --ci --level <minimal|balanced|thorough|manual> --ci-mode <gate|advisory> --billing <subscription|api> --max-changed-lines <n> [--budget-usd <n>]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
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`.
|
|
109
|
+
|
|
110
|
+
## Execution Steps
|
|
111
|
+
|
|
112
|
+
1. **Inspect repo:** `git rev-parse --is-inside-work-tree`, `git remote get-url origin`, `gh auth status`.
|
|
113
|
+
2. **Credential path:** Claude-only → skip OpenCode. OpenCode or mix → **read `references/opencode-ci.md`** and execute it (metadata inspect, CI-only blob, secret, routing with `modelSnapshot`).
|
|
114
|
+
3. **Claude secret (if used):** `gh secret set CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` (secure input, never print).
|
|
115
|
+
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`. Confirm `checks: write` and `actions: read`, both `pull_request` and `issue_comment` triggers, quoted `routing` / `opencode-auth`. `--force` if an old template lacks them (an old `credentials` job or a missing `issue_comment` trigger means it predates the single workflow).
|
|
116
|
+
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 `PRH-GOTCHAS-MISSING`.
|
|
117
|
+
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"]`.
|
|
118
|
+
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 `routing` key.** `npx -y crysk config` to verify.
|
|
119
|
+
8. **Verify:** `npx -y crysk doctor`. `git status`. Confirm no openai `type:"api"` blob, no echoed auth, `modelSnapshot` matches `opencode models` when OpenCode is on.
|
|
120
|
+
9. **Deploy:** Offer commit. Open a **same-repo** test PR (forks skip).
|
|
121
|
+
|
|
122
|
+
## Output Contract
|
|
123
|
+
|
|
124
|
+
Report:
|
|
125
|
+
- Secret status (set or manual link). Names only: which of `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY` / `OPENCODE_AUTH_JSON` exist. Never values.
|
|
126
|
+
- OpenCode (if in scope): `OPENCODE_AUTH_JSON` set; blob providers **names + type only**; whether the blob was stripped to one CI provider; `CRYSK_ROUTING` JSON (no credentials); `modelSnapshot` vs `opencode models`.
|
|
127
|
+
- 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, and quoted `routing` / `opencode-auth` are present.
|
|
128
|
+
- 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 `routing` key.
|
|
129
|
+
- `npx -y crysk doctor` / `npx -y crysk config` outcome.
|
|
130
|
+
- 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).
|
|
131
|
+
- 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).
|
|
132
|
+
- 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"`.
|
|
133
|
+
|
|
134
|
+
## References
|
|
135
|
+
|
|
136
|
+
- `assets/workflow.yml` — the one review workflow (`pull_request` + `issue_comment` for `/crysk review`).
|
|
137
|
+
- `assets/admission-config.example.json` — starter `.crysk/config.json`.
|
|
138
|
+
- `references/ci-admission.md` — admission keys, modes, rollout, ledger.
|
|
139
|
+
- `references/opencode-ci.md` — OpenCode secret/variable procedure, routing, pin, openai vs deepseek.
|
|
140
|
+
- `docs/github-actions.md` — full CI integration docs.
|