crysk 0.3.1 → 0.3.2

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 (65) hide show
  1. package/README.md +9 -5
  2. package/dist/SKILL-6j27707y.md +140 -0
  3. package/dist/SKILL-816621e5.md +74 -0
  4. package/dist/SKILL-bnh7nrjz.md +74 -0
  5. package/dist/SKILL-fv8x6hhx.md +140 -0
  6. package/dist/SKILL-nv32jpc5.md +74 -0
  7. package/dist/SKILL-qnfc8yp3.md +539 -0
  8. package/dist/SKILL-xr56f0b6.md +140 -0
  9. package/dist/SKILL-yz6wk92g.md +542 -0
  10. package/dist/ci-admission-09k2ba89.md +126 -0
  11. package/dist/ci-admission-f19qh39t.md +128 -0
  12. package/dist/ci-admission-tcqsj7b2.md +126 -0
  13. package/dist/cli.js +1831 -1150
  14. package/dist/index.js +1464 -911
  15. package/dist/materiality-f1qwnvg1.md +27 -0
  16. package/package.json +3 -2
  17. package/prompts/materiality.md +27 -0
  18. package/skills/crysk/SKILL.md +2 -2
  19. package/skills/crysk-ci-setup/SKILL.md +13 -7
  20. package/skills/crysk-ci-setup/references/ci-admission.md +4 -0
  21. package/skills/crysk-loop/SKILL.md +32 -5
  22. package/src/asset-manifest.ts +2 -0
  23. package/src/assets.ts +4 -1
  24. package/src/brand.ts +11 -9
  25. package/src/ci/cli-record.ts +1 -1
  26. package/src/ci/gates.ts +31 -0
  27. package/src/ci/outcome.ts +2 -1
  28. package/src/ci/override.ts +11 -10
  29. package/src/ci/publish.ts +44 -103
  30. package/src/ci/reporter.ts +34 -5
  31. package/src/ci/review-levels.ts +21 -0
  32. package/src/ci/setup.ts +1 -2
  33. package/src/commands/post.ts +17 -0
  34. package/src/compare/loop.ts +356 -0
  35. package/src/compare/materiality.ts +266 -0
  36. package/src/compare/noise.ts +166 -0
  37. package/src/diversity/projection.ts +3 -0
  38. package/src/index.ts +1 -1
  39. package/src/model/routing.ts +62 -0
  40. package/src/pr/admission.ts +13 -1
  41. package/src/pr/discovery.ts +17 -5
  42. package/src/pr/inline.ts +15 -1
  43. package/src/pr/plan.ts +5 -0
  44. package/src/pr/post-floor.ts +30 -0
  45. package/src/pr/posting.ts +4 -0
  46. package/src/pr/pr-status.ts +14 -0
  47. package/src/pr/pr.ts +50 -34
  48. package/src/pr/preflight.ts +2 -2
  49. package/src/pr/publish-outcome.ts +4 -0
  50. package/src/pr/review-pr.ts +65 -26
  51. package/src/pr/teardown.ts +1 -1
  52. package/src/rereview/prepare.ts +16 -0
  53. package/src/rereview/state.ts +206 -25
  54. package/src/review/boundary.ts +4 -1
  55. package/src/review/dedupe.ts +48 -4
  56. package/src/review/findings.ts +47 -1
  57. package/src/review/materiality-gate.ts +134 -0
  58. package/src/review/pipeline.ts +521 -41
  59. package/src/review/preflight.ts +69 -0
  60. package/src/review/report.ts +73 -10
  61. package/src/review/review.ts +16 -0
  62. package/src/review/route-preflight.ts +29 -1
  63. package/src/review/run.ts +2 -0
  64. package/src/ui/config.ts +8 -0
  65. package/src/updater.ts +1 -1
