@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -14,13 +14,16 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import {
+  CLAUDE_DIR_SEGMENTS,
   denyWouldRevoke,
   evaluateGuards,
   findPermissionConflict,
   grantCovers,
   HUMAN_REVIEW_PATHS,
+  SUPERVISED_ONLY_PATHS,
   isDeadBashRule,
   LOCAL_FORBIDDEN_PATHS,
+  matchesPathSegment,
   resolveTaskBase,
   resolveTestCommand,
   SECURITY_PATH_PATTERNS,
@@ -32,6 +35,7 @@ import {
 import {
   DEFAULT_DISPATCH_LIMITS,
   LANE,
+  MODE,
   TASK_STATUS,
   type Board,
   type SettingsAllowRule,
@@ -47,8 +51,9 @@ const baseTask = (overrides: Partial<Task> = {}): Task => ({
   tier: 'minor',
   lane: LANE.LOCAL,
   path: 'direct',
+  mode: MODE.HEADLESS,
   bc: 'backlog',
-  filesToTouch: ['scripts/backlog/guards.ts'],
+  filesToTouch: ['backend/src/@app/some-bc/x.service.ts'],
   testCommand: 'pnpm test:backlog',
   acceptanceCriteria: [],
   definitionOfDone: [],
@@ -133,8 +138,8 @@ describe('the split path criteria', () => {
     assert.ok(!HUMAN_REVIEW_PATHS.some((pattern) => 'scripts/packager/'.includes(pattern)));
   });
 
-  it('HUMAN_REVIEW_PATHS holds the dispatcher sources and the generator package', () => {
-    assert.deepEqual(HUMAN_REVIEW_PATHS, ['scripts/backlog/', 'packages/cli/']);
+  it('HUMAN_REVIEW_PATHS holds the generator package, and nothing else', () => {
+    assert.deepEqual(HUMAN_REVIEW_PATHS, ['packages/cli/']);
   });
 
   // `CLAUDE.md` is HARD on both lanes (T-31 round 2). The premise that demoted it — "a soft-list
@@ -165,12 +170,19 @@ describe('the split path criteria', () => {
       '.git/',
     ]);
   });
+
+  // A FIFTH list (T-44), read by guard 1d only — see that guard's own describe block below for
+  // the matcher it needs. Anchoring the content here gives the `export` a real reader: nothing
+  // else in this suite imports `CLAUDE_DIR_SEGMENTS` by name.
+  it('CLAUDE_DIR_SEGMENTS holds one entry, a bare segment with no trailing slash', () => {
+    assert.deepEqual(CLAUDE_DIR_SEGMENTS, ['.claude']);
+  });
 });
 
 // ── Guard 1: missing triage ───────────────────────────────────────────────────
 
 describe('evaluateGuards — guard 1: missing triage', () => {
-  for (const missing of ['tier', 'lane', 'path'] as const) {
+  for (const missing of ['tier', 'lane', 'path', 'mode'] as const) {
     it(`blocks when ${missing} is missing`, () => {
       const task = baseTask({ [missing]: undefined });
       const result = evaluateGuards(
@@ -185,6 +197,9 @@ describe('evaluateGuards — guard 1: missing triage', () => {
       if (result.kind === 'block') {
         assert.equal(result.reason, 'missing-triage');
         assert.match(result.comment, /sin triage/i);
+        if (missing === 'mode') {
+          assert.match(result.comment, /mode/i);
+        }
       }
     });
   }
@@ -522,6 +537,315 @@ describe('evaluateGuards — guard 1c: a declared hard-list path', () => {
   });
 });
 
+// ── Guard 1d: a declared `.claude/` path blocks in the queue (T-44, 2026-09-10) ────
+//
+// Measured fact this guard is built on: a dispatched worker runs under `--permission-mode
+// dontAsk`. 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 (`Edit(./**)`,
+// `Edit(**)`, `Edit(**/.claude/**)`, `Edit(**/.claude/skills/**)`, the exact relative path, the
+// exact absolute path) — `claude -p` probes on a temporary repo, 2026-09-10. Two controls PASS
+// with `Edit(./**)` on the same run (`sub/plain/a.md`, `sub/.hidden/a.md`), so the trigger is the
+// NAME `.claude`, not "hidden directory". 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. No lane settings change can
+// fix this — the task must run in an interactive session, which is exactly what guard 1d's
+// comment tells a person to do.
+
+// Guard 1e refuses the two core packages on BOTH lanes, and for a cause no other list here shares:
+// nothing in the slot executes them and the harness does not refuse the write — the DECISION is
+// architectural, so it needs a person while it is being made. T-94 measured what happens without
+// this: the framework change was written, the consumer could not compile it, and the attempt ended
+// in a `needs-guidance` question after a whole frontier slot was spent.
+
+describe('evaluateGuards — guard 1e: a declared supervised-only path', () => {
+  for (const lane of [LANE.LOCAL, LANE.FRONTIER] as const) {
+    for (const declared of [
+      'packages/core-back/src/domain/decorators/tenant-constraint.decorator.ts',
+      'packages/core-front/src/lib/index.ts',
+      'packages/core-back/',
+      'scripts/backlog/guards.ts',
+      'scripts/backlog/',
+    ]) {
+      it(`blocks a lane:${lane} task declaring ${declared}, naming it and the cause`, () => {
+        const task = baseTask({
+          lane,
+          tier: lane === LANE.LOCAL ? 'minor' : 'medium',
+          filesToTouch: [declared],
+        });
+        const result = evaluateGuards(
+          task,
+          emptyBoard,
+          freeSlots(),
+          DEFAULT_DISPATCH_LIMITS,
+          null,
+          [],
+        );
+        assert.equal(result.kind, 'block');
+        if (result.kind === 'block') {
+          assert.equal(result.reason, 'supervised-only-path');
+          assert.ok(
+            result.comment.includes(declared),
+            'the comment must name the offending declared file',
+          );
+          assert.match(result.comment, /sesión interactiva/i);
+        }
+      });
+    }
+  }
+
+  // The two causes behind SUPERVISED_ONLY_PATHS are different (framework vs. dispatcher sources),
+  // and the comment a person reads in a `Blocked` task must name the one that actually applies —
+  // never the other, which would misdirect the release flow of section 10.
+  it('names the framework cause for a core package, and not the dispatcher cause', () => {
+    const task = baseTask({
+      lane: LANE.FRONTIER,
+      tier: 'medium',
+      filesToTouch: ['packages/core-back/src/domain/decorators/tenant-constraint.decorator.ts'],
+    });
+    const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.match(result.comment, /consumidor/i);
+      assert.doesNotMatch(result.comment, /despachador/i);
+    }
+  });
+
+  it('names the dispatcher cause for scripts/backlog/, and not the framework cause', () => {
+    const task = baseTask({
+      lane: LANE.FRONTIER,
+      tier: 'medium',
+      filesToTouch: ['scripts/backlog/guards.ts'],
+    });
+    const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.match(result.comment, /despachador/i);
+      assert.doesNotMatch(result.comment, /consumidor/i);
+    }
+  });
+
+  // The generator package stays SOFT — admitted and marked, never blocked. Guard 1e must not widen
+  // to `packages/` wholesale: that would refuse the mechanical, local changes the soft list exists
+  // to admit.
+  it('does not block a task declaring packages/cli, which stays on the soft list', () => {
+    const task = baseTask({
+      lane: LANE.FRONTIER,
+      tier: 'medium',
+      filesToTouch: ['packages/cli/src/templates/codegen/foo.eta'],
+    });
+    const result = evaluateGuards(
+      task,
+      emptyBoard,
+      freeSlots(),
+      DEFAULT_DISPATCH_LIMITS,
+      null,
+      [],
+    );
+    assert.notEqual(result.kind, 'block');
+  });
+
+  it('SUPERVISED_ONLY_PATHS holds the two core packages plus the dispatcher sources, and nothing else', () => {
+    assert.deepEqual(SUPERVISED_ONLY_PATHS, [
+      'packages/core-back/',
+      'packages/core-front/',
+      'scripts/backlog/',
+    ]);
+  });
+
+  // The two lists answer different questions and must not be conflated: a supervised-only path is
+  // refused outright, a soft-list path is admitted and marked. An entry in both would make the
+  // classification order decide the verdict.
+  it('no path is both supervised-only and human-review', () => {
+    for (const supervised of SUPERVISED_ONLY_PATHS) {
+      assert.ok(
+        !HUMAN_REVIEW_PATHS.some((soft) => supervised.includes(soft) || soft.includes(supervised)),
+        `${supervised} must not overlap the soft list`,
+      );
+    }
+  });
+});
+
+describe('evaluateGuards — guard 1d: a declared ".claude" path', () => {
+  for (const lane of [LANE.LOCAL, LANE.FRONTIER] as const) {
+    it(`blocks a lane:${lane} task declaring a ".claude" file, naming it and the cause`, () => {
+      const claudeFile = '.claude/skills/catalyst-backlog/SKILL.md';
+      const task = baseTask({
+        lane,
+        tier: lane === LANE.LOCAL ? 'minor' : 'medium',
+        filesToTouch: [claudeFile],
+      });
+      const result = evaluateGuards(
+        task,
+        emptyBoard,
+        freeSlots(),
+        DEFAULT_DISPATCH_LIMITS,
+        null,
+        [],
+      );
+      assert.equal(result.kind, 'block');
+      if (result.kind === 'block') {
+        assert.equal(result.reason, 'claude-dir-path');
+        assert.ok(
+          result.comment.includes(claudeFile),
+          'the comment must name the offending declared file',
+        );
+        assert.match(result.comment, /dontAsk/);
+        assert.match(result.comment, /sesión interactiva/i);
+      }
+    });
+  }
+
+  // T-44 round 2 measured `declarationReachesPathPattern` (guard 1c's substring/containment
+  // matcher) wrong for THIS list: its forward direction requires the declaration to literally
+  // contain the pattern text `.claude/`, trailing slash included, so a NESTED directory declared
+  // WITHOUT one — `frontend/.claude`, the exact shape T-41 used — matched neither direction and
+  // sailed straight through the guard. `matchesPathSegment` (a sibling of `matchesBasename`, split
+  // on `/` the same way) replaces it here. Tested directly against the exported matcher, isolated
+  // from guard ORDER: a bare root-level `.claude` also reaches `SLOT_EXECUTED_PATHS` by
+  // containment (`.claude/hooks/`, `.claude/settings.json`, …), so through `evaluateGuards` it is
+  // guard 1c that fires first and reports `slot-executed-path` — see that guard's own describe
+  // block above, which already covers this exact declaration. What matters for guard 1d itself is
+  // that its OWN predicate says true for every one of these five forms, root-level or nested, with
+  // or without a trailing slash — which is what this asserts, unconfounded by which guard wins the
+  // race for the bare case.
+  for (const declared of [
+    'backend/.claude/',
+    'backend/.claude',
+    'frontend/.claude',
+    'frontend/.claude/skills',
+    '.claude',
+  ]) {
+    it(`matchesPathSegment reaches the declared path ${declared}`, () => {
+      assert.equal(matchesPathSegment(declared, CLAUDE_DIR_SEGMENTS), true);
+    });
+  }
+
+  // End to end via `evaluateGuards`, for the forms that reach ONLY guard 1d — a nested `.claude`
+  // never collides with guard 1c's root-anchored hard list, so these confirm the real dispatch
+  // verdict, not just the predicate.
+  const nestedForms = [
+    'backend/.claude/',
+    'backend/.claude',
+    'frontend/.claude',
+    'frontend/.claude/skills',
+  ];
+  for (const declared of nestedForms) {
+    it(`blocks the declared path ${declared}`, () => {
+      const task = baseTask({ filesToTouch: [declared] });
+      const result = evaluateGuards(
+        task,
+        emptyBoard,
+        freeSlots(),
+        DEFAULT_DISPATCH_LIMITS,
+        null,
+        [],
+      );
+      assert.equal(result.kind, 'block');
+      if (result.kind === 'block') {
+        assert.equal(result.reason, 'claude-dir-path');
+      }
+    });
+  }
+
+  // The real-world case that hit: the segment is not at the repo root, and carries no trailing
+  // slash — the full path to the file, not just its containing directory.
+  it('blocks a nested ".claude" path, not only a root-level one', () => {
+    const nestedFile = 'frontend/.claude/skills/catalyst-form-composer-auditor/SKILL.md';
+    const task = baseTask({ filesToTouch: [nestedFile] });
+    const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.equal(result.reason, 'claude-dir-path');
+      assert.ok(result.comment.includes(nestedFile));
+    }
+  });
+
+  // The same round measured a false POSITIVE alongside the false negative above: the substring
+  // matcher blocked `notes.claude/file.md`, which carries no `.claude` path COMPONENT at all —
+  // the text `.claude` is glued to the end of `notes`, not a segment on its own. A near-miss that
+  // merely CONTAINS the letters must pass, on either side of the `/`.
+  const nearMisses = ['src/dotclaude/', 'a/.claudex/', 'my.claude-notes/', 'notes.claude/file.md'];
+
+  for (const nearMiss of nearMisses) {
+    it(`matchesPathSegment does not reach the near-miss ${nearMiss}`, () => {
+      assert.equal(matchesPathSegment(nearMiss, CLAUDE_DIR_SEGMENTS), false);
+    });
+  }
+
+  for (const nearMiss of nearMisses) {
+    it(`does not block the near-miss declared path ${nearMiss}`, () => {
+      const task = baseTask({ filesToTouch: [nearMiss] });
+      const result = evaluateGuards(
+        task,
+        emptyBoard,
+        freeSlots(),
+        DEFAULT_DISPATCH_LIMITS,
+        null,
+        [],
+      );
+      assert.notEqual(result.kind, 'block');
+    });
+  }
+
+  // `baseTask()`'s default `filesToTouch` (`backend/src/@app/some-bc/x.service.ts`) does not even
+  // contain the substring `claude`, so on its own this test cannot tell a correct matcher from a broken
+  // one — a gap T-44 round 2 measured directly (mutating `CLAUDE_DIR_SEGMENTS` to `['claude']`
+  // left every test in this file green). The near-miss fixtures above and the list-content
+  // assertion below are what actually discriminate; this one stays as the ordinary "an unrelated
+  // task launches" case.
+  it('does not block a task with no ".claude" path declared', () => {
+    const result = evaluateGuards(
+      baseTask(),
+      emptyBoard,
+      freeSlots(),
+      DEFAULT_DISPATCH_LIMITS,
+      null,
+      [],
+    );
+    assert.equal(result.kind, 'launch');
+  });
+
+  it('reports missing triage before a declared ".claude" path (guard 1 runs first)', () => {
+    const task = baseTask({ lane: undefined, filesToTouch: ['.claude/skills/x/SKILL.md'] });
+    const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.equal(result.reason, 'missing-triage');
+    }
+  });
+
+  // The refusal must happen BEFORE a slot is taken: even with zero free slots, the verdict is the
+  // `.claude` block, never the wait-for-slot reason.
+  it('reports the block before a no-free-slot wait, never the other way round', () => {
+    const busySlots: SlotRegistry = {
+      slots: [
+        {
+          name: 'dispatch-a',
+          path: '/slots/a',
+          lane: LANE.LOCAL,
+          taskId: 'T-99',
+          pid: 1,
+          lockfileHash: 'x',
+        },
+      ],
+    };
+    const task = baseTask({ filesToTouch: ['.claude/skills/x/SKILL.md'] });
+    const result = evaluateGuards(
+      task,
+      emptyBoard,
+      busySlots,
+      { ...DEFAULT_DISPATCH_LIMITS, capacity: { [LANE.LOCAL]: 1, [LANE.FRONTIER]: 2 } },
+      null,
+      [],
+    );
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.equal(result.reason, 'claude-dir-path');
+    }
+  });
+});
+
 // ── Guard 1b: permission composition (BOTH lanes) ─────────────────────────────
 //
 // R2 (round 10): this refusal used to live in `buildLaunch`, which runs AFTER the slot is acquired
@@ -601,16 +925,82 @@ describe('evaluateGuards — guard 1b: a settings rule broader than one the laun
   // A non-covered scoping of a FILE tool is a conflict only when the deny that cancels it would
   // reach INSIDE the slot — that deny is what takes away the worker's ability to open a file there.
   // A scoping that only reaches outside the slot is denied like any other rule, which is the point.
-  for (const rule of ['Edit(frontend/**)', 'Edit(**)', 'Edit(./**)', 'Edit']) {
-    it(`blocks a settings rule whose deny would disable a file tool inside the slot: ${rule}`, () => {
+  // Parametrized over all three FILE_TOOLS (not just Edit), each with a granted list that does NOT
+  // grant that tool, so the case always falls through to `denyReachesInsideSlot`.
+  const fileToolGrants: Record<'Read' | 'Edit' | 'Write', string[]> = {
+    Read: ['Edit(./**)', 'Write(./**)', 'Bash(openspec:*)'],
+    Edit: ['Read', 'Write(./**)', 'Bash(openspec:*)'],
+    Write: ['Read', 'Edit(./**)', 'Bash(openspec:*)'],
+  };
+
+  for (const tool of ['Read', 'Edit', 'Write'] as const) {
+    // `${tool}(~/**)` is a THIRD shape here, distinct from a relative glob (narrows a slot
+    // directory) and a bare/unscoped rule (takes the tool away wholesale): the slot lives inside
+    // the home directory (root CLAUDE.md, "Worktree location"), so a bare "~" wildcard is a
+    // SUPERSET that reaches back into the slot too — it is not an exit like "/" or "..".
+    for (const rule of [
+      `${tool}(frontend/**)`,
+      `${tool}(**)`,
+      `${tool}(./**)`,
+      tool,
+      `${tool}(~/**)`,
+    ]) {
+      it(`blocks a settings rule whose deny would disable a file tool inside the slot: ${rule}`, () => {
+        const result = evaluateGuards(
+          frontierTask(),
+          emptyBoard,
+          freeSlots(),
+          DEFAULT_DISPATCH_LIMITS,
+          {
+            settingsAllow: projectRules(rule),
+            grantedAllow: fileToolGrants[tool],
+          },
+          [],
+        );
+        assert.equal(result.kind, 'block');
+        if (result.kind === 'block') {
+          assert.equal(result.reason, 'permission-conflict');
+          assert.ok(result.comment.includes(rule));
+        }
+      });
+    }
+  }
+
+  for (const tool of ['Read', 'Edit', 'Write'] as const) {
+    // A scoped home path (`~/notes/**`) is NOT the same shape as the bare `~/**` above: it names a
+    // sibling directory, not the slot, so it stays in the "only reaches outside" group.
+    for (const rule of [`${tool}(/etc/**)`, `${tool}(~/notes/**)`, `${tool}(../**)`]) {
+      it(`lets a file-tool scoping that only reaches outside the slot fall through to a deny: ${rule}`, () => {
+        const result = evaluateGuards(
+          frontierTask(),
+          emptyBoard,
+          freeSlots(),
+          DEFAULT_DISPATCH_LIMITS,
+          {
+            settingsAllow: projectRules(rule),
+            grantedAllow: [`${tool}(./**)`, 'Bash(openspec:*)'],
+          },
+          [],
+        );
+        assert.equal(result.kind, 'launch');
+      });
+    }
+  }
+
+  // A USER-file path scoping is relative to the home directory, not to the slot, so the lane's
+  // slot-scoped `Edit(./**)` does not cover it — it only looks like it does once the `./` is
+  // normalised away. The lane cannot express "everything under $HOME", so the launch cannot make
+  // this rule safe: it is a conflict a person resolves.
+  for (const rule of ['Edit', 'Edit(**)', 'Edit(./**)']) {
+    it(`blocks a user-file rule with no path scoping of its own: ${rule}`, () => {
       const result = evaluateGuards(
         frontierTask(),
         emptyBoard,
         freeSlots(),
         DEFAULT_DISPATCH_LIMITS,
         {
-          settingsAllow: projectRules(rule),
-          grantedAllow: ['Read', 'Write(./**)', 'Bash(openspec:*)'],
+          settingsAllow: userRules(rule),
+          grantedAllow: frontierGrants(),
         },
         [],
       );
@@ -622,44 +1012,51 @@ describe('evaluateGuards — guard 1b: a settings rule broader than one the laun
     });
   }
 
-  for (const rule of ['Edit(/etc/**)', 'Edit(~/notes/**)', 'Edit(../**)']) {
-    it(`lets a file-tool scoping that only reaches outside the slot fall through to a deny: ${rule}`, () => {
-      const result = evaluateGuards(
-        frontierTask(),
-        emptyBoard,
-        freeSlots(),
-        DEFAULT_DISPATCH_LIMITS,
-        {
-          settingsAllow: projectRules(rule),
-          grantedAllow: ['Edit(./**)', 'Bash(openspec:*)'],
-        },
-        [],
-      );
-      assert.equal(result.kind, 'launch');
-    });
-  }
+  // Defect 1 (T-10): a RELATIVE user-file path rule (its own scoping, not bare) is STILL
+  // home-relative, not slot-relative — it must block the same way the bare forms above do, not read
+  // as covered by the lane's slot-scoped `Edit(./**)`.
+  it('blocks a user-file rule scoped to a RELATIVE path, not just a bare one', () => {
+    const result = evaluateGuards(
+      frontierTask(),
+      emptyBoard,
+      freeSlots(),
+      DEFAULT_DISPATCH_LIMITS,
+      {
+        settingsAllow: userRules('Edit(Documents/**)'),
+        grantedAllow: frontierGrants(),
+      },
+      [],
+    );
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.equal(result.reason, 'permission-conflict');
+      assert.ok(result.comment.includes('Edit(Documents/**)'));
+    }
+  });
 
-  // A USER-file path scoping is relative to the home directory, not to the slot, so the lane's
-  // slot-scoped `Edit(./**)` does not cover it — it only looks like it does once the `./` is
-  // normalised away. The lane cannot express "everything under $HOME", so the launch cannot make
-  // this rule safe: it is a conflict a person resolves.
-  for (const rule of ['Edit', 'Edit(**)', 'Edit(./**)']) {
-    it(`blocks a user-file rule with no path scoping of its own: ${rule}`, () => {
+  // Defect 3 (T-10): PATH_TOOLS includes Glob and Grep, not just the FILE_TOOLS that "open" a file —
+  // the conflict text must name the real tool and the real action, not claim the worker cannot open
+  // a file when the tool in question searches or lists paths instead.
+  for (const tool of ['Glob', 'Grep'] as const) {
+    it(`names the real tool for a bare user-file rule on ${tool}, not "abrir un fichero"`, () => {
       const result = evaluateGuards(
         frontierTask(),
         emptyBoard,
         freeSlots(),
         DEFAULT_DISPATCH_LIMITS,
         {
-          settingsAllow: userRules(rule),
-          grantedAllow: frontierGrants(),
+          settingsAllow: userRules(tool),
+          grantedAllow: ['Read', 'Edit(./**)', 'Write(./**)', 'Bash(openspec:*)'],
         },
         [],
       );
       assert.equal(result.kind, 'block');
       if (result.kind === 'block') {
-        assert.equal(result.reason, 'permission-conflict');
-        assert.ok(result.comment.includes(rule));
+        assert.ok(result.comment.includes(tool), `comment must name ${tool}`);
+        assert.ok(
+          !result.comment.includes('abrir ficheros') && !result.comment.includes('abrir un fichero'),
+          'comment must not claim the conflict is about opening a file',
+        );
       }
     });
   }
@@ -925,6 +1322,49 @@ describe('findPermissionConflict', () => {
       null,
     );
   });
+
+  // Defect 1 (T-10): a user-file rule scoped to a RELATIVE path is still home-relative, not
+  // slot-relative — the `./` normalization strips the lane's `Edit(./**)` down to an empty base,
+  // which then wrongly reads as a prefix of "Documents" too. Only a bare grant reaches far enough
+  // outside the slot to cover a user-file rule, scoped or not.
+  it('reports a RELATIVE user-file path rule as a file-tool conflict, not covered by a slot grant', () => {
+    assert.deepEqual(findPermissionConflict(userRules('Edit(Documents/**)'), ['Edit(./**)']), {
+      kind: 'file-tool',
+      rule: 'Edit(Documents/**)',
+    });
+  });
+
+  // Defect 4 (T-10): the CLASS of the conflict, not just the guard-level reason, must be `file-tool`
+  // for a bare user-file rule the lane only grants scoped.
+  it('reports a bare user-file rule as a file-tool conflict (asserted by kind, not just reason)', () => {
+    assert.deepEqual(findPermissionConflict(userRules('Edit'), ['Edit(./**)']), {
+      kind: 'file-tool',
+      rule: 'Edit',
+    });
+  });
+
+  // Fix-round regression (code-review, T-10): the point-1 fix must stay scoped to a rule whose base
+  // does NOT already read as leaving the working directory. A user-file rule that is ALREADY
+  // unambiguous about pointing outside the slot (absolute, "~/subdir", "..") must still fall through
+  // to the ordinary coverage/deny path — the SAME `null` a `project`-sourced rule of the identical
+  // shape gets (see the parallel `projectRules` loop in the guard-1b suite above) — not be force-
+  // blocked just for being "user"-sourced. Forcing a block here would refuse a task over a settings
+  // rule that never touched the slot at all.
+  it('is null for a user-file rule that already reads as leaving the working directory', () => {
+    assert.equal(findPermissionConflict(userRules('Edit(/etc/**)'), ['Edit(./**)']), null);
+    assert.equal(findPermissionConflict(userRules('Edit(~/notes/**)'), ['Edit(./**)']), null);
+    assert.equal(findPermissionConflict(userRules('Edit(../**)'), ['Edit(./**)']), null);
+  });
+
+  // The bare home wildcard is the one "leaving" shape that must still block — via the SAME
+  // `denyReachesInsideSlot` mechanism a `project`-sourced `~/**` rule blocks through (defect 2),
+  // because the slot lives inside home and this one genuinely reaches back into it.
+  it('still reports a bare user-file "~/**" rule as a file-tool conflict, via denyReachesInsideSlot', () => {
+    assert.deepEqual(findPermissionConflict(userRules('Edit(~/**)'), ['Edit(./**)']), {
+      kind: 'file-tool',
+      rule: 'Edit(~/**)',
+    });
+  });
 });
 
 // ── Guard 2: Complex on local ─────────────────────────────────────────────────
@@ -947,6 +1387,88 @@ describe('evaluateGuards — guard 2: Complex on local', () => {
   });
 });
 
+// ── Guard 0: supervised mode ──────────────────────────────────────────────────
+
+describe('evaluateGuards — guard 0: supervised mode', () => {
+  it('blocks a mode:supervised task, naming both ways out', () => {
+    const task = baseTask({ mode: MODE.SUPERVISED });
+    const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.equal(result.reason, 'supervised-mode');
+      assert.match(result.comment, /supervised/i);
+      assert.match(result.comment, /sesión/i);
+      assert.match(result.comment, /mode:headless/);
+    }
+  });
+
+  // `--add-label` APPENDS rather than replacing — following "relabel mode:headless" literally
+  // would leave BOTH `mode:` labels on the task. The comment must state the exact edit instead of
+  // an instruction a person could follow into that trap.
+  it('names the exact edit — --remove-label AND --add-label in the same command — never --add-label alone', () => {
+    const task = baseTask({ mode: MODE.SUPERVISED });
+    const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.match(result.comment, /--remove-label mode:supervised/);
+      assert.match(result.comment, /--add-label mode:headless/);
+    }
+  });
+
+  it('blocks a mode:supervised task with an unfinished dependency, rather than waiting for it', () => {
+    const board: Board = {
+      tasksById: { 'T-2': baseTask({ id: 'T-2', status: TASK_STATUS.IN_PROGRESS }) },
+    };
+    const task = baseTask({ mode: MODE.SUPERVISED, dependsOn: ['T-2'] });
+    const result = evaluateGuards(task, board, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.equal(result.reason, 'supervised-mode');
+    }
+  });
+
+  it('does not block a mode:headless task', () => {
+    const task = baseTask({ mode: MODE.HEADLESS });
+    const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.notEqual(result.kind, 'block');
+  });
+
+  // Evaluation order: a mode:supervised task has exactly ONE true verdict, regardless of what else
+  // is wrong with it — the task never needed any other guard's contract in the first place (its
+  // verification is not a dispatchable command at all), so no other guard may report first.
+  describe('wins over every other guard, even one that would also block', () => {
+    it('over guard 1 (missing Test command)', () => {
+      const task = baseTask({ mode: MODE.SUPERVISED, testCommand: null });
+      const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+      assert.equal(result.kind, 'block');
+      if (result.kind === 'block') {
+        assert.equal(result.reason, 'supervised-mode');
+      }
+    });
+
+    it('over guard 1c (a declared hard-list path)', () => {
+      const task = baseTask({ mode: MODE.SUPERVISED, filesToTouch: ['package.json'] });
+      const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+      assert.equal(result.kind, 'block');
+      if (result.kind === 'block') {
+        assert.equal(result.reason, 'supervised-mode');
+      }
+    });
+
+    it('over guard 1e (a declared supervised-only path)', () => {
+      const task = baseTask({
+        mode: MODE.SUPERVISED,
+        filesToTouch: ['packages/core-back/src/index.ts'],
+      });
+      const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+      assert.equal(result.kind, 'block');
+      if (result.kind === 'block') {
+        assert.equal(result.reason, 'supervised-mode');
+      }
+    });
+  });
+});
+
 // ── Guard 3: dependencies (wait vs block) ─────────────────────────────────────
 
 describe('evaluateGuards — guard 3: dependencies', () => {
@@ -1097,24 +1619,24 @@ describe("evaluateGuards — guard 4b: a subtask's parent branch missing from th
     }
   });
 
-  // T-15, acceptance criterion #2: a parent worked in an interactive session lives on a
-  // `feat/`/`fix/`/`refactor/` branch, never on `task/<id>` — its subtask must not stay blocked
-  // forever just because `task/T-4` itself was never created.
-  it("launches a subtask whose parent's DECLARED branch is on the remote, even though task/<parentId> is not", () => {
+  // T-52: the Worktree Gate now mandates `task/T-nn` for any task on the board, interactive or
+  // dispatched, so a subtask launches once ITS PARENT's `task/<parentId>` branch is on the remote —
+  // no separate declaration needed.
+  it("launches a subtask whose parent's task/<parentId> branch is on the remote", () => {
     const board: Board = {
       tasksById: {
-        'T-4': baseTask({ id: 'T-4', declaredBranch: 'fix/parent-branch-resolution' }),
+        'T-4': baseTask({ id: 'T-4' }),
       },
     };
     const task = baseTask({ parentId: 'T-4' });
     const result = evaluateGuards(task, board, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, [
       'main',
-      'fix/parent-branch-resolution',
+      'task/T-4',
     ]);
     assert.equal(result.kind, 'launch');
   });
 
-  // T-15, acceptance criterion #3: the failure names the candidates found on the remote, not just
+  // The failure names the candidates found on the remote, not just
   // the branch that was tried.
   it('names the candidate remote branches in the block comment when the base is missing', () => {
     const task = baseTask({ parentId: 'T-4' });
@@ -1140,13 +1662,16 @@ describe("evaluateGuards — guard 4b: a subtask's parent branch missing from th
     }
   });
 
-  // Fix round B4: before T-15, guard 4b never consulted the board at all, so a transient board-read
-  // failure could never affect it. Now it does — `tasksById[parentId]` is `undefined` both when the
-  // parent genuinely has no branch AND when THIS pass's `backlog task view <parentId>` simply threw
-  // (`dispatch.ts`'s `loadBoard` drops that task and reports the whole read `complete: false`). The
-  // two must not read the same: the first is a real, actionable block; the second must wait for a
-  // pass whose read succeeds, not instruct a person to push a branch that may already exist.
-  it('waits, never blocks, when the parent id is absent from an INCOMPLETE board read', () => {
+  // T-52 fix round B3: this guard used to also read `board.complete`/`board.tasksById` (T-15's
+  // declared-branch chain — a transient board-read failure could make a real declaration look
+  // absent), so an INCOMPLETE board read a subtask's missing base as "wait", not "block". Now that
+  // `resolveTaskBase` resolves purely off `task.parentId` and the live `remoteBranches` — never the
+  // board — board completeness has no bearing on the answer at all: it must block exactly the same
+  // whether the board read that pass was complete, incomplete, or the `complete` field is absent
+  // entirely. A guard that still waited here would leave a subtask stuck in `Queued` forever on a
+  // board read that fails persistently, even with `task/<parentId>` published and the resolution
+  // fully determined.
+  it('blocks on an INCOMPLETE board exactly as it would on a complete one — board completeness is irrelevant', () => {
     const incompleteBoard: Board = { tasksById: {}, complete: false };
     const task = baseTask({ parentId: 'T-4' });
     const result = evaluateGuards(
@@ -1157,25 +1682,14 @@ describe("evaluateGuards — guard 4b: a subtask's parent branch missing from th
       null,
       ['main'],
     );
-    assert.equal(result.kind, 'wait');
-  });
-
-  it('still blocks on a COMPLETE board when the parent genuinely cannot be resolved', () => {
-    const completeBoard: Board = { tasksById: {}, complete: true };
-    const task = baseTask({ parentId: 'T-4' });
-    const result = evaluateGuards(task, completeBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, [
-      'main',
-    ]);
     assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.equal(result.reason, 'missing-parent-branch');
+    }
   });
 
-  it('resolves normally on an incomplete board when the PARENT itself was read (only some other task failed)', () => {
-    const incompleteBoard: Board = {
-      tasksById: {
-        'T-4': baseTask({ id: 'T-4', declaredBranch: 'fix/parent-branch-resolution' }),
-      },
-      complete: false,
-    };
+  it('launches on an INCOMPLETE board too, once task/<parentId> is on the remote', () => {
+    const incompleteBoard: Board = { tasksById: {}, complete: false };
     const task = baseTask({ parentId: 'T-4' });
     const result = evaluateGuards(
       task,
@@ -1183,23 +1697,25 @@ describe("evaluateGuards — guard 4b: a subtask's parent branch missing from th
       freeSlots(),
       DEFAULT_DISPATCH_LIMITS,
       null,
-      ['main', 'fix/parent-branch-resolution'],
+      ['main', 'task/T-4'],
     );
     assert.equal(result.kind, 'launch');
   });
 
-  it('defaults to "complete" when board.complete is omitted, unchanged from before this fix round', () => {
-    const boardWithNoCompleteField: Board = { tasksById: {} };
+  it('resolves the same whether board.complete is true, false, or omitted entirely', () => {
     const task = baseTask({ parentId: 'T-4' });
-    const result = evaluateGuards(
-      task,
-      boardWithNoCompleteField,
-      freeSlots(),
-      DEFAULT_DISPATCH_LIMITS,
-      null,
-      ['main'],
+    const outcomes = [{ complete: true }, { complete: false }, {}].map(
+      (fields) =>
+        evaluateGuards(
+          task,
+          { tasksById: {}, ...fields },
+          freeSlots(),
+          DEFAULT_DISPATCH_LIMITS,
+          null,
+          ['main'],
+        ).kind,
     );
-    assert.equal(result.kind, 'block');
+    assert.deepEqual(outcomes, ['block', 'block', 'block']);
   });
 });
 
@@ -1479,6 +1995,15 @@ describe('evaluateGuards — evaluation order', () => {
     }
   });
 
+  it('reports supervised-mode before checking dependencies', () => {
+    const task = baseTask({ mode: MODE.SUPERVISED, dependsOn: ['unknown'] });
+    const result = evaluateGuards(task, emptyBoard, freeSlots(), DEFAULT_DISPATCH_LIMITS, null, []);
+    assert.equal(result.kind, 'block');
+    if (result.kind === 'block') {
+      assert.equal(result.reason, 'supervised-mode');
+    }
+  });
+
   it('reports the unmet dependency before the security-path check', () => {
     const securityFile = SECURITY_PATH_PATTERNS[0];
     const board: Board = {
@@ -1511,79 +2036,47 @@ describe('evaluateGuards — evaluation order', () => {
   });
 });
 
-// ── taskBaseBranch / resolveTaskBase: the resolution chain (T-14 → T-15) ─────────
+// ── taskBaseBranch / resolveTaskBase: the resolution (T-14, T-15 → T-52) ─────────
 //
-// T-15: a subtask's base is DEDUCED no longer — `task/<parentId>` is only the FALLBACK once the
-// parent has declared no real branch (`Task.declaredBranch`, `task-view.ts`'s `parseDeclaredBranch`
-// reading the parent's own "Branch:" description line). A parent worked in an interactive session
-// lives on a `feat/`/`fix/`/`refactor/` branch per the root `CLAUDE.md`'s Worktree Gate, never on
-// `task/<id>` — this is the declaration that lets such a parent's subtasks dispatch at all.
+// T-52 retired the T-15 declared-branch chain: the root `CLAUDE.md`'s Worktree Gate now mandates
+// `task/T-nn` for ANY task on the board, interactive or dispatched, so `task/<parentId>` is the
+// ONLY answer — a pure deduction from the id, never read off the parent's own description.
 
 describe('taskBaseBranch', () => {
-  it("names a top-level task's base main, regardless of tasksById", () => {
-    assert.equal(taskBaseBranch({ parentId: undefined }, {}), 'main');
-  });
-
-  it("falls back to task/<parentId> when the parent declared no branch", () => {
-    assert.equal(taskBaseBranch({ parentId: 'T-4' }, {}), 'task/T-4');
+  it("names a top-level task's base main", () => {
+    assert.equal(taskBaseBranch({ parentId: undefined }), 'main');
   });
 
-  it("falls back to task/<parentId> when the parent is not even in tasksById", () => {
-    assert.equal(
-      taskBaseBranch({ parentId: 'T-4' }, { 'T-9': { declaredBranch: 'feat/unrelated' } }),
-      'task/T-4',
-    );
-  });
-
-  it("uses the parent's DECLARED branch when it named one — never task/<parentId>", () => {
-    assert.equal(
-      taskBaseBranch(
-        { parentId: 'T-4' },
-        { 'T-4': { declaredBranch: 'fix/parent-branch-resolution' } },
-      ),
-      'fix/parent-branch-resolution',
-    );
-  });
-
-  it('treats an empty declared branch the same as no declaration at all', () => {
-    assert.equal(taskBaseBranch({ parentId: 'T-4' }, { 'T-4': { declaredBranch: '' } }), 'task/T-4');
+  it('names a subtask base task/<parentId>', () => {
+    assert.equal(taskBaseBranch({ parentId: 'T-4' }), 'task/T-4');
   });
 });
 
 describe('resolveTaskBase', () => {
   it('a top-level task is always ok, regardless of the remote list', () => {
-    assert.deepEqual(resolveTaskBase({ parentId: undefined }, {}, []), {
+    assert.deepEqual(resolveTaskBase({ parentId: undefined }, []), {
       kind: 'ok',
       branch: 'main',
     });
   });
 
-  it("a subtask is ok when its parent's task/<id> branch is on the remote (no declaration)", () => {
-    assert.deepEqual(resolveTaskBase({ parentId: 'T-4' }, {}, ['main', 'task/T-4']), {
+  it("a subtask is ok when its parent's task/<id> branch is on the remote", () => {
+    assert.deepEqual(resolveTaskBase({ parentId: 'T-4' }, ['main', 'task/T-4']), {
       kind: 'ok',
       branch: 'task/T-4',
     });
   });
 
-  it("a subtask is ok when its parent's DECLARED branch is on the remote", () => {
-    const tasksById = { 'T-4': { declaredBranch: 'fix/parent-branch-resolution' } };
-    assert.deepEqual(
-      resolveTaskBase({ parentId: 'T-4' }, tasksById, ['main', 'fix/parent-branch-resolution']),
-      { kind: 'ok', branch: 'fix/parent-branch-resolution' },
-    );
-  });
-
-  it("a subtask is missing-parent-branch when NEITHER the declared branch nor task/<id> is on the remote", () => {
-    const tasksById = { 'T-4': { declaredBranch: 'fix/parent-branch-resolution' } };
-    const result = resolveTaskBase({ parentId: 'T-4' }, tasksById, ['main']);
+  it("a subtask is missing-parent-branch when task/<id> is not on the remote", () => {
+    const result = resolveTaskBase({ parentId: 'T-4' }, ['main']);
     assert.equal(result.kind, 'missing-parent-branch');
     if (result.kind === 'missing-parent-branch') {
-      assert.equal(result.branch, 'fix/parent-branch-resolution');
+      assert.equal(result.branch, 'task/T-4');
     }
   });
 
   it('names candidate remote branches mentioning the parent id when the base is missing', () => {
-    const result = resolveTaskBase({ parentId: 'T-4' }, {}, ['main', 'wip-T-4-not-pushed-right']);
+    const result = resolveTaskBase({ parentId: 'T-4' }, ['main', 'wip-T-4-not-pushed-right']);
     assert.equal(result.kind, 'missing-parent-branch');
     if (result.kind === 'missing-parent-branch') {
       assert.deepEqual(result.candidates, ['wip-T-4-not-pushed-right']);
@@ -1591,7 +2084,7 @@ describe('resolveTaskBase', () => {
   });
 
   it('reports no candidates when nothing on the remote mentions the parent id at all', () => {
-    const result = resolveTaskBase({ parentId: 'T-4' }, {}, ['main', 'task/T-9']);
+    const result = resolveTaskBase({ parentId: 'T-4' }, ['main', 'task/T-9']);
     assert.equal(result.kind, 'missing-parent-branch');
     if (result.kind === 'missing-parent-branch') {
       assert.deepEqual(result.candidates, []);
@@ -1605,7 +2098,7 @@ describe('resolveTaskBase', () => {
     // T-15's own branch is on the remote, so resolving T-15 itself launches — nothing to prove
     // there. The trap is on the OTHER side: T-1's base is missing, and T-15/T-19/T-100's branches
     // (each containing "T-1" as a literal substring) sit on the remote as decoys.
-    const forT1 = resolveTaskBase({ parentId: 'T-1' }, {}, [
+    const forT1 = resolveTaskBase({ parentId: 'T-1' }, [
       'main',
       'wip-T-1-rescue',
       'task/T-15',
@@ -1621,7 +2114,7 @@ describe('resolveTaskBase', () => {
   // The dotted-subtask continuation: `T-4.2` names a DIFFERENT task than `T-4`, so a candidate
   // search for T-4 must not treat `T-4.2`'s branch as mentioning T-4.
   it('does not treat a dotted subtask id (T-4.2) as mentioning its parent id (T-4)', () => {
-    const result = resolveTaskBase({ parentId: 'T-4' }, {}, ['main', 'task/T-4.2']);
+    const result = resolveTaskBase({ parentId: 'T-4' }, ['main', 'task/T-4.2']);
     assert.equal(result.kind, 'missing-parent-branch');
     if (result.kind === 'missing-parent-branch') {
       assert.deepEqual(result.candidates, []);
@@ -1631,7 +2124,7 @@ describe('resolveTaskBase', () => {
   // Optional fix-round item: the candidate list is diagnostic only (it names branches for a PERSON
   // to look at), so a lower-cased rescue branch is still worth surfacing.
   it('matches the parent id case-insensitively, so a lower-cased rescue branch still surfaces', () => {
-    const result = resolveTaskBase({ parentId: 'T-4' }, {}, ['main', 'wip-t-4-rescue']);
+    const result = resolveTaskBase({ parentId: 'T-4' }, ['main', 'wip-t-4-rescue']);
     assert.equal(result.kind, 'missing-parent-branch');
     if (result.kind === 'missing-parent-branch') {
       assert.deepEqual(result.candidates, ['wip-t-4-rescue']);