@polymorphism-tech/morph-spec 8.35.1 → 8.36.0

package/src/lib/tasks/test-scope.js

@@ -0,0 +1,567 @@
+/**
+ * Test Scope — which test nodes a TASK-scoped `verify {feature} {task}` runs,
+ * and which tests inside each node (issue #87).
+ *
+ * GHLBrain ran its whole suite 121 times in 8 days from the per-task loop — about
+ * five hours a week — because a task-scoped verify had no way to run less. The
+ * feature-scoped verify (Gate 3) keeps running everything; this module only
+ * DECIDES the task-scoped cut, verify-runner executes it (task B4).
+ *
+ * Two independent decisions:
+ *   1. selection — the task's `group` picks the nodes (`effectiveGroups`);
+ *   2. narrowing — the task's `outputs` narrow the command INSIDE each node.
+ *
+ * The declared command is literal and nobody's parser owns it, so narrowing is
+ * string surgery on a short list of shapes that were read and, where it
+ * mattered, measured (test/fixtures/test-output/README.md). Anything else runs
+ * WHOLE with a reason: a narrowing that guesses runs the wrong tests or none,
+ * and a run of none is the green that issue #87 must never buy.
+ *
+ * Pure: reads files (and one environment variable, TESTINGPLATFORM_EXITCODE_IGNORE),
+ * never spawns a process.
+ *
+ * @module test-scope
+ */
+
+import { readFileSync, statSync } from 'fs';
+import { dirname, relative, resolve } from 'path';
+
+import { effectiveGroups } from './test-nodes.js';
+import { canonicalPath, extractCsprojTargets, isInside } from './test-runner.js';
+import { normalizePath } from '../validators/traceability-check.js';
+import { samePathCase } from '../worktree/docker-audit.js';
+import {
+  csharpClasses, declaresCaseFilter, dotnetTestMode, dotnetTestProjectOf, ignoresExitCode, imposesMinimumExpected,
+  isDotnetSource, isDotnetTestProject, nearestCsprojOf, nearestProjectOf, readsLikeTestSource,
+} from './dotnet-test-introspection.js';
+
+// Part of this module's API (task B3); implemented beside the rest of the .NET introspection.
+export { dotnetTestMode, classNamesOf } from './dotnet-test-introspection.js';
+
+/**
+ * The per-node decision B4 consumes (`preDecideRun` skips `out-of-scope`;
+ * `judgeRun` reads `mode`/`zeroGuard`). `null` — in fact absent — at feature scope.
+ *
+ * @typedef {Object} TestSelection
+ * @property {'narrowed'|'whole'|'out-of-scope'|'full'} mode
+ *   - `narrowed`: `node.command` was rewritten to run only the task's tests. Its
+ *     count is PARTIAL: never compare it with `expectedCount` (the whole-suite
+ *     baseline, left untouched on the node), and a pass without proof that tests
+ *     ran is not a pass — see `zeroGuard`.
+ *   - `whole`: selected, runs its declared command unchanged; `reason` says why.
+ *   - `out-of-scope`: must not run at this task scope; `reason` says why.
+ *   - `full`: `--full` — declared command unchanged, no recorte by request.
+ * @property {string|null} reason - Why whole/out-of-scope; null when narrowed.
+ * @property {string|null} declaredCommand - The command as declared, before narrowing.
+ * @property {string[]} files - Task test files this node owns (project-relative,
+ *   `/`, spelled as on disk): inside its cwd, or — dotnet — belonging to a
+ *   `.csproj` a link of its command names, wherever they sit (ownership is the
+ *   link's project, never the cwd).
+ * @property {string[]} selectors - What the narrowed command selects: BARE type
+ *   names (dotnet — every class/record/struct/interface of the task's test files,
+ *   no namespace, each matched namespace-free as `--filter-class "*T*"` (MTP +
+ *   xunit.v3, measured) or the substring `FullyQualifiedName~T`, so any namespace,
+ *   nested `Outer+Inner` and prefix siblings are covered: a SUPERSET of the file's
+ *   tests, never a subset) or paths relative to the node cwd (vitest/jest). `[]`
+ *   unless narrowed.
+ * @property {'count'|'mtp-exit-8'|null} zeroGuard - How a narrowed run proves tests
+ *   ran: `count` = only a parsed count > 0 proves it (VSTest exits 0 on an empty
+ *   filter; vitest/jest print a string); `mtp-exit-8` = MTP exits 8 on zero tests,
+ *   so exit 0 is proof. null unless narrowed.
+ */
+
+const NO_TEST_FILE = 'no test file from task outputs in this node — running it whole';
+const SHAPE = 'command shape not recognised for narrowing — running it whole';
+/**
+ * Measured (test/fixtures/test-output/mtp-minimum-expected-cli-override-ignored.txt):
+ * `--minimum-expected-tests 1` on the CLI does NOT override the project's floor —
+ * a green narrowed run still exits 9. So a project that imposes it runs whole
+ * rather than produce a red that no test caused. Wording pinned by the plan.
+ */
+const MIN_EXPECTED = 'projeto impõe --minimum-expected-tests; recorte desligado';
+const FILTER_TAKEN = 'command already carries a test filter — a second one would replace it; running it whole';
+const CASE_FILTER = 'project declares <VSTestTestCaseFilter> — an appended --filter would replace it; running it whole';
+/**
+ * Final review F3: under MTP a narrowed run's proof that tests ran is exit 0 (zero
+ * tests exit 8). Whatever makes MTP ignore an exit code takes that proof away —
+ * zero tests then exit 0 — so the node runs whole. The COMMAND is read by
+ * FLOOR_OR_IGNORE; these two are the project (ignoresExitCode) and the environment.
+ */
+const IGNORE_EXIT_PROJECT = 'project makes MTP ignore an exit code (--ignore-exit-code / TESTINGPLATFORM_EXITCODE_IGNORE in its MSBuild files or testconfig) — exit 0 would no longer prove that tests ran; running it whole';
+const IGNORE_EXIT_ENV = 'TESTINGPLATFORM_EXITCODE_IGNORE is set in the environment — MTP may exit 0 on zero tests, so exit 0 would no longer prove that tests ran; running it whole';
+
+const CLASS_NAME = /^[A-Za-z0-9_.]+$/;
+/** Characters that change meaning inside double quotes in `sh` (the `--linux` container) or `cmd.exe`. */
+const UNSAFE_IN_QUOTES = /["$`%!]/;
+const JS_TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)__tests__\/.+\.[cm]?[jt]sx?$/;
+const JS_SOURCE = /\.[cm]?[jt]sx?$/i;
+/** Read in the RAW text of a JS/TS output the recogniser did not classify as a test file (the .NET markers: readsLikeTestSource). */
+const JS_TEST_CALL = /^[ \t]*(?:describe|it|test)(?:\.\w+)*\s*\(/m;
+const EXISTING_FILTER = /(^|\s)--(?:treenode-)?filter(?=$|[\s=-])/;
+/** As a flag, or inside `-p:TestingPlatformCommandLineArguments=…` (preceded by `=` or a quote). */
+const FLOOR_OR_IGNORE = /(^|[\s="'])--(?:ignore-exit-code|minimum-expected-tests)(?=$|[\s="'])/;
+const MTP_FRAMEWORKS = new Set(['xunit.v3', 'mstest', 'nunit']);
+
+const toPosix = (p) => String(p).replace(/\\/g, '/');
+const samePath = (a, b) => isInside(a, b) && isInside(b, a);
+const whole = (reason) => ({ command: null, selectors: [], zeroGuard: null, reason });
+
+const isFile = (path) => { try { return statSync(path).isFile(); } catch { return false; } };
+const isDirectory = (path) => { try { return statSync(path).isDirectory(); } catch { return false; } };
+
+/**
+ * The on-disk spelling of a path inside the root (#87 F4). A mis-cased output
+ * resolves on a case-insensitive disk and was forwarded verbatim; the `--linux`
+ * container is case-sensitive, and jest `--runTestsByPath` skips a path it cannot
+ * find while a sibling keeps the count above zero. `canonicalPath` (test-runner.js)
+ * is the one spelling, and only its CASE is taken: a path it moves ELSEWHERE — a
+ * symlink or junction, inside the root or out of it — keeps the plain spelling, so a
+ * file never changes node (re-review N3: `web/src/shared` → `libs/shared` left the
+ * `web` node narrowed past it). Case is compared by `samePathCase` (docker-audit.js),
+ * the one copy of that rule.
+ */
+function spelled(abs, rootAbs) {
+  const real = canonicalPath(abs);
+  return isInside(real, rootAbs) && samePathCase(real) === samePathCase(abs) ? real : abs;
+}
+
+/** The project root as on disk: every path compared with it is spelled the same way (F4). */
+const rootOf = (projectPath) => canonicalPath(resolve(projectPath));
+const cwdOf = (node, rootAbs) => spelled(resolve(rootAbs, node?.cwd || '.'), rootAbs);
+
+/**
+ * Task outputs → the existing FILES and DIRECTORIES among them, absolute and
+ * spelled as on disk; ghosts dropped. A directory is kept apart and never
+ * narrows: which of its files the task touched cannot be told (forcedWhole).
+ */
+function existingEntries(outputs, rootAbs) {
+  const files = new Set();
+  const dirs = new Set();
+  for (const o of outputs || []) {
+    if (typeof o !== 'string' || !o.trim()) continue;
+    const abs = resolve(rootAbs, normalizePath(o.trim()));
+    if (isFile(abs)) files.add(spelled(abs, rootAbs));
+    else if (isDirectory(abs)) dirs.add(spelled(abs, rootAbs));
+  }
+  return { files: [...files], dirs: [...dirs] };
+}
+
+/** Is this file a test file for THIS runner? (A `.cs` file is nothing to a vitest node.) */
+function isTestFileFor(runner, fileAbs, rootAbs) {
+  const js = JS_TEST_FILE.test(toPosix(relative(rootAbs, fileAbs)));
+  if (runner === 'dotnet' || runner === 'evals') return dotnetTestProjectOf(fileAbs, rootAbs) !== null;
+  if (['vitest', 'jest', 'node-test', 'playwright'].includes(runner)) return js;
+  return js || dotnetTestProjectOf(fileAbs, rootAbs) !== null;
+}
+
+const readRaw = (path) => { try { return readFileSync(path, 'utf8'); } catch { return null; } };
+
+/**
+ * An output the recogniser did NOT classify as a test file for this runner but
+ * that READS like one in its raw text: a `.cs` carrying a test marker
+ * (readsLikeTestSource — loose on purpose), or a JS/TS file with a top-level
+ * `describe`/`it`/`test` call. Recognition is a heuristic (csproj name or packages
+ * listed in the csproj itself; file-name pattern) — a touched test file it misses
+ * would be dropped from `owned`, and the recognised files would narrow the node
+ * PAST it: a green run that skipped a touched class. Such a file is named and the
+ * node runs whole (and is never scoped out). Non-C# .NET sources: forcedWhole.
+ */
+function unrecognisedTestFile(runner, fileAbs, rootAbs) {
+  if (isTestFileFor(runner, fileAbs, rootAbs)) return false;
+  const dotnet = runner === 'dotnet' || runner === 'evals';
+  if (/\.cs$/i.test(fileAbs)) return dotnet && readsLikeTestSource(fileAbs);
+  if (JS_SOURCE.test(fileAbs)) return !dotnet && JS_TEST_CALL.test(readRaw(fileAbs) ?? '');
+  return false;
+}
+
+/**
+ * An output the recorte cannot narrow on, for THIS node: the reason to run it
+ * whole — and never scope it out — or null. The final review of branch B found
+ * both shapes narrowing PAST touched tests:
+ * - F1: an existing DIRECTORY overlapping the node's cwd or the folder of a
+ *   project a link names (either one containing the other). Dropped as "not a
+ *   file", it let the task's other files narrow the node while the tests inside
+ *   it never ran — and the count guard passed on the ones that did.
+ * - F2 (dotnet): ANY non-`.cs` file this node may run — inside its cwd, or its
+ *   nearest project is one a link names — whose nearest project is a TEST project
+ *   (a bUnit `.razor`, a Reqnroll/SpecFlow `.feature`, a Verify `.verified.txt`, test
+ *   data; re-review N2: a list of source kinds let the `.feature` through), or that
+ *   reads like a test (readsLikeTestSource: `.razor`/`.cshtml`/`.fs`/`.fsi`/`.fsx`/`.vb`
+ *   outside a recognised test project). It yields no selector, and the tests it feeds
+ *   may sit in files the task did not touch, so a recorte skips them.
+ */
+function forcedWhole(node, entries, cwdAbs, rootAbs) {
+  const rel = (abs) => toPosix(relative(rootAbs, abs)) || '.';
+  const targets = node?.runner === 'dotnet' ? extractCsprojTargets(node.command).map((t) => resolve(cwdAbs, t)) : [];
+  const areas = [cwdAbs, ...targets.map((t) => dirname(t))];
+  const dir = entries.dirs.find((d) => areas.some((a) => isInside(d, a) || isInside(a, d)));
+  if (dir) {
+    return `output "${rel(dir)}" is a directory — which of its files the task touched cannot be told, and a recorte would skip them; running it whole`;
+  }
+  if (node?.runner !== 'dotnet') return null;
+  const source = entries.files.find((abs) => {
+    if (/\.cs$/i.test(abs)) return false;
+    const project = nearestProjectOf(abs, rootAbs);
+    const mayRun = isInside(abs, cwdAbs) || (project !== null && targets.some((t) => samePath(t, project)));
+    return mayRun && (inTestProject(abs, rootAbs) || readsLikeTestSource(abs));
+  });
+  if (source) {
+    return `output file "${rel(source)}" is a test source the recorte cannot read — not C#, and it belongs to a test project or reads like a test; running it whole`;
+  }
+  return null;
+}
+
+/** The file belongs to a .NET test project: its nearest `.csproj`/`.fsproj`/`.vbproj` is one (N2). */
+function inTestProject(abs, rootAbs) {
+  const project = nearestProjectOf(abs, rootAbs);
+  return project !== null && isDotnetTestProject(project);
+}
+
+/**
+ * The `.cs` outputs a LINK of the command owns through its `.csproj` — wherever
+ * the file sits, recognised as a test file or not (the caller decides which of
+ * the two questions it is asking). A link's ownership is decided by the link's
+ * project, never by the node cwd: `cd tests/A.Tests && dotnet test --project
+ * ../B.Tests/B.Tests.csproj` runs B's tests, so a touched `tests/B.Tests/XTests.cs`
+ * belongs to that link and must select on it (round 5: it was dropped as
+ * "outside the cwd", and the link with it — XTests never ran). A bare link keeps
+ * the cwd rule: it runs what its cwd resolves, and a file outside is not its business.
+ */
+function linkedOutputs(command, filesAbs, cwdAbs, rootAbs) {
+  const targets = extractCsprojTargets(command).map((t) => resolve(cwdAbs, t));
+  if (targets.length === 0) return [];
+  return filesAbs.filter((abs) => {
+    const csproj = nearestCsprojOf(abs, rootAbs);
+    return csproj !== null && targets.some((t) => samePath(t, csproj));
+  });
+}
+
+/**
+ * The first project target a command names that is NOT an existing `.csproj`
+ * inside the project root — as `extractCsprojTargets` spells it — or null.
+ *
+ * Link ownership is decided by the link's csproj (linkedOutputs), so a target
+ * the recorte cannot resolve turns every ownership answer into a guess, and the
+ * guess was "owns nothing": the link was DROPPED, and with it the touched class
+ * (B3 final review — compiled, exit 0, the class never ran). Two shapes reach
+ * here: `--project=PATH` / `--project:PATH`, which `extractCsprojTargets` returns
+ * as ONE token, flag included (resolved, it names nothing), and a csproj OUTSIDE
+ * the root, which `nearestCsprojOf` never walks to. `extractCsprojTargets` keeps
+ * its semantics for its other callers; this only refuses what it cannot match.
+ */
+function unresolvedProjectTarget(command, cwdAbs, rootAbs) {
+  return extractCsprojTargets(command).find((target) => {
+    const abs = resolve(cwdAbs, target);
+    return !/\.csproj$/i.test(abs) || !isFile(abs) || !isInside(abs, rootAbs);
+  }) ?? null;
+}
+
+const strayProject = (target) => whole(`command names project "${target}", which is not an existing .csproj inside the project root — the task's files cannot be matched to its link; running it whole`);
+
+/**
+ * The flags of a link that names no csproj, ready to follow a re-pointed
+ * project — or null when it names a target that cannot be re-pointed.
+ * Re-pointing keeps the class filter off projects that do not own the class:
+ * under MTP each of them exits 8, under VSTest each prints "No test matches the
+ * given testcase filter" — a zero-test signature on a green run (false red).
+ * MTP: a solution/folder target → null. VSTest: a `.sln` token is dropped (the
+ * csproj replaces it); a folder → null. A target FLAG — `--solution`,
+ * `--directory`, `--test-modules`, `--project` — → null in either spelling: as
+ * its own token, or with its value after `=`/`:` in ONE token (final review C2:
+ * that spelling was kept, the link re-pointed and filtered, and the `dotnet` CLI
+ * refused the narrowed command — a red with no culprit test). A `--project` left
+ * for this function never names a csproj: extractCsprojTargets took those, and
+ * `--project=X.csproj` runs whole by unresolvedProjectTarget before reaching here.
+ */
+function retargetFlags(link, mode, cwdAbs) {
+  let refused = false;
+  const flags = link.replace(/^dotnet\s+test/, '').replace(/(\s*)("[^"]*"|'[^']*'|\S+)/g, (all, _ws, raw) => {
+    const value = raw.replace(/^(["'])(.*)\1$/, '$2');
+    if (value.startsWith('-')) {
+      if (/^--(?:solution|directory|test-modules|project)(?:[=:]|$)/.test(value)) refused = true;
+      return all;
+    }
+    if (/\.slnx?f?$/i.test(value)) {
+      if (mode === 'mtp') refused = true;
+      return '';
+    }
+    if (isDirectory(resolve(cwdAbs, value))) refused = true;
+    return all;
+  });
+  return refused ? null : flags;
+}
+
+function selectorArgs(mode, framework, classes) {
+  // Namespace-free by construction (R1). Measured (test/fixtures/test-output/
+  // mtp-filter-class-any-namespace*.txt): `--filter-class "*Outer*"` runs Outer in
+  // EVERY namespace, its nested Outer+Inner classes and prefix siblings; the exact
+  // name runs Outer alone (mtp-filter-class-exact-skips-nested.txt) and a prefix
+  // without the namespace runs NOTHING (mtp-filter-class-prefix-without-namespace-
+  // zero.txt, exit 8). `FullyQualifiedName~T` is a substring of the FQN: same superset.
+  if (mode === 'mtp' && framework === 'xunit.v3') return classes.map((c) => `--filter-class "*${c}*"`).join(' ');
+  return `--filter "${classes.map((c) => `FullyQualifiedName~${c}`).join('|')}"`;
+}
+
+const classesOf = (files) => [...new Set(files.flatMap((f) => f.types))];
+
+function narrowDotnet(command, owned, cwdAbs, rootAbs) {
+  if (/[;|]/.test(command) || /(^|[^&])&(?!&)/.test(command)) return whole(SHAPE);
+  const links = command.split('&&').map((l) => l.trim());
+  if (links.some((l) => !/^dotnet\s+test(\s|$)/.test(l))) return whole(SHAPE);
+  if (links.some((l) => EXISTING_FILTER.test(l))) return whole(FILTER_TAKEN);
+  if (links.some((l) => /(^|\s)--(\s|$)/.test(l))) return whole('command passes arguments after "--" — running it whole');
+  if (links.some((l) => FLOOR_OR_IGNORE.test(l))) {
+    return whole('command carries --ignore-exit-code/--minimum-expected-tests — a recorte would be judged by the wrong exit; running it whole');
+  }
+  if (process.env.TESTINGPLATFORM_EXITCODE_IGNORE?.trim()) return whole(IGNORE_EXIT_ENV);
+
+  const mode = dotnetTestMode(cwdAbs);
+  if (mode === null) return whole('global.json unreadable — cannot tell VSTest from MTP; running it whole');
+
+  const files = owned.map((abs) => ({ abs, inside: isInside(abs, cwdAbs), ...dotnetTestProjectOf(abs, rootAbs), ...csharpClasses(abs) }));
+  // The PROJECT binds the run, in either mode: a floor exits 9 on a green
+  // recorte (MTP, or MTP through the VSTest bridge), and a declared case filter
+  // is REPLACED by an appended --filter (`Category!=Eval` silently gone).
+  const projects = [...new Set(files.map((f) => f.csproj))];
+  if (projects.some((p) => imposesMinimumExpected(p, rootAbs))) return whole(MIN_EXPECTED);
+  if (projects.some((p) => ignoresExitCode(p, rootAbs))) return whole(IGNORE_EXIT_PROJECT);
+  if (projects.some((p) => declaresCaseFilter(p, rootAbs))) return whole(CASE_FILTER);
+  if (mode === 'mtp') {
+    const other = files.find((f) => !MTP_FRAMEWORKS.has(f.framework));
+    if (other) return whole(`MTP test project uses a framework with no known class filter (${other.framework ?? 'unknown'}) — running it whole`);
+  }
+
+  // Selectors are the files' BARE type names at any depth, matched namespace-free
+  // (`--filter-class "*T*"` / `FullyQualifiedName~T`): no namespace, scope or depth
+  // reading can misname a type, and a misread only ADDS a selector. A MISSED type
+  // is what must never happen — and `scannable` means exactly that every type
+  // keyword of the RAW text is a named declaration (csharpClasses states the
+  // guarantee and its limits); else the file is untrusted and never narrows.
+  const unscannable = files.find((f) => !f.scannable);
+  if (unscannable) {
+    const rel = toPosix(relative(rootAbs, unscannable.abs));
+    return whole(`test file "${rel}" could not be scanned safely (${unscannable.why}) — running it whole`);
+  }
+  // R3: an abstract class's tests run under the names of its DERIVED classes —
+  // declared in files the task may not have touched, so no selector here names them.
+  const abstractFile = files.find((f) => f.abstract.length > 0);
+  if (abstractFile) {
+    const rel = toPosix(relative(rootAbs, abstractFile.abs));
+    return whole(`test file "${rel}" declares an abstract class (${abstractFile.abstract.join(', ')}) — its tests run under derived classes' names, possibly in files the task did not touch; running it whole`);
+  }
+  if (!files.some((f) => f.hasTestClass)) return whole('no test class found in the task\'s test files — running it whole');
+  // Round 5: a test-project file WITHOUT a test attribute is a helper, fake or
+  // fixture. Its types select nothing (`*FakeClock*` → exit 8, a red no test
+  // earned) while the tests that USE it live in files the task did not touch.
+  const helper = files.find((f) => !f.hasTestAttribute);
+  if (helper) {
+    const rel = toPosix(relative(rootAbs, helper.abs));
+    return whole(`test file "${rel}" carries no test attribute ([Fact]/[Theory]/[Test…]) — a helper, fake or fixture whose tests live in files the task did not touch; running it whole`);
+  }
+  const unsafe = classesOf(files).find((c) => !CLASS_NAME.test(c));
+  if (unsafe) return whole(`type name "${unsafe}" is not safe to pass as a filter — running it whole`);
+
+  const out = [];
+  for (const link of links) {
+    const targets = extractCsprojTargets(link).map((t) => resolve(cwdAbs, t));
+    if (targets.length > 0) {
+      const mine = files.filter((f) => targets.some((t) => samePath(t, f.csproj)));
+      const classes = classesOf(mine);
+      if (classes.length > 0) out.push(`${link} ${selectorArgs(mode, mine[0].framework, classes)}`);
+      continue; // a link whose project owns none of the files is dropped
+    }
+    const flags = retargetFlags(link, mode, cwdAbs);
+    if (flags === null) return whole('command targets a solution or folder the recorte cannot re-point — running it whole');
+    // A bare link runs what its cwd resolves: re-point it to the projects of the
+    // files INSIDE the cwd only (a linked file outside belongs to its own link).
+    for (const csproj of [...new Set(files.filter((f) => f.inside).map((f) => f.csproj))]) {
+      const rel = toPosix(relative(cwdAbs, csproj));
+      if (UNSAFE_IN_QUOTES.test(rel)) return whole(`path "${rel}" has a character unsafe inside quotes — running it whole`);
+      const mine = files.filter((f) => f.csproj === csproj && f.inside);
+      const classes = classesOf(mine);
+      const target = mode === 'mtp' ? `--project "${rel}"` : `"${rel}"`;
+      if (classes.length > 0) out.push(`dotnet test ${target}${flags} ${selectorArgs(mode, mine[0].framework, classes)}`);
+    }
+  }
+  if (out.length === 0) {
+    return whole('no link of the command runs the test project owning the task\'s test files — running it whole');
+  }
+  return {
+    command: out.join(' && '),
+    selectors: classesOf(files),
+    zeroGuard: mode === 'mtp' ? 'mtp-exit-8' : 'count',
+    reason: null,
+  };
+}
+
+function narrowJs(runner, command, owned, cwdAbs) {
+  const single = !/[;&|]/.test(command) && !/^\s*(?:npm|pnpm|yarn|bun)\s+run(?:-script)?\b/.test(command);
+  const shaped = runner === 'vitest'
+    ? /\bvitest\b/.test(command) && /(^|\s)(?:--)?run(\s|$)/.test(command)
+    : /\bjest\b/.test(command);
+  if (!single || !shaped) return whole(SHAPE);
+  const rels = owned.map((abs) => toPosix(relative(cwdAbs, abs)));
+  const unsafe = rels.find((r) => UNSAFE_IN_QUOTES.test(r));
+  if (unsafe) return whole(`path "${unsafe}" has a character unsafe inside quotes — running it whole`);
+  const quoted = rels.map((r) => `"${r}"`).join(' ');
+  return {
+    command: `${command.trim()} ${runner === 'jest' ? `--runTestsByPath ${quoted}` : quoted}`,
+    selectors: rels,
+    zeroGuard: 'count',
+    reason: null,
+  };
+}
+
+/**
+ * Narrow ONE node's command to the task's test files it owns.
+ *
+ * @param {import('./test-nodes.js').TestNode} node
+ * @param {string[]} testFiles - Task output paths (project-relative or absolute),
+ *   spelled as on disk before anything reads them (F4). Only EXISTING files that
+ *   are test files for its runner are narrowed on: those inside the node cwd, plus
+ *   (dotnet) those a link's `.csproj` owns wherever they sit (linkedOutputs). The
+ *   node runs whole rather than skip anything when an output is a directory it
+ *   may hold, or (dotnet) a non-C# test source it may compile (forcedWhole); when
+ *   a candidate — inside the cwd OR compiled by a link's `.csproj` — merely READS
+ *   like a test file (see unrecognisedTestFile); and when a dotnet command names a
+ *   project that is not an existing `.csproj` inside the root
+ *   (unresolvedProjectTarget): no file could be matched to that link at all.
+ * @param {string} projectPath
+ * @returns {{ command: string|null, selectors: string[], zeroGuard: 'count'|'mtp-exit-8'|null, reason: string|null }}
+ *   `command` null ⇒ run the declared command whole, and `reason` says why.
+ */
+export function narrowNode(node, testFiles, projectPath = '.') {
+  const rootAbs = rootOf(projectPath);
+  const cwdAbs = cwdOf(node, rootAbs);
+  if (!['dotnet', 'vitest', 'jest'].includes(node?.runner)) {
+    return whole(`runner "${node?.runner}" has no in-node narrowing — running it whole`);
+  }
+  if (typeof node.command !== 'string' || !node.command.trim()) return whole('node has no command to narrow');
+  if (node.runner === 'dotnet') {
+    const stray = unresolvedProjectTarget(node.command, cwdAbs, rootAbs);
+    if (stray) return strayProject(stray);
+  }
+  const entries = existingEntries(testFiles, rootAbs);
+  const forced = forcedWhole(node, entries, cwdAbs, rootAbs);
+  if (forced) return whole(forced);
+  const existing = entries.files;
+  // This node's candidates: inside its cwd, plus (dotnet) whatever a link's csproj compiles.
+  const candidates = existing.filter((abs) => isInside(abs, cwdAbs));
+  if (node.runner === 'dotnet') {
+    for (const abs of linkedOutputs(node.command, existing, cwdAbs, rootAbs)) if (!candidates.includes(abs)) candidates.push(abs);
+  }
+  const missed = candidates.find((abs) => unrecognisedTestFile(node.runner, abs, rootAbs));
+  if (missed) {
+    return whole(`output file "${toPosix(relative(rootAbs, missed))}" reads like a test file but is not recognised as one for runner "${node.runner}" — a recorte would skip it; running it whole`);
+  }
+  const owned = candidates.filter((abs) => isTestFileFor(node.runner, abs, rootAbs));
+  if (owned.length === 0) return whole(NO_TEST_FILE);
+  return node.runner === 'dotnet'
+    ? narrowDotnet(node.command.trim(), owned, cwdAbs, rootAbs)
+    : narrowJs(node.runner, node.command, owned, cwdAbs);
+}
+
+/**
+ * How the node set was chosen, for the `--json` summary.
+ * `feature` scope has none; `full`/`filter` switch group selection off.
+ */
+function derivationOf({ full, filter, group, nodes }) {
+  if (full) return 'full';
+  if (filter) return 'filter';
+  if (group === 'docs') return 'docs';
+  if (!group) return 'no-group';
+  return nodes.some((n) => effectiveGroups(n)?.includes(group)) ? 'group' : 'unclaimed-group';
+}
+
+/**
+ * Scope a test plan to one task.
+ *
+ * - Feature scope (`taskId` empty): nodes returned as copies, deep-equal to the
+ *   input — no `selection` key at all (readers take absent as null).
+ * - `full`: every node `mode: 'full'`, commands untouched.
+ * - `filter`: the caller's `--filter` picks the nodes; here it only switches
+ *   group selection OFF — narrowing inside the nodes still applies.
+ * - Otherwise: group `docs` runs only nodes owning an output file; a group some
+ *   node claims (`effectiveGroups`) runs the nodes serving it, the unmapped ones
+ *   (null) and any node owning one of the task's TEST files (safety net for a
+ *   mis-grouped task); an unclaimed or missing group runs every node.
+ *
+ * Input nodes are never mutated.
+ *
+ * @param {Object} args
+ * @param {string} args.projectPath
+ * @param {import('./test-nodes.js').TestNode[]} args.nodes
+ * @param {{ group?: string, outputs?: string[] }|null} args.task
+ * @param {string|null} args.taskId
+ * @param {{ raw: string, tokens: string[] }|null} [args.filter]
+ * @param {boolean} [args.full]
+ * @returns {{ nodes: Array<import('./test-nodes.js').TestNode & { selection?: TestSelection }>,
+ *   summary: { scope: 'feature'|'task', derivation: string|null, group: string|null, testFiles: string[] } }}
+ */
+export function applyTaskScope({ projectPath = '.', nodes = [], task = null, taskId = null, filter = null, full = false } = {}) {
+  if (!taskId) {
+    return { nodes: nodes.map((n) => ({ ...n })), summary: { scope: 'feature', derivation: null, group: null, testFiles: [] } };
+  }
+  const rootAbs = rootOf(projectPath);
+  const rel = (abs) => toPosix(relative(rootAbs, abs));
+  const group = typeof task?.group === 'string' ? task.group : null;
+  const taskOutputs = Array.isArray(task?.outputs) ? task.outputs : [];
+  const entries = existingEntries(taskOutputs, rootAbs);
+  const outputs = entries.files;
+  const testFiles = outputs.filter((abs) => isTestFileFor(null, abs, rootAbs));
+  const derivation = derivationOf({ full, filter, group, nodes });
+
+  const scoped = nodes.map((node) => {
+    const cwdAbs = cwdOf(node, rootAbs);
+    const ownOutputs = outputs.filter((abs) => isInside(abs, cwdAbs));
+    // Dotnet: a file a LINK's csproj compiles is this node's too, wherever it sits.
+    if (node.runner === 'dotnet') {
+      for (const abs of linkedOutputs(node.command, outputs, cwdAbs, rootAbs)) if (!ownOutputs.includes(abs)) ownOutputs.push(abs);
+    }
+    // A link naming a project the recorte cannot resolve may compile ANY touched
+    // .NET source outside the cwd, run any test project's file there (N2), or
+    // anything inside a touched folder there: its ownership is unknowable, so the
+    // node is never scoped out past one (narrowNode then runs it whole, naming it).
+    const mayOwnOutside = node.runner === 'dotnet'
+      && unresolvedProjectTarget(node.command, cwdAbs, rootAbs) !== null
+      && (outputs.some((abs) => !isInside(abs, cwdAbs) && (isDotnetSource(abs) || inTestProject(abs, rootAbs)))
+        || entries.dirs.some((d) => !isInside(d, cwdAbs)));
+    // F1/F2: a folder it may hold, or a non-C# test source it may compile.
+    const forced = forcedWhole(node, entries, cwdAbs, rootAbs) !== null;
+    const ownTests = ownOutputs.filter((abs) => isTestFileFor(node.runner, abs, rootAbs));
+    // A test-looking output the recogniser missed counts as owned for the pull-in
+    // too: scoping the node out would skip it just as surely as narrowing past it.
+    const ownsTests = ownTests.length > 0 || mayOwnOutside || forced
+      || ownOutputs.some((abs) => unrecognisedTestFile(node.runner, abs, rootAbs));
+    const select = (selection, command = node.command) => ({
+      ...node,
+      command,
+      selection: {
+        declaredCommand: node.command ?? null, files: ownTests.map(rel), selectors: [], zeroGuard: null, ...selection,
+      },
+    });
+
+    if (derivation === 'full') return select({ mode: 'full', reason: '--full: task-scope narrowing switched off — running it whole' });
+    // The resolver already decided (invalid config, "no suites"): preDecideRun
+    // reports that verdict first, and a recorte would only disguise it.
+    if (node.status) return select({ mode: 'whole', reason: node.reason ?? `pre-decided: ${node.status}` });
+
+    // Ownership for docs is the SAME rule as for links (B3 carry-over): the cwd
+    // contains the file OR a link's csproj compiles it — ownOutputs holds both;
+    // a folder or non-C# test source it may run (forced) keeps it too.
+    if (derivation === 'docs' && ownOutputs.length === 0 && !mayOwnOutside && !forced) {
+      return select({ mode: 'out-of-scope', files: [], reason: 'out of task scope: task group "docs" runs only the nodes owning a file from the task\'s outputs' });
+    }
+    const groups = effectiveGroups(node);
+    if (derivation === 'group' && groups !== null && !groups.includes(group) && !ownsTests) {
+      return select({ mode: 'out-of-scope', files: [], reason: `out of task scope: node serves [${groups.join(', ')}], task group is "${group}"` });
+    }
+
+    // Every output: narrowNode keeps the cwd rule itself and adds the link-owned files.
+    const narrowed = narrowNode(node, taskOutputs, rootAbs);
+    if (narrowed.command === null) return select({ mode: 'whole', reason: narrowed.reason });
+    return select({ mode: 'narrowed', reason: null, selectors: narrowed.selectors, zeroGuard: narrowed.zeroGuard }, narrowed.command);
+  });
+
+  return { nodes: scoped, summary: { scope: 'task', derivation, group, testFiles: testFiles.map(rel) } };
+}

package/src/lib/validators/traceability-check.js

@@ -92,8 +92,15 @@ export function extractCitedFiles(recapText) {
   return [...cited];
 }
 
-/** Backslashes to forward slashes, strip a leading `./`. */
-function normalizePath(p) {
+/**
+ * Backslashes to forward slashes, strip a leading `./`.
+ *
+ * Exported because `src/lib/tasks/test-scope.js` normalises the SAME thing —
+ * a task's `outputs` entry — before deciding which tests a task-scoped verify
+ * runs. One normaliser for `outputs`, so the traceability check and the test
+ * recorte never disagree about which file a task delivered.
+ */
+export function normalizePath(p) {
   return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
 }