@softize/opus 11.1.1 → 12.0.0

package/docs/code-style.md

@@ -5,12 +5,147 @@ order: 5
 
 # Code style — padrão softize
 
-Este arquivo registra as convenções editoriais da documentação do Opus. Regras
-transversais de engenharia pertencem à `@softize/base`; o Opus mantém apenas o que é
-específico do SDK e seus gates.
+Este arquivo registra somente convenções específicas do Opus. Princípios gerais de
+comunicação humana pertencem à skill `write-product-communication` da `@softize/base`;
+as regras universais mecanicamente verificáveis de copy pertencem à política versionada,
+em `docs/copy-policy.md` daquele pacote.
 
-Resumo de uma linha: **código em inglês; o que humano lê (UI, comentário, doc) em pt-BR;
-frases com maiúscula e ponto; labels curtos sem ponto.**
+No Opus, `label`, `messages`, `fields`, `filters`, `columns`, confirmação e demais textos
+de interface vivem no contrato quando descrevem a operação, não numa tela isolada. O comando
+`opus copy` projeta essas propriedades para o inventário semântico que a Base valida; ele não
+reimplementa a política.
 
-O que dá, é regra executável no `opus check` (naming `<resource>.<verb>`, ordem dos
-campos do spec, registro no runtime); o restante vem das instruções versionadas no repo.
+As convenções executáveis próprias do SDK continuam no `opus check`: naming
+`<resource>.<verb>`, ordem dos campos do spec, segurança e registro no runtime.
+
+## Inventário de copy
+
+```bash
+pnpm exec opus copy            # regenera atomicamente o arquivo derivado
+pnpm exec opus copy --check    # CI/pre-push: compara sem escrever
+pnpm exec base copy check      # aplica a política universal
+```
+
+O inventário `.base/copy-inventory.json` é derivado e versionado. No protocolo
+`source-manifest-v1`, cada arquivo JavaScript/TypeScript efetivamente analisado entra com
+SHA-256, inclusive quando não contém uma superfície Opus ou produz zero entradas. O bloco
+`coverage` registra `analyzedFiles`, fontes distintas que produziram copy e entradas extraídas;
+as contagens são derivadas do próprio manifesto. Zero texto é válido após analisar uma fonte,
+mas zero arquivo não comprova execução e reprova. O pre-push roda `00-opus-copy` antes do
+fragmento `base`: ausência ou drift falham sem modificar silenciosamente o worktree.
+O caminho do inventário precisa permanecer dentro da raiz real do projeto; nenhum diretório nem
+o próprio arquivo pode ser link simbólico, tanto na leitura quanto na escrita. Links simbólicos
+no escopo de source também reprovam (a menos que o caminho esteja explicitamente excluído), em
+vez de reduzir a cobertura em silêncio.
+
+O extrator é deliberadamente estático. Aceita texto literal, concatenação de literais,
+`I18nRef` com `default` literal, constantes `const` no escopo lexical correto, propriedades
+computadas com chave literal e spreads de objetos/arrays igualmente estáticos. Duplicatas e
+spreads seguem a ordem real do JavaScript; um override posterior conhecido pode fechar uma
+incerteza anterior. Em contratos
+e em props, `aria-label` ou filhos de componentes Opus mapeados, uma superfície presente mas
+dinâmica, importada sem fallback ou composta de forma opaca reprova a extração. Isso torna
+lacunas conhecidas visíveis em vez de produzir um inventário verde e incompleto.
+
+Transformações visuais não observáveis e exceções ficam explícitas em `base.json`, usando um
+seletor estável e revisável. `source`, `line` e `role` devem identificar exatamente uma entrada;
+`text` é um refinamento opcional. Mudanças que invalidam o seletor reprovam a extração. Metadata
+pode complementar a análise, mas nunca sobrescrever uma transformação já observada no JSX —
+`transform: "none"` não mascara `className="uppercase"`. O Opus valida o shape `COPYnnn`; a
+Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada regra:
+
+```json
+{
+  "copy": {
+    "inventory": ".base/copy-inventory.json",
+    "allowedUppercase": ["CPF"],
+    "exclude": ["scripts/fixtures/**"],
+    "transforms": [
+      { "source": "src/account.ts", "line": 12, "role": "button", "transform": "uppercase" }
+    ],
+    "exemptions": [
+      {
+        "source": "src/account.ts",
+        "line": 18,
+        "role": "label",
+        "ruleId": "COPY001",
+        "kind": "external-requirement",
+        "reason": "Código regulatório exibido na grafia oficial.",
+        "reference": "regulation:ABC-123"
+      }
+    ]
+  }
+}
+```
+
+| Propriedade Opus | Papel no protocolo Base |
+|---|---|
+| `label`, `confirm.*Label`, `ActionTrigger.label` | `button` |
+| `title`, `examples[].name` | `title` |
+| `summary`, `description`, `examples[].description`, `expand.*.description` | `description` |
+| `messages.success`, `messages.error`, `messages.confirmation` | `success`, `error`, `message` |
+| `confirm.message` | `dialog-body` |
+| `fields.*.label`, `filters.*.label` | `label` |
+| `placeholder`, `hint`, `help` | `placeholder`, `helper-text` |
+| opções estáticas | `menu-item` |
+| `columns[].label`, `periods[].label` | `heading`, `tab` |
+| `Select.emptyText`, `Select.searchPlaceholder` | `empty-state`, `placeholder` |
+| `Select.options[].hint/triggerLabel/group` | `label`, `label`, `heading` |
+| `ActionTrigger.confirm.*` | papel correspondente do diálogo |
+
+## Cobertura e significado do gate verde
+
+O extrator cobre duas superfícies, sem heurística de nome:
+
+1. propriedades estáticas de `defineAction` e `defineContract` descritas acima, somente
+   quando a factory resolve por símbolo a um import de `@softize/opus` ou
+   `@softize/opus/core`; alias, namespace e destructuring `const` de namespace funcionam,
+   homônimo local não é contrato;
+2. texto estático em filhos e props de uma allowlist de componentes importados diretamente
+   de `@softize/opus/ui*` — por exemplo, `Button`, `DialogTitle`, `DialogDescription`,
+   `FieldLabel`, `TabsTrigger`, `Page`, `Input` e `DataState`. Alias e namespace de import
+   continuam rastreáveis. `uppercase`, variantes como `sm:hover:uppercase`, modificadores
+   `!uppercase`/`uppercase!` e classes em descendentes são projetados na superfície que
+   realmente herda o CSS. Props específicas também respeitam a implementação: por exemplo,
+   `ActionFormCard.cardClassName` alcança título/descrição, enquanto `className` alcança só o
+   form; o portal do Select custom não herda a classe do gatilho. `className` dinâmico numa
+   superfície afetada reprova, pois poderia aplicar a transformação sem registrá-la. Ícones
+   decorativos em filhos devem declarar
+   `aria-hidden="true"`; componentes somente com ícone usam um `aria-label` estático como
+   nome acessível. Um `aria-label` não apaga nem substitui copy visual: texto visível aninhado
+   estático e inequívoco também entra no inventário, inclusive quando um ancestral
+   `aria-hidden` o remove apenas da árvore de acessibilidade; folhas sob esse ancestral são
+   decorativas, sem mascarar texto visual. `null`, booleanos e `void` não viram copy.
+   Composições em múltiplos fragmentos que exigiriam adivinhar espaçamento
+   ou accessible name também reprovam em vez de gerar um texto diferente do renderizado.
+
+`Select` custom cobre `placeholder`, `searchPlaceholder`, `emptyText` e cada campo textual de
+`options`; no modo nativo inventaria somente o que o `<select>` realmente renderiza
+(`placeholder`, `label` e `group`). A classe do Select alcança o placeholder e o rótulo/chip
+do gatilho custom, mas não busca, vazio, hint ou menu no portal. `ActionTrigger` cobre `label`
+e todo o objeto `confirm`; sua classe alcança o label do botão, mas não confirmação nem tooltip
+do modo ícone. `itemLabel` fica fora de
+propósito: ele identifica o dado alvo em runtime (por exemplo, `customer.name`), não uma frase
+autoral da interface. Arrays, objetos ou discriminadores dinâmicos falham visivelmente.
+`content`, `triggerLabel` e demais `ReactNode` mapeados aceitam uma composição estática e
+inequívoca; entidades JSX são decodificadas antes do inventário. Fragmentos cuja concatenação
+exigiria adivinhar espaços continuam reprovando.
+
+Um `opus copy --check` verde **não significa que toda a copy do produto foi coberta**. Ficam
+fora, deliberadamente:
+
+- JSX nativo (`h1`, `p`, `button`) e componentes locais/wrappers, pois o Opus não conhece
+  seu papel semântico;
+- texto vindo de API, banco, catálogo i18n importado ou variável de runtime em superfícies
+  que o Opus não classifica. Quando esse conteúdo ocupa uma prop ou filho mapeado, a extração
+  falha e pede um fallback estático;
+- props ou componentes de terceiros sem contrato Opus;
+- copy escondida em CSS ou pseudo-elemento. Para uma transformação conhecida que o AST não
+  enxerga globalmente, use `copy.transforms`; em componente Opus mapeado, `className` opaco
+  reprova para não mascarar `uppercase`.
+
+Essas superfícies continuam obrigatórias na revisão humana/por IA da Base. O verde do gate
+prova o manifesto dos arquivos que o extrator declara ter analisado e a conformidade mecânica
+**das entradas inventariadas**, não cobertura total do repositório nem da interface. Ampliar a
+allowlist exige papel inequívoco no componente Opus e teste; não se infere semântica pelo nome
+de componente do consumidor.

