wachiman 1.16.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 (51) hide show
  1. package/README.md +12 -0
  2. package/package.json +1 -1
  3. package/skills/wachiman-loop/SKILL.md +43 -0
  4. package/src/cli.ts +37 -6
  5. package/src/config.ts +21 -2
  6. package/src/connectors/local-git.ts +82 -1
  7. package/src/connectors/working-tree.ts +23 -1
  8. package/src/engine.ts +848 -127
  9. package/src/formats.ts +44 -3
  10. package/src/help.ts +121 -6
  11. package/src/history/command.ts +5 -5
  12. package/src/history/match.ts +24 -4
  13. package/src/history/store.ts +1 -1
  14. package/src/history/types.ts +7 -2
  15. package/src/init/agents.ts +135 -0
  16. package/src/init/args.ts +4 -2
  17. package/src/init/json.ts +82 -0
  18. package/src/init/options.ts +15 -5
  19. package/src/init/render.ts +3 -1
  20. package/src/init/run.ts +172 -18
  21. package/src/init/settings.ts +10 -0
  22. package/src/json-schema.ts +8 -0
  23. package/src/ledger.ts +2 -2
  24. package/src/local.ts +37 -9
  25. package/src/loop/command.ts +24 -2
  26. package/src/memory/candidates.ts +425 -0
  27. package/src/memory/capture.ts +298 -0
  28. package/src/memory/command.ts +195 -0
  29. package/src/memory/entries.ts +213 -0
  30. package/src/memory/hygiene.ts +291 -0
  31. package/src/memory/inspect.ts +74 -0
  32. package/src/memory/load.ts +283 -0
  33. package/src/memory/mute.ts +259 -0
  34. package/src/memory/personal.ts +253 -0
  35. package/src/memory/proposal.ts +92 -0
  36. package/src/memory/propose.ts +414 -0
  37. package/src/memory/remember.ts +187 -0
  38. package/src/memory/report.ts +250 -0
  39. package/src/memory/settings.ts +20 -0
  40. package/src/pr-template/install.ts +23 -0
  41. package/src/precision.ts +10 -2
  42. package/src/priority.ts +106 -0
  43. package/src/repo-settings.ts +166 -3
  44. package/src/risk.ts +38 -9
  45. package/src/sinks/common.ts +12 -6
  46. package/src/sinks/markdown.ts +3 -0
  47. package/src/sinks/terminal.ts +3 -0
  48. package/src/store/figures.ts +5 -4
  49. package/src/store/html.ts +1 -1
  50. package/src/verify.ts +20 -2
  51. package/templates/wachiman-review-caller.yml +7 -7
package/src/engine.ts CHANGED
@@ -34,7 +34,11 @@ import { tmpdir } from "node:os";
34
34
  import { join } from "node:path";
35
35
  import { estimateReview, sizeGate, suggestedBudget, type ReviewEstimate } from "./estimate";
36
36
  import { UsageError, isAutomatic, operatorProblem, type EngineConfig, type LimitMode, type Trigger } from "./config";
