@softize/opus 8.9.1 → 9.0.1

package/CHANGELOG.md

@@ -11,6 +11,53 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 > tinha ficado sem registro nenhum, o que é exatamente o caso que este arquivo existe
 > pra cobrir.
 
+## 9.0.1 — 2026-08-12
+
+**A garantia de materialização volta a ser local.** `opus setup` deixa de criar o
+workflow `.github/workflows/opus.yml`; o hook composto de pre-push e `opus check`
+continuam sendo os gates reproduzíveis do pacote. Ao atualizar, o setup remove o workflow
+anterior quando ele ainda está íntegro e gerenciado pelo Opus, preservando qualquer edição
+local para revisão explícita.
+
+## 9.0.0 — 2026-08-12
+
+**Chrome denso passa a compartilhar a mesma régua visual.** Três primitives deixam de
+depender de coincidências do call site:
+
+- `TabsList` volta a aceitar uma altura fornecida por `className`; no variant `line`, o
+  indicador ancora na borda da própria lista, inclusive quando ela preenche uma faixa mais
+  alta que o size padrão.
+- `Select variant="ghost"` abraça ícone, rótulo e chevron como um botão de toolbar. O
+  rótulo ainda pode encolher e truncar, mas não cresce para empurrar o chevron à borda;
+  agora ele também respeita a régua `default` (36px) / `sm` (32px).
+- `Button`, `Select`, `Toggle`, `ToggleGroup`, `InputGroup` e `ButtonGroup` aceitam
+  `shape="pill"`. Forma fica separada de intenção (`variant`) e altura (`size`), e grupos
+  preservam o raio somente nas extremidades externas — inclusive quando contêm `Select`.
+- o botão de envio do `Composer` usa a geometria pill do próprio `Button`.
+- `Select variant="outline"` oferece a borda de um controle sem o `min-width` de campo:
+  ícone, rótulo e chevron ficam juntos em uma única linha em toolbars e composers; rótulos
+  longos truncam em vez de empurrar o chevron para uma segunda linha.
+- superfícies elevadas voltam a usar `border border-border`; `ring-edge` e seu token são
+  removidos, deixando `ring-*` para foco e estados transitórios.
+- a elevação volta ao vocabulário de intensidade do Tailwind (`shadow-sm`, `shadow-md`,
+  `shadow-lg` etc.), com a composição clara e difusa controlada pelo tema do Opus.
+  `Card`/`Composer`, menus/popovers e modais usam respectivamente `sm`, `md` e `lg` como
+  defaults; os aliases por papel e as variáveis intermediárias `--elevation-*` saem.
+- `shadow-lg` ganha spread negativo e menos opacidade: mantém alcance, mas deixa de
+  engrossar visualmente a borda no ponto de contato com a superfície.
+- toda a escala passa a declarar a receita diretamente em `--shadow-*`, preservando a
+  API nativa de modifiers do Tailwind, como `shadow-xl/30`.
+
+**Migração:** os tokens públicos de elevação por papel foram removidos porque forma e
+intensidade agora são ortogonais. Troque `shadow-card/popover/dialog` por
+`shadow-sm/md/lg`; troque `ring-1 ring-edge` por `border border-border` e `border-edge`
+por `border-border`. Overrides de `--elevation-*` devem migrar para o `--shadow-*`
+correspondente. `opus check` acusa esses usos, que de outra forma perderiam o efeito
+visual sem erro de compilação.
+
+Também remova overrides locais de altura, posição do indicador e largura mínima que
+existiam apenas para compensar os defeitos corrigidos nesta versão.
+
 ## 8.9.1 — 2026-08-04
 
 **A migração deixa de esconder o hook Opus no Git.** `opus setup` agora remove também a

package/bin/cli.mjs

@@ -176,7 +176,7 @@ async function cmdCheck(dir) {
   }
   const { files, actions, contracts, findings, hasMarker } = await scanDir(root)
 
