@softize/opus 27.1.0 → 29.0.0

package/bin/lib/materialize.mjs

@@ -27,6 +27,7 @@ const REGISTRY = join(PACKAGE_ROOT, 'registry')
 const BLOCK_SOURCE = 'registry/instructions/opus.md'
 const BLOCK_END = '<!-- softize-managed:end @softize/opus -->'
 const MANAGED_ROOTS = ['.agents/skills', '.claude/skills', '.claude/hooks', '.github/workflows', '.githooks/pre-push.d']
+const CLAUDE_IMPORT = '@AGENTS.md'
 
 const normalizedLineEndings = (content) => content.replace(/\r\n?/gu, '\n')
 const hash = (content) => createHash('sha256').update(normalizedLineEndings(content)).digest('hex')
@@ -533,6 +534,103 @@ function reconcileInstructions(root, file, mode, errors, changes) {
   }
 }
 
+// Blocos gerenciados de qualquer pacote. Um marcador de início ilegível não identifica dono e
+// conta como texto do projeto. Mesmo critério da Base (@softize/base, ADR 0006).
+function managedBlocks(content) {
+  const blocks = []
+  let cursor = 0
+  for (const match of content.matchAll(/<!-- softize-managed:start (\{[^\n]+\}) -->/g)) {
+    let meta
+    try {
+      meta = JSON.parse(match[1])
+    } catch {
+      continue
+    }
+    if (typeof meta?.package !== 'string') continue
+    const openEnd = match.index + match[0].length
+    const endMarker = `<!-- softize-managed:end ${meta.package} -->`
+    const endAt = content.indexOf(endMarker, openEnd)
+    if (match.index < cursor || endAt === -1 || content.slice(openEnd, endAt).includes('softize-managed:start')) return null
+    const end = endAt + endMarker.length
+    blocks.push({ start: match.index, end, package: meta.package, text: content.slice(match.index, end) })
+    cursor = end
+  }
+  return blocks
+}
+
+// Texto do projeto fora dos blocos gerenciados e da linha de import, normalizado para comparar o
+// CLAUDE.md legado com o AGENTS.md sem depender de fim de linha ou de linhas em branco.
+function freeInstructions(content, blocks) {
+  let rest = ''
+  let cursor = 0
+  for (const block of blocks) {
+    rest += content.slice(cursor, block.start)
+    cursor = block.end
+  }
+  rest += content.slice(cursor)
+  return normalizedLineEndings(rest)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line !== CLAUDE_IMPORT)
+    .join('\n')
+    .replace(/\n{3,}/gu, '\n\n')
+    .trim()
+}
+
+// O CLAUDE.md só importa o AGENTS.md, que concentra as instruções para qualquer agente. O Opus
+// remove dele apenas o próprio bloco; blocos de outros pacotes continuam depois do import até que
+// o pacote dono os remova, para que versões antigas e novas convivam sem reescrever o arquivo uma
+// da outra. Texto do projeto que só existe no CLAUDE.md é preservado e reprovado.
+function reconcileClaudeImport(root, mode, errors, changes) {
+  const destination = 'CLAUDE.md'
+  const pending =
+    `${destination}: deve conter a linha ${CLAUDE_IMPORT}, que importa o AGENTS.md, seguida apenas dos ` +
+    'blocos de outros pacotes, quando houver; rode opus setup.'
+  const currentFile = readMaterializedFile(root, destination, errors)
+  if (currentFile === null) return
+  const current = currentFile.exists ? currentFile.content : ''
+  const own = findBlock(current)
+  const blocks = managedBlocks(current)
+  if (own?.malformed || blocks === null) {
+    errors.push(`${destination}: bloco gerenciado malformado.`)
+    return
+  }
+  if (own !== null && (own.owner?.package !== PACKAGE_NAME || hash(own.body) !== own.owner.sha256)) {
+    errors.push(`${destination}: bloco Opus foi editado ou perdeu sua identificação de origem; preservado.`)
+    return
+  }
+
+  const free = freeInstructions(current, blocks)
+  if (free !== '') {
+    const agentsFile = readMaterializedFile(root, 'AGENTS.md', errors)
+    if (agentsFile === null) return
+    const agents = agentsFile.exists ? agentsFile.content : ''
+    if (free !== freeInstructions(agents, managedBlocks(agents) ?? [])) {
+      errors.push(
+        `${destination}: tem instruções que não estão no AGENTS.md; preservado. O CLAUDE.md passa a conter só ` +
+          `${CLAUDE_IMPORT}, então mova essas instruções para o AGENTS.md e rode opus setup.`,
+      )
+      return
+    }
+  }
+
+  const foreign = blocks.filter((block) => block.package !== PACKAGE_NAME).map((block) => normalizedLineEndings(block.text))
+  const expected = `${[CLAUDE_IMPORT, ...foreign].join('\n\n')}\n`
+  if (currentFile.exists && managedTextEquivalent(current, expected)) return
+  if (mode === 'check') errors.push(pending)
+  else if (
+    replaceMaterializedFile(
+      root,
+      destination,
+      currentFile.exists ? withProjectLineEndings(expected, current) : expected,
+      currentFile,
+      errors,
+    )
+  ) {
+    changes.push(`${currentFile.exists ? 'atualizado' : 'criado'} ${destination} como import do AGENTS.md`)
+  }
+}
+
 function isOpusHook(hook) { return typeof hook?.command === 'string' && hook.command.includes('.claude/hooks/opus-check-on-stop.mjs') }
 
 function isPlainObject(value) {
@@ -792,7 +890,7 @@ export function materializeOpus(root, mode = 'setup', options = {}) {
   removeObsolete(target, expected, mode, errors, changes)
   detectLegacyArtifacts(target, errors)
   reconcileInstructions(target, 'AGENTS.md', mode, errors, changes)
-  reconcileInstructions(target, 'CLAUDE.md', mode, errors, changes)
+  reconcileClaudeImport(target, mode, errors, changes)
   reconcileSettings(target, mode, errors, changes)
   configureGit(target, mode, errors, changes)
   return { ok: errors.length === 0, errors, changes, expected: [...expected.keys()] }

package/docs/adr/0015-action-size-follows-interaction-density.md

@@ -1,5 +1,7 @@
 # ADR 0015 — O tamanho da ação acompanha a densidade da interação
 
+> Parcialmente substituída pela [ADR 0060](0060-surface-composition-separates-chrome-and-intro.md), que define a composição e a escala atuais dos headers.
+
 - **Status:** aceita.
 - **Data:** 2026-09-12.
 

package/docs/adr/0028-schedules-run-actions-as-the-system-by-action-opt-in.md

@@ -45,7 +45,7 @@ HTTP sem usuário; o acesso do sistema é opt-in por action e negado por padrão
    `{ kind: 'schedule', scheduleName }` — ou `background` com essa provenance original. O helper
    `isSystemActor(ctx)`, exportado pelo core, responde se o ator é o sistema, para que um
    `authorize` possa aceitá-lo de forma explícita: `(ctx) => isSystemActor(ctx) ||
-   ctx.can('caixa:fechar')`. O helper não lê a provenance, que qualquer código servidor pode
+   ctx.can('ledger:close')`. O helper não lê a provenance, que qualquer código servidor pode
    preencher: ele consulta um registro interno dos contextos que o próprio runtime criou para o
    sistema. `requires` continua declarativo: o sistema não detém permissões, e o manifest mostra
    `automatable` ao lado de `permission`.

package/docs/adr/0029-page-header-is-the-single-page-introduction.md

@@ -1,6 +1,8 @@
 # ADR 0029 — PageHeader é a única introdução estrutural da página
 
-- **Status:** aceita.
+> Parcialmente substituída pela [ADR 0060](0060-surface-composition-separates-chrome-and-intro.md), que define a composição e a escala atuais dos headers.
+
+- **Status:** substituída parcialmente pela ADR 0060 na versão 28.0.0 da composição com intro.
 - **Data:** 2026-09-28.
 - **Substitui:** ADR 0011, quanto à barra persistente e à separação entre `PageHeader` e
   `PageIntro`.

package/docs/adr/0037-design-data-lives-outside-the-contract.md

@@ -54,7 +54,7 @@ Forças em tensão:
    - uma action ligada a um handler real (`bindAction`) mantém esse handler, como hoje.
 3. **Cenários são registrados fora do contrato, pelo nome da action.** O plugin ganha a opção
    `scenarios`, com um ou mais globs. Os módulos casados exportam cenários criados por
-   `defineDesignScenario(contrato, resposta)`, e a resposta pode ser um valor ou uma função tipada
+   `defineDesignScenario(contract, response)`, e a resposta pode ser um valor ou uma função tipada
    pela entrada e pela saída do contrato. O cenário vence a resposta padrão. Um cenário para uma
    action inexistente é erro visível no preview, não um silêncio.
 4. **O Opus não decide onde os cenários ficam.** A opção não tem default dentro do código da

package/docs/adr/0060-surface-composition-separates-chrome-and-intro.md

@@ -0,0 +1,161 @@
+# ADR 0060 — A composição separa controles da superfície e introdução do conteúdo
+
+- **Status:** aceita.
+- **Data:** 2026-10-10.
+- **Substitui parcialmente:** ADR 0029, quanto à proibição de PageIntro.
+- **Complementa:** ADRs 0023 e 0048.
+
+## Contexto
+
+Page perdeu a intro para evitar barras vazias e identificação redundante. Depois, Dialog e Drawer
+passaram a oferecer uma intro para separar os controles da superfície do conteúdo. A mesma página
+editorial passou a mudar o lugar do título e das ações quando aberta em outro hospedeiro.
+
+## Decisão
+
+Page, Dialog e Drawer compartilham duas composições, declaradas pelos slots, sem prop redundante:
+
+- compacta: o título e a orientação ficam no Header;
+- com intro: o Header recebe navegação e ações da superfície; a Intro é o primeiro bloco do Body
+  e recebe o único título, orientação opcional e ações locais por IntroActions.
+
+Header sem controles não reserva espaço. Navegação não é repetida na intro. O fechamento continua
+sendo responsabilidade do modal; Page não ganha um botão de fechar implícito. A posição da intro
+não muda o significado de layout: continuous/sectioned controla regiões e flow/fill controla altura.
+
+Page ganha PageIntro e PageIntroActions. A forma curta passa a colocar title e description na intro,
+com actions no Header. A forma explícita preserva a composição compacta para situações deliberadas.
+PageShell continua fornecendo contexto sem criar outra barra. Estados integrais continuam substituindo
+a introdução e o conteúdo, com um único heading acessível. O teto centralizado de 80rem é preservado.
+
+Surface mantém o cabeçalho do conteúdo, inclusive ações locais: não possui navegação ou fechamento
+que justifique uma segunda região. Pane e Split continuam sendo apenas layout. Alert mantém sua
+composição especializada. Patterns de formulário, coleção e Presentation precisam respeitar a mesma
+semântica ao montar os componentes, sem reconstruir linhas no consumidor.
+
+## Verificação e migração
+
+O checker valida família, posição da intro, unicidade do título e ações no slot correspondente.
+Testes renderizados cobrem as duas composições, estados integrais, ausência de barra vazia e contexto
+do shell. Consumidores de Page explícita migram título/descrição para PageIntro quando suas ações
+pertencem à superfície; cabeçalhos de coleções em Surface mantêm criação junto à coleção.
+
+A migração inclui SDK, exemplos, documentação e aplicação. Publicação e adoção definitiva só ocorrem
+após os gates e a revisão independente do conjunto. A versão 28.0.0 consolida a migração.
+
+## Alternativas
+
+Uma prop compact duplicaria informação já expressa pelos slots, abrindo combinações contraditórias.
+Manter Page diferente preservaria compatibilidade, mas perpetuaria a diferença entre hospedeiros.
+Uma barra obrigatória recuperaria o espaço vazio e a identificação repetida que motivaram a ADR 0029.
+
+## Rolagem
+
+Page ocupa a altura disponível do hospedeiro, com header e footer fora da região rolável.
+PageBody é o viewport vertical; a intro rola com o conteúdo. PageShell conserva a rolagem horizontal do canvas mínimo e permite rolagem vertical de
+contingência para rotas sem Page ou wrappers sem altura definida. Em layout fill, quando uma ActionList assume a rolagem, o body repassa
+a altura e não cria uma segunda rolagem vertical. Sem folha fill, o próprio body continua rolando.
+A composição compacta preserva a mesma responsabilidade: o título permanece no header estável.
+A fixação resulta da divisão de altura, sem position fixed ou sticky no consumidor.
+
+O header ocupa toda a largura disponível. O limite de 80rem e o recuo pertencem ao conteúdo
+interno do Body; o viewport ocupa a largura da página para manter sua barra de rolagem na extremidade.
+
+Quando presente, o header da Page usa borda inferior em toda a largura, como o Drawer.
+
+## Divisão visual da Page
+
+Page expõe `surfaceLayout="sectioned" | "continuous"`, com padrão `sectioned`.
+O nome separa a anatomia visual de `layout="flow" | "fill"`, preservado para altura.
+As regiões usam a tabela compartilhada de anatomia e seus divisores por adjacência.
+A largura total do header e do viewport, e o limite interno do conteúdo, valem nos dois modos.
+
+O header da Page acompanha o recuo do Drawer: 1rem no modo sectioned; no modo
+continuous, 1rem com recuo inferior de 0,75rem, ou 1rem quando for a única região.
+
+Após validação visual da barra com breadcrumb, o header da Page passa a usar 1rem nas
+laterais e 0,75rem na vertical nos dois modos. Esse ajuste substitui a equivalência de
+padding com o Drawer descrita acima; os divisores continuam compartilhados.
+
+A avaliação seguinte restaurou o padding do Drawer no header da Page: 1rem no modo
+sectioned e o ritmo correspondente no continuous. O experimento de redução vertical foi descartado.
+
+## Altura estável da linha do header
+
+A linha interna reserva 2rem em Page, Dialog, Drawer e Surface, mesmo sem ações.
+No header da Page, botões textuais usam `sm` (2rem), e os de ícone, `icon-sm` (2rem).
+Os consumidores declaram o tamanho; PageBack e comandos de Presentation em página já usam
+essa escala. Coleções e headers de modais usam a mesma escala; rodapés conservam default. É uma altura mínima, permitindo crescimento do
+conteúdo. Padding e intro permanecem independentes; headers ausentes não reservam espaço.
+
+Presentation em página delega padding e rolagem ao PageBody, tanto dentro quanto fora
+de PageShell. Não intercala um viewport próprio; PresentationBody conserva somente a
+propagação de altura quando houver conteúdo fill. Headers compactos distribuem título
+e ações na linha interna, inclusive sem navegação.
+
+## Revisão: geometria comum da família
+
+A escala compacta exclusiva de Page mantinha headers de Drawer maiores com a mesma
+composição. A família inteira passa a compartilhar padding de 1rem e linha mínima
+de 2rem: Page, Dialog, Drawer e Surface delimitada, também quando hospedada em Pane.
+Vale nos layouts continuous e sectioned; o divisor continua sendo uma decisão do layout.
+Isso substitui o ritmo variável de padding inferior dos headers descrito anteriormente.
+
+Botões de header usam `sm` para texto e `icon-sm` para ícones, incluindo comandos de
+Presentation e criação de coleções. Rodapés preservam a escala anterior. A seção
+Surface sem delimitação não ganha padding externo, e legendas recortadas continuam
+com sua geometria própria. O mínimo de linha e a escala das ações permanecem comuns.
+
+As medidas têm uma fonte compartilhada, comparada em testes entre as quatro famílias.
+Os tamanhos são declarados pelos consumidores: não há CSS de redimensionamento nem
+contexto herdável que altere botões de portais, corpos ou rodapés.
+
+## Correção da escala compacta
+
+`icon-sm` passa de 1,75rem para 2rem, correspondendo à altura de `sm`. O desenho
+do ícone continua em 0,875rem. O mínimo de 2rem da linha protege headers sem ações;
+não existe mais diferença de altura entre os controles compactos textuais e quadrados.
+Paginação usa os mesmos tokens, com largura flexível para números longos.
+
+## Ritmo vertical compartilhado — 2026-10-13
+
+A validação em Conhecimento encontrou intervalos de 0,5rem, 0,75rem e 1,25rem para a mesma
+relação entre cabeçalho e conteúdo. O padrão passa a ser 1rem entre regiões contínuas e
+entre blocos diretos de um body, inclusive TabsPanel. O componente hospedeiro fornece o
+ritmo; DetailGroup e Separator não recebem margem externa própria.
+
+Surface sem delimitação e Tabs sem moldura não adicionam padding inferior. Surface delimitada
+por framed ou elevation, Dialog e Drawer reservam 1rem até a borda. No layout sectioned,
+cada região reserva 1rem entre seu conteúdo e a divisória. No continuous, a região anterior
+fornece o intervalo, evitando somar dois paddings. A ausência de header preserva o recuo
+superior de uma superfície delimitada. Fieldset com legend conserva 1rem após a legenda.
+
+Page preserva largura de leitura e recuos laterais. Seu body não reserva padding inferior
+quando encerra a página; quando há footer sectioned, reserva 1rem até a divisória. A barra
+continua fora da rolagem. O modo flush continua removendo recuos, mas conserva o ritmo
+entre blocos: tabelas e listas que ocupam a superfície controlam seu próprio interior.
+
+Tabs mantém o espaçamento interno dos botões. O intervalo até o painel é 1rem; com framed,
+o painel recebe recuos laterais e inferior de 1rem. Abas verticais mantêm o intervalo entre
+as colunas e a moldura recebe o recuo externo sem duplicá-lo no painel.
+
+Manter medidas locais dependeria de disciplina em cada tela; impor margem a cada bloco
+somaria intervalos no aninhamento. As duas alternativas foram descartadas. A migração remove
+overrides de ritmo e padding nos slots estruturais, preservando layouts internos deliberados.
+Testes em navegador medem intervalos, fechamento inferior, aninhamento, presença/ausência de
+header e footer, flush e troca de abas. O ritmo altera o default visual; a composição de Page exige a migração documentada na versão major.
+
+Uma composição pode manter `gap-0` quando Tabs hospeda um DrawerBody que já fornece o
+intervalo superior e controla a rolagem, como o painel de nós de Fluxos. Isso evita dois
+intervalos para a mesma relação; não altera a medida de 1rem percebida pelo conteúdo.
+
+## Escala do título na intro — 2026-10-13
+
+PageTitle, DrawerTitle e DialogTitle usam a mesma escala na intro: 1,875rem, com peso
+semibold e tracking compacto. Drawer e Dialog mantêm a escala menor quando o título
+está no header compacto. A hierarquia HTML continua independente do tamanho visual.
+Metadados de data e autoria permanecem na descrição; um badge de tipo pode acompanhar
+o título em uma composição inline com quebra, sem criar um novo slot estrutural.
+
+`contentClassName` em Page e PageBody configura largura e alinhamento internos; `className`
+controla a moldura e o viewport, respectivamente. Presentation fora do shell preserva largura total.

package/docs/adr/0061-claude-md-imports-agents-md.md

@@ -0,0 +1,41 @@
+# ADR 0061 — O `CLAUDE.md` importa o `AGENTS.md`
+
+- **Status:** aceita.
+- **Data:** 2026-10-15.
+- **Acompanha:** ADR 0006 do `@softize/base`, que define o mesmo formato.
+
+## Contexto
+
+O `opus setup` escrevia o bloco de instruções do Opus no `AGENTS.md`, lido pelo Codex, e no
+`CLAUDE.md`, lido pelo Claude. A Base fazia o mesmo com o bloco dela. Fora dos blocos, cada projeto
+mantinha à mão as próprias regras nos dois arquivos, e as duas cópias divergiam: na GrandBrasil,
+quatro convenções existiram só no `AGENTS.md` por doze dias, e as sessões do Claude trabalharam sem
+elas.
+
+A documentação do Claude Code recomenda, para quem usa as duas ferramentas, um `CLAUDE.md` com a
+linha `@AGENTS.md`. A Base adotou esse formato na ADR 0006. Como o `CLAUDE.md` recebe blocos dos
+dois pacotes, e cada projeto adota as versões deles em momentos diferentes, o Opus precisa seguir
+a mesma regra para que um `setup` não desfaça o do outro.
+
+## Decisão
+
+O `AGENTS.md` é o único arquivo com instruções. O `opus setup` mantém nele o bloco do Opus e grava
+o `CLAUDE.md` como a linha `@AGENTS.md`, sem marcador.
+
+Ao reconciliar o `CLAUDE.md`, o Opus remove só o próprio bloco, quando íntegro. Blocos de outros
+pacotes ficam depois da linha do import, separados por uma linha em branco, até que o pacote dono
+os remova. O texto do projeto fora dos blocos e do import é comparado com o do `AGENTS.md`, com fim
+de linha, espaços no fim das linhas e linhas em branco seguidas normalizados: se for igual, é
+cópia e sai; se for diferente, `setup` e `opus check` preservam o arquivo e pedem para mover as
+instruções para o `AGENTS.md`. Os critérios de bloco, de linha do import e de normalização são os
+da Base, e as mensagens seguem as dela, trocando o comando por `opus setup`.
+
+## Consequências
+
+- Projeto com instruções só no `CLAUDE.md` precisa movê-las para o `AGENTS.md` antes de o `setup`
+  concluir. Por isso a mudança sai numa versão major.
+- Enquanto um projeto usa uma Base anterior à ADR 0006, o `CLAUDE.md` fica com o import e o bloco
+  da Base. O conteúdo da Base aparece duas vezes para o Claude, pelo import e pelo bloco, até a
+  adoção da Base nova; o arquivo não oscila entre os dois `setup`.
+- Um bloco do Opus editado à mão ou um bloco gerenciado malformado no `CLAUDE.md` são preservados e
+  reprovados, como antes.

package/docs/adr/README.md

@@ -12,3 +12,7 @@ Uma ADR preserva seu contexto histórico mesmo quando é substituída. O comport
 estar documentado na superfície correspondente, sem exigir a reconstrução dessa sequência.
 
 - [ADR 0059 — Subheadings orientam sem carregar regras de negócio](0059-subheadings-orient-without-carrying-business-rules.md).
+
+- [ADR 0060 — Composição de superfícies com cabeçalho e intro](0060-surface-composition-separates-chrome-and-intro.md).
+
+- [ADR 0061 — O `CLAUDE.md` importa o `AGENTS.md`](0061-claude-md-imports-agents-md.md).

package/docs/code-style.md

@@ -48,8 +48,12 @@ dinâmica, importada sem fallback ou composta de forma opaca reprova a extraçã
 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
+seletor estável e revisável. `source`, `role` e `text` selecionam o texto pelo conteúdo: a
+declaração vale para toda ocorrência desse texto com esse papel no arquivo e continua válida
+quando linhas entram ou saem acima dela. Um seletor que não encontra o texto reprova a extração,
+porque o texto mudou ou saiu do arquivo. O formato anterior, com `line` no lugar de `text` (ou
+junto dele), ainda é aceito e seleciona exatamente uma entrada naquela linha; `opus copy
+--reanchor` converte esses seletores para o formato por conteúdo. 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:
@@ -63,16 +67,16 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
     "transforms": [
       {
         "source": "src/account.ts",
-        "line": 12,
         "role": "button",
+        "text": "Confirmar",
         "transform": "uppercase"
       }
     ],
     "exemptions": [
       {
         "source": "src/account.ts",
-        "line": 18,
         "role": "label",
+        "text": "ABC-123",
         "ruleId": "COPY001",
         "kind": "external-requirement",
         "reason": "Código regulatório exibido na grafia oficial.",
@@ -145,21 +149,56 @@ exigiria adivinhar espaços continuam reprovando.
 
 Quando o diagnóstico corresponde a dados reais da aplicação ou a uma mensagem interpolada,
 `copy.dynamic` permite classificar somente aquela superfície sem excluir o arquivo. Cada item
-seleciona exatamente um diagnóstico por `source`, `line` e `field`, registra `reason` e
-`reference` auditáveis e usa um destes contratos:
+seleciona o diagnóstico por `source`, `field` e `expression` — o trecho de código que o
+extrator não conseguiu resolver; a mensagem do `opus copy` traz os dois valores prontos para
+copiar —,
+registra `reason` e `reference` auditáveis e usa um destes contratos:
 
 - `runtime-data` reconhece nomes, contagens, status ou opções fornecidos em runtime. Nenhuma
   entrada editorial é fabricada;
 - `message-template` exige `role` e `text`. O texto-modelo entra no inventário e passa pela
   política da Base, mas não substitui nem altera o conteúdo renderizado.
 
-As declarações aparecem em `dynamicSurfaces` no inventário. Se o source mudar e o seletor não
-encontrar exatamente um diagnóstico, `opus copy` falha. Assim, a classificação permanece
+No trecho, espaços e quebras de linha viram um espaço só e a vírgula final antes de `)`, `]` ou
+`}` é ignorada, para a âncora sobreviver à reformatação; trechos com mais de 200 caracteres são
+cortados e terminam em `…`. A declaração vale para toda ocorrência do mesmo trecho no mesmo
+campo do arquivo e não depende da linha em que ele está.
+
+As declarações aparecem em `dynamicSurfaces` no inventário, com as linhas atuais de cada
+ocorrência. Se o código mudar e o seletor deixar de encontrar o trecho, `opus copy` falha e lista,
+numa execução, todas as declarações quebradas, cada uma com o arquivo, o campo e os trechos desse
+campo que ainda não têm declaração. Assim, a classificação permanece
 estreita e revisável, sem transformar metadata em uma exclusão silenciosa. O mecanismo aceita
 somente diagnósticos de conteúdo; incerteza estrutural, `className`, `style`, transformação ou
 modo de renderização continua bloqueante. Superfície vazia também não pode ser reclassificada
 como dado de runtime.
 
+Declarações escritas antes da versão 29.0.0 usam `line` no lugar de `expression` (ou de `text`,
+nas exceções e transformações) e quebram sempre que alguém edita o arquivo acima delas. Elas
+continuam aceitas, selecionam exatamente um alvo naquela linha e são aplicadas antes das
+declarações por conteúdo, para que uma declaração pontual não seja coberta por uma geral; o
+`opus copy` avisa quantas restam. Para convertê-las, rode `opus copy --reanchor`. O comando
+agrupa as declarações por arquivo e campo (em `copy.dynamic`) ou por arquivo, papel e texto
+(nas exceções e transformações), grava o `base.json` e regenera o inventário:
+
+- um grupo só é convertido quando tem exatamente uma declaração para cada alvo. Assim a âncora
+  por conteúdo cobre os mesmos alvos que as âncoras por linha cobriam. Se o mesmo texto aparece
+  mais vezes do que foi declarado, ou se há um diagnóstico do campo sem declaração, o grupo
+  continua por linha e aparece no relatório;
+- dentro do grupo, declarações e alvos são pareados em ordem de linha. Quando o arquivo mudou e
+  as âncoras quebraram, o comando lista cada declaração que mudou de linha para revisão no diff;
+- declarações idênticas que passariam a selecionar o mesmo conteúdo viram uma só;
+- duas declarações com motivos diferentes para o mesmo conteúdo continuam por linha, já
+  corrigida, porque um seletor por conteúdo cobriria as duas com um único motivo. Para
+  convertê-las, unifique o motivo ou mantenha a âncora por linha;
+- os seletores gravados precisam passar na extração do `opus copy`; o que não dá para ancorar com
+  segurança fica como está e aparece no relatório.
+
+O `--reanchor` não avalia a política de copy da Base. Depois dele, rode `opus copy --check` e
+`base copy check`. Na revisão de uma declaração por conteúdo, vale olhar `dynamicSurfaces[].lines`
+no diff do inventário: uma lista que cresce indica que um trecho genérico, como `title` ou
+`count`, passou a cobrir uma ocorrência nova, que pode ter outra origem.
+
 Um `opus copy --check` verde **não significa que toda a copy do produto foi coberta**. Ficam
 fora, deliberadamente:
 

package/docs/protocol.md

@@ -679,7 +679,7 @@ O acesso do sistema é **opt-in por action** e negado por padrão. Sem usuário,
 `isSystemActor(ctx)` responde se o ator é o sistema. Ele consulta um registro interno dos contextos que o runtime criou, e não a provenance. Como o sistema não detém permissões, um `authorize` que delega a `ctx.can` o aceita de forma explícita, numa closure — a DSL em string não expressa isso, e `ctx.provenance` não serve como teste de sistema, porque o chamador de `runtime.execute` pode preenchê-la:
 
 ```ts
-authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar')
+authorize: (ctx) => isSystemActor(ctx) || ctx.can('ledger:close')
 ```
 
 `requires` continua declarativo; o manifest projeta `automatable` ao lado de `permission`. O audit registra `actor: { id: null, type: 'system' }`. Ver ADR 0028.

package/docs/releasing.md

@@ -18,6 +18,13 @@ confere essa entrada só DEPOIS do bump, então esquecê-la aborta a release com
 alterado — e a tentativa seguinte para na guarda de árvore limpa. Para recuperar, desfaça o bump
 (`git checkout -- package.json`), escreva a entrada, commite e rode de novo.
 
+Uma entrada que já está na `origin/main` não muda mais: quem consome o pacote lê o changelog como
+guia de migração, e em 10/09/2026 uma formatação avulsa reescreveu entradas publicadas e mudou o
+sentido de uma delas. Para corrigir uma informação publicada, registre a correção numa entrada
+nova, na próxima versão. A entrada da versão em preparo, enquanto não chega à `main`, pode ser
+ajustada livremente. O pre-push (`.githooks/pre-push.d/01-changelog`) e o `pnpm release` reprovam
+a alteração de uma seção publicada; para conferir antes, rode `pnpm changelog:check` na raiz.
+
 Os comandos rodam em `packages/opus`; o `package.json` da raiz não tem `release`.
 
 ```bash