package/docs/consumer-upgrade-propagation.md

@@ -10,7 +10,7 @@ pretende usar.
 
 Há três sinais diferentes e eles não devem ser confundidos:
 
-1. **disponível:** versão publicada no registry;
+1. **disponível:** versão publicada no npm;
 2. **adotada:** versão comitada na branch principal do consumidor;
 3. **aplicada:** versão presente na worktree e nos artefatos materializados.
 
@@ -21,7 +21,8 @@ Há três sinais diferentes e eles não devem ser confundidos:
 - A branch principal de cada consumidor é a autoridade sobre a versão adotada. Uma versão
   apenas publicada não bloqueia trabalho nem CI.
 - Quando um consumidor decide atualizar, a skill `upgrade-opus` lê o changelog, atualiza
-  manifests e lockfile, executa `opus setup` e conduz as migrações no próprio contexto.
+  manifests e lockfile, executa `pnpm run setup` (ou o script filtrado do workspace) e
+  conduz as migrações no próprio contexto.
 - O Maestro compara a versão aplicada na sessão com a versão adotada pela branch principal e
   apresenta o drift. A correção continua sendo puxar/reconciliar a branch; o Maestro não
   reimplementa o upgrade do pacote.
@@ -33,7 +34,7 @@ Há três sinais diferentes e eles não devem ser confundidos:
 - Publicação e adoção permanecem desacopladas; cada consumidor atualiza no seu próprio fluxo
   e passa pelos seus gates.
 - Worktrees com trabalho em andamento nunca são sobrescritas por uma release.