-  if (actions === 0) {
+  if (actions === 0 && findings.length === 0) {
     const verdict = emptyScanVerdict({ hasMarker, contracts })
     // Projeto MARCADO (opus.json) sem actions passa vacuamente — server/lib/app sem
     // domínio ainda. Sem marcador, "0 actions" segue sintoma (diretório errado ou
@@ -205,7 +205,7 @@ async function cmdCheck(dir) {
       console.log(`  ${String(f.line).padStart(4)}:  [${f.rule}] ${f.action} — ${f.message}`)
     }
   }
-  log('error', `\n✗ opus check: ${findings.length} violação(ões) em ${byFile.size}/${actions} action(s).`)
+  log('error', `\n✗ opus check: ${findings.length} violação(ões) em ${byFile.size} arquivo(s).`)
   process.exit(1)
 }
 
@@ -454,7 +454,7 @@ 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, pre-push e CI comitados
+  agentes          skills Claude/Codex, hook, instruções e pre-push comitados
 
 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

package/bin/lib/check.mjs

@@ -44,6 +44,22 @@ const SEG = '[a-z][a-z0-9]*(-[a-z0-9]+)*'
 const ACTION_NAME_RE = new RegExp(`^${SEG}(\\.${SEG})+$`)
 const KINDS = new Set(['simple', 'form', 'list', 'view'])
 
+// Tokens públicos removidos cuja ausência no CSS não quebra typecheck/build: sem uma
+// migração executável, o consumidor perde borda/sombra em silêncio. O check fica no Opus
+// (dono do contrato visual), não no Maestro. Uma ocorrência por token/arquivo basta.
+const REMOVED_UI_TOKENS = new Map([
+  ['ring-edge', 'use `border border-border` para a aresta da superfície'],
+  ['border-edge', 'use `border-border`'],
+  ['shadow-card', 'use `shadow-sm`'],
+  ['shadow-popover', 'use `shadow-md`'],
+  ['shadow-dialog', 'use `shadow-lg`'],
+  ['--edge-value', 'remova o override; a aresta agora usa `--border`'],
+  ['--color-edge', 'remova o token; a aresta agora usa `--border`'],
+  ['--elevation-card', 'use/ajuste `--shadow-sm`'],
+  ['--elevation-popover', 'use/ajuste `--shadow-md`'],
+  ['--elevation-dialog', 'use/ajuste `--shadow-lg`'],
+])
+
 /** Os três nomes que denotam action/contrato — o arquivo sem nenhum deles é pulado. */
 export const ACTION_MARKERS = ['defineAction', 'defineContract', 'bindAction']
 
@@ -239,7 +255,193 @@ export function checkProject(sources) {
   return { actions, contracts, findings }
 }
 
