@bluewombat/slots 0.10.0 → 0.11.0

package/README.md

@@ -57,8 +57,7 @@ these all use it. How Host wires a slot into a run:
 | ------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `agents/cursor.mjs`             | Agent     | Runs Cursor CLI with a filled prompt                                                                                                                                                                                                                  |
 | `agents/claude.mjs`             | Agent     | Runs Claude Code with a filled prompt                                                                                                                                                                                                                 |
-| `builders/tests.mjs`            | Builder   | The tests of the task, written before its code: one test per case of its "Tests" section (or per criterion when it has none), stubs for a missing interface, each test proved passable by a throwaway implementation in the stubs, then left failing. |
-| `builders/e2e.mjs`              | Builder   | The Ticket that holds a Feature's e2e acceptance suite: one test per scenario of the task, named after its id, and the manifest `e2e/scenarios.json`; nothing outside the suite folder, the suite never run. One command for the first pass and a refused one |
+| `builders/feature-test.mjs`     | Builder   | The Ticket that holds a Feature's tests: one test per scenario of the task, named after its id, existing tests updated when a scenario changes them, and the manifest `feature-tests/scenarios.json`; tests never run. One command for the first pass and a refused one |
 | `builders/producer.mjs`         | Builder   | First pass of the unit of work: fill `{{task}}`, then spawn the agent                                                                                                                                                                                 |
 | `builders/repair.mjs`           | Builder   | A Gate refused the unit: fill `{{task}}` and `{{report}}`                                                                                                                                                                                             |
 | `ticket/fix.mjs`                | Builder   | A judgement refused the assembled ticket: fill `{{task}}` and `{{report}}`                                                                                                                                                                            |
@@ -68,12 +67,12 @@ these all use it. How Host wires a slot into a run:
 | `gates/workspace-changed.mjs`   | Gate      | The Attempt left an uncommitted change                                                                                                                                                                                                                |
 | `gates/parent-clean.mjs`        | Gate      | Isolator's Parent working files did not move                                                                                                                                                                                                          |
 | `gates/sensitive-path.mjs`      | Gate      | No path matching a glob was touched                                                                                                                                                                                                                   |
+| `gates/base-diff.mjs`           | Gate      | What the work changed since the line (`--base`): no denied path was touched, or a command holds when a path did |
+| `gates/tests-only.mjs`          | Gate      | Every path the workspace changed matches a glob: the tests, their helpers and the manifest, nothing else |
 | `gates/workspace-unchanged.mjs` | Gate      | A read-only pass changed nothing at all (a file modified, deleted or added)                                                                                                                                                                           |
 | `gates/gitignore-leak.mjs`      | Gate      | The ticket's commits add nothing its own `.gitignore` excludes                                                                                                                                                                                        |
 | `gates/project-checks.mjs`      | Gate      | One command of the Project's own (typecheck, tests, lint, build) exits 0 in the workspace                                                                                                                                                             |
-| `gates/tests-red.mjs`           | Gate      | The tests just written fail, and not on a missing import or a syntax error (`--cmd` with `{files}`, `--test-glob`, `--not-red-when`).                                                                                                                 |
-| `gates/tests-frozen.mjs`        | Gate      | A test file held by the "Tests: " checkpoint was not modified, deleted or renamed (`--test-glob`, `--subject-prefix`)                                                                                                                                 |
-| `gates/e2e.mjs`                 | Gate      | The Feature's acceptance suite, run once on the assembled line: the Project's `--up` / `--ready` / `--run` / `--down`, a JUnit report compared with the manifest of scenario ids, each failing test retried once. |
+| `gates/feature-tests.mjs`       | Gate      | The Feature's own tests, run once on the assembled line: the Project's `--run` filtered on the ids of the manifest, a JUnit report compared with them. |
 | `gates/ci-green.mjs`            | Gate      | The work line's own checks came back green                                                                                                                                                                                                            |
 | `publishers/git.mjs`            | Publisher | Pushes the ticket's branch to the work line's own remote                                                                                                                                                                                              |
 | `refreshers/git.mjs`            | Refresher | Fast-forwards the work line copy onto what the Authority holds                                                                                                                                                                                        |