@@ -0,0 +1,126 @@
1
+ # CI review admission — setup reference
2
+
3
+ Read this when configuring `.crysk/config.json` during CI setup. Full operator docs:
4
+ `docs/github-actions.md` (section **CI review admission**).
5
+
6
+ ## Where config lives
7
+
8
+ - **Repository** `.crysk/config.json` on the default branch — authoritative.
9
+ - NOT in the PR branch worktree. Authors cannot change admission to suppress their own PR.
10
+ - Verify with `crysk config` after editing.
11
+
12
+ ## Keys and defaults
13
+
14
+ | Key | Default | Meaning |
15
+ |---|---|---|
16
+ | `ci_review_policy` | `risk_aware` | When to spend on `synchronize` pushes |
17
+ | `ci_max_attempts` | `2` | Automatic attempt budget per PR |
18
+ | `ci_rereview_min_score` | `4` | Prior score floor for re-review |
19
+ | `ci_blocking_weight` | `2` | Score weight per blocking-tier finding |
20
+ | `ci_advisory_weight` | `1` | Score weight per advisory-tier finding |
21
+ | `ci_trusted_actors` | `[]` | Extra GitHub logins for authoritative markers (+ `GITHUB_ACTOR`) |
22
+ | `ci_admission_observe_only` | `false` | Log would-be skip/manual decisions but always run |
23
+ | `max_verification_steps` | `8` | Max prior open findings verified per re-review (`0` pauses verification; capped key) |
24
+
25
+ `ci_max_reviews` is legacy — use `ci_max_attempts` (same fallback).
26
+
27
+ **Score:** `blocking × ci_blocking_weight + advisory × ci_advisory_weight`
28
+
29
+ **How a re-review depends on the previous pass:**
30
+ - **Whether it runs (admission):** in `risk_aware` and `thresholded` modes, the previous review's finding score (`blocking × 2 + advisory × 1` by default) is compared against `ci_rereview_min_score`, bounded by `ci_max_attempts` total automatic passes per PR.
31
+ - **What it does when it runs:** discovery is incremental by default (hunters examine only commits since the last completed review's head SHA; `/crysk review --full` widens to the full PR), and up to `max_verification_steps` verifier steps check whether prior open findings were fixed by the new push.
32
+
33
+ ## Review levels (what setup --ci asks)
34
+
35
+ `setup --ci` (and `ci init`) asks for a level and always writes its keys. An agent asks the human and passes `--level`, `--ci-mode`, `--billing`, `--max-changed-lines` and `--budget-usd`; a terminal user gets the same questions from the CLI; with neither, `balanced` and `gate` apply and the summary says nobody chose them.
36
+
37
+ | Level | `ci_review_policy` | `ci_max_attempts` | `ci_rereview_min_score` | `max_verification_steps` |
38
+ |---|---|---|---|---|
39
+ | `minimal` | `once_per_pr` | 1 | (unset) | 8 |
40
+ | `balanced` (default) | `risk_aware` | 2 | 4 | 8 |
41
+ | `thorough` | `every_push` | 4 | (unset) | 8 |
42
+ | `manual` | `manual_only` | 1 | (unset) | 8 |
43
+
44
+ Billing: `--billing subscription` writes no `budget-usd` (a subscription spends quota, not dollars, and CI applies no ceiling while the repo has neither `ANTHROPIC_API_KEY` nor `OPENCODE_AUTH_JSON`, either of which makes the route metered; an explicit 0 would warn on every run and outlive a later API key); `--billing api` writes `--budget-usd` or the $10 default. `--budget-usd` alone implies `api`, and `--budget-usd` with `subscription` is refused.
45
+
46
+ Re-runs: a group (the level's keys, or `max_changed_lines`) is overwritten only when someone chose it this run (a flag or a terminal answer); otherwise it fills the file only if absent, and setup prints `Changed` and `Kept existing` lines. A `--force` refresh keeps the old workflow's `mode` and `budget-usd` unless a flag names them, and in a terminal every question defaults to the current value (a tuned level that matches no preset gets a "Keep current settings" option).
47
+
48
+ Size threshold: `max_changed_lines` is always written (default 4000, `--max-changed-lines`, `0` = no limit). Unlike the budget it applies on any billing: left unset, a subscription route reviews a PR of any size.
49
+
50
+ Posting floor: setup writes `post_min_severity: "warning"` only when the repo config has no value, so a re-run never replaces a chosen floor. `warning` hides advisory suggestions, `blocking` hides every advisory finding, `suggestion` (or unset) posts everything. Hidden findings are counted in the summary comment. The gate is unchanged, since a blocking finding always posts; admission scores only posted findings, so a hidden one never triggers a re-review.
51
+
52
+ ## Policy modes
53
+
54
+ | Mode | Use when |
55
+ |---|---|
56
+ | `risk_aware` | Default — re-review on risky delta OR score ≥ floor |
57
+ | `thresholded` | Score-only; ignore path risk classification |
58
+ | `once_per_pr` | One automatic review; later pushes reported as not reviewed |
59
+ | `every_push` | Review every push (still capped by `ci_max_attempts`) |
60
+ | `manual_only` | No automatic re-review; operator override only |
61
+
62
+ ## Outcomes users see
63
+
64
+ | Outcome | Meaning |
65
+ |---|---|
66
+ | Review runs | Normal pipeline |
67
+ | **Skipped** | Push did not justify spend (same head, low score, docs-only delta, etc.) — **not** “clean” |
68
+ | **Automatic reviews done** | Budget exhausted or `manual_only` — the gate keeps the last verdict, answered findings turn a red green (marked unverified), and `/crysk review` runs another round |
69
+
70
+ Skipped and automatic-reviews-done posts include admission metadata in the step summary. The automatic-reviews-done
71
+ comment explains the end of the budget by the repository's rules (policy, attempts used, last reviewed head) and how to
72
+ ask for more rounds.
73
+
74
+ ## Durable ledger
75
+
76
+ - Check Runs named `crysk/ci-admission` on the reviewed commit (`pr-hero/ci-admission` on a commit first reviewed by an older release; both are read).
77
+ - Requires workflow permission **`checks: write`** (template includes it).
78
+ - Requires **`actions: read`** too: the gate lists this workflow's past runs, which a private repo refuses without it (HTTP 403).
79
+ - PR comments are presentation. The ledger counts a run that reached the provider (completed, failed, or still provider-started) and an admission skip. It does not count a run that yielded to an in-flight review, a size or budget gate skip, or a cancelled row (#164). A workflow run that concluded success or failure is dropped from the attempt count only when every ledger row on its head is a gate skip or a yield, because both are written before any provider spend. A cancelled row is not that proof: the signal handler that writes it can run after the provider started, so a run killed by `timeout-minutes` (concluded `failure`) still counts. A run whose row is still `reserved` stays counted too, because the provider-started write is best-effort and the run may have spent anyway.
80
+
81
+ ## Rollout (recommended)
82
+
83
+ 1. Ship workflow + secrets first.
84
+ 2. Add `.crysk/config.json` with `"ci_admission_observe_only": true`.
85
+ 3. Open a test PR; read `::notice::` lines for would-be skip/manual decisions.
86
+ 4. Set `ci_admission_observe_only` to `false` when behavior matches intent.
87
+
88
+ ## Example config
89
+
90
+ ```json
91
+ {
92
+ "ci_review_policy": "risk_aware",
93
+ "ci_max_attempts": 2,
94
+ "ci_rereview_min_score": 4,
95
+ "ci_blocking_weight": 2,
96
+ "ci_advisory_weight": 1,
97
+ "ci_trusted_actors": [],
98
+ "ci_admission_observe_only": true
99
+ }
100
+ ```
101
+
102
+ ## Manual override
103
+
104
+ Comment `/crysk review` on the pull request. GitHub Actions runs the review with `--force`. Posting the comment does not review anything on the machine that sends it:
105
+
106
+ ```bash
107
+ gh pr comment <n> --body "/crysk review"
108
+ ```
109
+
110
+ `/crysk review --full` also re-discovers the whole range. The comment must be exactly one of those two, and it 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 on the default branch.
111
+
112
+ It bypasses the size gate, the admission rules (same commit, `once_per_pr`, score, low-risk delta, exhausted attempts, `manual_only`), and the budget ceiling. It does not reset the ledger.
113
+
114
+ Who can force: anyone with write access to the repository; a comment from anyone else is refused. A fork PR is reviewed only this way, since its own pushes are skipped. `gh run rerun` on a skipped run re-evaluates the gates and does not force.
115
+
116
+ A workflow scaffolded before the comment trigger has no `issue_comment` listener. There, use the legacy `gh workflow run pr-hero-force.yml -f pr=<n>`, or re-scaffold with `crysk ci init --force`.
117
+
118
+ A local agent posts the comment. It does not run `crysk review --pr <n> --force` when the review should happen in CI.
119
+
120
+ A red gate with blocking findings that the team accepts is unlocked by commenting exactly `/crysk override` on the pull request, not by `/crysk review`. In gate mode a same-head review re-runs the same blocking count and leaves the `failure` in place, so the gate clears only when a pushed fix is verified gone or the override is posted:
121
+
122
+ ```bash
123
+ gh pr comment <n> --body "/crysk override"
124
+ ```
125
+
126
+ The override sets the `crysk` status on that head to `success` with no review, no spend, and no credential, and only a user with write or admin access may post it. Each override is recorded: the status names who acted, and a `<!-- crysk-override` comment names who, which head, and when. It is valid only for the head it names, so a new push or a later `/crysk review` on that head replaces it, and it works only on pull requests from this repository, never on forks.
@@ -0,0 +1,128 @@
1
+ # CI review admission — setup reference
2
+
3
+ Read this when configuring `.crysk/config.json` during CI setup. Full operator docs:
4
+ `docs/github-actions.md` (section **CI review admission**).
5
+
6
+ ## Where config lives
7
+
8
+ - **Repository** `.crysk/config.json` on the default branch — authoritative.
9
+ - NOT in the PR branch worktree. Authors cannot change admission to suppress their own PR.
10
+ - Verify with `crysk config` after editing.
11
+
12
+ ## Keys and defaults
13
+
14
+ | Key | Default | Meaning |
15
+ |---|---|---|
16
+ | `ci_review_policy` | `risk_aware` | When to spend on `synchronize` pushes |
17
+ | `ci_max_attempts` | `2` | Automatic attempt budget per PR |
18
+ | `ci_rereview_min_score` | `4` | Prior score floor for re-review |
19
+ | `ci_blocking_weight` | `2` | Score weight per blocking-tier finding |
20
+ | `ci_advisory_weight` | `1` | Score weight per advisory-tier finding |
21
+ | `ci_trusted_actors` | `[]` | Extra GitHub logins for authoritative markers (+ `GITHUB_ACTOR`) |
22
+ | `ci_admission_observe_only` | `false` | Log would-be skip/manual decisions but always run |
23
+ | `max_verification_steps` | `8` | Max prior open findings verified per re-review (`0` pauses verification; capped key) |
24
+
25
+ `ci_max_reviews` is legacy — use `ci_max_attempts` (same fallback).
26
+
27
+ **Score:** `blocking × ci_blocking_weight + advisory × ci_advisory_weight`
28
+
29
+ **How a re-review depends on the previous pass:**
30
+ - **Whether it runs (admission):** in `risk_aware` and `thresholded` modes, the previous review's finding score (`blocking × 2 + advisory × 1` by default) is compared against `ci_rereview_min_score`, bounded by `ci_max_attempts` total automatic passes per PR.
31
+ - **What it does when it runs:** discovery is incremental by default (hunters examine only commits since the last completed review's head SHA; `/crysk review --full` widens to the full PR), and up to `max_verification_steps` verifier steps check whether prior open findings were fixed by the new push.
32
+
33
+ ## Review levels (what setup --ci asks)
34
+
35
+ `setup --ci` (and `ci init`) asks for a level and always writes its keys. An agent asks the human and passes `--level`, `--ci-mode`, `--billing`, `--max-changed-lines` and `--budget-usd`; a terminal user gets the same questions from the CLI; with neither, `balanced` and `gate` apply and the summary says nobody chose them.
36
+
37
+ | Level | `ci_review_policy` | `ci_max_attempts` | `ci_rereview_min_score` | `max_verification_steps` |
38
+ |---|---|---|---|---|
39
+ | `minimal` | `once_per_pr` | 1 | (unset) | 8 |
40
+ | `balanced` (default) | `risk_aware` | 2 | 4 | 8 |
41
+ | `thorough` | `every_push` | 4 | (unset) | 8 |
42
+ | `manual` | `manual_only` | 1 | (unset) | 8 |
43
+
44
+ Billing: `--billing subscription` writes no `budget-usd` (a subscription spends quota, not dollars, and CI applies no ceiling while the repo has neither `ANTHROPIC_API_KEY` nor `OPENCODE_AUTH_JSON`, either of which makes the route metered; an explicit 0 would warn on every run and outlive a later API key); `--billing api` writes `--budget-usd` or the $10 default. `--budget-usd` alone implies `api`, and `--budget-usd` with `subscription` is refused.
45
+
46
+ Re-runs: a group (the level's keys, or `max_changed_lines`) is overwritten only when someone chose it this run (a flag or a terminal answer); otherwise it fills the file only if absent, and setup prints `Changed` and `Kept existing` lines. A `--force` refresh keeps the old workflow's `mode` and `budget-usd` unless a flag names them, and in a terminal every question defaults to the current value (a tuned level that matches no preset gets a "Keep current settings" option).
47
+
48
+ Size threshold: `max_changed_lines` is always written (default 4000, `--max-changed-lines`, `0` = no limit). Unlike the budget it applies on any billing: left unset, a subscription route reviews a PR of any size.
49
+
50
+ Posting floor: setup writes `post_min_severity: "warning"` only when the repo config has no value, so a re-run never replaces a chosen floor. `warning` hides advisory suggestions, `blocking` hides every advisory finding, `suggestion` (or unset) posts everything. Hidden findings are counted in the summary comment. The gate is unchanged, since a blocking finding always posts; admission scores only posted findings, so a hidden one never triggers a re-review.
51
+
52
+ Materiality gate: `materiality_gate: true` (opt-in; setup never writes it) sends each blocking finding the safety guard does not protect to an isolated sonnet judge (no tools, no MCP, PR title + claim + a ±25-line code window as untrusted data) that applies Crysk's written posting policy. An `immaterial` verdict demotes the finding to advisory with the reason in its comment, so the gate stops counting it; with `post_min_severity: "blocking"` it is not posted at all. Findings about security, credentials, permissions, sandboxing, injection or data loss are never sent and never demoted, including when consolidation merged them into another finding. Any failure (spawn, parse, unsafe input, unsupported route, ceiling) leaves the finding blocking. The key is capped: a global config can turn it off for every repo. Every run's `pipeline.json` carries a `materiality` record (`status`, `judged`, `demoted`, `protected`). Known limit: a finding that blocked on an earlier push still counts toward the gate on a re-review, so the effect shows mostly on first reviews and on new findings in later rounds.
53
+
54
+ ## Policy modes
55
+
56
+ | Mode | Use when |
57
+ |---|---|
58
+ | `risk_aware` | Default — re-review on risky delta OR score ≥ floor |
59
+ | `thresholded` | Score-only; ignore path risk classification |
60
+ | `once_per_pr` | One automatic review; later pushes reported as not reviewed |
61
+ | `every_push` | Review every push (still capped by `ci_max_attempts`) |
62
+ | `manual_only` | No automatic re-review; operator override only |
63
+
64
+ ## Outcomes users see
65
+
66
+ | Outcome | Meaning |
67
+ |---|---|
68
+ | Review runs | Normal pipeline |
69
+ | **Skipped** | Push did not justify spend (same head, low score, docs-only delta, etc.) — **not** “clean” |
70
+ | **Automatic reviews done** | Budget exhausted or `manual_only` — the gate keeps the last verdict, answered findings turn a red green (marked unverified), and `/crysk review` runs another round |
71
+
72
+ Skipped and automatic-reviews-done posts include admission metadata in the step summary. The automatic-reviews-done
73
+ comment explains the end of the budget by the repository's rules (policy, attempts used, last reviewed head) and how to
74
+ ask for more rounds.
75
+
76
+ ## Durable ledger
77
+
78
+ - Check Runs named `crysk/ci-admission` on the reviewed commit (`pr-hero/ci-admission` on a commit first reviewed by an older release; both are read).
79
+ - Requires workflow permission **`checks: write`** (template includes it).
80
+ - Requires **`actions: read`** too: the gate lists this workflow's past runs, which a private repo refuses without it (HTTP 403).
81
+ - PR comments are presentation. The ledger counts a run that reached the provider (completed, failed, or still provider-started) and an admission skip. It does not count a run that yielded to an in-flight review, a size or budget gate skip, or a cancelled row (#164). A workflow run that concluded success or failure is dropped from the attempt count only when every ledger row on its head is a gate skip or a yield, because both are written before any provider spend. A cancelled row is not that proof: the signal handler that writes it can run after the provider started, so a run killed by `timeout-minutes` (concluded `failure`) still counts. A run whose row is still `reserved` stays counted too, because the provider-started write is best-effort and the run may have spent anyway.
82
+
83
+ ## Rollout (recommended)
84
+
85
+ 1. Ship workflow + secrets first.
86
+ 2. Add `.crysk/config.json` with `"ci_admission_observe_only": true`.
87
+ 3. Open a test PR; read `::notice::` lines for would-be skip/manual decisions.
88
+ 4. Set `ci_admission_observe_only` to `false` when behavior matches intent.
89
+
90
+ ## Example config
91
+
92
+ ```json
93
+ {
94
+ "ci_review_policy": "risk_aware",
95
+ "ci_max_attempts": 2,
96
+ "ci_rereview_min_score": 4,
97
+ "ci_blocking_weight": 2,
98
+ "ci_advisory_weight": 1,
99
+ "ci_trusted_actors": [],
100
+ "ci_admission_observe_only": true
101
+ }
102
+ ```
103
+
104
+ ## Manual override
105
+
106
+ Comment `/crysk review` on the pull request. GitHub Actions runs the review with `--force`. Posting the comment does not review anything on the machine that sends it:
107
+
108
+ ```bash
109
+ gh pr comment <n> --body "/crysk review"
110
+ ```
111
+
112
+ `/crysk review --full` also re-discovers the whole range. The comment must be exactly one of those two, and it 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 on the default branch.
113
+
114
+ It bypasses the size gate, the admission rules (same commit, `once_per_pr`, score, low-risk delta, exhausted attempts, `manual_only`), and the budget ceiling. It does not reset the ledger.
115
+
116
+ Who can force: anyone with write access to the repository; a comment from anyone else is refused. A fork PR is reviewed only this way, since its own pushes are skipped. `gh run rerun` on a skipped run re-evaluates the gates and does not force.
117
+
118
+ A workflow scaffolded before the comment trigger has no `issue_comment` listener. There, use the legacy `gh workflow run pr-hero-force.yml -f pr=<n>`, or re-scaffold with `crysk ci init --force`.
119
+
120
+ A local agent posts the comment. It does not run `crysk review --pr <n> --force` when the review should happen in CI.
121
+
122
+ A red gate with blocking findings that the team accepts is unlocked by commenting exactly `/crysk override` on the pull request, not by `/crysk review`. In gate mode a same-head review re-runs the same blocking count and leaves the `failure` in place, so the gate clears only when a pushed fix is verified gone or the override is posted:
123
+
124
+ ```bash
125
+ gh pr comment <n> --body "/crysk override"
126
+ ```
127
+
128
+ The override sets the `crysk` status on that head to `success` with no review, no spend, and no credential, and only a user with write or admin access may post it. Each override is recorded: the status names who acted, and a `<!-- crysk-override` comment names who, which head, and when. It is valid only for the head it names, so a new push or a later `/crysk review` on that head replaces it, and it works only on pull requests from this repository, never on forks.
@@ -0,0 +1,126 @@
1
+ # CI review admission — setup reference
2
+
3
+ Read this when configuring `.crysk/config.json` during CI setup. Full operator docs:
4
+ `docs/github-actions.md` (section **CI review admission**).
5
+
6
+ ## Where config lives
7
+
8
+ - **Repository** `.crysk/config.json` on the default branch — authoritative.
9
+ - NOT in the PR branch worktree. Authors cannot change admission to suppress their own PR.
10
+ - Verify with `crysk config` after editing.
11
+
12
+ ## Keys and defaults
13
+
14
+ | Key | Default | Meaning |
15
+ |---|---|---|
16
+ | `ci_review_policy` | `risk_aware` | When to spend on `synchronize` pushes |
17
+ | `ci_max_attempts` | `2` | Automatic attempt budget per PR |
18
+ | `ci_rereview_min_score` | `4` | Prior score floor for re-review |
19
+ | `ci_blocking_weight` | `2` | Score weight per blocking-tier finding |
20
+ | `ci_advisory_weight` | `1` | Score weight per advisory-tier finding |
21
+ | `ci_trusted_actors` | `[]` | Extra GitHub logins for authoritative markers (+ `GITHUB_ACTOR`) |
22
+ | `ci_admission_observe_only` | `false` | Log would-be skip/manual decisions but always run |
23
+ | `max_verification_steps` | `8` | Max prior open findings verified per re-review (`0` pauses verification; capped key) |
24
+
25
+ `ci_max_reviews` is legacy — use `ci_max_attempts` (same fallback).
26
+
27
+ **Score:** `blocking × ci_blocking_weight + advisory × ci_advisory_weight`
28
+
29
+ **How a re-review depends on the previous pass:**
30
+ - **Whether it runs (admission):** in `risk_aware` and `thresholded` modes, the previous review's finding score (`blocking × 2 + advisory × 1` by default) is compared against `ci_rereview_min_score`, bounded by `ci_max_attempts` total automatic passes per PR.
31
+ - **What it does when it runs:** discovery is incremental by default (hunters examine only commits since the last completed review's head SHA; `/crysk review --full` widens to the full PR), and up to `max_verification_steps` verifier steps check whether prior open findings were fixed by the new push.
32
+
33
+ ## Review levels (what setup --ci asks)
34
+
35
+ `setup --ci` (and `ci init`) asks for a level and always writes its keys. An agent asks the human and passes `--level`, `--ci-mode`, `--billing`, `--max-changed-lines` and `--budget-usd`; a terminal user gets the same questions from the CLI; with neither, `balanced` and `gate` apply and the summary says nobody chose them.
36
+
37
+ | Level | `ci_review_policy` | `ci_max_attempts` | `ci_rereview_min_score` | `max_verification_steps` |
38
+ |---|---|---|---|---|
39
+ | `minimal` | `once_per_pr` | 1 | (unset) | 8 |
40
+ | `balanced` (default) | `risk_aware` | 2 | 4 | 8 |
41
+ | `thorough` | `every_push` | 4 | (unset) | 8 |
42
+ | `manual` | `manual_only` | 1 | (unset) | 8 |
43
+
44
+ Billing: `--billing subscription` writes no `budget-usd` (a subscription spends quota, not dollars, and CI applies no ceiling while the repo has neither `ANTHROPIC_API_KEY` nor `OPENCODE_AUTH_JSON`, either of which makes the route metered; an explicit 0 would warn on every run and outlive a later API key); `--billing api` writes `--budget-usd` or the $10 default. `--budget-usd` alone implies `api`, and `--budget-usd` with `subscription` is refused.
45
+
46
+ Re-runs: a group (the level's keys, or `max_changed_lines`) is overwritten only when someone chose it this run (a flag or a terminal answer); otherwise it fills the file only if absent, and setup prints `Changed` and `Kept existing` lines. A `--force` refresh keeps the old workflow's `mode` and `budget-usd` unless a flag names them, and in a terminal every question defaults to the current value (a tuned level that matches no preset gets a "Keep current settings" option).
47
+
48
+ Size threshold: `max_changed_lines` is always written (default 4000, `--max-changed-lines`, `0` = no limit). Unlike the budget it applies on any billing: left unset, a subscription route reviews a PR of any size.
49
+
50
+ Posting floor: setup writes `post_min_severity: "warning"` only when the repo config has no value, so a re-run never replaces a chosen floor. `warning` hides advisory suggestions, `blocking` hides every advisory finding, `suggestion` (or unset) posts everything. Hidden findings are counted in the summary comment; the gate and admission still count every finding.
51
+
52
+ ## Policy modes
53
+
54
+ | Mode | Use when |
55
+ |---|---|
56
+ | `risk_aware` | Default — re-review on risky delta OR score ≥ floor |
57
+ | `thresholded` | Score-only; ignore path risk classification |
58
+ | `once_per_pr` | One automatic review; later pushes reported as not reviewed |
59
+ | `every_push` | Review every push (still capped by `ci_max_attempts`) |
60
+ | `manual_only` | No automatic re-review; operator override only |
61
+
62
+ ## Outcomes users see
63
+
64
+ | Outcome | Meaning |
65
+ |---|---|
66
+ | Review runs | Normal pipeline |
67
+ | **Skipped** | Push did not justify spend (same head, low score, docs-only delta, etc.) — **not** “clean” |
68
+ | **Automatic reviews done** | Budget exhausted or `manual_only` — the gate keeps the last verdict, answered findings turn a red green (marked unverified), and `/crysk review` runs another round |
69
+
70
+ Skipped and automatic-reviews-done posts include admission metadata in the step summary. The automatic-reviews-done
71
+ comment explains the end of the budget by the repository's rules (policy, attempts used, last reviewed head) and how to
72
+ ask for more rounds.
73
+
74
+ ## Durable ledger
75
+
76
+ - Check Runs named `crysk/ci-admission` on the reviewed commit (`pr-hero/ci-admission` on a commit first reviewed by an older release; both are read).
77
+ - Requires workflow permission **`checks: write`** (template includes it).
78
+ - Requires **`actions: read`** too: the gate lists this workflow's past runs, which a private repo refuses without it (HTTP 403).
79
+ - PR comments are presentation. The ledger counts a run that reached the provider (completed, failed, or still provider-started) and an admission skip. It does not count a run that yielded to an in-flight review, a size or budget gate skip, or a cancelled row (#164). A workflow run that concluded success or failure is dropped from the attempt count only when every ledger row on its head is a gate skip or a yield, because both are written before any provider spend. A cancelled row is not that proof: the signal handler that writes it can run after the provider started, so a run killed by `timeout-minutes` (concluded `failure`) still counts. A run whose row is still `reserved` stays counted too, because the provider-started write is best-effort and the run may have spent anyway.
80
+
81
+ ## Rollout (recommended)
82
+
83
+ 1. Ship workflow + secrets first.
84
+ 2. Add `.crysk/config.json` with `"ci_admission_observe_only": true`.
85
+ 3. Open a test PR; read `::notice::` lines for would-be skip/manual decisions.
86
+ 4. Set `ci_admission_observe_only` to `false` when behavior matches intent.
87
+
88
+ ## Example config
89
+
90
+ ```json
91
+ {
92
+ "ci_review_policy": "risk_aware",
93
+ "ci_max_attempts": 2,
94
+ "ci_rereview_min_score": 4,
95
+ "ci_blocking_weight": 2,
96
+ "ci_advisory_weight": 1,
97
+ "ci_trusted_actors": [],
98
+ "ci_admission_observe_only": true
99
+ }
100
+ ```
101
+
102
+ ## Manual override
103
+
104
+ Comment `/crysk review` on the pull request. GitHub Actions runs the review with `--force`. Posting the comment does not review anything on the machine that sends it:
105
+
106
+ ```bash
107
+ gh pr comment <n> --body "/crysk review"
108
+ ```
109
+
110
+ `/crysk review --full` also re-discovers the whole range. The comment must be exactly one of those two, and it 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 on the default branch.
111
+
112
+ It bypasses the size gate, the admission rules (same commit, `once_per_pr`, score, low-risk delta, exhausted attempts, `manual_only`), and the budget ceiling. It does not reset the ledger.
113
+
114
+ Who can force: anyone with write access to the repository; a comment from anyone else is refused. A fork PR is reviewed only this way, since its own pushes are skipped. `gh run rerun` on a skipped run re-evaluates the gates and does not force.
115
+
116
+ A workflow scaffolded before the comment trigger has no `issue_comment` listener. There, use the legacy `gh workflow run pr-hero-force.yml -f pr=<n>`, or re-scaffold with `crysk ci init --force`.
117
+
118
+ A local agent posts the comment. It does not run `crysk review --pr <n> --force` when the review should happen in CI.
119
+
120
+ A red gate with blocking findings that the team accepts is unlocked by commenting exactly `/crysk override` on the pull request, not by `/crysk review`. In gate mode a same-head review re-runs the same blocking count and leaves the `failure` in place, so the gate clears only when a pushed fix is verified gone or the override is posted:
121
+
122
+ ```bash
123
+ gh pr comment <n> --body "/crysk override"
124
+ ```
125
+
126
+ The override sets the `crysk` status on that head to `success` with no review, no spend, and no credential, and only a user with write or admin access may post it. Each override is recorded: the status names who acted, and a `<!-- crysk-override` comment names who, which head, and when. It is valid only for the head it names, so a new push or a later `/crysk review` on that head replaces it, and it works only on pull requests from this repository, never on forks.