crysk 0.3.3 → 0.5.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 +26 -17
- package/config/models/anthropic.json +1 -1
- package/dist/SKILL-dsnffnfp.md +140 -0
- package/dist/SKILL-gnrbph72.md +140 -0
- package/dist/SKILL-k4k0zn1w.md +143 -0
- package/dist/SKILL-kq0xejn3.md +553 -0
- package/dist/SKILL-qaqsbygw.md +66 -0
- package/dist/SKILL-vhb4c3vv.md +553 -0
- package/dist/SKILL-vws0aqb8.md +553 -0
- package/dist/SKILL-xpf6kmdw.md +74 -0
- package/dist/ci-admission-0ken6ehx.md +128 -0
- package/dist/ci-admission-t0f5qwth.md +128 -0
- package/dist/cli.js +3366 -1680
- package/dist/index.js +1884 -947
- package/dist/opencode-ci-ac5zksdn.md +106 -0
- package/dist/workflow-4pkyck01.yml +160 -0
- package/package.json +2 -2
- package/prompts/default/PROVENANCE.md +1 -0
- package/skills/crysk/SKILL.md +16 -16
- package/skills/crysk-ci-setup/SKILL.md +42 -39
- package/skills/crysk-ci-setup/assets/workflow.yml +31 -22
- package/skills/crysk-ci-setup/references/ci-admission.md +2 -2
- package/skills/crysk-ci-setup/references/opencode-ci.md +53 -88
- package/skills/crysk-loop/SKILL.md +20 -9
- package/skills/crysk-pr/SKILL.md +1 -1
- package/src/asset-manifest.ts +0 -4
- package/src/assets.ts +2 -2
- package/src/ci/admission-ledger.ts +4 -0
- package/src/ci/classify-error.ts +21 -24
- package/src/ci/cli-record.ts +53 -1
- package/src/ci/crysk-secrets.ts +409 -0
- package/src/ci/gates.ts +31 -42
- package/src/ci/outcome.ts +421 -330
- package/src/ci/platform-config.ts +127 -0
- package/src/ci/platform-report.ts +935 -0
- package/src/ci/platform-trace.ts +551 -0
- package/src/ci/platform.ts +465 -0
- package/src/ci/publish.ts +19 -6
- package/src/ci/reporter.ts +9 -7
- package/src/ci/review-admission.ts +8 -4
- package/src/ci/review-levels.ts +8 -7
- package/src/ci/run.ts +88 -0
- package/src/ci/setup.ts +547 -109
- package/src/ci/trace-bundle.ts +1282 -0
- package/src/ci/trace-transcripts.ts +415 -0
- package/src/ci/trigger.ts +176 -33
- package/src/cli.ts +11 -3
- package/src/commands/ci-setup-questions.ts +3 -3
- package/src/commands/ci-setup.ts +152 -6
- package/src/commands/config.ts +3 -0
- package/src/commands/doctor.ts +15 -6
- package/src/compare/loop.ts +9 -1
- package/src/compare/martian-adapter.ts +1 -1
- package/src/config/config.ts +16 -3
- package/src/diversity/clustering.ts +0 -1
- package/src/diversity/identity.ts +4 -5
- package/src/diversity/pipeline-integration.ts +1 -9
- package/src/doctor.ts +3 -3
- package/src/execution/attempt-evidence.ts +10 -5
- package/src/execution/claude-session-trace.ts +480 -0
- package/src/execution/contracts.ts +21 -4
- package/src/execution/harness.ts +105 -8
- package/src/execution/model-fallback.ts +239 -0
- package/src/execution/usage-normalized.ts +6 -4
- package/src/home-preflight.ts +1 -1
- package/src/index.ts +1 -1
- package/src/model/catalog.ts +13 -37
- package/src/model/free-discovery.ts +117 -8
- package/src/model/model-name.ts +404 -0
- package/src/model/provider-capabilities.ts +22 -7
- package/src/model/routing.ts +346 -467
- package/src/pr/admission.ts +71 -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/plan.ts +20 -4
- 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 +44 -2
- package/src/pr/publish-outcome.ts +11 -3
- package/src/pr/review-pr.ts +20 -4
- package/src/pr/target.ts +12 -3
- package/src/production-runtime.ts +760 -331
- package/src/rereview/classify.ts +4 -0
- package/src/rereview/prepare.ts +47 -22
- package/src/rereview/state.ts +34 -8
- package/src/review/pipeline.ts +277 -101
- package/src/review/preflight.ts +201 -294
- package/src/review/report.ts +60 -40
- package/src/review/review.ts +20 -3
- package/src/review/route-preflight.ts +79 -11
- package/src/review/run.ts +28 -6
- package/src/review/scout.ts +1 -1
- package/src/review/spec.ts +3 -3
- package/src/review/step-runner.ts +70 -1
- package/src/runner-authority.ts +127 -9
- package/src/security/binding-policy.ts +1 -2
- package/src/security/claude-credential.ts +355 -0
- package/src/security/credential-broker.ts +56 -40
- package/src/security/evidence-redaction.ts +179 -4
- package/src/security/opencode-secret-manifest.ts +114 -0
- package/src/security/published-text.ts +161 -0
- package/src/security/redact.ts +45 -0
- package/src/system-tools.ts +48 -21
- package/src/transport-registry.ts +12 -2
- package/src/transports/claude-code-cli.ts +21 -2
- package/src/transports/opencode-sdk.ts +11 -9
- package/src/transports/opencode-server.ts +7 -10
- package/src/triage/triage.ts +2 -1
- package/src/ui/config-edit.ts +9 -20
- package/src/ui/config.ts +32 -27
- package/src/ui/plan.ts +76 -47
- package/src/updater.ts +10 -7
- package/prompts/default/deep-review-lifecycle.md +0 -362
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: crysk
|
|
3
|
+
description: "Trigger: use or configure Crysk locally — change the review model or backend per role (models, fallback models, OpenCode, DeepSeek, custom model), effort, credentials order, config.json keys, REVIEW.md / gotchas.md, .cryskignore, size gate, run a review, `crysk watch/gc`, `crysk doctor/config`. Not CI (crysk-ci-setup) and not answering findings (crysk-loop)."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: juanmaagd
|
|
7
|
+
version: "1.0"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Activation Contract
|
|
11
|
+
|
|
12
|
+
Load when the user wants to **operate or configure Crysk on their machine or repo**:
|
|
13
|
+
- Change which model or backend a step runs on (per role, with fallbacks: OpenCode, DeepSeek, a pinned Claude version).
|
|
14
|
+
- Tune effort, caps, the size gate, `.cryskignore`, `REVIEW.md` / `gotchas.md`, or any `config.json` key.
|
|
15
|
+
- Run a review (local branch or `--pr <n>`), understand its cost, or read its artifacts.
|
|
16
|
+
- Set up the watcher (`crysk watch`) or worktree GC (`crysk gc`).
|
|
17
|
+
- Diagnose a broken install or a refused run (`crysk doctor`, `crysk config`).
|
|
18
|
+
|
|
19
|
+
Route away: GitHub Actions, `CRYSK_*` secrets, `CRYSK_MODELS`, `/crysk review` comments → load `crysk-ci-setup`. Replying to posted `<!-- crysk-finding` comments → load `crysk-loop`.
|
|
20
|
+
|
|
21
|
+
## Source of Truth
|
|
22
|
+
|
|
23
|
+
This skill holds the mental model and the traps, not the reference. Before acting, read the live state, and for detail follow the linked section — do not answer from memory:
|
|
24
|
+
- `crysk config` — every key, its effective value, and **which layer decided it**. Read-only, $0.
|
|
25
|
+
- `crysk --help` — the installed version's real commands and flags.
|
|
26
|
+
- The docs on GitHub (they are not shipped in the npm package): [README](https://github.com/cryskai/crysk/blob/main/README.md), [configuration.md](https://github.com/cryskai/crysk/blob/main/docs/configuration.md).
|
|
27
|
+
|
|
28
|
+
If Crysk is not on `PATH`, run every command as `npx -y crysk <command>` (Node is enough). An install from before the rename (the package used to be `pr-hero`) still answers to `pr-hero`; either command is the same program.
|
|
29
|
+
|
|
30
|
+
## Mental Model
|
|
31
|
+
|
|
32
|
+
- **Two config files, owned by different people.** `~/.crysk/config.json` is the person's (never committed; `~/.prhero/config.json` on an install from before the rename — never create `~/.crysk` by hand while `~/.prhero` is in use, the CLI would switch homes); `<repo>/.crysk/config.json` is the team's (committed). `~/.crysk/watch.json` holds the watcher.
|
|
33
|
+
- **The one rule:** the repo file beats the global one, **except on capped keys** (`max_*`, and the on/off switches `summary.enabled`, `scout`, `materiality_gate`, `post`): there the team can only ask for *less*, so a committed file never enlarges a person's bill.
|
|
34
|
+
- **Some keys live in exactly one layer** and the parser refuses the other by name: `models` and `credentials` are person-only; `default_base`, `parity_trigger_paths`, `suspicion_priors` are repo-only. `--config <file>` replaces the repo layer only.
|
|
35
|
+
- **Flags always win**, and may exceed a cap (`--base`, `--agents`, `--model`, `--summary`/`--no-summary`, `--force`).
|
|
36
|
+
- **Models are assigned per role.** `models` maps a role (`default`, `hunter.<key>` per hunter, `refuter`, which also covers the re-review verifier and the CI adjudicator, `consolidate`, `scout`, `summary`, `judge`) to a list of one to three models tried in order; a role not listed uses `default`. With no `models`, each step runs its prompt's model: hunters, consolidation and scout `claude:sonnet-latest`, the refuter `claude:opus-latest`, the summarizer `claude:haiku-latest`. A model name carries its backend: `claude:<sonnet|opus|haiku|fable>-latest` (newest version), `claude:claude-…` (pinned), `opencode:<provider>/<model>`. The old `routing` key is gone and refused with the `models` form to write; `summary.model` is gone too (`"haiku"`, which `crysk init` used to write, still reads with a warning).
|
|
37
|
+
- **Crysk never stores a credential.** It reads the Claude CLI's login, `CRYSK_CLAUDE_*` (or `ANTHROPIC_API_KEY` / `CLAUDE_CODE_OAUTH_TOKEN`) variables, or OpenCode's `auth.json`, and projects an ephemeral copy into each step. A run uses one Claude credential, the first set in `credentials.claude` (default `["subscription", "api_key"]`).
|
|
38
|
+
|
|
39
|
+
## Hard Rules
|
|
40
|
+
|
|
41
|
+
- **Never print, `cat`, commit, or log credentials** — Keychain records, API keys, or `auth.json` contents. Inspect `auth.json` provider **keys and `type` only**.
|
|
42
|
+
- **Read before writing, verify after:** run `crysk config` before a change and again after it; finish with `crysk doctor`, and `crysk review --dry-run` when the change touches models or credentials.
|
|
43
|
+
- **Prefer the CLI to hand edits:** scalar keys go through `crysk config set|unset <key> <val> [--person|--team|--watch]` (or `crysk config --edit`). `models` and `credentials` are objects, so they are written by hand into `~/.crysk/config.json` — keep the file valid JSON and preserve every other key.
|
|
44
|
+
- **Never spend without consent:** a real `crysk review`, `crysk watch install` (starts automatic spending) or `--force` past the size gate runs only after the user confirms. `--dry-run` variants are free.
|
|
45
|
+
- **Never invent a model id.** The bundled catalog only knows the Claude aliases; an OpenCode model must be spelled exactly as `opencode models <provider>` lists it, and a typo fails at the provider, not at Crysk.
|
|
46
|
+
- **You cannot authenticate `claude` for the user.** If `doctor` reports it missing or unauthenticated, say so and stop.
|
|
47
|
+
|
|
48
|
+
## Recipes
|
|
49
|
+
|
|
50
|
+
**Models per role** — [Models](https://github.com/cryskai/crysk/blob/main/docs/configuration.md#models), [Fallback models](https://github.com/cryskai/crysk/blob/main/docs/configuration.md#fallback-models)
|
|
51
|
+
1. Ask: which roles to move (`default` for all, or `hunter.<key>`, `refuter`, `summary`, …), which model for each and which fallbacks, and whether metered spend is acceptable.
|
|
52
|
+
2. Write `models` in `~/.crysk/config.json` (or `~/.prhero/config.json` if that is the home in use), e.g. `{"models": {"default": ["opencode:deepseek/deepseek-v4-flash", "claude:sonnet-latest"], "refuter": ["claude:opus-latest"]}}`. Write `claude:sonnet-latest`, never a bare `claude:sonnet` (refused); a full `claude-*` id pins a version.
|
|
53
|
+
3. Traps: at most 3 models per role and none twice; a role not listed uses `default`, except the materiality judge, which runs only `claude:sonnet-latest` or `claude:opus-latest` and never inherits `default`; the next model is tried only on a provider failure (rate limit, quota, network, timeout, model unavailable; a refused login skips the models on the same credential), never on a bad answer; each fallback can bill and take the step's full time again. Several OpenCode providers may be mixed in one review. A local `auth.json` `openai` record must be `type: "oauth"` (the subscription); an `openai` API key there is refused.
|
|
54
|
+
4. Verify: `crysk config`, `crysk doctor`, then a **local** `crysk review --dry-run` (PR-mode dry-run returns before route admission, so it can look clean on a plan that will be refused).
|
|
55
|
+
|
|
56
|
+
**Effort** — [Effort](https://github.com/cryskai/crysk/blob/main/docs/configuration.md#effort): per model, as a `models` entry `{"model": "claude:opus-latest", "effort": "max"}`; otherwise the `effort:` frontmatter of a prompt in a custom `agents_dir`, then the role default (hunters `xhigh`, refuter `high`). Claude levels are `low|medium|high|xhigh|max` (`ultracode` is refused). On OpenCode the effort is the model's variant, as OpenCode names it; the review refuses, before spending, a variant `opencode models <provider> --verbose` does not list. The `#variant` suffix is gone. `models.judge` and `--model` take no effort.
|
|
57
|
+
|
|
58
|
+
**Credentials / billing** — [Credentials](https://github.com/cryskai/crysk/blob/main/docs/configuration.md#credentials): one Claude credential per run, the first set in `credentials.claude` (default `["subscription", "api_key"]`; on macOS a Claude login always counts as the subscription). To bill an API key with a login present, write `{"credentials": {"claude": ["api_key", "subscription"]}}`. The Claude child sees only the chosen one. For OpenCode on this machine, only an `openai` entry of `type: "oauth"` is a subscription; every other provider is a metered API token unless its catalog prices the model at $0.
|
|
59
|
+
|
|
60
|
+
**Caps, size gate, exclusions** — [config.json keys](https://github.com/cryskai/crysk/blob/main/README.md#configjson-keys), [size gate](https://github.com/cryskai/crysk/blob/main/README.md#the-size-gate--a-cost-gate-not-a-quality-gate), [.cryskignore](https://github.com/cryskai/crysk/blob/main/README.md#cryskignore--repo-defined-exclusions): `max_changed_lines`/`max_changed_files` skip oversized diffs (a cost gate, not a quality one); `max_concurrent_steps` keeps the fan-out under a provider's rate limit; `max_verification_steps` (default `8`, `0` pauses) caps how many prior open findings a re-review spawns verifier steps for. `post_min_severity` (`suggestion` | `warning` | `blocking`, unset posts everything; `setup --ci` writes `warning`) is the lowest finding a PR review posts: hidden findings get no comment and the summary counts them, the gate is unchanged (a blocking finding always posts), and re-review admission scores only what was posted. Only the repo-root `.cryskignore` is read, and matching is case-sensitive.
|
|
61
|
+
|
|
62
|
+
**REVIEW.md / gotchas.md** — [REVIEW.md and gotchas.md](https://github.com/cryskai/crysk/blob/main/README.md#reviewmd-and-gotchasmd): optional; a root `REVIEW.md` wins over `.crysk/gotchas.md`. A file that exists must be real: read the code and write the actual traps, then delete the `human-attention-required` marker line, or `review` and `doctor` refuse it. With neither file the review runs on the default guidance.
|
|
63
|
+
|
|
64
|
+
**Running a review** — [Commands](https://github.com/cryskai/crysk/blob/main/README.md#commands): `.crysk/` must be committed or gitignored (clean-tree gate). Expect roughly $2–5 and ~10 minutes per typical PR; the printed band ignores billing mode. Artifacts land in `~/.crysk/repos/<origin>/runs/<run>/`. To check or wait on a PR's CI review state deterministically ($0, via `gh`), run `pr-hero status --pr <n> [--wait] [--json]`.
|
|
65
|
+
|
|
66
|
+
**Watcher / GC** — [crysk watch](https://github.com/cryskai/crysk/blob/main/README.md#watching-prs-automatically--crysk-watch): `watch add [--post]`, preview with `watch --once --dry-run`, and only then `watch install`. `daily_cap` and `window` live in `~/.crysk/watch.json`. GC is separate: `crysk gc install`.
|
|
67
|
+
|
|
68
|
+
## Output Contract
|
|
69
|
+
|
|
70
|
+
Report back to the user:
|
|
71
|
+
1. What changed: the file and layer, and the keys touched (never credential values).
|
|
72
|
+
2. The `crysk config` lines proving the new effective value and its layer.
|
|
73
|
+
3. `doctor` / `--dry-run` result, and whether the next real run is subscription, metered, or free.
|
|
74
|
+
4. Anything left for the human: authenticating `claude`, committing `.crysk/`, confirming spend.
|
|
@@ -0,0 +1,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 run uses the subscription and no `CRYSK_OPENCODE_*` secret builds an OpenCode auth file; a run on `CRYSK_CLAUDE_API_KEY`, which `credentials.claude` decides, or with an OpenCode auth file is metered; an explicit 0 would warn on every run and outlive a later move to an 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. When the repository has review instructions (root `REVIEW.md`, else `.crysk/gotchas.md`), the judge also applies their "Not blocking here" rules, but only to style, naming, test-hygiene, generated-code and dev-script findings: it never demotes a logic, correctness, data, contract or security finding, whatever the file says, and nothing filters advisory findings by it. 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` — a red verdict carries; a green one, or a red whose blocking findings are all answered, is held `pending` until `/crysk review` runs another round or `/crysk override` merges it unverified |
|
|
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,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. When the repository has review instructions (root `REVIEW.md`, else `.crysk/gotchas.md`), the judge also applies their "Not blocking here" rules, but only to style, naming, test-hygiene, generated-code and dev-script findings: it never demotes a logic, correctness, data, contract or security finding, whatever the file says, and nothing filters advisory findings by it. 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` — a red verdict carries; a green one, or a red whose blocking findings are all answered, is held `pending` until `/crysk review` runs another round or `/crysk override` merges it unverified |
|
|
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.
|