@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/mutation/dotnet-introspection.js

@@ -0,0 +1,281 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+
+import { isInside } from '../tasks/test-runner.js';
+import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js';
+
+const MTP_RUNNER = 'Microsoft.Testing.Platform';
+const TYPE_HEADER = /\b(?:class|struct|record|interface)\b/;
+// `@` = verbatim identifier, `\` = unicode escape.
+const NAME_START = '[\\p{L}\\p{Nl}_@\\\\]';
+// TRIPWIRE with NO context rule: any exclusion based on what precedes the keyword can be
+// forged by a comment or exposed string. The quote in the lookahead makes every keyword
+// the blanked code counts also counted in the raw text, at the same offset.
+const TYPE_KEYWORD = new RegExp(`\\b(?:record\\s+(?:class|struct)|class|record|struct|interface)\\b(?=\\s*(?:${NAME_START}|["']|\\/[/*]|#))`, 'gu');
+const TYPE_DECL = new RegExp(`(?:^|[;{}\\]\\n])[ \\t]*(?:\\[[^\\]\\n]*\\][ \\t]*)*(?:(?:public|internal|private|protected|sealed|static|partial|abstract|unsafe|file|new|readonly|ref)\\s+)*(record\\s+(?:class|struct)|class|record|struct|interface)\\s+(${NAME_START}[^\\s:<({;,=]*)`, 'gu');
+const IDENT = '[\\p{L}_][\\p{L}\\p{N}_]*';
+const QUALIFIER = `(?:${IDENT}\\s*(?:\\.|::)\\s*)*`;
+const ATTRIBUTE_ARGS = '(?:\\((?:[^()\\]]|\\([^()\\]]*\\))*\\))?';
+const OTHER_ATTRIBUTE = `${QUALIFIER}${IDENT}\\s*${ATTRIBUTE_ARGS}`;
+const TEST_ATTRIBUTE_NAME = '(?:Fact|Theory|Test|TestMethod|DataTestMethod|TestCase|TestCaseSource)(?:Attribute)?';
+// A false POSITIVE is the unsafe side (a helper taken for a test file hides the tests that
+// use it), so the whole name must sit in an attribute section that CLOSES: a C# 12
+// collection such as `[\n Env.Test,\n];` must not match. Residual cases: csharpClasses.
+export const CS_TEST_ATTRIBUTE = new RegExp(
+  '(?:^|[;{}\\]]|\\*\\/)[ \\t]*\\['
+  + `\\s*(?:${IDENT}\\s*:(?!:)\\s*)?`
+  + `(?:${OTHER_ATTRIBUTE}\\s*,\\s*)*`
+  + `${QUALIFIER}${TEST_ATTRIBUTE_NAME}(?![\\p{L}\\p{N}_])\\s*${ATTRIBUTE_ARGS}`
+  + `(?:\\s*,\\s*${OTHER_ATTRIBUTE})*`
+  + '\\s*\\]\\s*(?:[\\[\\p{L}_@/#]|(?![\\s\\S]))',
+  'mu',
+);
+
+// Roslyn reads CR/NEL/LS/PS as new-lines and U+001A as whitespace; JS `\s` misses NEL
+// and U+001A, which hid `class<NEL>Name`. Mapped 1:1 so offsets stay aligned with the code.
+const readText = (path) => {
+  try { return readFileSync(path, 'utf8').replace(/\x1A/g, ' ').replace(/^\uFEFF/, '').replace(/[\r\u0085\u2028\u2029]/g, '\n'); } catch { return null; }
+};
+
+function nearestProjectFile(fileAbs, rootAbs, projectName) {
+  for (let dir = dirname(fileAbs); isInside(dir, rootAbs); dir = dirname(dir)) {
+    let names = [];
+    try { names = readdirSync(dir).filter((n) => projectName.test(n)).sort(); } catch { /* unreadable dir */ }
+    if (names.length > 0) return join(dir, names[0]);
+    if (dirname(dir) === dir) break;
+  }
+  return null;
+}
+
+export function nearestProjectOf(fileAbs, rootAbs) {
+  return nearestProjectFile(fileAbs, rootAbs, /\.(?:cs|fs|vb)proj$/i);
+}
+
+const NON_CSHARP_SOURCE = /\.(?:razor|cshtml|fs|fsi|fsx|vb)$/i;
+
+/** No type scan, hence no class selector, for these. */
+export const isNonCSharpSource = (path) => NON_CSHARP_SOURCE.test(String(path));
+
+export const isDotnetSource = (path) => /\.cs$/i.test(String(path)) || isNonCSharpSource(path);
+
+/**
+ * Nearest global.json walking up from the CWD, as the SDK resolves it (never from the
+ * `.sln` argument). null when one exists but cannot be read — never a guess.
+ */
+export function dotnetTestMode(absCwd) {
+  for (let dir = resolve(absCwd); ; dir = dirname(dir)) {
+    const file = join(dir, 'global.json');
+    if (existsSync(file)) {
+      try {
+        const parsed = JSON.parse(jsoncToJson(readFileSync(file, 'utf8')));
+        return parsed?.test?.runner === MTP_RUNNER ? 'mtp' : 'vstest';
+      } catch {
+        return null;
+      }
+    }
+    if (dirname(dir) === dir) return 'vstest';
+  }
+}
+
+const lineEnd = (text, i) => { const e = text.indexOf('\n', i); return e < 0 ? text.length : e; };
+
+function closeOnLine(text, start, quote) {
+  for (let j = start + 1; j < text.length && text[j] !== '\n'; j++) {
+    if (text[j] === '\\') j++;
+    else if (text[j] === quote) return j + 1;
+  }
+  return -1;
+}
+
+// A `"` inside a hole (`$"{d["k"]}"`) ends the literal as the scanner reads it,
+// leaving the hole open. `{{`/`}}` outside a hole are escapes.
+function holeLeftOpen(content) {
+  let depth = 0;
+  for (let k = 0; k < content.length; k++) {
+    const c = content[k];
+    if (depth === 0 && (c === '{' || c === '}') && content[k + 1] === c) { k++; continue; }
+    if (c === '{') depth++;
+    else if (c === '}' && depth > 0) depth--;
+  }
+  return depth > 0;
+}
+
+/**
+ * Comments, preprocessor lines and literals blanked, length and newlines kept; null when
+ * a literal never ends or an interpolation hole is cut. A heuristic lexer that CAN misread:
+ * csharpClasses never trusts it alone (it checks against the raw text).
+ */
+export function blankCSharpLiterals(text) {
+  const out = text.split('');
+  const blank = (from, to) => { for (let k = from; k < to; k++) if (out[k] !== '\n') out[k] = ' '; };
+  for (let i = 0; i < text.length;) {
+    const c = text[i];
+    let end = -1;
+    if (c === '#' && /^[ \t]*$/.test(text.slice(text.lastIndexOf('\n', i - 1) + 1, i))) {
+      end = lineEnd(text, i);
+    } else if (c === '/' && text[i + 1] === '/') {
+      end = lineEnd(text, i);
+    } else if (c === '/' && text[i + 1] === '*') {
+      const close = text.indexOf('*/', i + 2);
+      if (close < 0) return null;
+      end = close + 2;
+    } else if (c === '"' && (text[i - 1] === '@' || (text[i - 1] === '$' && text[i - 2] === '@'))) {
+      let j = i + 1;
+      while (j < text.length && !(text[j] === '"' && text[j + 1] !== '"')) j += text[j] === '"' ? 2 : 1;
+      if (j >= text.length) return null;
+      end = j + 1;
+      const interpolated = text[i - 1] === '$' || text[i - 2] === '$';
+      if (interpolated && holeLeftOpen(text.slice(i + 1, end - 1))) return null;
+    } else if (c === '"') {
+      let quotes = 0;
+      while (text[i + quotes] === '"') quotes++;
+      if (quotes >= 3) {
+        const close = text.indexOf('"'.repeat(quotes), i + quotes);
+        if (close < 0) return null;
+        end = close + quotes;
+      } else {
+        end = closeOnLine(text, i, '"');
+        if (end < 0) return null;
+        if (text[i - 1] === '$' && holeLeftOpen(text.slice(i + 1, end - 1))) return null;
+      }
+    } else if (c === "'") {
+      end = closeOnLine(text, i, "'");
+      if (end < 0) return null;
+    }
+    if (end < 0) { i++; continue; }
+    blank(i, end);
+    i = end;
+  }
+  return out.join('');
+}
+
+const typeKeywordCount = (text) => [...text.matchAll(TYPE_KEYWORD)].length;
+
+/**
+ * The types of a C# file, read FAIL-SAFE.
+ *
+ * `types` lists the BARE name of EVERY type declaration (class, record, struct,
+ * interface) at ANY depth, in source order, with no namespace. A selection built
+ * from these names is namespace-free (`--filter-class "*T*"`, measured, or the
+ * substring `FullyQualifiedName~T`): any namespace, `Outer+Inner`, `Name`1` — a
+ * selection that can only run MORE tests than the file's, never fewer.
+ *
+ * THE GUARANTEE (what `scannable: true` means), and why it holds:
+ *   every type-keyword token of the RAW text is a declaration in `types`.
+ * - R = keyword tokens of the raw text (TYPE_KEYWORD, no context rule); C = the
+ *   same on the blanked code; D = the declarations named (TYPE_DECL on the code).
+ *   `scannable` requires |R| = |D| and |C| = |D|. By construction D ⊆ C ⊆ R as
+ *   sets of offsets: blanking keeps length and only replaces characters by spaces,
+ *   a blanked region starts at `"` `'` `/` `#` and ends at `"` `'` `*` `/` or a
+ *   line end (never inside an identifier), and the raw lookahead accepts every
+ *   character the code lookahead can be looking past (a name, a comment, `#`, a
+ *   quote). So |R| = |D| forces R = D. A real declaration's keyword is always in R
+ *   (it is followed by its name, or by a comment/directive before the name) —
+ *   UNDER ONE ASSUMPTION: every character Roslyn reads as whitespace or a new-line
+ *   between a keyword and its name is whitespace to JS `\s` once readText has run.
+ *   Roslyn's whitespace is Unicode Zs, TAB, VT, FF and U+001A; its new-lines are
+ *   CR, LF, NEL, LS and PS. JS `\s` already covers Zs, TAB, VT, FF and LF, and
+ *   readText maps CR/NEL/LS/PS to `\n` and U+001A to a space. A separator outside
+ *   that shared set would hide a declaration from R; none is known, and that is a
+ *   statement about the two lexers as read, not a proof.
+ *   Hence: a declaration swallowed by ANY misread — `"/*"` taken for a comment
+ *   opener, a quote inside an interpolation hole, a char literal — is still in R
+ *   and cannot be compensated by anything (a fake the code exposes is in R too).
+ * - `abstract` lists the abstract types: their tests run under the names of DERIVED
+ *   classes, possibly in other files.
+ * - `hasTestAttribute`: a test attribute (CS_TEST_ATTRIBUTE: a whole name inside an
+ *   attribute section) is present in the blanked code (a file without one is a
+ *   helper/fake/fixture: the tests using it are elsewhere).
+ * - kept fail-safes: braces balance and blankCSharpLiterals returning null → unscannable.
+ *
+ * NOT guaranteed (stated, not hidden):
+ * - completeness: keyword-shaped text in a real comment or string (`// the
+ *   class under test`), a constraint keyword followed by a name-shaped token
+ *   (`where T : class where …`, `: class // note`), `record with`, a directive
+ *   splitting a name — all make the file unscannable;
+ * - which scope a type was read in;
+ * - a NON-abstract class whose tests are inherited by derived classes declared in
+ *   OTHER files: the touched class runs; the derived copies only if their names
+ *   contain it;
+ * - a test attribute reached through an alias (`using F = Xunit.FactAttribute; [F]`)
+ *   or a custom one (`[SkippableFact]`) is not seen: the file counts as a helper and
+ *   it is left out of a selection;
+ * - `hasTestAttribute` is still a heuristic, and ITS false positive is the unsafe
+ *   side. The section must close; what still matches in a
+ *   helper — probed — is a LIST PATTERN opening a line (or after `;` `{` `}` `]`)
+ *   whose element is named exactly `Test`/`Fact`/… (qualified or not) and whose `]`
+ *   is followed by a combinator: `[Env.Test] or [Env.Dev] => true`. Such a helper is
+ *   taken for a test file. (`[Env.Test] => 1` does not match: `=` starts no declaration.)
+ *
+ * @param {string} csFileAbs
+ * @returns {{ names: string[], types: string[], abstract: string[], hasTestClass: boolean, hasTestAttribute: boolean, scannable: boolean, why: string|null }}
+ *   `names`: top-level `class` names (classNamesOf). `abstract`: the abstract
+ *   types. `hasTestClass`: some plain `class` is declared (records, structs and
+ *   interfaces hold no tests). `hasTestAttribute`: see above. `why`: the reason
+ *   when `scannable` is false.
+ */
+export function csharpClasses(csFileAbs) {
+  const unscannable = (why) => ({ names: [], types: [], abstract: [], hasTestClass: false, hasTestAttribute: false, scannable: false, why });
+  const text = readText(csFileAbs);
+  if (text === null) return { names: [], types: [], abstract: [], hasTestClass: false, hasTestAttribute: false, scannable: true, why: null };
+  const code = blankCSharpLiterals(text);
+  if (code === null) return unscannable('a literal or comment never ends, or an interpolation hole is cut by an inner quote');
+
+  const decls = [...code.matchAll(TYPE_DECL)].map((m) => ({
+    at: m.index + m[0].length - m[2].length,
+    kind: m[1].split(/\s+/)[0],
+    name: m[2],
+    abstract: /\babstract\b/.test(m[0]),
+    gap: m[0].slice(0, m[0].length - m[2].length).match(/\s*$/)[0].length,
+  }));
+  // A preprocessor line between a keyword and its name (`class\n#if X\nA\n#else\nB…`)
+  // makes the compiled name depend on a symbol this scan cannot see. Blanking keeps
+  // length, so the raw text at the same offsets shows the directive.
+  const split = decls.find((d) => /(^|\n)[ \t]*#/.test(text.slice(d.at - d.gap, d.at)));
+  if (split) return unscannable(`a preprocessor directive stands between a type keyword and the name "${split.name}"`);
+  // The raw text is the lexer-independent truth about how many type keywords the file
+  // carries (the JSDoc explains why equal counts mean equal sets).
+  const rawKeywords = typeKeywordCount(text);
+  if (rawKeywords !== decls.length) {
+    return unscannable(`${rawKeywords} type keyword(s) in the file but ${decls.length} declaration(s) recognised`);
+  }
+  const codeKeywords = typeKeywordCount(code);
+  if (codeKeywords !== decls.length) {
+    return unscannable(`${codeKeywords} type keyword(s) in the code but ${decls.length} declaration(s) recognised`);
+  }
+
+  const names = [];
+  const types = [];
+  const abstractTypes = [];
+  const scopes = [];
+  let hasTestClass = false;
+  let header = 0;
+  for (let i = 0, d = 0; i < code.length; i++) {
+    for (; d < decls.length && decls[d].at === i; d++) {
+      types.push(decls[d].name);
+      if (decls[d].abstract) abstractTypes.push(decls[d].name);
+      if (decls[d].kind === 'class') {
+        hasTestClass = true;
+        if (!scopes.some((s) => s.type)) names.push(decls[d].name);
+      }
+    }
+    const c = code[i];
+    if (c === '{') {
+      scopes.push({ type: TYPE_HEADER.test(code.slice(header, i)) });
+    } else if (c === '}' && scopes.pop() === undefined) {
+      return unscannable('a `}` closes nothing');
+    }
+    if (c === '{' || c === '}' || c === ';') header = i + 1;
+  }
+  if (scopes.length > 0) return unscannable('braces left open at end of file');
+  return {
+    names: [...new Set(names)],
+    types: [...new Set(types)],
+    abstract: [...new Set(abstractTypes)],
+    hasTestClass,
+    hasTestAttribute: CS_TEST_ATTRIBUTE.test(code),
+    scannable: true,
+    why: null,
+  };
+}
+

package/src/lib/mutation/plan.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { isInside } from '../tasks/test-runner.js';
-import { isDotnetSource } from '../tasks/dotnet-test-introspection.js';
+import { isDotnetSource } from './dotnet-introspection.js';
 import { resolveRegions, validateManifest } from './manifest.js';
 
 const JS_RUNNERS = new Set(['vitest', 'jest', 'node-test']);
@@ -14,23 +14,31 @@ export function loadPlan({ root, planPath }) {
   });
 }
 