37
- import { SETTINGS_PATH, applyRepoSettings, fileSettingsNote, ignoredSettingsNote, parseRepoSettings, wantsRepoSettings, type RepoSettings } from "./repo-settings";
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";
38
42
  import {
39
43
  LedgerBadAnswer,
40
44
  LedgerNotPermitted,
@@ -74,6 +78,7 @@ import {
74
78
  type LineCounter,
75
79
  } from "./contracts";
76
80
  import { describeCall } from "./call-message";
81
+ import { armFor, priorityOf, PRIORITY_GLOSS, PRIORITY_WORD, type Arm, type Priority } from "./priority";
77
82
  import {
78
83
  annotateUnverified,
79
84
  applyVerdicts,
@@ -108,7 +113,7 @@ import { fidelitySummary } from "./fidelity/summary";
108
113
  import { publishConfidence } from "./fidelity/sink";
109
114
  import type { Fidelity } from "./fidelity/types";
110
115
  import type { ProviderErrorClass } from "./providers/errors";
111
- import type { Effort, ProviderAdapter } from "./providers/types";
116
+ import type { Effort, ProviderAdapter, ProviderAuth } from "./providers/types";
112
117
  import { renderDataPathQuestions, selectQuestions, type DataPathQuestion } from "./questions";
113
118
  import { buildRiskMap, renderRiskMap, wellFormed, type JudgementItem, type RiskFact, type RiskMap } from "./risk";
114
119
  import { ASK_SCHEMA, buildAskPrompt, checkRefs, isAskAnswer, renderAnswer } from "./ask";
@@ -139,8 +144,8 @@ export interface ReviewFile {
139
144
  patch?: string;
140
145
  /** The file's blob at the compared commit: equal blobs are equal contents. Absent for a removed file. */
141
146
  sha?: string;
142
- /** The name before a rename, as GitHub reports it. */
143
- 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;
144
149
  }
145
150
 
146
151
  /** @deprecated The name before the review core; use `ReviewFile`. Removed in the next minor release. */
@@ -251,7 +256,7 @@ export interface Review {
251
256
  }
252
257
 
253
258
  /** `force` is `--force` after `review`: spend past a spent limit. Only the operator's comment may honour it. */
254
- 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" };
255
260
 
256
261
  export const DEFAULT_EXCLUDE = [
257
262
  "**/bun.lock",
@@ -272,13 +277,32 @@ export const DEFAULT_EXCLUDE = [
272
277
  // `claude-review` is still read so repositories reviewed under that name keep their incremental state.
273
278
  const MARKER_SOURCE = "<!-- (?:wachiman|claude-review) sha=([A-Za-z0-9]+) -->";
274
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
+
294
+ /**
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.
297
+ */
298
+ export const label = (f: Finding & { origin?: Origin; priority?: Priority }, status?: string) => oneLineLabel(priorityLead(f), f, status);
299
+
275
300
  /**
276
- * `Important ยท ๐ŸŸ ๐Ÿ“ **Fix ยท docs: stale cell (confidence high)**`: the tier word, both emojis, then
277
- * the severity, topic and title in words, then the model's confidence when it gave one. The tier
278
- * stays outside the bold: the precision report reads the bold part.
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.
279
304
  */
280
- export const label = (f: Finding & { origin?: Origin }, status?: string) =>
281
- `${tierWord(f)} ยท ${SEVERITY[f.severity].emoji}${TOPIC[f.topic].emoji} **${SEVERITY[f.severity].word} ยท ${TOPIC[f.topic].word}: ${neutralise(f.title)}${detail(f, status)}**`;
305
+ export const legacyLabel = (f: Finding & { origin?: Origin }, status?: string) => oneLineLabel(tierWord(f), f, status);
282
306
  /** ` (confidence high, supported)`: the confidence the model gave and, for a local report, what the verifier found. */
283
307
  export const detail = (f: Finding, status?: string) => {
284
308
  const parts = [f.confidence ? `confidence ${f.confidence}` : "", status ?? ""].filter(Boolean);
@@ -295,6 +319,99 @@ export const BRAND = "๐Ÿ‘ฎ **Wachiman**";
295
319
  /** `text` after the brand, on the same first line. */
296
320
  export const branded = (text: string) => `${BRAND} ยท ${text}`;
297
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
+
298
415
  /** The default command keyword. A slash command, so writing it notifies no GitHub account. */
299
416
  export const DEFAULT_MENTION = "/wachiman";
300
417
  /**
@@ -320,6 +437,14 @@ export function parseCommand(body: string, keyword = DEFAULT_MENTION): Command |
320
437
  // `paths` is every word after `review`, as before the ledger: `comment` drops `--force` from it only when a ledger is set.
321
438
  return { kind: "review", paths: rest, force: rest.includes("--force") };
322
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
+ }
323
448
  return { kind: "answer" };
324
449
  }
325
450
 
@@ -430,8 +555,8 @@ export function fileKind(path: string): FileKind {
430
555
 
431
556
  /**
432
557
  * Path rules for `riskScore`. These are defaults taken from the first consumer (`ipc`, `preload`,
433
- * `main`, `apps/<name>/src`) and are the owner's to tune; per-repository configuration is planned
434
- * (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.
435
560
  * The highest matching weight wins. A test or a document scores its kind's weight whatever its
436
561
  * path, so `ipc/foo.test.ts` does not outrank the IPC code it tests.
437
562
  */
@@ -455,7 +580,26 @@ export const RISK_RULES: { glob: string; weight: number; why: string }[] = [
455
580
  const KIND_WEIGHT: Record<FileKind, number> = { code: 4, test: 2, docs: 1 };
456
581
  const riskGlobs = RISK_RULES.map((r) => ({ ...r, matcher: new Bun.Glob(r.glob) }));
457
582
 
458
- 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];
459
603
  const kind = fileKind(path);
460
604
  if (kind !== "code") return KIND_WEIGHT[kind];
461
605
  const weights = riskGlobs.filter((r) => r.matcher.match(path)).map((r) => r.weight);
@@ -490,25 +634,34 @@ const sizeOf = (f: ReviewFile) => f.additions + f.deletions;
490
634
  export function planBatches(
491
635
  files: ReviewFile[],
492
636
  limits: { maxLines: number; maxChars: number },
637
+ rules?: readonly PathRule[],
493
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);
494
652
  const modules = new Map<string, ReviewFile[]>();
495
653
  for (const f of files) {
654
+ if (matchedSet.has(f)) continue;
496
655
  const key = moduleKey(f.filename);
497
656
  modules.set(key, [...(modules.get(key) ?? []), f]);
498
657
  }
499
- const ordered = [...modules.values()]
500
- .map((group) =>
501
- group.sort(
502
- (a, b) =>
503
- riskScore(b.filename) - riskScore(a.filename) || a.filename.localeCompare(b.filename),
504
- ),
505
- )
506
- .sort(
507
- (a, b) =>
508
- riskScore(b[0].filename) - riskScore(a[0].filename) ||
509
- a[0].filename.localeCompare(b[0].filename),
510
- )
511
- .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
+ ];
512
665
 
513
666
  const batches: ReviewFile[][] = [];
514
667
  let current: ReviewFile[] = [];
@@ -533,11 +686,14 @@ export function planBatches(
533
686
  if (current.length > 0) batches.push(current);
534
687
 
535
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.
536
692
  files: [...group].sort(
537
- (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)],
538
694
  ),
539
695
  lines: group.reduce((n, f) => n + sizeOf(f), 0),
540
- maxRisk: Math.max(...group.map((f) => riskScore(f.filename))),
696
+ maxRisk: Math.max(...group.map((f) => score(f.filename))),
541
697
  }));
542
698
  }
543
699
 
@@ -995,6 +1151,27 @@ export function countLine(findings: Finding[]): string {
995
1151
  return `${findings.length} finding(s)${shown.length > 0 ? `: ${shown.join(", ")}` : ""}`;
996
1152
  }
997
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
+
998
1175
  /** The `<summary>` of the contracts block; `trimMiddle` finds the block by it. */
999
1176
  export const CONTRACTS_SUMMARY = "What the change connects to";
1000
1177
 
