@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

package/dist/templates/monorepo/scripts/backlog/guards.ts

@@ -0,0 +1,1234 @@
+/**
+ * guards.ts — the nine dispatch guards over a selected `Queued` task (the original six, plus
+ * guards 1b, 1c and 4b, added after the fact — see their own doc comments).
+ *
+ * Implements `specs/backlog-task-dispatcher/spec.md` — "Dispatch guards over the selected task",
+ * "Lane capacity caps" — and `specs/headless-harness-execution/spec.md` — "Security paths
+ * never dispatch to the local lane" (the pre-launch half; the close-time re-check against the
+ * real diff is `close.ts`, task 3.12, out of this module's scope).
+ *
+ * Pure function, no filesystem or process access: `evaluateGuards` takes the already-loaded task,
+ * board (for dependency lookups) and slot registry, and returns one of three outcomes —
+ * `launch`, `wait` (leave `Queued`, re-evaluate next pass), or `block` (move to `Blocked` with a
+ * cause and a user-facing Spanish comment, since the board is in Spanish). The nine guards run in
+ * a FIXED order and the first one that fires wins — later guards are never evaluated once an
+ * earlier one has decided the outcome (see the "evaluation order" tests in `guards.test.ts`).
+ *
+ * It also owns `resolveTestCommand`, the single allowlist for a task's declared `Test command:`
+ * line: guard 1 refuses a line it rejects, `launch.ts` turns the argv it returns into the worker's
+ * one Bash grant, and `close.ts` runs it as the triad's last check; and the split path criteria
+ * (T-31), which live HERE and not in `close.ts` so that dependency stays one-way — the close already
+ * reads this module for `SECURITY_PATH_PATTERNS`, and pre-launch validation is upstream of the close
+ * by definition. The four lists have DIFFERENT readers, and which reads which is load-bearing:
+ *
+ *   - `SLOT_EXECUTED_PATHS` + `SLOT_EXECUTED_BASENAMES` (hard) — read by BOTH guard 1c (against the
+ *     task's DECLARED files, before a slot is spent) and `close.ts`'s `checkScope` (against the real
+ *     diff, on both lanes);
+ *   - `HUMAN_REVIEW_PATHS` (soft) — read by `checkScope` ONLY. Guard 1c deliberately does not
+ *     consult it: a declared soft path is admissible work that marks its pull request, so blocking
+ *     it in the queue would refuse exactly what the split exists to allow;
+ *   - `LOCAL_FORBIDDEN_PATHS` (the hard list plus the local lane's extras) — read by `checkScope`'s
+ *     local branch ONLY. Guard 1c does not extend to the extras either (design.md Non-Goals), so a
+ *     `lane:local` task declaring `scripts/foo.ts` is still discovered at close.
+ */
+import {
+  TASK_STATUS,
+  TIER,
+  type Board,
+  type DispatchLimits,
+  type SettingsAllowRule,
+  type SlotRegistry,
+  type Task,
+  type Tier,
+} from './types.js';
+
+// ── Security path list ─────────────────────────────────────────────────────────
+
+/**
+ * Mechanical, deterministic approximation of the root `CLAUDE.md`'s "Security gate" surface list
+ * (auth/authz, secrets/sensitive config) — design.md decision (j) requires this check to be a
+ * path list, not a model judgment, "non-deterministic on exactly the decision that must not be".
+ *
+ * Matched as a case-insensitive substring against each of the task's declared `filesToTouch`.
+ * Exported so `close.ts` (task 3.12) can reuse the SAME list for its close-time re-check against
+ * the real diff, per that spec's "verify this mechanically both before launch and against the
+ * real diff at close".
+ */
+export const SECURITY_PATH_PATTERNS: readonly string[] = [
+  'o-auth/',
+  'iam/',
+  '.guard.ts',
+  '@auth',
+  'sops',
+  '.env',
+];
+
+function declaresSecurityPath(filesToTouch: readonly string[]): boolean {
+  const lowerFiles = filesToTouch.map((file) => file.toLowerCase());
+  return SECURITY_PATH_PATTERNS.some((pattern) => {
+    const lowerPattern = pattern.toLowerCase();
+    return lowerFiles.some((file) => file.includes(lowerPattern));
+  });
+}
+
+// ── The split path criteria (T-31, 2026-09-09) ────────────────────────────────
+//
+// One list became two, by one mechanical question: does this file EXECUTE inside the slot during
+// the attempt or during the close? `close.ts`'s `checkScope` (the close-time re-check against the
+// real diff) and `checkDeclaredSlotExecutedPath` below (the pre-launch check against DECLARED
+// files, guard 1c) both read these lists — moved here, out of `close.ts`, for the same reason
+// `SECURITY_PATH_PATTERNS` already lives here: a criterion checked BOTH before launch and at close
+// belongs with the other guard-1 checks, and `close.ts` already imports this module, so keeping the
+// lists there would close an import cycle the moment a guard needed them too.
+//
+// Board measurement, recounted 2026-09-09 (T-31 round 3, superseding round 1's figures — the board
+// has grown since, this change's own follow-ups included): of the 36 tasks on the board, 34 carry a
+// `Files to touch:` line, and 19 of those declare at least one path these lists reach. 43 hits in
+// all, and they concentrate in the two SOFT entries — `scripts/backlog/` (30) and `packages/cli/`
+// (10) — neither of which is read as instructions or sits on the path the dispatcher runs from,
+// which is what makes them soft (see `HUMAN_REVIEW_PATHS` below, and read its caveats: soft does NOT
+// mean inert). The hard list barely registered: `package.json` 1, `.backlog/` 1, `CLAUDE.md` 1 (by
+// basename), and the other NINE path entries never fired at all. That is why keeping `CLAUDE.md`
+// hard blocks no real work.
+
+/**
+ * HARD — refused on both lanes, whether or not the task declared it, because something RUNS it
+ * inside the slot during the attempt or the close:
+ *
+ *   - `.claude/settings.json` / `.claude/settings.local.json` / `.claude/hooks/` / `.claude/scripts/`
+ *     — the project's `PostToolUse` hook runs `$CLAUDE_PROJECT_DIR/.claude/hooks/format-with-prettier.ts`,
+ *     and `CLAUDE_PROJECT_DIR` IS THE SLOT: a hook a worker writes there runs as the worker on its
+ *     very next edit, past every permission rule. The local overlay (`settings.local.json`) is read
+ *     LAST by the harness, so a rule written there outranks the one it overlays.
+ *   - `.husky/` — runs on the close's own `git commit`.
+ *   - `package.json`, `pnpm-lock.yaml`, `node_modules/` — the close runs Prettier, the barrels lint
+ *     and the task's own declared test command with `pnpm`, INSIDE the slot: a rewritten `test`
+ *     script or a tampered lockfile is code the dispatcher executes moments later.
+ *   - `.backlog/` — not executed by an interpreter, but read as the close's own verdict input in the
+ *     same run: it holds the acceptance criteria and Definition of Done the attempt is judged
+ *     against, so a worker that edits it rewrites the criteria that judge it — the same failure mode
+ *     as the six paths above, just without a language runtime in between.
+ *   - `scripts/harness-rules/` — the close's mechanical triad runs `pnpm hr:lint-barrels` with
+ *     `cwd` = the slot, and the root `package.json` maps that script to
+ *     `tsx scripts/harness-rules/lint-barrels.ts` — the SLOT's copy. `package.json` being hard
+ *     protects the script NAME; it does nothing for the file the name points at. It fires whenever
+ *     the attempt changed a `.ts` file under the roots HR-BARRELS governs, which is most frontier
+ *     product work.
+ *   - `scripts/packager/` — the close's `mirrorRegen` step runs `node scripts/packager/publish.mjs`
+ *     with `cwd` = the slot (`dispatch.ts`'s `mirrorRegen` runner). That script does not run a fixed
+ *     set of files: it GLOBS `monorepo.mjs`, `backend/*.mjs` and `frontend/*.mjs` inside its OWN
+ *     directory — `PACKAGER_DIR`, derived from `import.meta.url`, so the SLOT's copy — and spawns
+ *     every match with `process.execPath` and the dispatcher's INHERITED environment. A worker that
+ *     drops one `.mjs` file into `scripts/packager/backend/` has the close execute it minutes later
+ *     with the dispatcher's own credentials. Nothing in the code says this: the glob is in
+ *     `publish.mjs`, three files away from the list, which is why it is written down here.
+ *
+ * The entries were derived BACKWARD as well as forward — see design.md decision 1's enumeration of
+ * everything the dispatch and the close execute or read from inside the slot, and the one
+ * documented gap it left (`.github/workflows/cli-template-drift-check.yml`).
+ */
+export const SLOT_EXECUTED_PATHS: readonly string[] = [
+  '.claude/settings.json',
+  // Not a superstring of the entry above — `.claude/settings.local.json` does not CONTAIN
+  // `.claude/settings.json` — and it is the file Claude Code reads last, so it needs its own entry.
+  '.claude/settings.local.json',
+  '.claude/hooks/',
+  '.claude/scripts/',
+  '.husky/',
+  'package.json',
+  'pnpm-lock.yaml',
+  'node_modules/',
+  '.backlog/',
+  // Disjoint from the soft `scripts/backlog/` entry, and both must stay so: these two directories
+  // are the parts of `scripts/` the close actually spawns.
+  'scripts/packager/',
+  'scripts/harness-rules/',
+];
+
+/**
+ * HARD too, matched by BASENAME rather than as a substring — `CLAUDE.md` is the instruction file
+ * every later reader treats as law. It lives at the root of the repo and of every scope, so there
+ * is no directory prefix to match, and a substring pattern would swallow an unrelated file whose
+ * name merely contains it (`claude.mdx`).
+ *
+ * Refused at close on BOTH lanes and blocked in the queue by guard 1c, for two measured reasons:
+ *
+ *   - the LOCAL close runs an AI reviewer over the attempt's own diff with `cwd` = the slot
+ *     (`dispatch.ts`'s `reviewer` runner), and `buildReviewerCommand` (`reviewer.ts`) does
+ *     NOT pass `--bare` — the one flag that turns instruction-file auto-discovery off, and one the
+ *     reviewer cannot take because it would strip the account credential it authenticates with. An
+ *     instruction file the local executor writes is read as INSTRUCTIONS by the judge of that same
+ *     attempt: the executor authoring its own examiner's brief.
+ *   - on EITHER lane, an instruction file written by attempt N is read by attempt N+1's executor.
+ *     A FAILED close opens no pull request at all (`planClose`'s failure plan has no `open-pr`
+ *     step, so no PULL-REQUEST mark is applied), yet `dispatch.ts`'s `saveWipAndPush` still commits
+ *     the whole slot tree to `task/<id>` and the retry's `prepareSlot` runs
+ *     `checkout -B task/<id> origin/task/<id>` (`slots.ts`), restoring it. Marking a file
+ *     nobody is shown, in a channel that only exists on the green path, is not a control — so this
+ *     one is refused rather than marked (T-31 round 2; it was 1 of the 43 measured hits, so the
+ *     refusal blocks no real work).
+ */
+export const SLOT_EXECUTED_BASENAMES: readonly string[] = ['CLAUDE.md'];
+
+/**
+ * SOFT — admitted; the close marks the pull request for human review instead of failing it
+ * (`close.ts`'s `checkScope`, `humanReviewFiles`).
+ *
+ * What "soft" means here, stated as it was MEASURED (T-31 round 2 — the first pass of this split
+ * certified these entries as "inert during the attempt", and that certification was false in two
+ * independent ways):
+ *
+ *   - a soft-list file CAN be executed inside the slot during the CLOSE. Admitting the diff at
+ *     `scope-check` is what unlocks the rest of the success plan, and the triad's last step spawns
+ *     the task's own declared `Test command:` with `cwd` = the slot, inheriting the dispatcher's
+ *     environment. `ALLOWED_TEST_SCRIPT` admits `test:backlog`, which the root manifest maps to a
+ *     runner over `scripts/backlog/**` — the SLOT's copies. This is not a privilege the soft list
+ *     grants: EVERY dispatched task's test command already runs worker-written code in the slot
+ *     the same way (the hole design.md's Risks records and does not close). It is the reason the
+ *     classification cannot rest on "nothing runs it".
+ *   - a soft-list edit SURVIVES a failed attempt. The failure plan pushes the whole slot tree to
+ *     `task/<id>` (`dispatch.ts`'s `saveWipAndPush`), and the retry's `prepareSlot` runs
+ *     `checkout -B task/<id> origin/task/<id>` (`slots.ts`), which restores it. "The slot
+ *     is hard-reset, so nothing survives the attempt" holds only for a branch with no such push
+ *     behind it.
+ *
+ * What justifies the classification is narrower, and does hold: neither entry is read as
+ * INSTRUCTIONS by any process (that is why the instruction file is HARD, above), and neither is on
+ * the path the dispatcher itself runs from — it runs as `tsx scripts/backlog/dispatch.ts` from the
+ * MAIN checkout (`package.json:38`), `workerEditCommand` resolves the board wrapper with
+ * `path.join(mainCheckoutPath, …)` (`worker-edit.ts`), the board lives only in the main
+ * checkout (`BOARD_CWD_ENV`, `worker-edit.ts`), and the generator is never invoked by the
+ * close at all. So the reachable outcome of editing either one is a test run that behaves
+ * differently, which costs the attempt — and is exactly what a person reads the marked pull
+ * request for.
+ *
+ *   - `scripts/backlog/` — measured wrong as hard (T-31): the old justification said an attempt
+ *     that edits it "edits its own examiner", and the examiner is in the main checkout.
+ *   - `packages/cli/` — the generator is never invoked by the close; its MIRROR output
+ *     (`packages/cli/src/templates/`) is the separate, still-refused case — see `close.ts`'s
+ *     `MIRROR_OUTPUT_PREFIX` and its own doc comment.
+ *
+ * The marked pull request is not the only record, because on a FAILED close there is no pull
+ * request at all (that plan has no `open-pr` step): the `Blocked` comment names these files
+ * instead — see `close.ts`'s `BlockDetails.humanReviewFiles`.
+ */
+export const HUMAN_REVIEW_PATHS: readonly string[] = ['scripts/backlog/', 'packages/cli/'];
+
+/**
+ * Forbidden for the LOCAL lane, on top of `SLOT_EXECUTED_PATHS`: everything that RUNS during the
+ * close or governs what the worker may do. The lane settings deny writes to these paths already,
+ * but a permission rule is one mechanism and this is the second: a rule that silently fails to match
+ * would otherwise let a `tier:minor` executor write `.husky/pre-commit` and have the dispatcher's
+ * own `git commit` execute it moments later.
+ *
+ * Matched as substrings (like `SLOT_EXECUTED_PATHS`), so `scripts/` also catches
+ * `scripts/backlog/dispatch.ts` — this is why `scripts/backlog/` stays refused on the local lane
+ * even though it is soft everywhere else (design.md decision 6) — and `backend/src/scripts/`.
+ * Deliberately wide: the local lane takes `tier:minor` product fixes only; nothing it legitimately
+ * does lives under any of these. Unchanged by the split (design.md decision 6): the extras are
+ * byte-for-byte what they were before it.
+ */
+export const LOCAL_FORBIDDEN_PATHS: readonly string[] = [
+  ...SLOT_EXECUTED_PATHS,
+  '.claude/',
+  'scripts/',
+  '.git/',
+];
+
+/** The shared substring matcher `close.ts`'s `checkScope` and the guard below both read. */
+export function matchesAnyPathPattern(file: string, patterns: readonly string[]): boolean {
+  const lowerFile = file.toLowerCase();
+  return patterns.some((pattern) => lowerFile.includes(pattern.toLowerCase()));
+}
+
+/** The shared basename matcher — `close.ts`'s `checkScope` and guard 1c both read `SLOT_EXECUTED_BASENAMES` through it. */
+export function matchesBasename(file: string, basenames: readonly string[]): boolean {
+  const basename = file.slice(file.lastIndexOf('/') + 1).toLowerCase();
+  return basenames.some((name) => name.toLowerCase() === basename);
+}
+
+/**
+ * Whether a DECLARED entry reaches any of `patterns`. Two directions, because a declaration is not
+ * a path on disk — it is what a person wrote under `Files to touch:`, and `close.ts`'s `isDeclared`
+ * already reads a trailing `/` as "the whole subtree under it is mine":
+ *
+ *   - the declaration is (or is under) a pattern — the substring direction `matchesAnyPathPattern`
+ *     covers, e.g. `.claude/hooks/x.ts` under `.claude/hooks/`;
+ *   - the declaration is a DIRECTORY that CONTAINS a pattern — `- .claude/` reaches
+ *     `.claude/settings.json`, and `- scripts/` reaches `scripts/packager/`. A plain substring match
+ *     misses this entirely (`.claude/` does not contain `.claude/settings.json`), which let a legal
+ *     directory declaration sail past guard 1c and be discovered at close instead.
+ *
+ * The second direction matches on a SEGMENT boundary, not on a raw prefix: the declaration is
+ * normalised with one trailing `/` and the pattern must start with THAT. So `package` does not
+ * reach `package.json` (it names the directory `package/`, which holds no hard entry) while
+ * `- .claude` does reach `.claude/settings.json`. Requiring the person to have TYPED the trailing
+ * slash was the earlier shape and it was too narrow: `- .claude` and `- scripts` are how a
+ * `Files to touch:` list is actually written, and both sailed past guard 1c — the exact wasted
+ * worker this guard exists to prevent (T-31 round 2).
+ *
+ * `close.ts`'s `isDeclared` keeps requiring the literal trailing slash, deliberately: it decides
+ * whether a real changed file was AUTHORISED, so widening what a declaration covers there widens
+ * the local lane's allowlist. Here the same widening only makes a refusal fire earlier. The two
+ * need not agree because they read the declaration for opposite purposes.
+ */
+export function declarationReachesPathPattern(
+  declared: string,
+  patterns: readonly string[],
+): boolean {
+  const lowerDeclared = declared.toLowerCase();
+  const asDirectoryPrefix = lowerDeclared.endsWith('/') ? lowerDeclared : `${lowerDeclared}/`;
+  return patterns.some((pattern) => {
+    const lowerPattern = pattern.toLowerCase();
+    return lowerDeclared.includes(lowerPattern) || lowerPattern.startsWith(asDirectoryPrefix);
+  });
+}
+
+// ── Declared test command: the allowlist guard 1 and the close's triad share ──────
+//
+// Guard 1 refuses a line this validator rejects, and the close's `planMechanicalChecks` runs the
+// argv it returns. It lives here rather than in `close.ts` so the dependency stays one-way — the
+// close already reads this module for `SECURITY_PATH_PATTERNS`, and pre-launch validation is
+// upstream of the close by definition.
+
+/**
+ * Splits a shell-ish command line into argv, honoring double and single quotes so a test path with
+ * a space survives as ONE argument. Deliberately not a shell: no expansion, no operators — the
+ * declared test command is spawned directly, never through `sh`.
+ */
+function tokenize(commandLine: string): string[] {
+  return [...commandLine.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map(
+    (match) => match[1] ?? match[2] ?? match[3],
+  );
+}
+
+/**
+ * The only binary a task may name in its `Test command:` line. `pnpm` alone, because that IS the
+ * repo's convention (`pnpm --filter <pkg> test …`) and because `npx` is not a test runner but an
+ * arbitrary-package fetch-and-execute: `npx <anything>` in a line a weak model wrote would run code
+ * that is not in this repository at all.
+ */
+const ALLOWED_TEST_BINARIES: readonly string[] = ['pnpm'];
+
+/**
+ * The scripts a task may ask for. Naming `pnpm` was never the permission — `pnpm dlx <package>` is
+ * the same fetch-and-execute `npx` is refused for, and `pnpm add`/`install`/`exec` reach just as far
+ * outside this repository. So the SCRIPT is allowlisted too, and everything else falls out for free:
+ * no rejection list to keep in sync with pnpm's own command set.
+ */
+const ALLOWED_TEST_SCRIPT = /^(?:test|cli:test|test:[\w-]+)$/;
+
+/**
+ * A `--filter` value must be a plain package name. Anchored on a first character that is NOT a dash,
+ * because `pnpm --filter --shell-mode test` otherwise reads as a package called `--shell-mode` and
+ * smuggles a second flag past the check.
+ */
+const PACKAGE_NAME = /^[@\w][\w@./-]*$/;
+
+/**
+ * A `--dir` value must be a RELATIVE path made of ordinary path characters. `packages/cli` is why
+ * the option is accepted at all: it is deliberately not a workspace member (root `CLAUDE.md`, D8),
+ * so `--filter` matches nothing there and `--dir` is the only way to run its tests. Anchored on a
+ * non-dash first character for the same reason `PACKAGE_NAME` is — otherwise a second flag smuggles
+ * itself in as a "directory" — and an absolute path or any `..` segment is refused, because a test
+ * command is only allowed to reach inside the slot it runs in.
+ */
+const RELATIVE_DIR = /^[\w.][\w./-]*$/;
+
+function isSlotRelativeDir(value: string | undefined): value is string {
+  return (
+    Boolean(value) &&
+    RELATIVE_DIR.test(value as string) &&
+    !(value as string).split('/').includes('..')
+  );
+}
+
+/** Anything a shell would interpret. The command is spawned directly, so these can only be an attack or a typo. */
+const SHELL_METACHARACTERS = /[;&|`$<>(){}\\\n]/;
+
+export const TEST_COMMAND_REFUSED = 'test command no permitido';
+
+export type TestCommandResolution =
+  | { kind: 'ok'; command: string; args: string[] }
+  | { kind: 'refused'; reason: string }
+  | { kind: 'absent' };
+
+/**
+ * Validates the `Test command:` line before anything spawns it. The line is free text a person (or
+ * a weak model) typed into a task description, and the close runs it with the dispatcher's own
+ * privileges in a real checkout — so any shell metacharacter is a refusal, never a "best effort"
+ * run, and BOTH the binary and the script it names are allowlisted. The accepted shapes are the
+ * repo's own convention and nothing else:
+ *
+ *   pnpm [--filter <pkg> | --dir <relative-path>] [run] <test | cli:test | test:*> [args…]
+ */
+export function resolveTestCommand(declared: string | null): TestCommandResolution {
+  if (!declared || declared.trim().length === 0) {
+    return { kind: 'absent' };
+  }
+  if (SHELL_METACHARACTERS.test(declared)) {
+    return { kind: 'refused', reason: TEST_COMMAND_REFUSED };
+  }
+  const [command, ...args] = tokenize(declared);
+  if (!command || !ALLOWED_TEST_BINARIES.includes(command)) {
+    return { kind: 'refused', reason: TEST_COMMAND_REFUSED };
+  }
+
+  // Walk the optional prefixes the repo's convention allows — one package selector (`--filter` for
+  // a workspace member, `--dir` for a package that is not one), then `run` — and require whatever
+  // follows them to be an allowlisted test script.
+  let index = 0;
+  if (args[index] === '--filter') {
+    const packageName = args[index + 1];
+    if (!packageName || !PACKAGE_NAME.test(packageName)) {
+      return { kind: 'refused', reason: TEST_COMMAND_REFUSED };
+    }
+    index += 2;
+  } else if (args[index] === '--dir') {
+    if (!isSlotRelativeDir(args[index + 1])) {
+      return { kind: 'refused', reason: TEST_COMMAND_REFUSED };
+    }
+    index += 2;
+  }
+  if (args[index] === 'run') {
+    index += 1;
+  }
+  if (!args[index] || !ALLOWED_TEST_SCRIPT.test(args[index])) {
+    return { kind: 'refused', reason: TEST_COMMAND_REFUSED };
+  }
+
+  return { kind: 'ok', command, args };
+}
+
+// ── Subtask base branch: the ONE place a task's base is named (T-14 → T-15) ──────
+//
+// A subtask branches from, and its close diffs and opens its PR against, its PARENT's branch —
+// never `main` directly (design.md decision (e): the parent integrates to `main` with ONE PR, so
+// `main` never holds half a decomposed change). `taskBaseBranch` names that base; `resolveTaskBase`
+// wraps it with the remote-existence check.
+//
+// The base is no longer DEDUCED from the parent's id alone (T-14's `task/<parentId>` naming) — it
+// is RESOLVED through a three-step chain (T-15, 2026-09-09), because a parent worked in an
+// INTERACTIVE session does not live on `task/<id>` at all: it lives on a conventional-commit branch
+// (`feat/…`, `fix/…`, `refactor/…`), per the root `CLAUDE.md`'s Worktree Gate, and `task/<id>` then
+// never exists — so the old deduction blocked every subtask of such a parent permanently.
+//
+//   1. The parent's OWN declared branch (`Task.declaredBranch`, `task-view.ts`'s
+//      `parseDeclaredBranch` reading its "Branch:" description line — see
+//      `catalyst-backlog/SKILL.md`). Written by the person who created the parent's worktree
+//      branch; nothing here parses a description a second time — `tasksById[task.parentId]` is
+//      handed a task the caller already loaded, and this module only reads the field off it.
+//   2. No declaration → the T-14 convention, `task/<parentId>`, exactly as before.
+//   3. Neither branch exists on the remote → `missing-parent-branch`, naming every remote branch
+//      whose name MENTIONS the parent's id as a whole token (`candidateBranches` below) — never a
+//      plain substring match, since `T-1` is a literal substring of `T-15`, `T-19`, `T-100`, and a
+//      naive match would propose a sibling subtask's branch as if it were the parent's own.
+//
+// `close.ts`'s `resolveBaseBranch`/`resolveBaseRef` call `taskBaseBranch` directly: by the time
+// either runs, `checkParentBranchOnRemote` below has already refused a subtask whose base is
+// missing, so there is nothing left to check. `slots.ts`'s `resolveBranch` calls `resolveTaskBase`
+// instead, because it is the one place that actually runs `git checkout` against the answer and
+// must fail loudly — not silently — if that invariant is ever violated.
+//
+// T-4.1 (2026-09-08) measured what happens without a single shared answer: `slots.ts` fell back to
+// `origin/main` on its own when a subtask's parent branch was not yet on the remote (its own doc
+// comment recorded why — a `checkout` against a missing ref used to take the whole pass down AFTER
+// the slot was already taken), while `close.ts` kept assuming `task/<parentId>` regardless. The
+// worker finished correctly, on `origin/main`, and the close then failed `scope-check-failed`
+// diffing against `origin/task/T-4` — a ref dispatch never created. One frontier run lost to two
+// functions quietly disagreeing. `checkParentBranchOnRemote` removes the REASON `slots.ts`'s
+// fallback existed for — a missing parent branch is now refused before a slot is ever taken — so
+// the fallback is gone rather than kept as a second, divergent answer.
+
+/** The lookup every caller of `taskBaseBranch`/`resolveTaskBase` hands in: the board's task map, or
+ *  the minimal slice of it a test fixture needs — only `declaredBranch` is ever read off an entry. */
+export type DeclaredBranchLookup = Readonly<Record<string, Pick<Task, 'declaredBranch'>>>;
+
+/**
+ * The naming convention: the parent's DECLARED branch when it named one, `task/<parentId>` when it
+ * did not, or `main` for a top-level task. No remote check — see `resolveTaskBase` for that.
+ *
+ * `||`, not `??`: an entry whose `declaredBranch` is `''` reads the same as one that is `null` or
+ * `undefined`. `task-view.ts`'s `parseDeclaredBranch` never actually PRODUCES `''` — an empty or
+ * whitespace-only "Branch:" value already normalizes to `null` there (fix round B1, 2026-09-09;
+ * before that fix, `\s*(.+)` on a blank "Branch:" line silently swallowed the NEXT description line
+ * instead of capturing an empty string, so this `||` was guarding an input that could never arrive).
+ * `||` stays here anyway as the second line of defense for a `DeclaredBranchLookup` entry built by
+ * hand — a test fixture, or any future caller that does not route through the real parser — so this
+ * function cannot be handed an empty string and resolve a base that is itself the empty string.
+ */
+export function taskBaseBranch(
+  task: Pick<Task, 'parentId'>,
+  tasksById: DeclaredBranchLookup,
+): string {
+  if (!task.parentId) {
+    return 'main';
+  }
+  return tasksById[task.parentId]?.declaredBranch || `task/${task.parentId}`;
+}
+
+export type TaskBaseResolution =
+  | { kind: 'ok'; branch: string }
+  | { kind: 'missing-parent-branch'; branch: string; candidates: readonly string[] };
+
+/**
+ * Whether `branchName` mentions `taskId` as a WHOLE token — never a plain substring. `T-1` is a
+ * literal substring of `T-15`, `T-19` and `T-100`, so `String.includes` would offer every one of
+ * those sibling branches as a "candidate" for T-1's missing base. A boundary is anything that is
+ * NOT an identifier character on the left, and on the right anything that is not a digit — with one
+ * exception: a `.` immediately followed by a digit continues a DOTTED subtask id (`T-4.2` names a
+ * DIFFERENT task than `T-4`), so that is not a boundary either. Case-insensitive: this list is
+ * diagnostic only, read by a PERSON deciding which branch is theirs, and a lower-cased rescue
+ * branch (`wip-t-4-rescue`) is exactly the kind of thing worth surfacing to them.
+ */
+function mentionsIdToken(branchName: string, taskId: string): boolean {
+  const escaped = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(?<![A-Za-z0-9])${escaped}(?!\\d)(?!\\.\\d)`, 'i').test(branchName);
+}
+
+/** Every remote branch that mentions `taskId` as a whole token — see `mentionsIdToken`. */
+function candidateBranches(taskId: string, remoteBranches: readonly string[]): readonly string[] {
+  return remoteBranches.filter((branch) => mentionsIdToken(branch, taskId));
+}
+
+/**
+ * `taskBaseBranch` PLUS the remote-existence check. `remoteBranches` is the same live `git branch
+ * -r` list `slots.ts`'s `prepareSlot` and `checkParentBranchOnRemote` below both read — a top-level
+ * task (no parent) is always `ok`, since `main` is assumed to exist; a subtask is `ok` only when the
+ * branch `taskBaseBranch` names is actually on the remote. Otherwise `missing-parent-branch`, with
+ * `candidates` naming every OTHER remote branch that mentions the parent's id, for a person to pick
+ * from — step 3 of the resolution chain (see this file's header comment above).
+ */
+export function resolveTaskBase(
+  task: Pick<Task, 'parentId'>,
+  tasksById: DeclaredBranchLookup,
+  remoteBranches: readonly string[],
+): TaskBaseResolution {
+  const branch = taskBaseBranch(task, tasksById);
+  if (!task.parentId || remoteBranches.includes(branch)) {
+    return { kind: 'ok', branch };
+  }
+  return {
+    kind: 'missing-parent-branch',
+    branch,
+    candidates: candidateBranches(task.parentId, remoteBranches),
+  };
+}
+
+// ── Permission-rule coverage: the primitive guard 1b and the launch both read ──────
+//
+// A frontier worker loads two settings sources on purpose (`--setting-sources user,project`), so
+// every `permissions.allow` rule those files carry reaches it on top of the lane's own list. The
+// launch cancels them with one deny per rule the lane does not grant — and "does not grant" is
+// decided by COVERAGE, not by string inequality, because a deny is coarse: denying
+// `Bash(openspec status:*)` for not being spelled like the lane's `Bash(openspec:*)` would revoke
+// the lane's own grant.
+//
+// The comparison lives HERE for the same reason `resolveTestCommand` does: guard 1b decides the
+// pre-launch refusal and `launch.ts` composes the deny list from the same verdict, so the two
+// cannot disagree, and the dependency stays one-way (`launch.ts` → `guards.ts`).
+
+/** `Bash(git status:*)` → `{ tool: 'Bash', argument: 'git status:*' }`; `Read` → argument `null`. */
+function parseRule(rule: string): { tool: string; argument: string | null } {
+  const match = /^([^()]+)\((.*)\)$/.exec(rule);
+  return match ? { tool: match[1], argument: match[2] } : { tool: rule, argument: null };
+}
+
+/**
+ * Collapses the whitespace inside a permission rule, so `Bash(git  status:*)` and
+ * `Bash(git status:*)` are the same rule to the comparison below. Without it a re-spaced copy of a
+ * granted rule would be emitted as a deny — and that deny would then revoke the grant.
+ */
+export function normalizeRule(rule: string): string {
+  return rule.trim().replace(/\s+/g, ' ');
+}
+
+/**
+ * Whether `rule` combines a mid-rule `*` with a trailing `:*` suffix — the ONE shape measured
+ * (T-7, 2026-09-07, Claude Code 2.1.263, `claude -p` probes with `--setting-sources user` and 0
+ * allow rules, `--permission-mode dontAsk`) to match NOTHING at all: `Bash(mkdir * end:*)` does not
+ * match `mkdir mid end`, while the exact same base spelled either as a bare glob
+ * (`Bash(mkdir * end)`) or with a trailing ` *` (`Bash(mkdir * end *)`) does. A rule shaped like
+ * this is not a narrow grant, it is a silent hole: it reads as coverage in a review and matches
+ * nothing at runtime. `launch.ts`'s `assertNoDeadBashRules` refuses to launch a lane whose shipped
+ * settings carry one, naming it, rather than trusting a rule that grants an illusion.
+ */
+export function isDeadBashRule(rule: string): boolean {
+  const { tool, argument } = parseRule(normalizeRule(rule));
+  if (tool !== 'Bash' || argument === null || !argument.endsWith(':*')) {
+    return false;
+  }
+  return argument.slice(0, -':*'.length).includes('*');
+}
+
+/** The tools whose rule argument is a path glob rather than a command line. */
+const PATH_TOOLS: readonly string[] = ['Read', 'Edit', 'Write', 'Glob', 'Grep'];
+
+/**
+ * The tools whose non-covered scoping refuses a launch instead of being denied: a deny on one of
+ * them does not narrow the worker, it stops it opening files at all.
+ */
+const FILE_TOOLS: readonly string[] = ['Read', 'Edit', 'Write'];
+
+/**
+ * Anything a shell reads as a second command. A rule whose command line carries one is not "the
+ * granted command with arguments" — it is that command AND another one, which on this lane is how a
+ * denied binary would ride in on an allowed prefix. Tested over the whole candidate rather than
+ * only the part after the prefix, because a `*` in the granted rule is greedy and would otherwise
+ * swallow the operator into the match.
+ */
+const RULE_METACHARACTERS = /&&|\|\||\$\(|[;|`\n<>]/;
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The part of a rule argument that must match, with the trailing `:*` / `*` / `**` stripped — and,
+ * for a path rule, with a leading `./` removed on both sides of the comparison. The lane spells its
+ * file scopings `./**` because the cwd is the slot, so without that normalization every
+ * `Edit(<dir>/**)` a settings source carries read as uncovered, and the deny composed for it would
+ * have taken the worker's write access to that directory.
+ */
+function patternBase(tool: string, argument: string): string {
+  const base = argument.replace(/:?\*+$/, '');
+  return PATH_TOOLS.includes(tool) ? base.replace(/^\.\//, '') : base;
+}
+
+/**
+ * A path scoping that leaves the working directory. It is compared separately because the `./`
+ * normalization above turns the lane's `Edit(./**)` into an empty prefix, which would then "cover"
+ * an absolute `Edit(/etc/**)` — the one scoping that is emphatically not inside the slot. `..`
+ * climbs out of it just as effectively, and reads as an ordinary relative glob to a prefix match.
+ */
+function leavesWorkingDirectory(base: string): boolean {
+  return base.startsWith('/') || base.startsWith('~') || base === '..' || base.startsWith('../');
+}
+
+/** The base a rule matches on, with a bare rule (no argument) reading as the widest base of all. */
+function ruleBase(rule: { tool: string; argument: string | null }): string {
+  return rule.argument === null ? '' : patternBase(rule.tool, rule.argument);
+}
+
+/** `grantedBase` as the anchored regex a prefix match uses, with every `*` as a wildcard. */
+function prefixPattern(base: string): RegExp {
+  return new RegExp(`^${base.split('*').map(escapeRegExp).join('.*')}`);
+}
+
+/**
+ * Does `granted` grant everything `candidate` grants? A permission rule matches a PREFIX, so
+ * `Bash(openspec:*)` covers `Bash(openspec status:*)`, and a `*` inside the rule is a wildcard, so
+ * `Bash(pnpm --filter * test)` covers `Bash(pnpm --filter aurora-back test:*)`. A bare tool rule
+ * (`Read`) covers every scoping of that tool and is covered by none of them.
+ *
+ * The granted rule must not itself be `isDeadBashRule` — a mid-rule `*` combined with a trailing
+ * `:*` matches nothing in the real harness (measured T-7), so treating it as coverage here would
+ * approve a launch on a grant that is actually empty. `launch.ts` refuses to build one before this
+ * function is ever asked to compare it.
+ *
+ * A prefix match alone is not coverage for a COMMAND rule: `Bash(git status:*)` matches the string
+ * `git statusfoo`, which is a different command, and `git status && fd .`, which is two — so what
+ * the candidate adds must start at a token boundary and carry no shell operator. A boundary is a
+ * space or a `:` (the pnpm script separator: `pnpm test:hooks` is `test` scoped, not a token called
+ * `test:hooks` for this purpose), and the requirement is already met when the granted base ends at
+ * one itself — `Bash(git *)` matched `git ` before the candidate's own text began.
+ *
+ * This is the "already granted, skip it" direction, and it is deliberately STRICTER than how Claude
+ * Code matches a rule: a false "not covered" costs a deny for a rule the launch would have granted
+ * anyway, while a false "covered" hands the worker surface nobody reviewed. The opposite direction —
+ * "would a deny for this rule revoke that grant?" — must be raw instead: see `denyWouldRevoke`.
+ */
+export function grantCovers(granted: string, candidate: string): boolean {
+  if (normalizeRule(granted) === normalizeRule(candidate)) {
+    return true;
+  }
+  const grantedRule = parseRule(normalizeRule(granted));
+  const candidateRule = parseRule(normalizeRule(candidate));
+  if (grantedRule.tool !== candidateRule.tool) {
+    return false;
+  }
+  if (grantedRule.argument === null) {
+    return true;
+  }
+  if (candidateRule.argument === null) {
+    return false;
+  }
+  const candidateBase = patternBase(candidateRule.tool, candidateRule.argument);
+  const grantedBase = patternBase(grantedRule.tool, grantedRule.argument);
+  if (
+    PATH_TOOLS.includes(grantedRule.tool) &&
+    leavesWorkingDirectory(candidateBase) !== leavesWorkingDirectory(grantedBase)
+  ) {
+    return false;
+  }
+  const match = prefixPattern(grantedBase).exec(candidateBase);
+  if (match === null) {
+    return false;
+  }
+  if (PATH_TOOLS.includes(grantedRule.tool)) {
+    return true;
+  }
+  const remainder = candidateBase.slice(match[0].length);
+  const boundaryConsumed = /[\s:]$/.test(grantedBase);
+  return (
+    !RULE_METACHARACTERS.test(candidateBase) &&
+    (remainder.length === 0 || boundaryConsumed || /^[\s:]/.test(remainder))
+  );
+}
+
+/**
+ * Would a deny for `rule` revoke `grant`? This is how Claude Code actually matches: a RAW prefix,
+ * with `*` as a wildcard, and no opinion about token boundaries or shell operators — a deny is
+ * coarse, which is exactly why it outranks every allow.
+ *
+ * It is the mirror of `grantCovers` and cannot be that function: asking the strict predicate in
+ * this direction made a settings rule BROADER than a grant (`Bash(pnpm test:*)` over the task's own
+ * `Bash(pnpm test:hooks x:*)`) read as unrelated to it, and the launch then emitted it as a deny
+ * that killed the grant. Here the answer must err the other way: a rule that MIGHT revoke a grant
+ * is reported as a conflict for a person to resolve, never denied silently.
+ *
+ * A bare deny (`Edit`) revokes every scoping of that tool. A scoped deny does not revoke a BARE
+ * grant: it narrows it, which is what the file-tool check below decides separately.
+ */
+export function denyWouldRevoke(rule: string, grant: string): boolean {
+  const denyRule = parseRule(normalizeRule(rule));
+  const grantRule = parseRule(normalizeRule(grant));
+  if (denyRule.tool !== grantRule.tool) {
+    return false;
+  }
+  if (denyRule.argument === null) {
+    return true;
+  }
+  if (grantRule.argument === null) {
+    return false;
+  }
+  return prefixPattern(patternBase(denyRule.tool, denyRule.argument)).test(
+    patternBase(grantRule.tool, grantRule.argument),
+  );
+}
+
+/**
+ * The loaded allow rule that has no safe answer, or `null` when every rule can be either skipped
+ * (the granted list already covers it) or denied.
+ *
+ * Three shapes qualify. A rule BROADER than one the launch grants — the project file's
+ * `Bash(pnpm test:hooks:*)` over a task whose declared test command is `pnpm test:hooks <file>` — is
+ * either denied, revoking the task's own test grant, or kept, handing the worker a runner that
+ * executes files out of a tree it can write to. A non-covered scoping of a FILE tool that reaches
+ * INSIDE the slot would be denied into a worker that cannot read or write there at all — while one
+ * that only reaches outside it (`/etc/**`, `~/notes/**`, `../**`) is denied like any other rule,
+ * which is the whole point of the subtraction. And a USER-file path rule with no scoping of its own
+ * (`Edit`, `Edit(**)`, `Edit(./**)`) is relative to the home directory, not to the slot: the lane
+ * has no way to grant that, so the apparent coverage by its slot-scoped `Edit(./**)` is an artefact
+ * of the `./` normalization, not a real one.
+ *
+ * None of the three is a choice to make unattended, so the task is blocked with the rules named.
+ */
+export type PermissionConflict =
+  { kind: 'broader'; rule: string; granted: string } | { kind: 'file-tool'; rule: string };
+
+/**
+ * Would a deny for this file-tool rule reach inside the slot? A bare rule and an unscoped glob take
+ * the tool away wholesale; a relative glob narrows a directory the worker may well be working in.
+ */
+function denyReachesInsideSlot(rule: { tool: string; argument: string | null }): boolean {
+  const base = ruleBase(rule);
+  return base.length === 0 || !leavesWorkingDirectory(base);
+}
+
+export function findPermissionConflict(
+  settingsAllow: readonly SettingsAllowRule[],
+  grantedAllow: readonly string[],
+): PermissionConflict | null {
+  const granted = grantedAllow.map(normalizeRule);
+  const grantsToolUnscoped = (tool: string): boolean =>
+    granted.some((grant) => {
+      const parsed = parseRule(grant);
+      return parsed.tool === tool && parsed.argument === null;
+    });
+
+  for (const entry of settingsAllow) {
+    const rule = normalizeRule(entry.rule);
+    const parsed = parseRule(rule);
+    // Checked BEFORE coverage on purpose: coverage is what gets this wrong. Only a BARE lane grant
+    // reaches outside the slot, so only a bare grant can cover a home-relative rule.
+    if (
+      entry.source === 'user' &&
+      PATH_TOOLS.includes(parsed.tool) &&
+      ruleBase(parsed).length === 0
+    ) {
+      if (!grantsToolUnscoped(parsed.tool)) {
+        return { kind: 'file-tool', rule };
+      }
+    }
+    if (granted.some((grant) => grantCovers(grant, rule))) {
+      continue;
+    }
+    const revoked = granted.find((grant) => denyWouldRevoke(rule, grant));
+    if (revoked !== undefined) {
+      return { kind: 'broader', rule, granted: revoked };
+    }
+    if (FILE_TOOLS.includes(parsed.tool) && denyReachesInsideSlot(parsed)) {
+      return { kind: 'file-tool', rule };
+    }
+  }
+  return null;
+}
+
+/** The conflict as one English sentence, for the launch's last-resort invariant throw. */
+export function describePermissionConflict(conflict: PermissionConflict): string {
+  return conflict.kind === 'broader'
+    ? `the settings allow rule ${conflict.rule} is broader than ${conflict.granted}, which this launch grants; ` +
+        'a deny for it would revoke that grant. Narrow the settings rule or the task test command.'
+    : `the settings allow rule ${conflict.rule} scopes a file tool this launch does not cover; ` +
+        'a deny for it would leave the worker unable to open a file with that tool. Narrow the settings rule ' +
+        "or widen the lane's allow list.";
+}
+
+// ── Result type ────────────────────────────────────────────────────────────────
+
+export const GUARD_BLOCK_REASON = {
+  MISSING_TRIAGE: 'missing-triage',
+  TIER_LANE_MISMATCH: 'tier-lane-mismatch',
+  MISSING_FILES_TO_TOUCH: 'missing-files-to-touch',
+  MISSING_TEST_COMMAND: 'missing-test-command',
+  REFUSED_TEST_COMMAND: 'refused-test-command',
+  PERMISSION_CONFLICT: 'permission-conflict',
+  COMPLEX_ON_LOCAL: 'complex-on-local',
+  MISSING_PARENT_BRANCH: 'missing-parent-branch',
+  UNKNOWN_DEPENDENCY: 'unknown-dependency',
+  SECURITY_PATH_ON_LOCAL: 'security-path-on-local',
+  ATTEMPTS_EXHAUSTED: 'attempts-exhausted',
+  SLOT_EXECUTED_PATH: 'slot-executed-path',
+} as const;
+
+export type GuardBlockReason = (typeof GUARD_BLOCK_REASON)[keyof typeof GUARD_BLOCK_REASON];
+
+export const GUARD_WAIT_REASON = {
+  DEPENDENCY_NOT_DONE: 'dependency-not-done',
+  NO_FREE_SLOT: 'no-free-slot',
+  /** This task's OWN slot still holds work that never reached the remote — see guard 6. */
+  PUSH_PENDING: 'push-pending',
+  /**
+   * Guard 4b: this task's PARENT is absent from an INCOMPLETE board read (`Board.complete === false`
+   * and `board.tasksById[task.parentId]` undefined) — the parent's real base branch could not be
+   * determined THIS pass, not "the parent has none". Re-evaluated next pass once a complete read
+   * names it, same as `dependency-not-done`.
+   */
+  PARENT_READ_INCOMPLETE: 'parent-read-incomplete',
+} as const;
+
+export type GuardWaitReason = (typeof GUARD_WAIT_REASON)[keyof typeof GUARD_WAIT_REASON];
+
+export type GuardResult =
+  | { kind: 'block'; reason: GuardBlockReason; comment: string }
+  | { kind: 'wait'; reason: GuardWaitReason }
+  | { kind: 'launch' };
+
+const block = (reason: GuardBlockReason, comment: string): GuardResult => ({
+  kind: 'block',
+  reason,
+  comment,
+});
+
+const wait = (reason: GuardWaitReason): GuardResult => ({ kind: 'wait', reason });
+
+// ── Guards ──────────────────────────────────────────────────────────────────────
+
+const MISSING_TRIAGE_COMMENT = 'Bloqueado: sin triage completo (falta tier, lane o path).';
+
+/**
+ * `tier:complex` already has its own dedicated check (guard 2, `checkComplexOnLocal`) with its own
+ * established reason and message — this one is scoped to `tier:medium` on purpose so it never
+ * shadows that guard's `complex-on-local` verdict for the complex+local combination.
+ */
+function tierLaneMismatchComment(tier: Tier): string {
+  return (
+    `Bloqueado: lane:local solo admite tier:minor (design.md decision (n) / catalyst-backlog/SKILL.md ` +
+    `§2); esta tarea declara tier:${tier}, no puede ejecutarse en local.`
+  );
+}
+
+const MISSING_TEST_COMMAND_COMMENT =
+  'Bloqueado: la tarea no declara la línea "Test command:" en su descripción — sin ella el close no ' +
+  'puede probar nada, y el criterio "scoped tests pass" de la Definition of Done se quedaría sin ' +
+  'evidencia. Declara el comando con el que se verifica el cambio (p. ej. "pnpm --filter aurora-back test").';
+
+const MISSING_FILES_TO_TOUCH_COMMENT =
+  'Bloqueado: una tarea lane:local necesita la línea "Files to touch:" en su descripción — es la ' +
+  'lista contra la que el close verifica el diff real y la que inspecciona el guard de rutas de ' +
+  'seguridad. Sin ella no hay alcance declarado que comprobar.';
+
+/**
+ * Guard 1: `tier`/`lane`/`path` triage must all be present, a `lane:local` task must declare its
+ * files, and EVERY task must declare its test command. An empty allowlist is not "no restriction":
+ * the close's local-lane scope check would then report EVERY changed file as undeclared, so the
+ * attempt is doomed before it starts — and the security-path guard below would have nothing to
+ * inspect. A missing test command is refused here rather than downstream because the close's
+ * "scoped tests pass" DoD item can only be ticked by a test that actually ran: without a command
+ * the attempt would reach the pre-PR gate with that item unticked and fail there, having burned a
+ * whole run to discover a line a person could have written in five seconds.
+ */
+function refusedTestCommandComment(declared: string, reason: string): string {
+  return (
+    `Bloqueado: el "Test command:" declarado no pasa la allowlist (${reason}): "${declared}". ` +
+    'Se admite solo la convención del repo — pnpm [--filter <pkg> | --dir <ruta>] [run] <test | cli:test | test:*> ' +
+    '[args…] — sin metacaracteres de shell. Corrige la línea y vuelve a encolar.'
+  );
+}
+
+function checkTriage(task: Task): GuardResult | null {
+  if (!task.tier || !task.lane || !task.path) {
+    return block(GUARD_BLOCK_REASON.MISSING_TRIAGE, MISSING_TRIAGE_COMMENT);
+  }
+  // T-6 measured this hole open: `worker-edit.ts --subtask`'s own label validator only ever
+  // refused tier:complex on lane:local, so a tier:medium subtask reached the board, guard 1 let it
+  // through, and `resolveLane` only threw LATER — after a slot was already taken
+  // (`dispatch-failed`). tier:complex is excluded here on purpose: it already has its own guard
+  // (guard 2, `checkComplexOnLocal`) with its own established reason, and this check runs first.
+  if (task.lane === 'local' && task.tier === TIER.MEDIUM) {
+    return block(GUARD_BLOCK_REASON.TIER_LANE_MISMATCH, tierLaneMismatchComment(task.tier));
+  }
+  if (task.lane === 'local' && task.filesToTouch.length === 0) {
+    return block(GUARD_BLOCK_REASON.MISSING_FILES_TO_TOUCH, MISSING_FILES_TO_TOUCH_COMMENT);
+  }
+  if (!task.testCommand) {
+    return block(GUARD_BLOCK_REASON.MISSING_TEST_COMMAND, MISSING_TEST_COMMAND_COMMENT);
+  }
+  // A line the allowlist refuses is worse than a missing one: it read as present here, so the whole
+  // attempt ran and the close failed the triad on `refusal` at the very end. Same validator, same
+  // verdict, paid before anything is spawned.
+  const resolved = resolveTestCommand(task.testCommand);
+  if (resolved.kind === 'refused') {
+    return block(
+      GUARD_BLOCK_REASON.REFUSED_TEST_COMMAND,
+      refusedTestCommandComment(task.testCommand, resolved.reason),
+    );
+  }
+  return null;
+}
+
+function slotExecutedPathComment(file: string): string {
+  return (
+    `Bloqueado: la tarea declara "${file}", que alcanza ficheros que se ejecutan dentro del slot ` +
+    'durante el intento o el cierre (design.md — split-dispatcher-forbidden-paths, decisión 1: la ' +
+    'lista no está en función de su severidad sino de si algo los ejecuta). Ese cambio necesita una ' +
+    'sesión interactiva — quita la entrada de "Files to touch:" y haz esa parte del trabajo a mano.'
+  );
+}
+
+/**
+ * Guard 1c: on BOTH lanes, a task may not DECLARE a file on the hard list (`SLOT_EXECUTED_PATHS`) —
+ * that file can never be admitted, so no later guard could make it actionable (no free slot to wait
+ * for, no parent branch to push). Modeled on `checkSecurityPathOnLocal`: reads `task.filesToTouch`,
+ * matches case-insensitively, blocks with its own reason and a comment naming the offending file.
+ *
+ * Covers `SLOT_EXECUTED_BASENAMES` too, by basename at any depth — `checkScope` refuses the
+ * instruction file on both lanes, so declaring it can never be dispatched either. The basename
+ * half has no directory-containment direction: `- frontend/` does not resolve to
+ * `frontend/CLAUDE.md` without reading the filesystem, and this module is pure. Such a declaration
+ * is still refused at close, where the real diff names the file.
+ *
+ * It does NOT block on a SOFT-list declaration (`HUMAN_REVIEW_PATHS`) —
+ * that is admissible work whose pull request gets marked for human review instead
+ * (`close.ts`'s `checkScope`). And it inspects DECLARATIONS only, so a task that declares nothing
+ * passes it — the close's own scope verification over the REAL diff remains the enforcing check on
+ * both lanes; this guard exists to save a worker the four measured attempts already paid for
+ * discovering the same refusal at close.
+ *
+ * PLACED immediately after guard 1 (`checkTriage`) and before everything else (design.md decision
+ * 4): after guard 1, so a `lane:local` task with no `Files to touch:` at all reports THAT missing
+ * line, not a vacuous pass of this check; before everything else, because a task declaring a
+ * hard-list file can never be dispatched at all, and every later guard's verdict would be either
+ * unactionable or misleading for it.
+ */
+function checkDeclaredSlotExecutedPath(task: Task): GuardResult | null {
+  const offending = task.filesToTouch.find(
+    (file) =>
+      declarationReachesPathPattern(file, SLOT_EXECUTED_PATHS) ||
+      matchesBasename(file, SLOT_EXECUTED_BASENAMES),
+  );
+  return offending
+    ? block(GUARD_BLOCK_REASON.SLOT_EXECUTED_PATH, slotExecutedPathComment(offending))
+    : null;
+}
+
+/**
+ * The two permission lists guard 1b compares, loaded by the CALLER (this module stays pure): every
+ * `permissions.allow` rule this worker's settings sources contribute, and the whole surface the
+ * launch would grant it — the lane's allow list plus the per-task rules (the `worker-edit.ts`
+ * wrapper and the validated test command).
+ *
+ * Composed on BOTH lanes now: they differ in WHICH sources they load (`user` locally,
+ * `user,project` on the frontier lane), not in whether a loaded rule needs cancelling. `null` only
+ * when the task carries no usable lane at all, which guard 1 blocks on its own.
+ */
+export interface PermissionComposition {
+  settingsAllow: readonly SettingsAllowRule[];
+  grantedAllow: readonly string[];
+}
+
+function permissionConflictComment(conflict: PermissionConflict): string {
+  return conflict.kind === 'broader'
+    ? `Bloqueado: conflicto de permisos — la regla de settings ${conflict.rule} es más amplia que ` +
+        `${conflict.granted}, que el launch concede. Denegarla revocaría esa concesión y no denegarla daría al ` +
+        'worker una regla más amplia de la revisada. La salida habitual es declarar un "Test command:" que la ' +
+        'lista del proyecto no cubra — la forma "pnpm --filter <pkg> test <fichero>" — en vez de ampliar el ' +
+        'allowlist del lane, que vale para todas las tareas y no solo para esta.'
+    : `Bloqueado: conflicto de permisos — la regla de settings ${conflict.rule} acota una herramienta de ` +
+        'ficheros dentro del slot y el allowlist del lane no la cubre. Denegarla dejaría al worker sin poder ' +
+        'abrir ficheros con ella. Estrecha la regla de settings o amplía el allowlist del lane.';
+}
+
+/**
+ * Guard 1b: on EITHER lane, no loaded settings rule may be broader than a rule this launch grants
+ * (nor scope a file tool the lane does not cover). It ran inside `buildLaunch` before, which is
+ * after the slot is acquired and the attempt directory is created — so a conflict only a person can
+ * resolve burned a worktree slot and an attempt to report itself. Nothing about it depends on the
+ * slot, so it is decided here, where a block costs nothing.
+ *
+ * It was frontier-only while the local lane was believed to load no settings source at all. That
+ * reading was measured wrong (T-5, 2026-09-07): `--bare` skips hooks, LSP, plugin sync,
+ * auto-memory, keychain reads and `CLAUDE.md` discovery — not settings files. The local lane now
+ * names its source (`--setting-sources user`) and composes the same deny list, so the same overlap
+ * with no safe answer is reachable on it.
+ */
+function checkPermissionComposition(
+  task: Task,
+  permissions: PermissionComposition | null,
+): GuardResult | null {
+  if (permissions === null) {
+    return null;
+  }
+  const conflict = findPermissionConflict(permissions.settingsAllow, permissions.grantedAllow);
+  return conflict === null
+    ? null
+    : block(GUARD_BLOCK_REASON.PERMISSION_CONFLICT, permissionConflictComment(conflict));
+}
+
+/** Guard 2: Complex never dispatches to the local lane. */
+function checkComplexOnLocal(task: Task): GuardResult | null {
+  if (task.tier === 'complex' && task.lane === 'local') {
+    return block(
+      GUARD_BLOCK_REASON.COMPLEX_ON_LOCAL,
+      'Bloqueado: tier:complex requiere lane:frontier, no puede ejecutarse en local.',
+    );
+  }
+  return null;
+}
+
+/**
+ * Guard 3: every declared dependency must resolve on the board AND be `Done`. An id the board
+ * cannot resolve is a hard block ("dependencia desconocida") — it can never become Done on its
+ * own, so waiting for the next pass would loop forever. A resolvable-but-unfinished dependency is
+ * a wait: the next reconciler pass re-evaluates once it finishes.
+ */
+function checkDependencies(task: Task, board: Board): GuardResult | null {
+  for (const dependencyId of task.dependsOn) {
+    const dependency = board.tasksById[dependencyId];
+    if (!dependency) {
+      return block(
+        GUARD_BLOCK_REASON.UNKNOWN_DEPENDENCY,
+        `Bloqueado: dependencia desconocida (${dependencyId} no existe en el tablero).`,
+      );
+    }
+    if (dependency.status !== TASK_STATUS.DONE) {
+      return wait(GUARD_WAIT_REASON.DEPENDENCY_NOT_DONE);
+    }
+  }
+  return null;
+}
+
+/** Guard 4: a local-lane task may not declare a file under a security path. */
+function checkSecurityPathOnLocal(task: Task): GuardResult | null {
+  if (task.lane === 'local' && declaresSecurityPath(task.filesToTouch)) {
+    return block(
+      GUARD_BLOCK_REASON.SECURITY_PATH_ON_LOCAL,
+      'Bloqueado: la tarea declara un fichero bajo una ruta de seguridad; no puede ir a lane:local.',
+    );
+  }
+  return null;
+}
+
+function missingParentBranchComment(
+  branch: string,
+  parentId: string,
+  candidates: readonly string[],
+): string {
+  const candidateLine =
+    candidates.length > 0
+      ? `Ramas remotas que mencionan a ${parentId} y podrían ser la correcta: ${candidates.join(', ')}.`
+      : `Ninguna rama remota menciona a ${parentId} tampoco.`;
+  return (
+    `Bloqueado: el padre de esta subtarea (${parentId}) no tiene rama publicada en el remoto ` +
+    `(${branch} no existe en origin). El close diferencia el trabajo y abre el PR contra la rama del ` +
+    'padre (design.md decisión (e)) — sin ella, el dispatch fallaría después de ya haber tomado un ' +
+    `slot. ${candidateLine} Declara la rama real del padre con una línea "Branch: <nombre>" en su ` +
+    `descripción (catalyst-backlog/SKILL.md), o crea y empuja ${branch} — la convención por defecto — ` +
+    'y vuelve a encolar esta subtarea.'
+  );
+}
+
+/**
+ * Guard 4b: a subtask's parent branch must exist on the remote before dispatch ever takes a slot.
+ * `resolveTaskBase` is the single answer both this guard and `slots.ts`'s `resolveBranch` consult —
+ * see that function's doc comment for the T-4.1 measurement this guard exists to prevent from
+ * recurring: a whole frontier worker run wasted on work that finished correctly and only failed
+ * because the close measured it against a branch dispatch never actually used.
+ *
+ * A top-level task (no `parentId`) never reaches the remote check at all — `resolveTaskBase` is
+ * unconditionally `ok` for it — so `remoteBranches` costs nothing for the common case.
+ *
+ * PLACED AFTER `checkSecurityPathOnLocal` (guard 4) and BEFORE `checkAttemptsExhausted` (guard 5),
+ * deliberately, not where it first landed (right after guard 2). Two reasons, per the same
+ * ordering discipline `checkPermissionComposition`'s doc comment above states for guard 1b:
+ *
+ *   - The security signal must never be masked. A `lane:local` subtask that BOTH declares a file
+ *     under `SECURITY_PATH_PATTERNS` AND has an unpushed parent branch has to report
+ *     `security-path-on-local` — the refusal a person cannot work around — not
+ *     `missing-parent-branch`, which reads as actionable ("push the branch") and would send that
+ *     person to fix a branch, re-queue, and only THEN discover the real, unfixable-by-them refusal.
+ *     Reporting the security gate first costs nothing: pushing the parent branch never changes
+ *     whether the task declares a security path.
+ *   - Guard 6's `push-pending` (a WAIT — the one outcome that explains why re-queueing changes
+ *     nothing until the maintenance pass's push retry succeeds) must stay a wait, not become a
+ *     terminal block underneath a guard that runs earlier. This guard sitting after guard 4 and
+ *     before guard 5/6 keeps that ordering intact; it never reaches guard 6's slot-capacity checks
+ *     until its own condition has already passed.
+ *
+ * `push-pending` and `missing-parent-branch` CAN still both apply to the same task at once (this
+ * task's OWN unpushed work, from a PRIOR attempt, sitting in a held slot — guard 6 — while its
+ * PARENT's branch is separately missing — this guard, which runs first since it is earlier in the
+ * chain). That overlap is acceptable and left as is: both conditions need a person to resolve, and
+ * the maintenance sweep retries the push independently of whatever this guard reports meanwhile.
+ *
+ * Fix round B4 (2026-09-09): before T-15's declared-branch chain, this guard never consulted the
+ * board at all — `task/<parentId>` was a pure deduction from the id, so nothing here could be
+ * wrong about a task the board failed to read. T-15 made this guard read `board.tasksById` for the
+ * parent's `declaredBranch`, and that IS something a transient read failure can get wrong:
+ * `dispatch.ts`'s `loadBoard` drops a task whose `backlog task view` threw and reports the whole
+ * read `complete: false`, and `tasksById[parentId]` is `undefined` in EXACTLY that case too — not
+ * only when the parent genuinely declares nothing. Blocking on the deduced fallback then would
+ * instruct a person to push a branch that likely already exists. So the FIRST thing this guard
+ * checks is narrower than "was the board complete": only when the board is incomplete AND this
+ * task's own parent id is unresolved does it wait; a task whose parent WAS read, on an otherwise
+ * incomplete board (some unrelated task's view failed), resolves exactly as it would on a complete
+ * one.
+ */
+function checkParentBranchOnRemote(
+  task: Task,
+  board: Board,
+  remoteBranches: readonly string[],
+): GuardResult | null {
+  if (task.parentId && board.complete === false && !(task.parentId in board.tasksById)) {
+    return wait(GUARD_WAIT_REASON.PARENT_READ_INCOMPLETE);
+  }
+  const resolution = resolveTaskBase(task, board.tasksById, remoteBranches);
+  if (resolution.kind === 'missing-parent-branch') {
+    return block(
+      GUARD_BLOCK_REASON.MISSING_PARENT_BRANCH,
+      missingParentBranchComment(
+        resolution.branch,
+        task.parentId as string,
+        resolution.candidates,
+      ),
+    );
+  }
+  return null;
+}
+
+/** Guard 5: dispatch attempts are capped at `lanes.json`'s `attempts`. */
+function checkAttemptsExhausted(task: Task, limits: DispatchLimits): GuardResult | null {
+  if (task.attempts >= limits.maxAttempts) {
+    return block(
+      GUARD_BLOCK_REASON.ATTEMPTS_EXHAUSTED,
+      `Bloqueado: se agotaron los ${limits.maxAttempts} intentos de dispatch.`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Guard 6: a free slot must exist for the task's lane, respecting the lane's `maxParallel`.
+ *
+ * A slot still holding THIS task's unpushed work is reported apart from a plain capacity wait: both
+ * leave the task `Queued`, but only `push-pending` says why re-queueing changes nothing until the
+ * maintenance pass's push retry succeeds.
+ */
+function checkFreeSlot(
+  task: Task,
+  slots: SlotRegistry,
+  limits: DispatchLimits,
+): GuardResult | null {
+  const lane = task.lane;
+  if (!lane) {
+    // Unreachable in practice: guard 1 already blocks a missing lane. Guarded here only so this
+    // function's own type stays sound without a non-null assertion.
+    return block(GUARD_BLOCK_REASON.MISSING_TRIAGE, MISSING_TRIAGE_COMMENT);
+  }
+
+  if (slots.slots.some((slot) => slot.taskId === task.id && slot.heldForRecovery)) {
+    return wait(GUARD_WAIT_REASON.PUSH_PENDING);
+  }
+
+  const busyCount = slots.slots.filter((slot) => slot.lane === lane && slot.taskId !== null).length;
+  if (busyCount >= limits.capacity[lane]) {
+    return wait(GUARD_WAIT_REASON.NO_FREE_SLOT);
+  }
+  return null;
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+/**
+ * Evaluates the nine dispatch guards — the original six, plus 1b, 1c and 4b, added after the fact
+ * (see their own doc comments) — in the fixed order the spec defines. Each guard returns `null` to
+ * fall through to the next one, or a terminal `GuardResult` that short-circuits the rest. Reaching
+ * the end with every guard falling through means the task is clear to launch.
+ *
+ * `remoteBranches` has NO default (T-14 fix round, 2026-09-08). It used to default to `[]`, on the
+ * reasoning that an empty list "costs nothing" for a task with no parent — true, but irrelevant: a
+ * caller that DROPS the argument entirely for a task that DOES have a parent gets the same `[]`,
+ * silently, and guard 4b then blocks that subtask with a message telling a person to push a branch
+ * that may already be on the remote. Every existing test fixture happened to use a task with no
+ * `parentId`, so that regression passed the whole suite at 963/963 — proven by deleting the call
+ * argument at the one production call site and re-running it. Every caller must now pass a live
+ * list explicitly, `[]` included for one with genuinely none in hand.
+ *
+ * `limits` and `permissions` lost their defaults in the same change, not because either one was
+ * measured unsafe, but because TypeScript refuses a required parameter after an optional one
+ * (TS1016) — `remoteBranches` becoming required forces every parameter after it, and the two before
+ * it, into the same shape. `tsx` strips types without checking them (the same gap `resolveTaskBase`
+ * hit in `slots.ts`, see F3 in the T-14 fix round), so this would otherwise be exactly as invisible
+ * as the bug being fixed. Every call site already passes real values for both — `DEFAULT_DISPATCH_LIMITS`
+ * and `null` are still the right values to reach for, they are simply no longer implicit.
+ */
+export function evaluateGuards(
+  task: Task,
+  board: Board,
+  slots: SlotRegistry,
+  limits: DispatchLimits,
+  permissions: PermissionComposition | null,
+  remoteBranches: readonly string[],
+): GuardResult {
+  return (
+    checkTriage(task) ??
+    // Guard 1c runs directly after guard 1 and before everything else (design.md decision 4): a
+    // task declaring a hard-list file can never be dispatched at all, so no later guard's verdict —
+    // a free-slot wait, a parent-branch push — would be anything but misleading for it.
+    checkDeclaredSlotExecutedPath(task) ??
+    // After the triage checks on purpose: the granted list the caller composed includes the rule for
+    // the task's declared test command, so a line the allowlist refuses must be reported as that
+    // refusal rather than as whatever the (absent) rule fails to conflict with.
+    checkPermissionComposition(task, permissions) ??
+    checkComplexOnLocal(task) ??
+    checkDependencies(task, board) ??
+    // Guard 4b runs AFTER security (guard 4) and BEFORE attempts/free-slot (guards 5/6) — see its
+    // own doc comment for why: the security refusal must never be masked by an actionable-looking
+    // "push a branch" message, and guard 6's push-pending wait must stay reachable as a wait.
+    checkSecurityPathOnLocal(task) ??
+    checkParentBranchOnRemote(task, board, remoteBranches) ??
+    checkAttemptsExhausted(task, limits) ??
+    checkFreeSlot(task, slots, limits) ?? { kind: 'launch' }
+  );
+}