@softize/opus 11.1.1 → 12.0.0

package/CHANGELOG.md

@@ -4,7 +4,57 @@ O que muda em cada versão — e, quando quebra, **o que fazer**. Regras de leit
 minor = novidade compatível; major = breaking (a seção **Breaking** diz a migração).
 Este arquivo viaja no pacote: num projeto, leia `node_modules/@softize/opus/CHANGELOG.md`.
 Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
-`manifest:check`) — eles apontam o que a mudança cobra do seu código.
+`opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
+mudança cobra do seu código.
+
+## 12.0.0 — 2026-08-21
+
+**Copy declarativa passa a ter inventário semântico e gate reproduzível.** `opus copy`
+projeta texto estático dos contratos e de uma allowlist explícita de componentes
+`@softize/opus/ui` e subpaths para o protocolo v2 da `@softize/base`; `--check` confere
+ausência e drift sem escrever. Factories e componentes são reconhecidos pela origem do
+import, inclusive alias e namespace, sem confundir homônimo local. Spreads, duplicatas,
+chaves computadas literais e escopo léxico seguem a semântica real quando estáticos; uma
+incerteza relevante falha em vez de sumir do inventário. `aria-label` não mascara texto
+visual opaco, e `Select`/`ActionTrigger` têm suas superfícies estáveis classificadas.
+Fontes recebem SHA-256, a geração troca o arquivo atomicamente e não atravessa links simbólicos
+no caminho do inventário. O manifesto `source-manifest-v1` inclui todo JS/TS efetivamente
+analisado, mesmo sem entradas, e deriva as contagens de arquivos, fontes cobertas e textos;
+zero arquivo falha em vez de simular uma execução vazia. Transformações e exceções usam
+seletores explícitos em `base.json`; exceções v2 exigem `ruleId`, `kind`, `reason` e
+`reference` auditável.
+
+A Base 2.0 passa a ser a única dona da skill geral `write-product-communication`. O Opus não
+mantém um segundo registry com o mesmo slug; sua página `communication.md` registra somente
+vocabulário, papéis semânticos, cobertura e convenções específicas de componentes.
+
+`opus setup` configura e gera `.base/copy-inventory.json`. O fragmento
+`00-opus-copy` roda antes de `base` no dispatcher compartilhado, e projetos novos recebem
+scripts `setup`/`copy`/`copy:check` e `@softize/base ^2.0.0`. `pnpm run setup`
+materializa os dois fragmentos do pre-push, gerando o inventário Opus antes de a Base validar
+freshness. O próprio repositório e a release do Opus materializam e validam a Base 2.0.
+
+**Breaking — materialização e análise mais conservadoras.** A resolução dos hooks usa o workspace
+declarado em `base.json`, e o
+extrator não aceita como estáticas referências mutadas, escapadas nem condições JSX de tipo
+incerto. Superfícies visuais consideram `style.textTransform`, herança, slots e conteúdo ARIA
+opaco. Quando o texto não pode ser provado estaticamente, o diagnóstico exige copy estática ou
+uma exceção auditável em vez de omitir a superfície.
+
+As operações sobre o projeto passam a falhar de forma fechada quando encontram links
+simbólicos, hardlinks mutáveis ou caminhos que mudam durante a leitura/escrita. Isso vale para
+setup, inventário, scaffold, `add`, geração, comandos de banco e scans estáticos; assets internos
+do pacote continuam sendo lidos da instalação. `opus gen --config/--output` e `opus db --config`
+agora aceitam somente caminhos contidos no diretório do projeto em que o comando foi iniciado.
+Um source ilegível ou inseguro deixa de ser pulado silenciosamente e reprova o comando.
+
+**Migração:** instale `@softize/base 2.0.0`, rode `pnpm run setup`, revise e versione o
+inventário gerado. Corrija os achados de `base copy check`; para conteúdo dinâmico, forneça
+fallback estático ou documente a superfície fora da cobertura do extrator. O setup remove do
+projeto a configuração legada de `registry.softize.com.br`; remova também a configuração
+global antiga com `pnpm config delete @softize:registry --global`. Para gerar ou migrar conteúdo
+fora do projeto, execute o comando a partir dessa outra raiz ou mova a saída explicitamente
+depois que o gate terminar.
 
 ## 11.1.1 — 2026-08-21
 

package/README.md

@@ -82,7 +82,7 @@ src/
   core/      schema/    server/    client/    ui/
   data/      auth/      audit/     log/       queue/   events/   scheduler/   dsl/
 registry/    # scaffolds + skills Opus — geração e conhecimento do SDK, não runtime
-bin/         # CLI (opus setup/gen/check/introspect/mcp) + libs
+bin/         # CLI (opus setup/gen/copy/check/introspect/mcp) + libs
 docs/
   protocol.md   # contrato completo (16 seções)
   data-layer.md · releasing.md · code-style.md
@@ -102,6 +102,36 @@ pnpm test           # vitest run
 pnpm test:cov       # com coverage report
 ```
 
