wachiman 1.12.0 → 1.13.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 (41) hide show
  1. package/README.md +132 -101
  2. package/package.json +1 -1
  3. package/skills/wachiman-loop/SKILL.md +91 -0
  4. package/src/call-message.ts +26 -3
  5. package/src/cli.ts +81 -5
  6. package/src/config.ts +19 -0
  7. package/src/connectors/local-git.ts +101 -13
  8. package/src/cost.ts +20 -0
  9. package/src/doctor/checks.ts +1 -1
  10. package/src/engine.ts +532 -55
  11. package/src/estimate.ts +64 -0
  12. package/src/fidelity/block.ts +263 -0
  13. package/src/fidelity/claims-call.ts +172 -0
  14. package/src/fidelity/claims.ts +69 -0
  15. package/src/fidelity/digest.ts +80 -0
  16. package/src/fidelity/grade.ts +242 -0
  17. package/src/fidelity/inert.ts +25 -0
  18. package/src/fidelity/rules.ts +166 -0
  19. package/src/fidelity/sink.ts +135 -0
  20. package/src/fidelity/summary.ts +16 -0
  21. package/src/fidelity/types.ts +93 -0
  22. package/src/formats.ts +16 -3
  23. package/src/history/fingerprint.ts +1 -1
  24. package/src/history/store.ts +39 -1
  25. package/src/init/options.ts +1 -1
  26. package/src/local.ts +20 -2
  27. package/src/loop/command.ts +441 -0
  28. package/src/loop/state.ts +88 -0
  29. package/src/loop/stop-rule.ts +98 -0
  30. package/src/providers/claude-code.ts +47 -12
  31. package/src/providers/codex.ts +3 -2
  32. package/src/providers/index.ts +5 -2
  33. package/src/providers/types.ts +10 -0
  34. package/src/sinks/json.ts +13 -2
  35. package/src/skills/install.ts +4 -4
  36. package/src/store/command.ts +109 -0
  37. package/src/store/figures.ts +153 -0
  38. package/src/store/html.ts +138 -0
  39. package/src/store/index.ts +298 -0
  40. package/templates/caller-workflow.yml +45 -15
  41. package/templates/wachiman-review-caller.yml +8 -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/agent-review.md`, `.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "wachiman",
3
- "version": "1.12.0",
3
+ "version": "1.13.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",
@@ -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 |
@@ -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}`;
package/src/cli.ts CHANGED
@@ -10,10 +10,14 @@
10
10
  * when the head was already reviewed
11
11
  * wachiman local [paths…] review the committed branch of a clone on the signed-in
12
12
  * `claude`, and print it; no GitHub call (src/local.ts)
13
+ * wachiman loop [--base <ref>] one review round of a fix loop on the signed-in `claude`; exit 0
14
+ * converged, 10 findings open, 11 stopped (src/loop/command.ts)
13
15
  * wachiman ask [question…] answer a question about the local change, or explain it; one
14
16
  * call, no GitHub request, grounded in the stored review (src/local-ask.ts)
15
17
  * wachiman history list and judge what `local --history` kept on this laptop
16
18
  * wachiman status what the local history kept and its estimated cost; files only
19
+ * wachiman dashboard spend, findings and loops across every repository in the history, as one
20
+ * static HTML file or JSON, from a rebuildable index (src/store/)
17
21
  * wachiman setup [--profile <name>] bind this repository to an account profile (home config only);
18
22
  * on a terminal without --profile it asks
19
23
  * wachiman init write the GitHub caller workflow, or hand over to `setup`
@@ -24,7 +28,7 @@
24
28
  * wachiman --setup-profile [name] sign in an isolated Claude Code profile under the Wachiman home
25
29
  *
26
30
  * Exit codes: 0 posted or nothing to do; 1 engine error (nothing posted); 2 usage error;
27
- * 130 cancelled (`local`, `setup`, `init`).
31
+ * 130 cancelled (`local`, `loop`, `setup`, `init`); `loop` also exits 10 and 11 (see its help).
28
32
  * The settings are documented in docs/cli.md.
29
33
  */
30
34
  import { existsSync, readFileSync, statSync, writeSync } from "node:fs";
@@ -33,8 +37,10 @@ import { writeStepSummary, type CallCost } from "./cost";
33
37
  import { loadConfig, UsageError } from "./config";
34
38
  import { historyUsage, parseHistoryArgs, runHistory } from "./history/command";
35
39
  import { parseStatusArgs, runStatus, statusUsage } from "./status/command";
36
- import { comment, defaultGh, isThreadQuestion, review, threadReplies, type Deps, type ReviewLineComment } from "./engine";
40
+ import { dashboardUsage, parseDashboardArgs, runDashboard } from "./store/command";
41
+ import { comment, defaultGh, isThreadQuestion, review, threadReplies, type Deps, type GhFn, type ReviewLineComment } from "./engine";
37
42
  import { localUsage, parseLocalArgs, runLocal } from "./local";
43
+ import { loopUsage, parseLoopArgs, runLoop } from "./loop/command";
38
44
  import { askUsage, parseAskArgs, runAsk } from "./local-ask";
39
45
  import { parseProfileArgs, parseProjectArgs, profileUsage, projectUsage, runProfile, runProject, setupUsage } from "./accounts/commands";
40
46
  import { wachimanHome } from "./accounts/config";
@@ -45,6 +51,7 @@ import { DEFAULT_WORKFLOW_REF } from "./init/options";
45
51
  import { runInitCommand } from "./init/run";
46
52
  import { projectCommands } from "./wizard/command";
47
53
  import { DEFAULT_ISOLATED_NAME, setupProfile } from "./profiles";
54
+ import { resetConfidence } from "./fidelity/sink";
48
55
  import { getProvider, PROVIDER_NAMES, UnknownProviderError } from "./providers";
49
56
  import { parseSetupFlags } from "./setup/args";
50
57
  import { runSetupCommand } from "./setup/run";
@@ -53,11 +60,20 @@ export const USAGE = `Usage:
53
60
  wachiman review <pr> [paths…] [--repo-dir <dir>] Review a pull request (or only the given paths)
