@softize/opus 28.0.0 → 29.0.0

package/CHANGELOG.md

@@ -7,6 +7,64 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 29.0.0 — 2026-10-15
+
+O `CLAUDE.md` passa a importar o `AGENTS.md`, e as declarações de copy passam a ser ancoradas pelo
+conteúdo, não pela linha. A seção **Breaking** traz a única migração obrigatória, que atinge só quem
+mantém instruções no `CLAUDE.md` que não estão no `AGENTS.md`.
+
+### Breaking
+
+`opus setup` mantém o bloco do Opus só no `AGENTS.md` e grava o `CLAUDE.md` como a linha
+`@AGENTS.md`, que importa as instruções para o Claude Code (ADR 0061, no mesmo formato da ADR 0006 da
+Base). Na conversão, o `setup` remove do `CLAUDE.md` o bloco do Opus e descarta o texto do projeto
+que repete o do `AGENTS.md`. Texto que só existe no `CLAUDE.md` é preservado, e o `setup` e o
+`opus pre-push materialization` reprovam até que ele vá para o `AGENTS.md`. Blocos de outros
+pacotes ficam depois do import até que o pacote dono os remova: com uma Base anterior à ADR 0006, o
+`CLAUDE.md` fica com o import e o bloco da Base.
+
+Migre movendo para o `AGENTS.md` as instruções que estão só no `CLAUDE.md` e rodando `opus setup`.
+
+### Âncora de copy pelo conteúdo
+
+- **`copy.dynamic` por trecho.** A declaração seleciona o diagnóstico por `source`, `field` e
+  `expression`, o trecho de código que o extrator não resolveu, e continua válida quando linhas
+  entram ou saem acima dela. Espaços e quebras de linha do trecho são normalizados e a vírgula
+  final antes de `)`, `]` ou `}` é ignorada, para a âncora sobreviver à reformatação. A declaração
+  vale para toda ocorrência do mesmo trecho no mesmo campo do arquivo, e `dynamicSurfaces` registra
+  as linhas atuais de cada uma. O diagnóstico de conteúdo traz o `field` e a `expression` prontos
+  para a declaração.
+- **`copy.exemptions` e `copy.transforms` por texto.** Sem `line`, `source`, `role` e `text`
+  selecionam toda ocorrência desse texto com esse papel no arquivo.
+- **Seletores por linha continuam aceitos.** Eles selecionam exatamente um alvo, são aplicados
+  antes dos seletores por conteúdo e geram um aviso no `opus copy`. `opus copy --reanchor` converte
+  o `base.json` agrupando as declarações por arquivo e campo, ou por arquivo, papel e texto. Um
+  grupo só é convertido quando tem uma declaração para cada alvo, para que a âncora por conteúdo não
+  cubra um alvo que ninguém declarou; dentro dele, declarações e alvos são pareados em ordem de
+  linha, e as que mudaram de linha são listadas para revisão. Declarações idênticas se fundem, e
+  duas com motivos diferentes para o mesmo conteúdo continuam por linha, já corrigida. Os seletores
+  gravados passam na extração do `opus copy`; a política da Base não é avaliada, então rode
+  `opus copy --check` e `base copy check` depois e revise o diff.
+- **`dynamicSurfaces` no inventário.** Uma declaração por conteúdo aparece com `expression` e
+  `lines`, as linhas atuais de cada ocorrência, no lugar de `line`. Uma lista `lines` que cresce no
+  diff indica que o trecho passou a cobrir uma ocorrência nova.
+- **Erros que dizem onde.** Cada seletor que deixa de encontrar seu alvo aparece na mesma execução,
+  com o arquivo, o campo, o trecho e os diagnósticos daquele campo ainda sem declaração, ou com o
+  aviso de que o arquivo não existe mais no escopo.
+
+### Instruções, documentação e changelog
+
+- A instrução gerenciada do Opus passa a dizer que o inventário de copy guarda o hash de todo
+  arquivo JS/TS do escopo, inclusive scripts sem copy como `scripts/*.mjs`, e que alterar qualquer
+  um deles também exige `opus copy`.
+- Os exemplos da documentação usam identificadores, nomes de action, domínios, eventos e permissões
+  em inglês (`ledger.close`, `ledger:close`, `invoice.issued`); rótulos, mensagens e comentários
+  continuam em pt-BR. O padrão editorial e a lista de verificação da skill `maintain-opus-docs`
+  passam a exigir isso, e um teste do repositório reprova identificadores com palavra em português.
+- Entradas do changelog que já estão na `origin/main` do Opus não mudam mais: uma correção de
+  informação publicada entra como entrada nova. O pre-push e o `pnpm release` do repositório
+  reprovam a alteração.
+
 ## 28.0.0 — 2026-10-13
 
 ### Breaking