+## Qualidade de copy
+
+O Opus extrai o papel semântico dos textos declarados nos contratos; a política universal e
+seus fundamentos ficam na `@softize/base`. Uma allowlist pequena também cobre texto estático
+de componentes importados diretamente de `@softize/opus/ui` ou seus subpaths. O inventário
+derivado usa o protocolo v2, é versionado e conferido sem escrita nos gates:
+
+```bash
+# No projeto criado por `opus create` (o scaffold declara este script):
+pnpm run setup
+pnpm exec opus copy
+pnpm exec opus copy --check
+pnpm exec base copy check
+```
+
+Neste repositório-fonte, que não declara um script `setup` na raiz, a materialização
+equivalente usa os comandos reais e os cwd exigidos por cada protocolo:
+
+```bash
+node packages/opus/bin/cli.mjs setup
+pnpm --filter @softize/opus exec base setup
+```
+
+O manifesto lista com hash todo JS/TS submetido à análise, inclusive arquivos com zero entradas,
+e reporta as contagens observáveis; ele não afirma cobertura total do repositório. O gate verde
+não cobre JSX nativo nem wrappers locais; essas superfícies continuam na revisão editorial.
+Texto de runtime que ocupa uma superfície Opus mapeada falha visivelmente, e `aria-label` não
+mascara copy visual opaca. Detalhes e mapeamentos estão em
+[docs/code-style.md](docs/code-style.md).
+
 ## Publicar
 
 Publicado no npm público (`registry.npmjs.org`). `pnpm release

package/bin/cli.mjs

@@ -15,10 +15,18 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import {
+  canonicalProjectDirectory,
+  ensureProjectDirectory,
+  readProjectFile,
+  safeProjectPath,
+  writeProjectFileAtomically,
+} from '@softize/base/project-path'
 
 import { cmdGen, helpGen } from './lib/gen.mjs'
 import { cmdDb } from './lib/db.mjs'
 import { scanDir, emptyScanVerdict } from './lib/check.mjs'
+import { checkCopyInventory, writeCopyInventory } from './lib/copy.mjs'
 import { createMonorepo, createProject } from './lib/create.mjs'
 import { initProject, repoRootOf, setupUiFoundation } from './lib/init.mjs'
 import { introspect } from './lib/introspect.mjs'
@@ -54,13 +62,12 @@ async function fileExists(p) {
 }
 
 async function loadComponentsJson(cwd) {
-  const candidate = path.join(cwd, 'components.json')
-  if (!(await fileExists(candidate))) {
+  const candidate = readProjectFile(cwd, 'components.json', { allowMissing: true })
+  if (!candidate.exists) {
     return null
   }
   try {
-    const raw = await fs.readFile(candidate, 'utf-8')
-    return JSON.parse(raw)
+    return JSON.parse(candidate.content)
   } catch (err) {
     log('warn', `components.json existe mas não é JSON válido: ${err.message}`)
     return null
@@ -84,12 +91,12 @@ async function resolveDestination(cwd, name) {
       'warn',
       'Sem components.json. Usando default ./src/components/action/. Roda `npx shadcn init` se quiser configurar.',
     )
-    return path.join(cwd, 'src/components/action', `${name}.tsx`)
+    return path.join('src/components/action', `${name}.tsx`)
   }
   const aliasComponents =
     components.aliases?.components ?? '@/components'
   const componentsRel = resolveAlias(aliasComponents, 'components')
-  return path.join(cwd, 'src', componentsRel, 'action', `${name}.tsx`)
+  return path.join('src', componentsRel, 'action', `${name}.tsx`)
 }
 
 async function listTemplates() {
@@ -140,26 +147,34 @@ async function cmdAdd(name, options) {
     process.exit(1)
   }
 
-  const cwd = process.cwd()
+  const cwd = canonicalProjectDirectory(process.cwd())
   const src = path.join(REGISTRY_DIR, `${name}.tsx`)
   const dest = await resolveDestination(cwd, name)
+  safeProjectPath(cwd, dest)
+  const current = readProjectFile(cwd, dest, { allowMissing: true })
 
-  if (await fileExists(dest)) {
+  if (current.exists) {
     if (options.force !== true) {
       log(
         'warn',
-        `Já existe em ${path.relative(cwd, dest)} — passa --force pra sobrescrever.`,
+        `Já existe em ${dest} — passa --force pra sobrescrever.`,
       )
       process.exit(1)
     }
-    log('warn', `Sobrescrevendo ${path.relative(cwd, dest)}`)
+    log('warn', `Sobrescrevendo ${dest}`)
   }
 
-  await fs.mkdir(path.dirname(dest), { recursive: true })
+  const parents = []
+  let parent = path.dirname(dest)
+  while (parent !== '.') {
+    parents.unshift(parent)
+    parent = path.dirname(parent)
+  }
+  for (const directory of parents) ensureProjectDirectory(cwd, directory)
   const content = await fs.readFile(src, 'utf-8')
-  await fs.writeFile(dest, content, 'utf-8')
+  writeProjectFileAtomically(cwd, dest, content, { exists: current.exists, content: current.content })
 
-  log('success', `✓ Criado ${path.relative(cwd, dest)}`)
+  log('success', `✓ Criado ${dest}`)
   console.log(
     '\n  Edita à vontade — esse arquivo é seu agora. Próximas runs com --force\n  sobrescrevem suas mudanças.\n',
   )
@@ -219,6 +234,32 @@ async function cmdMaterializationCheck() {
   log('success', '✓ opus check: artefatos materializados estão atualizados.')
 }
 
+async function cmdCopy(dir, flags) {
+  const selected = path.resolve(process.cwd(), dir ?? '.')
+  const root = (await repoRootOf(selected)) ?? selected
+  const result = flags.check ? checkCopyInventory(root) : writeCopyInventory(root)
+  for (const diagnostic of result.diagnostics) {
+    log('error', `✗ opus copy: ${diagnostic.source}:${diagnostic.line} — ${diagnostic.message}`)
+  }
+  if (!result.ok) {
+    if (result.reason === 'missing') {
+      log('error', `✗ opus copy: inventário ausente em ${path.relative(root, result.path)}; rode \`opus copy\` e versione o resultado.`)
+    } else if (result.reason === 'stale') {
+      log('error', `✗ opus copy: inventário desatualizado em ${path.relative(root, result.path)}; rode \`opus copy\` e revise o diff.`)
+    }
+    process.exitCode = 1
+    return
+  }
+  const location = path.relative(root, result.path) || '.'
+  const coverage = result.inventory.coverage
+  const summary =
+    `${coverage.analyzedFiles} arquivo(s) analisado(s), ` +
+    `${coverage.coveredSources} fonte(s) com copy, ${coverage.extractedEntries} texto(s)`
+  if (flags.check) log('success', `✓ opus copy: ${location} está atualizado (${summary}).`)
+  else if (result.changed) log('success', `✓ opus copy: ${location} gerado atomicamente (${summary}).`)
+  else log('success', `✓ opus copy: ${location} já estava atualizado (${summary}).`)
+}
+
 async function cmdCreate(dir, flags) {
   if (!dir) {
     log('error', 'Uso: opus create <dir> — o nome do diretório vira o nome do app (--monorepo: a raiz do workspace).')
@@ -229,8 +270,8 @@ async function cmdCreate(dir, flags) {
 
   if (flags.monorepo) {
     const r = await createMonorepo(REGISTRY_DIR, target, name)
-    log('success', `✓ opus create: raiz do monorepo "${name}" criada (base v${r.version}).`)
-    console.log(`\n  ${r.files.length} arquivos (workspace apps/* + packages/*, registry, allowBuilds).`)
+    log('success', `✓ opus create: raiz do monorepo "${name}" criada (Opus v${r.version}).`)
+    console.log(`\n  ${r.files.length} arquivos (workspace apps/* + packages/*, allowBuilds e quarentena coordenada).`)
     console.log(`
   Próximos passos:
     cd ${dir}
@@ -245,7 +286,7 @@ async function cmdCreate(dir, flags) {
     throw new Error(`setup incompleto: ${r.setup.materialization.errors.join(' | ')}`)
   }
   const modeLabel = r.mode === 'app' ? 'app no monorepo (workspace detectado)' : 'repo standalone'
-  log('success', `✓ opus create: app "${name}" criado (base v${r.version}, ${modeLabel}).`)
+  log('success', `✓ opus create: app "${name}" criado (Opus v${r.version}, ${modeLabel}).`)
   console.log(`\n  ${r.files.length} arquivos do esqueleto + setup (${r.setup.created.join(', ')}).`)
   const warnings = [...r.warnings, ...r.setup.warnings]
   if (warnings.length) {
@@ -256,7 +297,8 @@ async function cmdCreate(dir, flags) {
     console.log(`
   Próximos passos (no monorepo):
     pnpm install
-    pnpm --filter ${name} test && pnpm --filter ${name} manifest
+    pnpm --filter ${name} run setup
+    pnpm --filter ${name} test && pnpm --filter ${name} copy:check && pnpm --filter ${name} manifest
 
   Opcional: cadastre o app em uma interface de desenvolvimento como o Maestro.
 `)
@@ -264,9 +306,11 @@ async function cmdCreate(dir, flags) {
     console.log(`
   Próximos passos:
     cd ${dir}
-    git init && git add -A && git commit -m "chore: esqueleto opus"
+    git init
     pnpm install
-    pnpm test && pnpm exec opus check src && pnpm manifest
+    pnpm run setup
+    pnpm test && pnpm exec opus check src && pnpm copy:check && pnpm manifest
+    git add -A && git commit -m "chore: esqueleto opus"
 
   Opcional: cadastre o repo em uma interface de desenvolvimento como o Maestro.
 `)
@@ -279,6 +323,7 @@ async function cmdInit() {
   if (!r.materialization.ok) {
     for (const error of r.materialization.errors) log('error', `✗ opus setup: ${error}`)
     process.exitCode = 1
+    return
   }
   log('success', `✓ opus setup: app v${r.version} ${r.wasInitialized ? 'atualizado' : 'inicializado'}.`)
   if (r.created.length) {
@@ -311,7 +356,7 @@ async function cmdInit() {
   }
 
   console.log(
-    '\n  Per-app: opus.json. No repo: base.json + skills/hooks/instruções comitados.\n' +
+    '\n  Por app: opus.json. No repo: base.json + skills/hooks/instruções específicos do Opus.\n' +
       '  A spec vive nas declarações (description → manifest). Gate: opus check.\n',
   )
 }
@@ -402,9 +447,10 @@ Comandos:
   create <dir>     Scaffolda um app opus-based canônico (vite+react+ui+domínio-exemplo);
                    detecta workspace (app em monorepo); --monorepo cria a RAIZ do workspace
   setup            Reconcilia opus.json e os artefatos Opus versionados para Claude/Codex
-  add <name>       Copia template do registry pro consumer
+  add <name>       Copia template do catálogo empacotado pro projeto
   list             Lista templates disponíveis
   gen              Gera manifest/openapi/docs/stubs a partir do opus.config.ts
+  copy [dir]       Gera o inventário semântico de copy dos contratos; --check só confere
   check [dir]      Valida as convenções das actions (régua de padrão; exit ≠ 0 se violar)
   pre-push         Gate Git: freshness dos artefatos + convenções das actions
   db <verbo>       Comandos de banco. v1: db check (drift-check entidade ↔ banco)
@@ -414,6 +460,7 @@ Comandos:
 
 Flags:
   --force, -f      Sobrescreve arquivo existente
+  --check          Não escreve; falha se o inventário de copy estiver ausente/desatualizado
   --config <path>  (gen) Caminho do opus.config.ts
   --output <path>  (gen) Pasta de saída
 
@@ -432,13 +479,13 @@ Exemplos:
 @softize/opus create <dir>
 
 Scaffolda um app opus-based CANÔNICO no diretório <dir> (recusa dir não-vazio).
-O esqueleto versiona com a base — nasce com os pré-requisitos plugados:
+O esqueleto versiona com o Opus — nasce com os pré-requisitos plugados:
   protocolo   opus.config.ts + domínio-exemplo + manifest/scripts (+ teste verde)
   UI          vite + react + tailwind v4 CSS-first (tema + @source do Opus)
   desenvolvimento dev server na porta injetada (PORT) + allowedHosts do preview
-  dia zero    opus.json + skills/hooks/instruções comitados no repo
+  automação   opus.json + skills/hooks/instruções específicos do Opus
 
-Depois: git init && pnpm install && pnpm test — e cadastre repo/app no admin.
+Depois: git init && pnpm install && pnpm run setup && pnpm test — e cadastre repo/app no admin.
 `)
       return
     }
@@ -453,14 +500,16 @@ Depois: git init && pnpm install && pnpm test — e cadastre repo/app no admin.
 
 Setup idempotente de um projeto Opus:
   opus.json        marcador per-app com a versão do SDK
-  base.json        versão aplicada e eventuais skills excluídas
-  agentes          skills Claude/Codex, hook, instruções e pre-push comitados
+  base.json        configuração compartilhada e versão aplicada do Opus
+  agentes          skills, hook, instruções e pre-push específicos do SDK
 
 Fundação de UI (só apps web — preset Tailwind + tema + flags do Opus):
   tailwind.config  criado se faltar; senão avisa pra estender o preset
   tema/tsconfig/dep — avisa o que falta plugar (não edita seus arquivos: sem clobber)
 
-O próprio pacote materializa somente seus artefatos. Base e Maestro são opcionais.
+Este comando materializa somente os artefatos Opus. O template encadeia
+\`opus setup && base setup\`: a Base 2.0 é obrigatória quando o gate universal de copy
+está habilitado; Maestro continua opcional.
 `)
       return
     }
@@ -524,6 +573,27 @@ passa verde). Default dir: cwd.
     return
   }
 
