@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -1,16 +1,16 @@
 /**
- * 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).
+ * guards.ts — the twelve dispatch guards over a selected `Queued` task (the original six, plus
+ * guards 0, 1b, 1c, 1d, 1e 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
+ * Implements `specs/backlog-task-dispatcher/spec.md` — "Twelve 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
+ * cause and a user-facing Spanish comment, since the board is in Spanish). The twelve 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`).
  *
@@ -19,7 +19,7 @@
  * 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:
+ * by definition. The five 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
@@ -30,8 +30,14 @@
  *   - `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.
+ *   - `CLAUDE_DIR_SEGMENTS` (T-44) — read by guard 1d ONLY, never by `checkScope`. There is no real
+ *     diff for `checkScope` to check it against: `--permission-mode dontAsk` denies the write
+ *     outright, on EITHER lane, so a `.claude` path a task did not think to declare can never reach
+ *     the close as a changed file in the first place — this list exists purely to save a worker the
+ *     wasted attempt of discovering that refusal after a slot is already spent.
  */
 import {
+  MODE,
   TASK_STATUS,
   TIER,
   type Board,
@@ -139,8 +145,9 @@ export const SLOT_EXECUTED_PATHS: readonly string[] = [
   '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.
+  // Disjoint from the supervised-only `scripts/backlog/` entry, and both must stay so: these two
+  // directories are the parts of `scripts/` the close actually SPAWNS during the attempt — a
+  // different cause from `scripts/backlog/`'s own (see `SUPERVISED_ONLY_PATHS`'s doc comment).
   'scripts/packager/',
   'scripts/harness-rules/',
 ];
@@ -174,17 +181,16 @@ 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):
+ * What "soft" means here (T-31 round 2 — the first pass of this split certified this entry as
+ * "inert during the attempt", and that certification is 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
+ *     environment. `ALLOWED_TEST_SCRIPT` admits `cli:test`/`--dir packages/cli`, which spawns the
+ *     SLOT's own copy of the generator's test suite. 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
@@ -192,27 +198,124 @@ export const SLOT_EXECUTED_BASENAMES: readonly string[] = ['CLAUDE.md'];
  *     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.
+ * What justifies the classification is narrower, and does hold: `packages/cli/` is never read as
+ * INSTRUCTIONS by any process, and the generator itself is never invoked by the close at all — its
+ * MIRROR output (`packages/cli/src/templates/{backend,frontend,monorepo}/`, NOT the hand-written
+ * `packages/cli/src/templates/codegen/`) is the separate, still-refused case — see `close.ts`'s
+ * `MIRROR_OUTPUT_PREFIXES` and its own doc comment. So the reachable outcome of editing it is a
+ * test run that behaves differently, which costs the attempt — and is exactly what a person reads
+ * the marked pull request for.
  *
  * 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`.
+ * request at all (that plan has no `open-pr` step): the `Blocked` comment names this file instead
+ * — see `close.ts`'s `BlockDetails.humanReviewFiles`.
+ */
+export const HUMAN_REVIEW_PATHS: readonly string[] = ['packages/cli/'];
+
+/**
+ * HARD, for a reason ORTHOGONAL to every list above: not because something inside the slot
+ * executes or reads the file, but because the harness itself refuses the write outright. A
+ * dispatched worker runs under `--permission-mode dontAsk` (`launch.ts`). Under that mode, an
+ * Edit/Write on ANY path carrying a `.claude/` segment is DENIED with `decision_reason_type:
+ * mode`, under EVERY permission rule shape tried: an `Edit(./**)`-style relative glob, a bare
+ * `Edit(**)`, a `.claude/`-scoped double-star glob at the root and nested under `skills`, the
+ * exact relative path, and the exact absolute path — measured 2026-09-10 with `claude -p` probes
+ * on a temporary repo. Two controls PASS with the relative glob on the same run
+ * (`sub/plain/a.md`, `sub/.hidden/a.md`), so the trigger is the NAME `.claude`, not "hidden
+ * directory" or "outside a lane's grant" — a lane's own `.claude/` allowances
+ * (`frontier.settings.json`'s `Edit`/`Write` on `.claude/hooks/`, `.claude/scripts/` and the two
+ * settings files — see the README's "Lane profiles") are exactly as denied as anything else under
+ * `.claude/`. Real-world evidence: `.backlog/.dispatch/T-41/intento-1/stream.jsonl` holds
+ * three Edit/Write denials on `frontend/.claude/skills/catalyst-form-composer-auditor/SKILL.md`
+ * and one successful Edit on `frontend/src/main.ts`, in the same run with the same allow list.
+ *
+ * Consequently: no lane settings change can fix this — a task whose work reaches a `.claude/`
+ * path can only be done in an interactive session. `checkDeclaredClaudeDirPath` (guard 1d) refuses
+ * a task that DECLARES one before a slot is ever taken, mirroring guard 1c
+ * (`checkDeclaredSlotExecutedPath`) above in shape — a list, a check function, a block reason, a
+ * comment builder — but not in cause: guard 1c blocks because the close EXECUTES or READS the
+ * file, this blocks because the harness never lets the write happen at all, on EITHER lane.
+ *
+ * Matched by PATH SEGMENT, not by substring — `matchesPathSegment` below, a sibling of
+ * `matchesBasename` split the same way, generalized from "the last component" to "any component".
+ * `declarationReachesPathPattern` (guard 1c's matcher) was measured wrong for this list (T-44
+ * round 2): its substring direction (`declared.includes('.claude/')`) requires the trailing slash,
+ * so a nested directory declared WITHOUT one — `frontend/.claude`, the exact shape T-41 used —
+ * matched neither direction and sailed through; and the same substring direction produces a false
+ * POSITIVE on `notes.claude/file.md`, which carries no `.claude` segment at all. A segment
+ * comparison has neither failure mode: split the declaration on `/` and compare each component
+ * whole, so `frontend/.claude`, `frontend/.claude/skills` and `.claude` all reach `.claude`
+ * (root-level or nested, with or without a trailing slash), while `notes.claude/` and
+ * `my.claude-notes/` do not (`.claude` is not one of their components). The entry itself carries no
+ * trailing slash for the same reason — it names a SEGMENT, not a path prefix.
  */
-export const HUMAN_REVIEW_PATHS: readonly string[] = ['scripts/backlog/', 'packages/cli/'];
+export const CLAUDE_DIR_SEGMENTS: readonly string[] = ['.claude'];
+
+/**
+ * HARD, for a reason ORTHOGONAL to every other list here: nothing inside the slot executes these
+ * files, and the harness does not refuse the write either. They are refused because the DECISION is
+ * architectural, and an architectural decision needs a person while it is being made, not a
+ * reviewer once it exists.
+ *
+ * `packages/core-back/` and `packages/core-front/` are the framework both applications compile
+ * against. Widening a decorator or a port there changes every consumer at once, and no test inside
+ * the changed package can show that. By the time such a change reaches a marked pull request its
+ * shape is already settled, and the reviewer's only moves are accept it or throw a whole attempt
+ * away — which is why the SOFT list (`HUMAN_REVIEW_PATHS`, admitted and marked) is the wrong
+ * instrument here even though it looks close.
+ *
+ * `scripts/backlog/` is the dispatcher's own machinery — the guards, the close and the launch every
+ * task, including this one, is judged by. On the "does anything execute it" question it reads
+ * exactly like the two packages above: the dispatcher runs as `tsx scripts/backlog/dispatch.ts`
+ * (`package.json`'s `backlog:dispatch` script) from the MAIN checkout, never from a slot, and
+ * `workerEditCommand` resolves the board wrapper against the main checkout too. What makes it
+ * architectural is different: a change here alters the machinery every LATER task is judged by, and
+ * it ships to every scaffolded application (`scripts/packager/monorepo.mjs`), where no solution
+ * task has any business touching it at all. By the time such a change is a marked pull request its
+ * shape is already settled, the same problem the framework packages have.
+ *
+ * Two consequences worth stating, because neither is obvious:
+ *
+ *   - A task DECLARING one of these is blocked in the QUEUE (guard 1e), before a slot is spent.
+ *     A task that only DISCOVERS the need mid-attempt still spends its slot and is refused by
+ *     `close.ts`'s `checkScope`, the same way the hard list behaves — the refusal is mechanical and
+ *     names its cause, which beats the `needs-guidance` question T-94 ended on, but the slot is
+ *     gone either way.
+ *   - Refusing the work also removes the need to grant extra scaffolding inside a slot just to test
+ *     it — a package build for `packages/core-back`/`core-front`, a live dispatcher run for
+ *     `scripts/backlog/`. A dispatched worker cannot make these changes, so it never needs either.
+ *
+ * Deliberately NOT `packages/cli/` (soft — the generator's changes are mechanical and local) and
+ * NOT `packages/` or `scripts/` wholesale: the entry list is these three paths, and it grows only
+ * when a person decides another surface has earned the same treatment.
+ */
+/** The framework cause, shared by both core packages — see the doc comment above. */
+const FRAMEWORK_CAUSE =
+  'una ruta del framework que las dos aplicaciones compilan contra. Ensanchar un decorador o un ' +
+  'puerto ahí cambia todos los consumidores a la vez, y ninguna prueba del propio paquete lo ' +
+  'demuestra. Esa decisión es de arquitectura, y necesita una persona MIENTRAS se toma, no un ' +
+  'revisor cuando ya existe: en una pull request marcada las únicas salidas son aceptarla o tirar ' +
+  'el intento entero.';
+
+/** The dispatcher cause, distinct from the framework one above — see the doc comment above. */
+const DISPATCHER_SOURCES_CAUSE =
+  'las fuentes del propio despachador: cambiarlas altera la maquinaria con la que se juzga ' +
+  'cualquier tarea posterior, y este código se envía tal cual a toda aplicación generada por el ' +
+  'scaffold, donde ninguna tarea de solución tiene nada que hacer tocándolo. Esa decisión es de ' +
+  'arquitectura, y necesita una persona MIENTRAS se toma.';
+
+/**
+ * One structure ties every `SUPERVISED_ONLY_PATHS` entry to ITS cause — an entry cannot be added
+ * here without one. `SUPERVISED_ONLY_PATHS` itself is derived from this map's keys, so the two can
+ * never drift apart.
+ */
+const SUPERVISED_ONLY_PATH_CAUSES: Readonly<Record<string, string>> = {
+  'packages/core-back/': FRAMEWORK_CAUSE,
+  'packages/core-front/': FRAMEWORK_CAUSE,
+  'scripts/backlog/': DISPATCHER_SOURCES_CAUSE,
+};
+
+export const SUPERVISED_ONLY_PATHS: readonly string[] = Object.keys(SUPERVISED_ONLY_PATH_CAUSES);
 
 /**
  * Forbidden for the LOCAL lane, on top of `SLOT_EXECUTED_PATHS`: everything that RUNS during the
@@ -221,12 +324,12 @@ export const HUMAN_REVIEW_PATHS: readonly string[] = ['scripts/backlog/', 'packa
  * 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.
+ * Matched as substrings (like `SLOT_EXECUTED_PATHS`), so `scripts/` also catches every OTHER
+ * `scripts/` subtree — one not already refused everywhere by `SUPERVISED_ONLY_PATHS` or
+ * `SLOT_EXECUTED_PATHS` — 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,
@@ -247,6 +350,20 @@ export function matchesBasename(file: string, basenames: readonly string[]): boo
   return basenames.some((name) => name.toLowerCase() === basename);
 }
 
+/**
+ * Sibling of `matchesBasename` above, generalized from "the last path component" to "any
+ * component": splits `value` on `/` and compares each piece WHOLE against `segments`, case
+ * insensitively. Guard 1d (`checkDeclaredClaudeDirPath`) reads this rather than
+ * `declarationReachesPathPattern`'s substring matching, which cannot express "this exact
+ * component" — see `CLAUDE_DIR_SEGMENTS`'s doc comment for the two failure modes that forced the
+ * split (a nested directory declared without a trailing slash sailing through; a bare substring
+ * hit inside an unrelated name).
+ */
+export function matchesPathSegment(value: string, segments: readonly string[]): boolean {
+  const parts = value.toLowerCase().split('/');
+  return segments.some((segment) => parts.includes(segment.toLowerCase()));
+}
+
 /**
  * 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`
@@ -400,71 +517,40 @@ export function resolveTestCommand(declared: string | null): TestCommandResoluti
   return { kind: 'ok', command, args };
 }
 
-// ── Subtask base branch: the ONE place a task's base is named (T-14 → T-15) ──────
+// ── Subtask base branch: the ONE place a task's base is named (T-14) ──────
 //
 // 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`
+// `main` never holds half a decomposed change). `taskBaseBranch` names that base as a pure
+// deduction from the parent's id — `task/<parentId>` (`main` for a top-level task); `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.
+// The root `CLAUDE.md`'s Worktree Gate mandates `task/T-nn` for any task that exists on the board,
+// interactive or dispatched (T-52), so this deduction is the base — never something a parent
+// declares. `missing-parent-branch` fires when that branch is not (yet) on the remote, 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'>>>;
+// must fail loudly — not silently — if that invariant is ever violated. This module is the ONE
+// place that names a task's base, so the two can never disagree: T-4.1 (2026-09-08) measured the
+// cost of letting them — a subtask finished correctly on a branch its close then diffed against a
+// different one, `scope-check-failed` against a ref dispatch never created, a whole frontier run
+// lost to two functions computing two independent answers to the same question.
 
 /**
- * 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.
+ * The naming convention: `task/<parentId>` for a subtask, `main` for a top-level task. No remote
+ * check — see `resolveTaskBase` for that.
  */
-export function taskBaseBranch(
-  task: Pick<Task, 'parentId'>,
-  tasksById: DeclaredBranchLookup,
-): string {
+export function taskBaseBranch(task: Pick<Task, 'parentId'>): string {
   if (!task.parentId) {
     return 'main';
   }
-  return tasksById[task.parentId]?.declaredBranch || `task/${task.parentId}`;
+  return `task/${task.parentId}`;
 }
 
 export type TaskBaseResolution =
@@ -497,14 +583,13 @@ function candidateBranches(taskId: string, remoteBranches: readonly string[]): r
  * 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).
+ * from — the remote-existence half of the two-step resolution this file's header describes.
  */
 export function resolveTaskBase(
   task: Pick<Task, 'parentId'>,
-  tasksById: DeclaredBranchLookup,
   remoteBranches: readonly string[],
 ): TaskBaseResolution {
-  const branch = taskBaseBranch(task, tasksById);
+  const branch = taskBaseBranch(task);
   if (!task.parentId || remoteBranches.includes(branch)) {
     return { kind: 'ok', branch };
   }
@@ -717,10 +802,14 @@ export function denyWouldRevoke(rule: string, grant: string): boolean {
  * 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.
+ * which is the whole point of the subtraction. And a USER-file path rule that does not already read
+ * as leaving the working directory — bare (`Edit`, `Edit(**)`, `Edit(./**)`) or a plain relative
+ * scoping (`Edit(Documents/**)`) alike — 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 stripping both down to the same empty base, not a real one.
+ * Only a grant with no scoping of its own reaches far enough outside the slot to cover it. A
+ * user-file rule that already reads as leaving (absolute, `~/subdir`, `..`) is not this shape at
+ * all — it falls through to the ordinary deny path, same as the identical `project`-sourced rule.
  *
  * None of the three is a choice to make unattended, so the task is blocked with the rules named.
  */
@@ -730,9 +819,18 @@ export type PermissionConflict =
 /**
  * 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.
+ *
+ * A bare home wildcard (`~` or `~/**`) is a THIRD shape, and `leavesWorkingDirectory` cannot answer
+ * for it: the slot lives inside the home directory (root `CLAUDE.md`, "Worktree location"), so `~`
+ * is not an exit like `/` or `..` — it is a SUPERSET that reaches back into the slot too, and is
+ * treated as reaching inside it here. A scoped home path (`~/notes/**`) still reads as leaving, same
+ * as before: it names a sibling directory, not the slot.
  */
 function denyReachesInsideSlot(rule: { tool: string; argument: string | null }): boolean {
   const base = ruleBase(rule);
+  if (base === '~' || base === '~/') {
+    return true;
+  }
   return base.length === 0 || !leavesWorkingDirectory(base);
 }
 
@@ -751,11 +849,23 @@ export function findPermissionConflict(
     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.
+    // reaches outside the slot, so only a bare grant can cover a home-relative rule — a user-file
+    // rule stays home-relative even when it carries its own scoping (`Edit(Documents/**)`), so the
+    // check is not limited to a bare rule.
+    //
+    // Scoped to `!leavesWorkingDirectory` on purpose (fix round, code-review): a user rule whose
+    // base ALREADY reads as leaving (absolute, `~/subdir`, `..`) is not the shape this branch exists
+    // for — `grantCovers`'s own leaving-mismatch check already refuses to call it "covered", and
+    // `denyReachesInsideSlot` below already knows it does not reach the slot, so it falls through to
+    // the ordinary deny path like the identical `project`-sourced rule does (see the parallel
+    // `projectRules` cases in guard 1b). Widening this branch to catch those too force-blocked a
+    // task over a settings rule that never touched the slot at all. The one "leaves" shape that DOES
+    // still need blocking — a bare `~`/`~/**` home wildcard, because the slot lives inside home — is
+    // caught by `denyReachesInsideSlot` further down, not by this branch.
     if (
       entry.source === 'user' &&
       PATH_TOOLS.includes(parsed.tool) &&
-      ruleBase(parsed).length === 0
+      !leavesWorkingDirectory(ruleBase(parsed))
     ) {
       if (!grantsToolUnscoped(parsed.tool)) {
         return { kind: 'file-tool', rule };
@@ -795,11 +905,14 @@ export const GUARD_BLOCK_REASON = {
   REFUSED_TEST_COMMAND: 'refused-test-command',
   PERMISSION_CONFLICT: 'permission-conflict',
   COMPLEX_ON_LOCAL: 'complex-on-local',
+  SUPERVISED_MODE: 'supervised-mode',
   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',
+  CLAUDE_DIR_PATH: 'claude-dir-path',
+  SUPERVISED_ONLY_PATH: 'supervised-only-path',
 } as const;
 
 export type GuardBlockReason = (typeof GUARD_BLOCK_REASON)[keyof typeof GUARD_BLOCK_REASON];
@@ -809,13 +922,6 @@ export const GUARD_WAIT_REASON = {
   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];
@@ -835,7 +941,33 @@ const wait = (reason: GuardWaitReason): GuardResult => ({ kind: 'wait', reason }
 
 // ── Guards ──────────────────────────────────────────────────────────────────────
 
-const MISSING_TRIAGE_COMMENT = 'Bloqueado: sin triage completo (falta tier, lane o path).';
+const SUPERVISED_MODE_COMMENT =
+  'Bloqueado: la tarea está declarada mode:supervised — necesita una persona en sesión, nunca se ' +
+  'despacha a un worker headless. Dos salidas: trabájala en una sesión interactiva, o quítale la ' +
+  'etiqueta y ponle la otra en el MISMO edit — backlog task edit <id> --remove-label mode:supervised ' +
+  '--add-label mode:headless — y vuelve a encolarla (--add-label por sí solo AÑADE, no sustituye, y ' +
+  'dejaría las dos etiquetas mode: puestas a la vez).';
+
+/**
+ * Guard 0: `mode:supervised` needs a person in a session, so no other guard's verdict could ever be
+ * anything but misleading for it — a missing `Test command:` (guard 1), a declared hard-list or
+ * supervised-only path (guards 1c/1e), an unfinished dependency (guard 3) are all contracts this
+ * task can never need, since it was never going to be dispatched in the first place. Placed at the
+ * very HEAD of `evaluateGuards`, before every other guard including guard 1's triage check: a task
+ * carrying `mode:supervised` has exactly one true verdict, and letting an earlier-numbered guard
+ * fire first would cost a needless round trip — a person fixing a contract the task never needed,
+ * then re-queueing only to learn the real cause. A task with NO `mode` label at all is unaffected by
+ * this guard: it checks specifically for the SUPERVISED value, so it falls through to guard 1, which
+ * blocks it as an incomplete triage — a missing declaration is not read as either value.
+ */
+function checkSupervisedMode(task: Task): GuardResult | null {
+  if (task.mode === MODE.SUPERVISED) {
+    return block(GUARD_BLOCK_REASON.SUPERVISED_MODE, SUPERVISED_MODE_COMMENT);
+  }
+  return null;
+}
+
+const MISSING_TRIAGE_COMMENT = 'Bloqueado: sin triage completo (falta tier, lane, path o mode).';
 
 /**
  * `tier:complex` already has its own dedicated check (guard 2, `checkComplexOnLocal`) with its own
@@ -850,9 +982,9 @@ function tierLaneMismatchComment(tier: Tier): string {
 }
 
 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").';
+  'Bloqueado: la tarea no declara la línea "Test command:" en su descripción, o la deja vacía — 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 ' +
@@ -878,7 +1010,7 @@ function refusedTestCommandComment(declared: string, reason: string): string {
 }
 
 function checkTriage(task: Task): GuardResult | null {
-  if (!task.tier || !task.lane || !task.path) {
+  if (!task.tier || !task.lane || !task.path || !task.mode) {
     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
@@ -953,6 +1085,85 @@ function checkDeclaredSlotExecutedPath(task: Task): GuardResult | null {
     : null;
 }
 
+function claudeDirPathComment(file: string): string {
+  return (
+    `Bloqueado: la tarea declara "${file}", una ruta bajo un segmento ".claude". Con ` +
+    '--permission-mode dontAsk (el modo del dispatch), el harness deniega CUALQUIER Edit/Write que ' +
+    'alcance una ruta con ese segmento, bajo cualquier forma de regla de permisos probada — ningún ' +
+    'cambio en los settings del lane lo soluciona (medido 2026-09-10, ver ' +
+    '`scripts/backlog/README.md`, "Forbidden paths, split by mechanism"). ' +
+    'Ese trabajo necesita una sesión interactiva — quita la entrada de "Files to touch:" y hazlo a mano.'
+  );
+}
+
+/**
+ * Guard 1d: on BOTH lanes, a task may not DECLARE a path carrying a `.claude` segment — the
+ * harness's own `--permission-mode dontAsk` refuses that Edit/Write outright (see
+ * `CLAUDE_DIR_SEGMENTS`'s doc comment for the measurement), so no lane settings change could ever
+ * make it actionable and no later guard's verdict — a free-slot wait, a parent-branch push — would
+ * be anything but misleading for it.
+ *
+ * Same SHAPE as guard 1c (`checkDeclaredSlotExecutedPath`) — a declared-path scan, a list, a check
+ * function, a block reason, a comment builder — but a different MATCHER, cause and list: guard 1c
+ * reads `declarationReachesPathPattern` (substring/containment) because it is about what the SLOT
+ * executes or reads, against a list of specific paths; this reads `matchesPathSegment` (whole path
+ * component) because it is about a bare directory NAME that can appear at any depth, and a
+ * substring match over that name both misses a nested declaration with no trailing slash and false
+ * positives on an unrelated name that merely contains it — see `CLAUDE_DIR_SEGMENTS`'s doc comment.
+ * No basename half either: `.claude` is a directory component, not a filename
+ * `SLOT_EXECUTED_BASENAMES`'s whole-name match would apply to.
+ *
+ * PLACED directly after guard 1c and before everything else, for the same reason guard 1c sits
+ * where it does: a task declaring a `.claude` path can never be dispatched, on either lane.
+ */
+function checkDeclaredClaudeDirPath(task: Task): GuardResult | null {
+  const offending = task.filesToTouch.find((file) => matchesPathSegment(file, CLAUDE_DIR_SEGMENTS));
+  return offending
+    ? block(GUARD_BLOCK_REASON.CLAUDE_DIR_PATH, claudeDirPathComment(offending))
+    : null;
+}
+
+function supervisedOnlyPathComment(file: string, matchedPattern: string): string {
+  const cause = SUPERVISED_ONLY_PATH_CAUSES[matchedPattern];
+  return (
+    `Bloqueado: la tarea declara "${file}", ${cause} ` +
+    'Ese trabajo va en una sesión interactiva — quita la entrada de "Files to touch:" y encola aparte ' +
+    'lo que sí sea despachable.'
+  );
+}
+
+/**
+ * Guard 1e: on BOTH lanes, a task may not DECLARE a path under a supervised-only surface. Same
+ * SHAPE as guards 1c and 1d — a declared-path scan, a list, a check function, a block reason, a
+ * comment builder — and the same MATCHER as guard 1c (`declarationReachesPathPattern`), because
+ * like it this list names path PREFIXES, not a bare directory name that can appear at any depth.
+ *
+ * The CAUSE is what differs from both, and `SUPERVISED_ONLY_PATHS`'s doc comment carries it:
+ * nothing in the slot executes these files and the harness does not refuse the write — the work is
+ * refused because the decision behind it belongs to a person, before the code exists.
+ *
+ * PLACED after guard 1d for the same reason those two sit where they do: a task declaring one of
+ * these can never be dispatched on either lane, so every later verdict — a free-slot wait, a
+ * parent-branch push — would only mislead.
+ */
+function checkDeclaredSupervisedOnlyPath(task: Task): GuardResult | null {
+  const offending = task.filesToTouch.find((file) =>
+    declarationReachesPathPattern(file, SUPERVISED_ONLY_PATHS),
+  );
+  if (!offending) {
+    return null;
+  }
+  // The matched PATTERN, not just the offending file, decides which cause applies — two entries can
+  // share none of the file's substring otherwise.
+  const matchedPattern = SUPERVISED_ONLY_PATHS.find((pattern) =>
+    declarationReachesPathPattern(offending, [pattern]),
+  )!;
+  return block(
+    GUARD_BLOCK_REASON.SUPERVISED_ONLY_PATH,
+    supervisedOnlyPathComment(offending, matchedPattern),
+  );
+}
+
 /**
  * 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
@@ -969,15 +1180,24 @@ export interface PermissionComposition {
 }
 
 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.';
+  if (conflict.kind === 'broader') {
+    return (
+      `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.'
+    );
+  }
+  // PATH_TOOLS includes Glob and Grep, no solo los FILE_TOOLS que "abren" un fichero — el texto debe
+  // nombrar la herramienta real y la acción real, no asumir siempre "abrir un fichero" (defecto 3).
+  const tool = parseRule(conflict.rule).tool;
+  const action = FILE_TOOLS.includes(tool) ? 'abrir ficheros' : 'buscar rutas';
+  return (
+    `Bloqueado: conflicto de permisos — la regla de settings ${conflict.rule} acota ${tool} dentro del ` +
+    'slot y el allowlist del lane no la cubre. Denegarla dejaría al worker sin poder ' +
+    `${action} con ella. Estrecha la regla de settings o amplía el allowlist del lane.`
+  );
 }
 
 /**
@@ -1063,9 +1283,7 @@ function missingParentBranchComment(
     `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.'
+    `slot. ${candidateLine} Crea y empuja ${branch} y vuelve a encolar esta subtarea.`
   );
 }
 
@@ -1102,28 +1320,14 @@ function missingParentBranchComment(
  * 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.
+ * This guard reads no board state at all: `task.parentId` is the subtask's own field (always known
+ * once it is triaged), and `resolveTaskBase` below resolves purely against the live
+ * `remoteBranches` list. Nothing here can go stale the way a board read can — a `backlog task view`
+ * that threw this pass has no bearing on whether `task/<parentId>` is on the remote. That is why it
+ * carries no wait for an incomplete board read: there is no board read left to be incomplete.
  */
-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);
+function checkParentBranchOnRemote(task: Task, remoteBranches: readonly string[]): GuardResult | null {
+  const resolution = resolveTaskBase(task, remoteBranches);
   if (resolution.kind === 'missing-parent-branch') {
     return block(
       GUARD_BLOCK_REASON.MISSING_PARENT_BRANCH,
@@ -1181,8 +1385,8 @@ function checkFreeSlot(
 // ── 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
+ * Evaluates the twelve dispatch guards — the original six, plus 0, 1b, 1c, 1d, 1e 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.
  *
@@ -1212,11 +1416,25 @@ export function evaluateGuards(
   remoteBranches: readonly string[],
 ): GuardResult {
   return (
+    // Guard 0 runs before EVERYTHING else, including guard 1's triage check: a task carrying
+    // `mode:supervised` has exactly one true verdict, and letting any other guard fire first would
+    // block it for a contract it can never need (e.g. a missing `Test command:`, when its
+    // verification is not a dispatchable command at all) — reporting the real cause only after a
+    // person fixes that one first and re-queues. A task with NO `mode` label at all is unaffected:
+    // this guard checks specifically for the SUPERVISED value, so it falls through to guard 1, which
+    // blocks it as an incomplete triage.
+    checkSupervisedMode(task) ??
     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) ??
+    // Guard 1d runs directly after guard 1c, for the same reason: a task declaring a `.claude/`
+    // path can never be dispatched at all (the harness's own permission mode refuses the write,
+    // not a lane setting a later guard could reason about), so it belongs beside guard 1c rather
+    // than after the checks that assume the task's declared scope is actionable.
+    checkDeclaredClaudeDirPath(task) ??
+    checkDeclaredSupervisedOnlyPath(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.
@@ -1227,7 +1445,7 @@ export function evaluateGuards(
     // 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) ??
+    checkParentBranchOnRemote(task, remoteBranches) ??
     checkAttemptsExhausted(task, limits) ??
     checkFreeSlot(task, slots, limits) ?? { kind: 'launch' }
   );