package/package.json

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

package/registry/instructions/opus.md

@@ -24,7 +24,9 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
   e operá-los por `opus seed`; não criar comandos de seed paralelos nem reset implícito.
 - 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.
+  valida o conteúdo. O inventário também guarda o hash de todo arquivo JS/TS do escopo, mesmo sem
+  copy, como os scripts em `scripts/*.mjs`; alterar qualquer um deles também exige `opus copy`,
+  e o pre-push reprova o inventário desatualizado.
 - 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

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

@@ -43,17 +43,17 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 7. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh. Em `Presentation`, declarar `route`
    no artefato e deixar o adaptador apenas conectar a spec ao router da aplicação.
-8. Compor superfícies pela gramática estrutural do catálogo: `PageHeader` é a única introdução
-   estrutural e reúne navegação contextual opcional, título e ações; `PageBody` contém o conteúdo.
-   Na composição explícita, declare exatamente um heading principal com `PageTitle` no header,
-   `Surface level={1}` ou um `PageState` ativo no body. `PageShell` pode fornecer navegação e ações
-   conhecidas pela aplicação, mas não cria uma barra visual. `Surface` contém `SurfaceHeader` e
-   `SurfaceBody`; Drawer e Pane usam seus respectivos `*Body`. Para o caso direto, usar a sintaxe
-   abreviada de `Page` (`title`, `actions`) ou de `Surface` (`title`, `description`, `actions` e
-   `count`); não misturá-la com o
-   header explícito. O título da página não carrega contador. Ajustar o
-   nível do heading pela hierarquia semântica, não pelo destaque visual. O `Page` mantém seu teto
-   centralizado padrão de `80rem`.
+8. Compor Page, Dialog e Drawer pela mesma gramática: no formato compacto, título e orientação
+   ficam no Header; com Intro, navegação e ações da superfície ficam no Header e a Intro abre o
+   Body com título, orientação e ações locais em IntroActions. Declarar a escolha pelos slots,
+   sem prop redundante. Usar PageIntro na Page explícita; a forma curta de Page já coloca title e
+   description na intro e actions no header. Não misturar shorthand com regiões explícitas.
+   Manter exatamente um heading principal, inclusive quando Surface level={1} nomeia uma coleção
+   ou PageState substitui a página. PageShell fornece contexto sem criar barra paralela; header
+   sem controles não reserva espaço. Preservar o teto de 80rem e separar composição de ocupação
+   de altura (flow/fill). Surface mantém o cabeçalho do conteúdo; Pane distribui espaço e recebe
+   uma superfície quando precisar de anatomia visual. Não criar Intro nem controles de navegação
+   artificiais para Surface ou Pane.
    Em `Surface framed`, usar `layout="sectioned"` e `SurfaceBody flush` quando o filho direto já
    controlar o recuo do body, como `DetailGroup` com divisores, lista ou tabela; não reconstruir
    divisor, padding ou recorte por classes no consumidor. Em grupos de formulário,