+/** Migrações de UI que falhariam apenas visualmente. Linhas que são só comentário não
+ * contam; documentação vive fora do sourceRoot e também não entra no walk. */
+function stripComments(text) {
+  let output = ''
+  let state = 'code'
+  let escaped = false
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index]
+    const next = text[index + 1]
+    if (state === 'line-comment') {
+      if (char === '\n') { state = 'code'; output += char } else output += ' '
+      continue
+    }
+    if (state === 'block-comment') {
+      if (char === '*' && next === '/') { output += '  '; index += 1; state = 'code' }
+      else output += char === '\n' ? '\n' : ' '
+      continue
+    }
+    if (state === 'html-comment') {
+      if (char === '-' && text.slice(index, index + 3) === '-->') {
+        output += '   '; index += 2; state = 'code'
+      } else output += char === '\n' ? '\n' : ' '
+      continue
+    }
+    if (state === 'code' && text.slice(index, index + 4) === '<!--') {
+      output += '    '; index += 3; state = 'html-comment'; continue
+    }
+    if (state === 'code' && char === '/' && next === '/') {
+      output += '  '; index += 1; state = 'line-comment'; continue
+    }
+    if (state === 'code' && char === '/' && next === '*') {
+      output += '  '; index += 1; state = 'block-comment'; continue
+    }
+    if (state === 'code' && (char === "'" || char === '"' || char === '`')) {
+      state = char; output += char; escaped = false; continue
+    }
+    if (state !== 'code') {
+      output += char
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === state) state = 'code'
+      continue
+    }
+    output += char
+  }
+  return output
+}
+
+function quotedValues(text) {
+  const values = []
+  let line = 1
+  const startsRegex = (index) => {
+    const before = text.slice(0, index).trimEnd()
+    if (before === '') return true
+    const previous = before.at(-1)
+    return /[=(:,![{;?&|+*%^~<>-]/.test(previous) ||
+      /\b(?:return|case|throw|typeof|instanceof|in|of|yield|await)\s*$/.test(before)
+  }
+  for (let index = 0; index < text.length; index += 1) {
+    const quote = text[index]
+    if (quote === '\n') { line += 1; continue }
+    if (quote === '/' && startsRegex(index)) {
+      let escaped = false
+      let inCharacterClass = false
+      for (index += 1; index < text.length; index += 1) {
+        const char = text[index]
+        if (char === '\n') line += 1
+        if (escaped) { escaped = false; continue }
+        if (char === '\\') { escaped = true; continue }
+        if (char === '[') { inCharacterClass = true; continue }
+        if (char === ']') { inCharacterClass = false; continue }
+        if (char === '/' && !inCharacterClass) break
+      }
+      while (/[a-z]/i.test(text[index + 1] ?? '')) index += 1
+      continue
+    }
+    if (quote !== "'" && quote !== '"' && quote !== '`') continue
+    let value = ''
+    let escaped = false
+    const startLine = line
+    const startIndex = index
+    for (index += 1; index < text.length; index += 1) {
+      const char = text[index]
+      if (char === '\n') line += 1
+      if (escaped) { value += char; escaped = false; continue }
+      if (char === '\\') { value += char; escaped = true; continue }
+      if (char === quote) break
+      value += char
+    }
+    values.push({ value, startLine, startIndex, endIndex: index })
+  }
+  return values
+}
+
+const SIMPLE_TAILWIND_CLASSES = new Set(['flex', 'grid', 'block', 'inline', 'hidden', 'border', 'shadow', 'ring'])
+
+function looksLikeUtilityValue(value, token, matchesToken) {
+  if (!matchesToken(value, token)) return false
+  const parts = value.trim().split(/\s+/).filter(Boolean)
+  return parts.length > 1 && parts.every((part) =>
+    matchesToken(part, token) || SIMPLE_TAILWIND_CLASSES.has(part) || /[-:[\]/!@.%]/.test(part),
+  )
+}
+
+function isInsideUtilityHelper(beforeValue) {
+  const matches = [...beforeValue.matchAll(/\b(?:cn|cva|clsx|twMerge)\s*\(/g)]
+  for (const match of matches.reverse()) {
+    const call = beforeValue.slice(match.index)
+    let depth = 0
+    let quote = null
+    let escaped = false
+    for (const char of call) {
+      if (quote !== null) {
+        if (escaped) escaped = false
+        else if (char === '\\') escaped = true
+        else if (char === quote) quote = null
+        continue
+      }
+      if (char === "'" || char === '"' || char === '`') { quote = char; continue }
+      if (char === '(') depth += 1
+      else if (char === ')') depth -= 1
+    }
+    if (depth > 0) return true
+  }
+  return false
+}
+
+export function checkUiMigrations(file, text) {
+  const findings = []
+  const seen = new Set()
+  const matchesToken = (line, token) => {
+    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    return new RegExp(`(^|[^A-Za-z0-9_-])${escaped}(?=$|[^A-Za-z0-9_-])`).test(line)
+  }
+  const extension = path.extname(file)
+  const source = stripComments(text)
+  const addFinding = (token, replacement, line) => {
+    seen.add(token)
+    findings.push({
+      rule: 'removed-ui-token',
+      level: 'error',
+      action: token,
+      line,
+      file,
+      message: `token removido na 9.0.0 — ${replacement}.`,
+    })
+  }
+  for (const [index, raw] of source.split(/\r?\n/).entries()) {
+    const line = raw.trim()
+    if (line === '') continue
+    for (const [token, replacement] of REMOVED_UI_TOKENS) {
+      if (seen.has(token)) continue
+      const inStylesheet = extension === '.css' && matchesToken(line, token)
+      const inSvelteDirective = extension === '.svelte' && new RegExp(`\\bclass:${token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[=\\s]|$)`).test(line)
+      if (inStylesheet || inSvelteDirective) addFinding(token, replacement, index + 1)
+    }
+  }
+  for (const { value, startLine, startIndex, endIndex } of quotedValues(source)) {
+    const beforeValue = source.slice(Math.max(0, startIndex - 500), startIndex)
+    const classAttribute = /\bclass(?:Name)?\s*=\s*\{?\s*$/.test(beforeValue)
+    const classExpression = /\bclass(?:Name)?\s*=\s*\{[^{}]*$/.test(beforeValue)
+    const utilityHelper = isInsideUtilityHelper(beforeValue)
+    const propertyKey = /^\s*:/.test(source.slice(endIndex + 1, endIndex + 12))
+    const classBinding = /\b(?:class(?:Name|Names)?|classes|\w+(?:Class|Classes))\s*=\s*[^;\n]*$/.test(beforeValue)
+    const objectProperty = /\b(?!aria(?:Label|Description)\b|label\b|title\b|description\b|text\b|message\b|note\b|content\b)[A-Za-z_$][\w$-]*\s*:\s*$/.test(beforeValue)
+    const classListCall = /\bclassList\.(?:add|remove|toggle|replace|contains)\s*\([^)]*$/.test(beforeValue)
+    const stylePropertyCall = /\b(?:style\.)?setProperty\s*\([^)]*$/.test(beforeValue)
+    for (const [token, replacement] of REMOVED_UI_TOKENS) {
+      const usedAsUtility = matchesToken(value, token) && (
+        classAttribute || classExpression || utilityHelper || classBinding || objectProperty ||
+        (classListCall && !token.startsWith('--')) ||
+        (stylePropertyCall && token.startsWith('--')) ||
+        (propertyKey && token.startsWith('--')) ||
+        looksLikeUtilityValue(value, token, matchesToken)
+      )
+      if (seen.has(token) || !usedAsUtility) continue
+      const tokenIndex = value.indexOf(token)
+      const tokenLine = startLine + value.slice(0, tokenIndex).split('\n').length - 1
+      addFinding(token, replacement, tokenLine)
+    }
+  }
+  return findings.sort((left, right) => left.line - right.line)
+}
+
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.next', 'coverage'])
+const UI_SKIP_DIRS = new Set([...SKIP_DIRS, '__tests__', '__fixtures__', 'fixtures', 'test', 'tests'])
+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
@@ -264,6 +466,25 @@ export async function walkTsFiles(dir, acc = []) {
   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)
+    }
+  }
+  return acc
+}
+
 async function exists(p) {
   try {
     await fs.access(p)
@@ -283,9 +504,22 @@ export async function scanDir(rootDir) {
     if (!ACTION_MARKERS.some((m) => text.includes(m))) continue
     sources.push({ file: path.relative(rootDir, file), text })
   }
-  const { actions, contracts, findings } = checkProject(sources)
+  const checked = checkProject(sources)
+  const uiFindings = []
+  // 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')
+    uiFindings.push(...checkUiMigrations(path.relative(rootDir, file), text))
+  }
   const hasMarker = await exists(path.join(rootDir, 'opus.json'))
-  return { files: files.length, actions, contracts, findings, hasMarker }
+  return {
+    files: files.length,
+    actions: checked.actions,
+    contracts: checked.contracts,
+    findings: [...checked.findings, ...uiFindings],
+    hasMarker,
+  }
 }
 
 /**

package/bin/lib/create.mjs

@@ -18,7 +18,7 @@
  *   • tokens `{{APP_NAME}}` e `{{OPUS_VERSION}}` são substituídos em todo arquivo.
  *
  * Depois da cópia roda o `initProject` (setup): opus.json e artefatos Opus rastreáveis,
- * `.claude/memory/` e o CI de fábrica (repo-level: acha a raiz pelo `.git`).
+ * `.claude/memory/` e os gates locais (repo-level: acha a raiz pelo `.git`).
  */
 
 import { promises as fs } from 'node:fs'
@@ -202,7 +202,7 @@ export async function createProject(registryDir, targetDir, appName) {
   const warnings = mode === 'app' ? await workspaceWarnings(wsRoot, path.resolve(targetDir)) : []
 
   // Setup por cima: opus.json per-app e materialização repo-level. Em monorepo, a raiz
-  // é descoberta pelo Git e recebe skills, hooks, instruções e CI específicos do Opus.
+  // é descoberta pelo Git e recebe skills, hooks, instruções e pre-push específicos do Opus.
   const setup = await initProject(registryDir, targetDir)
   return { version, mode, files, warnings, setup }
 }

package/bin/lib/materialize.mjs

@@ -109,7 +109,6 @@ function expectedFiles(exclude) {
   for (const [source, destination] of [
     ['registry/hooks/opus-check-on-stop.mjs', '.claude/hooks/opus-check-on-stop.mjs'],
     ['registry/git/pre-push.d/opus', '.githooks/pre-push.d/opus'],
-    ['registry/github/opus.yml', '.github/workflows/opus.yml'],
   ]) {
     const content = readFileSync(join(PACKAGE_ROOT, source), 'utf8')
     expected.set(destination, { source, content, output: addMarker(destination, source, content) })

package/bin/lib/postinstall.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * postinstall do @softize/opus — tenta rodar o setup no consumidor. É conveniência
- * best-effort; a garantia vem de `opus setup` explícito + `opus check` no CI.
+ * best-effort; a garantia vem de `opus setup` explícito + `opus check` nos gates locais.
  *
  * Blindagem (best-effort, NUNCA falha o install):
  *   • OPUS_SKIP_INIT=1            → pula

package/docs/consumer-upgrade-propagation.md

@@ -0,0 +1,56 @@
+# Adoção de upgrades pelos consumidores
+
+## Contexto
+
+Publicar uma versão do `@softize/opus` não significa que um projeto decidiu adotá-la.
+Da mesma forma, uma worktree pode continuar coerente com seu próprio lockfile mesmo depois
+que a branch principal do projeto adotou uma versão mais nova. Nesse intervalo, `opus check`
+consegue provar a consistência local, mas não consegue concluir sozinho qual versão o projeto
+pretende usar.
+
+Há três sinais diferentes e eles não devem ser confundidos:
+
+1. **disponível:** versão publicada no registry;
+2. **adotada:** versão comitada na branch principal do consumidor;
+3. **aplicada:** versão presente na worktree e nos artefatos materializados.
+
+## Decisão
+
+- A release do Opus publica a versão e seu changelog; não altera nem dispara automações nos
+  repositórios consumidores.
+- 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.
+- 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.
+- `opus check` mantém detectores de migração para APIs removidas cujo uso possa falhar em
+  silêncio. Erros de compilação continuam pertencendo ao typecheck.
+
+## Consequências
+
+- 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
+  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.
+
+## Alternativas descartadas
+
+- **Fazer `opus check` consultar `latest`:** não é determinístico e bloquearia projetos que
+  ainda não decidiram adotar a versão publicada.
+- **Atualizar todas as worktrees na publicação:** atravessa mudanças pendentes e pode criar
+  conflitos fora da sessão que iniciou a release.
+- **Disparar GitHub Actions nos consumidores:** acopla a publicação à infraestrutura do
+  GitHub e concede ao release autoridade para criar branches e PRs em outros projetos.
+- **Deixar apenas Dependabot/Renovate:** atualizar o semver não materializa `base.json`,
+  `opus.json`, skills, hooks e instruções que fazem parte do upgrade do Opus.
+
+## Verificação
+
+- o status do Maestro deve distinguir versão instalada, aplicada e adotada;
+- fixtures com tokens removidos devem reprovar no detector de migração, enquanto texto de
+  documentação e dependências geradas são ignorados.

package/docs/elevation-scale.md

@@ -0,0 +1,55 @@
+# Escala de elevação
+
+> **Status: decidido (ago/2026).** A intensidade da sombra usa a escala do Tailwind;
+> o papel do componente não faz parte do nome do token.
+
+## Contexto
+
+A composição original de `shadow-*` do Tailwind era escura demais para a interface do
+Opus. A primeira correção preservou os nomes da escala e clareou seus valores. Depois ela
+foi substituída por tokens de papel (`shadow-card`, `shadow-popover`, `shadow-dialog`).
+
+Os tokens de papel acoplaram intensidade e tipo de componente. Na composição de páginas,
+uma superfície que precisava apenas de mais presença acabava recebendo um nome incorreto
+— por exemplo, um card usando `shadow-popover`. O nome deixava de explicar o efeito.
+
+## Decisão
+
+- `shadow-2xs` até `shadow-2xl` continuam significando intensidade crescente, como no
+  Tailwind.
+- O Opus declara a composição diretamente em `--shadow-*`, mantendo a progressão do
+  Tailwind com camadas mais claras, difusas e spread negativo. Sem variável intermediária,
+  modifiers nativos como `shadow-xl/30` continuam funcionando.
+- Componentes escolhem a intensidade pelo contexto: `sm` para repouso, `md` para
+  flutuantes e `lg` para modais ou destaques fortes. Essa associação é default, não uma
+  restrição semântica.
+- A aresta volta a ser `border border-border`; `ring-*` fica reservado para foco e outros
+  estados transitórios.
+- Os antigos `--elevation-*`, `shadow-card/popover/dialog` e `ring-edge` são removidos.
+
+## Consequências
+
+- Qualquer componente pode subir ou descer um degrau sem adotar o nome de outro papel.
+- A escala global afeta todo uso legítimo de `shadow-*`, inclusive consumidores externos;
+  isso é intencional e fica declarado no tema.
+- Forma e cor podem continuar semânticas (`rounded-card`, `bg-popover`), pois não
+  representam uma intensidade intercambiável.
+
+## Alternativas descartadas
+
+- **Manter tokens por papel:** preserva defaults rígidos, mas repete a ambiguidade que
+  motivou esta decisão.
+- **Usar a escala stock do Tailwind:** mantém o vocabulário, mas recupera sombras mais
+  escuras que a identidade do Opus.
+- **Criar outra escala (`shadow-opus-sm`):** evita sobrescrever tokens, ao custo de dois
+  vocabulários equivalentes para a mesma propriedade.
+- **Manter `ring-edge` como aresta:** não altera a geometria, mas duplica o vocabulário de
+  borda e usa outra camada de `box-shadow` para resolver um problema da receita da sombra.
+
+## Verificação
+
+- A documentação de tokens demonstra a escala, não papéis.
+- Primitivos elevados usam `border` e não dependem de `ring-edge`.
+- A compilação de `shadow-xl/30` contém o modifier de opacidade aplicado às cores.
+- Typecheck, testes de UI e build dos consumidores verificam que as classes continuam
+  materializadas pelo Tailwind.

package/docs/ownership-vs-shadcn-lock.md

@@ -21,9 +21,10 @@
 
 Sobrescrever um default do Tailwind/shadcn é legítimo quando **declarado** num dos dois
 registros — o header de DIVERGÊNCIAS do `theme.css` (valores de token) ou o delta do
-`registry.lock.json` (componentes ejetados). Nunca sobrescrever a **mecânica** (utilitário
-mantém o significado documentado; preferir namespace próprio, como a elevação
-`shadow-card/popover/dialog`). O que não está declarado é drift.
+`registry.lock.json` (componentes ejetados). Nunca sobrescrever a **mecânica**: o utilitário
+mantém o significado documentado. A escala de elevação, por exemplo, mantém `sm` → `2xl`
+como intensidade crescente e muda somente a composição visual. O que não está declarado
+é drift.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "8.9.1",
+  "version": "9.0.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/instructions/opus.md

@@ -11,5 +11,7 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
   `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.
+- 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.
 - Consultar as skills Opus materializadas conforme o workflow; não atribuir ao SDK decisões
   universais de domínio ou arquitetura.

package/src/ui/components/primitives/alert-dialog.tsx

@@ -52,7 +52,7 @@ function AlertDialogContent({
       <AlertDialogPrimitive.Content
         data-slot="alert-dialog-content"
         className={cn(
-          "group/alert-dialog-content fixed top-[50%] left-[50%] z-50 grid w-full max-w-xs translate-x-[-50%] translate-y-[-50%] gap-4 rounded-dialog ring-1 ring-edge bg-background p-6 shadow-dialog duration-200 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
+          "group/alert-dialog-content fixed top-[50%] left-[50%] z-50 grid w-full max-w-xs translate-x-[-50%] translate-y-[-50%] gap-4 rounded-dialog border border-border bg-background p-6 shadow-lg duration-200 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
           className
         )}
         {...props}

package/src/ui/components/primitives/button-group.tsx

@@ -14,9 +14,26 @@ const buttonGroupVariants = cva(
         vertical:
           "flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none",
       },
+      shape: {
+        default: '',
+        pill: 'rounded-full',
+      },
     },
+    compoundVariants: [
+      {
+        orientation: 'horizontal',
+        shape: 'pill',
+        className: '[&>*:first-child]:rounded-l-full [&>*:last-child]:rounded-r-full [&>[data-slot=select]:first-child_[data-slot=select-control]]:rounded-l-full [&>[data-slot=select]:last-child_[data-slot=select-control]]:rounded-r-full [&>[data-slot=select-wrapper]:first-child_[data-slot=select]]:rounded-l-full [&>[data-slot=select-wrapper]:last-child_[data-slot=select]]:rounded-r-full',
+      },
+      {
+        orientation: 'vertical',
+        shape: 'pill',
+        className: '[&>*:first-child]:rounded-t-full [&>*:last-child]:rounded-b-full [&>[data-slot=select]:first-child_[data-slot=select-control]]:rounded-t-full [&>[data-slot=select]:last-child_[data-slot=select-control]]:rounded-b-full [&>[data-slot=select-wrapper]:first-child_[data-slot=select]]:rounded-t-full [&>[data-slot=select-wrapper]:last-child_[data-slot=select]]:rounded-b-full',
+      },
+    ],
     defaultVariants: {
       orientation: "horizontal",
+      shape: "default",
     },
   }
 )
@@ -24,6 +41,7 @@ const buttonGroupVariants = cva(
 function ButtonGroup({
   className,
   orientation,
+  shape,
   ...props
 }: React.ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>) {
   return (
@@ -31,7 +49,14 @@ function ButtonGroup({
       role="group"
       data-slot="button-group"
       data-orientation={orientation}
-      className={cn(buttonGroupVariants({ orientation }), className)}
+      data-shape={shape}
+      className={cn(
+        buttonGroupVariants({ orientation, shape }),
+        orientation === 'vertical'
+          ? '[&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:rounded-t-none [&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:border-t-0 [&>[data-slot=select]:not(:last-child)_[data-slot=select-control]]:rounded-b-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:rounded-t-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:border-t-0 [&>[data-slot=select-wrapper]:not(:last-child)_[data-slot=select]]:rounded-b-none'
+          : '[&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:rounded-l-none [&>[data-slot=select]:not(:first-child)_[data-slot=select-control]]:border-l-0 [&>[data-slot=select]:not(:last-child)_[data-slot=select-control]]:rounded-r-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:rounded-l-none [&>[data-slot=select-wrapper]:not(:first-child)_[data-slot=select]]:border-l-0 [&>[data-slot=select-wrapper]:not(:last-child)_[data-slot=select]]:rounded-r-none',
+        className,
+      )}
       {...props}
     />
   )

package/src/ui/components/primitives/button.tsx

@@ -2,6 +2,7 @@ import * as React from 'react'
 import { Slot } from '@radix-ui/react-slot'
 import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '../../lib/cn.ts'
+import type { ControlShape } from './control.ts'
 import { Spinner } from './spinner.tsx'
 
 /**
@@ -39,8 +40,12 @@ export const buttonVariants = cva(
         // do `icon-xs` do InputGroupButton; sem ele, o exemplo virava `className="size-6"`.
         'icon-xs': 'size-6',
       },
+      shape: {
+        default: '',
+        pill: 'rounded-full',
+      },
     },
-    defaultVariants: { variant: 'default', size: 'default' },
+    defaultVariants: { variant: 'default', size: 'default', shape: 'default' },
   },
 )
 
@@ -56,12 +61,15 @@ export interface ButtonProps
   /** Ícone à esquerda do texto (o componente, ex.: `icon={Plus}`). No `busy` é TROCADO
    *  pelo Spinner — não soma (evita ícone + spinner juntos). Ignorado com asChild. */
   icon?: React.ElementType
+  /** Geometria do controle; `pill` não altera cor nem hierarquia da variante. */
+  shape?: ControlShape
 }
 
 export function Button({
   className,
   variant,
   size,
+  shape,
   asChild = false,
   busy = false,
   icon: Icon,
@@ -76,7 +84,7 @@ export function Button({
   return (
     <Comp
       data-slot="button"
-      className={cn(buttonVariants({ variant, size }), className)}
+      className={cn(buttonVariants({ variant, size, shape }), className)}
       disabled={disabled || busy}
       {...props}
     >

package/src/ui/components/primitives/card.tsx

@@ -24,7 +24,7 @@ export function Card({
 }): React.ReactElement {
   const Comp = asChild ? Slot : 'div'
   return (
-    <Comp data-slot="card" className={cn('rounded-card bg-card text-card-foreground ring-1 ring-edge shadow-card', className)} {...props} />
+    <Comp data-slot="card" className={cn('rounded-card border border-border bg-card text-card-foreground shadow-sm', className)} {...props} />
   )
 }