-export function pickNode(file, nodes, root) {
+function ownersOf(file, nodes, root) {
+  if (isDotnetSource(file)) return nodes.filter((n) => n.runner === 'dotnet');
   const abs = resolve(root, file);
-  if (isDotnetSource(file)) return nodes.find((n) => n.runner === 'dotnet') ?? null;
-  const owners = nodes
+  return nodes
     .filter((n) => JS_RUNNERS.has(n.runner) && isInside(abs, resolve(root, n.cwd || '.')))
     .sort((a, b) => resolve(root, b.cwd || '.').length - resolve(root, a.cwd || '.').length);
-  return owners[0] ?? null;
+}
+
+// An `e2e: true` suite tests the running compose stack, which mutate never
+// rebuilds: it is picked only when no other suite owns the file, and the caller refuses.
+export function pickNode(file, nodes, root) {
+  const owners = ownersOf(file, nodes, root);
+  return owners.find((n) => !n.e2e) ?? owners[0] ?? null;
 }
 
 export function groupByNode(regions, nodes, root) {
   const groups = new Map();
   const orphans = [];
+  const stackOnly = [];
   for (const region of regions) {
     const node = pickNode(region.file, nodes, root);
     if (!node) { orphans.push(region); continue; }
+    if (node.e2e) { stackOnly.push({ region, node }); continue; }
     if (!groups.has(node.id)) groups.set(node.id, { node, regions: [] });
     groups.get(node.id).regions.push(region);
   }
-  return { groups: [...groups.values()], orphans };
+  return { groups: [...groups.values()], orphans, stackOnly };
 }

package/src/lib/mutation/runner.js

@@ -5,7 +5,7 @@ import { blame, parseCompilerErrors, patchFile, switchClassName, switchSource, S
 import { md5Of, md5OfFile, openSnapshot, restoreSnapshot, trackGenerated } from './snapshot.js';
 import { parseBuiltDlls } from './commands.js';
 import { firstLines, methodOf } from './trx.js';
-import { nearestProjectOf } from '../tasks/dotnet-test-introspection.js';
+import { nearestProjectOf } from './dotnet-introspection.js';
 
 const posix = (p) => p.replace(/\\/g, '/');
 const MAX_SCHEMATA_ATTEMPTS = 3;

package/src/lib/mutation/subset.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
-import { csharpClasses } from '../tasks/dotnet-test-introspection.js';
+import { csharpClasses } from './dotnet-introspection.js';
 import { relatedCommand } from './commands.js';
 
 const SKIP_DIRS = new Set(['bin', 'obj', 'node_modules', '.git', 'worktrees', 'TestResults']);
@@ -24,18 +24,37 @@ function walkCs(dir, out = []) {
 
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
-/**
- * The tests to run FIRST, chosen by the tool: files the feature changed, and files naming a
- * type the mutated files declare. A mutant the subset does not kill goes to the whole suite.
- */
+export function mutatedTypesOf(root, files) {
+  const types = new Set();
+  for (const file of files) {
+    for (const t of csharpClasses(resolve(root, file)).types) if (t.length >= MIN_TYPE_LENGTH) types.add(t);
+  }
+  return [...types];
+}
+
+const mentionOf = (types) => (types.length > 0 ? new RegExp(`\\b(?:${types.map(escapeRe).join('|')})\\b`) : null);
+
+/** Test files (a test attribute in the code) under `testProjectDirs` naming one of `types` as a whole word. */
+export function testFilesCiting({ root, testProjectDirs, types, exclude = [] }) {
+  const mention = mentionOf(types);
+  if (mention === null) return [];
+  const skip = new Set(exclude.map(posix));
+  const found = [];
+  for (const dir of testProjectDirs) {
+    for (const abs of walkCs(resolve(root, dir))) {
+      const rel = posix(relative(root, abs));
+      if (skip.has(rel)) continue;
+      const info = csharpClasses(abs);
+      if (info.scannable && info.hasTestAttribute && mention.test(readFileSync(abs, 'utf8'))) found.push(rel);
+    }
+  }
+  return found.sort();
+}
+
+/** Chosen by the tool, never the verifier: test files the feature changed or that name a mutated type. */
 export function dotnetSubset({ root, testProjectDirs, mutatedFiles, changed = [] }) {
   const changedSet = new Set(changed.map(posix));
-  const mutatedTypes = new Set();
-  for (const file of mutatedFiles) {
-    for (const t of csharpClasses(resolve(root, file)).types) if (t.length >= MIN_TYPE_LENGTH) mutatedTypes.add(t);
-  }
-  const mention = mutatedTypes.size > 0
-    ? new RegExp(`\\b(?:${[...mutatedTypes].map(escapeRe).join('|')})\\b`) : null;
+  const mention = mentionOf(mutatedTypesOf(root, mutatedFiles));
 
   const byChange = new Set();
   const byMention = new Set();
@@ -70,6 +89,21 @@ export function jsSubset({ runner, command, root, mutatedFiles }) {
   return { usable: true, command: cmd, files: { related: files } };
 }
 
-export function testProjectDirsOf(root, csprojs) {
-  return [...new Set(csprojs.map((c) => posix(relative(root, dirname(resolve(root, c))))))];
+const SLN_PROJECT = /^Project\("[^"]*"\)\s*=\s*"[^"]*",\s*"([^"]+\.csproj)"/gim;
+const SLNX_PROJECT = /<Project\b[^>]*\bPath="([^"]+\.csproj)"/gi;
+
+function solutionProjects(solutionAbs) {
+  let text;
+  try { text = readFileSync(solutionAbs, 'utf8'); } catch { return []; }
+  const pattern = /\.slnx$/i.test(solutionAbs) ? SLNX_PROJECT : SLN_PROJECT;
+  return [...text.matchAll(pattern)].map((m) => resolve(dirname(solutionAbs), posix(m[1])));
+}
+
+/** A solution stands for every project it lists; one that lists none yields no directory. */
+export function testProjectDirsOf(root, targets, cwd = root) {
+  const projects = targets.flatMap((t) => {
+    const abs = resolve(cwd, t);
+    return /\.slnx?$/i.test(t) ? solutionProjects(abs) : [abs];
+  });
+  return [...new Set(projects.map((p) => posix(relative(root, dirname(p)))))];
 }

package/src/lib/plan/artifact-vocabulary.js

@@ -0,0 +1,40 @@
+/** The inline justification that lets a criterion talk about an artifact on purpose. */
+export const ARTIFACT_MARKER_RE = /por\s+que\s+artefato\s*:/i;
+
+// Node 18 has no inline `(?i:…)` modifier, and the rest of the regex must stay case-sensitive.
+const anyCase = (word) => [...word].map((c) => {
+  const lo = c.toLowerCase();
+  const up = c.toUpperCase();
+  return lo === up ? c : `[${lo}${up}]`;
+}).join('');
+
+// Case-sensitive on purpose: `src`, `docs` or `lib` after "arquivo em" are places, and places are artifacts.
+const FORMAT_TOKEN = String.raw`\s+(?:[A-Z]{2,5}(?![\p{L}\d_])|${anyCase('formato')}(?![\p{L}]))`;
+
+// `term` is cited verbatim by the `morph-plan` skill (a parity test imports it): keep it stable.
+// Unicode lookarounds, never `\b`: JS `\b` false-boundaries inside "não" or "binário".
+export const ARTIFACT_VOCABULARY = [
+  { term: 'grep',                        re: /(?<![\p{L}\d_])grep(?![\p{L}\d_])/iu },
+  { term: 'contém a string',             re: /cont[ée]m\s+as?\s+strings?/iu },
+  { term: 'o binário',                   re: /(?<![\p{L}])o\s+bin[áa]rio(?![\p{L}])/iu },
+  { term: 'nenhum arquivo',              re: /(?<![\p{L}])nenhum\s+arquivo(?![\p{L}])/iu },
+  {
+    term: 'arquivo/pasta/diretório em',
+    re: new RegExp(
+      String.raw`(?<![\p{L}])(?:${anyCase('arquivo')}|${anyCase('pasta')}|${anyCase('diret')}[óoÓO]${anyCase('rio')})` +
+      String.raw`[sS]?\s+${anyCase('em')}(?![\p{L}])(?!${FORMAT_TOKEN})`,
+      'u',
+    ),
+  },
+  { term: 'glob **/',                    re: /\*\*\/|\/\*\*/ },
+];
+
+/** Each term at most once, in vocabulary order. */
+export function findArtifactTerms(text) {
+  const s = String(text ?? '');
+  const found = [];
+  for (const { term, re } of ARTIFACT_VOCABULARY) {
+    if (re.test(s)) found.push(term);
+  }
+  return found;
+}

package/src/lib/plan/checks.js

@@ -0,0 +1,208 @@
+import { createHash } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+import { frozenBody } from '../../../framework/hooks/shared/errata.js';
+import { readAgentsJson } from '../specs/screen-checklist.js';
+import { findArtifactTerms } from './artifact-vocabulary.js';
+import { PROOF_KINDS, REUSE_VERDICTS, ADR_SCOPES, SECTIONS, CONFLICTS_HEADING } from './plan-parser.js';
+
+export const CHECKS_VERSION = 1;
+export const MAX_SLICE_FILES = 8;
+export const MAX_SLICES = 12;
+export const MAX_PARALLEL = 4;
+
+/** sha256 of the plan without its errata: appending a correction never invalidates the extracted checks. */
+export function planHash(text) {
+  return createHash('sha256').update(frozenBody(text), 'utf8').digest('hex');
+}
+
+/** The installed agents.json, else the package's; null when unreadable (personas then go unchecked). */
+export function knownPersonas(cwd) {
+  const agents = readAgentsJson(cwd)?.agents;
+  return agents && typeof agents === 'object' ? Object.keys(agents) : null;
+}
+
+/** The ids on a dependency cycle, or null. */
+export function dependencyCycle(slices) {
+  const deps = new Map(slices.map((s) => [s.id, s.depends ?? []]));
+  const state = new Map();
+  const stack = [];
+  const visit = (id) => {
+    if (state.get(id) === 'done' || !deps.has(id)) return null;
+    if (state.get(id) === 'open') return stack.slice(stack.indexOf(id)).concat(id);
+    state.set(id, 'open');
+    stack.push(id);
+    for (const dep of deps.get(id)) {
+      const cycle = visit(dep);
+      if (cycle) return cycle;
+    }
+    stack.pop();
+    state.set(id, 'done');
+    return null;
+  };
+  for (const id of deps.keys()) {
+    const cycle = visit(id);
+    if (cycle) return cycle;
+  }
+  return null;
+}
+
+const fileKey = (f) => f.replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
+
+// A slice joins a wave only after its dependencies ran, never with one touching its files, and at most
+// MAX_PARALLEL per wave. Empty on a dependency cycle.
+export function parallelGroups(slices) {
+  if (dependencyCycle(slices)) return [];
+  const ids = new Set(slices.map((s) => s.id));
+  const depth = new Map();
+  const depthOf = (slice) => {
+    if (depth.has(slice.id)) return depth.get(slice.id);
+    const parents = (slice.depends ?? []).filter((d) => ids.has(d)).map((d) => slices.find((s) => s.id === d));
+    const value = parents.length === 0 ? 0 : 1 + Math.max(...parents.map(depthOf));
+    depth.set(slice.id, value);
+    return value;
+  };
+  const layers = [];
+  for (const slice of slices) (layers[depthOf(slice)] ??= []).push(slice);
+
+  const groups = [];
+  for (const layer of layers.filter(Boolean)) {
+    const open = [];
+    for (const slice of layer) {
+      const files = new Set((slice.files ?? []).map(fileKey));
+      const group = open.find((g) => g.ids.length < MAX_PARALLEL && ![...files].some((f) => g.files.has(f)));
+      if (group) {
+        group.ids.push(slice.id);
+        files.forEach((f) => group.files.add(f));
+      } else {
+        open.push({ ids: [slice.id], files });
+      }
+    }
+    groups.push(...open.map((g) => g.ids));
+  }
+  return groups;
+}
+
+export function validatePlan(plan, { personas = null, surfaces = null } = {}) {
+  const errors = [];
+  const warnings = [];
+  const at = (line) => (line ? ` (linha ${line})` : '');
+
+  for (const key of ['problem', 'scenarios', 'decisions', 'slices']) {
+    if (!plan.present[key]) errors.push(`seção obrigatória ausente: ## ${SECTIONS[key]}`);
+  }
+  if (plan.present.decisions && !plan.conflicts) {
+    errors.push(`### ${CONFLICTS_HEADING} ausente em ## ${SECTIONS.decisions} — escreva "nenhum" quando não houver`);
+  } else if (plan.conflicts && !plan.conflicts.text) {
+    errors.push(`### ${CONFLICTS_HEADING} está vazio${at(plan.conflicts.line)} — escreva "nenhum" quando não houver`);
+  }
+  if (plan.sectionsAfterErrata.length > 0) {
+    errors.push(`## ${SECTIONS.errata} precisa ser a última seção — depois dela: ${plan.sectionsAfterErrata.join(', ')}`);
+  }
+
+  const duplicated = (items) => items.map((i) => i.id).filter((id, i, all) => all.indexOf(id) !== i);
+  for (const [label, items] of [['cenário', plan.scenarios], ['fatia', plan.slices], ['ADR', plan.adrs]]) {
+    for (const id of new Set(duplicated(items))) errors.push(`${label} duplicado: ${id}`);
+  }
+
+  if (plan.present.scenarios && plan.scenarios.length === 0) {
+    errors.push(`## ${SECTIONS.scenarios} sem nenhum cenário no formato "- **C1** — Dado …, quando …, então …"`);
+  }
+  for (const c of plan.scenarios) {
+    if (c.proof === null) {
+      errors.push(`${c.id} sem "prova:" (${PROOF_KINDS.join(' | ')})${at(c.line)}`);
+    } else if (!PROOF_KINDS.includes(c.proof.toLowerCase())) {
+      errors.push(`${c.id}: prova "${c.proof}" fora de ${PROOF_KINDS.join(' | ')}${at(c.line)}`);
+    }
+    const terms = findArtifactTerms(c.text);
+    if (terms.length > 0 && !c.artifactWhy) {
+      errors.push(`${c.id} descreve artefato ("${terms.join(', ')}") sem "> Por que artefato:" — reescreva como efeito observável ou justifique${at(c.line)}`);
+    }
+  }
+
+  const scenarioIds = new Set(plan.scenarios.map((c) => c.id));
+  const sliceIds = new Set(plan.slices.map((s) => s.id));
+  const covered = new Set();
+  for (const s of plan.slices) {
+    if (!s.persona) {
+      errors.push(`${s.id} sem "- persona:"${at(s.line)}`);
+    } else if (personas && !personas.includes(s.persona)) {
+      errors.push(`${s.id}: persona "${s.persona}" não existe em agents.json (${personas.join(', ')})${at(s.line)}`);
+    }
+    if (s.files.length > MAX_SLICE_FILES) {
+      errors.push(`${s.id} toca ${s.files.length} arquivos — o teto é ${MAX_SLICE_FILES}; divida a fatia${at(s.line)}`);
+    }
+    for (const c of s.covers) {
+      if (scenarioIds.has(c)) covered.add(c);
+      else errors.push(`${s.id} cobre ${c}, que não existe em ## ${SECTIONS.scenarios}${at(s.line)}`);
+    }
+    for (const d of s.depends) {
+      if (!sliceIds.has(d)) errors.push(`${s.id} depende de ${d}, que não existe${at(s.line)}`);
+    }
+    if (s.covers.length === 0) warnings.push(`${s.id} não cobre nenhum cenário${at(s.line)}`);
+    if (s.unknownKeys.length > 0) warnings.push(`${s.id}: chave desconhecida ${s.unknownKeys.join(', ')}${at(s.line)}`);
+    if (s.surface && surfaces && !surfaces.includes(s.surface)) {
+      warnings.push(`${s.id}: superfície "${s.surface}" não é uma de ${surfaces.join(', ')}${at(s.line)}`);
+    }
+  }
+  for (const c of plan.scenarios) {
+    if (!covered.has(c.id)) errors.push(`${c.id} não é coberto por nenhuma fatia ("- cobre: ${c.id}")`);
+  }
+  const cycle = dependencyCycle(plan.slices);
+  if (cycle) errors.push(`ciclo em "depende": ${cycle.join(' → ')}`);
+  if (plan.slices.length > MAX_SLICES) warnings.push(`${plan.slices.length} fatias — acima de ${MAX_SLICES}, considere dividir a feature`);
+
+  for (const r of plan.reuse) {
+    if (!REUSE_VERDICTS.includes(r.verdict)) {
+      errors.push(`## ${SECTIONS.reuse}: veredito "${r.verdict}" de "${r.concept}" fora de ${REUSE_VERDICTS.join(' | ')}${at(r.line)}`);
+    } else if (r.verdict === 'CRIAR' && !r.why) {
+      warnings.push(`## ${SECTIONS.reuse}: CRIAR "${r.concept}" sem why${at(r.line)}`);
+    }
+  }
+  for (const a of plan.adrs) {
+    if (!ADR_SCOPES.includes(a.scope)) warnings.push(`${a.id} sem **Alcance:** ${ADR_SCOPES.join(' | ')}${at(a.line)}`);
+  }
+
+  return { errors, warnings };
+}
+
+export function buildChecks(feature, text, plan) {
+  return {
+    version: CHECKS_VERSION,
+    feature,
+    planHash: planHash(text),
+    checks: plan.scenarios.map((c) => ({
+      id: c.id, text: c.text, proof: c.proof ? c.proof.toLowerCase() : null, artifactWhy: c.artifactWhy || null,
+    })),
+    slices: plan.slices.map((s) => ({
+      id: s.id, title: s.title, persona: s.persona, surface: s.surface,
+      standards: s.standards, files: s.files, depends: s.depends, covers: s.covers,
+    })),
+    reuse: plan.reuse.map(({ concept, verdict, target, why }) => ({ concept, verdict, target, why })),
+    adrs: plan.adrs.map((a) => ({ id: a.id, title: a.title, scope: ADR_SCOPES.includes(a.scope) ? a.scope : null })),
+  };
+}
+
+/** plan-check writes the checks only with zero errors, so `fresh` also means the plan passed every rule. */
+export function readPlanChecks(cwd, featureName) {
+  const planPath = getAbsoluteOutputPath(cwd, featureName, 'plan');
+  const checksPath = getAbsoluteOutputPath(cwd, featureName, 'checks');
+  if (!existsSync(planPath)) return { status: 'no-plan', checks: null };
+  if (!existsSync(checksPath)) return { status: 'no-checks', checks: null };
+  let checks;
+  try {
+    checks = JSON.parse(readFileSync(checksPath, 'utf8'));
+  } catch {
+    return { status: 'unreadable', checks: null };
+  }
+  if (checks?.version !== CHECKS_VERSION || !Array.isArray(checks.slices) || !Array.isArray(checks.checks)) {
+    return { status: 'unreadable', checks: null };
+  }
+  let plan;
+  try {
+    plan = readFileSync(planPath, 'utf8');
+  } catch {
+    return { status: 'no-plan', checks };
+  }
+  return { status: checks.planHash === planHash(plan) ? 'fresh' : 'stale', checks };
+}