package/bin/cli.mjs

@@ -15,7 +15,7 @@ import { cmdGen, helpGen } from './lib/gen.mjs'
 import { cmdDb } from './lib/db.mjs'
 import { scanDir, emptyScanVerdict } from './lib/check.mjs'
 import { log } from './lib/cli-shared.mjs'
-import { checkCopyInventory, writeCopyInventory } from './lib/copy.mjs'
+import { checkCopyInventory, reanchorCopySelectors, writeCopyInventory } from './lib/copy.mjs'
 import { createMonorepo, createProject } from './lib/create.mjs'
 import { initProject, repoRootOf, setupUiFoundation } from './lib/init.mjs'
 import { introspect } from './lib/introspect.mjs'
@@ -63,9 +63,9 @@ async function cmdCheck(dir) {
     log('error', `✗ opus check: nenhuma action encontrada em ${rel} (${files} arquivos .ts); ${verdict.message}`)
     process.exit(1)
   }
-  const viaContrato = contracts > 0 ? ` (${contracts} contrato(s))` : ''
+  const contractSuffix = contracts > 0 ? ` (${contracts} contrato(s))` : ''
   if (findings.length === 0) {
-    log('success', `✓ opus check: ${actions} action(s)${viaContrato}; nenhuma violação encontrada.`)
+    log('success', `✓ opus check: ${actions} action(s)${contractSuffix}; nenhuma violação encontrada.`)
     return
   }
 