+  if (command === 'copy') {
+    if (flags.help) {
+      console.log(`
+@softize/opus copy [dir]
+
+Projeta textos de \`defineAction\`/\`defineContract\` no protocolo v2 da
+@softize/base. O caminho vem de \`base.json.copy.inventory\`; o default é
+\`.base/copy-inventory.json\` na raiz Git. A geração é atômica e o arquivo
+derivado deve ser versionado. O manifesto \`source-manifest-v1\` hasheia todo
+JS/TS analisado, mesmo sem entradas; zero arquivo elegível falha porque não
+comprova que o extrator executou sobre uma fonte.
+
+Flags:
+  --check          Compara sem escrever; falha em ausência, drift ou copy dinâmica
+`)
+      return
+    }
+    await cmdCopy(rest[0], flags)
+    return
+  }
+
   if (command === 'pre-push') {
     if (rest[0] === 'materialization') await cmdMaterializationCheck()
     else await cmdCheck(rest[0] ?? '.')

package/bin/lib/check.mjs

@@ -21,9 +21,14 @@
  * É a régua do reviewer e a métrica de padrão.
  */
 
-import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import ts from 'typescript'
+import {
+  canonicalProjectDirectory,
+  readProjectDirectory,
+  readProjectFile,
+  safeProjectPath,
+} from '@softize/base/project-path'
 
 // Ordem canônica (grupos do ActionBase em src/core/types.ts). Campos kind-específicos
 // (fields/paginate/filters/expand/background/emits/successStatus…) NÃO entram no mapa —
@@ -480,63 +485,70 @@ const UI_SKIP_DIRS = new Set([...SKIP_DIRS, '__tests__', '__fixtures__', 'fixtur
 const UI_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.css', '.html', '.svelte', '.vue'])
 
 export async function walkTsFiles(dir, acc = []) {
-  let entries
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true })
-  } catch {
-    return acc
-  }
-  for (const e of entries) {
-    if (e.name.startsWith('.') && e.name !== '.') continue
-    const full = path.join(dir, e.name)
-    if (e.isDirectory()) {
-      if (!SKIP_DIRS.has(e.name)) await walkTsFiles(full, acc)
-    } else if (
-      (e.name.endsWith('.ts') || e.name.endsWith('.tsx')) &&
-      !e.name.endsWith('.d.ts') &&
-      !e.name.endsWith('.test.ts')
-    ) {
-      acc.push(full)
+  const root = canonicalProjectDirectory(dir)
+  const walk = (local = '.') => {
+    const entries = readProjectDirectory(root, local).entries
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.name !== '.') continue
+      if (SKIP_DIRS.has(e.name)) continue
+      const relative = path.join(local, e.name)
+      const full = path.join(root, relative)
+      if (e.isSymbolicLink()) {
+        // Dirent não revela se o link aponta para arquivo ou diretório. Ignorá-lo pela
+        // extensão permitiria ocultar uma árvore de sources sob um nome de asset.
+        safeProjectPath(root, relative, { mustExist: true })
+      }
+      if (e.isDirectory()) {
+        safeProjectPath(root, relative, { mustExist: true })
+        walk(relative)
+      } else if (
+        (e.name.endsWith('.ts') || e.name.endsWith('.tsx')) &&
+        !e.name.endsWith('.d.ts') &&
+        !e.name.endsWith('.test.ts')
+      ) {
+        safeProjectPath(root, relative, { mustExist: true })
+        acc.push(full)
+      }
     }
   }
+  walk()
   return acc
 }
 
 async function walkUiFiles(dir, acc = []) {
-  let entries
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true })
-  } catch {
-    return acc
-  }
-  for (const e of entries) {
-    if (e.name.startsWith('.')) continue
-    const full = path.join(dir, e.name)
-    if (e.isDirectory()) {
-      if (!UI_SKIP_DIRS.has(e.name)) await walkUiFiles(full, acc)
-    } else if (UI_EXTENSIONS.has(path.extname(e.name)) && !/\.(?:test|spec)\.[^.]+$/.test(e.name)) {
-      acc.push(full)
+  const root = canonicalProjectDirectory(dir)
+  const walk = (local = '.') => {
+    const entries = readProjectDirectory(root, local).entries
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue
+      if (UI_SKIP_DIRS.has(e.name)) continue
+      const relative = path.join(local, e.name)
+      const full = path.join(root, relative)
+      if (e.isSymbolicLink()) {
+        // Um link com nome de asset ainda pode esconder um diretório com UI analisável.
+        safeProjectPath(root, relative, { mustExist: true })
+      }
+      if (e.isDirectory()) {
+        safeProjectPath(root, relative, { mustExist: true })
+        walk(relative)
+      } else if (UI_EXTENSIONS.has(path.extname(e.name)) && !/\.(?:test|spec)\.[^.]+$/.test(e.name)) {
+        safeProjectPath(root, relative, { mustExist: true })
+        acc.push(full)
+      }
     }
   }
+  walk()
   return acc
 }
 