@@ -407,11 +406,52 @@ the workspace — tracked paths, and new ones `.gitignore` does not exclude —
 what an install left under an ignored directory (a dependency's own `.github/`)
 is not a change to guard.
 
+`base-diff` is `sensitive-path` against the work line instead of `HEAD`. It takes the
+paths that differ between the base and the workspace — the commits since the workspace
+left it (`BASE...HEAD`) and what is on disk and not committed, an ignored path excluded —
+so it still sees the work after the commit, and answers at the unit, the ticket and the
+recheck (`--stage assembly`). The base is the branch checked out in the **main worktree**
+of the repository the workspace belongs to: Isolation makes every workspace a worktree of
+the work line's copy, and Host keeps that copy on the line the work lands on, a
+Feature's own line while a Feature is open. In a Ticket of a Feature the diff is therefore
+the Ticket's own, not the Feature's so far. `--base REF` names another ref instead; a
+hand-named `main` is the copy's local branch, which Host does not move (the Refresher
+moves the Feature's line), so it can be weeks old. Two uses, alone or together:
+
+```yaml
+- id: no-workflow-edit
+  argv: [node, ./node_modules/@bluewombat/slots/gates/base-diff.mjs, --deny, ".github/workflows/**"]
+- id: e2e-when-app-changes
+  timeoutMs: 600000
+  argv:
+    - node
+    - ./node_modules/@bluewombat/slots/gates/base-diff.mjs
+    - --when
+    - "src/**"
+    - --run
+    - "npm run e2e"
+```
+
+`--deny GLOB` (repeatable) fail-retries when a changed path matches. `--when GLOB`
+(repeatable) with `--run COMMAND` hands the command to `project-checks` when a changed path
+matches (so it is cleaned, bounded by the Gate's ceiling and classified as every command of
+the Project is) and answers as it does; `MASON_BASE` is the base and `MASON_CHANGED_FILES`
+the changed paths one per line. When nothing matches it passes without running it. It
+fail-blocks where there is no base to derive: the workspace is the main worktree itself,
+the main worktree has no branch (detached), a `--base` the workspace lacks, and
+`--stage feature` without `--base` — the Feature's workspace is its line with the target
+merged in, so the line would show the target's work; name the target there.
+
+`tests-only` is its counterpart: it fail-retries if the workspace changed a path that matches
+none of the globs (added, modified, deleted or renamed, tracked or new and not ignored). It is
+the Gate of the feature-test Ticket, whose tests sit among the Project's code
+(`**/*.test.ts`), where a list of denied paths cannot say "everything but tests".
+
 `project-checks --cmd COMMAND` runs one command of the Project's own in the workspace
 and answers on its exit code. It is the Gate that makes a machine, not the Builder,
 say that the code typechecks and the tests pass. The command goes through the shell,
 so it is written as the Project writes it; it knows no stack.
-The report carries the end of the output, cleaned as it arrives: escape codes removed, a line redrawn with `\r` reduced to its last state, and spinner or progress lines (`[⣷] Pulling schema...`) dropped, so thousands of redraws cannot push the real error out of the tail. `tests-red` reads its output the same way.
+The report carries the end of the output, cleaned as it arrives: escape codes removed, a line redrawn with `\r` reduced to its last state, and spinner or progress lines (`[⣷] Pulling schema...`) dropped, so thousands of redraws cannot push the real error out of the tail. `feature-tests` reads its output the same way.
 
 ```yaml
 - id: typecheck
@@ -502,70 +542,56 @@ the variable holding a token that can read the checks — the same one the
 manager's `tokenEnv` names. It has no default on purpose: `GITHUB_TOKEN` is
 what `gh` reads ahead of its own login, so an operator must not export it,
 and a Gate that fell back to it refused only at the first assembly of a real
-run. `--remote`, `--poll-ms` and `--api-base` (GitHub Enterprise) are there too. It talks to GitHub, and knows
+run. `--remote`, `--poll-ms` and `--api-base` (GitHub Enterprise) are there too.
+`--require-check NAME` (repeatable) names a check that must exist and have succeeded:
+the check run (or status context) called exactly `NAME`. The general rule counts a
+`skipped` or `neutral` run as green, so an e2e job skipped for want of its secrets lets the
+line through; a required one that settled so is `fail-blocking`: the work cannot make it run, so a person reads it, not a fix agent. One not created yet is
+waited for like `--require-checks`, and at the ceiling the CI did not answer
+(`fail-blocking`). A name is exact: a matrix job is one check per cell (`e2e (chrome)`), and each is listed. It talks to GitHub, and knows
 nothing about `@bluewombat/manager-github`: a Project may run either one
 without the other.
 
-`sensitive-path`, `workspace-changed`, `gitignore-leak` and `ci-green` need a git workspace, which
+`sensitive-path`, `base-diff`, `workspace-changed`, `gitignore-leak` and `ci-green` need a git workspace, which
 is what Isolator makes when WorkLineStable is a git tree. They fail-block on a
 workspace Isolator had to copy.
 
-### The e2e acceptance suite
+### The feature tests
 
-`e2e.mjs` runs a Feature's acceptance suite on the assembled Feature line, from a Feature Gate
-(`feature.validate.gates`). It knows no stack: the Project supplies four commands, run through
-the shell in the workspace, and the Gate starts, waits, runs, compares and always stops.
+`feature-tests.mjs` runs the tests of a Feature on the assembled Feature line, from a Feature Gate
+(`feature.validate.gates`). Only the scenarios of this Feature run, not the Project's whole suite. It
+knows no stack and starts no application: the Project supplies one command, run through the shell
+in the workspace, and the Gate runs it, compares and judges.
 
 | Option | Meaning |
 | --- | --- |
-| `--up CMD` | Required. Starts the application. It may return once started or keep running; the Gate does not wait for it, it waits for `--ready`. An `--up` that exits non-zero before that is a start failure |
-| `--ready CMD` | Required. Exit 0 when the application answers. Polled every second until `--start-timeout-ms` |
-| `--run CMD` | Required. Runs the suite and writes a JUnit XML report to `--junit` |
-| `--rerun CMD` | Runs the failed scenarios again; `{ids}` is their ids joined with `\|` (a regular expression, `pnpm e2e --grep "{ids}"`). Absent: `--run` again, whole |
-| `--down CMD` | Required. Stops the application. Always run, whatever happened; the process group of `--up` is killed after it |
-| `--manifest PATH` | The scenarios the suite must hold. Default `e2e/scenarios.json`: an array of ids, or `{ "scenarios": [ "E1" \| { "id": "E1", "title": "…" } ] }` |
-| `--junit PATH` | Where `--run` writes its report. Default `e2e/results/junit.xml`. Removed before every run, so an old report is never read |
-| `--server-log PATH` | The application's log, whose tail goes in a red report. Default: what `--up` printed |
-| `--max-scenarios N` | The most scenarios a suite may hold. Default 5 |
-| `--max-run-ms N` | The most the whole Gate may take. Default 600000 (10 minutes), and never more than the Gate's own ceiling less 25 s |
-| `--start-timeout-ms N` | The most `--up` and `--ready` may take together. Default 120000 |
-| `--host HOST` | Handed to every command as `E2E_HOST`. Default `127.0.0.1`; any non-loopback address is refused |
-| `--port N` | Handed to every command as `E2E_PORT`. Absent: the application's own choice |
-
-Every command also gets `E2E_DATA_DIR`, an empty directory made for the run and removed after it
-(the data is disposable), and `E2E_RESULTS_DIR`, the folder of `--junit`. A secret is not an
-option of the Gate: the commands read it from the environment mason was started in, and it
-belongs in no file of the repository.
-
-A scenario is a manifest id, and every test carries its id in its name (`E2 pays by card`). The
+| `--run CMD` | Required. Runs the tests of the Feature and writes a JUnit XML report. `{ids}` is the ids of the manifest joined with `\|` (a regular expression, `pnpm test --grep "{ids}"`), `{junit}` the path of the report |
+| `--manifest PATH` | The scenarios of the Feature. Default `feature-tests/scenarios.json`: an array of ids, or `{ "scenarios": [ "S1" \| { "id": "S1", "title": "…" } ] }` |
+| `--junit PATH` | Where `--run` writes its report. Default `feature-tests/results/junit.xml`. Removed before every run, so an old report is never read |
+| `--max-run-ms N` | The most the whole Gate may take. Default 600000 (10 minutes), and never more than the Gate's own ceiling less 5 s |
+
+A scenario is a manifest id, and every test carries its id in its name (`S2 pays by card`). The
 comparison is exact: an id with no test, a test with no manifest id, and a test the runner
-skipped are failures. A failing test is run once more: a pass then is reported `UNSTABLE`, and
-is not a refusal; failing twice is red. The verdict:
+skipped are failures. There is no retry. The verdict:
 
 | Verdict | When |
 | --- | --- |
-| `pass` | Every scenario ran and passed. The report says how many and which, and which were unstable |
-| `fail-retryable` | Red: the report has, per scenario, its id, the test, the step (`at`), the message, the trace path when the runner saved one, then the last 40 lines of the server log. Screenshots and traces stay on disk beside the report. The suite is frozen; the application is the producer's to repair. Also a runner that crashed before writing a report |
-| `fail-blocking` | What no change to the application fixes: a missing, empty or oversized manifest, an application that does not start or is never ready, a run or a retry that outlives the ceiling, a suite that exits 0 and writes no report, a non-loopback `--host` |
+| `pass` | Every scenario ran and passed. The report says how many and which |
+| `fail-retryable` | Red: the report has, per scenario, its id, the test, the step (`at`) and the message. Whether the test or the application is wrong is for the caller to say: the feature-test Ticket's author reads the report to fix its tests, and the Feature's fix repairs the application with the tests frozen. Also a runner that crashed before writing a report, and tests that carry no id of the manifest |
+| `fail-blocking` | What no change to the application fixes: a missing, empty or malformed manifest, a run that outlives the ceiling, a run that exits 0 and writes no report |
 
-The Project's `.gitignore` excludes the results folder (`e2e/results/`): a Gate that guards the
-suite folder (`sensitive-path e2e/**` in `feature.fix.gates`) would read the report as a change.
+The Project's `.gitignore` excludes the results folder (`feature-tests/results/`): a Gate that guards
+the folder (`sensitive-path feature-tests/**` in `feature.fix.gates`) would read the report as a change.
 
 ```yaml
-- id: e2e
-  skipWhen: skip-test-e2e   # Host's: not run for a Feature that carries the label
+- id: feature-tests
+  skipWhen: skip-feature-test   # Host's: not run for a Feature that carries the label
   timeoutMs: 720000
   argv:
     - node
-    - ./node_modules/@bluewombat/slots/gates/e2e.mjs
-    - --up
-    - pnpm e2e:up
-    - --ready
-    - pnpm e2e:ready
+    - ./node_modules/@bluewombat/slots/gates/feature-tests.mjs
     - --run
-    - pnpm e2e
-    - --down
-    - pnpm e2e:down
+    - pnpm test --grep "{ids}" --reporter=junit --outputFile={junit}
 ```
 
 ## Publishers
@@ -650,7 +676,7 @@ type in JSDoc.
 ```
 README.md      this file
 agents/        vendor CLIs: filled prompt in, serialized run out
-builders/      first-pass and repair roles for the unit of work, and the e2e Ticket's
+builders/      first-pass and repair roles for the unit of work, and the feature-test Ticket's
 ticket/        fix and validate for an assembled ticket
 feature/       fix for a whole feature
 lib/           what the shipped templates say, shared by the roles

package/builders/{e2e.mjs → feature-test.mjs}

@@ -15,29 +15,38 @@ import {
 } from "@bluewombat/slot-kit";
 import { attemptOf } from "../lib/fill.mjs";
 
-// The Ticket that holds a Feature's e2e acceptance suite. One command for its first pass and for
-// a pass a Gate refused: the suite is written once from the scenarios of the task, and a refusal
-// is about its form, so there is no second command to tell apart. `{{report}}` and
-// `{{refused_by}}` are empty on a first pass; `{{refusal}}` is a ready-made paragraph about them.
+// The Ticket that holds a Feature's tests. One command for its first pass and for a pass a Gate
+// refused: the tests are written once from the scenarios of the task, and a refusal is about their
+// form, so there is no second command to tell apart. `{{report}}` and `{{refused_by}}` are empty
+// on a first pass; `{{refusal}}` is a ready-made paragraph about them.
 
-const NAME = "builder e2e";
+const NAME = "builder feature-test";
 
 const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
 
-You write the acceptance suite of a feature. The task below lists its scenarios, agreed with the
-operator before development, each with an id (E1, E2, ...).
+You write the tests of a feature. The task below lists its scenarios, agreed with the operator
+before development, each with an id (S1, S2, ...). The feature is built: this checkout holds every
+other Ticket of it.
 
 Task:
 {{task}}
 
-- Write one test per scenario, in the end-to-end framework this project already uses, and
-  start the name of each test with its scenario id ("E1 …"). Follow the scenario's steps and
-  expected result as written; do not add, merge or drop one.
-- List the ids in the manifest \`e2e/scenarios.json\`, a JSON array: ["E1", "E2"].
-- Write only inside the suite folder (\`e2e/\`). Touch no file of the application, and add no
+- Write one test per scenario, in the test framework this project already uses, at the level the
+  scenario describes (through the feature's public interfaces: routes, services, pages), and start
+  the name of each test with its scenario id ("S1 …"). Follow the scenario's steps and expected
+  result as written; do not add, merge, drop or weaken one. If a scenario changes a behaviour that
+  existing tests describe, update those tests to the new behaviour, and only those.
+- List the ids of the scenarios in the manifest \`feature-tests/scenarios.json\`, a JSON array:
+  ["S1", "S2"]. Only the scenarios of this feature, never the project's other tests.
+- Write only tests, their helpers and the manifest. Touch no file of the application, and add no
   dependency it does not already have.
-- The feature is not finished here and the application is not started: do not run the suite. Check
-  only that it compiles, with the project's own typecheck or build command.
+- A Gate runs your tests against the built feature after every attempt and gives you its report
+  (the refusal below). Read it: a test that fails for its own reasons (a wrong selector or wait, a
+  wrong data setup, a misread expectation) is yours to fix. Check only that your tests compile
+  before you finish, with the project's own typecheck or build command.
+- If a test stays red because the feature does not do what the scenario says, do not change the
+  application and do not weaken the test: that is a finding. Change nothing more and end with
+  MASON_BLOCKED, naming the scenario, what the feature does instead and where.
 
 {{refusal}}
 
@@ -45,9 +54,10 @@ Task:
 
 ## When you cannot act
 
-If what you were given is not enough to act on (a scenario is ambiguous, the framework is missing,
-the cause is outside this directory), do not invent a change. Change nothing and end your final
-message with exactly one line:
+If what you were given is not enough to act on (a scenario is ambiguous, cannot be written without
+changing the application or without a weaker result than asked, the framework is missing, the
+feature is wrong, the cause is outside this directory), do not invent a change and do not lower
+the scenario. Change nothing and end your final message with exactly one line:
 
 MASON_BLOCKED: <what is missing, in one line>
 

package/gates/base-diff.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  emitVerdict,
+  GATE_FLAGS,
+  listOption,
+  ownArgv,
+  parseOptions,
+  pathMatchesGlob,
+  stageOf,
+  take,
+  textOption,
+} from "@bluewombat/slot-kit";
+
+// What the work changed since the line it is offered to, judged by path.
+//
+// The base is the work line the workspace was cut from. Without --base it is the
+// branch checked out in the main worktree of the repository the workspace belongs
+// to: Isolation makes every workspace a worktree of the work line's copy, and Host
+// keeps that copy on the line the work lands on (a Feature's own line while a
+// Feature is open), so the answer follows the line. A branch named by hand
+// (`--base main`) is the copy's local branch and is only as fresh as the last
+// time something moved it; Host moves the Feature's line, not `main`.
+//
+// The changed set is what differs between the base and the workspace: the commits
+// since the workspace left it (`BASE...HEAD`) and whatever is on disk and not yet
+// committed (a fold can carry it out, so it counts; an ignored path does not).
+// Unlike a Gate that compares the disk to the last commit, it still sees the work
+// once it is committed, so it answers at the unit, the ticket and the recheck
+// after the align (`--stage assembly`).
+//
+// At `--stage feature` there is no base to derive: the Feature's workspace is its
+// line with the target merged in, so the line would show the target's work. Name
+// the target with --base there.
+//
+//   --base REF       optional. The ref to compare with, instead of the main
+//                    worktree's branch.
+//
+// Two ways to use the changed set, alone or together:
+//
+//   --deny GLOB      repeatable. fail-retryable when a changed path matches:
+//                    "this must not be touched".
+//   --when GLOB      repeatable, with --run. When a changed path matches, run
+//                    CMD with project-checks (shell, output cleaned, the Gate's
+//                    ceiling honoured) and answer as it does: "if this changed,
+//                    this must hold". When nothing matches, pass without running it.
+//   --run CMD        MASON_BASE holds the base; MASON_CHANGED_FILES holds the
+//                    changed paths, one per line, so CMD can narrow itself to them.
+//
+// `*` is one path segment, `**` any depth.
+
+const cwd = process.cwd();
+const projectChecks = join(dirname(fileURLToPath(import.meta.url)), "project-checks.mjs");
+
+const parsed = parseOptions(
+  ownArgv(process.argv, GATE_FLAGS),
+  { "--base": {}, "--deny": { many: true }, "--when": { many: true }, "--run": {} },
+  "base-diff",
+);
+if (!parsed.ok) {
+  emitVerdict("fail-blocking", parsed.reason);
+  process.exit(0);
+}
+const explicitBase = textOption(parsed.values, "base");
+const deny = listOption(parsed.values, "deny");
+const when = listOption(parsed.values, "when");
+const command = textOption(parsed.values, "run");
+
+if (explicitBase?.startsWith("-")) {
+  emitVerdict("fail-blocking", `base-diff cannot take "${explicitBase}" as a base.`);
+  process.exit(0);
+}
+if (deny.length === 0 && when.length === 0 && command === undefined) {
+  emitVerdict(
+    "fail-blocking",
+    "base-diff needs at least one --deny GLOB, or --when GLOB with --run CMD.",
+  );
+  process.exit(0);
+}
+if (when.length > 0 !== (command !== undefined)) {
+  emitVerdict(
+    "fail-blocking",
+    "base-diff takes --when and --run together: a condition, and what to run on it.",
+  );
+  process.exit(0);
+}
+
+if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
+  emitVerdict("fail-blocking", "base-diff needs a git workspace.");
+  process.exit(0);
+}
+
+const base = explicitBase ?? deriveBase();
+if (base === undefined) {
+  process.exit(0);
+}
+if (git(["rev-parse", "--verify", "--quiet", `${base}^{commit}`]).status !== 0) {
+  emitVerdict("fail-blocking", `base-diff cannot find the base "${base}" in this workspace.`);
+  process.exit(0);
+}
+
+const changed = changedPaths();
+if (changed === undefined) {
+  process.exit(0);
+}
+
+if (deny.length > 0) {
+  const hit = changed.filter((path) => matchesAny(path, deny));
+  if (hit.length > 0) {
+    emitVerdict(
+      "fail-retryable",
+      `Paths changed since ${base} that this work may not touch (${deny.join(", ")}):\n${hit.join("\n")}`,
+    );
+    process.exit(0);
+  }
+}
+
+if (command !== undefined && changed.some((path) => matchesAny(path, when))) {
+  runCondition(command);
+} else {
+  emitVerdict("pass");
+}
+
+/**
+ * The branch checked out in the main worktree: the line this workspace's work
+ * lands on. Nothing when there is none to name; the verdict is then already out.
+ * @returns {string | undefined}
+ */
+function deriveBase() {
+  if (stageOf(process.argv) === "feature") {
+    emitVerdict(
+      "fail-blocking",
+      "base-diff cannot derive a base at the feature stage: the Feature's workspace is its line with the target merged in, so the line would show the target's work, not the Feature's. Name the target with --base.",
+    );
+    return undefined;
+  }
+  const listed = git(["worktree", "list", "--porcelain"]);
+  if (listed.status !== 0) {
+    emitVerdict("fail-blocking", `base-diff cannot list the worktrees: ${listed.stderr.trim()}`);
+    return undefined;
+  }
+  // The first entry is the main worktree.
+  const main = listed.stdout.split("\n\n")[0] ?? "";
+  const mainPath = /^worktree (.+)$/m.exec(main)?.[1];
+  const branch = /^branch refs\/heads\/(.+)$/m.exec(main)?.[1];
+  const top = git(["rev-parse", "--show-toplevel"]).stdout.trim();
+  if (mainPath === undefined || top.length === 0) {
+    emitVerdict(
+      "fail-blocking",
+      "base-diff cannot tell which worktree is the main one. Name the base with --base.",
+    );
+    return undefined;
+  }
+  if (sameDirectory(mainPath, top)) {
+    emitVerdict(
+      "fail-blocking",
+      "base-diff has no base to derive: this workspace is the main worktree itself, not a worktree of a work line. Name the base with --base.",
+    );
+    return undefined;
+  }
+  if (branch === undefined) {
+    emitVerdict(
+      "fail-blocking",
+      `base-diff has no base to derive: the main worktree (${mainPath}) has no branch checked out. Name the base with --base.`,
+    );
+    return undefined;
+  }
+  return `refs/heads/${branch}`;
+}
+
+/**
+ * Runs the --run command through project-checks, so it is cleaned, bounded and
+ * classified the way every command of the Project is, and relays its verdict.
+ * @param {string} cmd
+ */
+function runCondition(cmd) {
+  const flags = ["--cmd", cmd];
+  const ceiling = take(process.argv, "--timeout-ms");
+  if (ceiling !== undefined) {
+    flags.push("--timeout-ms", ceiling);
+  }
+  const result = spawnSync(process.execPath, [projectChecks, ...flags], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    env: { ...process.env, MASON_BASE: base, MASON_CHANGED_FILES: (changed ?? []).join("\n") },
+  });
+  const line = (result.stdout ?? "").trim().split("\n").filter(Boolean).at(-1);
+  /** @type {{ verdict?: string; report?: string } | undefined} */
+  let answer;
+  try {
+    answer = line === undefined ? undefined : JSON.parse(line);
+  } catch {
+    answer = undefined;
+  }
+  if (answer?.verdict === "pass") {
+    emitVerdict("pass");
+    return;
+  }
+  if (answer?.verdict === "fail-retryable" || answer?.verdict === "fail-blocking") {
+    const lead = `Paths matching ${when.join(", ")} changed since ${base}. `;
+    emitVerdict(answer.verdict, `${lead}${answer.report ?? ""}`.trim());
+    return;
+  }
+  emitVerdict(
+    "fail-blocking",
+    `base-diff could not read the answer of "${cmd}": ${(result.stderr ?? "").trim().slice(-2_000) || "no output"}`,
+  );
+}
+
+/**
+ * Every path that differs from the base, committed or not, sorted. Nothing when
+ * git could not say: the verdict is already out.
+ * @returns {string[] | undefined}
+ */
+function changedPaths() {
+  // --no-renames: a move is a removal and an addition, so the old path counts too.
+  const committed = git(["diff", "--name-only", "--no-renames", "-z", `${base}...HEAD`]);
+  if (committed.status !== 0) {
+    emitVerdict(
+      "fail-blocking",
+      `base-diff cannot diff HEAD against "${base}": ${committed.stderr.trim()}`,
+    );
+    return undefined;
+  }
+  const status = git(["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+  if (status.status !== 0) {
+    emitVerdict("fail-blocking", `base-diff cannot read the workspace: ${status.stderr.trim()}`);
+    return undefined;
+  }
+  const paths = new Set(committed.stdout.split("\0").filter(Boolean));
+  const fields = status.stdout.split("\0");
+  for (let i = 0; i < fields.length; i++) {
+    const entry = fields[i] ?? "";
+    if (entry.length < 4) {
+      continue;
+    }
+    paths.add(entry.slice(3));
+    // A rename or a copy carries the old path in the next field.
+    if (entry[0] === "R" || entry[0] === "C") {
+      const old = fields[++i];
+      if (old !== undefined && old.length > 0) {
+        paths.add(old);
+      }
+    }
+  }
+  return [...paths].map((path) => path.replaceAll("\\", "/")).sort();
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ */
+function sameDirectory(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return a === b;
+  }
+}
+
+/**
+ * @param {string} path
+ * @param {readonly string[]} patterns
+ */
+function matchesAny(path, patterns) {
+  return patterns.some((pattern) => pathMatchesGlob(path, pattern));
+}
+
+/** @param {string[]} args */
+function git(args) {
+  return spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+}