@@ -89,10 +89,12 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 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`. Quando uma superfície mapeada recebe dados da aplicação, usar
-`copy.dynamic` com seletor exato, motivo e referência: `runtime-data` para valores sem autoria
-editorial; `message-template` com `role` e texto-modelo para mensagens interpoladas. Não excluir
+`copy.dynamic` com `field` e `expression` copiados do diagnóstico, motivo e referência:
+`runtime-data` para valores sem autoria editorial; `message-template` com `role` e
+texto-modelo para mensagens interpoladas. Não usar `line` em declaração nova. Não excluir
 o arquivo inteiro nem contornar o diagnóstico com `aria-label` paralelo. Revisar cada declaração
-dinâmica como fronteira de cobertura, mesmo com os gates verdes.
+dinâmica como fronteira de cobertura, mesmo com os gates verdes, inclusive quando
+`dynamicSurfaces[].lines` cresce no diff do inventário.
 Inspecionar visualmente a rota real e validar navegação por URL quando aplicável.
 
 ## Limites

package/registry/skills/build-opus-ui/references/evaluations.md

@@ -74,3 +74,13 @@ complementar do termo. Esperado: `description` orienta a finalidade, `hint` mant
 de deixar vazio e `help` oferece somente o detalhe opcional. `intro` continua no corpo quando a
 regra afeta vários campos. Reprovar regra obrigatória somente em subheading ou tooltip, repetição
 da label, duplicação entre hint/help e perda de `aria-describedby` quando aparece um erro.
+
+## Composição de superfícies
+
+- Gatilho positivo: “Monte o detalhe de um recurso com menu da página separado do título.”
+- Gatilho negativo: “Explique por que a ADR antiga juntava título e ações”, sem pedido de UI.
+- Execução: montar o mesmo detalhe em Page, Dialog e Drawer com header de navegação/ações e intro
+  abrindo o body; montar também a versão compacta sem intro. Provar título único, ações locais em
+  IntroActions, nenhum header vazio na Page e transição de loading para conteúdo sem título duplicado.
+- Reprovar intro depois de texto, título simultâneo em header e intro, ações da superfície no título
+  ou adaptação de Pane para que ele volte a possuir anatomia visual.