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/README.md CHANGED
@@ -22,6 +22,7 @@ warns you and lets you decide; the Spanish word comes from the English one.
22
22
  - [What it will not do](#what-it-will-not-do)
23
23
  - [The trust decision, in brief](#the-trust-decision-in-brief)
24
24
  - [Providers and platforms](#providers-and-platforms)
25
+ - [Contributing](#contributing)
25
26
  - [License](#license)
26
27
  - [Commit messages](#commit-messages)
27
28
 
@@ -91,12 +92,17 @@ maintained workflow.
91
92
 
92
93
  ## Documentation
93
94
 
95
+ [Engineering principles](docs/principles/README.md) explain the ideas behind the reviewer,
96
+ their external sources, the evidence expected of changes, and the boundary between current
97
+ behavior and proposed review memory.
98
+
94
99
  The guides are published at **[wachiman.dev/docs](https://wachiman.dev/docs/what-it-is/)**. The
95
100
  same material, in this repository:
96
101
 
97
102
  | I want to… | Read |
98
103
  | --- | --- |
99
104
  | Get a first review on a repository | [docs/install.md](docs/install.md) |
105
+ | Have my coding agent install, configure, upgrade or remove Wachiman from chat | [docs/agents.md](docs/agents.md) |
100
106
  | Know what I am trusting, and what is unverified | [SECURITY.md](SECURITY.md) |
101
107
  | Look up an input, a default or an environment setting | [docs/configuration.md](docs/configuration.md) |
102
108
  | Find out why there was no review, or an error | [docs/troubleshooting.md](docs/troubleshooting.md) |
@@ -200,6 +206,12 @@ read with a notice; see [docs/upgrading.md](docs/upgrading.md).
200
206
  - **Platforms:** macOS and Linux are covered by CI. Windows (Git Bash, PowerShell) is not tested
201
207
  in CI and is expected to work wherever Node and Bun run.
202
208
 
209
+ ## Contributing
210
+
211
+ The code is public, but pull requests from outside the team are not accepted for now. Report
212
+ bugs and questions in [GitHub Issues](https://github.com/niway-dev/wachiman/issues); see
213
+ [CONTRIBUTING.md](CONTRIBUTING.md).
214
+
203
215
  ## License
204
216
 
205
217
  Wachiman is **source available**, not open source. It is licensed under the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "wachiman",
3
- "version": "1.16.0",
3
+ "version": "1.17.0",
4
4
  "description": "Advisory pull request reviews by an agent CLI, run in your own GitHub Actions with your own key, or locally on your own Claude subscription",
5
5
  "private": false,
6
6
  "type": "module",
@@ -78,6 +78,47 @@ Tell the developer, in this order:
78
78
  changing, not proved.
79
79
  4. The `notes[]`, one line each, as optional.
80
80
 
81
+ ## Ask the owner, and memory
82
+
83
+ Fix the mechanical findings like any other. Two cases need the owner.
84
+
85
+ **A finding whose fix depends on intent.** If the right fix depends on what the owner wants (which
86
+ behaviour is intended, which value is correct), do not guess. Fix the rest, commit, call the loop
87
+ again, then ask the owner in one message: the finding (`id`, `path`, `line`), what you would do,
88
+ and why you are asking. Leave it open until they answer.
89
+
90
+ **Repository memory.** Memory holds rules that a later review should apply, or should stop
91
+ reporting. Change it only with the owner's yes. Start this when `wachiman loop --format json`
92
+ lists `memoryCandidates`, or when the owner says a finding should not come back:
93
+
94
+ 1. Draft the entry yourself, from the code and what the owner meant. Do not copy the owner's
95
+ words as the rule.
96
+ 2. Record it. `memory add` prints the id:
97
+
98
+ ```sh
99
+ wachiman memory add --kind convention|exception --scope "<glob>" --rule "<what to do, or what not to report>" --why "<the reason, in your words>" --agent --repo-dir <clone>
100
+ ```
101
+
102
+ The default `--source instruction` records the owner's instruction. For a finding of the loop,
103
+ `--finding <id> --source judged` (a `wrong` verdict with a reason) or `--source fixed` (a
104
+ convention the loop marked probably fixed) ties the entry to the loop's history instead.
105
+ 3. Check whether it can be proposed: `wachiman memory candidates --repo-dir <clone>` prints
106
+ `proposable` or `not proposable: <reason>` (for example, not enough evidence yet). If it is not
107
+ proposable, do not ask for approval: tell the owner in one sentence that the candidate is
108
+ recorded on this laptop and why it cannot be proposed yet, and stop.
109
+ 4. If it is proposable, show the owner the exact text: `wachiman memory show <id> --repo-dir <clone>`.
110
+ Ask whether to propose it, and say why. Do not paraphrase the text you show.
111
+ 5. Only on a yes, run `wachiman memory propose <id> --repo-dir <clone>`. It opens a draft pull
112
+ request for a person to merge. On a no, stop; the candidate stays on this laptop.
113
+
114
+ Never propose without the owner's yes.
115
+
116
+ **What belongs in memory.** Belongs: how code is written here (readable before terse), what a test
117
+ must have, how documents and ADRs are kept, behaviour that is intentional and looks like a bug.
118
+ Does not belong: the details of one feature, a one-time exception, the temporary state of a
119
+ migration, anything a formatter or linter can enforce, anything already in a hand-written
120
+ instruction file. If an entry is in doubt, do not add it; tell the owner instead.
121
+
81
122
  ## Never
82
123
 
83
124
  | Tempting | Instead |
@@ -89,3 +130,5 @@ Tell the developer, in this order:
89
130
  | Running with `ANTHROPIC_API_KEY` set | `env -u ANTHROPIC_API_KEY wachiman loop ...`; the subscription pays |
90
131
  | Editing files under `~/.wachiman` to reset or close a loop | `--base <ref>` starts a new loop |
91
132
  | Claiming the branch is approved or safe | Report the outcome and its limits |
133
+ | Copying the owner's reply into a memory rule | Draft the rule, show `memory show <id>`, and ask |
134
+ | Running `memory propose` without the owner's yes | Ask first; it opens a pull request |
package/src/cli.ts CHANGED
@@ -25,6 +25,7 @@
25
25
  * wachiman doctor explain what a local run would use and what would fail
26
26
  * wachiman profile … list, create, add, login, remove and default account profiles
27
27
  * wachiman project show|unbind inspect or remove this repository's binding
28
+ * wachiman memory check|archive|candidates|add|show|propose repository memory in .wachiman/memory (src/memory/)
28
29
  * wachiman upgrade [--check] update the CLI, then the workflow pin in this repository (src/upgrade/)
29
30
  * wachiman skills install|uninstall copy the agent skills into place, or remove what was copied
30
31
  * wachiman pr-template show|install|status|check|format|risk|strip the PR description template: install it,
@@ -54,9 +55,9 @@ import { parseProfileArgs, parseProjectArgs, runProfile, runProject } from "./ac
54
55
  import { wachimanHome } from "./accounts/config";
55
56
  import { parseSkillsArgs, runSkills } from "./skills/install";
56
57
  import { runPrTemplate } from "./pr-template/run";
58
+ import { runMemory } from "./memory/command";
57
59
  import { parseUpgradeArgs, runUpgrade } from "./upgrade/command";
58
60
  import { parseDoctorArgs, runDoctor } from "./doctor/run";
59
- import { parseInitFlags } from "./init/args";
60
61
  import { ghLogin } from "./init/github-login";
61
62
  import { DEFAULT_WORKFLOW_REF } from "./init/options";
62
63
  import { projectCommands } from "./wizard/command";
@@ -64,7 +65,8 @@ import { DEFAULT_ISOLATED_NAME, setupProfile } from "./profiles";
64
65
  import { resetConfidence } from "./fidelity/sink";
65
66
  import { getProvider, PROVIDER_NAMES, UnknownProviderError } from "./providers";
66
67
  import { parseSetupFlags } from "./setup/args";
67
- import { runInitCommand } from "./init/run";
68
+ import { failureDocument, printDocument } from "./init/json";
69
+ import { runInitFromArgv } from "./init/run";
68
70
  import { runSetupCommand } from "./setup/run";
69
71
  import { commandHelp, helpFor, isCommand, rootHelp } from "./help";
70
72
  import { shouldLaunch } from "./wizard/interactive";
@@ -109,6 +111,27 @@ export function extractRepoDir(argv: string[]) {
109
111
  return { repoDir, rest };
110
112
  }
111
113
 
114
+ /** The `--repo-dir` the caller typed, resolved to an absolute path; the working directory when there is none. Never throws: it only reads the arguments. */
115
+ export function requestedRepoDir(argv: string[]): string {
116
+ let value: string | undefined;
117
+ for (let i = 0; i < argv.length; i++) {
118
+ if (argv[i] === "--repo-dir") value = argv[++i];
119
+ else if (argv[i].startsWith("--repo-dir=")) value = argv[i].slice("--repo-dir=".length);
120
+ }
121
+ return resolve(value || ".");
122
+ }
123
+
124
+ /** Whether a question can be asked: Bun's `prompt` reads stdin and writes to stdout, and the question itself goes to stderr, so all three must be terminals. */
125
+ export function canAskOnTerminal(stdin: { isTTY?: boolean }, stdout: { isTTY?: boolean }, stderr: { isTTY?: boolean }): boolean {
126
+ return stdin.isTTY === true && stdout.isTTY === true && stderr.isTTY === true;
127
+ }
128
+
129
+ /** Asks one question on the terminal and returns the typed answer (Bun's synchronous `prompt`); only used when `canAskOnTerminal`. */
130
+ function askOnTerminal(question: string): string | undefined {
131
+ console.error(question);
132
+ return prompt("Your choice (1 or 2):") ?? undefined;
133
+ }
134
+
112
135
  /**
113
136
  * Writes all of `text` to a file descriptor before returning. `process.stdout.write` is
114
137
  * asynchronous on a pipe, and `process.exit` right after it cuts a long report short.
@@ -199,9 +222,8 @@ async function runWizard(mode: "setup" | "init", args: string[], repoDir: string
199
222
  if (flags.help) return (io.stdout(commandHelp(["setup"])!), 0);
200
223
  return runSetupCommand(flags, env, io, { doctor: { version } });
201
224
  }
202
- const flags = parseInitFlags(args, repoDir);
203
- if (flags.help) return (io.stdout(commandHelp(["init"])!), 0);
204
- return runInitCommand(flags, env, io, {
225
+ if (args.includes("--help") || args.includes("-h")) return (io.stdout(commandHelp(["init"])!), 0);
226
+ return runInitFromArgv(args, repoDir, env, io, {
205
227
  version,
206
228
  defaultWorkflowRef: DEFAULT_WORKFLOW_REF,
207
229
  githubLogin: ghLogin,
@@ -225,7 +247,7 @@ export function runResetConfidence(args: string[], env: Record<string, string |
225
247
  if (!/^\d+$/.test(prArg ?? "") || pr <= 0) throw new UsageError("reset-confidence needs a pull request number.");
226
248
  let commit: string | undefined;
227
249
  for (let i = 0; i < flags.length; i++) {
228
- if (flags[i] !== "--commit" || !flags[i + 1]) throw new UsageError(`reset-confidence: unexpected "${flags[i]}".`);
250
+ if (flags[i] !== "--commit" || !flags[i + 1]) throw new UsageError(`reset-confidence: unexpected "${flags[i]}". Accepted form: --commit <sha>.`);
229
251
  commit = flags[++i];
230
252
  }
231
253
  const config = loadConfig(env);
@@ -358,6 +380,10 @@ export async function main(argv: string[], env: Record<string, string | undefine
358
380
  // No model, no provider; `check --pr` and `risk` shell out to gh and git in the repository directory.
359
381
  return runPrTemplate(args.slice(1), repoDir, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) });
360
382
  }
383
+ if (mode === "memory") {
384
+ // No model, no provider. `check`, `candidates`, `add` and `show` read files and git; `propose` also pushes with the developer's git credentials and calls `gh`.
385
+ return runMemory(args.slice(1), repoDir, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) }, { env, ...(canAskOnTerminal(process.stdin, process.stdout, process.stderr) ? { ask: askOnTerminal } : {}) });
386
+ }
361
387
  if (mode === "doctor" || mode === "profile" || mode === "project") {
362
388
  return runAccountCommand(mode, args.slice(1), repoDir, env);
363
389
  }
@@ -458,6 +484,11 @@ export async function main(argv: string[], env: Record<string, string | undefine
458
484
  return 0;
459
485
  } catch (error) {
460
486
  if (error instanceof UsageError || error instanceof UnknownProviderError) {
487
+ // `init --json` promises one document on stdout even when the arguments fail before init runs (a bad --repo-dir).
488
+ if (mode === "init" && argv.includes("--json")) {
489
+ printDocument((text) => writeAll(1, text), failureDocument({ mode: null, dryRun: argv.includes("--dry-run"), repoDir: requestedRepoDir(argv), report: {}, code: "usage", message: error.message }));
490
+ return 2;
491
+ }
461
492
  return usageError(error.message, mode);
462
493
  }
463
494
  if (error instanceof SpendLimitReached) {
package/src/config.ts CHANGED
@@ -132,6 +132,19 @@ export interface EngineConfig {
132
132
  * the pull request review only: `wachiman local` never grades.
133
133
  */
134
134
  confidence: boolean;
135
+ /**
136
+ * `WACHIMAN_PRIORITY_TRIAL`: the A/B of the finding priority (ADR 0059 decision 10). Each pull
137
+ * request review gets the old Important/Nit word or the priority row, by a hash of the repository
138
+ * and the pull request number, and the result records `arm`. On only with the exact value `1`;
139
+ * off, every review shows the priority and records no arm. Local reviews never join the trial.
140
+ */
141
+ priorityTrial: boolean;
142
+ /**
143
+ * `WACHIMAN_MEMORY_PROPOSALS`: a thread reply may propose an entry for repository memory from the
144
+ * operator's instruction (layer 5); the operator approves it with `/wachiman remember <id>`. Off by
145
+ * default; enabled only by `1` or `true`. Read by the thread-only run.
146
+ */
147
+ memoryProposals: boolean;
135
148
  }
136
149
 
137
150
  /** The verifier's model when `WACHIMAN_VERIFIER_MODEL` is unset (Claude Code only). */
@@ -213,6 +226,10 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
213
226
  if (verify && verifierModel === undefined) {
214
227
  throw new UsageError(`WACHIMAN_VERIFY needs WACHIMAN_VERIFIER_MODEL with the ${provider} provider: the default verifier is a Claude model.`);
215
228
  }
229
+ const memoryProposalsRaw = get("MEMORY_PROPOSALS");
230
+ if (memoryProposalsRaw !== undefined && !["0", "1", "true", "false"].includes(memoryProposalsRaw)) {
231
+ throw new UsageError(`WACHIMAN_MEMORY_PROPOSALS must be 1, true, 0 or false (unset means off), got "${memoryProposalsRaw}".`);
232
+ }
216
233
  const confidenceRaw = get("CONFIDENCE");
217
234
  if (confidenceRaw !== undefined && !["0", "1", "true", "false"].includes(confidenceRaw)) {
218
235
  throw new UsageError(`WACHIMAN_CONFIDENCE must be 1, true, 0 or false (unset means off), got "${confidenceRaw}".`);
@@ -241,12 +258,12 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
241
258
  `WACHIMAN_LEDGER_URL must start with https:// (http://localhost and http://127.0.0.1 are allowed for tests), got "${ledgerUrl}".`,
242
259
  );
243
260
  }
244
- // With a ledger, `review-platform.yml` grants `id-token: write`, so the request token is in the
261
+ // With a ledger, `wachiman-platform.yml` grants `id-token: write`, so the request token is in the
245
262
  // engine's environment; a Codex sandbox could read it from /proc and mint tokens as this job.
246
263
  // Without `ledger_url` nothing uses the token and the guard does not apply.
247
264
  if (ledgerUrl !== undefined && provider !== "claude-code" && env.ACTIONS_ID_TOKEN_REQUEST_TOKEN !== undefined) {
248
265
  throw new UsageError(
249
- `WACHIMAN_PROVIDER ${provider} cannot run in a job that holds an OIDC request token: its sandbox can read it from the engine's environment. Use claude-code, or call review.yml instead of review-platform.yml.`,
266
+ `WACHIMAN_PROVIDER ${provider} cannot run in a job that holds an OIDC request token: its sandbox can read it from the engine's environment. Use claude-code, or call review.yml instead of wachiman-platform.yml.`,
250
267
  );
251
268
  }
252
269
  return {
@@ -279,6 +296,8 @@ export function loadConfig(env: Env, warn: (line: string) => void = console.erro
279
296
  verifyBudgetUsd: number("VERIFY_BUDGET_USD", 1),
280
297
  verifierModel: verifierModel ?? DEFAULT_VERIFIER_MODEL,
281
298
  confidence: confidenceRaw === "1" || confidenceRaw === "true",
299
+ priorityTrial: get("PRIORITY_TRIAL") === "1",
300
+ memoryProposals: memoryProposalsRaw === "1" || memoryProposalsRaw === "true",
282
301
  ledgerUrl,
283
302
  dailyBudgetUsd: get("DAILY_BUDGET_USD") === undefined ? undefined : number("DAILY_BUDGET_USD", 0),
284
303
  weeklyBudgetUsd: get("WEEKLY_BUDGET_USD") === undefined ? undefined : number("WEEKLY_BUDGET_USD", 0),
@@ -25,7 +25,8 @@ import {
25
25
  type ReviewInput,
26
26
  } from "../engine";
27
27
  import { GIT_BASE_ARGS, gitEnv, spawnGit, type GitRunner } from "../evidence";
28
- import { parseRepoSettings, SETTINGS_PATH, type RepoSettings } from "../repo-settings";
28
+ import { ignoredSettingsNote, parseRepoSettings, pathsEdited, SETTINGS_PATH, touchesSettingsFile, withPolicyEditRule, type PathRule, type RepoSettings } from "../repo-settings";
29
+ import { MEMORY_DIR, cutMemoryNote, loadMemory, type MemoryLoad, type MemorySource } from "../memory/load";
29
30
 
30
31
  const TIMEOUT_MS = 60_000;
31
32
  /** The whole branch diff is one output; a large branch can be far over the evidence step's 8 MB. */
@@ -400,6 +401,79 @@ export function localRepoSettings(repoDir: string, sha: string, git: GitRunner =
400
401
  return parseRepoSettings(bytes.toString("utf8"));
401
402
  }
402
403
 
404
+ /**
405
+ * The `paths` rules of the `.wachiman.yml` at `sha` (ADR 0058), or undefined when it has none. Read
406
+ * at the commit the instruction files are read at, never at the head. A broken file is ignored with
407
+ * one warning naming `where`, like the model and effort read: the change that fixes it must be
408
+ * reviewable.
409
+ */
410
+ export function localPathRules(repoDir: string, sha: string, where: string, warn: (line: string) => void, git: GitRunner = spawnGit): PathRule[] | undefined {
411
+ try {
412
+ return localRepoSettings(repoDir, sha, git)?.paths;
413
+ } catch (error) {
414
+ if (!(error instanceof UsageError)) throw error;
415
+ warn(ignoredSettingsNote(error.message, `${where} ${short(sha)}`));
416
+ return undefined;
417
+ }
418
+ }
419
+
420
+ /**
421
+ * The path rules a local review applies and whether the change edits them (ADR 0058 decision 5).
422
+ * `readHead` returns the head's `.wachiman.yml` bytes, or null when the head has none: the head
423
+ * commit's blob, or the snapshot's file for a working-tree review. They are compared with the
424
+ * base's (`baseRules`) only to tell the reader; the head's rules are never applied. When the change
425
+ * edits them, `.wachiman.yml` is added to the rules as a critical path for this review.
426
+ */
427
+ export function localPathPolicy(
428
+ readHead: () => Buffer | null,
429
+ files: readonly ReviewFile[],
430
+ baseRules: PathRule[] | undefined,
431
+ ): { pathRules: PathRule[] | undefined; pathPolicyChanged: boolean } {
432
+ if (!touchesSettingsFile(files)) return { pathRules: baseRules, pathPolicyChanged: false };
433
+ const bytes = readHead();
434
+ const edited = bytes ? bytes.length > MAX_INSTRUCTION_BYTES || pathsEdited(baseRules, bytes.toString("utf8")) : pathsEdited(baseRules, null);
435
+ return edited ? { pathRules: withPolicyEditRule(baseRules), pathPolicyChanged: true } : { pathRules: baseRules, pathPolicyChanged: false };
436
+ }
437
+
438
+ /**
439
+ * The memory folder and `.wachiman.yml` at `sha`, read from git's object store: the merge-base for a
440
+ * branch, never the head, so a branch cannot change the memory it is reviewed under (ADR 0056).
441
+ * A `sha` that is not in this clone (an `--input` file can name one) has no memory.
442
+ */
443
+ export function localMemorySource(repoDir: string, sha: string, git: GitRunner = spawnGit, warn: (line: string) => void = () => {}): MemorySource {
444
+ return {
445
+ list: () => {
446
+ const out = git(["ls-tree", "-z", sha, "--", `${MEMORY_DIR}/`], { cwd: repoDir, timeoutMs: TIMEOUT_MS });
447
+ if (out.status !== 0) return [];
448
+ return out.stdout
449
+ .split("\0")
450
+ .filter(Boolean)
451
+ .flatMap((line) => {
452
+ const [meta, path] = line.split("\t");
453
+ const [mode, type] = meta.split(" ");
454
+ return type === "blob" && (mode === "100644" || mode === "100755") && path.startsWith(`${MEMORY_DIR}/`) ? [path.slice(MEMORY_DIR.length + 1)] : [];
455
+ });
456
+ },
457
+ read: (name) => {
458
+ const bytes = blobAt(repoDir, sha, `${MEMORY_DIR}/${name}`, git);
459
+ if (!bytes) return null;
460
+ const file = instructionFileOf(name, bytes);
461
+ if (file.truncated) warn(cutMemoryNote(name, MAX_INSTRUCTION_BYTES / 1024));
462
+ return file.content;
463
+ },
464
+ settings: () => localRepoSettings(repoDir, sha, git),
465
+ };
466
+ }
467
+
468
+ /**
469
+ * The memory a local review of `changedPaths` loads at `sha`; undefined without a memory folder.
470
+ * `personal` is the developer's own folder for this repository (`personalSourceFor`): only a laptop
471
+ * review passes it, so a review in Actions never has it.
472
+ */
473
+ export function localMemory(repoDir: string, sha: string, changedPaths: string[], warn: (line: string) => void, git: GitRunner = spawnGit, personal?: MemorySource): MemoryLoad | undefined {
474
+ return loadMemory(localMemorySource(repoDir, sha, git, warn), sha, changedPaths, warn, personal);
475
+ }
476
+
403
477
  const names = (out: string) => out.split("\0").filter(Boolean);
404
478
 
405
479
  /**
@@ -591,6 +665,11 @@ export function buildLocalInput(p: {
591
665
  );
592
666
  if (ignored.length > 0) p.log(`Not paths in this change, ignored: ${ignored.join(" ")}`);
593
667
  const instructions = localInstructions(p.repoDir, refs.mergeBase, p.warn, git);
668
+ const { pathRules, pathPolicyChanged } = localPathPolicy(
669
+ () => blobAt(p.repoDir, refs.headSha, SETTINGS_PATH, git),
670
+ files,
671
+ localPathRules(p.repoDir, refs.mergeBase, "the merge-base", p.warn, git),
672
+ );
594
673
  const top = run(git, p.repoDir, ["rev-parse", "--show-toplevel"]).trim();
595
674
  const name = basename(top);
596
675
  const subjects = run(git, p.repoDir, ["log", "--reverse", "--format=%s", ...subjectRange(refs)]).trim();
@@ -613,6 +692,8 @@ export function buildLocalInput(p: {
613
692
  instructions,
614
693
  headDir: snapshot.dir,
615
694
  scope: paths,
695
+ ...(pathRules?.length ? { pathRules } : {}),
696
+ ...(pathPolicyChanged ? { pathPolicyChanged: true as const } : {}),
616
697
  };
617
698
  return { input, snapshotDir: snapshot.dir, refs };
618
699
  }
@@ -11,6 +11,7 @@ import {
11
11
  readFileSync,
12
12
  readlinkSync,
13
13
  realpathSync,
14
+ statSync,
14
15
  rmSync,
15
16
  writeFileSync,
16
17
  } from "node:fs";
@@ -21,10 +22,20 @@ import { UsageError } from "../config";
21
22
  import { GIT_BASE_ARGS, gitEnv, spawnGit, type GitRunner } from "../evidence";
22
23
  import { REVIEW_INPUT_V2, type ReviewInput } from "../formats";
23
24
  import { resolveScope } from "../engine";
24
- import { localFiles, localInstructions } from "./local-git";
25
+ import { SETTINGS_PATH } from "../repo-settings";
26
+ import { localFiles, localInstructions, localPathPolicy, localPathRules } from "./local-git";
25
27
 
26
28
  type Spawn = typeof spawnSync;
27
29
  const hash = (bytes: Buffer) => createHash("sha256").update(bytes).digest("hex");
30
+ /** A snapshot file's bytes, or null when the path is absent or not a regular file (a directory is absent, as in a commit). */
31
+ export function readSnapshotFile(file: string): Buffer | null {
32
+ try {
33
+ return statSync(file).isFile() ? readFileSync(file) : null;
34
+ } catch {
35
+ return null;
36
+ }
37
+ }
38
+
28
39
  const identity = (s: ReturnType<typeof lstatSync>) => [s.dev, s.ino, s.mode, s.size, s.mtimeMs, s.ctimeMs].join(":");
29
40
  const failure = () => new UsageError("The index, HEAD or tracked files changed during capture; retry --working-tree.");
30
41
  /** Index the materialized bytes directly; git add would apply repository attributes. */
@@ -264,6 +275,15 @@ export function workingTreeInput(p: {
264
275
  // Evidence uses git grep in its own index; symlink entries remain textual blobs there too.
265
276
  indexRawSnapshot(snapshot, treeEntries, (a, input) => exec(["-C", snapshot, ...a], input));
266
277
  const name = basename(top);
278
+ const { pathRules, pathPolicyChanged } = localPathPolicy(
279
+ () => {
280
+ // The snapshot holds the working tree's blobs as plain files, so a link is its target text.
281
+ const file = join(snapshot, SETTINGS_PATH);
282
+ return readSnapshotFile(file);
283
+ },
284
+ files,
285
+ localPathRules(top, base, "HEAD", p.warn, git),
286
+ );
267
287
  const input: ReviewInput = {
268
288
  format: REVIEW_INPUT_V2,
269
289
  change: {
@@ -278,6 +298,8 @@ export function workingTreeInput(p: {
278
298
  instructions: localInstructions(top, base, p.warn, git),
279
299
  headDir: snapshot,
280
300
  scope: paths,
301
+ ...(pathRules?.length ? { pathRules } : {}),
302
+ ...(pathPolicyChanged ? { pathPolicyChanged: true as const } : {}),
281
303
  };
282
304
  return { input, release };
283
305
  } catch (e) {