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/src/engine.ts CHANGED
@@ -33,7 +33,12 @@ import { closeSync, mkdtempSync, openSync, readFileSync, readSync, realpathSync,
33
33
  import { tmpdir } from "node:os";
34
34
  import { join } from "node:path";
35
35
  import { estimateReview, sizeGate, suggestedBudget, type ReviewEstimate } from "./estimate";
36
- import { isAutomatic, operatorProblem, type EngineConfig, type LimitMode, type Trigger } from "./config";
36
+ import { UsageError, isAutomatic, operatorProblem, type EngineConfig, type LimitMode, type Trigger } from "./config";
37
+ import { SETTINGS_PATH, applyRepoSettings, fileSettingsNote, ignoredSettingsNote, matchPathRule, parseRepoSettings, pathsEdited, touchesSettingsFile, wantsRepoSettings, withPolicyEditRule, type PathRule, type PathSeverity, type RepoSettings } from "./repo-settings";
38
+ import { newCandidate, proposability, renderEntry, today, type Candidate } from "./memory/candidates";
39
+ import { renderProposal } from "./memory/proposal";
40
+ import { MEMORY_DIR, cutMemoryNote, loadMemory, memoryNotice, memoryRecord, type MemoryLoad, type MemorySource } from "./memory/load";
41
+ import { MATCH_SCHEMA, applyMatches, buildMatchPrompt, matchRequest, parseMatches, planExceptions, MUTED_HEADING, renderConventions, renderMuting, type ExceptionPlan, type MutedFinding } from "./memory/mute";
37
42
  import {
38
43
  LedgerBadAnswer,
39
44
  LedgerNotPermitted,
@@ -73,6 +78,7 @@ import {
73
78
  type LineCounter,
74
79
  } from "./contracts";
75
80
  import { describeCall } from "./call-message";
81
+ import { armFor, priorityOf, PRIORITY_GLOSS, PRIORITY_WORD, type Arm, type Priority } from "./priority";
76
82
  import {
77
83
  annotateUnverified,
78
84
  applyVerdicts,
@@ -107,7 +113,7 @@ import { fidelitySummary } from "./fidelity/summary";
107
113
  import { publishConfidence } from "./fidelity/sink";
108
114
  import type { Fidelity } from "./fidelity/types";
109
115
  import type { ProviderErrorClass } from "./providers/errors";
110
- import type { Effort, ProviderAdapter } from "./providers/types";
116
+ import type { Effort, ProviderAdapter, ProviderAuth } from "./providers/types";
111
117
  import { renderDataPathQuestions, selectQuestions, type DataPathQuestion } from "./questions";
112
118
  import { buildRiskMap, renderRiskMap, wellFormed, type JudgementItem, type RiskFact, type RiskMap } from "./risk";
113
119
  import { ASK_SCHEMA, buildAskPrompt, checkRefs, isAskAnswer, renderAnswer } from "./ask";
@@ -138,8 +144,8 @@ export interface ReviewFile {
138
144
  patch?: string;
139
145
  /** The file's blob at the compared commit: equal blobs are equal contents. Absent for a removed file. */
140
146
  sha?: string;
141
- /** The name before a rename, as GitHub reports it. */
142
- previous_filename?: string;
147
+ /** The name before a rename, as GitHub reports it: `null` for a file that was not renamed. */
148
+ previous_filename?: string | null;
143
149
  }
144
150
 
145
151
  /** @deprecated The name before the review core; use `ReviewFile`. Removed in the next minor release. */
@@ -250,7 +256,7 @@ export interface Review {
250
256
  }
251
257
 
252
258
  /** `force` is `--force` after `review`: spend past a spent limit. Only the operator's comment may honour it. */
253
- export type Command = { kind: "review"; paths: string[]; force: boolean } | { kind: "answer" };
259
+ export type Command = { kind: "review"; paths: string[]; force: boolean } | { kind: "remember"; id: string } | { kind: "answer" };
254
260
 
255
261
  export const DEFAULT_EXCLUDE = [
256
262
  "**/bun.lock",
@@ -271,13 +277,32 @@ export const DEFAULT_EXCLUDE = [
271
277
  // `claude-review` is still read so repositories reviewed under that name keep their incremental state.
272
278
  const MARKER_SOURCE = "<!-- (?:wachiman|claude-review) sha=([A-Za-z0-9]+) -->";
273
279
  const short = (sha: string) => sha.slice(0, 7);
280
+ /** One finding as a line: `<lead> · 🟠📝 **Fix · docs: stale cell (confidence high)**`. The lead stays outside the bold: the precision report reads the bold part. */
281
+ const oneLineLabel = (lead: string, f: Finding, status?: string) =>
282
+ `${lead} · ${SEVERITY[f.severity].emoji}${TOPIC[f.topic].emoji} **${SEVERITY[f.severity].word} · ${TOPIC[f.topic].word}: ${neutralise(f.title)}${detail(f, status)}**`;
283
+
284
+ /**
285
+ * The priority word of a finding as a reader sees it: `Should`, or `Should · Pre-existing` for a
286
+ * finding that predates the change (ADR 0059 decision 14). A result written before `priority`
287
+ * existed is priced on the fly with table v1.
288
+ */
289
+ export const priorityLead = (f: Finding & { origin?: Origin; priority?: Priority }) => {
290
+ const word = PRIORITY_WORD[f.priority ?? priorityOf(f).priority];
291
+ return f.origin === "pre-existing" ? `${word} · Pre-existing` : word;
292
+ };
293
+
274
294
  /**
275
- * `Important · 🟠📝 **Fix · docs: stale cell (confidence high)**`: the tier word, both emojis, then
276
- * the severity, topic and title in words, then the model's confidence when it gave one. The tier
277
- * stays outside the bold: the precision report reads the bold part.
295
+ * `Should · 🟠📝 **Fix · docs: stale cell (confidence high)**`: the label every list in the review
296
+ * body and every local report shows, led by the priority word.
278
297
  */
279
- export const label = (f: Finding & { origin?: Origin }, status?: string) =>
280
- `${tierWord(f)} · ${SEVERITY[f.severity].emoji}${TOPIC[f.topic].emoji} **${SEVERITY[f.severity].word} · ${TOPIC[f.topic].word}: ${neutralise(f.title)}${detail(f, status)}**`;
298
+ export const label = (f: Finding & { origin?: Origin; priority?: Priority }, status?: string) => oneLineLabel(priorityLead(f), f, status);
299
+
300
+ /**
301
+ * `Important · 🟠📝 **Fix · docs: stale cell (confidence high)**`: today's label with the tier word,
302
+ * the one the model reads back from its own earlier comments (`legacyFindingComment`). It never
303
+ * shows the priority: the model must not see the word the reader sees.
304
+ */
305
+ export const legacyLabel = (f: Finding & { origin?: Origin }, status?: string) => oneLineLabel(tierWord(f), f, status);
281
306
  /** ` (confidence high, supported)`: the confidence the model gave and, for a local report, what the verifier found. */
282
307
  export const detail = (f: Finding, status?: string) => {
283
308
  const parts = [f.confidence ? `confidence ${f.confidence}` : "", status ?? ""].filter(Boolean);
@@ -294,6 +319,99 @@ export const BRAND = "👮 **Wachiman**";
294
319
  /** `text` after the brand, on the same first line. */
295
320
  export const branded = (text: string) => `${BRAND} · ${text}`;
296
321
 
322
+ /** `🟥🟥⬜ Medium`: one red square per level, filled from the left, always three. More red is more certain. */
323
+ export const confidenceMeter = (level: Confidence) => {
324
+ const filled = CONFIDENCE.length - CONFIDENCE.indexOf(level);
325
+ return `${"🟥".repeat(filled)}${"⬜".repeat(CONFIDENCE.length - filled)} ${level[0].toUpperCase()}${level.slice(1)}`;
326
+ };
327
+
328
+ /** A table cell of text Wachiman did not write: `|`, a backtick and a newline would break the row. */
329
+ const cell = (text: string) => text.replace(/\r?\n|\r/g, " ").replaceAll("|", "\\|").replaceAll("`", "\\`");
330
+ const uncell = (text: string) => text.replaceAll("\\|", "|").replaceAll("\\`", "`");
331
+
332
+ /** The Track record row. Layer 1 counts no outcomes, so every finding says so (spec decision 19). */
333
+ const TRACK_RECORD = "no record yet · seed";
334
+
335
+ /**
336
+ * The GitHub body of an inline finding, before the signature: a table whose first cell is the
337
+ * brand, then the model's body unchanged (spec 2026-11-14, "Inline finding"). `legacyFindingComment`
338
+ * undoes it for the model; the local sinks use `label`.
339
+ *
340
+ * The priority arm (the default) opens with a Priority row and leaves the tier word out of the
341
+ * Severity cell; the word arm of the trial is today's table. Both end with the Track record row.
342
+ */
343
+ export const inlineFindingBody = (f: Finding & { origin?: Origin; priority?: Priority }, arm: Arm = "priority") => {
344
+ const severity = `${SEVERITY[f.severity].emoji} ${SEVERITY[f.severity].word}`;
345
+ const word = f.priority ?? priorityOf(f).priority;
346
+ return [
347
+ `| ${BRAND} | ${cell(neutralise(f.title))} |`,
348
+ "|:--|:--|",
349
+ ...(arm === "priority"
350
+ ? [`| **Priority** | **${PRIORITY_WORD[word]}** · ${PRIORITY_GLOSS[word]}${f.origin === "pre-existing" ? " · Pre-existing" : ""} |`, `| **Severity** | ${severity} |`]
351
+ : [`| **Severity** | ${severity} · ${tierWord(f)} |`]),
352
+ `| **Area** | ${TOPIC[f.topic].emoji} ${TOPIC[f.topic].word} |`,
353
+ ...(f.confidence ? [`| **Confidence** | ${confidenceMeter(f.confidence)} |`] : []),
354
+ `| **Track record** | ${TRACK_RECORD} |`,
355
+ "",
356
+ neutralise(f.body),
357
+ ].join("\n");
358
+ };
359
+
360
+ const TABLE_HEAD = `| ${BRAND} | `;
361
+
362
+ /**
363
+ * The fields of an inline finding's table, or null when the comment does not open with one. The
364
+ * Severity cell is read with or without the tier word, and the Priority and Track record rows are
365
+ * ignored: severity, topic and confidence are all a reader of the table needs (ADR 0059).
366
+ */
367
+ export function parseInlineTable(body: string) {
368
+ if (!body.startsWith(TABLE_HEAD)) return null;
369
+ const rows = body.split("\n");
370
+ const end = rows.findIndex((r) => !r.startsWith("|"));
371
+ const table = rows.slice(0, end === -1 ? rows.length : end);
372
+ const value = (name: string) => table.find((r) => r.startsWith(`| **${name}** | `))?.slice(`| **${name}** | `.length).replace(/ \|$/, "");
373
+ const severity = value("Severity")?.match(/^(\S+) (Blocker|Fix|Consider|Info)(?: · (Important|Nit))?$/);
374
+ const area = value("Area")?.match(/^(\S+) ([a-z]+)$/);
375
+ if (!severity || !area || !table[0].endsWith(" |")) return null;
376
+ const confidence = value("Confidence")?.match(/^\S+ (High|Medium|Low)$/)?.[1].toLowerCase();
377
+ const priority = value("Priority")?.match(/^\*\*(Must|Should|Could|FYI)\*\*/)?.[1];
378
+ const preExisting = value("Priority")?.endsWith(" · Pre-existing") ?? false;
379
+ return {
380
+ rows: table.length,
381
+ title: uncell(table[0].slice(TABLE_HEAD.length, -2)),
382
+ // The tier word of the one-line label: the cell's own, or, in the priority arm, the one `tierWord` derives.
383
+ severity: { emoji: severity[1], word: severity[2], tier: severity[3] ?? tierWord({ severity: severity[2].toLowerCase() as Severity, ...(preExisting ? { origin: "pre-existing" as const } : {}) }) },
384
+ topic: { emoji: area[1], word: area[2] },
385
+ ...(priority ? { priority: { word: priority, preExisting } } : {}),
386
+ ...(confidence ? { confidence } : {}),
387
+ };
388
+ }
389
+
390
+ /**
391
+ * A finding comment as a one-line label again: an inline table becomes `branded(<lead> · label)`,
392
+ * the rest of the comment is untouched. A comment without a table is returned as is.
393
+ */
394
+ function findingLine(body: string, lead: (t: NonNullable<ReturnType<typeof parseInlineTable>>) => string): string {
395
+ const t = parseInlineTable(body);
396
+ if (!t) return body;
397
+ const detail = t.confidence ? ` (confidence ${t.confidence})` : "";
398
+ const line = branded(
399
+ `${lead(t)} · ${t.severity.emoji}${t.topic.emoji} **${t.severity.word} · ${t.topic.word}: ${t.title}${detail}**`,
400
+ );
401
+ return [line, ...body.split("\n").slice(t.rows)].join("\n");
402
+ }
403
+
404
+ /**
405
+ * A finding comment as the model reads it: an inline table becomes today's one-line label with the
406
+ * tier word (`branded(legacyLabel(f))`), whichever arm wrote it, so the Priority and Track record
407
+ * rows never reach the model. A comment without a table is returned as is.
408
+ */
409
+ export const legacyFindingComment = (body: string) => findingLine(body, (t) => t.severity.tier);
410
+
411
+ /** A finding comment as a person reads it in a list: the same line, led by the word its table showed. */
412
+ const shownFindingComment = (body: string) =>
413
+ findingLine(body, (t) => (t.priority ? `${t.priority.word}${t.priority.preExisting ? " · Pre-existing" : ""}` : t.severity.tier));
414
+
297
415
  /** The default command keyword. A slash command, so writing it notifies no GitHub account. */
298
416
  export const DEFAULT_MENTION = "/wachiman";
299
417
  /**
@@ -319,6 +437,14 @@ export function parseCommand(body: string, keyword = DEFAULT_MENTION): Command |
319
437
  // `paths` is every word after `review`, as before the ledger: `comment` drops `--force` from it only when a ledger is set.
320
438
  return { kind: "review", paths: rest, force: rest.includes("--force") };
321
439
  }
440
+ // `remember <id>` approves a memory entry the thread showed (layer 5); the id is seven hex characters. The
441
+ // approval is the whole comment: "thanks, /wachiman remember 4c1e9a2", a trailing word, or a question that merely
442
+ // starts with the word ("remember the lessons") stays an ordinary comment. It starts the comment, as the write
443
+ // job's gate (`startsWith`) requires, so leading whitespace makes an ordinary comment; trailing whitespace is fine.
444
+ if (words[0]?.toLowerCase() === "remember" && words.length === 2 && /^[0-9a-f]{7}$/i.test(words[1])) {
445
+ const whole = body.match(new RegExp(`^${mentionSource(keyword)}\\s+remember\\s+[0-9a-f]{7}\\s*$`, "i"));
446
+ if (whole) return { kind: "remember", id: words[1].toLowerCase() };
447
+ }
322
448
  return { kind: "answer" };
323
449
  }
324
450
 
@@ -429,8 +555,8 @@ export function fileKind(path: string): FileKind {
429
555
 
430
556
  /**
431
557
  * Path rules for `riskScore`. These are defaults taken from the first consumer (`ipc`, `preload`,
432
- * `main`, `apps/<name>/src`) and are the owner's to tune; per-repository configuration is planned
433
- * (https://github.com/niway-dev/wachiman/issues/5).
558
+ * `main`, `apps/<name>/src`) and are the owner's to tune. A repository adds its own through `paths`
559
+ * in `.wachiman.yml` (`matchPathRule`), which outranks these weights for the files it matches.
434
560
  * The highest matching weight wins. A test or a document scores its kind's weight whatever its
435
561
  * path, so `ipc/foo.test.ts` does not outrank the IPC code it tests.
436
562
  */
@@ -454,7 +580,26 @@ export const RISK_RULES: { glob: string; weight: number; why: string }[] = [
454
580
  const KIND_WEIGHT: Record<FileKind, number> = { code: 4, test: 2, docs: 1 };
455
581
  const riskGlobs = RISK_RULES.map((r) => ({ ...r, matcher: new Bun.Glob(r.glob) }));
456
582
 
457
- export function riskScore(path: string): number {
583
+ /**
584
+ * The ordering score of a file a maintainer's path rule matched (ADR 0058): above every heuristic
585
+ * weight, `critical` above `high` above `medium`. Derived from the tables, so a heavier heuristic
586
+ * weight added later cannot outrank a rule. Today: medium 9, high 10, critical 11.
587
+ */
588
+ const HEURISTIC_MAX = Math.max(...Object.values(KIND_WEIGHT), ...RISK_RULES.map((r) => r.weight));
589
+ export const PATH_RULE_SCORE: Record<PathSeverity, number> = {
590
+ medium: HEURISTIC_MAX + 1,
591
+ high: HEURISTIC_MAX + 2,
592
+ critical: HEURISTIC_MAX + 3,
593
+ };
594
+
595
+ /**
596
+ * How risky a path is, for ordering. With `rules` (the repository's `paths`, from the base commit),
597
+ * a file a rule matches scores by the rule, tests and documents included: the maintainer named the
598
+ * path. Without rules, or with no match, the built-in heuristic decides, unchanged.
599
+ */
600
+ export function riskScore(path: string, rules?: readonly PathRule[], previous?: string): number {
601
+ const rule = matchPathRule(path, rules, previous);
602
+ if (rule) return PATH_RULE_SCORE[rule.severity];
458
603
  const kind = fileKind(path);
459
604
  if (kind !== "code") return KIND_WEIGHT[kind];
460
605
  const weights = riskGlobs.filter((r) => r.matcher.match(path)).map((r) => r.weight);
@@ -489,25 +634,34 @@ const sizeOf = (f: ReviewFile) => f.additions + f.deletions;
489
634
  export function planBatches(
490
635
  files: ReviewFile[],
491
636
  limits: { maxLines: number; maxChars: number },
637
+ rules?: readonly PathRule[],
492
638
  ): Batch[] {
639
+ const previousOf = new Map(files.flatMap((f) => (f.previous_filename ? [[f.filename, f.previous_filename] as const] : [])));
640
+ const score = (path: string) => riskScore(path, rules, previousOf.get(path));
641
+ /** The rule's score for a matched file, 0 for any other. */
642
+ const ruled = (path: string) => {
643
+ const rule = matchPathRule(path, rules, previousOf.get(path));
644
+ return rule ? PATH_RULE_SCORE[rule.severity] : 0;
645
+ };
646
+ const byScore = (a: ReviewFile, b: ReviewFile) =>
647
+ score(b.filename) - score(a.filename) || a.filename.localeCompare(b.filename);
648
+ // A file a path rule matched leaves its module and packs first, most severe first: the maintainer
649
+ // named the path, so a spent budget never leaves it unread behind a heuristic-ranked file.
650
+ const matched = files.filter((f) => ruled(f.filename) > 0).sort((a, b) => ruled(b.filename) - ruled(a.filename) || byScore(a, b));
651
+ const matchedSet = new Set(matched);
493
652
  const modules = new Map<string, ReviewFile[]>();
494
653
  for (const f of files) {
654
+ if (matchedSet.has(f)) continue;
495
655
  const key = moduleKey(f.filename);
496
656
  modules.set(key, [...(modules.get(key) ?? []), f]);
497
657
  }
498
- const ordered = [...modules.values()]
499
- .map((group) =>
500
- group.sort(
501
- (a, b) =>
502
- riskScore(b.filename) - riskScore(a.filename) || a.filename.localeCompare(b.filename),
503
- ),
504
- )
505
- .sort(
506
- (a, b) =>
507
- riskScore(b[0].filename) - riskScore(a[0].filename) ||
508
- a[0].filename.localeCompare(b[0].filename),
509
- )
510
- .flat();
658
+ const ordered = [
659
+ ...matched,
660
+ ...[...modules.values()]
661
+ .map((group) => group.sort(byScore))
662
+ .sort((a, b) => byScore(a[0], b[0]))
663
+ .flat(),
664
+ ];
511
665
 
512
666
  const batches: ReviewFile[][] = [];
513
667
  let current: ReviewFile[] = [];
@@ -532,11 +686,14 @@ export function planBatches(
532
686
  if (current.length > 0) batches.push(current);
533
687
 
534
688
  return batches.map((group) => ({
689
+ // A file a path rule matched leads its batch, most severe first, tests and documents included:
690
+ // the maintainer named the path. The rest keep the order of its kind. Without rules this is the
691
+ // kind order alone.
535
692
  files: [...group].sort(
536
- (a, b) => KIND_ORDER[fileKind(a.filename)] - KIND_ORDER[fileKind(b.filename)],
693
+ (a, b) => ruled(b.filename) - ruled(a.filename) || KIND_ORDER[fileKind(a.filename)] - KIND_ORDER[fileKind(b.filename)],
537
694
  ),
538
695
  lines: group.reduce((n, f) => n + sizeOf(f), 0),
539
- maxRisk: Math.max(...group.map((f) => riskScore(f.filename))),
696
+ maxRisk: Math.max(...group.map((f) => score(f.filename))),
540
697
  }));
541
698
  }
542
699
 
@@ -994,6 +1151,27 @@ export function countLine(findings: Finding[]): string {
994
1151
  return `${findings.length} finding(s)${shown.length > 0 ? `: ${shown.join(", ")}` : ""}`;
995
1152
  }
996
1153
 
1154
+ /**
1155
+ * `**9 findings:** 1 Must, 4 Should, 3 Could, 1 FYI · 6 at high confidence`: what the review found,
1156
+ * weighed, on one line that opens its findings (ADR 0059). Groups with none are left out,
1157
+ * a finding with no confidence is not counted as high, and no findings means no line. The priority
1158
+ * arm (the default) counts by priority word and counts a finding's stored priority before the
1159
+ * table's. The trial's word arm counts by tier word instead, `**9 findings:** 5 Important, 3 Nit,
1160
+ * 1 Pre-existing · 6 at high confidence`, so no priority word appears in a word-arm review.
1161
+ */
1162
+ export function summaryLine(findings: (Finding & { priority?: Priority; origin?: Origin })[], arm?: Arm): string | null {
1163
+ if (findings.length === 0) return null;
1164
+ const groups =
1165
+ arm === "word"
1166
+ ? (["Important", "Nit", "Pre-existing"] as const).map((t) => [findings.filter((f) => tierWord(f) === t).length, t] as const)
1167
+ : (["must", "should", "could", "fyi"] as const).map(
1168
+ (p) => [findings.filter((f) => (f.priority ?? priorityOf(f).priority) === p).length, PRIORITY_WORD[p]] as const,
1169
+ );
1170
+ const shown = groups.filter(([n]) => n > 0).map(([n, word]) => `${n} ${word}`);
1171
+ const high = findings.filter((f) => f.confidence === "high").length;
1172
+ return `**${countOf(findings.length, "finding")}:** ${shown.join(", ")} · ${high} at high confidence`;
1173
+ }
1174
+
997
1175
  /** The `<summary>` of the contracts block; `trimMiddle` finds the block by it. */
998
1176
  export const CONTRACTS_SUMMARY = "What the change connects to";
999
1177
 
@@ -1100,7 +1278,7 @@ const estimateTail = (estimate: boolean) => (estimate ? ` · ${ESTIMATE_NOTE}` :
1100
1278
 
1101
1279
  export function buildReview(input: {
1102
1280
  /** A finding's `anchor`, when given (a `ReviewResult`'s), decides inline or body; else its file's patch does. */
1103
- output: Omit<ReviewOutput, "findings"> & { findings: (Finding & Partial<Pick<ResultFinding, "anchor" | "origin" | "verification">>)[] };
1281
+ output: Omit<ReviewOutput, "findings"> & { findings: (Finding & Partial<Pick<ResultFinding, "anchor" | "origin" | "verification" | "priority" | "rank">>)[] };
1104
1282
  files: ReviewFile[];
1105
1283
  headSha: string;
1106
1284
  since: string | null;
@@ -1135,10 +1313,14 @@ export function buildReview(input: {
1135
1313
  priorSpend?: { spent: number; runs: number };
1136
1314
  /** Review-instruction files this pull request edits, and the base commit they were read from. */
1137
1315
  instructionChanges?: { files: string[]; baseSha: string };
1316
+ /** The pull request edits the path rules in `.wachiman.yml`; the review ran under the base's. */
1317
+ pathPolicyChange?: { baseSha: string };
1138
1318
  /** The verifier's record (ADR 0027): its outcome goes in the footer's cost line. */
1139
1319
  verification?: ResultVerificationV2;
1140
1320
  /** The run is on a Claude subscription: its dollar figures are API-price estimates (ADR 0037). */
1141
1321
  estimate?: boolean;
1322
+ /** The trial arm (ADR 0059): `word` renders today's Important/Nit word in each inline table. Default: the priority. */
1323
+ arm?: Arm;
1142
1324
  /** The risk map (ADR 0031), rendered right after the count line. */
1143
1325
  riskMap?: RiskMap;
1144
1326
  /** PR Confidence (ADR 0033): the grade as one line after the count line; the description block holds the rest. */
@@ -1185,7 +1367,7 @@ export function buildReview(input: {
1185
1367
  path: f.path,
1186
1368
  line: f.line,
1187
1369
  side: "RIGHT",
1188
- body: `${branded(label(f))}\n\n${neutralise(f.body)}\n\n${SIGNATURE.finding}`,
1370
+ body: `${inlineFindingBody(f, input.arm)}\n\n${SIGNATURE.finding}`,
1189
1371
  });
1190
1372
  } else outsideDiff.push(f);
1191
1373
  }
@@ -1236,9 +1418,16 @@ export function buildReview(input: {
1236
1418
  `ℹ️ **Review instructions changed**: this pull request edits ${names}. The review ran under the versions at the base commit \`${short(input.instructionChanges.baseSha)}\`; the change takes effect after merge.`,
1237
1419
  );
1238
1420
  }
1421
+ if (input.pathPolicyChange) {
1422
+ parts.push(
1423
+ `ℹ️ **Review policy changed**: this pull request edits the path rules in \`${SETTINGS_PATH}\`. The review ran under the rules at the base commit \`${short(input.pathPolicyChange.baseSha)}\`; the change takes effect after merge.`,
1424
+ );
1425
+ }
1239
1426
  parts.push(
1240
1427
  `${countLine(output.findings)}; ${comments.length} on their lines. Reply in a comment's thread to answer it.`,
1241
1428
  );
1429
+ const summary = summaryLine(output.findings, input.arm);
1430
+ if (summary) parts.push(summary);
1242
1431
  if (input.fidelity) parts.push(fidelitySummary(input.fidelity));
1243
1432
  if (input.verification?.status === "failed") {
1244
1433
  parts.push("⚠️ **Not verified**: the second reader that checks each finding did not finish, so these findings are posted as the review wrote them.");
@@ -1248,7 +1437,9 @@ export function buildReview(input: {
1248
1437
  // Before the findings and outside any <details> block. The size fitting below cuts the contracts,
1249
1438
  // the Inconclusive and Pre-existing lists and the unreviewed-files list, never this part.
1250
1439
  if (input.riskMap) parts.push(renderRiskMap(input.riskMap, "### Risk map", { pushOnly: input.pushOnly }));
1251
- const listed = (f: Finding & { origin?: Origin }) => `- ${label(f)} (\`${at(f)}\`): ${neutralise(f.body)}`;
1440
+ // The word arm of the trial keeps today's tier word in these lists too: only the word differs between arms.
1441
+ const listLabel = input.arm === "word" ? legacyLabel : label;
1442
+ const listed = (f: Finding & { origin?: Origin; priority?: Priority }) => `- ${listLabel(f)} (\`${at(f)}\`): ${neutralise(f.body)}`;
1252
1443
  if (outsideDiff.length > 0) parts.push("### Outside the diff", ...outsideDiff.map(listed));
1253
1444
  // Each of these two is one part, so a long body can cut it by its index.
1254
1445
  const cuttable: { at: number; heading: string; items: string[] }[] = [];
@@ -1353,7 +1544,7 @@ export function buildReview(input: {
1353
1544
  export function moveCommentsToBody(review: Review): Review {
1354
1545
  if (review.comments.length === 0) return review;
1355
1546
  const moved = review.comments.map(
1356
- (c) => `- \`${neutralise(c.path)}:${c.line}\`: ${c.body.replace(SIGNATURE.finding, "").trim().replace(/\n\n/, " ")}`,
1547
+ (c) => `- \`${neutralise(c.path)}:${c.line}\`: ${shownFindingComment(c.body).replace(SIGNATURE.finding, "").trim().replace(/\n\n/, " ")}`,
1357
1548
  );
1358
1549
  const base = review.body.replace(
1359
1550
  /; \d+ on their lines\. Reply in a comment's thread to answer it\./,
@@ -1398,6 +1589,23 @@ function trimHead(head: string, cut: number) {
1398
1589
  return `${head.slice(0, at > 0 ? at : target)}${trimmed}`;
1399
1590
  }
1400
1591
 
1592
+ /**
1593
+ * The "Muted by memory" paragraph (with its leading blank line) within `room` characters: the
1594
+ * count line, then as many entries as fit. The count stays even when no entry fits.
1595
+ */
1596
+ function fitMuted(block: string, room: number): string {
1597
+ const items = block.trim().split("\n").slice(1);
1598
+ const count = `**${items.length} finding${items.length === 1 ? "" : "s"} muted by memory** (not posted as comments; the list is cut to fit GitHub's size limit):`;
1599
+ const kept: string[] = [];
1600
+ let used = 2 + count.length;
1601
+ for (const item of items) {
1602
+ if (used + 1 + item.length > room) break;
1603
+ kept.push(item);
1604
+ used += 1 + item.length;
1605
+ }
1606
+ return `\n\n${[count, ...kept].join("\n")}`;
1607
+ }
1608
+
1401
1609
  /**
1402
1610
  * Makes the part of a review body between the first findings and the footer (`### Summary`, the
1403
1611
  * contracts block, the coverage table) at least `cut` characters shorter. The footer (`<sub>`
@@ -1412,23 +1620,30 @@ function trimMiddle(tail: string, cut: number) {
1412
1620
  const trimmed = "\n\n(Trimmed: this review is at GitHub's size limit.)";
1413
1621
  const target = middle.length - cut - trimmed.length;
1414
1622
  // The text before the first collapsed block is the Summary; each block after it starts at `<details>`.
1415
- const [summary, ...blocks] = middle.split(/(?=\n\n<details>)/);
1623
+ const [whole, ...blocks] = middle.split(/(?=\n\n<details>)/);
1624
+ // The "Muted by memory" list ends the Summary and is protected (ADR 0057: every muted finding is shown): the text before it is cut first, then the list shrinks to a count and the entries that fit.
1625
+ const mutedAt = whole.lastIndexOf(`\n\n${MUTED_HEADING}`);
1626
+ const summary = mutedAt === -1 ? whole : whole.slice(0, mutedAt);
1627
+ let muted = mutedAt === -1 ? "" : whole.slice(mutedAt);
1416
1628
  const dropOrder = [
1417
1629
  ...blocks.filter((b) => b.includes(`<summary>${CONTRACTS_SUMMARY}`)),
1418
1630
  ...blocks.filter((b) => !b.includes(`<summary>${CONTRACTS_SUMMARY}`)),
1419
1631
  ];
1420
1632
  let kept = blocks;
1421
- const size = () => summary.length + kept.reduce((n, b) => n + b.length, 0);
1633
+ const size = () => summary.length + muted.length + kept.reduce((n, b) => n + b.length, 0);
1422
1634
  for (const block of dropOrder) {
1423
1635
  if (size() <= target) break;
1424
1636
  kept = kept.filter((b) => b !== block);
1425
1637
  }
1426
1638
  let text = summary;
1427
1639
  if (size() > target) {
1428
- const cutAt = summary.lastIndexOf("\n", Math.max(target, 0));
1640
+ const room = target - muted.length - kept.reduce((n, b) => n + b.length, 0);
1641
+ const cutAt = summary.lastIndexOf("\n", Math.max(room, 0));
1429
1642
  text = summary.slice(0, Math.max(cutAt, 0));
1430
1643
  }
1431
- return `${text}${kept.join("")}${trimmed}${footer}`;
1644
+ const keptLength = kept.reduce((n, b) => n + b.length, 0);
1645
+ if (muted && text.length + muted.length + keptLength > target) muted = fitMuted(muted, target - text.length - keptLength);
1646
+ return `${text}${muted}${kept.join("")}${trimmed}${footer}`;
1432
1647
  }
1433
1648
 
1434
1649
  // ---------------------------------------------------------------------------------------------
@@ -1676,6 +1891,117 @@ export function readBaseInstructions(
1676
1891
  return instructionsFrom(sha, (path) => fileAtBase(gh, repo, path, sha), warn);
1677
1892
  }
1678
1893
 
1894
+ /**
1895
+ * `.wachiman.yml` as it is at the pull request's base commit, parsed, or undefined when the base has
1896
+ * none. Like the focus file, never the head's copy: a pull request that edits `model` or `effort`
1897
+ * is reviewed, and paid for, under the base's values. A file the contents API cannot return whole
1898
+ * (over 64 KB) is a usage error rather than a guess. An invalid file is a usage error naming it;
1899
+ * `withBaseSettings` turns that into a warning, so a broken file never blocks a review.
1900
+ */
1901
+ export function readBaseSettings(gh: GhFn, repo: string, sha: string): RepoSettings | undefined {
1902
+ const file = fileAtBase(gh, repo, SETTINGS_PATH, sha);
1903
+ if (!file) return undefined;
1904
+ if (file.truncated) throw new UsageError(`${SETTINGS_PATH} at the base commit is over ${MAX_INSTRUCTION_BYTES / 1024} KB, too large for a settings file.`);
1905
+ return parseRepoSettings(file.content);
1906
+ }
1907
+
1908
+ /**
1909
+ * The base commit's `paths` rules (ADR 0058), or undefined when it has none. Read on every run,
1910
+ * whether or not `model` and `effort` were set explicitly: the rules are review policy, not a spend
1911
+ * choice. Like `withBaseSettings`, a broken file is ignored with one warning and the run continues
1912
+ * with no rules, so the pull request that fixes the file can be reviewed; errors from GitHub itself
1913
+ * still propagate. When a `.wachiman.yml` read has already warned about the same file, the same
1914
+ * problem is reported once more here: the two reads are independent.
1915
+ */
1916
+ export function readBasePathRules(gh: GhFn, repo: string, sha: string, warn: (line: string) => void): PathRule[] | undefined {
1917
+ try {
1918
+ return readBaseSettings(gh, repo, sha)?.paths;
1919
+ } catch (error) {
1920
+ if (!(error instanceof UsageError)) throw error;
1921
+ warn(ignoredSettingsNote(error.message, `the base commit ${sha.slice(0, 7)}`));
1922
+ return undefined;
1923
+ }
1924
+ }
1925
+
1926
+ /**
1927
+ * Whether the pull request's head `.wachiman.yml` sets different path rules than the base's
1928
+ * (`baseRules`), read from the contents API at the head sha (ADR 0058 decision 5). Only to tell
1929
+ * the author and the reader: the head's rules are never applied. A head copy that is gone and had
1930
+ * no base rules is no change; one that cannot be parsed, or is over the size limit, is.
1931
+ */
1932
+ export function headEditsPathRules(gh: GhFn, repo: string, headSha: string, baseRules: readonly PathRule[] | undefined): boolean {
1933
+ const file = fileAtBase(gh, repo, SETTINGS_PATH, headSha);
1934
+ if (file?.truncated) return true;
1935
+ return pathsEdited(baseRules, file ? file.content : null);
1936
+ }
1937
+
1938
+ /**
1939
+ * The memory folder and `.wachiman.yml` at the pull request's base commit, read through the
1940
+ * contents API. Never the head: a pull request cannot change the memory it is reviewed under.
1941
+ */
1942
+ export function githubMemorySource(gh: GhFn, repo: string, sha: string, warn: (line: string) => void = () => {}): MemorySource {
1943
+ return {
1944
+ list: () => {
1945
+ let raw: string;
1946
+ try {
1947
+ raw = gh(["api", `repos/${repo}/contents/${MEMORY_DIR}?ref=${sha}`]);
1948
+ } catch (error) {
1949
+ if (error instanceof GhError && error.status === 404) return [];
1950
+ throw error;
1951
+ }
1952
+ const listing = JSON.parse(raw) as unknown;
1953
+ if (!Array.isArray(listing)) return [];
1954
+ return listing.flatMap((e: { type?: string; name?: string }) => (e.type === "file" && typeof e.name === "string" ? [e.name] : []));
1955
+ },
1956
+ read: (name) => {
1957
+ const file = fileAtBase(gh, repo, `${MEMORY_DIR}/${name}`, sha);
1958
+ if (!file) return null;
1959
+ if (file.truncated) warn(file.content === "" ? `${MEMORY_DIR}/${name} is over 1 MB, which GitHub does not return; it is not loaded. Split it into area files.` : cutMemoryNote(name, MAX_INSTRUCTION_BYTES / 1024));
1960
+ return file.truncated && file.content === "" ? null : file.content;
1961
+ },
1962
+ settings: () => readBaseSettings(gh, repo, sha),
1963
+ };
1964
+ }
1965
+
1966
+ /** The memory a review of `changedPaths` loads at the base commit `sha`; undefined without a memory folder. */
1967
+ export function readBaseMemory(gh: GhFn, repo: string, sha: string, changedPaths: string[], warn: (line: string) => void): MemoryLoad | undefined {
1968
+ return loadMemory(githubMemorySource(gh, repo, sha, warn), sha, changedPaths, warn);
1969
+ }
1970
+
1971
+ /**
1972
+ * `config` with the model and the effort the base commit's `.wachiman.yml` sets, wherever no
1973
+ * explicit `WACHIMAN_MODEL` / `WACHIMAN_EFFORT` (a workflow input) did. Reads nothing when both
1974
+ * were explicit. Logs one line when the file decided something, so the job log says so. A broken
1975
+ * file at the base (bad YAML, a bad `effort`, too large) is ignored with a warning and the run
1976
+ * continues on the environment and the defaults: the pull request that fixes the file must be
1977
+ * reviewable. Errors from GitHub itself still propagate.
1978
+ */
1979
+ export function withBaseSettings(
1980
+ config: EngineConfig,
1981
+ gh: GhFn,
1982
+ repo: string,
1983
+ pr: number,
1984
+ log: (line: string) => void,
1985
+ warn: (line: string) => void = log,
1986
+ ): EngineConfig {
1987
+ if (!wantsRepoSettings(config)) return config;
1988
+ const sha = baseSha(gh, repo, pr);
1989
+ let settings: RepoSettings | undefined;
1990
+ try {
1991
+ settings = readBaseSettings(gh, repo, sha);
1992
+ } catch (error) {
1993
+ if (!(error instanceof UsageError)) throw error;
1994
+ warn(ignoredSettingsNote(error.message, `the base commit ${sha.slice(0, 7)}`));
1995
+ return config;
1996
+ }
1997
+ if (!settings) return config;
1998
+ const where = `the base commit ${sha.slice(0, 7)}`;
1999
+ const next = applyRepoSettings(config, settings, { where, warn });
2000
+ const note = fileSettingsNote(next, where);
2001
+ if (note) log(`settings: ${note}`);
2002
+ return next;
2003
+ }
2004
+
1679
2005
  /**
1680
2006
  * The instruction files at `sha`, read one path at a time through `fileAt` (null when absent):
1681
2007
  * the lookup order, the old focus path's fallback and the warnings of every connector.
@@ -2210,7 +2536,8 @@ export function openBotThreads(threads: RawThread[]) {
2210
2536
  comment_id: t.comments.nodes[0].databaseId,
2211
2537
  path: t.path,
2212
2538
  line: t.line,
2213
- finding: t.comments.nodes[0].body,
2539
+ // The model reads today's one-line label, never the inline table.
2540
+ finding: legacyFindingComment(t.comments.nodes[0].body),
2214
2541
  replies: t.comments.nodes
2215
2542
  .slice(1)
2216
2543
  .filter((c) => TRUSTED.has(c.authorAssociation))
@@ -2281,17 +2608,20 @@ export function reviewMaterial(
2281
2608
  ): { review: string; threads: FindingThread[] } | null {
2282
2609
  const review = latestEngineReview(gh, repo, pr);
2283
2610
  if (review === null) return null;
2284
- const threads = fetchThreads(gh, repo, pr)
2285
- .filter(isBotFinding)
2286
- .map((t) => ({
2287
- path: t.path,
2288
- line: t.line,
2289
- resolved: t.isResolved,
2290
- finding: t.comments.nodes[0].body,
2291
- }));
2611
+ const threads = fetchThreads(gh, repo, pr).filter(isBotFinding).map(askFindingThread);
2292
2612
  return { review, threads };
2293
2613
  }
2294
2614
 
2615
+ /** A bot finding thread as the ask prompt reads it: the model sees today's label, never the table. */
2616
+ export function askFindingThread(t: RawThread): FindingThread {
2617
+ return {
2618
+ path: t.path,
2619
+ line: t.line,
2620
+ resolved: t.isResolved,
2621
+ finding: legacyFindingComment(t.comments.nodes[0].body),
2622
+ };
2623
+ }
2624
+
2295
2625
  /** The file the ask prompt reads for the review: the body, then the threads as JSON. */
2296
2626
  export function renderReviewMaterial(material: { review: string; threads: FindingThread[] }) {
2297
2627
  return [
@@ -2312,7 +2642,7 @@ export const MAX_WACHI_REPLIES = 2;
2312
2642
  * Whether a comment is one this engine wrote as a thread reply: the bot login AND the reply
2313
2643
  * signature, since `github-actions` is shared by every workflow of the repository.
2314
2644
  */
2315
- const isWachiReply = (c: RawThread["comments"]["nodes"][number]) =>
2645
+ export const isWachiReply = (c: RawThread["comments"]["nodes"][number]) =>
2316
2646
  c.author?.login === "github-actions" && c.body.includes(SIGNATURE.reply);
2317
2647
 
2318
2648
  /**
@@ -2321,15 +2651,20 @@ const isWachiReply = (c: RawThread["comments"]["nodes"][number]) =>
2321
2651
  * fewer than `MAX_WACHI_REPLIES` replies in the thread. A thread whose latest comment is
2322
2652
  * Wachiman's, or a stranger's, or whose cap is spent, is not pending. Each entry is
2323
2653
  * `openBotThreads`' thread plus how many replies Wachiman already wrote, so the model knows
2324
- * whether its answer is the last one allowed.
2654
+ * whether its answer is the last one allowed. With `memoryProposals` on, a latest reply that is
2655
+ * `<mention> remember <id>` written by the `operator` is not pending: the memory write job answers it
2656
+ * (layer 5). With it off no job does, and for anyone but the operator the job skips it, so that reply is
2657
+ * an ordinary one.
2325
2658
  */
2326
- export function pendingThreads(threads: RawThread[]) {
2659
+ export function pendingThreads(threads: RawThread[], keyword = DEFAULT_MENTION, memoryProposals = false, operator?: string) {
2327
2660
  const open = openBotThreads(threads);
2328
2661
  const byId = new Map(threads.map((t) => [t.comments.nodes[0]?.databaseId, t]));
2329
2662
  return open.flatMap((t) => {
2330
2663
  const nodes = byId.get(t.comment_id)?.comments.nodes ?? [];
2331
2664
  const latest = nodes.length > 1 ? nodes[nodes.length - 1] : undefined;
2332
2665
  if (!latest || latest.author?.login === "github-actions" || !TRUSTED.has(latest.authorAssociation)) return [];
2666
+ const byOperator = operator !== undefined && latest.author?.login.toLowerCase() === operator.trim().toLowerCase();
2667
+ if (memoryProposals && byOperator && parseCommand(latest.body, keyword)?.kind === "remember") return [];
2333
2668
  const wachiReplies = nodes.slice(1).filter(isWachiReply).length;
2334
2669
  return wachiReplies < MAX_WACHI_REPLIES ? [{ ...t, wachi_replies: wachiReplies }] : [];
2335
2670
  });
@@ -2338,6 +2673,13 @@ export function pendingThreads(threads: RawThread[]) {
2338
2673
  /** Below this a batch cannot read its prompt, so none is started. */
2339
2674
  export const MIN_BATCH_USD = 0.05;
2340
2675
 
2676
+ /**
2677
+ * How many batches of one review run at the same time. Start at 4 and measure 4 against 6 before
2678
+ * raising it: the subscription documents no concurrency limit per account, and a short-lived
2679
+ * "temporarily limiting requests" throttle exists that Claude Code retries by itself.
2680
+ */
2681
+ export const BATCH_CONCURRENCY = 4;
2682
+
2341
2683
  /**
2342
2684
  * What the pull request's automatic runs have spent, and the ceilings the engine already told
2343
2685
  * the owner about. Both come only from the engine's own signed footers (`readAutoCost`,
@@ -2616,7 +2958,7 @@ export function spendReserve(deps: Deps, repo: string, pr: number, headSha: stri
2616
2958
  }
2617
2959
  if (error instanceof LedgerNotPermitted) {
2618
2960
  const message =
2619
- "`ledger_url` is set, but this job cannot request an OIDC token, so nothing was reviewed. Call `.github/workflows/review-platform.yml` instead of `review.yml`, and grant `id-token: write` in the caller's job (docs/install.md).";
2961
+ "`ledger_url` is set, but this job cannot request an OIDC token, so nothing was reviewed. Call `.github/workflows/wachiman-platform.yml` instead of `review.yml`, and grant `id-token: write` in the caller's job (docs/install.md).";
2620
2962
  ledgerNote(deps, message);
2621
2963
  throw new LedgerStopped(message);
2622
2964
  }
@@ -2687,9 +3029,9 @@ function grantTooSmall(deps: Deps, grant: SpendGrant, what: string): boolean {
2687
3029
  }
2688
3030
 
2689
3031
  /** Runs a paid step; if it throws, the ledger still hears what the calls so far cost, then the error goes on. */
2690
- function settledOnError<T>(deps: Deps, grant: SpendGrant, run: () => T): T {
3032
+ async function settledOnError<T>(deps: Deps, grant: SpendGrant, run: () => Promise<T>): Promise<T> {
2691
3033
  try {
2692
- return run();
3034
+ return await run();
2693
3035
  } catch (error) {
2694
3036
  spendSettle(deps, grant, spentSince(deps, grant));
2695
3037
  throw error;
@@ -2697,8 +3039,8 @@ function settledOnError<T>(deps: Deps, grant: SpendGrant, run: () => T): T {
2697
3039
  }
2698
3040
 
2699
3041
  /** The estimate of reviewing `files` with this configuration: the batches `planBatches` makes, priced per batch. */
2700
- export function estimateFor(files: ReviewFile[], config: EngineConfig): ReviewEstimate {
2701
- const batches = planBatches(files, { maxLines: config.batchLines, maxChars: config.batchChars }).length;
3042
+ export function estimateFor(files: ReviewFile[], config: EngineConfig, rules?: readonly PathRule[]): ReviewEstimate {
3043
+ const batches = planBatches(files, { maxLines: config.batchLines, maxChars: config.batchChars }, rules).length;
2702
3044
  return estimateReview(files, { batches, batchBudgetUsd: config.batchBudgetUsd, model: config.model });
2703
3045
  }
2704
3046
 
@@ -2708,6 +3050,38 @@ export const SIZE_GATE_MARKER = "<!-- wachi:size-gate -->";
2708
3050
  const usd2 = (n: number) => `$${n.toFixed(2)}`;
2709
3051
  const count = (n: number) => n.toLocaleString("en-US");
2710
3052
 
3053
+ /** A changed file a `critical` path rule matches, and the maintainer's reason. */
3054
+ export interface CriticalPath {
3055
+ path: string;
3056
+ reason: string;
3057
+ }
3058
+
3059
+ /** How many critical paths the size-gate comment lists before "and N more". */
3060
+ const MAX_CRITICAL_LISTED = 20;
3061
+
3062
+ /** Every name a list of changed files uses: the current one, and the one before a rename. */
3063
+ export const touchedPathsOf = (files: readonly { filename: string; previous_filename?: string | null }[]): string[] => [
3064
+ ...new Set(files.flatMap((f) => (f.previous_filename ? [f.filename, f.previous_filename] : [f.filename]))),
3065
+ ];
3066
+
3067
+ /** The changed files a `critical` rule of `rules` matches, in the order given. Never lifts the gate: it only names. */
3068
+ export function criticalPathsOf(files: readonly { filename: string; previous_filename?: string | null }[], rules: readonly PathRule[] | undefined): CriticalPath[] {
3069
+ return files.flatMap((f) => {
3070
+ const rule = matchPathRule(f.filename, rules, f.previous_filename);
3071
+ return rule?.severity === "critical" ? [{ path: f.filename, reason: rule.reason }] : [];
3072
+ });
3073
+ }
3074
+
3075
+ function criticalPathsSection(critical: readonly CriticalPath[]): string {
3076
+ const listed = critical.slice(0, MAX_CRITICAL_LISTED).map((c) => `- \`${neutralise(c.path)}\`: ${neutralise(c.reason)}`);
3077
+ const more = critical.length - listed.length;
3078
+ return [
3079
+ `**Critical paths in this change** (from \`${SETTINGS_PATH}\` at the base commit): a person should read these before merging, since nothing was reviewed.`,
3080
+ ...listed,
3081
+ ...(more > 0 ? [`- and ${more} more`] : []),
3082
+ ].join("\n");
3083
+ }
3084
+
2711
3085
  /**
2712
3086
  * The comment that says a pull request was not reviewed because its estimate is above the size
2713
3087
  * gate (nothing was sent to a model), what the estimate rests on, and the inputs that lift it.
@@ -2718,6 +3092,8 @@ export function sizeGateBody(o: {
2718
3092
  headSha: string;
2719
3093
  mention: string;
2720
3094
  model: string;
3095
+ /** The changed files a `critical` path rule matches, from the base commit's rules; none by default. */
3096
+ critical?: readonly CriticalPath[];
2721
3097
  }): string {
2722
3098
  const { estimate: e, gate, headSha, mention, model } = o;
2723
3099
  const budget = suggestedBudget(e.usd);
@@ -2725,6 +3101,7 @@ export function sizeGateBody(o: {
2725
3101
  branded(
2726
3102
  `**Not reviewed: this pull request is above the size gate.** Reviewing all of it would cost about **${usd2(e.usd)}**, and the gate is **${usd2(gate)}**, so nothing was sent to a model and nothing was spent.`,
2727
3103
  ),
3104
+ ...(o.critical?.length ? [criticalPathsSection(o.critical)] : []),
2728
3105
  `The estimate: ${count(e.batches)} batches × ${usd2(e.perBatchUsd)} a batch for \`${model}\` (${count(e.files)} files, ${count(e.lines)} changed lines), from the diff alone, before any model call. It can be off by about 40% either way.`,
2729
3106
  `To review the whole pull request, set the run budget in the workflow that calls Wachiman, then comment \`${mention} review\`:`,
2730
3107
  ["```yaml", " with:", ` budget_usd: ${budget}`, "```"].join("\n"),
@@ -2746,6 +3123,7 @@ export function postSizeGateNotice(
2746
3123
  headSha: string,
2747
3124
  estimate: ReviewEstimate,
2748
3125
  gate: number,
3126
+ critical: readonly CriticalPath[] = [],
2749
3127
  ) {
2750
3128
  const { config } = deps;
2751
3129
  const body = sizeGateBody({
@@ -2754,6 +3132,7 @@ export function postSizeGateNotice(
2754
3132
  headSha,
2755
3133
  mention: config.mention,
2756
3134
  model: config.model,
3135
+ critical,
2757
3136
  });
2758
3137
  if (config.dryRun) {
2759
3138
  deps.log("--- size gate comment ---\n" + body);
@@ -2814,6 +3193,24 @@ function reviewUrlOf(answer: string): string | undefined {
2814
3193
  }
2815
3194
  }
2816
3195
 
3196
+ /**
3197
+ * The review a push posts when nothing in it needs reading: the branch was only brought up to date
3198
+ * with its base (a merge, or a rebase with the same changes). One wording for both. It makes no
3199
+ * model call, so it carries no cost line, no automatic flag and no model: the ceiling does not
3200
+ * count it. It still carries the marker, so the next push is compared with this head.
3201
+ */
3202
+ export function baseUpdateNotice(o: { base?: string; from: string; to: string; version?: string }, headMarker: string) {
3203
+ const base = o.base ? `\`${o.base.replaceAll("`", "'")}\`` : "the base branch";
3204
+ return [
3205
+ branded(
3206
+ `No new changes to review: the branch was updated from ${base} (\`${short(o.from)}\` → \`${short(o.to)}\`). The previous review still applies.`,
3207
+ ),
3208
+ `<sub>Wachiman ${o.version ?? "unknown"}</sub>`,
3209
+ SIGNATURE.review,
3210
+ headMarker,
3211
+ ].join("\n\n");
3212
+ }
3213
+
2817
3214
  /** Posts the review. Returns its address when GitHub gave one (the description block links to it). */
2818
3215
  export function postReview(deps: Deps, repo: string, pr: number, headSha: string, review: Review): string | undefined {
2819
3216
  if (deps.config.dryRun) {
@@ -2870,16 +3267,149 @@ export function postReview(deps: Deps, repo: string, pr: number, headSha: string
2870
3267
  return url;
2871
3268
  }
2872
3269
 
3270
+ /** What a provider can refuse with: no money or quota, a rejected credential, or a rate limit that outlasted the retry. */
3271
+ export type RefusalKind = "billing" | "auth" | "rate_limit";
3272
+
3273
+ /**
3274
+ * The hidden marker of a $0 refusal notice (billing, auth, rate limit). The next refusal finds it
3275
+ * on the latest bot review and edits that review in place instead of posting an identical one
3276
+ * (ADR 0055). A notice that spent money never carries it: the ceiling counts its cost line, and
3277
+ * an edit would erase it.
3278
+ */
3279
+ export const refusalMarker = (kind: RefusalKind) => `<!-- wachi:refusal kind=${kind} -->`;
3280
+ /**
3281
+ * A refusal notice of an automatic run: the marker is a block of its own, and the engine's review
3282
+ * signature ends the body (an attempt line may follow). Anchored like the other footer readers, so
3283
+ * text that merely contains the marker, or a signature somewhere in the middle, never matches.
3284
+ */
3285
+ const REFUSAL_NOTICE = new RegExp(
3286
+ `\\n\\n<!-- wachi:refusal kind=(?:billing|auth|rate_limit) -->\\n\\n[\\s\\S]*\\n\\n${SIGNATURE_REVIEW_SOURCE}(?:\\n\\n${ATTEMPT_SOURCE})?$`,
3287
+ );
3288
+
3289
+ const RERUN = 'the "Wachiman review" job in the Actions tab, or push again';
3290
+
3291
+ /**
3292
+ * The notice for a provider that refused the call: a headline that says what happened, and a
3293
+ * "What to do" table that says who acts, what to do, what was spent and what the provider said.
3294
+ * Who and Fix branch on how the reviewer pays: a Claude subscription token or an API key.
3295
+ */
3296
+ export function refusalNotice(o: {
3297
+ kind: RefusalKind;
3298
+ /** `oauth-token` is a Claude subscription; anything else is an API key. */
3299
+ auth: ProviderAuth | undefined;
3300
+ /** The provider's own text, if any; it is neutralised and cut here. */
3301
+ detail: string;
3302
+ /** What this run spent, in dollars. */
3303
+ spentUsd: number;
3304
+ /** What the pull request's automatic runs have spent before this one; absent for a run the ceiling does not count. */
3305
+ priorSpentUsd?: number;
3306
+ }): { headline: string; table: string } {
3307
+ const owner = (secret: string) => `The repository owner, who holds the \`${secret}\` secret`;
3308
+ const subscription = o.auth === "oauth-token";
3309
+ const [headline, who, fix] = (
3310
+ subscription
3311
+ ? {
3312
+ billing: [
3313
+ "the Claude subscription refused the call (usage limit or plan access)",
3314
+ owner("CLAUDE_CODE_OAUTH_TOKEN"),
3315
+ `Wait for the usage limit to reset, or check that the plan gives access, then re-run ${RERUN}. Wachiman does not fall back to an API key`,
3316
+ ],
3317
+ auth: [
3318
+ "the Claude subscription token was rejected",
3319
+ owner("CLAUDE_CODE_OAUTH_TOKEN"),
3320
+ `Replace the \`CLAUDE_CODE_OAUTH_TOKEN\` secret (a token lasts a year; \`claude setup-token\` makes a new one), then re-run ${RERUN}`,
3321
+ ],
3322
+ rate_limit: ["Claude kept rate-limiting the reviewer", "Anyone who can re-run workflows", `Re-run later: ${RERUN}`],
3323
+ }
3324
+ : {
3325
+ billing: [
3326
+ "the Anthropic account has no credit",
3327
+ owner("ANTHROPIC_API_KEY"),
3328
+ `Add credit to that Anthropic account, then re-run ${RERUN}`,
3329
+ ],
3330
+ auth: [
3331
+ "the API key was rejected",
3332
+ owner("ANTHROPIC_API_KEY"),
3333
+ `Check the \`ANTHROPIC_API_KEY\` secret, then re-run ${RERUN}`,
3334
+ ],
3335
+ rate_limit: [
3336
+ "the Anthropic API kept rate-limiting the reviewer",
3337
+ "Anyone who can re-run workflows",
3338
+ `Re-run later: ${RERUN}`,
3339
+ ],
3340
+ }
3341
+ )[o.kind];
3342
+ const thisRun = o.spentUsd === 0 ? "Nothing this run" : `$${o.spentUsd.toFixed(2)} this run`;
3343
+ const total = o.priorSpentUsd === undefined ? "" : ` · PR so far $${(o.priorSpentUsd + o.spentUsd).toFixed(2)}`;
3344
+ // The provider's own text: comments defused and cut to one short line here, whatever the caller did, then escaped for a table cell.
3345
+ const text = oneLine(o.detail, 300).replaceAll("`", "'");
3346
+ const said = text ? `\`${cell(text)}\`` : "no text";
3347
+ const table = [
3348
+ "| What to do | |",
3349
+ "| --- | --- |",
3350
+ `| **Who** | ${who} |`,
3351
+ `| **Fix** | ${fix} |`,
3352
+ `| **Spent** | ${thisRun}${total} |`,
3353
+ `| **Provider said** | ${said} |`,
3354
+ ].join("\n");
3355
+ return { headline: `⛔ **Not reviewed**: ${headline}`, table };
3356
+ }
3357
+
3358
+ /**
3359
+ * Posts a $0 refusal notice. When the latest review of the bot is itself a $0 refusal notice (it
3360
+ * carries `refusalMarker`), that review's body is replaced with one `PUT` instead of a new review:
3361
+ * the same refusal on each push was 68 identical reviews in three days. A `PUT` with the same body
3362
+ * is idempotent, so a transient error repeats it with no `wachi:attempt` check. Any other latest
3363
+ * review, or a `PUT` that fails, posts a new review. Only the engine's own signed notices count, so
3364
+ * a person cannot plant the marker; the bot's login is shared by every workflow of the repository.
3365
+ * Only an automatic run's notice is edited or edited over: it carries the cost line and the
3366
+ * signature the ceiling reads, and a manual run's body has neither.
3367
+ */
3368
+ export function postRefusalReview(deps: Deps, repo: string, pr: number, headSha: string, review: Review): string | undefined {
3369
+ if (deps.config.dryRun) return postReview(deps, repo, pr, headSha, review);
3370
+ const sleep = deps.sleep ?? blockingSleep;
3371
+ const jq = '.[] | select(.user.login == "github-actions[bot]") | {id, body} | @json';
3372
+ let latest: { id: number; body: string | null } | undefined;
3373
+ try {
3374
+ const reviews = jsonLines<{ id: number; body: string | null }>(
3375
+ deps.gh(["api", "--paginate", `repos/${repo}/pulls/${pr}/reviews`, "--jq", jq]),
3376
+ );
3377
+ latest = reviews[reviews.length - 1];
3378
+ } catch (error) {
3379
+ deps.warn(`Could not list the reviews to look for an earlier refusal; posting a new review. ${error}`);
3380
+ }
3381
+ if (latest && REFUSAL_NOTICE.test((latest.body ?? "").trimEnd())) {
3382
+ for (let retry = 0; ; retry++) {
3383
+ try {
3384
+ const answer = deps.gh(
3385
+ ["api", "-X", "PUT", `repos/${repo}/pulls/${pr}/reviews/${latest.id}`, "--input", "-"],
3386
+ JSON.stringify({ body: review.body }),
3387
+ );
3388
+ return reviewUrlOf(answer);
3389
+ } catch (error) {
3390
+ const delay = REVIEW_RETRY_DELAYS_MS[retry];
3391
+ if (!isTransientReviewError(error) || delay === undefined) {
3392
+ deps.warn(`Could not edit the earlier refusal notice; posting a new review. ${error}`);
3393
+ break;
3394
+ }
3395
+ deps.warn(`GitHub answered with a transient error; retrying in ${delay / 1000} s. ${error}`);
3396
+ sleep(delay);
3397
+ }
3398
+ }
3399
+ }
3400
+ return postReview(deps, repo, pr, headSha, review);
3401
+ }
3402
+
2873
3403
  /**
2874
3404
  * Runs one call so that its failure does not end the review: the batches that did run still
2875
3405
  * post. A call that died without a result is counted at its cap, since what it spent is unknown.
2876
3406
  */
2877
- export function attempt<T>(
2878
- run: () => T,
3407
+ export async function attempt<T>(
3408
+ run: () => Promise<T> | T,
2879
3409
  capUsd: number,
2880
- ): { ok: true; value: T } | { ok: false; error: string; costUsd: number } {
3410
+ ): Promise<{ ok: true; value: T } | { ok: false; error: string; costUsd: number }> {
2881
3411
  try {
2882
- return { ok: true, value: run() };
3412
+ return { ok: true, value: await run() };
2883
3413
  } catch (error) {
2884
3414
  return { ok: false, error: String(error).slice(0, 300), costUsd: capUsd };
2885
3415
  }
@@ -2917,6 +3447,25 @@ export interface ReviewOptions {
2917
3447
  * by `reviewOptionsOf`: a local review and an incremental or scoped one have no grade.
2918
3448
  */
2919
3449
  confidence?: { budgetUsd: number };
3450
+ /**
3451
+ * The priority A/B (ADR 0059): a pull request review records its `arm` in the result. Set by the
3452
+ * pull request review from `WACHIMAN_PRIORITY_TRIAL=1`, never by `reviewOptionsOf`: a local review
3453
+ * never joins the trial, and a change that is not a pull request has no arm either way.
3454
+ */
3455
+ priorityTrial?: boolean;
3456
+ /**
3457
+ * The repository's memory, loaded from the base commit by the connector (ADR 0056). It is
3458
+ * recorded in the result and, when over budget, announced in the summary. Its conventions go
3459
+ * into the discovery prompt; its exceptions are matched against the findings afterwards, in one
3460
+ * small call, and never reach a discovery prompt (ADR 0057). Absent when the repository has no `.wachiman/memory/` folder.
3461
+ */
3462
+ memory?: MemoryLoad;
3463
+ /**
3464
+ * Every path the whole change touches, for the memory exceptions' `holds while` check (ADR 0057
3465
+ * decision 4): the names before and after a rename, and the deleted files, also when this run
3466
+ * reviews only what changed since the last review. Absent: the paths of `input.files`.
3467
+ */
3468
+ changedPaths?: string[];
2920
3469
  }
2921
3470
 
2922
3471
  /** Today's settings as the core's options. */
@@ -2944,7 +3493,7 @@ export function reviewOptionsOf(config: EngineConfig, totalBudgetUsd: number, pr
2944
3493
  * checks, coverage, the one retry, budget arithmetic, merging, the confidence rule, dedupe, the
2945
3494
  * ADR notices, the anchors and the "not reached" skips are here. Posting is not.
2946
3495
  */
2947
- export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: CoreDeps): ReviewResult {
3496
+ export async function reviewChange(input: ReviewInput, options: ReviewOptions, deps: CoreDeps): Promise<ReviewResult> {
2948
3497
  assertReviewInputFormat(input);
2949
3498
  const started = Date.now();
2950
3499
  // Every warning the core logs is also a notice of the result; `runProvider` appends one entry
@@ -2968,13 +3517,21 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2968
3517
  // The verifier's reserve is taken first, so the batches cannot spend it; at most half the total,
2969
3518
  // so a small budget still reviews something (a review with no findings has nothing to verify).
2970
3519
  const reserve = options.verify ? Math.min(options.verify.budgetUsd, totalBudget / 2) : 0;
2971
- const batchTotal = totalBudget - reserve;
3520
+ // The memory exceptions that may act on this diff (ADR 0057). When there are any, the matching
3521
+ // call's money is reserved too, so the batches cannot spend it; no exception, no reserve.
3522
+ const exceptionPlan = planExceptions(options.memory, options.changedPaths ?? touchedPathsOf(input.files), kept.map((f) => f.filename));
3523
+ const matchReserve = exceptionPlan.active.length > 0 ? Math.min(MEMORY_MATCH_BUDGET_USD, (totalBudget - reserve) / 4) : 0;
3524
+ const batchTotal = totalBudget - reserve - matchReserve;
2972
3525
  const batchBudget = options.batchBudgetUsd;
2973
- const batches = planBatches(kept, {
2974
- maxLines: options.batchLines,
2975
- // About 40k tokens at 3.5 characters a token.
2976
- maxChars: options.batchChars,
2977
- });
3526
+ const batches = planBatches(
3527
+ kept,
3528
+ {
3529
+ maxLines: options.batchLines,
3530
+ // About 40k tokens at 3.5 characters a token.
3531
+ maxChars: options.batchChars,
3532
+ },
3533
+ input.pathRules,
3534
+ );
2978
3535
  // The files this run reviews whole because the previous review did not reach them.
2979
3536
  const keptNames = new Set(kept.map((f) => f.filename));
2980
3537
  const carriedHere = (input.since?.carried ?? []).filter((f) => keptNames.has(f));
@@ -2994,7 +3551,9 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
2994
3551
  dropped: dropped.length,
2995
3552
  everyFile,
2996
3553
  meta: { title: change.title, body: change.description, author: change.author },
2997
- instructions: renderInstructions(input.instructions),
3554
+ // The hand-written files first, then the learned conventions, which they outrank (ADR 0057). No exception is ever here.
3555
+ instructions: renderInstructions(input.instructions) + renderConventions(options.memory),
3556
+ ...(input.pathRules?.length ? { pathRules: input.pathRules } : {}),
2998
3557
  costTags: { repo: change.repository.name, ...(number ? { pr: Number(number) } : {}) },
2999
3558
  };
3000
3559
 
@@ -3008,7 +3567,7 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3008
3567
  // is spent before the batches, so they cannot overspend the pull request's budget.
3009
3568
  const confidence = change.kind === "pull-request" ? options.confidence : undefined;
3010
3569
  const claimsStep = confidence
3011
- ? listClaims(core, options, context, Math.min(confidence.budgetUsd, batchTotal / 4))
3570
+ ? await listClaims(core, options, context, Math.min(confidence.budgetUsd, batchTotal / 4))
3012
3571
  : undefined;
3013
3572
  if (claimsStep) {
3014
3573
  spent += claimsStep.costUsd;
@@ -3035,51 +3594,88 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3035
3594
  else rejection ??= { kind: r.kind, text: r.text };
3036
3595
  };
3037
3596
 
3038
- batches.forEach((batch, i) => {
3039
- const label = `Batch ${i + 1} of ${batches.length}`;
3040
- const remaining = () => batchTotal - spent;
3041
- if (rejection) {
3042
- rejectedFiles.push(...batch.files.map((f) => f.filename));
3043
- reports.push({
3044
- label,
3045
- files: batch.files.length,
3046
- lines: batch.lines,
3047
- maxRisk: batch.maxRisk,
3048
- status: "not run: provider rejected the call",
3049
- turns: 0,
3050
- costUsd: 0,
3051
- });
3052
- return;
3053
- }
3054
- if (remaining() < MIN_BATCH_USD) {
3055
- notRun.push(...batch.files.map((f) => f.filename));
3056
- reports.push({
3057
- label,
3058
- files: batch.files.length,
3059
- lines: batch.lines,
3060
- maxRisk: batch.maxRisk,
3061
- status: "not run: budget spent",
3062
- turns: 0,
3063
- costUsd: 0,
3064
- });
3065
- return;
3597
+ // Batches run side by side, at most `BATCH_CONCURRENCY` at a time, launched in risk order. Each
3598
+ // one ends in its own outcome; the report, the parts and the file lists are put together in
3599
+ // batch order afterwards, so the finish order does not decide them. Warnings and the cost rows
3600
+ // are recorded as the calls end, and name their batch.
3601
+ interface BatchOutcome {
3602
+ report: BatchReport;
3603
+ parts: { label: string; output: ReviewOutput }[];
3604
+ notRun: string[];
3605
+ rejectedFiles: string[];
3606
+ budgetCut: string[];
3607
+ usage: TokenUsage;
3608
+ budgetError: boolean;
3609
+ stopped?: "turns" | "timeout";
3610
+ anyLimit: boolean;
3611
+ /** What the provider refused or failed with, to be reported in batch order, not in finish order. */
3612
+ rejections: NonNullable<BatchResult["rejection"]>[];
3613
+ }
3614
+ const outcomes: (BatchOutcome | undefined)[] = new Array(batches.length).fill(undefined);
3615
+ // Money the batches in flight may still spend: what each reserved, until its cost is known.
3616
+ const reserved = new Map<number, number>();
3617
+ let inFlight = 0;
3618
+ let fatal: { error: unknown } | undefined;
3619
+ const waiters: (() => void)[] = [];
3620
+ const changed = () => new Promise<void>((resolve) => waiters.push(resolve));
3621
+ const notify = () => waiters.splice(0).forEach((resolve) => resolve());
3622
+ const room = () => batchTotal - spent - [...reserved.values()].reduce((sum, usd) => sum + usd, 0);
3623
+ /**
3624
+ * Reserves `min(batchBudget, room)` for batch `id`, or says why it cannot run. While the room is
3625
+ * below the minimum but money is reserved by batches in flight, it waits: what they do not spend
3626
+ * comes back, and giving up now would skip a batch that a sequential run would have afforded.
3627
+ */
3628
+ const acquire = async (id: number, launching: boolean): Promise<{ usd: number } | { why: "rejected" | "budget" | "failed" }> => {
3629
+ for (;;) {
3630
+ if (fatal) return { why: "failed" };
3631
+ if (rejection) return { why: "rejected" };
3632
+ if (!launching || inFlight < BATCH_CONCURRENCY) {
3633
+ const left = room();
3634
+ if (left >= MIN_BATCH_USD) {
3635
+ const usd = Math.min(batchBudget, left);
3636
+ reserved.set(id, usd);
3637
+ return { usd };
3638
+ }
3639
+ if (reserved.size === 0) return { why: "budget" };
3640
+ }
3641
+ await changed();
3066
3642
  }
3067
- const first = reviewBatchBackingOff(
3643
+ };
3644
+
3645
+ const runBatch = async (i: number, batch: Batch, firstBudget: number): Promise<BatchOutcome> => {
3646
+ const label = `Batch ${i + 1} of ${batches.length}`;
3647
+ const out: BatchOutcome = {
3648
+ report: { label, files: batch.files.length, lines: batch.lines, maxRisk: batch.maxRisk, status: "", turns: 0, costUsd: 0 },
3649
+ parts: [],
3650
+ notRun: [],
3651
+ rejectedFiles: [],
3652
+ budgetCut: [],
3653
+ usage: NO_USAGE,
3654
+ budgetError: false,
3655
+ anyLimit: false,
3656
+ rejections: [],
3657
+ };
3658
+ core.log(`batch ${i + 1}/${batches.length}: started (${inFlight} of ${BATCH_CONCURRENCY} running, $${firstBudget.toFixed(2)} reserved)`);
3659
+ const first = await reviewBatchBackingOff(
3068
3660
  core,
3069
3661
  options,
3070
3662
  context,
3071
3663
  batch.files,
3072
3664
  threadsByBatch[i],
3073
3665
  { index: i + 1, total: batches.length },
3074
- Math.min(batchBudget, remaining()),
3666
+ firstBudget,
3075
3667
  );
3668
+ // The reservation gives way to what the call really cost.
3076
3669
  spent += first.costUsd;
3077
- usage = addUsage(usage, first.usage);
3670
+ reserved.delete(i);
3671
+ notify();
3672
+ out.usage = addUsage(out.usage, first.usage);
3078
3673
  noteRejection(first.rejection);
3079
- if (first.output) parts.push({ label, output: first.output });
3080
- if (first.budget) budgetError = true;
3081
- if (first.stopped) limitError = first.stopped;
3082
- if (first.budget || first.stopped) anyLimit = true;
3674
+ if (first.rejection) out.rejections.push(first.rejection);
3675
+ if (first.output) out.parts.push({ label, output: first.output });
3676
+ if (first.budget) out.budgetError = true;
3677
+ if (first.stopped) out.stopped = first.stopped;
3678
+ if (first.budget || first.stopped) out.anyLimit = true;
3083
3679
  let status = first.output
3084
3680
  ? "reviewed"
3085
3681
  : first.budget
@@ -3096,53 +3692,127 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3096
3692
  let turns = first.turns;
3097
3693
  let cost = first.costUsd;
3098
3694
 
3099
- // One retry with only the files the first pass left unaccounted for.
3695
+ // One retry with only the files the first pass left unaccounted for, in the same slot.
3100
3696
  const gaps = batchGaps(batch.files, first.output);
3101
3697
  // After a wall-clock kill the same files would likely run into the same limit, and another
3102
3698
  // full timeout could exhaust the job's own limit: they are reported as not reviewed instead.
3103
3699
  // A refused call (no credit, bad key) would be refused again: no retry.
3104
- if (gaps.length > 0 && first.stopped !== "timeout" && !rejection && remaining() >= MIN_BATCH_USD) {
3105
- const retry = reviewBatchBackingOff(
3700
+ // Only this batch's own refusal explains its gaps; another batch's refusal only stops new calls.
3701
+ const ownRefusal = first.rejection !== undefined && first.rejection.kind !== "other";
3702
+ const grant = gaps.length > 0 && first.stopped !== "timeout" && !ownRefusal ? await acquire(i, false) : undefined;
3703
+ if (gaps.length > 0 && grant && "usd" in grant) {
3704
+ const retry = await reviewBatchBackingOff(
3106
3705
  core,
3107
3706
  options,
3108
3707
  context,
3109
3708
  gaps,
3110
3709
  [],
3111
3710
  { index: i + 1, total: batches.length, retry: true },
3112
- Math.min(batchBudget, remaining()),
3711
+ grant.usd,
3113
3712
  );
3114
3713
  spent += retry.costUsd;
3115
- usage = addUsage(usage, retry.usage);
3714
+ reserved.delete(i);
3715
+ notify();
3716
+ out.usage = addUsage(out.usage, retry.usage);
3116
3717
  turns += retry.turns;
3117
3718
  cost += retry.costUsd;
3118
3719
  noteRejection(retry.rejection);
3119
- if (retry.budget || retry.stopped) anyLimit = true;
3120
- if (retry.output) parts.push({ label: `${label}, retry`, output: retry.output });
3720
+ if (retry.rejection) out.rejections.push(retry.rejection);
3721
+ if (retry.budget || retry.stopped) out.anyLimit = true;
3722
+ if (retry.output) out.parts.push({ label: `${label}, retry`, output: retry.output });
3121
3723
  const left = batchGaps(gaps, retry.output);
3122
- if (retry.rejection && retry.rejection.kind !== "other") rejectedFiles.push(...left.map((f) => f.filename));
3123
- else if (retry.budget) budgetCut.push(...left.map((f) => f.filename));
3724
+ if (retry.rejection && retry.rejection.kind !== "other") out.rejectedFiles.push(...left.map((f) => f.filename));
3725
+ else if (retry.budget) out.budgetCut.push(...left.map((f) => f.filename));
3124
3726
  status =
3125
3727
  left.length === 0 ? "reviewed after a retry" : `${left.length} file(s) left after a retry`;
3126
3728
  } else if (gaps.length > 0) {
3127
- status = rejection
3729
+ // The files are blamed on a refusal when this batch's own call was refused, or when another
3730
+ // batch's refusal stopped the retry of a call that had no cause of its own (a budget or a limit).
3731
+ const refused =
3732
+ ownRefusal ||
3733
+ (grant !== undefined && "why" in grant && grant.why === "rejected" && !first.budget && !first.stopped);
3734
+ status = refused
3128
3735
  ? `${gaps.length} file(s) left: the provider rejected the call`
3129
3736
  : first.stopped === "timeout"
3130
3737
  ? `${gaps.length} file(s) left: the call timed out`
3131
3738
  : `${gaps.length} file(s) left: budget spent`;
3132
3739
  // A refused call or a spent budget is not the files' doing; a timeout may be, so it stays unexplained.
3133
- if (rejection) rejectedFiles.push(...gaps.map((f) => f.filename));
3134
- else if (first.stopped !== "timeout") budgetCut.push(...gaps.map((f) => f.filename));
3740
+ if (refused) out.rejectedFiles.push(...gaps.map((f) => f.filename));
3741
+ else if (first.stopped !== "timeout") out.budgetCut.push(...gaps.map((f) => f.filename));
3135
3742
  }
3136
- reports.push({
3137
- label,
3138
- files: batch.files.length,
3139
- lines: batch.lines,
3140
- maxRisk: batch.maxRisk,
3141
- status,
3142
- turns,
3143
- costUsd: cost,
3743
+ out.report = { ...out.report, status, turns, costUsd: cost };
3744
+ return out;
3745
+ };
3746
+
3747
+ const running = new Set<Promise<void>>();
3748
+ for (const [i, batch] of batches.entries()) {
3749
+ const label = `Batch ${i + 1} of ${batches.length}`;
3750
+ const skipped = (status: string, files: string[]): BatchOutcome => ({
3751
+ report: { label, files: batch.files.length, lines: batch.lines, maxRisk: batch.maxRisk, status, turns: 0, costUsd: 0 },
3752
+ parts: [],
3753
+ notRun: status === "not run: budget spent" ? files : [],
3754
+ rejectedFiles: status === "not run: budget spent" ? [] : files,
3755
+ budgetCut: [],
3756
+ usage: NO_USAGE,
3757
+ budgetError: false,
3758
+ anyLimit: false,
3759
+ rejections: [],
3144
3760
  });
3145
- });
3761
+ const granted = await acquire(i, true);
3762
+ if ("why" in granted) {
3763
+ if (granted.why === "failed") break;
3764
+ const files = batch.files.map((f) => f.filename);
3765
+ outcomes[i] =
3766
+ granted.why === "rejected"
3767
+ ? skipped("not run: provider rejected the call", files)
3768
+ : skipped("not run: budget spent", files);
3769
+ continue;
3770
+ }
3771
+ // A batch that threw while this one waited for its slot: give the money back and start nothing.
3772
+ if (fatal) {
3773
+ reserved.delete(i);
3774
+ break;
3775
+ }
3776
+ inFlight++;
3777
+ const task: Promise<void> = runBatch(i, batch, granted.usd)
3778
+ .then(
3779
+ (outcome) => void (outcomes[i] = outcome),
3780
+ (error) => void (fatal ??= { error }),
3781
+ )
3782
+ .finally(() => {
3783
+ inFlight--;
3784
+ reserved.delete(i);
3785
+ running.delete(task);
3786
+ notify();
3787
+ });
3788
+ running.add(task);
3789
+ }
3790
+ await Promise.all(running);
3791
+ // A batch that threw (not a failed call: those are outcomes) ends the review as it always did,
3792
+ // after the ones in flight finished and were counted.
3793
+ if (fatal) throw fatal.error;
3794
+
3795
+ // In batch order, whatever order they finished in. The refusal that stopped new batches was noted
3796
+ // as it came; the one that is reported is the first in batch order, as in a sequential run.
3797
+ rejection = undefined;
3798
+ otherError = undefined;
3799
+ for (const outcome of outcomes) {
3800
+ if (!outcome) continue;
3801
+ outcome.rejections.forEach(noteRejection);
3802
+ reports.push(outcome.report);
3803
+ parts.push(...outcome.parts);
3804
+ notRun.push(...outcome.notRun);
3805
+ rejectedFiles.push(...outcome.rejectedFiles);
3806
+ budgetCut.push(...outcome.budgetCut);
3807
+ usage = addUsage(usage, outcome.usage);
3808
+ if (outcome.budgetError) budgetError = true;
3809
+ if (outcome.stopped) limitError = outcome.stopped;
3810
+ if (outcome.anyLimit) anyLimit = true;
3811
+ }
3812
+
3813
+ // Set by the callbacks above, which the compiler does not follow.
3814
+ const refused = rejection as { kind: Exclude<ProviderErrorClass, "other">; text: string } | undefined;
3815
+ const other = otherError as string | undefined;
3146
3816
 
3147
3817
  const merged: ReviewOutput =
3148
3818
  parts.length > 0
@@ -3166,12 +3836,18 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3166
3836
  let verification: ResultVerificationV2 | undefined;
3167
3837
  let checked: VerifiedFinding[];
3168
3838
  if (options.verify && parts.length > 0) {
3169
- const verified = verifyFindings(core, options, context, merged.findings, kept, Math.max(totalBudget - spent, 0), rejection?.text);
3839
+ const verified = await verifyFindings(core, options, context, merged.findings, kept, Math.max(totalBudget - spent - matchReserve, 0), refused?.text);
3170
3840
  spent += verified.record.costUsd;
3171
3841
  usage = addUsage(usage, verified.usage);
3172
3842
  checked = verified.findings;
3173
3843
  verification = verified.record;
3174
3844
  } else checked = annotateUnverified(merged.findings);
3845
+ // After verification, so the floor applies to the final severity (ADR 0057). Muted findings leave
3846
+ // the list here: nothing below, the anchors, the fidelity grade or the posting, ever sees them.
3847
+ const memoryStep = await matchExceptions(core, options, context, exceptionPlan, checked, Math.max(totalBudget - spent, 0), refused?.text);
3848
+ spent += memoryStep.costUsd;
3849
+ usage = addUsage(usage, memoryStep.usage);
3850
+ checked = memoryStep.findings;
3175
3851
  for (const path of notRun)
3176
3852
  merged.files_skipped.push({ path, reason: "not reached: the pull request's budget was spent" });
3177
3853
  // A file the model listed itself, with a reason of its own, is replaced: the run's own cause comes first.
@@ -3195,9 +3871,6 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3195
3871
  const known = new Set(threads.map((t) => t.comment_id));
3196
3872
  const threadReplies = merged.thread_replies.filter((r) => known.has(r.comment_id));
3197
3873
 
3198
- // Assigned inside the loop's callbacks, which the compiler does not follow.
3199
- const refused = rejection as { kind: Exclude<ProviderErrorClass, "other">; text: string } | undefined;
3200
- const other = otherError as string | undefined;
3201
3874
  const firstRejection = refused ?? (other !== undefined ? { kind: "other" as const, text: other } : undefined);
3202
3875
  // In today's precedence: a refused account stops everything; a review with output, or nothing
3203
3876
  // to review, is complete (coverage says whether it is partial); otherwise the limit that ended
@@ -3218,7 +3891,8 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3218
3891
  // contracts' lines are: the file must be in the review and the line must exist at the head.
3219
3892
  const lineCount = deps.lineCounter ?? repoLineCounter(input.headDir);
3220
3893
  const riskMap = buildRiskMap({
3221
- files: kept.map((f) => ({ path: f.filename, changedLines: f.additions + f.deletions })),
3894
+ ...(input.pathRules?.length ? { pathRules: input.pathRules } : {}),
3895
+ files: kept.map((f) => ({ path: f.filename, changedLines: f.additions + f.deletions, ...(f.previous_filename ? { previousPath: f.previous_filename } : {}) })),
3222
3896
  facts: parts.flatMap((p) => wellFormed<RiskFact>(p.output.risk_facts, RISK_KINDS)),
3223
3897
  judgement: parts.flatMap((p) => wellFormed<JudgementItem>(p.output.judgement, JUDGEMENT_KINDS)),
3224
3898
  unreadFiles: expected.filter((f) => !reviewedSet.has(f)).length,
@@ -3266,6 +3940,8 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3266
3940
  },
3267
3941
  });
3268
3942
  }
3943
+ // The trial arm: a pull request only, by its number; a change without one has none.
3944
+ const arm = options.priorityTrial && change.kind === "pull-request" && number ? armFor(change.repository.name, Number(number)) : undefined;
3269
3945
  return {
3270
3946
  format: REVIEW_RESULT_V2,
3271
3947
  change,
@@ -3281,14 +3957,17 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3281
3957
  },
3282
3958
  findings,
3283
3959
  contracts: merged.contracts ?? [],
3284
- summary: merged.summary,
3960
+ summary: withMemoryNotices(merged.summary, options.memory, memoryStep.text),
3285
3961
  riskMap,
3962
+ ...(options.memory ? { memory: memoryRecord(options.memory) } : {}),
3963
+ ...(memoryStep.muted.length > 0 ? { muted: memoryStep.muted } : {}),
3286
3964
  batches: reports,
3287
3965
  threadReplies,
3288
3966
  instructionChanges: {
3289
3967
  files: changedInstructionFiles(input.files.map((f) => f.filename)),
3290
3968
  baseSha: input.instructions.baseSha,
3291
3969
  },
3970
+ ...(input.pathPolicyChanged ? { pathPolicyChanged: true as const } : {}),
3292
3971
  execution: {
3293
3972
  costUsdEstimate: spent,
3294
3973
  usage,
@@ -3302,6 +3981,7 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3302
3981
  },
3303
3982
  ...(verification ? { verification } : {}),
3304
3983
  ...(fidelity ? { fidelity } : {}),
3984
+ ...(arm ? { arm } : {}),
3305
3985
  };
3306
3986
  }
3307
3987
 
@@ -3310,12 +3990,12 @@ export function reviewChange(input: ReviewInput, options: ReviewOptions, deps: C
3310
3990
  * from the author's text alone (Wachiman's own block stripped). It fails closed: with no list the
3311
3991
  * review still runs, and the grade is `cannot say`. A call that cannot be afforded is not made.
3312
3992
  */
3313
- function listClaims(
3993
+ async function listClaims(
3314
3994
  deps: CoreDeps,
3315
3995
  options: ReviewOptions,
3316
3996
  ctx: ReviewContext,
3317
3997
  budgetUsd: number,
3318
- ): { claims?: ProposedClaim[]; costUsd: number; usage: TokenUsage; budget: boolean; truncated: boolean } {
3998
+ ): Promise<{ claims?: ProposedClaim[]; costUsd: number; usage: TokenUsage; budget: boolean; truncated: boolean }> {
3319
3999
  const input = claimsInput(ctx.meta.title ?? "", ctx.meta.body);
3320
4000
  const truncated = claimsTextTruncated(input);
3321
4001
  const none = { costUsd: 0, usage: NO_USAGE, budget: false, truncated };
@@ -3324,7 +4004,7 @@ function listClaims(
3324
4004
  return { ...none, budget: true };
3325
4005
  }
3326
4006
  const prompt = buildClaimsPrompt(input);
3327
- const call = attempt(
4007
+ const call = await attempt(
3328
4008
  () => runProvider(deps, options, ctx.headDir, { operation: "review", label: "claims", ...ctx.costTags }, prompt, ctx.headDir, budgetUsd, CLAIMS_SCHEMA),
3329
4009
  budgetUsd,
3330
4010
  );
@@ -3370,7 +4050,7 @@ function verdictsOf(structured: unknown): VerifierVerdict[] | undefined {
3370
4050
  * `inconclusive` with the stop as their reason. Findings it left at low confidence go through the
3371
4051
  * confidence rule again.
3372
4052
  */
3373
- function verifyFindings(
4053
+ async function verifyFindings(
3374
4054
  deps: CoreDeps,
3375
4055
  options: ReviewOptions & { verify: { model: string; budgetUsd: number } },
3376
4056
  ctx: ReviewContext,
@@ -3378,7 +4058,7 @@ function verifyFindings(
3378
4058
  files: ReviewFile[],
3379
4059
  budgetUsd: number,
3380
4060
  refused?: string,
3381
- ): { findings: VerifiedFinding[]; record: ResultVerificationV2; usage: TokenUsage } {
4061
+ ): Promise<{ findings: VerifiedFinding[]; record: ResultVerificationV2; usage: TokenUsage }> {
3382
4062
  const verifier = deps.verifier ?? deps.provider;
3383
4063
  // Without its own adapter the call runs on the reviewer's, whose model and effort are fixed at construction.
3384
4064
  const ran = deps.verifier ? { model: options.verify.model, effort: "high" } : { model: options.model, effort: options.effort };
@@ -3419,7 +4099,7 @@ function verifyFindings(
3419
4099
  const prompt = buildVerifyPrompt({ describe: ctx.describe, headSha: ctx.headSha, headDir: ctx.headDir, baseDir: baseSnap?.dir, candidates, files });
3420
4100
  dir = mkdtempSync(join(tmpdir(), "agent-verify-"));
3421
4101
  const runDir = dir;
3422
- const call = attempt(
4102
+ const call = await attempt(
3423
4103
  () =>
3424
4104
  runProvider(
3425
4105
  { ...deps, provider: verifier },
@@ -3467,6 +4147,73 @@ function verifyFindings(
3467
4147
  }
3468
4148
  }
3469
4149
 
4150
+ /** The most the matching call may spend (ADR 0057): a small call, since it compares a few findings with a few entries. */
4151
+ export const MEMORY_MATCH_BUDGET_USD = 0.25;
4152
+
4153
+ /**
4154
+ * The matching step of ADR 0057: one call, after discovery and verification, that says which
4155
+ * Consider and Info findings an in-scope memory exception covers. The engine decides what the
4156
+ * answer does (`applyMatches`): the floor, the known ids and the exception's scope are checked in
4157
+ * code. No call is made without a candidate and an exception that can cover it. The step fails
4158
+ * open: a call that fails, stops or answers nothing usable mutes nothing, and the summary and the
4159
+ * notices say matching did not run.
4160
+ */
4161
+ async function matchExceptions<F extends Finding>(
4162
+ deps: CoreDeps,
4163
+ options: ReviewOptions,
4164
+ ctx: ReviewContext,
4165
+ plan: ExceptionPlan,
4166
+ findings: F[],
4167
+ budgetUsd: number,
4168
+ refused?: string,
4169
+ ): Promise<{ findings: F[]; muted: MutedFinding[]; costUsd: number; usage: TokenUsage; text?: string }> {
4170
+ const request = matchRequest(plan.active, findings);
4171
+ // `failure` is a generic reason and goes to the public summary; `detail` (provider text) goes to the local log only.
4172
+ const finish = (rest: { findings: F[]; muted: MutedFinding[]; costUsd: number; usage: TokenUsage }, failure?: string, detail?: string) => {
4173
+ if (failure) deps.warn(`Memory exceptions were not applied: matching did not run (${oneLine(failure, 200)}${detail ? `: ${oneLine(detail, 300)}` : ""}); every finding is posted.`);
4174
+ const text = renderMuting({ muted: rest.muted, stale: plan.stale, ...(failure ? { failure } : {}) });
4175
+ return { ...rest, ...(text ? { text } : {}) };
4176
+ };
4177
+ const none = { findings, muted: [] as MutedFinding[], costUsd: 0, usage: NO_USAGE };
4178
+ if (!request) return finish(none);
4179
+ // The same account refused a batch; the matching call would most likely be refused too.
4180
+ if (refused) return finish(none, "the provider rejected an earlier call", refused);
4181
+ const cap = Math.min(MEMORY_MATCH_BUDGET_USD, budgetUsd);
4182
+ if (cap < MIN_BATCH_USD) return finish(none, "no budget left for the matching call");
4183
+ const dir = mkdtempSync(join(tmpdir(), "agent-memory-"));
4184
+ try {
4185
+ const call = await attempt(
4186
+ () => runProvider(deps, options, ctx.headDir, { operation: "review", label: "memory match", ...ctx.costTags }, buildMatchPrompt({ describe: ctx.describe, request }), dir, cap, MATCH_SCHEMA),
4187
+ cap,
4188
+ );
4189
+ if (!call.ok) {
4190
+ // As for a returned error: what the provider said stays in the local log, the summary gets the generic reason.
4191
+ deps.warn(`Memory matching call failed: ${oneLine(call.error, 300)}`);
4192
+ return finish({ ...none, costUsd: call.costUsd }, "the call failed");
4193
+ }
4194
+ const result = call.value;
4195
+ const spend = { costUsd: result.costUsd, usage: result.usage ?? NO_USAGE };
4196
+ if (result.isError || result.terminalReason === "budget" || result.terminalReason === "turns" || result.terminalReason === "timeout") {
4197
+ // The provider's text is for the local log only; the public summary gets the generic reason.
4198
+ if (result.isError && result.errorText) deps.warn(`Memory matching call failed (${result.providerError ?? "other"}): ${oneLine(result.errorText, 300)}`);
4199
+ return finish({ ...none, ...spend }, `the call ended on ${result.isError ? "an error" : `its ${result.terminalReason} limit`}`);
4200
+ }
4201
+ const matches = parseMatches(result.structuredOutput);
4202
+ if (!matches) return finish({ ...none, ...spend }, "the answer was not usable");
4203
+ const applied = applyMatches(findings, plan.active, matches);
4204
+ deps.log(`Memory: ${applied.muted.length} finding(s) muted by an exception, ${applied.protectedBy.length} posted although an exception matched them.`);
4205
+ return finish({ findings: applied.posted, muted: applied.muted, ...spend });
4206
+ } finally {
4207
+ rmSync(dir, { recursive: true, force: true });
4208
+ }
4209
+ }
4210
+
4211
+ /** The summary, then the memory's notices after it: the over-budget notice, and what exceptions did. Absent notices add nothing. */
4212
+ function withMemoryNotices(summary: string, memory: MemoryLoad | undefined, muting?: string) {
4213
+ const notices = [memory ? memoryNotice(memoryRecord(memory)) : undefined, muting].filter((n): n is string => n !== undefined);
4214
+ return notices.reduce((text, notice) => (text === "" ? notice : `${text}\n\n${notice}`), summary);
4215
+ }
4216
+
3470
4217
  /** The GitHub connector: today's pull request facts as a `ReviewInput`. Pure; `review()` read them. */
3471
4218
  export function githubReviewInput(p: {
3472
4219
  repo: string;
@@ -3484,6 +4231,10 @@ export function githubReviewInput(p: {
3484
4231
  /** The files of `files` the previous partial review did not reach (they carry their whole diff). */
3485
4232
  carried?: string[];
3486
4233
  threads: Thread[];
4234
+ /** The base commit's `paths` rules; omitted or empty when the repository has none. */
4235
+ pathRules?: PathRule[];
4236
+ /** The pull request edits the path rules; `pathRules` then ends with the rule for `.wachiman.yml`. */
4237
+ pathPolicyChanged?: boolean;
3487
4238
  }): ReviewInput {
3488
4239
  return {
3489
4240
  format: REVIEW_INPUT_FORMAT,
@@ -3514,6 +4265,8 @@ export function githubReviewInput(p: {
3514
4265
  }
3515
4266
  : {}),
3516
4267
  ...(p.threads.length > 0 ? { conversation: p.threads } : {}),
4268
+ ...(p.pathRules?.length ? { pathRules: p.pathRules } : {}),
4269
+ ...(p.pathPolicyChanged ? { pathPolicyChanged: true as const } : {}),
3517
4270
  };
3518
4271
  }
3519
4272
 
@@ -3575,7 +4328,9 @@ export function githubReview(
3575
4328
  receiptLine: github.receiptLine,
3576
4329
  mention: github.mention,
3577
4330
  instructionChanges: github.instructionChanges,
4331
+ ...(result.pathPolicyChanged ? { pathPolicyChange: { baseSha: github.instructionChanges.baseSha } } : {}),
3578
4332
  riskMap: result.riskMap,
4333
+ ...(result.arm ? { arm: result.arm } : {}),
3579
4334
  ...(result.fidelity ? { fidelity: result.fidelity } : {}),
3580
4335
  pushOnly: github.since !== null,
3581
4336
  ...(result.verification ? { verification: result.verification } : {}),
@@ -3584,10 +4339,10 @@ export function githubReview(
3584
4339
  }
3585
4340
 
3586
4341
  /** `force` (`--force`) counts only for the operator's own run, never an automatic trigger. */
3587
- export function review(deps: Deps, repo: string, pr: number, words: string[], force = false) {
4342
+ export async function review(deps: Deps, repo: string, pr: number, words: string[], force = false) {
3588
4343
  const { gh, config } = deps;
3589
4344
  const meta = JSON.parse(
3590
- gh(["pr", "view", String(pr), "-R", repo, "--json", "headRefOid,title,body,author"]),
4345
+ gh(["pr", "view", String(pr), "-R", repo, "--json", "headRefOid,baseRefName,title,body,author"]),
3591
4346
  );
3592
4347
  const headSha: string = meta.headRefOid;
3593
4348
  const bodyOnly = (body: string) =>
@@ -3658,11 +4413,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[], fo
3658
4413
  deps.log(why);
3659
4414
  // The marker moves so that the next push is compared with this head, not with the old one.
3660
4415
  postReview(deps, repo, pr, headSha, {
3661
- body: [
3662
- branded(`Brought up to date with the base branch, no new changes since \`${short(last)}\`.`),
3663
- SIGNATURE.review,
3664
- marker(headSha),
3665
- ].join("\n\n"),
4416
+ body: baseUpdateNotice({ base: meta.baseRefName, from: last, to: headSha, version: deps.engineVersion }, marker(headSha)),
3666
4417
  comments: [],
3667
4418
  });
3668
4419
  };
@@ -3723,11 +4474,7 @@ export function review(deps: Deps, repo: string, pr: number, words: string[], fo
3723
4474
  );
3724
4475
  // The marker moves so that the next push is compared with this head, not with the old one.
3725
4476
  postReview(deps, repo, pr, headSha, {
3726
- body: [
3727
- branded(`Rebased onto \`${short(base)}\`, no new changes since \`${short(last)}\`.`),
3728
- SIGNATURE.review,
3729
- marker(headSha),
3730
- ].join("\n\n"),
4477
+ body: baseUpdateNotice({ base: meta.baseRefName, from: last, to: headSha, version: deps.engineVersion }, marker(headSha)),
3731
4478
  comments: [],
3732
4479
  });
3733
4480
  return;
@@ -3780,11 +4527,19 @@ export function review(deps: Deps, repo: string, pr: number, words: string[], fo
3780
4527
  }
3781
4528
  // The size gate: what this run would send, priced before any model call. Nothing is posted as a
3782
4529
  // review and no marker is written, so the next push sees no marker and gates again.
3783
- const estimate = estimateFor(allBinary.reviewable, config);
4530
+ // The path rules come from the base commit whatever the model and effort inputs say; they reorder
4531
+ // the batches, so the estimate is made with them.
4532
+ const base = baseSha(gh, repo, pr);
4533
+ const baseRules = readBasePathRules(gh, repo, base, deps.warn);
4534
+ // A pull request that edits the rules is reviewed under the base's, and `.wachiman.yml` itself is
4535
+ // a critical path for that review: the head's rules are never applied, only compared.
4536
+ const pathPolicyChanged = touchesSettingsFile(prFiles) && headEditsPathRules(gh, repo, headSha, baseRules);
4537
+ const pathRules = pathPolicyChanged ? withPolicyEditRule(baseRules) : baseRules;
4538
+ const estimate = estimateFor(allBinary.reviewable, config, pathRules);
3784
4539
  const gate = sizeGate(config, isAutomatic(config.trigger));
3785
4540
  if (estimate.usd > gate) {
3786
4541
  deps.log(`Estimated $${estimate.usd.toFixed(2)} is above the $${gate.toFixed(2)} size gate; nothing sent to a model.`);
3787
- postSizeGateNotice(deps, repo, pr, headSha, estimate, gate);
4542
+ postSizeGateNotice(deps, repo, pr, headSha, estimate, gate, criticalPathsOf(allBinary.reviewable, pathRules));
3788
4543
  return;
3789
4544
  }
3790
4545
  // After the rebase exits above (they cost nothing and move the marker) and before any paid step.
@@ -3793,12 +4548,14 @@ export function review(deps: Deps, repo: string, pr: number, words: string[], fo
3793
4548
  // What the automatic runs before this one cost; an operator's run is not counted and shows none.
3794
4549
  const automatic = isAutomatic(config.trigger);
3795
4550
  const prior = automatic ? { spent: ceiling.spent, runs: ceiling.runs } : undefined;
3796
- const base = baseSha(gh, repo, pr);
3797
4551
  const instructions = readBaseInstructions(gh, repo, base, deps.warn);
4552
+ // The memory of the base commit, selected by the files this run reviews (ADR 0056): not the
4553
+ // excluded, out-of-scope or binary ones that `files` still holds.
4554
+ const memory = readBaseMemory(gh, repo, base, allBinary.reviewable.map((f) => f.filename), deps.warn);
3798
4555
  const batchBudget = config.batchBudgetUsd;
3799
4556
  // Only threads that wait for an answer (the owner wrote last, Wachiman has replies left): a
3800
4557
  // thread Wachiman already answered is not read again, so it is not answered twice (ADR 0008).
3801
- const threads = last ? pendingThreads(fetchThreads(gh, repo, pr)) : [];
4558
+ const threads = last ? pendingThreads(fetchThreads(gh, repo, pr), config.mention, config.memoryProposals, config.operator) : [];
3802
4559
  const input = githubReviewInput({
3803
4560
  repo,
3804
4561
  pr,
@@ -3814,6 +4571,8 @@ export function review(deps: Deps, repo: string, pr: number, words: string[], fo
3814
4571
  commits,
3815
4572
  carried: resumed,
3816
4573
  threads,
4574
+ pathRules,
4575
+ pathPolicyChanged,
3817
4576
  });
3818
4577
  // PR Confidence grades a full review only (ADR 0033): an incremental or scoped review reads a
3819
4578
  // part of the change, and "nothing else changed" cannot be said of a part.
@@ -3824,59 +4583,59 @@ export function review(deps: Deps, repo: string, pr: number, words: string[], fo
3824
4583
  const totalBudget = Math.min(config.budgetUsd, ceiling.room, grant.roomUsd);
3825
4584
  const options: ReviewOptions = {
3826
4585
  ...reviewOptionsOf(config, totalBudget),
4586
+ ...(memory ? { memory } : {}),
4587
+ // The check of `holds while` reads the whole pull request, not the delta this run reviews.
4588
+ changedPaths: touchedPathsOf(prFiles),
3827
4589
  ...(config.confidence && fullReview ? { confidence: { budgetUsd: CLAIMS_BUDGET_USD } } : {}),
4590
+ ...(config.priorityTrial ? { priorityTrial: true } : {}),
3828
4591
  };
3829
- const result = settledOnError(deps, grant, () => reviewChange(input, options, deps));
4592
+ const result = await settledOnError(deps, grant, () => reviewChange(input, options, deps));
3830
4593
  const { usage, costUsdEstimate: spent } = result.execution;
3831
4594
  const operation: Operation = since ? "re-review" : "review";
3832
4595
  const receiptLine = spendSettle(deps, grant, spent) ?? undefined;
3833
4596
 
3834
4597
  if (result.execution.callsWithOutput === 0) {
3835
4598
  // A failed automatic run still spent money: its notice carries the cost line the ceiling sums.
3836
- const spentNotice = (text: string) =>
3837
- isAutomatic(config.trigger)
3838
- ? postReview(deps, repo, pr, headSha, {
3839
- body: [
3840
- branded(text),
3841
- ...(receiptLine ? [receiptLine] : []),
3842
- costLine({
3843
- modelLabel: result.provider.label,
3844
- effort: config.effort,
3845
- operation,
3846
- extra: prior ? [prSoFar(prior, spent)] : [],
3847
- usage,
3848
- estimate: onSubscription(deps),
3849
- costUsd: spent,
3850
- }),
3851
- SIGNATURE.auto,
3852
- SIGNATURE.review,
3853
- ].join("\n\n"),
3854
- comments: [],
3855
- })
3856
- : // A manual run keeps its receipt and forced/bypass lines, but not `SIGNATURE.auto`: the ceiling does not count it.
3857
- receiptLine
3858
- ? postReview(deps, repo, pr, headSha, { body: [branded(text), receiptLine].join("\n\n"), comments: [] })
3859
- : bodyOnly(text);
4599
+ // A manual run keeps its receipt and forced/bypass lines, but not `SIGNATURE.auto`: the ceiling does not count it.
4600
+ // `replaceable` is for a $0 refusal only: it may edit the earlier refusal notice in place.
4601
+ const sendNotice = (blocks: string[], replaceable = false) => {
4602
+ const body = isAutomatic(config.trigger)
4603
+ ? [
4604
+ ...blocks,
4605
+ ...(receiptLine ? [receiptLine] : []),
4606
+ costLine({
4607
+ modelLabel: result.provider.label,
4608
+ effort: config.effort,
4609
+ operation,
4610
+ extra: prior ? [prSoFar(prior, spent)] : [],
4611
+ usage,
4612
+ estimate: onSubscription(deps),
4613
+ costUsd: spent,
4614
+ }),
4615
+ SIGNATURE.auto,
4616
+ SIGNATURE.review,
4617
+ ].join("\n\n")
4618
+ : [...blocks, ...(receiptLine ? [receiptLine] : [])].join("\n\n");
4619
+ return (replaceable ? postRefusalReview : postReview)(deps, repo, pr, headSha, { body, comments: [] });
4620
+ };
4621
+ const spentNotice = (text: string) => sendNotice([branded(text)]);
3860
4622
  const { rejection, stop } = result.execution;
3861
4623
  const refused = rejection && rejection.kind !== "other" ? { kind: rejection.kind, text: rejection.text } : undefined;
3862
4624
  if (refused) {
3863
- // On a subscription token the key is not the credential: say what fits it, and that nothing falls back to a key.
3864
- const headline = (
3865
- deps.provider.auth === "oauth-token"
3866
- ? {
3867
- billing: "**Not reviewed: the reviewer's Claude subscription refused the call (usage limit or plan access).** Re-run after the limit resets. Wachiman does not fall back to an API key.",
3868
- auth: "**Not reviewed: the reviewer's Claude subscription token was rejected.** Check the `CLAUDE_CODE_OAUTH_TOKEN` secret (a token lasts a year; make a new one with `claude setup-token`), then re-run.",
3869
- rate_limit: "**Not reviewed: Claude kept rate-limiting the reviewer.** Re-run later.",
3870
- }
3871
- : {
3872
- billing: "**Not reviewed: the reviewer's Anthropic account has no credit.** Top up, then re-run this job.",
3873
- auth: "**Not reviewed: the reviewer's API key was rejected.** Check the `ANTHROPIC_API_KEY` secret, then re-run.",
3874
- rate_limit: "**Not reviewed: the Anthropic API kept rate-limiting the reviewer.** Re-run later.",
3875
- }
3876
- )[refused.kind];
3877
4625
  // `oneLine` neutralises the text and cuts it at 300 characters.
3878
4626
  const detail = oneLine(refused.text, 300);
3879
- spentNotice(detail ? `${headline}\n\n> ${detail}` : headline);
4627
+ const { headline, table } = refusalNotice({
4628
+ kind: refused.kind,
4629
+ auth: deps.provider.auth,
4630
+ detail,
4631
+ spentUsd: spent,
4632
+ ...(prior ? { priorSpentUsd: prior.spent } : {}),
4633
+ });
4634
+ // Only an automatic run's notice that spent nothing may be replaced by the next one, and only it
4635
+ // carries the marker. A manual run's body has no signature and no cost line, so replacing an
4636
+ // automatic notice with it would erase that run from the ceiling.
4637
+ const free = spent === 0 && isAutomatic(config.trigger);
4638
+ sendNotice([branded(headline), table, ...(free ? [refusalMarker(refused.kind)] : [])], free);
3880
4639
  if (config.onProviderUnavailable === "fail") {
3881
4640
  throw new Error(`Not reviewed: the provider rejected the call (${refused.kind}): ${detail || "no error text"}`);
3882
4641
  }
@@ -3964,6 +4723,8 @@ export interface ThreadReply {
3964
4723
  comment_id: number;
3965
4724
  status: "addressed" | "still_open";
3966
4725
  reply: string;
4726
+ /** An entry for repository memory, proposed from the owner's latest instruction (only with `memory_proposals`). */
4727
+ memory?: { kind?: unknown; scope?: unknown; rule?: unknown; why?: unknown; holds_while?: unknown } | null;
3967
4728
  /** `path:line` or `path:from-to` the reply rests on; every one is checked against the head. */
3968
4729
  cites: string[];
3969
4730
  }
@@ -3991,6 +4752,41 @@ export const THREAD_SCHEMA = {
3991
4752
  },
3992
4753
  };
3993
4754
 
4755
+ /**
4756
+ * The thread schema with an optional `memory` object on each reply: the entry the owner's latest
4757
+ * instruction asks for (layer 5). Only used when `memory_proposals` is on, so a run without it sends
4758
+ * `THREAD_SCHEMA` and the prompt it always did.
4759
+ */
4760
+ export const THREAD_SCHEMA_WITH_MEMORY = {
4761
+ ...THREAD_SCHEMA,
4762
+ properties: {
4763
+ thread_replies: {
4764
+ type: "array",
4765
+ items: {
4766
+ ...THREAD_SCHEMA.properties.thread_replies.items,
4767
+ // Codex's structured output is strict: every property is required and an optional one is a union with
4768
+ // null. So the model answers `memory: null` for no proposal and `holds_while: null` for no condition.
4769
+ required: [...THREAD_SCHEMA.properties.thread_replies.items.required, "memory"],
4770
+ properties: {
4771
+ ...THREAD_SCHEMA.properties.thread_replies.items.properties,
4772
+ memory: {
4773
+ type: ["object", "null"],
4774
+ additionalProperties: false,
4775
+ required: ["kind", "scope", "rule", "why", "holds_while"],
4776
+ properties: {
4777
+ kind: { enum: ["convention", "exception"] },
4778
+ scope: { type: "string" },
4779
+ rule: { type: "string" },
4780
+ why: { type: "string" },
4781
+ holds_while: { type: ["string", "null"] },
4782
+ },
4783
+ },
4784
+ },
4785
+ },
4786
+ },
4787
+ },
4788
+ };
4789
+
3994
4790
  /** Lines on each side of a thread's line that the thread file shows as the current code. */
3995
4791
  const EXCERPT_RADIUS = 12;
3996
4792
  const EXCERPT_MAX_CHARS = 4000;
@@ -4013,8 +4809,27 @@ export function codeAround(repoDir: string, path: string, line: number | null) {
4013
4809
  }
4014
4810
  }
4015
4811
 
4812
+ /**
4813
+ * Added to the thread prompt when `memory_proposals` is on (layer 5). The model only drafts the
4814
+ * fields; the engine builds the entry, shows it to the owner and writes it only after the owner's
4815
+ * `remember <id>`.
4816
+ */
4817
+ const MEMORY_PROPOSAL_PROMPT = `
4818
+
4819
+ Repository memory. When the latest reply in a thread is the owner's own explicit instruction about how
4820
+ code in this repository should be written, or which kind of finding they do not want, and it gives a
4821
+ reason, set that thread's "memory" to an object: kind ("convention" for how code is written here,
4822
+ "exception" for one kind of finding the owner does not want), scope (a path glob), rule (one sentence),
4823
+ why (the owner's reason, in their terms) and holds_while (the paths that fact lives in, only when the reason
4824
+ is a fact about the code, as in "this caller already validates"; otherwise null). An exception names one kind of finding
4825
+ in a path scope: never write an entry that excludes files from review ("do not review the auth files").
4826
+ Do not propose memory for the details of one feature, a one-time exception, the temporary state of a
4827
+ migration, or anything a formatter or linter can enforce. Most replies are not such an instruction: then
4828
+ set "memory" to null. The owner approves the entry separately and you never write it, so your reply text
4829
+ must not say it was recorded.`;
4830
+
4016
4831
  /** The prompt of a thread-only run. The threads, their replies and the code are in `threads.json`. */
4017
- export function buildThreadsPrompt(ctx: { pr: number; repo: string; headSha: string }, dir: string) {
4832
+ export function buildThreadsPrompt(ctx: { pr: number; repo: string; headSha: string }, dir: string, memoryProposals = false) {
4018
4833
  return `You are answering replies in review threads that Wachiman opened on pull request #${ctx.pr} in ${ctx.repo}.
4019
4834
  The repository is checked out at its head commit ${ctx.headSha}. No file is being reviewed in this run:
4020
4835
  do not report new findings, only answer the threads.
@@ -4042,7 +4857,7 @@ root. The engine checks each one against the head and drops a reply whose cite d
4042
4857
  You only read code: write "read", never "tested" or "verified by running". You cannot resolve a
4043
4858
  thread and must not offer to. Keep each reply to a few sentences, in English. When wachi_replies is
4044
4859
  1, this is your last reply in the thread: end it with what you are waiting for from the owner.
4045
- Answer every thread once. Answer no thread that is not in the file.`;
4860
+ Answer every thread once. Answer no thread that is not in the file.${memoryProposals ? MEMORY_PROPOSAL_PROMPT : ""}`;
4046
4861
  }
4047
4862
 
4048
4863
  /**
@@ -4052,7 +4867,7 @@ Answer every thread once. Answer no thread that is not in the file.`;
4052
4867
  * It is an automatic run: it counts against the pull request's ceiling. It follows ADR 0008: it
4053
4868
  * reports, it never resolves.
4054
4869
  */
4055
- export function threadReplies(deps: Deps, repo: string, pr: number, author?: string) {
4870
+ export async function threadReplies(deps: Deps, repo: string, pr: number, author?: string) {
4056
4871
  const { gh, config } = deps;
4057
4872
  // As in `comment`: before anything is read, so a stranger's reply on a public repository (or a
4058
4873
  // placeholder operator) starts no paid step. The workflow's `if:` checks the same login.
@@ -4074,7 +4889,7 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
4074
4889
  );
4075
4890
  return;
4076
4891
  }
4077
- const pending = pendingThreads(fetchThreads(gh, repo, pr));
4892
+ const pending = pendingThreads(fetchThreads(gh, repo, pr), config.mention, config.memoryProposals, config.operator);
4078
4893
  if (pending.length === 0) {
4079
4894
  deps.log("No Wachiman thread waits for an answer.");
4080
4895
  return;
@@ -4097,16 +4912,16 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
4097
4912
  const grant = spendReserve(deps, repo, pr, headSha, Math.min(config.threadsBudgetUsd, ceiling.room), false);
4098
4913
  const budgetUsd = Math.min(config.threadsBudgetUsd, ceiling.room, grant.roomUsd);
4099
4914
  if (grantTooSmall(deps, grant, "thread replies")) return;
4100
- const call = settledOnError(deps, grant, () =>
4915
+ const call = await settledOnError(deps, grant, () =>
4101
4916
  runProvider(
4102
4917
  deps,
4103
4918
  config,
4104
4919
  repoDir,
4105
4920
  { operation: "reply", label: "threads", repo, pr },
4106
- buildThreadsPrompt({ pr, repo, headSha }, dir),
4921
+ buildThreadsPrompt({ pr, repo, headSha }, dir, config.memoryProposals),
4107
4922
  dir,
4108
4923
  budgetUsd,
4109
- THREAD_SCHEMA,
4924
+ config.memoryProposals ? THREAD_SCHEMA_WITH_MEMORY : THREAD_SCHEMA,
4110
4925
  ),
4111
4926
  );
4112
4927
  const receiptLine = spendSettle(deps, grant, call.costUsd);
@@ -4133,12 +4948,52 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
4133
4948
  }
4134
4949
  replies.push({ reply: r, cites });
4135
4950
  }
4136
- refuseLeak(deps, replies.map((r) => r.reply.reply));
4951
+ // A proposal is shown only for a thread whose latest reply is the operator's own (layer 5): a collaborator's
4952
+ // words, or a model's idea of them, never become an entry the operator is asked to approve.
4953
+ const proposals = new Map<number, Candidate>();
4954
+ // Why a proposal was dropped, in the engine's own words (never the model's): the reply may still talk about
4955
+ // a proposal, so the engine says under it that there is nothing to approve.
4956
+ const dropped = new Map<number, string>();
4957
+ if (config.memoryProposals) {
4958
+ const date = today(new Date(deps.now?.() ?? Date.now()));
4959
+ for (const { reply } of replies) {
4960
+ const proposed: unknown = reply.memory;
4961
+ // `null` is the strict schema's form of "no proposal" (`THREAD_SCHEMA_WITH_MEMORY`), the same as leaving it out.
4962
+ if (proposed === undefined || proposed === null) continue;
4963
+ // The model's own field: anything but an object is no proposal, never an error that fails a run whose cost is spent.
4964
+ if (typeof proposed !== "object" || Array.isArray(proposed)) {
4965
+ deps.warn(`Memory proposal for thread ${reply.comment_id} dropped: it is not an object.`);
4966
+ dropped.set(reply.comment_id, "the proposal was not in a usable shape");
4967
+ continue;
4968
+ }
4969
+ const fields = proposed as NonNullable<typeof reply.memory>;
4970
+ const latest = pending.find((t) => t.comment_id === reply.comment_id)?.replies.at(-1);
4971
+ if (latest?.author.toLowerCase() !== config.operator.trim().toLowerCase()) {
4972
+ deps.warn(`Memory proposal for thread ${reply.comment_id} dropped: the latest reply there is not the operator's.`);
4973
+ dropped.set(reply.comment_id, "the latest reply in this thread is not the operator's");
4974
+ continue;
4975
+ }
4976
+ try {
4977
+ const text = (v: unknown) => (typeof v === "string" ? v : "");
4978
+ const holds = typeof fields.holds_while === "string" && fields.holds_while.trim() !== "" ? fields.holds_while : undefined;
4979
+ const candidate = newCandidate({ kind: text(fields.kind), scope: text(fields.scope), rule: text(fields.rule), why: text(fields.why), ...(holds ? { holdsWhile: holds } : {}) }, { date, source: "instruction", pr, agent: false }, date);
4980
+ const shown = renderEntry(candidate);
4981
+ if (neutralise(shown) !== shown) throw new UsageError("the entry contains an HTML comment marker");
4982
+ if (proposability(candidate, 1).proposable === false) throw new UsageError("the entry is not proposable");
4983
+ proposals.set(reply.comment_id, candidate);
4984
+ } catch (error) {
4985
+ if (!(error instanceof UsageError)) throw error;
4986
+ deps.warn(`Memory proposal for thread ${reply.comment_id} dropped: ${error.message}`);
4987
+ dropped.set(reply.comment_id, "the entry did not pass the checks for a memory entry (the run log says which)");
4988
+ }
4989
+ }
4990
+ }
4991
+ refuseLeak(deps, [...replies.map((r) => r.reply.reply), ...[...proposals.values()].map(renderEntry)]);
4137
4992
 
4138
4993
  // ADR 0008: recheck the head and each thread before posting. A push since the start means its
4139
4994
  // review answers; a thread someone answered meanwhile is not answered twice.
4140
4995
  const stillPending = new Set<number>();
4141
- if (headOf() === headSha) for (const t of pendingThreads(fetchThreads(gh, repo, pr))) stillPending.add(t.comment_id);
4996
+ if (headOf() === headSha) for (const t of pendingThreads(fetchThreads(gh, repo, pr), config.mention, config.memoryProposals, config.operator)) stillPending.add(t.comment_id);
4142
4997
  const toPost = replies.filter((r) => stillPending.has(r.reply.comment_id));
4143
4998
  if (toPost.length < replies.length)
4144
4999
  deps.log(`${replies.length - toPost.length} reply(ies) not posted: the head moved or the thread changed meanwhile.`);
@@ -4155,7 +5010,10 @@ export function threadReplies(deps: Deps, repo: string, pr: number, author?: str
4155
5010
  i === 0
4156
5011
  ? `${receiptLine ? `\n\n${receiptLine}` : ""}\n\n${costLine({ modelLabel: deps.provider.modelLabel(), effort: config.effort, operation: "reply", extra: [`answers ${toPost.length} thread(s)`, prSoFar(prior, call.costUsd)], usage: call.usage, estimate: onSubscription(deps), costUsd: call.costUsd })}\n\n${SIGNATURE.auto}`
4157
5012
  : `\n\n<sub>this run $${call.costUsd.toFixed(2)} · ${prSoFar(prior, call.costUsd)}${estimateTail(onSubscription(deps))}</sub>`;
4158
- const body = `${branded(`**${label}**`)} at \`${short(headSha)}\`: ${neutralise(reply.reply)}${cost}\n\n${SIGNATURE.reply}`;
5013
+ const proposal = proposals.get(reply.comment_id);
5014
+ const why = dropped.get(reply.comment_id);
5015
+ const proposed = proposal ? `\n\n${renderProposal(proposal, config.mention)}` : why ? `\n\nNo memory entry was proposed: ${why}, so there is nothing to approve.` : "";
5016
+ const body = `${branded(`**${label}**`)} at \`${short(headSha)}\`: ${neutralise(reply.reply)}${proposed}${cost}\n\n${SIGNATURE.reply}`;
4159
5017
  if (config.dryRun) {
4160
5018
  deps.log(`--- reply to ${reply.comment_id}: ${label} ---\n${body}`);
4161
5019
  return;
@@ -4183,6 +5041,8 @@ export interface ReviewContext {
4183
5041
  meta: { title?: string; body?: string; author?: string };
4184
5042
  /** `renderInstructions` of the base commit's rules. */
4185
5043
  instructions: string;
5044
+ /** The repository's path rules (`paths` in `.wachiman.yml`, from the base commit); a matched file's line in the prompt quotes its rule. */
5045
+ pathRules?: readonly PathRule[];
4186
5046
  /** PR Confidence on: the claims the batches assign their files to, as the claims call listed them. */
4187
5047
  claims?: readonly string[];
4188
5048
  /** How the cost log line names the change; absent for a change with no repository or number. */
@@ -4230,7 +5090,11 @@ export function buildBatchPrompt(
4230
5090
  ) {
4231
5091
  const carried = new Set(ctx.carried ?? []);
4232
5092
  const list = files
4233
- .map((f) => `- ${f.filename} +${f.additions} −${f.deletions}${carried.has(f.filename) ? " (not reached by the previous review: whole diff)" : ""}`)
5093
+ .map((f) => {
5094
+ const rule = matchPathRule(f.filename, ctx.pathRules, f.previous_filename);
5095
+ const ruleNote = rule ? ` — ${neutralise(`path rule ${rule.severity} (${rule.match}): ${rule.reason}`)}` : "";
5096
+ return `- ${f.filename} +${f.additions} −${f.deletions}${carried.has(f.filename) ? " (not reached by the previous review: whole diff)" : ""}${ruleNote}`;
5097
+ })
4234
5098
  .join("\n");
4235
5099
  const sinceScope = ctx.since
4236
5100
  ? ctx.rebased
@@ -4415,8 +5279,8 @@ function gatherEvidence(deps: CoreDeps, headDir: string, files: ReviewFile[], di
4415
5279
  type CallLimits = Pick<EngineConfig, "maxTurns" | "callTimeoutS" | "model" | "trigger">;
4416
5280
 
4417
5281
  /** One provider call over one batch, with the batch's diff inside the prompt. */
4418
- function reviewBatch(
4419
- deps: CoreDeps,
5282
+ async function reviewBatch(
5283
+ core: CoreDeps,
4420
5284
  limits: CallLimits,
4421
5285
  ctx: ReviewContext,
4422
5286
  files: ReviewFile[],
@@ -4424,6 +5288,8 @@ function reviewBatch(
4424
5288
  part: { index: number; total: number; retry?: boolean },
4425
5289
  budgetUsd: number,
4426
5290
  ) {
5291
+ // Batches run side by side, so every line this one prints names it.
5292
+ const deps = attributed(core, part);
4427
5293
  const dir = mkdtempSync(join(tmpdir(), "wachiman-review-"));
4428
5294
  // The run dir holds the change's text (title, body, threads, evidence): removed once the call
4429
5295
  // is over, whatever happened. Nothing reads it after the provider returns.
@@ -4454,7 +5320,7 @@ function reviewBatch(
4454
5320
  );
4455
5321
 
4456
5322
  const label = `batch ${part.index}/${part.total}${part.retry ? " retry" : ""}`;
4457
- const call = attempt(
5323
+ const call = await attempt(
4458
5324
  () =>
4459
5325
  runProvider(
4460
5326
  deps,
@@ -4505,17 +5371,33 @@ function reviewBatch(
4505
5371
  /** Where a rate-limited call waits before its one retry, in ms. Overridable through `Deps` so tests do not sleep. */
4506
5372
  const RATE_LIMIT_BACKOFF_MS = 20_000;
4507
5373
 
4508
- type BatchResult = ReturnType<typeof reviewBatch>;
5374
+ type BatchResult = Awaited<ReturnType<typeof reviewBatch>>;
5375
+
5376
+ /**
5377
+ * `core` whose log and warning lines each name the batch that printed them (`batch 2/7: ...`),
5378
+ * unless the line already does (the call summary and the cost line carry the label themselves).
5379
+ */
5380
+ function attributed(core: CoreDeps, part: { index: number; total: number }): CoreDeps {
5381
+ const mentions = new RegExp(`\\b(batch ${part.index}/${part.total}|batch ${part.index} of ${part.total}|part ${part.index} of ${part.total})\\b`, "i");
5382
+ const tag = (line: string) => (mentions.test(line) ? line : `batch ${part.index}/${part.total}: ${line}`);
5383
+ return { ...core, log: (line) => core.log(tag(line)), warn: (line) => core.warn(tag(line)) };
5384
+ }
5385
+
5386
+ /** Waits `ms` without blocking the other batches. A test's own `sleep` replaces the wait. */
5387
+ async function pause(deps: CoreDeps, ms: number) {
5388
+ if (deps.sleep) deps.sleep(ms);
5389
+ else await new Promise<void>((resolve) => setTimeout(resolve, ms));
5390
+ }
4509
5391
 
4510
5392
  /** `reviewBatch`, with one retry of the same batch after a backoff when the API rate-limited the call. */
4511
- function reviewBatchBackingOff(...args: Parameters<typeof reviewBatch>): BatchResult {
5393
+ async function reviewBatchBackingOff(...args: Parameters<typeof reviewBatch>): Promise<BatchResult> {
4512
5394
  const [deps, , , , , part] = args;
4513
- const first = reviewBatch(...args);
5395
+ const first = await reviewBatch(...args);
4514
5396
  if (first.rejection?.kind !== "rate_limit") return first;
4515
5397
  const wait = deps.rateLimitBackoffMs ?? RATE_LIMIT_BACKOFF_MS;
4516
5398
  deps.warn(`Batch ${part.index} of ${part.total} was rate-limited; retrying once in ${wait / 1000} s.`);
4517
- (deps.sleep ?? blockingSleep)(wait);
4518
- const again = reviewBatch(...args);
5399
+ await pause(deps, wait);
5400
+ const again = await reviewBatch(...args);
4519
5401
  return {
4520
5402
  ...again,
4521
5403
  turns: first.turns + again.turns,
@@ -4525,7 +5407,7 @@ function reviewBatchBackingOff(...args: Parameters<typeof reviewBatch>): BatchRe
4525
5407
  }
4526
5408
 
4527
5409
  /** The prompt goes through stdin: a batch's diff in an argument would hit Linux's 128 KB limit. */
4528
- export function runProvider(
5410
+ export async function runProvider(
4529
5411
  deps: CoreDeps,
4530
5412
  limits: CallLimits,
4531
5413
  cwd: string,
@@ -4538,9 +5420,9 @@ export function runProvider(
4538
5420
  extraDirs: string[] = [],
4539
5421
  ) {
4540
5422
  const started = Date.now();
4541
- let result: ReturnType<ProviderAdapter["run"]>;
5423
+ let result: Awaited<ReturnType<ProviderAdapter["run"]>>;
4542
5424
  try {
4543
- result = deps.provider.run({
5425
+ result = await deps.provider.run({
4544
5426
  prompt,
4545
5427
  cwd,
4546
5428
  addDirs: [dir, ...extraDirs],
@@ -4574,6 +5456,7 @@ export function runProvider(
4574
5456
  if (result.costKnown === false) result = { ...result, costUsd: budgetUsd };
4575
5457
  deps.log(
4576
5458
  JSON.stringify({
5459
+ label: what.label,
4577
5460
  is_error: result.isError,
4578
5461
  terminal_reason: result.terminalReason,
4579
5462
  turns: result.turns,
@@ -4686,8 +5569,18 @@ export function askLedger(gh: GhFn, repo: string, pr: number) {
4686
5569
  function threadBefore(gh: GhFn, repo: string, pr: number, line: ReviewLineComment): string | undefined {
4687
5570
  const root = threadRoot(line);
4688
5571
  const thread = fetchThreads(gh, repo, pr).find((t) => t.comments.nodes[0]?.databaseId === root);
4689
- const earlier = (thread?.comments.nodes ?? []).filter((n) => n.databaseId < line.id).slice(-10);
4690
- const text = earlier.map((n) => `@${n.author?.login ?? "ghost"}: ${neutralise(n.body)}`).join("\n\n");
5572
+ return earlierThreadText(thread?.comments.nodes ?? [], line.id);
5573
+ }
5574
+
5575
+ /** The text of the comments before `lineId`, the ask prompt's view: a finding table as today's label. */
5576
+ export function earlierThreadText(
5577
+ nodes: { databaseId: number; author: { login: string } | null; body: string }[],
5578
+ lineId: number,
5579
+ ): string | undefined {
5580
+ const earlier = nodes.filter((n) => n.databaseId < lineId).slice(-10);
5581
+ const text = earlier
5582
+ .map((n) => `@${n.author?.login ?? "ghost"}: ${neutralise(legacyFindingComment(n.body))}`)
5583
+ .join("\n\n");
4691
5584
  if (text === "") return undefined;
4692
5585
  return text.length > 4000 ? `…${text.slice(-4000)}` : text;
4693
5586
  }
@@ -4717,7 +5610,7 @@ function postAnswer(deps: Deps, repo: string, pr: number, body: string, line?: R
4717
5610
  * For someone but the operator, the answer is marked with its cost (`readAskCost`), and a call that
4718
5611
  * fails still posts a note with its cost, so the question ceiling counts what was spent.
4719
5612
  */
4720
- export function answer(deps: Deps, repo: string, pr: number, question: string, options: AnswerOptions = {}) {
5613
+ export async function answer(deps: Deps, repo: string, pr: number, question: string, options: AnswerOptions = {}) {
4721
5614
  const { asker, line } = options;
4722
5615
  const dir = mkdtempSync(join(tmpdir(), "agent-answer-"));
4723
5616
  const meta = deps.gh(["pr", "view", String(pr), "-R", repo, "--json", "title,body,files,headRefOid"]);
@@ -4754,10 +5647,10 @@ export function answer(deps: Deps, repo: string, pr: number, question: string, o
4754
5647
  else postAnswer(deps, repo, pr, body, line);
4755
5648
  return;
4756
5649
  }
4757
- let result: ReturnType<typeof runProvider> | undefined;
5650
+ let result: Awaited<ReturnType<typeof runProvider>> | undefined;
4758
5651
  let failure = "";
4759
5652
  try {
4760
- result = runProvider(
5653
+ result = await runProvider(
4761
5654
  deps,
4762
5655
  deps.config,
4763
5656
  cwd,
@@ -4848,24 +5741,35 @@ function postAskLimit(deps: Deps, repo: string, pr: number, spent: number) {
4848
5741
  * write access, and while the pull request's question ceiling has room (ADR 0032 decision 9).
4849
5742
  * An empty or placeholder operator is an error.
4850
5743
  */
4851
- export function comment(deps: Deps, repo: string, pr: number, request: string, author?: string, line?: ReviewLineComment) {
5744
+ export async function comment(deps: Deps, repo: string, pr: number, request: string, author?: string, line?: ReviewLineComment) {
4852
5745
  const { operator, askers } = deps.config;
4853
5746
  // Before anything else: an unset or placeholder operator would let a stranger who registered
4854
5747
  // that login command the tool.
4855
5748
  const problem = operatorProblem(operator);
4856
5749
  if (problem) throw new Error(problem);
4857
- const command = parseCommand(request, deps.config.mention);
5750
+ const parsed = parseCommand(request, deps.config.mention);
4858
5751
  // Without an author, the caller is the operator (manual CLI use, as before), unless collaborators
4859
5752
  // may ask: then nobody is trusted without a login. A dry run posts nothing, so it keeps the manual path.
4860
5753
  const operatorAsked =
4861
5754
  author === undefined ? askers === "operator" || deps.config.dryRun : author.toLowerCase() === operator.toLowerCase();
5755
+ // `/wachiman remember <id>` is the memory write job's (layer 5). No shipped route sends it here: `routeMode` keeps it
5756
+ // in the thread run, which skips it, and the `comment` job only gets top-level comments. This guards a direct call:
5757
+ // the operator's own reply in a thread, with `memory_proposals` on, is left to the job and costs no model call.
5758
+ // Anything else (the flag off, a top-level comment, anyone but the operator) is an ordinary comment, so a
5759
+ // collaborator's `remember <id>` is answered or refused like any other comment, never dropped silently.
5760
+ const command = parsed?.kind === "remember" && !(deps.config.memoryProposals && line?.replyTo && operatorAsked) ? ({ kind: "answer" } as const) : parsed;
5761
+ // With the write job wired it is neither a review nor a question, so no model call.
5762
+ if (command?.kind === "remember") {
5763
+ deps.log("A `remember` command is handled by the memory write job; nothing to do here.");
5764
+ return;
5765
+ }
4862
5766
  if (operatorAsked) {
4863
5767
  if (command?.kind === "review") {
4864
5768
  // With no ledger `--force` means nothing: it stays a word that names no file, as it always did.
4865
5769
  const words = deps.config.ledgerUrl ? command.paths.filter((w) => w !== "--force") : command.paths;
4866
- review(deps, repo, pr, words, command.force);
5770
+ await review(deps, repo, pr, words, command.force);
4867
5771
  }
4868
- else if (command) answer(deps, repo, pr, request, { line });
5772
+ else if (command) await answer(deps, repo, pr, request, { line });
4869
5773
  return;
4870
5774
  }
4871
5775
  if (askers !== "write") {
@@ -4891,5 +5795,5 @@ export function comment(deps: Deps, repo: string, pr: number, request: string, a
4891
5795
  if (!ledger.latestIsLimit) postAskLimit(deps, repo, pr, ledger.spent);
4892
5796
  return;
4893
5797
  }
4894
- answer(deps, repo, pr, request, { asker: author, line });
5798
+ await answer(deps, repo, pr, request, { asker: author, line });
4895
5799
  }