54
61
  wachiman comment <pr> [--repo-dir <dir>] Handle the comment in $REQUEST (a review or an answer)
55
62
  wachiman threads <pr> [--repo-dir <dir>] Answer the pending Wachiman threads (an automatic run)
63
+ wachiman reset-confidence <pr> [--commit <sha>] Write "cannot say" into the PR Confidence block (no model call;
64
+ the first step of a review run, with AGENT_REVIEW_CONFIDENCE=1)
56
65
  ${localUsage}
57
66
  Review the committed branch of a clone on your
58
67
  signed-in claude, and print it; nothing is posted.
59
68
  --commit: that one commit (<commit>^ → <commit>);
60
69
  --from: that commit forward (<commit>^ → HEAD)
70
+ ${loopUsage}
71
+ One round of a review loop on your signed-in claude:
72
+ --base starts it (round 1 reviews the whole range),
73
+ a call with a loop open continues it and reviews only
74
+ the commits since the last round. Fix, or judge a
75
+ finding wrong with a reason, between calls; the CLI
76
+ never edits code. Three rounds by default
61
77
  ${askUsage}
62
78
  Answer a question about the change the scope flags
63
79
  select, or explain it when no question is given. One
@@ -72,6 +88,17 @@ export const USAGE = `Usage:
72
88
  What this laptop kept of its local runs and their
73
89
  estimated cost, filterable; uses local history. GitHub
74
90
  Actions runs are not counted
91
+ ${dashboardUsage}
92
+ Write one static HTML page (or print JSON) with the
93
+ spend per day and repository, the findings by severity
94
+ and verdict and the loop rounds of every repository in
95
+ the local history. Built from an index under the
96
+ Wachiman home that is rebuilt whenever it is missing or
97
+ out of date. It writes only that index and, without
98
+ --json, the page, and, like \`wachiman history\`, moves
99
+ a damaged run file aside. No claude, no GitHub, no
100
+ network, no server, no browser. --repo-dir is accepted
101
+ and unused
75
102
  ${setupUsage}
76
103
  Bind this repository to an account profile; written
77
104
  in the Wachiman home, never in the repository. On a
@@ -92,7 +119,7 @@ export const USAGE = `Usage:
92
119
  Claude configuration directory, used in place
93
120
  ${projectUsage.split("\n").join("\n ")}
94
121
  ${skillsUsage.split("\n").join("\n ")}
95
- Copy the wachiman-review and wachiman-audit agent
122
+ Copy the wachiman-review, wachiman-loop and wachiman-audit agent
96
123
  skills into ~/.agents/skills and each Claude Code
97
124
  config directory; uninstall removes only the copies
98
125
  it marked. Never touches ~/.wachiman
@@ -107,17 +134,21 @@ Options:
107
134
 
108
135
  Environment:
