wachiman 1.15.0 → 1.17.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 (87) hide show
  1. package/README.md +13 -0
  2. package/package.json +1 -1
  3. package/skills/wachiman-loop/SKILL.md +43 -0
  4. package/src/accounts/commands.ts +3 -2
  5. package/src/accounts/confirm.ts +1 -1
  6. package/src/accounts/profile-list.ts +24 -0
  7. package/src/cli.ts +91 -26
  8. package/src/config.ts +40 -8
  9. package/src/connectors/local-git.ts +128 -0
  10. package/src/connectors/working-tree.ts +23 -1
  11. package/src/doctor/checks.ts +106 -1
  12. package/src/doctor/run.ts +9 -1
  13. package/src/engine.ts +1126 -222
  14. package/src/formats.ts +44 -3
  15. package/src/help.ts +204 -7
  16. package/src/history/command.ts +5 -5
  17. package/src/history/match.ts +24 -4
  18. package/src/history/store.ts +1 -1
  19. package/src/history/types.ts +7 -2
  20. package/src/init/agents.ts +135 -0
  21. package/src/init/args.ts +7 -2
  22. package/src/init/github-login.ts +13 -0
  23. package/src/init/json.ts +82 -0
  24. package/src/init/options.ts +42 -4
  25. package/src/init/prompt.ts +46 -15
  26. package/src/init/render.ts +3 -1
  27. package/src/init/run.ts +362 -28
  28. package/src/init/settings.ts +137 -0
  29. package/src/init/write.ts +16 -102
  30. package/src/json-schema.ts +8 -0
  31. package/src/ledger.ts +2 -2
  32. package/src/local-ask.ts +5 -4
  33. package/src/local.ts +90 -17
  34. package/src/loop/command.ts +29 -7
  35. package/src/memory/candidates.ts +425 -0
  36. package/src/memory/capture.ts +298 -0
  37. package/src/memory/command.ts +195 -0
  38. package/src/memory/entries.ts +213 -0
  39. package/src/memory/hygiene.ts +291 -0
  40. package/src/memory/inspect.ts +74 -0
  41. package/src/memory/load.ts +283 -0
  42. package/src/memory/mute.ts +259 -0
  43. package/src/memory/personal.ts +253 -0
  44. package/src/memory/proposal.ts +92 -0
  45. package/src/memory/propose.ts +414 -0
  46. package/src/memory/remember.ts +187 -0
  47. package/src/memory/report.ts +250 -0
  48. package/src/memory/settings.ts +20 -0
  49. package/src/pr-template/adopt.ts +434 -0
  50. package/src/pr-template/catalog.ts +429 -0
  51. package/src/pr-template/check-run.ts +328 -0
  52. package/src/pr-template/check.ts +338 -0
  53. package/src/pr-template/describe.ts +368 -0
  54. package/src/pr-template/format.ts +399 -0
  55. package/src/pr-template/gh.ts +159 -0
  56. package/src/pr-template/install.ts +311 -0
  57. package/src/pr-template/legacy-guides.ts +50 -0
  58. package/src/pr-template/pr-risk.ts +426 -0
  59. package/src/pr-template/render.ts +302 -0
  60. package/src/pr-template/resolve.ts +65 -0
  61. package/src/pr-template/run.ts +88 -0
  62. package/src/pr-template/strip.ts +171 -0
  63. package/src/pr-template/write.ts +139 -0
  64. package/src/precision.ts +10 -2
  65. package/src/priority.ts +106 -0
  66. package/src/providers/claude-code.ts +7 -8
  67. package/src/providers/codex.ts +4 -4
  68. package/src/providers/spawn.ts +95 -0
  69. package/src/providers/types.ts +5 -2
  70. package/src/repo-settings.ts +322 -0
  71. package/src/risk.ts +38 -9
  72. package/src/setup/prompt.ts +49 -33
  73. package/src/setup/run.ts +31 -6
  74. package/src/sinks/common.ts +22 -9
  75. package/src/sinks/markdown.ts +6 -2
  76. package/src/sinks/terminal.ts +6 -2
  77. package/src/store/figures.ts +5 -4
  78. package/src/store/html.ts +1 -1
  79. package/src/upgrade/command.ts +286 -0
  80. package/src/upgrade/pin.ts +112 -0
  81. package/src/verify.ts +20 -2
  82. package/src/wizard/mascot.ts +56 -51
  83. package/src/wizard/prompt-fancy.ts +10 -2
  84. package/src/wizard/prompt.ts +17 -4
  85. package/src/wizard/ui.ts +2 -0
  86. package/templates/pr/sections.json +163 -0
  87. package/templates/wachiman-review-caller.yml +7 -7
