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