109
136
  GH_TOKEN, GITHUB_REPOSITORY required (not read by \`local\`, \`ask\` or \`--setup-profile\`)
110
- ANTHROPIC_API_KEY required by the claude-code provider (not in a dry run);
111
- \`local\` and \`ask\` refuse to start when it is set
137
+ ANTHROPIC_API_KEY the claude-code provider needs this or CLAUDE_CODE_OAUTH_TOKEN
138
+ (not in a dry run); \`local\` and \`ask\` refuse to start when it is set
139
+ CLAUDE_CODE_OAUTH_TOKEN a Claude subscription token (\`claude setup-token\`); if set, it is
140
+ used and ANTHROPIC_API_KEY never reaches the agent
112
141
  REQUEST the comment text, for \`comment\`
113
142
  AGENT_REVIEW_COMMENT_AUTHOR the login of the comment's author, for \`comment\` and \`threads\`
114
143
  AGENT_REVIEW_* optional settings; see docs/cli.md
115
144
 
116
145
  Exit codes: 0 posted or nothing to do, 1 engine error, 2 usage error.
117
146
  \`local\`: 0 a report was printed, 1 no call returned a review, 2 usage error, 130 interrupted.
147
+ \`loop\`: 0 converged, 10 findings still open, 11 stopped without converging (round cap or review failed), 2 usage error, 130 interrupted. A stop is never an approval.
118
148
  \`ask\`: 0 an answer was printed (it may say what it could not answer), 1 no answer (the call failed or returned nothing usable), 2 usage error, 130 interrupted.
119
149
  \`history\`: 0 listed (or nothing to list), 2 usage error, including an unknown finding id.
120
150
  \`status\`: 0 printed (also with no run kept), 2 usage error.
151
+ \`dashboard\`: 0 written or printed (also with no run kept), 2 usage error, 1 the index or the page could not be written.
121
152
  \`doctor\`: 0 every required check passed, 1 one failed. \`setup\`: 1 when its closing doctor summary failed.
122
153
  \`setup\`, \`init\`: 130 cancelled (Escape, Ctrl-C, Ctrl-D); nothing pending is saved.
123
154
  \`skills\`: 0 done (copies left in place are warned about), 1 a copy could not be written, 2 usage error or a refused target.
@@ -247,6 +278,37 @@ async function runWizard(mode: "setup" | "init", args: string[], repoDir: string
247
278
  });
248
279
  }
249
280
 
281
+ /**
282
+ * `wachiman reset-confidence <pr> [--commit <sha>]`: the first step of a review run (ADR 0033
283
+ * decision 14). It rewrites the PR Confidence block to `cannot say` for the commit under review
284
+ * before the push wait, so a run cancelled during it leaves no letter from an older commit. No
285
+ * model, no provider. A failure inside the reset itself (reading or writing the description) is a
286
+ * warning and the exit code stays 0. A usage or configuration error is not: a bad pull request
287
+ * number or flag, an invalid `AGENT_REVIEW_*` value, or a missing `GH_TOKEN` or
288
+ * `GITHUB_REPOSITORY` exits non-zero. The workflow steps run it with `continue-on-error`.
289
+ */
290
+ export function runResetConfidence(args: string[], env: Record<string, string | undefined>, gh: GhFn = defaultGh): number {
291
+ const [prArg, ...flags] = args;
292
+ const pr = Number(prArg);
293
+ if (!/^\d+$/.test(prArg ?? "") || pr <= 0) throw new UsageError("reset-confidence needs a pull request number.");
294
+ let commit: string | undefined;
295
+ for (let i = 0; i < flags.length; i++) {
296
+ if (flags[i] !== "--commit" || !flags[i + 1]) throw new UsageError(`reset-confidence: unexpected "${flags[i]}".`);
297
+ commit = flags[++i];
298
+ }
299
+ const config = loadConfig(env);
300
+ if (!config.confidence) return 0;
301
+ required(env, "GH_TOKEN");
302
+ const repo = required(env, "GITHUB_REPOSITORY");
303
+ resetConfidence(
304
+ { gh, dryRun: config.dryRun, log: (line) => console.log(line), warn: (line) => console.error(line) },
305
+ repo,
306
+ pr,
307
+ commit,
308
+ );
309
+ return 0;
310
+ }
311
+
250
312
  export async function main(argv: string[], env: Record<string, string | undefined>): Promise<number> {
251
313
  const mode = argv[0];
252
314
  if (mode === "--help" || mode === "-h") {
@@ -281,6 +343,14 @@ export async function main(argv: string[], env: Record<string, string | undefine
281
343
  engineVersion: readVersion(),
282
344
  });
283
345
  }
346
+ if (mode === "loop") {
347
+ // Like `local`: no GitHub token, no `gh` function anywhere on this path.
348
+ return runLoop(parseLoopArgs(args.slice(1)), repoDir, env, {
349
+ stdout: (text) => writeAll(1, text),
350
+ stderr: (line) => console.error(line),
351
+ engineVersion: readVersion(),
352
+ });
353
+ }
284
354
  if (mode === "ask") {
285
355
  // Like `local`: no GitHub token, no `gh` function anywhere on this path.
286
356
  return runAsk(parseAskArgs(args.slice(1)), repoDir, env, {
@@ -298,9 +368,15 @@ export async function main(argv: string[], env: Record<string, string | undefine
298
368
  if ("help" in parsed) return (writeAll(1, `${statusUsage}\n`), 0);
299
369
  return runStatus(parsed, repoDir, env, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line), version: readVersion() });
300
370
  }
371
+ if (mode === "dashboard") {
372
+ const parsed = parseDashboardArgs(args.slice(1));
373
+ if ("help" in parsed) return (writeAll(1, `${dashboardUsage}\n`), 0);
374
+ return runDashboard(parsed, env, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) });
375
+ }
301
376
  if (mode === "history") {
302
377
  return runHistory(parseHistoryArgs(args.slice(1)), repoDir, env, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) });
303
378
  }
379
+ if (mode === "reset-confidence") return runResetConfidence(args.slice(1), env);
304
380
  const [, prArg, ...rest] = args;
305
381
  if (mode !== "review" && mode !== "comment" && mode !== "threads") {
306
382
  throw new UsageError(mode ? `Unknown command "${mode}".` : "No command given.");