wachiman 1.12.0 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +132 -101
  2. package/bin/wachiman.js +1 -1
  3. package/package.json +2 -3
  4. package/skills/wachiman-loop/SKILL.md +91 -0
  5. package/skills/wachiman-review/SKILL.md +2 -2
  6. package/src/call-message.ts +26 -3
  7. package/src/cli.ts +113 -18
  8. package/src/config.ts +99 -32
  9. package/src/connectors/local-git.ts +102 -14
  10. package/src/cost.ts +48 -1
  11. package/src/doctor/checks.ts +1 -1
  12. package/src/engine.ts +910 -89
  13. package/src/estimate.ts +64 -0
  14. package/src/fidelity/block.ts +263 -0
  15. package/src/fidelity/claims-call.ts +172 -0
  16. package/src/fidelity/claims.ts +69 -0
  17. package/src/fidelity/digest.ts +80 -0
  18. package/src/fidelity/grade.ts +242 -0
  19. package/src/fidelity/inert.ts +25 -0
  20. package/src/fidelity/rules.ts +166 -0
  21. package/src/fidelity/sink.ts +135 -0
  22. package/src/fidelity/summary.ts +16 -0
  23. package/src/fidelity/types.ts +93 -0
  24. package/src/formats.ts +16 -3
  25. package/src/history/fingerprint.ts +1 -1
  26. package/src/history/store.ts +44 -6
  27. package/src/init/options.ts +1 -1
  28. package/src/ledger.ts +306 -0
  29. package/src/local.ts +23 -5
  30. package/src/loop/command.ts +441 -0
  31. package/src/loop/state.ts +88 -0
  32. package/src/loop/stop-rule.ts +98 -0
  33. package/src/providers/claude-code.ts +48 -13
  34. package/src/providers/codex.ts +8 -7
  35. package/src/providers/index.ts +6 -3
  36. package/src/providers/types.ts +13 -3
  37. package/src/sinks/common.ts +3 -3
  38. package/src/sinks/json.ts +13 -2
  39. package/src/skills/install.ts +4 -4
  40. package/src/status/command.ts +1 -1
  41. package/src/store/command.ts +109 -0
  42. package/src/store/figures.ts +153 -0
  43. package/src/store/html.ts +138 -0
  44. package/src/store/index.ts +298 -0
  45. package/templates/caller-workflow.yml +84 -57
  46. package/templates/wachiman-review-caller.yml +13 -0
package/README.md CHANGED
@@ -2,13 +2,127 @@
2
2
 
3
3
  <img src="docs/assets/wachi.png" alt="Wachiman, a cartoon watchman with a cap and a whistle" width="96" align="right">
4
4
 