package/README.md CHANGED
@@ -22,6 +22,7 @@ warns you and lets you decide; the Spanish word comes from the English one.
22
22
  - [What it will not do](#what-it-will-not-do)
23
23
  - [The trust decision, in brief](#the-trust-decision-in-brief)
24
24
  - [Providers and platforms](#providers-and-platforms)
25
+ - [Contributing](#contributing)
25
26
  - [License](#license)
26
27
  - [Commit messages](#commit-messages)
27
28
 
@@ -91,12 +92,17 @@ maintained workflow.
91
92
 
92
93
  ## Documentation
93
94
 
95
+ [Engineering principles](docs/principles/README.md) explain the ideas behind the reviewer,
96
+ their external sources, the evidence expected of changes, and the boundary between current
97
+ behavior and proposed review memory.
98
+
94
99
  The guides are published at **[wachiman.dev/docs](https://wachiman.dev/docs/what-it-is/)**. The
95
100
  same material, in this repository:
96
101
 
97
102
  | I want to… | Read |
98
103
  | --- | --- |
99
104
  | Get a first review on a repository | [docs/install.md](docs/install.md) |
105
+ | Have my coding agent install, configure, upgrade or remove Wachiman from chat | [docs/agents.md](docs/agents.md) |
100
106
  | Know what I am trusting, and what is unverified | [SECURITY.md](SECURITY.md) |
101
107
  | Look up an input, a default or an environment setting | [docs/configuration.md](docs/configuration.md) |
102
108
  | Find out why there was no review, or an error | [docs/troubleshooting.md](docs/troubleshooting.md) |
@@ -110,6 +116,7 @@ same material, in this repository:
110
116
  | Run the engine from the command line | [docs/cli.md](docs/cli.md) |
111
117
  | Review a branch on my laptop, on my own Claude subscription | [docs/local-review.md](docs/local-review.md) |
112
118
  | See the spend, findings and loops of my local reviews on one page | [docs/local-dashboard.md](docs/local-dashboard.md) |
119
+ | Give every pull request the same description template, and check it | [docs/pr-template.md](docs/pr-template.md) |
113
120
  | 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
121
  | Move from a copied installation | [docs/setup-copy.md](docs/setup-copy.md) |
115
122
  | Understand how a review is built | [docs/architecture.md](docs/architecture.md) |
@@ -199,6 +206,12 @@ read with a notice; see [docs/upgrading.md](docs/upgrading.md).
199
206
  - **Platforms:** macOS and Linux are covered by CI. Windows (Git Bash, PowerShell) is not tested
200
207
  in CI and is expected to work wherever Node and Bun run.
201
208
 
209
+ ## Contributing
210
+
211
+ The code is public, but pull requests from outside the team are not accepted for now. Report
212
+ bugs and questions in [GitHub Issues](https://github.com/niway-dev/wachiman/issues); see
213
+ [CONTRIBUTING.md](CONTRIBUTING.md).
214
+
202
215
  ## License
203
216
 
204
217
  Wachiman is **source available**, not open source. It is licensed under the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "wachiman",
3
- "version": "1.15.0",
3
+ "version": "1.17.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",
@@ -78,6 +78,47 @@ Tell the developer, in this order:
78
78
  changing, not proved.
79
79
  4. The `notes[]`, one line each, as optional.
80
80
 
81
+ ## Ask the owner, and memory
82
+
83
+ Fix the mechanical findings like any other. Two cases need the owner.
84
+
85
+ **A finding whose fix depends on intent.** If the right fix depends on what the owner wants (which
86
+ behaviour is intended, which value is correct), do not guess. Fix the rest, commit, call the loop
87
+ again, then ask the owner in one message: the finding (`id`, `path`, `line`), what you would do,
88
+ and why you are asking. Leave it open until they answer.
89
+
90
+ **Repository memory.** Memory holds rules that a later review should apply, or should stop
91
+ reporting. Change it only with the owner's yes. Start this when `wachiman loop --format json`
92
+ lists `memoryCandidates`, or when the owner says a finding should not come back:
93
+
94
+ 1. Draft the entry yourself, from the code and what the owner meant. Do not copy the owner's
95
+ words as the rule.
96
+ 2. Record it. `memory add` prints the id:
97
+
98
+ ```sh
99
+ wachiman memory add --kind convention|exception --scope "<glob>" --rule "<what to do, or what not to report>" --why "<the reason, in your words>" --agent --repo-dir <clone>
100
+ ```
101
+
102
+ The default `--source instruction` records the owner's instruction. For a finding of the loop,
103
+ `--finding <id> --source judged` (a `wrong` verdict with a reason) or `--source fixed` (a
104
+ convention the loop marked probably fixed) ties the entry to the loop's history instead.
105
+ 3. Check whether it can be proposed: `wachiman memory candidates --repo-dir <clone>` prints
106
+ `proposable` or `not proposable: <reason>` (for example, not enough evidence yet). If it is not
107
+ proposable, do not ask for approval: tell the owner in one sentence that the candidate is
108
+ recorded on this laptop and why it cannot be proposed yet, and stop.
109
+ 4. If it is proposable, show the owner the exact text: `wachiman memory show <id> --repo-dir <clone>`.
110
+ Ask whether to propose it, and say why. Do not paraphrase the text you show.
111
+ 5. Only on a yes, run `wachiman memory propose <id> --repo-dir <clone>`. It opens a draft pull
112
+ request for a person to merge. On a no, stop; the candidate stays on this laptop.
113
+
114
+ Never propose without the owner's yes.
115
+
116
+ **What belongs in memory.** Belongs: how code is written here (readable before terse), what a test
117
+ must have, how documents and ADRs are kept, behaviour that is intentional and looks like a bug.
118
+ Does not belong: the details of one feature, a one-time exception, the temporary state of a
119
+ migration, anything a formatter or linter can enforce, anything already in a hand-written
120
+ instruction file. If an entry is in doubt, do not add it; tell the owner instead.
121
+
81
122
  ## Never
82
123
 
83
124
  | Tempting | Instead |
@@ -89,3 +130,5 @@ Tell the developer, in this order:
89
130
  | Running with `ANTHROPIC_API_KEY` set | `env -u ANTHROPIC_API_KEY wachiman loop ...`; the subscription pays |
90
131
  | Editing files under `~/.wachiman` to reset or close a loop | `--base <ref>` starts a new loop |
91
132
  | Claiming the branch is approved or safe | Report the outcome and its limits |
133
+ | Copying the owner's reply into a memory rule | Draft the rule, show `memory show <id>`, and ask |
134
+ | Running `memory propose` without the owner's yes | Ask first; it opens a pull request |
@@ -379,7 +379,7 @@ function removeProfile(cmd: Extract<ProfileCommand, { kind: "remove" }>, env: Re
379
379
  function loginProfile(cmd: Extract<ProfileCommand, { kind: "login" }>, env: Record<string, string | undefined>, io: CommandIo, deps: AccountDeps) {
380
380
  const home = wachimanHome(env);
381
381
  if (parseProfileRef(cmd.profile).kind === "default") {
382
- throw new UsageError("`default` is your own claude: sign in with your own claude (run it and use /login).");
382
+ throw new UsageError("`default` is your own claude: sign in with `claude auth login`.");
383
383
  }
384
384
  if (!(deps.interactive ?? isInteractive(env, { stdin: process.stdin.isTTY === true, stdout: process.stdout.isTTY === true }))) {
385
385
  throw new UsageError("profile login needs a terminal: run it yourself in a terminal, not from an agent or a pipe.");
@@ -609,12 +609,13 @@ export function parseSetupArgs(argv: string[], repoDir: string): SetupOptions |
609
609
  * The end of `setup`: the compact doctor summary and the suggested `wachiman local` line, on stderr.
610
610
  * Returns the exit code the summary decides (1 when a required check failed; the binding stays written).
611
611
  */
612
- export function closeSetup(repoDir: string, env: Record<string, string | undefined>, io: CommandIo, deps: AccountDeps = {}): number {
612
+ export function closeSetup(repoDir: string, env: Record<string, string | undefined>, io: CommandIo, deps: AccountDeps = {}, result?: { failedRequired?: number }): number {
613
613
  const report = buildDoctorReport(
614
614
  { repoDir, allProfiles: false, json: false, redactPaths: false },
615
615
  env,
616
616
  { spawn: deps.spawn, git: deps.git, userHome: deps.userHome, ...deps.doctor },
617
617
  );
618
+ if (result) result.failedRequired = report.failedRequired;
618
619
  const width = Math.max(...report.checks.map((r) => r.id.length));
619
620
  io.stderr(`doctor: ${report.checks.length} checks, ${report.failedRequired} required failed`);
620
621
  for (const row of report.checks) if (row.status === "fail" || row.status === "warn") for (const line of renderRow(row, width)) io.stderr(line);
@@ -175,7 +175,7 @@ function* confirmSteps(p: ResolvedProfile, env: Env, io: ConfirmIo): Generator<P
175
175
  const { profile } = p;
176
176
  const label = profile.kind === "default" ? "default" : profile.name;
177
177
  const login =
178
- profile.kind === "default" ? "sign in with your own `claude` (run it and use /login)" : `wachiman profile login ${profile.name}`;
178
+ profile.kind === "default" ? "sign in with your own claude: `claude auth login`" : `wachiman profile login ${profile.name}`;
179
179
  const configDir = profile.kind === "default" ? undefined : profile.configDir;
180
180
 
181
181
  if (configDir !== undefined && !io.isDirectory(configDir)) {
@@ -42,6 +42,30 @@ export interface ProfileList {
42
42
  profiles: ProfileListEntry[];
43
43
  }
44
44
 
45
+ export interface DetectedClaudeDir {
46
+ /** The profile name proposed for it: the suffix of `~/.claude-<suffix>`. */
47
+ name: string;
48
+ configDir: string;
49
+ }
50
+
51
+ /**
52
+ * The `~/.claude-<name>` directories in the person's home that no profile registers: the
53
+ * configuration directories people keep for a second account, usually reached through a shell alias
54
+ * or function that sets CLAUDE_CONFIG_DIR, which Wachiman cannot see. Looks at the listing only.
55
+ */
56
+ export function detectClaudeDirs(userHome: string, config: WachimanConfigV1 | undefined): DetectedClaudeDir[] {
57
+ const registered = new Set(Object.values(config?.profiles ?? {}).map((p) => p.configDir));
58
+ try {
59
+ return readdirSync(userHome, { withFileTypes: true })
60
+ .filter((d) => d.isDirectory() && d.name.startsWith(".claude-"))
61
+ .map((d) => ({ name: d.name.slice(".claude-".length).toLowerCase(), configDir: join(userHome, d.name) }))
62
+ .filter((d) => /^[a-z0-9][a-z0-9-]{0,31}$/.test(d.name) && !registered.has(d.configDir))
63
+ .sort((a, b) => a.name.localeCompare(b.name));
64
+ } catch {
65
+ return [];
66
+ }
67
+ }
68
+
45
69
  /** Registered profiles plus the `claude-*` directories under the home that no entry names. Looks at the home's listing only. */
46
70
  export function buildProfileList(home: string, config: WachimanConfigV1 | undefined): ProfileList {
47
71
  const profiles: ProfileListEntry[] = Object.entries(config?.profiles ?? {}).map(([name, entry]) => ({
package/src/cli.ts CHANGED
@@ -25,7 +25,11 @@
25
25
  * wachiman doctor explain what a local run would use and what would fail
26
26
  * wachiman profile … list, create, add, login, remove and default account profiles
27
27
  * wachiman project show|unbind inspect or remove this repository's binding
28
+ * wachiman memory check|archive|candidates|add|show|propose repository memory in .wachiman/memory (src/memory/)
29
+ * wachiman upgrade [--check] update the CLI, then the workflow pin in this repository (src/upgrade/)
28
30
  * wachiman skills install|uninstall copy the agent skills into place, or remove what was copied
31
+ * wachiman pr-template show|install|status|check|format|risk|strip the PR description template: install it,
32
+ * report its state, check and reorder a description, and compute the risk floor
29
33
  * wachiman --setup-profile [name] sign in an isolated Claude Code profile under the Wachiman home
30
34
  *
31
35
  * Exit codes: 0 posted or nothing to do; 1 engine error (nothing posted); 2 usage error; 3 the spend
@@ -43,22 +47,26 @@ import { parseStatusArgs, runStatus } from "./status/command";
43
47
  import { parseDashboardArgs, runDashboard } from "./store/command";
44
48
  import { parseLedgerArgs, runLedger } from "./ledger-read/command";
45
49
  import { pullLedger } from "./ledger-read/pull";
46
- import { LedgerStopped, SpendLimitReached, comment, defaultGh, isThreadQuestion, review, threadReplies, type Deps, type GhFn, type ReviewLineComment } from "./engine";
50
+ import { LedgerStopped, SpendLimitReached, comment, defaultGh, isThreadQuestion, review, threadReplies, withBaseSettings, type Deps, type GhFn, type ReviewLineComment } from "./engine";
47
51
  import { parseLocalArgs, runLocal } from "./local";
48
52
  import { parseLoopArgs, runLoop } from "./loop/command";
49
53
  import { parseAskArgs, runAsk } from "./local-ask";
50
54
  import { parseProfileArgs, parseProjectArgs, runProfile, runProject } from "./accounts/commands";
51
55
  import { wachimanHome } from "./accounts/config";
52
56
  import { parseSkillsArgs, runSkills } from "./skills/install";
57
+ import { runPrTemplate } from "./pr-template/run";
58
+ import { runMemory } from "./memory/command";
59
+ import { parseUpgradeArgs, runUpgrade } from "./upgrade/command";
53
60
  import { parseDoctorArgs, runDoctor } from "./doctor/run";
54
- import { parseInitFlags } from "./init/args";
61
+ import { ghLogin } from "./init/github-login";
55
62
  import { DEFAULT_WORKFLOW_REF } from "./init/options";
56
63
  import { projectCommands } from "./wizard/command";
57
64
  import { DEFAULT_ISOLATED_NAME, setupProfile } from "./profiles";
58
65
  import { resetConfidence } from "./fidelity/sink";
59
66
  import { getProvider, PROVIDER_NAMES, UnknownProviderError } from "./providers";
60
67
  import { parseSetupFlags } from "./setup/args";
61
- import { runInitCommand } from "./init/run";
68
+ import { failureDocument, printDocument } from "./init/json";
69
+ import { runInitFromArgv } from "./init/run";
62
70
  import { runSetupCommand } from "./setup/run";
63
71
  import { commandHelp, helpFor, isCommand, rootHelp } from "./help";
64
72
  import { shouldLaunch } from "./wizard/interactive";
@@ -103,6 +111,27 @@ export function extractRepoDir(argv: string[]) {
103
111
  return { repoDir, rest };
104
112
  }
105
113
 
114
+ /** The `--repo-dir` the caller typed, resolved to an absolute path; the working directory when there is none. Never throws: it only reads the arguments. */
115
+ export function requestedRepoDir(argv: string[]): string {
116
+ let value: string | undefined;
117
+ for (let i = 0; i < argv.length; i++) {
118
+ if (argv[i] === "--repo-dir") value = argv[++i];
119
+ else if (argv[i].startsWith("--repo-dir=")) value = argv[i].slice("--repo-dir=".length);
120
+ }
121
+ return resolve(value || ".");
122
+ }
123
+
124
+ /** Whether a question can be asked: Bun's `prompt` reads stdin and writes to stdout, and the question itself goes to stderr, so all three must be terminals. */
125
+ export function canAskOnTerminal(stdin: { isTTY?: boolean }, stdout: { isTTY?: boolean }, stderr: { isTTY?: boolean }): boolean {
126
+ return stdin.isTTY === true && stdout.isTTY === true && stderr.isTTY === true;
127
+ }
128
+
129
+ /** Asks one question on the terminal and returns the typed answer (Bun's synchronous `prompt`); only used when `canAskOnTerminal`. */
130
+ function askOnTerminal(question: string): string | undefined {
131
+ console.error(question);
132
+ return prompt("Your choice (1 or 2):") ?? undefined;
133
+ }
134
+
106
135
  /**
107
136
  * Writes all of `text` to a file descriptor before returning. `process.stdout.write` is
108
137
  * asynchronous on a pipe, and `process.exit` right after it cuts a long report short.
@@ -193,13 +222,13 @@ async function runWizard(mode: "setup" | "init", args: string[], repoDir: string
193
222
  if (flags.help) return (io.stdout(commandHelp(["setup"])!), 0);
194
223
  return runSetupCommand(flags, env, io, { doctor: { version } });
195
224
  }
196
- const flags = parseInitFlags(args, repoDir);
197
- if (flags.help) return (io.stdout(commandHelp(["init"])!), 0);
198
- return runInitCommand(flags, env, io, {
225
+ if (args.includes("--help") || args.includes("-h")) return (io.stdout(commandHelp(["init"])!), 0);
226
+ return runInitFromArgv(args, repoDir, env, io, {
199
227
  version,
200
228
  defaultWorkflowRef: DEFAULT_WORKFLOW_REF,
201
- // Choosing local/both already requests setup; keep its final write confirmation.
202
- bindNow: (prompter, mode) => runSetupCommand({ repoDir }, env, io, { doctor: { version }, interactive: true, prompter, fromInit: true, initMode: mode, unboundHints: projectCommands("setup", repoDir, process.cwd()) }),
229
+ githubLogin: ghLogin,
230
+ // Choosing local/both already requests setup, which saves the binding without asking again.
231
+ bindNow: (prompter, mode, closing) => runSetupCommand({ repoDir }, env, io, { doctor: { version }, interactive: true, prompter, fromInit: true, initMode: mode, unboundHints: projectCommands("setup", repoDir, process.cwd()), closing }),
203
232
  });
204
233
  }
205
234
 
@@ -218,7 +247,7 @@ export function runResetConfidence(args: string[], env: Record<string, string |
218
247
  if (!/^\d+$/.test(prArg ?? "") || pr <= 0) throw new UsageError("reset-confidence needs a pull request number.");
219
248
  let commit: string | undefined;
220
249
  for (let i = 0; i < flags.length; i++) {
221
- if (flags[i] !== "--commit" || !flags[i + 1]) throw new UsageError(`reset-confidence: unexpected "${flags[i]}".`);
250
+ if (flags[i] !== "--commit" || !flags[i + 1]) throw new UsageError(`reset-confidence: unexpected "${flags[i]}". Accepted form: --commit <sha>.`);
222
251
  commit = flags[++i];
223
252
  }
224
253
  const config = loadConfig(env);
@@ -325,7 +354,7 @@ export async function main(argv: string[], env: Record<string, string | undefine
325
354
  const { repoDir, rest: args } = extractRepoDir(argv);
326
355
  if (mode === "local") {
327
356
  // No GitHub: no token, no repository, no `gh` function anywhere on this path.
328
- return runLocal(parseLocalArgs(args.slice(1)), repoDir, env, {
357
+ return await runLocal(parseLocalArgs(args.slice(1)), repoDir, env, {
329
358
  stdout: (text) => writeAll(1, text),
330
359
  stderr: (line) => console.error(line),
331
360
  engineVersion: readVersion(),
@@ -333,7 +362,7 @@ export async function main(argv: string[], env: Record<string, string | undefine
333
362
  }
334
363
  if (mode === "loop") {
335
364
  // Like `local`: no GitHub token, no `gh` function anywhere on this path.
336
- return runLoop(parseLoopArgs(args.slice(1)), repoDir, env, {
365
+ return await runLoop(parseLoopArgs(args.slice(1)), repoDir, env, {
337
366
  stdout: (text) => writeAll(1, text),
338
367
  stderr: (line) => console.error(line),
339
368
  engineVersion: readVersion(),
@@ -341,15 +370,28 @@ export async function main(argv: string[], env: Record<string, string | undefine
341
370
  }
342
371
  if (mode === "ask") {
343
372
  // Like `local`: no GitHub token, no `gh` function anywhere on this path.
344
- return runAsk(parseAskArgs(args.slice(1)), repoDir, env, {
373
+ return await runAsk(parseAskArgs(args.slice(1)), repoDir, env, {
345
374
  stdout: (text) => writeAll(1, text),
346
375
  stderr: (line) => console.error(line),
347
376
  engineVersion: readVersion(),
348
377
  });
349
378
  }
379
+ if (mode === "pr-template") {
380
+ // No model, no provider; `check --pr` and `risk` shell out to gh and git in the repository directory.
381
+ return runPrTemplate(args.slice(1), repoDir, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) });
382
+ }
383
+ if (mode === "memory") {
384
+ // No model, no provider. `check`, `candidates`, `add` and `show` read files and git; `propose` also pushes with the developer's git credentials and calls `gh`.
385
+ return runMemory(args.slice(1), repoDir, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) }, { env, ...(canAskOnTerminal(process.stdin, process.stdout, process.stderr) ? { ask: askOnTerminal } : {}) });
386
+ }
350
387
  if (mode === "doctor" || mode === "profile" || mode === "project") {
351
388
  return runAccountCommand(mode, args.slice(1), repoDir, env);
352
389
  }
390
+ if (mode === "upgrade") {
391
+ const parsed = parseUpgradeArgs(args.slice(1), repoDir);
392
+ if ("help" in parsed) return (writeAll(1, commandHelp(["upgrade"])!), 0);
393
+ return runUpgrade(parsed, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) }, { version: readVersion() });
394
+ }
353
395
  if (mode === "setup" || mode === "init") return await runWizard(mode, args.slice(1), repoDir, env);
354
396
  if (mode === "status") {
355
397
  const parsed = parseStatusArgs(args.slice(1));
@@ -384,13 +426,39 @@ export async function main(argv: string[], env: Record<string, string | undefine
384
426
  // decision 4); the rest of the thread-only run is unchanged. Its trigger is the question's, not
385
427
  // an automatic run's, so it does not spend from the automatic ceiling.
386
428
  const effective = routeMode(mode, commentLine, env.REQUEST ?? "", loaded.mention);
387
- const config = effective === "comment" ? { ...loaded, trigger: "comment" } : effective === "threads" ? { ...loaded, trigger: "thread" } : loaded;
388
- const provider = getProvider(config.provider, config);
429
+ const routed = effective === "comment" ? { ...loaded, trigger: "comment" } : effective === "threads" ? { ...loaded, trigger: "thread" } : loaded;
430
+ const mainProvider = (c: typeof routed) => getProvider(c.provider, c);
389
431
  // The verifier is its own adapter on its own model, always at effort high (ADR 0027).
390
- const verifier = config.verify && mode !== "threads" ? getProvider(config.provider, { ...config, model: config.verifierModel, effort: "high" }) : undefined;
432
+ const verifier = routed.verify && mode !== "threads" ? getProvider(routed.provider, { ...routed, model: routed.verifierModel, effort: "high" }) : undefined;
433
+ let provider = mainProvider(routed);
391
434
  required(env, "GH_TOKEN");
392
435
  const repo = required(env, "GITHUB_REPOSITORY");
393
436
  const request = effective === "comment" ? required(env, "REQUEST") : "";
437
+ // Before any call is paid for: a missing binary or settings file would fail every batch.
438
+ try {
439
+ provider.preflight();
440
+ verifier?.preflight();
441
+ } catch (error) {
442
+ console.error(`wachiman: ${error instanceof Error ? error.message : error}`);
443
+ return 1;
444
+ }
445
+ // Where no workflow input or WACHIMAN_* set them, the model and the effort come from the base
446
+ // commit's `.wachiman.yml` (never the head's, ADR 0049), so the estimate, the size gate and every
447
+ // call agree. The adapters are rebuilt only when the file changed one of them.
448
+ let config = withBaseSettings(routed, defaultGh, repo, pr, (line) => console.log(line), (line) => console.error(line));
449
+ if (config.model !== routed.model || config.effort !== routed.effort) {
450
+ // Settings never change the verifier (own model, effort high), so only the main provider is rebuilt.
451
+ const before = provider;
452
+ provider = mainProvider(config);
453
+ try {
454
+ provider.preflight();
455
+ } catch (error) {
456
+ // A value the base file set that this provider cannot use must not block the pull request that fixes it.
457
+ console.error(`wachiman: ignored model/effort from .wachiman.yml at the base commit: ${error instanceof Error ? error.message : error}; using the workflow's values.`);
458
+ provider = before;
459
+ config = routed;
460
+ }
461
+ }
394
462
  const costs: CallCost[] = [];
395
463
  const ledgerNotes: string[] = [];
396
464
  const deps: Deps = {
@@ -405,18 +473,10 @@ export async function main(argv: string[], env: Record<string, string | undefine
405
473
  log: (line) => console.log(line),
406
474
  warn: (line) => console.error(line),
407
475
  };
408
- // Before any call is paid for: a missing binary or settings file would fail every batch.
409
476
  try {
410
- provider.preflight();
411
- verifier?.preflight();
412
- } catch (error) {
413
- console.error(`wachiman: ${error instanceof Error ? error.message : error}`);
414
- return 1;
415
- }
416
- try {
417
- if (effective === "review") review(deps, repo, pr, rest);
418
- else if (effective === "threads") threadReplies(deps, repo, pr, env.WACHIMAN_COMMENT_AUTHOR || undefined);
419
- else comment(deps, repo, pr, request, env.WACHIMAN_COMMENT_AUTHOR || undefined, commentLine);
477
+ if (effective === "review") await review(deps, repo, pr, rest);
478
+ else if (effective === "threads") await threadReplies(deps, repo, pr, env.WACHIMAN_COMMENT_AUTHOR || undefined);
479
+ else await comment(deps, repo, pr, request, env.WACHIMAN_COMMENT_AUTHOR || undefined, commentLine);
420
480
  } finally {
421
481
  // Also after a failed run: the calls it made were paid for.
422
482
  writeStepSummary(costs, env, undefined, ledgerNotes);
@@ -424,6 +484,11 @@ export async function main(argv: string[], env: Record<string, string | undefine
424
484
  return 0;
425
485
  } catch (error) {
426
486
  if (error instanceof UsageError || error instanceof UnknownProviderError) {
487
+ // `init --json` promises one document on stdout even when the arguments fail before init runs (a bad --repo-dir).
488
+ if (mode === "init" && argv.includes("--json")) {
489
+ printDocument((text) => writeAll(1, text), failureDocument({ mode: null, dryRun: argv.includes("--dry-run"), repoDir: requestedRepoDir(argv), report: {}, code: "usage", message: error.message }));
490
+ return 2;
491
+ }
427
492
  return usageError(error.message, mode);
428
493
  }
429
494
  if (error instanceof SpendLimitReached) {
package/src/config.ts CHANGED
@@ -14,6 +14,9 @@ export type Trigger = string;
14
14
  /** Whether a run started by `trigger` spends from the pull request's automatic ceiling. */
15
15
  export const isAutomatic = (trigger: Trigger | undefined) => trigger !== undefined && trigger !== "comment";
16
16
 
17
+ /** Where a setting's value came from: the environment (a workflow input or `WACHIMAN_*`), the repository's `.wachiman.yml`, or the built-in default. */
18
+ export type SettingSource = "env" | "file" | "default";
19
+
17
20
  export type LimitMode = "fail" | "notice";
18
21
  export type LedgerUnavailableMode = "run" | "stop";
19
22
 
@@ -64,8 +67,13 @@ export interface EngineConfig {
64
67
  * reviewed, without reading the previous-review marker. Only together with `dryRun`.
65
68
  */
66
69
  fullReview: boolean;
67
- /** The provider's default (`DEFAULT_MODELS`) when unset. */
70
+ /**
71
+ * `WACHIMAN_MODEL`, else `model` of the repository's `.wachiman.yml` (`applyRepoSettings`), else the
72
+ * provider's default (`DEFAULT_MODELS`).
73
+ */
68
74
  model: string;
75
+ /** Where `model` came from. `loadConfig` sets `env` or `default`; `applyRepoSettings` may change `default` to `file`. */
76
+ modelSource?: SettingSource;
69
77
  provider: string;
70
78
  /** `WACHIMAN_PRICE_PER_MTOK`: "input,cached_input,output" USD per million tokens, for a Codex model without a built-in price. */
71
79
  pricePerMTok?: string;
@@ -74,6 +82,8 @@ export interface EngineConfig {
74
82
  * alter reviews. Passed as `--effort` (Claude Code) or `model_reasoning_effort` (Codex).
75
83
  */
76
84
  effort: Effort;
85
+ /** Where `effort` came from, as for `modelSource`. */
86
+ effortSource?: SettingSource;
77
87
  /**
78
88
  * `WACHIMAN_MAX_TURNS`: the most agent turns one provider call may take. Passed as
79
89
  * `--max-turns` (Claude Code); Codex has no equivalent and ignores it.
@@ -122,6 +132,19 @@ export interface EngineConfig {
122
132
  * the pull request review only: `wachiman local` never grades.
123
133
  */
124
134
  confidence: boolean;
135
+ /**
136
+ * `WACHIMAN_PRIORITY_TRIAL`: the A/B of the finding priority (ADR 0059 decision 10). Each pull
137
+ * request review gets the old Important/Nit word or the priority row, by a hash of the repository
138
+ * and the pull request number, and the result records `arm`. On only with the exact value `1`;
139
+ * off, every review shows the priority and records no arm. Local reviews never join the trial.
140
+ */
141
+ priorityTrial: boolean;
142
+ /**
143
+ * `WACHIMAN_MEMORY_PROPOSALS`: a thread reply may propose an entry for repository memory from the
144
+ * operator's instruction (layer 5); the operator approves it with `/wachiman remember <id>`. Off by
145
+ * default; enabled only by `1` or `true`. Read by the thread-only run.
146
+ */
147
+ memoryProposals: boolean;
125
148
  }
126
149
 
127
150
  /** The verifier's model when `WACHIMAN_VERIFIER_MODEL` is unset (Claude Code only). */
@@ -149,7 +172,7 @@ export function readSetting(env: Env, name: string, warn: (line: string) => void
149
172
  * else the default. An unknown value is a configuration error: a silent fallback would run the
150
173
  * review at an effort nobody chose.
151
174
  */
152
- function readEffort(env: Env, warn: (line: string) => void): Effort {
175
+ function readEffort(env: Env, warn: (line: string) => void): { value: Effort; source: SettingSource } {
153
176
  const current = readSetting(env, "EFFORT", warn);
154
177
  const old = readSetting(env, "REASONING_EFFORT", () => {});
155
178
  let name = "WACHIMAN_EFFORT";
@@ -161,11 +184,11 @@ function readEffort(env: Env, warn: (line: string) => void): Effort {
161
184
  name = "WACHIMAN_REASONING_EFFORT";
162
185
  }
163
186
  }
164
- if (raw === undefined) return DEFAULT_EFFORT;
187
+ if (raw === undefined) return { value: DEFAULT_EFFORT, source: "default" };
165
188
  if (!(EFFORTS as readonly string[]).includes(raw)) {
166
189
  throw new UsageError(`${name} must be one of ${EFFORTS.join(", ")}, got "${raw}".`);
167
190
  }
168
- return raw as Effort;
191
+ return { value: raw as Effort, source: "env" };
169
192
  }
170
193
 
171
194
  export function loadConfig(env: Env, warn: (line: string) => void = console.error): EngineConfig {
@@ -185,6 +208,7 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
185
208
  throw new UsageError(`WACHIMAN_ON_PROVIDER_UNAVAILABLE must be warn or fail, got "${onProviderUnavailable}".`);
186
209
  }
187
210
  const provider = get("PROVIDER") ?? "claude-code";
211
+ const modelFromEnv = get("MODEL");
188
212
  const dryRun = get("DRY_RUN") === "1";
189
213
  const fullReview = get("FULL_REVIEW") === "1";
190
214
  if (fullReview && !dryRun) {
@@ -202,6 +226,10 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
202
226
  if (verify && verifierModel === undefined) {
203
227
  throw new UsageError(`WACHIMAN_VERIFY needs WACHIMAN_VERIFIER_MODEL with the ${provider} provider: the default verifier is a Claude model.`);
204
228
  }
229
+ const memoryProposalsRaw = get("MEMORY_PROPOSALS");
230
+ if (memoryProposalsRaw !== undefined && !["0", "1", "true", "false"].includes(memoryProposalsRaw)) {
231
+ throw new UsageError(`WACHIMAN_MEMORY_PROPOSALS must be 1, true, 0 or false (unset means off), got "${memoryProposalsRaw}".`);
232
+ }
205
233
  const confidenceRaw = get("CONFIDENCE");
206
234
  if (confidenceRaw !== undefined && !["0", "1", "true", "false"].includes(confidenceRaw)) {
207
235
  throw new UsageError(`WACHIMAN_CONFIDENCE must be 1, true, 0 or false (unset means off), got "${confidenceRaw}".`);
@@ -230,12 +258,12 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
230
258
  `WACHIMAN_LEDGER_URL must start with https:// (http://localhost and http://127.0.0.1 are allowed for tests), got "${ledgerUrl}".`,
231
259
  );
232
260
  }
233
- // With a ledger, `review-platform.yml` grants `id-token: write`, so the request token is in the
261
+ // With a ledger, `wachiman-platform.yml` grants `id-token: write`, so the request token is in the
234
262
  // engine's environment; a Codex sandbox could read it from /proc and mint tokens as this job.
235
263
  // Without `ledger_url` nothing uses the token and the guard does not apply.
236
264
  if (ledgerUrl !== undefined && provider !== "claude-code" && env.ACTIONS_ID_TOKEN_REQUEST_TOKEN !== undefined) {
237
265
  throw new UsageError(
238
- `WACHIMAN_PROVIDER ${provider} cannot run in a job that holds an OIDC request token: its sandbox can read it from the engine's environment. Use claude-code, or call review.yml instead of review-platform.yml.`,
266
+ `WACHIMAN_PROVIDER ${provider} cannot run in a job that holds an OIDC request token: its sandbox can read it from the engine's environment. Use claude-code, or call review.yml instead of wachiman-platform.yml.`,
239
267
  );
240
268
  }
241
269
  return {
@@ -250,10 +278,12 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
250
278
  batchChars: number("BATCH_CHARS", 140000, true),
251
279
  dryRun,
252
280
  fullReview,
253
- model: get("MODEL") ?? DEFAULT_MODELS[provider as keyof typeof DEFAULT_MODELS] ?? DEFAULT_MODELS["claude-code"],
281
+ model: modelFromEnv ?? DEFAULT_MODELS[provider as keyof typeof DEFAULT_MODELS] ?? DEFAULT_MODELS["claude-code"],
282
+ modelSource: modelFromEnv === undefined ? "default" : "env",
254
283
  provider,
255
284
  pricePerMTok: get("PRICE_PER_MTOK"),
256
- effort,
285
+ effort: effort.value,
286
+ effortSource: effort.source,
257
287
  maxTurns: number("MAX_TURNS", DEFAULT_MAX_TURNS, true),
258
288
  callTimeoutS: number("CALL_TIMEOUT_S", DEFAULT_CALL_TIMEOUT_S, true),
259
289
  onProviderUnavailable,
@@ -266,6 +296,8 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
266
296
  verifyBudgetUsd: number("VERIFY_BUDGET_USD", 1),
267
297
  verifierModel: verifierModel ?? DEFAULT_VERIFIER_MODEL,
268
298
  confidence: confidenceRaw === "1" || confidenceRaw === "true",
299
+ priorityTrial: get("PRIORITY_TRIAL") === "1",
300
+ memoryProposals: memoryProposalsRaw === "1" || memoryProposalsRaw === "true",
269
301
  ledgerUrl,
270
302
  dailyBudgetUsd: get("DAILY_BUDGET_USD") === undefined ? undefined : number("DAILY_BUDGET_USD", 0),
271
303
  weeklyBudgetUsd: get("WEEKLY_BUDGET_USD") === undefined ? undefined : number("WEEKLY_BUDGET_USD", 0),