@@ -97,10 +97,28 @@ async function cmdMaterializationCheck() {
 async function cmdCopy(dir, flags) {
   const selected = path.resolve(process.cwd(), dir ?? '.')
   const root = (await repoRootOf(selected)) ?? selected
+  if (flags.reanchor) {
+    if (flags.check) {
+      log('error', '✗ opus copy: --reanchor grava o base.json e não combina com --check.')
+      process.exitCode = 1
+      return
+    }
+    if (!reportReanchor(reanchorCopySelectors(root))) {
+      process.exitCode = 1
+      return
+    }
+  }
   const result = flags.check ? checkCopyInventory(root) : writeCopyInventory(root)
   for (const diagnostic of result.diagnostics) {
     log('error', `✗ opus copy: ${diagnostic.source}:${diagnostic.line} — ${diagnostic.message}`)
   }
+  if (result.legacySelectors > 0) {
+    log(
+      'warn',
+      `! opus copy: ${result.legacySelectors} seletor(es) em base.json ainda usam \`line\`, que quebra a cada edição acima dele; ` +
+        'rode `opus copy --reanchor` para ancorá-los pelo conteúdo.',
+    )
+  }
   if (!result.ok) {
     if (result.reason === 'missing') {
       log('error', `✗ opus copy: inventário ausente em ${path.relative(root, result.path)}; rode \`opus copy\` e versione o resultado.`)
@@ -121,6 +139,40 @@ async function cmdCopy(dir, flags) {
   else log('success', `✓ opus copy: ${location} já estava atualizado (${summary}).`)
 }
 
+function reportReanchor(result) {
+  if (!result.ok) {
+    for (const diagnostic of result.diagnostics) {
+      log('error', `✗ opus copy --reanchor: ${diagnostic.source}:${diagnostic.line} — ${diagnostic.message}`)
+    }
+    log('error', '✗ opus copy --reanchor: resolva os problemas de leitura acima antes de reancorar; base.json não foi alterado.')
+    return false
+  }
+  const { converted, realigned, relined, merged, unresolved } = result.report
+  const anchor = (item) => (item.anchor.expression === undefined ? `"${item.anchor.text}"` : `\`${item.anchor.expression}\``)
+  if (converted.length > 0) log('success', `✓ opus copy --reanchor: ${converted.length} seletor(es) passaram a ser ancorados pelo conteúdo.`)
+  // copy.dynamic identifica o alvo pelo campo; exceções e transformações, pelo papel do texto.
+  const target = (item) => (item.list === 'dynamic' ? `\`${item.selector.field}\`` : `(${item.selector.role})`)
+  if (realigned.length > 0) {
+    log('warn', `! opus copy --reanchor: ${realigned.length} âncora(s) quebradas pela mudança de linha foram convertidas; revise cada uma no diff:`)
+    for (const item of realigned) {
+      console.log(`    copy.${item.list}[${item.index}] ${item.selector.source} ${target(item)} linha ${item.from} → ${item.to}: ${anchor(item)}`)
+    }
+  }
+  if (relined.length > 0) {
+    log('warn', `! opus copy --reanchor: ${relined.length} seletor(es) continuam por linha, com a linha corrigida; revise cada um no diff:`)
+    for (const item of relined) {
+      console.log(`    copy.${item.list}[${item.index}] ${item.selector.source} linha ${item.from} → ${item.to}: ${item.reason}`)
+    }
+  }
+  if (merged.length > 0) log('success', `✓ opus copy --reanchor: ${merged.length} declaração(ões) repetida(s) fundida(s) com a idêntica.`)
+  if (unresolved.length > 0) {
+    log('warn', `! opus copy --reanchor: ${unresolved.length} seletor(es) continuam por linha:`)
+    for (const item of unresolved) console.log(`    copy.${item.list}[${item.index}]: ${item.reason}`)
+  }
+  if (!result.changed) log('success', '✓ opus copy --reanchor: nada a converter em base.json.')
+  return true
+}
+
 async function cmdCreate(dir, flags) {
   if (!dir) {
     log('error', 'Uso: opus create <dir> — o nome do diretório vira o nome do app (--monorepo: a raiz do workspace).')
@@ -273,6 +325,10 @@ function parseArgs(argv) {
       flags.json = true
       continue
     }
+    if (arg === '--reanchor') {
+      flags.reanchor = true
+      continue
+    }
     if (arg === '--monorepo') {
       flags.monorepo = true
       continue
@@ -334,6 +390,7 @@ Flags
   --help, -h         Ajuda do comando.
   --check            (copy) Compara sem escrever; falha se o inventário estiver ausente ou
                      desatualizado.
+  --reanchor         (copy) Ancora pelo conteúdo os seletores do base.json que usam linha.
   --json             (introspect, seed) Saída estruturada em JSON.
   --monorepo         (create) Cria a raiz do workspace em vez de um app.
   --config <path>    (gen, db, seed) Caminho do opus.config.ts. Default: ./opus.config.ts.
@@ -483,6 +540,14 @@ comprova que o extrator executou sobre uma fonte.
 
 Flags:
   --check          Compara sem escrever; falha em ausência, drift ou copy dinâmica
+                   sem declaração.
+  --reanchor       Converte os seletores de copy.dynamic, copy.exemptions e
+                   copy.transforms que ainda usam \`line\` para seletores pelo
+                   conteúdo, grava o base.json e regenera o inventário. Só
+                   converte quando há uma declaração para cada alvo, para não
+                   ampliar nenhuma; as que mudaram de linha são listadas para
+                   revisão, e o que não dá para converter com segurança fica
+                   como está. Depois, rode base copy check e revise o diff.
 `)
       return
     }