-async function exists(p) {
-  try {
-    await fs.access(p)
-    return true
-  } catch {
-    return false
-  }
-}
-
 /** Escaneia um diretório → { files, actions, contracts, findings, hasMarker }.
  *  `hasMarker` = o diretório é um projeto opus (tem opus.json na raiz). */
 export async function scanDir(rootDir) {
+  rootDir = canonicalProjectDirectory(rootDir)
   const files = await walkTsFiles(rootDir)
   const sources = []
   for (const file of files) {
-    const text = await fs.readFile(file, 'utf-8')
+    const text = readProjectFile(rootDir, path.relative(rootDir, file)).content
     if (!ACTION_MARKERS.some((m) => text.includes(m))) continue
     sources.push({ file: path.relative(rootDir, file), text })
   }
@@ -545,10 +557,10 @@ export async function scanDir(rootDir) {
   // UI pode morar em src/, app/, pages/ ou na raiz. O walk cobre o projeto inteiro e
   // exclui dependências, builds, testes e fixtures para não interpretar exemplos como uso.
   for (const file of await walkUiFiles(rootDir)) {
-    const text = await fs.readFile(file, 'utf-8')
+    const text = readProjectFile(rootDir, path.relative(rootDir, file)).content
     uiFindings.push(...checkUiMigrations(path.relative(rootDir, file), text))
   }
-  const hasMarker = await exists(path.join(rootDir, 'opus.json'))
+  const hasMarker = safeProjectPath(rootDir, 'opus.json').exists
   return {
     files: files.length,
     actions: checked.actions,