@@ -1101,7 +1278,7 @@ const estimateTail = (estimate: boolean) => (estimate ? ` ยท ${ESTIMATE_NOTE}` :
1101
1278
 
1102
1279
  export function buildReview(input: {
1103
1280
  /** A finding's `anchor`, when given (a `ReviewResult`'s), decides inline or body; else its file's patch does. */
1104
- 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">>)[] };
1105
1282
  files: ReviewFile[];
1106
1283
  headSha: string;
1107
1284
  since: string | null;
@@ -1136,10 +1313,14 @@ export function buildReview(input: {
1136
1313
  priorSpend?: { spent: number; runs: number };
1137
1314
  /** Review-instruction files this pull request edits, and the base commit they were read from. */
1138
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 };
1139
1318
  /** The verifier's record (ADR 0027): its outcome goes in the footer's cost line. */
1140
1319
  verification?: ResultVerificationV2;
1141
1320
  /** The run is on a Claude subscription: its dollar figures are API-price estimates (ADR 0037). */
1142
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;
1143
1324
  /** The risk map (ADR 0031), rendered right after the count line. */
1144
1325
  riskMap?: RiskMap;
1145
1326
  /** PR Confidence (ADR 0033): the grade as one line after the count line; the description block holds the rest. */
@@ -1186,7 +1367,7 @@ export function buildReview(input: {
1186
1367
  path: f.path,
1187
1368
  line: f.line,
1188
1369
  side: "RIGHT",
1189
- body: `${branded(label(f))}\n\n${neutralise(f.body)}\n\n${SIGNATURE.finding}`,
1370
+ body: `${inlineFindingBody(f, input.arm)}\n\n${SIGNATURE.finding}`,
1190
1371
  });
1191
1372
  } else outsideDiff.push(f);
1192
1373
  }
@@ -1237,9 +1418,16 @@ export function buildReview(input: {
1237
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.`,
1238
1419
  );
1239
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
+ }
1240
1426
  parts.push(
1241
1427
  `${countLine(output.findings)}; ${comments.length} on their lines. Reply in a comment's thread to answer it.`,
1242
1428
  );
1429
+ const summary = summaryLine(output.findings, input.arm);
1430
+ if (summary) parts.push(summary);
1243
1431
  if (input.fidelity) parts.push(fidelitySummary(input.fidelity));
1244
1432
  if (input.verification?.status === "failed") {
1245
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.");
@@ -1249,7 +1437,9 @@ export function buildReview(input: {
1249
1437
  // Before the findings and outside any <details> block. The size fitting below cuts the contracts,
1250
1438
  // the Inconclusive and Pre-existing lists and the unreviewed-files list, never this part.
1251
1439
  if (input.riskMap) parts.push(renderRiskMap(input.riskMap, "### Risk map", { pushOnly: input.pushOnly }));
1252
- 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)}`;
1253
1443
  if (outsideDiff.length > 0) parts.push("### Outside the diff", ...outsideDiff.map(listed));
1254
1444
  // Each of these two is one part, so a long body can cut it by its index.
1255
1445
  const cuttable: { at: number; heading: string; items: string[] }[] = [];
@@ -1354,7 +1544,7 @@ export function buildReview(input: {
1354
1544
  export function moveCommentsToBody(review: Review): Review {
1355
1545
  if (review.comments.length === 0) return review;
1356
1546
  const moved = review.comments.map(
1357
- (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/, " ")}`,
1358
1548
  );
1359
1549
  const base = review.body.replace(
1360
1550
  /; \d+ on their lines\. Reply in a comment's thread to answer it\./,
@@ -1399,6 +1589,23 @@ function trimHead(head: string, cut: number) {
1399
1589
  return `${head.slice(0, at > 0 ? at : target)}${trimmed}`;
1400
1590
  }
1401
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
+
1402
1609
  /**
1403
1610
  * Makes the part of a review body between the first findings and the footer (`### Summary`, the
1404
1611
  * contracts block, the coverage table) at least `cut` characters shorter. The footer (`<sub>`
@@ -1413,23 +1620,30 @@ function trimMiddle(tail: string, cut: number) {
1413
1620
  const trimmed = "\n\n(Trimmed: this review is at GitHub's size limit.)";
1414
1621
  const target = middle.length - cut - trimmed.length;
1415
1622
  // The text before the first collapsed block is the Summary; each block after it starts at `<details>`.
1416
- 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);
1417
1628
  const dropOrder = [
1418
1629
  ...blocks.filter((b) => b.includes(`<summary>${CONTRACTS_SUMMARY}`)),
1419
1630
  ...blocks.filter((b) => !b.includes(`<summary>${CONTRACTS_SUMMARY}`)),
1420
1631
  ];
1421
1632
  let kept = blocks;
1422
- 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);
1423
1634
  for (const block of dropOrder) {
1424
1635
  if (size() <= target) break;
1425
1636
  kept = kept.filter((b) => b !== block);
1426
1637
  }
1427
1638
  let text = summary;
1428
1639
  if (size() > target) {
1429
- 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));
1430
1642
  text = summary.slice(0, Math.max(cutAt, 0));
1431
1643
  }
1432
- 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}`;
1433
1647
  }
1434
1648
 
1435
1649
  // ---------------------------------------------------------------------------------------------
@@ -1691,6 +1905,69 @@ export function readBaseSettings(gh: GhFn, repo: string, sha: string): RepoSetti
1691
1905
  return parseRepoSettings(file.content);
1692
1906
  }
1693
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
+
1694
1971
  /**
1695
1972
  * `config` with the model and the effort the base commit's `.wachiman.yml` sets, wherever no
1696
1973
  * explicit `WACHIMAN_MODEL` / `WACHIMAN_EFFORT` (a workflow input) did. Reads nothing when both
@@ -2259,7 +2536,8 @@ export function openBotThreads(threads: RawThread[]) {
2259
2536
  comment_id: t.comments.nodes[0].databaseId,
2260
2537
  path: t.path,
2261
2538
  line: t.line,
2262
- 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),
2263
2541
  replies: t.comments.nodes
2264
2542
  .slice(1)
2265
2543
  .filter((c) => TRUSTED.has(c.authorAssociation))
@@ -2330,17 +2608,20 @@ export function reviewMaterial(
2330
2608
  ): { review: string; threads: FindingThread[] } | null {
2331
2609
  const review = latestEngineReview(gh, repo, pr);
2332
2610
  if (review === null) return null;
2333
- const threads = fetchThreads(gh, repo, pr)
2334
- .filter(isBotFinding)
2335
- .map((t) => ({
2336
- path: t.path,
2337
- line: t.line,
2338
- resolved: t.isResolved,
2339
- finding: t.comments.nodes[0].body,
2340
- }));
2611
+ const threads = fetchThreads(gh, repo, pr).filter(isBotFinding).map(askFindingThread);
2341
2612
  return { review, threads };
2342
2613
  }
2343
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
+
2344
2625
  /** The file the ask prompt reads for the review: the body, then the threads as JSON. */
2345
2626
  export function renderReviewMaterial(material: { review: string; threads: FindingThread[] }) {
2346
2627
  return [
@@ -2361,7 +2642,7 @@ export const MAX_WACHI_REPLIES = 2;
2361
2642
  * Whether a comment is one this engine wrote as a thread reply: the bot login AND the reply
2362
2643
  * signature, since `github-actions` is shared by every workflow of the repository.
2363
2644
  */
2364
- const isWachiReply = (c: RawThread["comments"]["nodes"][number]) =>
2645
+ export const isWachiReply = (c: RawThread["comments"]["nodes"][number]) =>
2365
2646
  c.author?.login === "github-actions" && c.body.includes(SIGNATURE.reply);
2366
2647
 
2367
2648
  /**
@@ -2370,15 +2651,20 @@ const isWachiReply = (c: RawThread["comments"]["nodes"][number]) =>
2370
2651
  * fewer than `MAX_WACHI_REPLIES` replies in the thread. A thread whose latest comment is
2371
2652
  * Wachiman's, or a stranger's, or whose cap is spent, is not pending. Each entry is
2372
2653
  * `openBotThreads`' thread plus how many replies Wachiman already wrote, so the model knows
2373
- * 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.
2374
2658
  */
2375
- export function pendingThreads(threads: RawThread[]) {
2659
+ export function pendingThreads(threads: RawThread[], keyword = DEFAULT_MENTION, memoryProposals = false, operator?: string) {
2376
2660
  const open = openBotThreads(threads);
2377
2661
  const byId = new Map(threads.map((t) => [t.comments.nodes[0]?.databaseId, t]));
2378
2662
  return open.flatMap((t) => {
2379
2663
  const nodes = byId.get(t.comment_id)?.comments.nodes ?? [];
2380
2664
  const latest = nodes.length > 1 ? nodes[nodes.length - 1] : undefined;
2381
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 [];
2382
2668
  const wachiReplies = nodes.slice(1).filter(isWachiReply).length;
2383
2669
  return wachiReplies < MAX_WACHI_REPLIES ? [{ ...t, wachi_replies: wachiReplies }] : [];
2384
2670
  });
@@ -2672,7 +2958,7 @@ export function spendReserve(deps: Deps, repo: string, pr: number, headSha: stri
2672
2958
  }
2673
2959
  if (error instanceof LedgerNotPermitted) {
2674
2960
  const message =
2675
- "`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).";
2676
2962
  ledgerNote(deps, message);
2677
2963
  throw new LedgerStopped(message);
2678
2964
  }
@@ -2753,8 +3039,8 @@ async function settledOnError<T>(deps: Deps, grant: SpendGrant, run: () => Promi
2753
3039
  }
2754
3040
 
2755
3041
  /** The estimate of reviewing `files` with this configuration: the batches `planBatches` makes, priced per batch. */
2756
- export function estimateFor(files: ReviewFile[], config: EngineConfig): ReviewEstimate {
2757
- 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;
2758
3044
  return estimateReview(files, { batches, batchBudgetUsd: config.batchBudgetUsd, model: config.model });
2759
3045
  }
2760
3046
 
@@ -2764,6 +3050,38 @@ export const SIZE_GATE_MARKER = "<!-- wachi:size-gate -->";
2764
3050
  const usd2 = (n: number) => `$${n.toFixed(2)}`;
2765
3051
  const count = (n: number) => n.toLocaleString("en-US");
2766
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
+
2767
3085
  /**
2768
3086
  * The comment that says a pull request was not reviewed because its estimate is above the size
2769
3087
  * gate (nothing was sent to a model), what the estimate rests on, and the inputs that lift it.
@@ -2774,6 +3092,8 @@ export function sizeGateBody(o: {
2774
3092
  headSha: string;
2775
3093
  mention: string;
2776
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[];
2777
3097
  }): string {
2778
3098
  const { estimate: e, gate, headSha, mention, model } = o;
2779
3099
  const budget = suggestedBudget(e.usd);
@@ -2781,6 +3101,7 @@ export function sizeGateBody(o: {
2781
3101
  branded(
2782
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.`,
2783
3103
  ),
3104
+ ...(o.critical?.length ? [criticalPathsSection(o.critical)] : []),
2784
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.`,
2785
3106
  `To review the whole pull request, set the run budget in the workflow that calls Wachiman, then comment \`${mention} review\`:`,
2786
3107
  ["```yaml", " with:", ` budget_usd: ${budget}`, "```"].join("\n"),
@@ -2802,6 +3123,7 @@ export function postSizeGateNotice(
2802
3123
  headSha: string,
2803
3124
  estimate: ReviewEstimate,
2804
3125
  gate: number,
3126
+ critical: readonly CriticalPath[] = [],
2805
3127
  ) {
2806
3128
  const { config } = deps;
2807
3129
  const body = sizeGateBody({
@@ -2810,6 +3132,7 @@ export function postSizeGateNotice(
2810
3132
  headSha,
2811
3133
  mention: config.mention,
2812
3134
  model: config.model,
3135
+ critical,
2813
3136
  });
2814
3137
  if (config.dryRun) {
2815
3138
  deps.log("--- size gate comment ---\n" + body);
@@ -2870,6 +3193,24 @@ function reviewUrlOf(answer: string): string | undefined {
2870
3193
  }
2871
3194
  }
2872
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
+
2873
3214
  /** Posts the review. Returns its address when GitHub gave one (the description block links to it). */
2874
3215
  export function postReview(deps: Deps, repo: string, pr: number, headSha: string, review: Review): string | undefined {
2875
3216
  if (deps.config.dryRun) {
@@ -2926,6 +3267,139 @@ export function postReview(deps: Deps, repo: string, pr: number, headSha: string
2926
3267
  return url;
2927
3268
  }
2928
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
+
2929
3403
  /**
2930
3404
  * Runs one call so that its failure does not end the review: the batches that did run still
2931
3405
  * post. A call that died without a result is counted at its cap, since what it spent is unknown.
@@ -2973,6 +3447,25 @@ export interface ReviewOptions {
2973
3447
  * by `reviewOptionsOf`: a local review and an incremental or scoped one have no grade.
2974
3448
  */
2975
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[];
2976
3469
  }
2977
3470
 
2978
3471
  /** Today's settings as the core's options. */
@@ -3024,13 +3517,21 @@ export async function reviewChange(input: ReviewInput, options: ReviewOptions, d
3024
3517
  // The verifier's reserve is taken first, so the batches cannot spend it; at most half the total,
3025
3518
  // so a small budget still reviews something (a review with no findings has nothing to verify).
3026
3519
  const reserve = options.verify ? Math.min(options.verify.budgetUsd, totalBudget / 2) : 0;
3027
- 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;
3028
3525
  const batchBudget = options.batchBudgetUsd;
3029
- const batches = planBatches(kept, {
3030
- maxLines: options.batchLines,
3031
- // About 40k tokens at 3.5 characters a token.
3032
- maxChars: options.batchChars,
3033
- });
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
+ );
3034
3535
  // The files this run reviews whole because the previous review did not reach them.
3035
3536
  const keptNames = new Set(kept.map((f) => f.filename));
3036
3537
  const carriedHere = (input.since?.carried ?? []).filter((f) => keptNames.has(f));
@@ -3050,7 +3551,9 @@ export async function reviewChange(input: ReviewInput, options: ReviewOptions, d
3050
3551
  dropped: dropped.length,
3051
3552
  everyFile,
3052
3553
  meta: { title: change.title, body: change.description, author: change.author },
3053
- 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 } : {}),
3054
3557
  costTags: { repo: change.repository.name, ...(number ? { pr: Number(number) } : {}) },
3055
3558
  };
3056
3559
 
@@ -3333,12 +3836,18 @@ export async function reviewChange(input: ReviewInput, options: ReviewOptions, d
3333
3836
  let verification: ResultVerificationV2 | undefined;
3334
3837
  let checked: VerifiedFinding[];
3335
3838
  if (options.verify && parts.length > 0) {
3336
- const verified = await verifyFindings(core, options, context, merged.findings, kept, Math.max(totalBudget - spent, 0), refused?.text);
3839
+ const verified = await verifyFindings(core, options, context, merged.findings, kept, Math.max(totalBudget - spent - matchReserve, 0), refused?.text);
3337
3840
  spent += verified.record.costUsd;
3338
3841
  usage = addUsage(usage, verified.usage);
3339
3842
  checked = verified.findings;
3340
3843
  verification = verified.record;
3341
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;
3342
3851
  for (const path of notRun)
3343
3852
  merged.files_skipped.push({ path, reason: "not reached: the pull request's budget was spent" });
3344
3853
  // A file the model listed itself, with a reason of its own, is replaced: the run's own cause comes first.
@@ -3382,7 +3891,8 @@ export async function reviewChange(input: ReviewInput, options: ReviewOptions, d
3382
3891
  // contracts' lines are: the file must be in the review and the line must exist at the head.
3383
3892
  const lineCount = deps.lineCounter ?? repoLineCounter(input.headDir);
3384
3893
  const riskMap = buildRiskMap({
3385
- 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 } : {}) })),
3386
3896
  facts: parts.flatMap((p) => wellFormed<RiskFact>(p.output.risk_facts, RISK_KINDS)),
3387
3897
  judgement: parts.flatMap((p) => wellFormed<JudgementItem>(p.output.judgement, JUDGEMENT_KINDS)),
3388
3898
  unreadFiles: expected.filter((f) => !reviewedSet.has(f)).length,
@@ -3430,6 +3940,8 @@ export async function reviewChange(input: ReviewInput, options: ReviewOptions, d
3430
3940
  },
3431
3941
  });
3432
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;
3433
3945
  return {
3434
3946
  format: REVIEW_RESULT_V2,
3435
3947
  change,
@@ -3445,14 +3957,17 @@ export async function reviewChange(input: ReviewInput, options: ReviewOptions, d
3445
3957
  },
3446
3958
  findings,
3447
3959
  contracts: merged.contracts ?? [],
3448
- summary: merged.summary,
3960
+ summary: withMemoryNotices(merged.summary, options.memory, memoryStep.text),
3449
3961
  riskMap,
3962
+ ...(options.memory ? { memory: memoryRecord(options.memory) } : {}),
3963
+ ...(memoryStep.muted.length > 0 ? { muted: memoryStep.muted } : {}),
3450
3964
  batches: reports,
3451
3965
  threadReplies,
3452
3966
  instructionChanges: {
3453
3967
  files: changedInstructionFiles(input.files.map((f) => f.filename)),
3454
3968
  baseSha: input.instructions.baseSha,
3455
3969
  },
3970
+ ...(input.pathPolicyChanged ? { pathPolicyChanged: true as const } : {}),
3456
3971
  execution: {
3457
3972
  costUsdEstimate: spent,
3458
3973
  usage,
@@ -3466,6 +3981,7 @@ export async function reviewChange(input: ReviewInput, options: ReviewOptions, d
3466
3981
  },
3467
3982
  ...(verification ? { verification } : {}),
3468
3983
  ...(fidelity ? { fidelity } : {}),
3984
+ ...(arm ? { arm } : {}),
3469
3985
  };
3470
3986
  }
3471
3987
 
@@ -3631,6 +4147,73 @@ async function verifyFindings(
3631
4147
  }
3632
4148
  }
3633
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
+
3634
4217
  /** The GitHub connector: today's pull request facts as a `ReviewInput`. Pure; `review()` read them. */
3635
4218
  export function githubReviewInput(p: {
3636
4219
  repo: string;
@@ -3648,6 +4231,10 @@ export function githubReviewInput(p: {
3648
4231
  /** The files of `files` the previous partial review did not reach (they carry their whole diff). */
3649
4232
  carried?: string[];
3650
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;
3651
4238
  }): ReviewInput {
3652
4239
  return {
3653
4240
  format: REVIEW_INPUT_FORMAT,
@@ -3678,6 +4265,8 @@ export function githubReviewInput(p: {
3678
4265
  }
3679
4266
  : {}),
3680
4267
  ...(p.threads.length > 0 ? { conversation: p.threads } : {}),
4268
+ ...(p.pathRules?.length ? { pathRules: p.pathRules } : {}),
4269
+ ...(p.pathPolicyChanged ? { pathPolicyChanged: true as const } : {}),
3681
4270
  };
3682
4271
  }
3683
4272
 
@@ -3739,7 +4328,9 @@ export function githubReview(
3739
4328
  receiptLine: github.receiptLine,
3740
4329
  mention: github.mention,
3741
4330
  instructionChanges: github.instructionChanges,
4331
+ ...(result.pathPolicyChanged ? { pathPolicyChange: { baseSha: github.instructionChanges.baseSha } } : {}),
3742
4332
  riskMap: result.riskMap,
4333
+ ...(result.arm ? { arm: result.arm } : {}),
3743
4334
  ...(result.fidelity ? { fidelity: result.fidelity } : {}),
3744
4335
  pushOnly: github.since !== null,
3745
4336
  ...(result.verification ? { verification: result.verification } : {}),
@@ -3751,7 +4342,7 @@ export function githubReview(
3751
4342
  export async function review(deps: Deps, repo: string, pr: number, words: string[], force = false) {
3752
4343
  const { gh, config } = deps;
3753
4344
  const meta = JSON.parse(
3754
- 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"]),
3755
4346
  );
3756
4347
  const headSha: string = meta.headRefOid;
3757
4348
  const bodyOnly = (body: string) =>
@@ -3822,11 +4413,7 @@ export async function review(deps: Deps, repo: string, pr: number, words: string
3822
4413
  deps.log(why);
3823
4414
  // The marker moves so that the next push is compared with this head, not with the old one.
3824
4415
  postReview(deps, repo, pr, headSha, {
3825
- body: [
3826
- branded(`Brought up to date with the base branch, no new changes since \`${short(last)}\`.`),
3827
- SIGNATURE.review,
3828
- marker(headSha),
3829
- ].join("\n\n"),
4416
+ body: baseUpdateNotice({ base: meta.baseRefName, from: last, to: headSha, version: deps.engineVersion }, marker(headSha)),
3830
4417
  comments: [],
3831
4418
  });
3832
4419
  };
@@ -3887,11 +4474,7 @@ export async function review(deps: Deps, repo: string, pr: number, words: string
3887
4474
  );
3888
4475
  // The marker moves so that the next push is compared with this head, not with the old one.
3889
4476
  postReview(deps, repo, pr, headSha, {
3890
- body: [
3891
- branded(`Rebased onto \`${short(base)}\`, no new changes since \`${short(last)}\`.`),
3892
- SIGNATURE.review,
3893
- marker(headSha),
3894
- ].join("\n\n"),
4477
+ body: baseUpdateNotice({ base: meta.baseRefName, from: last, to: headSha, version: deps.engineVersion }, marker(headSha)),
3895
4478
  comments: [],
3896
4479
  });
3897
4480
  return;
@@ -3944,11 +4527,19 @@ export async function review(deps: Deps, repo: string, pr: number, words: string
3944
4527
  }
3945
4528
  // The size gate: what this run would send, priced before any model call. Nothing is posted as a
3946
4529
  // review and no marker is written, so the next push sees no marker and gates again.
3947
- 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);
3948
4539
  const gate = sizeGate(config, isAutomatic(config.trigger));
3949
4540
  if (estimate.usd > gate) {
3950
4541
  deps.log(`Estimated $${estimate.usd.toFixed(2)} is above the $${gate.toFixed(2)} size gate; nothing sent to a model.`);
3951
- postSizeGateNotice(deps, repo, pr, headSha, estimate, gate);
4542
+ postSizeGateNotice(deps, repo, pr, headSha, estimate, gate, criticalPathsOf(allBinary.reviewable, pathRules));
3952
4543
  return;
3953
4544
  }
3954
4545
  // After the rebase exits above (they cost nothing and move the marker) and before any paid step.
@@ -3957,12 +4548,14 @@ export async function review(deps: Deps, repo: string, pr: number, words: string
3957
4548
  // What the automatic runs before this one cost; an operator's run is not counted and shows none.
3958
4549
  const automatic = isAutomatic(config.trigger);
3959
4550
  const prior = automatic ? { spent: ceiling.spent, runs: ceiling.runs } : undefined;
3960
- const base = baseSha(gh, repo, pr);
3961
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);
3962
4555
  const batchBudget = config.batchBudgetUsd;
3963
4556
  // Only threads that wait for an answer (the owner wrote last, Wachiman has replies left): a
3964
4557
  // thread Wachiman already answered is not read again, so it is not answered twice (ADR 0008).
3965
- const threads = last ? pendingThreads(fetchThreads(gh, repo, pr)) : [];
4558
+ const threads = last ? pendingThreads(fetchThreads(gh, repo, pr), config.mention, config.memoryProposals, config.operator) : [];
3966
4559
  const input = githubReviewInput({
3967
4560
  repo,
3968
4561
  pr,
@@ -3978,6 +4571,8 @@ export async function review(deps: Deps, repo: string, pr: number, words: string
3978
4571
  commits,
3979
4572
  carried: resumed,
3980
4573
  threads,
4574
+ pathRules,
4575
+ pathPolicyChanged,
3981
4576
  });
3982
4577
  // PR Confidence grades a full review only (ADR 0033): an incremental or scoped review reads a
3983
4578
  // part of the change, and "nothing else changed" cannot be said of a part.
@@ -3988,7 +4583,11 @@ export async function review(deps: Deps, repo: string, pr: number, words: string
3988
4583
  const totalBudget = Math.min(config.budgetUsd, ceiling.room, grant.roomUsd);
3989
4584
  const options: ReviewOptions = {
3990
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),
3991
4589
  ...(config.confidence && fullReview ? { confidence: { budgetUsd: CLAIMS_BUDGET_USD } } : {}),
4590
+ ...(config.priorityTrial ? { priorityTrial: true } : {}),
3992
4591
  };
3993
4592
  const result = await settledOnError(deps, grant, () => reviewChange(input, options, deps));
3994
4593
  const { usage, costUsdEstimate: spent } = result.execution;
@@ -3997,50 +4596,46 @@ export async function review(deps: Deps, repo: string, pr: number, words: string
3997
4596
 
3998
4597
  if (result.execution.callsWithOutput === 0) {
3999
4598
  // A failed automatic run still spent money: its notice carries the cost line the ceiling sums.
4000
- const spentNotice = (text: string) =>
4001
- isAutomatic(config.trigger)
4002
- ? postReview(deps, repo, pr, headSha, {
4003
- body: [
4004
- branded(text),
4005
- ...(receiptLine ? [receiptLine] : []),
4006
- costLine({
4007
- modelLabel: result.provider.label,
4008
- effort: config.effort,
4009
- operation,
4010
- extra: prior ? [prSoFar(prior, spent)] : [],
4011
- usage,
4012
- estimate: onSubscription(deps),
4013
- costUsd: spent,
4014
- }),
4015
- SIGNATURE.auto,
4016
- SIGNATURE.review,
4017
- ].join("\n\n"),
4018
- comments: [],
4019
- })
4020
- : // A manual run keeps its receipt and forced/bypass lines, but not `SIGNATURE.auto`: the ceiling does not count it.
4021
- receiptLine
4022
- ? postReview(deps, repo, pr, headSha, { body: [branded(text), receiptLine].join("\n\n"), comments: [] })
4023
- : 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)]);
4024
4622
  const { rejection, stop } = result.execution;
4025
4623
  const refused = rejection && rejection.kind !== "other" ? { kind: rejection.kind, text: rejection.text } : undefined;
4026
4624
  if (refused) {
4027
- // On a subscription token the key is not the credential: say what fits it, and that nothing falls back to a key.
4028
- const headline = (
4029
- deps.provider.auth === "oauth-token"
4030
- ? {
4031
- 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.",
4032
- 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.",
4033
- rate_limit: "**Not reviewed: Claude kept rate-limiting the reviewer.** Re-run later.",
4034
- }
4035
- : {
4036
- billing: "**Not reviewed: the reviewer's Anthropic account has no credit.** Top up, then re-run this job.",
4037
- auth: "**Not reviewed: the reviewer's API key was rejected.** Check the `ANTHROPIC_API_KEY` secret, then re-run.",
4038
- rate_limit: "**Not reviewed: the Anthropic API kept rate-limiting the reviewer.** Re-run later.",
4039
- }
4040
- )[refused.kind];
4041
4625
  // `oneLine` neutralises the text and cuts it at 300 characters.
4042
4626
  const detail = oneLine(refused.text, 300);
4043
- 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);
4044
4639
  if (config.onProviderUnavailable === "fail") {
4045
4640
  throw new Error(`Not reviewed: the provider rejected the call (${refused.kind}): ${detail || "no error text"}`);
4046
4641
  }
@@ -4128,6 +4723,8 @@ export interface ThreadReply {
4128
4723
  comment_id: number;
4129
4724
  status: "addressed" | "still_open";
4130
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;
4131
4728
  /** `path:line` or `path:from-to` the reply rests on; every one is checked against the head. */
4132
4729
  cites: string[];
4133
4730
  }
@@ -4155,6 +4752,41 @@ export const THREAD_SCHEMA = {
4155
4752
  },
4156
4753
  };
4157
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
+
4158
4790
  /** Lines on each side of a thread's line that the thread file shows as the current code. */
4159
4791
  const EXCERPT_RADIUS = 12;
4160
4792
  const EXCERPT_MAX_CHARS = 4000;
@@ -4177,8 +4809,27 @@ export function codeAround(repoDir: string, path: string, line: number | null) {
4177
4809
  }
4178
4810
  }
4179
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
+
4180
4831
  /** The prompt of a thread-only run. The threads, their replies and the code are in `threads.json`. */
4181
- 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) {
4182
4833
  return `You are answering replies in review threads that Wachiman opened on pull request #${ctx.pr} in ${ctx.repo}.
4183
4834
  The repository is checked out at its head commit ${ctx.headSha}. No file is being reviewed in this run:
4184
4835
  do not report new findings, only answer the threads.
@@ -4206,7 +4857,7 @@ root. The engine checks each one against the head and drops a reply whose cite d
4206
4857
  You only read code: write "read", never "tested" or "verified by running". You cannot resolve a
4207
4858
  thread and must not offer to. Keep each reply to a few sentences, in English. When wachi_replies is
4208
4859
  1, this is your last reply in the thread: end it with what you are waiting for from the owner.
4209
- 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 : ""}`;
4210
4861
  }
4211
4862
 
4212
4863
  /**
@@ -4238,7 +4889,7 @@ export async function threadReplies(deps: Deps, repo: string, pr: number, author
4238
4889
  );
4239
4890
  return;
4240
4891
  }
4241
- const pending = pendingThreads(fetchThreads(gh, repo, pr));
4892
+ const pending = pendingThreads(fetchThreads(gh, repo, pr), config.mention, config.memoryProposals, config.operator);
4242
4893
  if (pending.length === 0) {
4243
4894
  deps.log("No Wachiman thread waits for an answer.");
4244
4895
  return;
@@ -4267,10 +4918,10 @@ export async function threadReplies(deps: Deps, repo: string, pr: number, author
4267
4918
  config,
4268
4919
  repoDir,
4269
4920
  { operation: "reply", label: "threads", repo, pr },
4270
- buildThreadsPrompt({ pr, repo, headSha }, dir),
4921
+ buildThreadsPrompt({ pr, repo, headSha }, dir, config.memoryProposals),
4271
4922
  dir,
4272
4923
  budgetUsd,
4273
- THREAD_SCHEMA,
4924
+ config.memoryProposals ? THREAD_SCHEMA_WITH_MEMORY : THREAD_SCHEMA,
4274
4925
  ),
4275
4926
  );
4276
4927
  const receiptLine = spendSettle(deps, grant, call.costUsd);
@@ -4297,12 +4948,52 @@ export async function threadReplies(deps: Deps, repo: string, pr: number, author
4297
4948
  }
4298
4949
  replies.push({ reply: r, cites });
4299
4950
  }
4300
- 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)]);
4301
4992
 
4302
4993
  // ADR 0008: recheck the head and each thread before posting. A push since the start means its
4303
4994
  // review answers; a thread someone answered meanwhile is not answered twice.
4304
4995
  const stillPending = new Set<number>();
4305
- 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);
4306
4997
  const toPost = replies.filter((r) => stillPending.has(r.reply.comment_id));
4307
4998
  if (toPost.length < replies.length)
4308
4999
  deps.log(`${replies.length - toPost.length} reply(ies) not posted: the head moved or the thread changed meanwhile.`);
@@ -4319,7 +5010,10 @@ export async function threadReplies(deps: Deps, repo: string, pr: number, author
4319
5010
  i === 0
4320
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}`
4321
5012
  : `\n\n<sub>this run $${call.costUsd.toFixed(2)} ยท ${prSoFar(prior, call.costUsd)}${estimateTail(onSubscription(deps))}</sub>`;
4322
- 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}`;
4323
5017
  if (config.dryRun) {
4324
5018
  deps.log(`--- reply to ${reply.comment_id}: ${label} ---\n${body}`);
4325
5019
  return;
@@ -4347,6 +5041,8 @@ export interface ReviewContext {
4347
5041
  meta: { title?: string; body?: string; author?: string };
4348
5042
  /** `renderInstructions` of the base commit's rules. */
4349
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[];
4350
5046
  /** PR Confidence on: the claims the batches assign their files to, as the claims call listed them. */
4351
5047
  claims?: readonly string[];
4352
5048
  /** How the cost log line names the change; absent for a change with no repository or number. */
@@ -4394,7 +5090,11 @@ export function buildBatchPrompt(
4394
5090
  ) {
4395
5091
  const carried = new Set(ctx.carried ?? []);
4396
5092
  const list = files
4397
- .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
+ })
4398
5098
  .join("\n");
4399
5099
  const sinceScope = ctx.since
4400
5100
  ? ctx.rebased
@@ -4869,8 +5569,18 @@ export function askLedger(gh: GhFn, repo: string, pr: number) {
4869
5569
  function threadBefore(gh: GhFn, repo: string, pr: number, line: ReviewLineComment): string | undefined {
4870
5570
  const root = threadRoot(line);
4871
5571
  const thread = fetchThreads(gh, repo, pr).find((t) => t.comments.nodes[0]?.databaseId === root);
4872
- const earlier = (thread?.comments.nodes ?? []).filter((n) => n.databaseId < line.id).slice(-10);
4873
- 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");
4874
5584
  if (text === "") return undefined;
4875
5585
  return text.length > 4000 ? `โ€ฆ${text.slice(-4000)}` : text;
4876
5586
  }
@@ -5037,11 +5747,22 @@ export async function comment(deps: Deps, repo: string, pr: number, request: str
5037
5747
  // that login command the tool.
5038
5748
  const problem = operatorProblem(operator);
5039
5749
  if (problem) throw new Error(problem);
5040
- const command = parseCommand(request, deps.config.mention);
5750
+ const parsed = parseCommand(request, deps.config.mention);
5041
5751
  // Without an author, the caller is the operator (manual CLI use, as before), unless collaborators
5042
5752
  // may ask: then nobody is trusted without a login. A dry run posts nothing, so it keeps the manual path.
5043
5753
  const operatorAsked =
5044
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
+ }
5045
5766
  if (operatorAsked) {
5046
5767
  if (command?.kind === "review") {
5047
5768
  // With no ledger `--force` means nothing: it stays a word that names no file, as it always did.