@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/specs/screen-checklist.js

@@ -1,43 +1,18 @@
-/**
- * O checklist de tela do `1-design/mockups.md` — as decisões que uma tela de
- * dados precisa (volume, paginação, ordenação, filtro, os três estados,
- * mobile, abas) escritas por tela, na fase uiux.
- *
- * Existe porque o que o design não pergunta não vira `doneCriteria`, e o que
- * não é critério ninguém entrega: telas de admin saíam listando tudo, sem
- * paginar nem ordenar, com o design aprovado. Os leitores do MESMO parser:
- *
- *   - `gate-check uiux` pausa com os problemas nomeados;
- *   - `approve`/`advance` com assinatura `auto` recusam a mesma pausa sem uma
- *     decisão gravada (`uiuxAutoApprovalBlock`) — a regra é a do risk-detector;
- *   - `gate-check review` exige que o avaliador registre a conferência de cada
- *     item decidido contra a tela entregue (`checklistCoverage`).
- *
- * Mockup no formato ANTERIOR ao checklist (telas `## S001: …`, sem nenhuma
- * `## Tela:`) é legado e isento, com a isenção gravada no sinal.
- *
- * O formato é o que a `morph-uiux` ensina: cada tela é um `## Tela: <nome>`, e
- * dentro dela um `### Checklist de tela` com uma linha por item — tabela
- * (`| Paginação | servidor, 25/página |`) ou lista (`- **Paginação:** …`).
- * "Não se aplica" é resposta válida; vazio, "?" ou "a definir" não são.
- */
+// Cada tela é `## Tela: <nome>` com um `### Checklist de tela`, uma linha por item (tabela ou lista).
+// "Não se aplica" é resposta válida; vazio, "?" ou "a definir" não são. Telas `## S001: …` sem
+// nenhuma `## Tela:` são o formato legado, isento.
 
 import { createHash } from 'crypto';
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
-import { evaluatorScreenChecklist } from '../evaluator-report.js';
+import { verifierScreenChecklist } from '../review-reports.js';
 import { LEGACY_MOCKUP_EXEMPTION, uiuxChecklistPause } from '../risk-detector.js';
 
 const PACKAGE_AGENTS = fileURLToPath(new URL('../../../framework/agents.json', import.meta.url));
 