-- O diagnóstico funciona sem consultar o registry durante cada commit ou review; isso evita
+- O diagnóstico funciona sem consultar o npm durante cada commit ou review; isso evita
   transformar disponibilidade em política e mantém os gates reproduzíveis.
 - O conhecimento durável fica no changelog, nos detectores de migração e nas instruções
   materializadas, sem depender de uma infraestrutura externa de automação.

package/docs/releasing.md

@@ -5,8 +5,8 @@ order: 6
 
 # Publicar o @softize/opus
 
-O Opus é publicado no **npm público** (`registry.npmjs.org`). O registry próprio foi
-aposentado; clientes instalam sem configuração ou token de leitura.
+O Opus é publicado no **npm público** (`registry.npmjs.org`). Clientes instalam sem
+configuração de escopo ou token de leitura.
 
 > O `publishConfig` do `package.json` já aponta para o npm — `pnpm publish` "só funciona",
 > sem `--registry`. Não precisa decorar a URL.
@@ -19,20 +19,20 @@ pnpm release minor      # minor
 pnpm release major      # major
 pnpm release 2.9.0      # versão explícita
 pnpm release none       # publica sem bump
+pnpm release none --dry-run  # materializa e valida, sem publicar/commitar/push
 ```
 
 Auth: o token do npm no `~/.npmrc` global (`//registry.npmjs.org/:_authToken=…`),
 NÃO commitado.
 
-## Não existe caminho pela CI (29/jul)
+## Publicação não roda na CI
 
 A camada de GitHub Actions foi **removida** deste repo — `.github/` não existe mais. Saíram
 o `release.yml` (publicava por tag `v*`), o `deploy.yml` (doc, já reserva) e o `check.yml`
 (typecheck+test em push/PR). É a mesma decisão do monorepo (ADR 0008 do softize): um
 caminho só, na estação, com os gates junto. Não há gatilho de reserva.
 