5
- Advisory code reviews by an agent CLI: a pull request review that runs inside your own GitHub
6
- Actions with your own API key, or a review of a branch on your laptop with your own Claude
7
- subscription. One engine, two ways to start it today ([below](#ways-to-run-it)). Wachiman
8
- (pronounced *watchman*) is named after the Peruvian *wachimán*, the street
9
- watchman who warns you and lets you decide; the Spanish word comes from the English one.
5
+ Advisory code reviews by an agent CLI. Review a branch on your laptop with your own Claude
6
+ subscription, or review every pull request inside your own GitHub Actions with your own API key or Claude subscription token.
7
+ One engine, same findings either way. Wachiman never approves or blocks a merge: it warns, you
8
+ decide.
10
9
 
11
- ## What it is
10
+ **Documentation: [wachiman.dev/docs](https://wachiman.dev/docs/what-it-is/)** ·
11
+ [npm](https://www.npmjs.com/package/wachiman) · [Changelog](CHANGELOG.md)
12
+
13
+ Wachiman (pronounced *watchman*) is named after the Peruvian *wachimán*, the street watchman who
14
+ warns you and lets you decide; the Spanish word comes from the English one.
15
+
16
+ ## Contents
17
+
18
+ - [Install](#install)
19
+ - [What you can do with it](#what-you-can-do-with-it)
20
+ - [Documentation](#documentation)
21
+ - [What a pull request review looks like](#what-a-pull-request-review-looks-like)
22
+ - [What it will not do](#what-it-will-not-do)
23
+ - [The trust decision, in brief](#the-trust-decision-in-brief)
24
+ - [Providers and platforms](#providers-and-platforms)
25
+ - [License](#license)
26
+ - [Commit messages](#commit-messages)
27
+
28
+ ## Install
29
+
30
+ ```sh
31
+ npm i -g wachiman # or: bun add -g wachiman
32
+ wachiman --version
33
+ wachiman init # set up this project: local reviews, GitHub Actions, or both
34
+ ```
35
+
36
+ You need Node 20 or later and, for local reviews, Claude Code (`claude`) signed in. The package
37
+ installs [Bun](https://bun.sh) for you through its `bun` dependency (a 23 to 42 MB download); with
38
+ `--ignore-scripts` it uses a Bun already on your `PATH`. No API key is needed for local reviews.
39
+ Details, the supply-chain note and installing from a clone: [docs/local-review.md](docs/local-review.md#3-install).
40
+
41
+ `wachiman init` asks which mode you want. Local setup uses your current Claude session (or a
42
+ separate profile), checks the machine and account, and prints the first review command. GitHub
43
+ setup writes the workflow file; adding the secret and pushing the workflow stay manual steps.
44
+ See [project setup](docs/local-review.md#configure-this-project).
45
+
46
+ ## What you can do with it
47
+
48
+ | Way | Where it runs | What you need | Guide |
49
+ | --- | --- | --- | --- |
50
+ | `wachiman local` | Your laptop, on a branch or commit; nothing is posted | Claude Code signed in; no API key | [docs/local-review.md](docs/local-review.md) |
51
+ | Reusable GitHub Actions workflow | Your repository's runners, on each pull request | A provider API key, or a Claude subscription token, as a secret | [docs/install.md](docs/install.md) |
52
+
53
+ A GitHub App is a design only; it is not implemented.
54
+
55
+ **Review your branch before you push.** `wachiman local` reviews the committed change on your
56
+ branch with your own signed-in `claude` and prints the findings in the terminal, or writes them as
57
+ Markdown or JSON. Nothing is posted, no GitHub requests are made and no telemetry is sent; your
58
+ code goes to your configured Claude account. Read [docs/local-review.md](docs/local-review.md)
59
+ before running it on an employer's code.
60
+
61
+ ```sh
62
+ wachiman local # current branch against origin's default branch
63
+ wachiman local --commit abc1234 # exactly one commit
64
+ wachiman local --from abc1234 # that commit and everything after it
65
+ wachiman local --format markdown --output review.md
66
+ ```
67
+
68
+ **Loop until clean.** `wachiman loop --base main` runs one review round per call and exits `0`
69
+ when nothing keeps it open, `10` while findings do and `11` when it stopped without converging; a
70
+ coding agent fixes between calls and the CLI never edits code ([docs/cli.md](docs/cli.md#loop)).
71
+
72
+ **Ask about a change.** `wachiman ask "<question>"` answers one question about the same local
73
+ change, grounded in its stored review when there is one; with no question it walks you through the
74
+ change ([docs/cli.md](docs/cli.md#ask)).
75
+
76
+ **See what local runs cost.** `wachiman status` shows the cost of the runs kept on this laptop
77
+ ([docs/cli.md](docs/cli.md#status)); workflow runs are not in it. `wachiman dashboard` writes one
78
+ offline HTML page (or JSON) with the spend per day and repository, the findings by severity and
79
+ verdict and the loop rounds ([docs/local-dashboard.md](docs/local-dashboard.md)).
80
+
81
+ **Let your coding agent run it.** `wachiman skills install` copies the `wachiman-review` agent
82
+ skill, which teaches Claude Code or Codex to pick the range from what you ask, run a local review
83
+ and present the findings, and the `wachiman-loop` skill, which fixes between loop rounds ([docs/local-review.md](docs/local-review.md#let-your-coding-agent-run-it)).
84
+
85
+ **Review every pull request in GitHub Actions.** A short caller file in your repository pins a
86
+ release, passes your key and names the operator. Start with [docs/install.md](docs/install.md),
87
+ from an empty repository to a posted review; the caller file is
88
+ [`templates/wachiman-review-caller.yml`](templates/wachiman-review-caller.yml). Already copied the
89
+ engine into a repository? [docs/setup-copy.md](docs/setup-copy.md) explains how to move to the
90
+ maintained workflow.
91
+
92
+ ## Documentation
93
+
94
+ The guides are published at **[wachiman.dev/docs](https://wachiman.dev/docs/what-it-is/)**. The
95
+ same material, in this repository:
96
+
97
+ | I want to… | Read |
98
+ | --- | --- |
99
+ | Get a first review on a repository | [docs/install.md](docs/install.md) |
100
+ | Know what I am trusting, and what is unverified | [SECURITY.md](SECURITY.md) |
101
+ | Look up an input, a default or an environment setting | [docs/configuration.md](docs/configuration.md) |
102
+ | Find out why there was no review, or an error | [docs/troubleshooting.md](docs/troubleshooting.md) |
103
+ | Ask for reviews, scope them, read the results | [docs/reviews.md](docs/reviews.md) |
104
+ | Understand what a run can cost and what coverage means | [docs/costs.md](docs/costs.md) |
105
+ | Read the PR Confidence grade in a description (trial) | [docs/pr-confidence.md](docs/pr-confidence.md) |
106
+ | Tell the reviewer what matters in my repository | [docs/review-policy.md](docs/review-policy.md) |
107
+ | Adopt a new release, or roll one back | [docs/upgrading.md](docs/upgrading.md) |
108
+ | Turn it off and remove it | [docs/uninstall.md](docs/uninstall.md) |
109
+ | Quick answers and limitations | [docs/faq.md](docs/faq.md) |
110
+ | Run the engine from the command line | [docs/cli.md](docs/cli.md) |
111
+ | Review a branch on my laptop, on my own Claude subscription | [docs/local-review.md](docs/local-review.md) |
112
+ | See the spend, findings and loops of my local reviews on one page | [docs/local-dashboard.md](docs/local-dashboard.md) |
113
+ | See what a provider adapter runs and inherits | [docs/providers/claude-code.md](docs/providers/claude-code.md), [docs/providers/codex.md](docs/providers/codex.md) |
114
+ | Move from a copied installation | [docs/setup-copy.md](docs/setup-copy.md) |
115
+ | Understand how a review is built | [docs/architecture.md](docs/architecture.md) |
116
+ | Measure false positives | [docs/precision.md](docs/precision.md) |
117
+ | See how it compares with Pullfrog and CodeRabbit | [wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks) |
118
+ | See what changed in a release | [CHANGELOG.md](CHANGELOG.md) |
119
+ | Cut a release (maintainers) | [docs/releasing.md](docs/releasing.md) |
120
+
121
+ Design decisions are recorded as ADRs in [docs/adr/](docs/adr/), starting with
122
+ [ADR 0001: distribution and trust](docs/adr/0001-distribution-and-trust.md) and
123
+ [ADR 0002: TypeScript on Bun, no runtime dependencies besides Bun itself](docs/adr/0002-typescript-on-bun-zero-dependencies.md).
124
+
125
+ ## What a pull request review looks like
12
126
 
13
127
  A GitHub Actions workflow that reads a pull request and posts one GitHub review on it. Each
14
128
  finding is an inline comment on its line, labelled with a severity (when to act: Blocker, Fix,
@@ -66,107 +180,24 @@ you do:
66
180
  This is not a sandbox. What is enforced, what the tests show and what is still unverified:
67
181
  [SECURITY.md](SECURITY.md).
68
182
 
69
- ## Status and providers
183
+ ## Providers and platforms
70
184
 
71
- The current release is **v1.5.0** ([CHANGELOG.md](CHANGELOG.md)). The command-line contract
72
- ([docs/cli.md](docs/cli.md)) and the provider adapter boundary are in place. The older
73
- `CLAUDE_REVIEW_*` variables, `.github/agent-review.md`, `.github/claude-review.md`, `/wachi` and the `@claude` mention are still read
74
- with a notice; see [docs/upgrading.md](docs/upgrading.md).
185
+ The current release is on [npm](https://www.npmjs.com/package/wachiman) and in
186
+ [CHANGELOG.md](CHANGELOG.md). The command-line contract ([docs/cli.md](docs/cli.md)) and the
187
+ provider adapter boundary are in place. The older `CLAUDE_REVIEW_*` variables,
188
+ `.github/claude-review.md`, `/wachi` and the `@claude` mention are still
189
+ read with a notice; see [docs/upgrading.md](docs/upgrading.md).
75
190
 
76
191
  - **Claude Code** (`claude -p`) is the provider the reusable workflow installs and runs, with
77
- `ANTHROPIC_API_KEY` ([docs/providers/claude-code.md](docs/providers/claude-code.md)).
192
+ `ANTHROPIC_API_KEY`, or `CLAUDE_CODE_OAUTH_TOKEN` to run on a Claude subscription
193
+ ([docs/providers/claude-code.md](docs/providers/claude-code.md)).
78
194
  - **Codex CLI** (`codex exec`, for OpenAI models) is a second adapter, available only from the
79
195
  command line. The reusable workflow does not install it or pass an OpenAI key
80
196
  ([docs/providers/codex.md](docs/providers/codex.md)).
81
- - **npm:** the package `wachiman` is on npm (`npm i -g wachiman`; a Node launcher that installs
82
- Bun through its `bun` dependency;
83
- [docs/local-review.md](docs/local-review.md#3-install)). Version 1.10.0 was published by hand,
84
- without a provenance statement; the release workflow publishes the following versions with one.
85
- Installing from source (`scripts/install-local.sh`) still works. macOS and Linux are covered by CI;
86
- Windows is not tested in CI, and is expected to work wherever Node and Bun run.
87
-
88
- ## Ways to run it
89
-
90
- One review engine, started from different places. Same findings, same labels, your own account each
91
- time.
92
-
93
- | Way | Where it runs | What you need | Status |
94
- | --- | --- | --- | --- |
95
- | Reusable GitHub Actions workflow | Your repository's runners, on each pull request | A provider API key as a secret | Shipped; [docs/install.md](docs/install.md) |
96
- | `wachiman local` | Your laptop, on a branch or commit; nothing is posted | Claude Code signed in; no API key | Shipped; [docs/local-review.md](docs/local-review.md) |
97
- | GitHub App | Not available | | A design only, not implemented |
98
-
99
- After a local run, `wachiman status` shows what the runs kept on this laptop cost
100
- ([docs/cli.md](docs/cli.md#status)); runs by the workflow are not in it.
101
-
102
- ## Install
103
-
104
- The recommended way is the reusable workflow: a short caller file in your repository pins a
105
- release, passes your key and names the operator.
106
-
107
- **Start here: [docs/install.md](docs/install.md)**, the first advisory review from an empty
108
- repository to a posted review. The caller file itself is
109
- [`templates/wachiman-review-caller.yml`](templates/wachiman-review-caller.yml).
110
-
111
- Already copied the engine into a repository? That setup still runs, and
112
- [docs/setup-copy.md](docs/setup-copy.md) explains how to move to the maintained workflow.
113
-
114
- ### Review locally on your own subscription
115
-
116
- `wachiman local` reviews the branch you have checked out, on your own signed-in `claude`, and
117
- prints the review in the terminal or writes it as Markdown or JSON. No API key, no GitHub token,
118
- nothing posted: Wachiman sends no telemetry and makes no GitHub requests in local mode; your code
119
- is sent to your configured Claude account for the review. Read
120
- [docs/local-review.md](docs/local-review.md) before running it on an employer's code.
121
-
122
- Install it from npm (below), or from source: run `scripts/install-local.sh` once from your clone. The npm package
123
- (`npm i -g wachiman` or `bun add -g wachiman`; it is written to work on Windows (Git Bash, PowerShell), and it is expected to work wherever Node and Bun run, but it is not tested in CI: it ships the
124
- TypeScript source and a small Node launcher, and it installs Bun for you by depending on the
125
- official npm package `bun`, which means installing it downloads Bun, 23 to 42 MB compressed; with
126
- `--ignore-scripts` it uses a Bun already on your `PATH`; details and the supply-chain note are in
127
- [docs/local-review.md](docs/local-review.md#from-npm)) is published. Both give a global `wachiman local …`
128
- command; the script also links the `wachiman-review` agent skill, usable from any project, and the
129
- `wachiman-audit` skill, which compares Wachiman's findings with another reviewer's on the same
130
- commits (data and procedure in
131
- [wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks)). Details and the Windows
132
- note are in [docs/local-review.md](docs/local-review.md#3-install).
133
-
134
- Configure an existing project with `wachiman init`: choose local reviews, GitHub Actions, or
135
- both. Local setup offers your current Claude session and checks the machine/account before
136
- suggesting the first review command. GitHub setup writes the workflow; adding the secret and
137
- submitting the workflow remain manual. See [project setup](docs/local-review.md#configure-this-project).
138
-
139
- `wachiman ask "<question>"` answers one question about the same local change (or walks through it
140
- with no question), grounded in the stored review of that change when there is one. It is in
141
- [docs/cli.md](docs/cli.md#ask).
142
-
143
- ## Documentation map
144
-
145
- | I want to… | Read |
146
- | --- | --- |
147
- | Get a first review on a repository | [docs/install.md](docs/install.md) |
148
- | Know what I am trusting, and what is unverified | [SECURITY.md](SECURITY.md) |
149
- | Look up an input, a default or an environment setting | [docs/configuration.md](docs/configuration.md) |
150
- | Find out why there was no review, or an error | [docs/troubleshooting.md](docs/troubleshooting.md) |
151
- | Ask for reviews, scope them, read the results | [docs/reviews.md](docs/reviews.md) |
152
- | Understand what a run can cost and what coverage means | [docs/costs.md](docs/costs.md) |
153
- | Tell the reviewer what matters in my repository | [docs/review-policy.md](docs/review-policy.md) |
154
- | Adopt a new release, or roll one back | [docs/upgrading.md](docs/upgrading.md) |
155
- | Turn it off and remove it | [docs/uninstall.md](docs/uninstall.md) |
156
- | Quick answers and limitations | [docs/faq.md](docs/faq.md) |
157
- | Run the engine from the command line | [docs/cli.md](docs/cli.md) |
158
- | Review a branch on my laptop, on my own Claude subscription | [docs/local-review.md](docs/local-review.md) |
159
- | See what a provider adapter runs and inherits | [docs/providers/claude-code.md](docs/providers/claude-code.md), [docs/providers/codex.md](docs/providers/codex.md) |
160
- | Move from a copied installation | [docs/setup-copy.md](docs/setup-copy.md) |
161
- | Understand how a review is built | [docs/architecture.md](docs/architecture.md) |
162
- | Measure false positives | [docs/precision.md](docs/precision.md) |
163
- | See how it compares with Pullfrog and CodeRabbit | [wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks) |
164
- | See what changed in a release | [CHANGELOG.md](CHANGELOG.md) |
165
- | Cut a release (maintainers) | [docs/releasing.md](docs/releasing.md) |
166
-
167
- Design decisions are recorded as ADRs in [docs/adr/](docs/adr/), starting with
168
- [ADR 0001: distribution and trust](docs/adr/0001-distribution-and-trust.md) and
169
- [ADR 0002: TypeScript on Bun, no runtime dependencies besides Bun itself](docs/adr/0002-typescript-on-bun-zero-dependencies.md).
197
+ - **npm releases:** version 1.10.0 was published by hand, without a provenance statement; the
198
+ release workflow publishes later versions with one.
199
+ - **Platforms:** macOS and Linux are covered by CI. Windows (Git Bash, PowerShell) is not tested
200
+ in CI and is expected to work wherever Node and Bun run.
170
201
 
171
202
  ## License
172
203
 
package/bin/wachiman.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- // The npm `bin` for `wachiman` and `agent-review`: finds Bun on PATH and runs this package's
2
+ // The npm `bin` for `wachiman`: finds Bun on PATH and runs this package's
3
3
  // TypeScript engine with it. All logic is in ./launcher-args.js.
4
4
  import { dirname } from "node:path";
5
5
  import { fileURLToPath } from "node:url";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "wachiman",
3
- "version": "1.12.0",
3
+ "version": "1.14.0",
4
4
  "description": "Advisory pull request reviews by an agent CLI, run in your own GitHub Actions with your own key, or locally on your own Claude subscription",
5
5
  "private": false,
6
6
  "type": "module",
@@ -10,8 +10,7 @@
10
10
  "url": "git+https://github.com/niway-dev/wachiman.git"
11
11
  },
12
12
  "bin": {
13
- "wachiman": "bin/wachiman.js",
14
- "agent-review": "bin/wachiman.js"
13
+ "wachiman": "bin/wachiman.js"
15
14
  },
16
15
  "files": [
17
16
  "bin/wachiman.js",
@@ -0,0 +1,91 @@
1
+ ---
2
+ name: wachiman-loop
3
+ description: Use when the developer asks you to review your own change with Wachiman and keep fixing what it finds until it is clean ("loop until clean", "run the wachiman loop", "fix what wachiman reports and run it again") on their laptop. Not for a single review or for judging a finding outside a loop; that is wachiman-review.
4
+ ---
5
+
6
+ # Fix a branch with the Wachiman loop
7
+
8
+ ## Why
9
+
10
+ `wachiman loop` runs **one review round per call** on the developer's signed-in `claude` and
11
+ tells you whether to stop. The CLI keeps the books: round count, which findings are still open,
12
+ retries and the stop rule. **You fix the code between calls; the CLI never edits it, and you never
13
+ review the code yourself.** Choose the account the way `wachiman-review` does ("Choose the
14
+ profile"): ask `wachiman project show --json`, never read inside a profile directory.
15
+
16
+ ## The command
17
+
18
+ ```sh
19
+ env -u ANTHROPIC_API_KEY wachiman loop --repo-dir <clone> --base <ref> --format json \
20
+ [--profile <name>] [--max-rounds <n>] 2> <tmp>/loop.log
21
+ ```
22
+
23
+ - `--base <ref>` **starts** a loop: round 1 reviews the whole branch range from that ref (the
24
+ default branch, unless the developer names another). Run it from a directory outside the clone.
25
+ - The same command **without** `--base` continues the open loop of the branch: it reviews only the
26
+ commits made since the previous round. **Commit your fix first**; uncommitted work is not reviewed.
27
+ - Three rounds by default. Raise `--max-rounds` only when the developer says so.
28
+
29
+ ## Read the exit code first
30
+
31
+ | Exit | Meaning | You do |
32
+ | --- | --- | --- |
33
+ | `0` | Converged: nothing keeps the loop open | Report it as below |
34
+ | `10` | Findings still open | Work through `open[]`, commit, call again |
35
+ | `11` | Stopped without converging (`outcome.reason`: `round cap` or `review failed`) | Stop. Report the reason and what is still open. Do not call again unless the developer says so |
36
+ | `2` | Usage error (no loop open, detached HEAD, bad flag) | Read stderr and fix the call |
37
+
38
+ A stop is never an approval. `0` means the rule found nothing open in the commits reviewed; it is
39
+ not a statement that the branch is safe to merge.
40
+
41
+ ## Between rounds (exit 10)
42
+
43
+ The JSON has `open[]` (each with `id`, `path`, `line`, `severity`, `title`, `status`), `released[]`
44
+ (findings that no longer count, with `why`) and `notes[]` (🟡 and ⚪, which never keep the loop
45
+ open). For each finding in `open[]`:
46
+
47
+ 1. Read the cited code in the repository and decide whether the finding is true.
48
+ 2. **True:** fix it at that place and commit. The next round has to see the change; a finding at
49
+ lines nobody changed stays open even if the reviewer does not repeat it.
50
+ 3. **False, and you can say why in one sentence:** judge it, with the reason:
51
+
52
+ ```sh
53
+ wachiman history --repo-dir <clone> --verdict <id> wrong --reason "<why it is not a defect>"
54
+ ```
55
+
56
+ A `wrong` verdict without a reason does not release the finding.
57
+ 4. **Not sure:** do not guess. Ask the developer, and leave the finding open.
58
+
59
+ **Never judge a finding `wrong` to make the loop converge.** The reason must be something you
60
+ checked in the code, not "out of scope" or "not worth fixing". Every finding you judge `wrong`
61
+ appears in the outcome, and the owner reads that list.
62
+
63
+ Then call `wachiman loop` again without `--base`. A call with no new commit makes no review call
64
+ (and still counts as a round), so use it only after a verdict, never to wait.
65
+
66
+ ## At the end
67
+
68
+ Tell the developer, in this order:
69
+
70
+ 1. The exit code and `outcome.message`, in your own words but with every caveat. A loop that
71
+ converged at round 1 says "Round 1 reviewed the whole range". A loop that converged later says
72
+ "converged on incremental rounds": round 1 read the whole range and later rounds only your fix
73
+ commits; interactions with code outside them were not re-read. Pass on whichever caveat it
74
+ printed.
75
+ 2. What you fixed, with the commit of each.
76
+ 3. Every finding in `released[]` with `why: "judged wrong"`, with its reason, so they can overrule
77
+ you. Also name the findings released as `probably-fixed`: that is inferred from the code
78
+ changing, not proved.
79
+ 4. The `notes[]`, one line each, as optional.
80
+
81
+ ## Never
82
+
83
+ | Tempting | Instead |
84
+ | --- | --- |
85
+ | Editing code inside the CLI, or asking it to apply a fix | You edit and commit; the CLI only reviews |
86
+ | Marking findings `wrong` until exit 0 | Fix the true ones; give a checked reason for the false ones; ask when unsure |
87
+ | Calling again after exit 11 to "try once more" | Report the stop; the developer decides |
88
+ | Running `wachiman review <pr>`, `gh` or a GitHub token | `loop` is local; nothing is posted |
89
+ | Running with `ANTHROPIC_API_KEY` set | `env -u ANTHROPIC_API_KEY wachiman loop ...`; the subscription pays |
90
+ | Editing files under `~/.wachiman` to reset or close a loop | `--base <ref>` starts a new loop |
91
+ | Claiming the branch is approved or safe | Report the outcome and its limits |
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: wachiman-review
3
- description: Use when the developer asks to review, audit or "analyse" their own code with Wachiman (or agent-review) on their laptop — a branch, one commit, or a range from a commit — including on employer code that must not reach GitHub, when they ask Wachiman to explain or answer a question about such a change ("explain this change", "ask about this branch"), and when they judge a finding from such a review as right or wrong.
3
+ description: Use when the developer asks to review, audit or "analyse" their own code with Wachiman on their laptop — a branch, one commit, or a range from a commit — including on employer code that must not reach GitHub, when they ask Wachiman to explain or answer a question about such a change ("explain this change", "ask about this branch"), and when they judge a finding from such a review as right or wrong.
4
4
  ---
5
5
 
6
6
  # Review local code with Wachiman
@@ -119,7 +119,7 @@ wachiman history --repo-dir <clone> --verdict <id> correct|partial|wrong --reaso
119
119
 
120
120
  | Tempting | Instead |
121
121
  | --- | --- |
122
- | `wachiman review <pr>`, `AGENT_REVIEW_DRY_RUN`, `gh`, a GitHub token | `local`: the GitHub modes post to the PR and need the code on GitHub |
122
+ | `wachiman review <pr>`, `WACHIMAN_DRY_RUN`, `gh`, a GitHub token | `local`: the GitHub modes post to the PR and need the code on GitHub |
123
123
  | A verdict as a PR comment or `Verdict:` reply | `history --verdict`: it stays on the laptop |
124
124
  | Running with `ANTHROPIC_API_KEY` set | `env -u ANTHROPIC_API_KEY wachiman local ...`: `local` refuses a key; the subscription pays |
125
125
  | `--max-depth 1000` because "review everything" | A closer start commit, or the number the developer chose |
@@ -3,7 +3,9 @@
3
3
  * scripts parse. The JSON stays the contract; this line is for the person reading the log.
4
4
  */
5
5
 
6
+ import { isEstimate } from "./cost";
6
7
  import type { ProviderErrorClass } from "./providers/errors";
8
+ import type { ProviderAuth } from "./providers/types";
7
9
 
8
10
  export interface CallSummary {
9
11
  /** Which call: `batch 1/2`, `threads`, `question`. */
@@ -15,6 +17,8 @@ export interface CallSummary {
15
17
  durationMs: number;
16
18
  providerError?: ProviderErrorClass;
17
19
  errorText?: string;
20
+ /** What paid for the call; absent means `api-key`. */
21
+ credential?: ProviderAuth;
18
22
  }
19
23
 
20
24
  const MAX_TEXT = 300;
@@ -29,18 +33,37 @@ const turnsText = (n: number) => `${n} turn${n === 1 ? "" : "s"}`;
29
33
  const seconds = (ms: number) => `${(ms / 1000).toFixed(1)} s`;
30
34
  const dollars = (usd: number) => `$${usd.toFixed(2)}`;
31
35
 
36
+ /** The messages for a call refused on a subscription token: its credential is not an API key, so nothing here names one. */
37
+ function describeTokenRefusal(head: string, providerError: ProviderErrorClass | undefined, api: string): string | undefined {
38
+ switch (providerError) {
39
+ case "auth":
40
+ return `❌ ${head}: Claude refused the call: the subscription token was rejected. Check the CLAUDE_CODE_OAUTH_TOKEN secret (a token lasts a year; make a new one with \`claude setup-token\`).${api}`;
41
+ case "billing":
42
+ return `❌ ${head}: Claude refused the call: the subscription's usage limit or plan access stopped it. Wait for the limit to reset, then re-run this job; the review does not fall back to an API key.${api}`;
43
+ case "rate_limit":
44
+ return `⏳ ${head}: Claude rate-limited the call. This is usually temporary.${api}`;
45
+ default:
46
+ return undefined;
47
+ }
48
+ }
49
+
32
50
  export function describeCall(call: CallSummary): string {
33
51
  const head = call.label;
52
+ const estimate = isEstimate(call.credential);
34
53
  if (!call.isError && call.terminalReason === "success")
35
- return `✅ ${head}: finished in ${turnsText(call.turns)}, ${seconds(call.durationMs)}, ${dollars(call.costUsd)}.`;
54
+ return `✅ ${head}: finished in ${turnsText(call.turns)}, ${seconds(call.durationMs)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
36
55
  if (call.terminalReason === "budget")
37
- return `💸 ${head}: stopped at its budget after ${turnsText(call.turns)}, ${dollars(call.costUsd)}.`;
56
+ return `💸 ${head}: stopped at its budget after ${turnsText(call.turns)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
38
57
  if (call.terminalReason === "turns")
39
- return `⏹️ ${head}: hit the turn limit after ${turnsText(call.turns)}, ${dollars(call.costUsd)}.`;
58
+ return `⏹️ ${head}: hit the turn limit after ${turnsText(call.turns)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
40
59
  if (call.terminalReason === "timeout") return `⏱️ ${head}: killed at the time limit after ${seconds(call.durationMs)}.`;
41
60
 
42
61
  const said = quoted(call.errorText);
43
62
  const api = said ? ` API said: ${said}` : "";
63
+ if (call.credential === "oauth-token") {
64
+ const line = describeTokenRefusal(head, call.providerError, api);
65
+ if (line) return line;
66
+ }
44
67
  switch (call.providerError) {
45
68
  case "billing":
46
69
  return `❌ ${head}: the Anthropic API refused the call: the account has no credit. Top up, then re-run this job.${api}`;