-/**
- * Os itens, na ordem do template. `match` roda sobre o rótulo NORMALIZADO
- * (minúsculas, sem acento): "Estado de erro", "Erro" e "**Erro:**" são o mesmo
- * item. Um rótulo que casa com vários ("Estados (vazio/carregando/erro)")
- * responde a todos eles.
- */
+/** `match` roda sobre o rótulo normalizado; um rótulo que casa com vários itens responde a todos. */
 export const SCREEN_CHECKLIST_ITEMS = [
   { id: 'superficie', label: 'Superfície', match: /\bsuperficie\b/ },
   { id: 'volume', label: 'Volume esperado', match: /\bvolume\b/ },
@@ -51,26 +26,24 @@ export const SCREEN_CHECKLIST_ITEMS = [
   { id: 'abas', label: 'Abas', match: /\babas\b/ },
 ];
 
-/**
- * Itens que o avaliador não confere contra a tela: a superfície decide QUAIS
- * standards a tela lê, não um comportamento que a tela entregue exiba.
- */
+// A superfície decide quais standards a tela lê, não um comportamento que a tela entregue exiba.
 const NOT_VERIFIED_AT_REVIEW = new Set(['superficie']);
 
-/**
- * Respostas que ocupam a célula sem decidir nada: as exatas, e as que COMEÇAM
- * adiando a decisão ("a definir depois", "TBD.", "? talvez").
- */
+// As exatas, e as que começam adiando a decisão ("a definir depois", "TBD.").
 const PLACEHOLDERS = new Set(['', '-', '--', '—', '–', '...', 'x', 'todo', 'definir', 'pendente']);
 const PLACEHOLDER_PREFIX_RE = /^(a definir|tbd|\?|…)/;
 
-/** O formato de mockup anterior ao checklist: telas `## S001: <nome>`. */
 const LEGACY_SCREEN_HEADING_RE = /^##\s+S\d+\s*:/i;
 
 const NOT_APPLICABLE_RE = /^(nao se aplica|n\/a)\b/;
 
 const SCREEN_HEADING_RE = /^##\s+tela\s*[:—–-]\s*(.+?)\s*#*\s*$/i;
 const CHECKLIST_HEADING_RE = /^(#{3,6})\s+checklist\b/i;
+const PROTOTYPE_LINE_RE = /prot[oó]tipo/i;
+const PROTOTYPE_PATH_RE = /(?:1-design\/)?(prototipos\/[^\s`|)\]]+\.html)/i;
+
+/** As larguras dos prints que o laço de autocrítica deixa ao lado do protótipo. */
+export const PROTOTYPE_WIDTHS = [1280, 390];
 
 /** Minúsculas, sem acento, sem marcação inline, espaços colapsados. */
 export function normalizeLabel(text) {
@@ -83,21 +56,15 @@ export function normalizeLabel(text) {
     .trim();
 }
 
-/** Nome de tela comparável entre o mockup e o relatório do avaliador. */
 function screenKey(name) {
   return normalizeLabel(name).replace(/^tela\s*[:—–-]\s*/, '').replace(/[.:;,]+$/, '');
 }
 
-/** Os itens que um rótulo responde. */
 function itemsOf(label) {
   const norm = normalizeLabel(label);
   return SCREEN_CHECKLIST_ITEMS.filter((item) => item.match.test(norm)).map((item) => item.id);
 }
 
-/**
- * Uma linha de checklist como `[rótulo, resposta]`, ou null: linha de tabela
- * (separador `|---|` fora) ou item de lista `- Rótulo: resposta`.
- */
 function checklistRow(line) {
   const trimmed = line.trim();
   if (trimmed.startsWith('|')) {
@@ -112,13 +79,12 @@ function checklistRow(line) {
   return [bullet[1].slice(0, colon), bullet[1].slice(colon + 1).trim()];
 }
 
-/** As células de uma linha de tabela markdown, sem as bordas. */
 export function tableCells(line) {
   const inner = line.trim().replace(/^\|/, '').replace(/\|$/, '');
   return inner.split(/(?<!\\)\|/).map((cell) => cell.trim());
 }
 
-/** Linhas fora de blocos cercados: um exemplo dentro de ``` não é uma tela. */
+// Um exemplo dentro de ``` não é uma tela.
 function proseLines(markdown) {
   const out = [];
   let fenced = false;
@@ -129,12 +95,6 @@ function proseLines(markdown) {
   return out;
 }
 
-/**
- * As telas do mockup e o que o checklist de cada uma responde.
- *
- * @param {string} markdown - conteúdo do `1-design/mockups.md`
- * @returns {Array<{ name: string, hasChecklist: boolean, answers: Map<string, string> }>}
- */
 export function parseScreens(markdown) {
   const screens = [];
   let screen = null;
@@ -146,7 +106,7 @@ export function parseScreens(markdown) {
       const level = heading[1].length;
       const named = SCREEN_HEADING_RE.exec(line);
       if (level <= 2) {
-        screen = named && named[1].trim() ? { name: named[1].trim(), hasChecklist: false, answers: new Map() } : null;
+        screen = named && named[1].trim() ? { name: named[1].trim(), hasChecklist: false, answers: new Map(), prototype: null } : null;
         if (screen) screens.push(screen);
         checklistLevel = 0;
         continue;
@@ -160,6 +120,9 @@ export function parseScreens(markdown) {
       }
       continue;
     }
+    if (screen && !screen.prototype && PROTOTYPE_LINE_RE.test(line)) {
+      screen.prototype = PROTOTYPE_PATH_RE.exec(line)?.[1] ?? null;
+    }
     if (!screen || !checklistLevel) continue;
     const row = checklistRow(line);
     if (!row) continue;
@@ -178,47 +141,29 @@ const isNotApplicable = (answer) => NOT_APPLICABLE_RE.test(normalizeLabel(answer
 
 const labelOf = (id) => SCREEN_CHECKLIST_ITEMS.find((item) => item.id === id)?.label ?? id;
 
-/**
- * As superfícies que a persona `ui-designer` declara no `agents.json` — o
- * vocabulário válido do item `Superfície`, que o `morph-plan` §5a usa para
- * somar os standards da tela em `tasks[].standards`. Lê a cópia instalada do
- * projeto; sem ela (este repositório), a do pacote. Persona sem `surfaces`
- * (instalação anterior ao campo) devolve null: o valor não é validado.
- *
- * @param {string} cwd
- * @returns {string[]|null}
- */
+// O vocabulário válido de `Superfície`: as `surfaces` da `ui-designer`, da cópia instalada ou do pacote.
+// null quando a persona não declara o campo, e então o valor não é validado.
 export function knownSurfaces(cwd) {
+  const surfaces = readAgentsJson(cwd)?.agents?.['ui-designer']?.surfaces;
+  return surfaces && typeof surfaces === 'object' && !Array.isArray(surfaces) ? Object.keys(surfaces) : null;
+}
+
+/** The project's installed `agents.json`, else the package's; null when unreadable. */
+export function readAgentsJson(cwd) {
   for (const path of [join(cwd, '.morph', 'framework', 'agents.json'), PACKAGE_AGENTS]) {
     if (!existsSync(path)) continue;
-    try {
-      const surfaces = JSON.parse(readFileSync(path, 'utf8'))?.agents?.['ui-designer']?.surfaces;
-      return surfaces && typeof surfaces === 'object' && !Array.isArray(surfaces) ? Object.keys(surfaces) : null;
-    } catch {
-      return null;
-    }
+    try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
   }
   return null;
 }
 
-/** A resposta de `Superfície` nomeia uma das superfícies conhecidas? */
 function namesSurface(answer, surfaces) {
   const norm = normalizeLabel(answer);
   return surfaces.some((key) => new RegExp(`(^|[^a-z0-9-])${key}([^a-z0-9-]|$)`).test(norm));
 }
 
-/**
- * Audita o checklist do mockup: toda tela tem o bloco, e todo item tem uma
- * resposta escrita — e, quando `surfaces` é dado, a `Superfície` é uma delas.
- *
- * Sem nenhuma `## Tela:`, o mockup é `legacy` (isento) só quando declara telas
- * no formato antigo; qualquer outro formato é o problema "nenhuma tela
- * declarada" — senão trocar o heading seria o atalho para pular o checklist.
- *
- * @param {string} markdown
- * @returns {{ legacy: boolean, screens: Array<{ name: string, hasChecklist: boolean, missing: string[], unanswered: string[] }>,
- *   problems: string[] }} `problems` vazio ⇔ checklist completo (ou isento)
- */
+// Sem nenhuma `## Tela:`, só o formato antigo é legado; qualquer outro heading é "nenhuma tela
+// declarada", senão trocar o heading pularia o checklist.
 export function auditScreenChecklist(markdown, { surfaces = null } = {}) {
   const parsed = parseScreens(markdown);
   const problems = [];
@@ -246,69 +191,55 @@ export function auditScreenChecklist(markdown, { surfaces = null } = {}) {
         problems.push(`tela "${screen.name}": Superfície "${surface}" não é uma das superfícies da ui-designer (${surfaces.join(', ')})`);
       }
     }
-    return { name: screen.name, hasChecklist: screen.hasChecklist, missing, unanswered };
+    return { name: screen.name, hasChecklist: screen.hasChecklist, missing, unanswered, prototype: screen.prototype };
   });
   return { legacy: false, screens, problems };
 }
 
-/**
- * O sinal `screenChecklist` de um gate, lido do disco. COLETA, nunca decide:
- * quem pausa é o risk-detector.
- *
- * `mockups: false` é "a feature não tem mockup" — nada a cobrar. No review, o
- * que se cobra é a conferência (`uncovered`: itens decididos sem linha na
- * seção do avaliador), não o design, que já passou pelo Gate uiux.
- *
- * @param {string} cwd
- * @param {string} featureName
- * @param {string} gateName
- * @returns {{ mockups: boolean, legacy: boolean, screens: string[], problems: string[],
- *   exempt?: string, section?: boolean, uncovered?: string[] }}
- */
+// Linha **Protótipo:** da tela + o HTML + os prints do laço de autocrítica ao lado dele.
+export function auditPrototypes(screens, designDir) {
+  const problems = [];
+  for (const screen of screens) {
+    if (!screen.prototype) {
+      problems.push(`tela "${screen.name}" sem a linha \`**Protótipo:** 1-design/prototipos/<tela>.html\``);
+      continue;
+    }
+    const base = screen.prototype.replace(/\.html$/i, '');
+    const expected = [screen.prototype, ...PROTOTYPE_WIDTHS.map((width) => `${base}-${width}.png`)];
+    const missing = expected.filter((rel) => !existsSync(join(designDir, rel)));
+    if (missing.length) problems.push(`tela "${screen.name}": falta ${missing.map((rel) => `1-design/${rel}`).join(', ')}`);
+  }
+  return problems;
+}
+
+// Coleta, nunca decide: quem pausa é o risk-detector. No review cobra-se a conferência (`uncovered`), não o design.
 export function collectScreenChecklist(cwd, featureName, gateName) {
   const mockups = readMockups(cwd, featureName);
   if (mockups === null) return { mockups: false, legacy: false, screens: [], problems: [] };
   const audit = auditScreenChecklist(mockups, { surfaces: knownSurfaces(cwd) });
   const signal = { mockups: true, legacy: audit.legacy, screens: audit.screens.map((s) => s.name), problems: audit.problems };
   if (audit.legacy) signal.exempt = LEGACY_MOCKUP_EXEMPTION;
+  if (gateName === 'uiux' && !audit.legacy) {
+    const designDir = dirname(getAbsoluteOutputPath(cwd, featureName, 'uiMockups'));
+    signal.prototypes = auditPrototypes(audit.screens, designDir);
+  }
   if (gateName === 'review') {
-    const report = evaluatorScreenChecklist(cwd, featureName);
+    const report = verifierScreenChecklist(cwd, featureName);
     signal.section = report.section;
     signal.uncovered = checklistCoverage(mockups, report.section ? report.body : '');
   }
   return signal;
 }
 
-/**
- * Por que o Gate uiux NÃO pode ser aprovado com assinatura `auto` — a pausa
- * que o `gate-check uiux` daria pelo checklist —, ou null. Lido por `approve`
- * e `advance`, para que uma aprovação automática nunca passe onde o gate-check
- * pausaria. Uma decisão gravada com `pause: false` (o `gate-decision` manual,
- * ou um gate-check que não pausou) é a resposta a essa pausa e destrava — só
- * para o mockup que ela viu: a decisão guarda `mockupsHash`, e um mockup
- * escrito ou mudado depois dela volta a ser conferido.
- *
- * @param {string} cwd
- * @param {string} featureName
- * @param {object} feature - o feature.json (lê `gateDecisions.uiux`)
- * @returns {string|null}
- */
+// Lido por approve e advance para que o `auto` nunca passe onde o gate-check pausaria. Uma decisão com
+// `pause: false` destrava só o design que ela viu: guarda `mockupsHash`, e mudar o arquivo volta a conferir.
 export function uiuxAutoApprovalBlock(cwd, featureName, feature) {
   const decision = feature?.gateDecisions?.uiux;
   if (decision?.pause === false && decision.mockupsHash === mockupsHash(cwd, featureName)) return null;
   return uiuxChecklistPause(collectScreenChecklist(cwd, featureName, 'uiux'));
 }
 
-/**
- * O que o avaliador deixou de conferir: por tela do mockup, os itens com
- * decisão (nem "não se aplica", nem a superfície) sem linha na seção
- * `## Checklist de tela` do relatório. Uma linha que o avaliador marca como
- * não verificável conta como conferida — o que pausa é a AUSÊNCIA da linha.
- *
- * @param {string} designMarkdown - o `1-design/mockups.md`
- * @param {string} reportSection - o corpo da seção do `evaluator-report.md`
- * @returns {string[]} `"<tela>: <item>, <item>"` por tela com lacuna
- */
+// Linha marcada como não verificável conta como conferida: o que pausa é a ausência da linha.
 export function checklistCoverage(designMarkdown, reportSection) {
   const covered = new Map();
   for (const line of proseLines(reportSection)) {
@@ -332,14 +263,7 @@ export function checklistCoverage(designMarkdown, reportSection) {
   return gaps;
 }
 
-/**
- * O `1-design/mockups.md` por conteúdo: BOM e CRLF não contam, para que o
- * checkout de outra máquina seja o mesmo mockup.
- *
- * @param {string} cwd
- * @param {string} featureName
- * @returns {string|null} null sem mockup
- */
+// BOM e CRLF não contam: o checkout de outra máquina é o mesmo arquivo.
 export function mockupsHash(cwd, featureName) {
   const text = readMockups(cwd, featureName);
   if (text === null) return null;

package/src/lib/stack/dotnet-build-ignores.js

@@ -0,0 +1,43 @@
+import { readdirSync } from 'fs';
+import { join } from 'path';
+import { ensureDotnetBuildIgnores } from '../../utils/file-copier.js';
+import { getProjectTags } from '../stack-filter.js';
+import { readMorphConfig } from '../tasks/test-runner.js';
+import { readPlanChecks } from '../plan/checks.js';
+import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
+
+export const DOTNET_IMPLEMENTERS = ['dotnet-senior', 'ef-modeler', 'maf-expert'];
+
+const SKIPPED_DIRS = new Set([...WORKTREE_DIR_NAMES, 'node_modules', 'bin', 'obj']);
+const DOTNET_PROJECT_FILE = /\.(?:csproj|slnx?)$/i;
+const MAX_DEPTH = 6;
+
+export function hasDotnetProjectFile(root, depth = 0) {
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return false; }
+  if (entries.some((e) => e.isFile() && DOTNET_PROJECT_FILE.test(e.name))) return true;
+  if (depth >= MAX_DEPTH) return false;
+  return entries.some((e) => e.isDirectory() && !e.name.startsWith('.') && !SKIPPED_DIRS.has(e.name)
+    && hasDotnetProjectFile(join(root, e.name), depth + 1));
+}
+
+function planHasDotnetSlice(tree, featureName) {
+  if (!featureName) return false;
+  const { checks } = readPlanChecks(tree, featureName);
+  return (checks?.slices || []).some((slice) => DOTNET_IMPLEMENTERS.includes(String(slice.persona || '').replace(/^morph-/, '')));
+}
+
+// The plan's slices are checked because a greenfield tree has no stack or .csproj yet.
+export function isDotnetProject(tree, { featureName, configRoot = tree } = {}) {
+  if (getProjectTags(readMorphConfig(configRoot)).includes('dotnet')) return true;
+  return planHasDotnetSlice(tree, featureName) || hasDotnetProjectFile(tree);
+}
+
+/** Returns the `.gitignore` entries added; `[]` when not .NET or on any error. */
+export function seedDotnetBuildIgnores(tree, options = {}) {
+  try {
+    return isDotnetProject(tree, options) ? ensureDotnetBuildIgnores(tree) : [];
+  } catch {
+    return [];
+  }
+}

package/src/lib/stack/stack-profile.js

@@ -1,17 +1,6 @@
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 
-/** @typedef {'nextjs'|'dotnet'|'nodejs-cli'|'unknown'} StackName */
-
-/**
- * @typedef {Object} StackProfile
- * @property {StackName} stack
- * @property {boolean} isDotnet
- * @property {boolean} isNextjs
- * @property {string[]} defaultValidators
- * @property {string|null} buildCommand
- */
-
 const DOTNET_STACKS = new Set(['dotnet', 'aspnet']);
 const NEXTJS_STACKS = new Set(['nextjs', 'next', 'next.js']);
 const NO_VALIDATOR_STACKS = new Set(['nodejs-cli', 'node-cli', 'cli']);
@@ -34,9 +23,6 @@ const PROFILES = {
   },
 };
 
-/**
- * Read project stack from .morph/config/config.json.
- */
 function readStack(cwd) {
   const configPath = join(cwd, '.morph', 'config', 'config.json');
   if (!existsSync(configPath)) return null;
@@ -47,7 +33,6 @@ function readStack(cwd) {
   }
 }
 
-/** Merge two or more profiles' validator lists (deduped) and boolean flags. */
 function mergeProfiles(profiles) {
   return {
     isDotnet: profiles.some((p) => p.isDotnet),
@@ -57,16 +42,7 @@ function mergeProfiles(profiles) {
   };
 }
 
-/**
- * Get the StackProfile for the current project.
- *
- * `stack` may be a compound value (e.g. "dotnet-nextjs", "dotnet+nextjs") —
- * the framework's own convention for monorepos (see stack-filter.js's
- * getProjectTags, which splits project.stack the same way). Each segment is
- * resolved independently and matching profiles are merged, instead of the
- * whole compound string failing every exact-match check and silently
- * collapsing to the empty profile (0 default validators).
- */
+/** A compound stack ("dotnet-nextjs", "dotnet+nextjs") merges the profile of each segment. */
 export function getStackProfile(cwd, stackOverride) {
   const root = cwd ?? process.cwd();
   const raw = stackOverride ?? readStack(root);
@@ -74,8 +50,6 @@ export function getStackProfile(cwd, stackOverride) {
 
   const segments = stack.split(/[-+]/).filter(Boolean);
 
-  // Single-segment stack (the overwhelming common case): resolve exactly as
-  // before, byte-for-byte, including the 'unknown' → dotnet fallback.
   if (segments.length <= 1) {
     let profile;
     if (NEXTJS_STACKS.has(stack)) {
@@ -90,7 +64,6 @@ export function getStackProfile(cwd, stackOverride) {
     return { stack, ...profile };
   }
 
-  // Compound stack: resolve each recognized segment and merge.
   const matched = [];
   if (segments.some((s) => DOTNET_STACKS.has(s))) matched.push(PROFILES.dotnet);
   if (segments.some((s) => NEXTJS_STACKS.has(s))) matched.push(PROFILES.nextjs);