-O secret **`OPUS_REGISTRY_TOKEN`** ficou órfão — nada mais o lê. Apague no GitHub. O que
-autentica hoje é o token do npm no seu `~/.npmrc` global.
+O token usado para publicar é exclusivamente o token do npm no `~/.npmrc` global.
 
 **O que o `release.sh` absorveu**, porque sem CI ficaria sem dono:
 
@@ -40,32 +40,43 @@ autentica hoje é o token do npm no seu `~/.npmrc` global.
   `main`, com árvore limpa (`--porcelain`, que pega não-rastreado) e igual a `origin/main`.
   Rodam ANTES do bump, que suja a árvore de propósito. Antes isso vinha de graça: a release
   nascia de um checkout limpo da tag, e a árvore do dev nunca entrava no tarball.
-- **Bump na main, automático** — a guarda `tag=versão` do CI existia pra impedir registry e
-  main divergindo em silêncio. Como aqui o bump acontece DEPOIS (o script versiona e
-  publica), a proteção equivalente é o script commitar e empurrar o bump sozinho ao fim. Se
-  o push falhar depois de o publish ter ido, ele grita e sai 1 — a versão existe pro cliente
-  e não existe no repo, e isso não pode passar como aviso no meio do log.
+- **Bump e derivados na main** — o script bumpeia primeiro, materializa o Opus na raiz e a
+  Base a partir de `packages/opus` (o workspace que declara a dependência), regenera
+  inventário e só então executa os gates. Antes de publicar, commita todo o diff produzido
+  (`package.json`, pins, inventário e projeções); depois do publish, empurra esse commit. Se
+  o push falhar, ele grita e sai 1 — a versão existe para o cliente e o commit fica local
+  para recuperação imediata.
 - **Smoke do esqueleto** — já tinha descido pro script antes (ver abaixo).
 
 `--local` (Verdaccio) não passa pelas guardas de procedência: é sandbox, e exigir main limpa
 pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
-**Gate de qualidade**: antes de bumpar/publicar roda `pnpm typecheck`
-+ `pnpm test` e **aborta a release se qualquer um falhar**. Como o Opus **ship source** (`.ts`,
-sem build), essa é a última barreira antes do tarball — sem ela, um `tsc` vermelho vaza pro
-cliente. Emergência (evite): `pnpm release --skip-checks`.
+**Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
+`pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
+se qualquer um falhar**. O Opus declara `@softize/base ^2.0.0` em `dependencies`, pois usa
+suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
+a release não baixa uma política ad hoc. Como o
+Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
+um `tsc` vermelho, inventário desatualizado ou violação da política vaza pro cliente. Emergência (evite):
+`pnpm release --skip-checks`.
 
 **Smoke do esqueleto**: depois do bump e antes do publish, o `release.sh` gera um app com
 `opus create`, instala o **tarball exato** que vai ser publicado e roda os gates dele
-(typecheck · test · `opus check` · manifest · build). É o que pega o que typecheck+test não
+(typecheck · test · `opus check` · `opus copy --check` · `base copy check` · manifest ·
+build). O template exige `@softize/base ^2.0.0`; publique a Base compatível antes do Opus.
+O `minimumReleaseAgeExclude` do template inclui os dois pacotes, e o smoke executa os
+fragmentos de pre-push para provar que o layout pnpm instalado resolve ambos os CLIs.
+É o que pega o que typecheck+test não
 alcançam — `files` mal recortado, export que só resolve por caminho relativo, template
 pinado numa versão que ainda não existe no registry. Ele vivia só no `release.yml`; como as
 últimas releases saíram pela estação (sem tag), passou tempo sem rodar, e foi assim que o
 template chegou a quebrar o `tsc` de um app recém-criado. `--skip-checks` pula junto.
 
 O script bumpa, publica **e leva o bump pra `origin/main`** — não sobra passo manual. Em
-`--local` ele não commita nada (Verdaccio é sandbox), e com `pnpm release none` não há bump
-pra commitar.
+`--local` ele não commita nada (Verdaccio é sandbox). `pnpm release none` não cria diff de
+versão, mas ainda commita qualquer derivado que a materialização legitimamente atualizar.
+`--dry-run` encerra depois das mesmas materializações/gates/smoke, sem publish, commit ou
+push; use `none` para validar a versão atual sem sujar o manifesto.
 
 ## Verificar
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "11.1.1",
+  "version": "12.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,9 @@
     "./check": {
       "default": "./bin/lib/check.mjs"
     },
+    "./copy": {
+      "default": "./bin/lib/copy.mjs"
+    },
     "./introspect": {
       "default": "./bin/lib/introspect.mjs"
     },
@@ -198,6 +201,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@softize/base": "^2.0.0",
     "@radix-ui/react-checkbox": "^1.1.3",
     "@radix-ui/react-dialog": "^1.1.4",
     "@radix-ui/react-dropdown-menu": "^2.1.4",
@@ -345,6 +349,7 @@
   "homepage": "https://opus.softize.com.br",
   "scripts": {
     "postinstall": "node ./bin/lib/postinstall.mjs",
+    "copy:check": "node ./bin/cli.mjs copy --check",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",

package/registry/git/pre-push.d/00-opus-copy

@@ -0,0 +1,14 @@
+#!/bin/sh
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo "opus copy pre-push: não foi possível localizar a raiz Git." >&2
+  exit 1
+}
+runner="$repo_root/.githooks/run-opus-pre-push.mjs"
+if [ ! -f "$runner" ]; then
+  echo "opus copy pre-push: runner gerenciado ausente; rode opus setup." >&2
+  exit 1
+fi
+
+# O prefixo 00 põe a verificação de freshness antes do fragmento `base`, que
+# valida o conteúdo. --check é somente leitura: o push nunca suja o worktree.
+node "$runner" "$repo_root" copy

package/registry/git/pre-push.d/opus

@@ -1,23 +1,9 @@
 #!/bin/sh
-if [ -f node_modules/@softize/opus/bin/cli.mjs ]; then
-  opus_cli=node_modules/@softize/opus/bin/cli.mjs
-elif [ -f packages/opus/bin/cli.mjs ]; then
-  opus_cli=packages/opus/bin/cli.mjs
-else
-  echo "opus pre-push: @softize/opus não está instalado." >&2
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo "opus pre-push: não foi possível localizar a raiz Git." >&2
   exit 1
-fi
-
-node "$opus_cli" pre-push materialization || exit $?
-
-# No repositório-fonte do próprio Opus, os exemplos deliberadamente inválidos dos testes
-# exercitam o linter. A suíte é o gate dessa árvore; não escaneie fixtures como consumidor.
-[ -f packages/opus/bin/cli.mjs ] && exit 0
-
-# A raiz de um monorepo não precisa ser um app. Cada marcador per-app define um alvo
-# real do check; node_modules e .git nunca participam da descoberta.
-find . -name opus.json -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.maestro/*' -exec dirname {} \; |
-  sort -u |
-  while IFS= read -r app_dir; do
-    node "$opus_cli" check "$app_dir" || exit $?
-  done
+}
+runner="$repo_root/.githooks/run-opus-pre-push.mjs"
+[ -f "$runner" ] || { echo "opus pre-push: runner gerenciado ausente; rode opus setup." >&2; exit 1; }
+node "$runner" "$repo_root" materialization || exit $?
+node "$runner" "$repo_root" apps

package/registry/git/run-opus-pre-push.mjs

@@ -0,0 +1,141 @@
+import { spawnSync } from 'node:child_process'
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { isAbsolute, join, posix, relative, resolve, sep, win32 } from 'node:path'
+
+const PACKAGE_NAME = '@softize/opus'
+const SKIP = new Set(['node_modules', '.git', '.maestro', 'dist', 'build', 'coverage', '.next'])
+
+function fail(message) { throw new Error(message) }
+function inside(root, candidate) {
+  const local = relative(root, candidate)
+  return local !== '..' && !local.startsWith(`..${sep}`) && !isAbsolute(local)
+}
+function identity(stat) { return `${stat.dev}:${stat.ino}:${stat.mode}:${stat.size}:${stat.ctimeNs}` }
+function canonicalRelativeDirectory(value) {
+  if (typeof value !== 'string' || value === '' || value.trim() !== value) return false
+  if (value !== value.normalize('NFC') || value.includes('\\') || /[\u0000-\u001f\u007f]/u.test(value)) return false
+  if (value === '.') return true
+  if (posix.isAbsolute(value) || win32.isAbsolute(value) || /^[A-Za-z]:/u.test(value)) return false
+  if (value === '..' || posix.normalize(value) !== value) return false
+  return value.split('/').every((part) => part !== '' && part !== '.' && part !== '..')
+}
+function stableDirectory(root, value) {
+  let cursor = root
+  for (const component of value === '.' ? [] : value.split('/')) {
+    cursor = join(cursor, component)
+    const before = lstatSync(cursor, { bigint: true })
+    if (before.isSymbolicLink() || !before.isDirectory()) fail('resolveFrom deve apontar para diretório regular interno.')
+    const canonical = realpathSync(cursor)
+    const after = lstatSync(cursor, { bigint: true })
+    if (identity(before) !== identity(after)) fail('resolveFrom mudou durante a resolução do hook.')
+    if (!inside(root, canonical)) fail('resolveFrom sai da raiz do projeto.')
+  }
+  return cursor
+}
+function stableConfig(root) {
+  const path = join(root, 'base.json')
+  let descriptor
+  try {
+    const before = lstatSync(path, { bigint: true })
+    if (before.isSymbolicLink() || !before.isFile() || before.nlink > 1n) fail('base.json deve ser arquivo regular sem links.')
+    let flags = constants.O_RDONLY
+    if (constants.O_NOFOLLOW !== undefined) flags |= constants.O_NOFOLLOW
+    descriptor = openSync(path, flags)
+    const opened = fstatSync(descriptor, { bigint: true })
+    if (opened.dev !== before.dev || opened.ino !== before.ino || identity(opened) !== identity(before)) fail('base.json mudou durante a resolução do hook.')
+    const content = readFileSync(descriptor, 'utf8')
+    const after = lstatSync(path, { bigint: true })
+    if (after.isSymbolicLink() || identity(after) !== identity(opened)) fail('base.json mudou durante a resolução do hook.')
+    try { return JSON.parse(content) } catch { fail('base.json não é JSON válido.') }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('base.json')) throw error
+    fail('base.json ausente ou inacessível.')
+  } finally {
+    if (descriptor !== undefined) try { closeSync(descriptor) } catch { /* já falhou */ }
+  }
+}
+function directRuntime(root, directory, expectedVersion) {
+  try {
+    const packagePath = join(directory, 'package.json')
+    const cliPath = join(directory, 'bin/cli.mjs')
+    const packageStat = lstatSync(packagePath, { bigint: true })
+    const cliStat = lstatSync(cliPath, { bigint: true })
+    if (packageStat.isSymbolicLink() || !packageStat.isFile() || packageStat.nlink > 1n) return null
+    if (cliStat.isSymbolicLink() || !cliStat.isFile() || cliStat.nlink > 1n) return null
+    const metadata = JSON.parse(readFileSync(packagePath, 'utf8'))
+    const cli = realpathSync(cliPath)
+    return metadata.name === PACKAGE_NAME && metadata.version === expectedVersion && inside(root, cli) ? cli : null
+  } catch { return null }
+}
+function packageRuntime(root, packageConfig) {
+  const resolutionBase = stableDirectory(root, packageConfig.resolveFrom)
+  const direct = directRuntime(root, resolutionBase, packageConfig.version)
+  if (direct !== null) return direct
+  const requireFrom = createRequire(join(resolutionBase, 'package.json'))
+  let packageJson
+  try { packageJson = realpathSync(requireFrom.resolve(`${PACKAGE_NAME}/package.json`)) }
+  catch { fail(`${PACKAGE_NAME} não foi resolvido a partir de ${packageConfig.resolveFrom}.`) }
+  if (!inside(root, packageJson)) fail(`${PACKAGE_NAME} resolveu fora da raiz do projeto.`)
+  const installed = JSON.parse(readFileSync(packageJson, 'utf8'))
+  if (installed.name !== PACKAGE_NAME || installed.version !== packageConfig.version) {
+    fail(`${PACKAGE_NAME} resolvido não corresponde à versão ${packageConfig.version} aplicada.`)
+  }
+  const cli = realpathSync(resolve(packageJson, '../bin/cli.mjs'))
+  if (!inside(root, cli) || !statSync(cli).isFile()) fail(`CLI de ${PACKAGE_NAME} é inválida ou externa ao projeto.`)
+  return cli
+}
+function run(cli, root, args, capture = false) {
+  const result = spawnSync(process.execPath, [cli, ...args], {
+    cwd: root,
+    encoding: capture ? 'utf8' : undefined,
+    stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+  })
+  if (result.error !== undefined) fail(`não foi possível executar ${PACKAGE_NAME}: ${result.error.message}`)
+  if (result.status === null) fail(`execução de ${PACKAGE_NAME} foi interrompida.`)
+  return result
+}
+function apps(root, dir = root, depth = 0) {
+  if (depth > 8) return []
+  const found = statSync(dir).isDirectory() && (() => { try { return statSync(join(dir, 'opus.json')).isFile() } catch { return false } })() ? [dir] : []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name.startsWith('.') || SKIP.has(entry.name)) continue
+    found.push(...apps(root, join(dir, entry.name), depth + 1))
+  }
+  return found
+}
+function main() {
+  try {
+    const requestedRoot = process.argv[2]
+    const mode = process.argv[3]
+    if (requestedRoot === undefined) fail('raiz do projeto não informada pelo hook.')
+    const root = realpathSync(resolve(requestedRoot))
+    if (!statSync(root).isDirectory()) fail('raiz do projeto não é um diretório.')
+    const config = stableConfig(root)
+    const packageConfig = config?.packages?.[PACKAGE_NAME]
+    if (packageConfig === null || typeof packageConfig !== 'object') fail(`configuração de ${PACKAGE_NAME} ausente em base.json.`)
+    if (typeof packageConfig.version !== 'string' || packageConfig.version === '') fail(`version de ${PACKAGE_NAME} ausente em base.json.`)
+    if (!canonicalRelativeDirectory(packageConfig.resolveFrom)) fail(`resolveFrom de ${PACKAGE_NAME} deve ser diretório relativo canônico.`)
+    const cli = packageRuntime(root, packageConfig)
+    if (mode === 'copy') process.exitCode = run(cli, root, ['copy', root, '--check']).status
+    else if (mode === 'materialization') process.exitCode = run(cli, root, ['pre-push', 'materialization']).status
+    else if (mode === 'check') {
+      const app = realpathSync(resolve(process.argv[4] ?? ''))
+      if (!inside(root, app) || !statSync(app).isDirectory()) fail('app do check é inválido ou externo ao projeto.')
+      const result = run(cli, app, ['check'], true)
+      process.stdout.write(result.stdout ?? '')
+      process.stderr.write(result.stderr ?? '')
+      process.exitCode = result.status
+    } else if (mode === 'apps') {
+      if (directRuntime(root, stableDirectory(root, packageConfig.resolveFrom), packageConfig.version) !== null) return
+      for (const app of [...new Set(apps(root))].sort()) {
+        const result = run(cli, app, ['check'])
+        if (result.status !== 0) { process.exitCode = result.status; return }
+      }
+    } else fail('operação do hook inválida.')
+  } catch (error) {
+    console.error(`opus pre-push: ${error instanceof Error ? error.message : 'falha ao resolver a CLI.'}`)
+    process.exitCode = 1
+  }
+}
+main()

package/registry/hooks/opus-check-on-stop.mjs

@@ -1,5 +1,5 @@
 /**
- * Hook Stop da base Opus: quando o turno termina, roda o `opus check` dos apps que a
+ * Hook Stop da camada Opus: quando o turno termina, roda o `opus check` dos apps que a
  * sessão MEXEU (arquivos alterados no git) e BLOQUEIA o fim do turno se houver violação
  * — exit 2 devolve os findings ao agente, que se corrige na hora. O gate da casa deixa
  * de depender de alguém lembrar de rodar.
@@ -11,7 +11,7 @@
  */
 import { execFileSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { join } from 'node:path'
 
 let event = {}
 try {
@@ -58,44 +58,26 @@ function findApps(dir, depth) {
 
 // Só os apps que a sessão tocou (app mais específico primeiro, pra um app aninhado
 // não cair no ancestral).
-const apps = findApps(root, 3).sort((a, b) => b.length - a.length)
+const apps = findApps(root, 8).sort((a, b) => b.length - a.length)
 const touched = new Set()
 for (const rel of changed) {
-  const app = apps.find((a) => a === root || join(root, rel).startsWith(`${a}/`))
+  const changedPath = join(root, rel.replace(/\/$/u, ''))
+  const app = apps.find((a) =>
+    a === root || changedPath === a || changedPath.startsWith(`${a}/`) || a.startsWith(`${changedPath}/`),
+  )
   if (app !== undefined) touched.add(app)
 }
 
-/**
- * Bin do opus pro app: sobe do app até a raiz (repo simples / hoisted) e, se não achar,
- * desce UM nível (app composto — pacotes api/web dentro do app, o pnpm instala o bin
- * no node_modules de cada pacote). Sem bin → fail-open (o app fica de fora).
- */
-function opusBinFor(appDir) {
-  let dir = appDir
-  for (;;) {
-    const bin = join(dir, 'node_modules', '.bin', 'opus')
-    if (existsSync(bin)) return bin
-    if (dir === root || dirname(dir) === dir) break
-    dir = dirname(dir)
-  }
-  try {
-    for (const e of readdirSync(appDir, { withFileTypes: true })) {
-      if (!e.isDirectory() || e.name.startsWith('.') || SKIP.has(e.name)) continue
-      const bin = join(appDir, e.name, 'node_modules', '.bin', 'opus')
-      if (existsSync(bin)) return bin
-    }
-  } catch {
-    /* Ilegível → sem bin. */
-  }
-  return null
-}
+// O mesmo runner versionado do pre-push resolve o pacote estritamente a partir do
+// workspace registrado em base.json. Assim um app composto não cai em bin hoisted,
+// global ou homônimo de outro workspace.
+const runner = join(root, '.githooks', 'run-opus-pre-push.mjs')
+if (!existsSync(runner)) process.exit(0)
 
 const failures = []
 for (const app of touched) {
-  const bin = opusBinFor(app)
-  if (bin === null) continue
   try {
-    execFileSync(bin, ['check'], { cwd: app, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 45_000 })
+    execFileSync(process.execPath, [runner, root, 'check', app], { cwd: app, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 45_000 })
   } catch (err) {
     // Sem cor: o destinatário é o agente, não um terminal.
     const out = `${err.stdout ?? ''}${err.stderr ?? ''}`.replace(/\x1b\[[0-9;]*m/g, '')

package/registry/instructions/opus.md

@@ -1,5 +1,8 @@
 # Opus
 
+<!-- softize-skill-route: $implement-opus-change -->
+<!-- softize-skill-route: $upgrade-opus -->
+
 Este repo usa `@softize/opus`, um SDK e protocolo de actions. A versão aplicada aos
 artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `opus.json`.
 
@@ -10,11 +13,14 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
 - Manter contrato compartilhável separado de banco, segredo e driver server-only; usar
   `defineContract` com `bindAction` quando cliente e servidor consomem a mesma action.
 - Não duplicar schemas, tipos de transporte, validação ou fetch que o contrato já fornece.
-- Rodar `opus check` e os gates do projeto depois de alterar actions, bindings ou versão do SDK.
+- Regenerar o inventário com `opus copy` quando mudar copy em contrato ou componente Opus
+  mapeado; o Opus classifica os papéis semânticos e a política universal de `@softize/base`
+  valida o conteúdo.
+- Rodar `opus check`, `opus copy --check` e os gates do projeto depois de alterar actions,
+  bindings ou versão do SDK.
 - Quando a default branch tiver adotado uma versão diferente da worktree, reconciliar a
-  branch antes de commit/review e usar `upgrade-opus` para ler changelog e aplicar migrações.
+  branch antes de commit/review e carregar `$upgrade-opus` para ler changelog e aplicar migrações.
+- Ao implementar mudança que atravesse domínio, action, runtime ou integração Opus, carregar
+  `$implement-opus-change`; seguir as rotas especializadas que ela indicar.
 - Consultar as skills Opus materializadas conforme o workflow; não atribuir ao SDK decisões
   universais de domínio ou arquitetura.
-- Usar `write-product-communication` ao criar ou alterar documentação, textos de interface,
-  mensagens de erro, CLI, onboarding ou explicações. Partir da situação do leitor, apresentar
-  contexto antes da regra e evitar slogans, absolutos e linguagem de manifesto.

package/registry/skills/build-opus-ui/SKILL.md

@@ -26,13 +26,14 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 7. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
    `rounded-sm` a `rounded-xl` já expressam a forma.
 8. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
-9. Usar `write-product-communication` para labels, ajuda, estados vazios, confirmações e erros;
-   revisar o fluxo completo, não apenas cada string isolada.
 
 ## Verificação
 
-Rodar `opus check`, testes focados, typecheck e build da superfície. Inspecionar visualmente
-a rota real e validar navegação por URL quando aplicável.
+Rodar `opus check`, testes focados, typecheck e build da superfície. Se a interface alterou
+copy em contrato ou componente Opus mapeado, regenerar com `opus copy` e executar
+`base copy check`. Copy dinâmica numa superfície mapeada precisa de fallback estático ou de
+uma decisão explícita de arquitetura; não contorne o diagnóstico com `aria-label` paralelo.
+Inspecionar visualmente a rota real e validar navegação por URL quando aplicável.
 
 ## Limites