aiox update 5.0.x → 5.0.7 falha: manifest sem assinatura .minisig + validate sem flag --no-signature

[ruibrunocunha]

Summary

aiox update falha sempre ao actualizar para a versão 5.0.7 com erro Manifest signature verification failed: Manifest signature file not found (.minisig) e faz rollback automático — mesmo quando o npm install aiox-core@5.0.7 correu com sucesso antes.

Parece ser um bug do release 5.0.7 (não um problema de ambiente): o package npm foi publicado sem o ficheiro de assinatura, e a CLI não expõe forma de saltar a verificação.

Environment

• AIOX CLI: 5.0.7 (global install via npm i -g aiox-core@5.0.7)
• Previous AIOX version: 5.0.4 (installed 2026-04-08)
• Node: v24.13.0
• Platform: macOS (darwin arm64)
• Project mode: project-development

Steps to reproduce

# Projecto com AIOX 5.0.4 instalado
aiox update

Expected behavior

Update bem-sucedido para 5.0.7, com validação pós-install a passar.

Actual behavior

[downloading] Downloading update...
npm install aiox-core@5.0.7 --save-exact   ← corre com sucesso
[finalizing] Updating version info...
[validating] Validating installation...
[PostInstallValidator] WARNING: Signature verification disabled - development mode only
[PostInstallValidator] Loaded manifest v5.0.4 with 1107 files   ← carrega manifest ANTIGO
[rollback] Validation failed, rolling back...

✗ Update failed
  Error: Validation failed (integrity: 0%)
  Rolled back to previous version.

Execução directa do aiox validate confirma a causa raiz:

✗ Manifest signature: NOT VERIFIED
✗ Status: FAILED
  Integrity Score: 0%

Critical Issues
  ✗ Manifest signature verification failed: Manifest signature file not found (.minisig)
    → Obtain a properly signed manifest from the official source

Root causes (3 problemas distintos)

1. Package npm 5.0.7 foi publicado sem .minisig

ls node_modules/aiox-core/.aiox-core/*.minisig
# No such file or directory

packages/installer/src/installer/post-install-validator.js linha 417 exige assinatura por default (requireSignature: true). Como o package oficial não inclui .minisig, a validação falha sempre para qualquer utilizador.

2. CLI aiox validate não expõe --no-signature

Ver .aiox-core/cli/commands/validate/index.js — as flags disponíveis são:

• --repair, --dry-run, --detailed, --no-hash, --extras, --verbose, --json, --source

A classe PostInstallValidator aceita requireSignature: false (documentado em docs/security/MANIFEST_SIGNING.md secção "Development Mode"), mas não há forma de passar essa opção via CLI.

3. Rollback automático em aiox update sem override

O aiox update não tem flag equivalente para dizer "ignora a assinatura em falta". O utilizador fica preso.

Workaround usado

Como o npm install aiox-core@5.0.7 realmente correu com sucesso antes da validação falhar, bastou copiar o manifest novo do node_modules para o projecto e actualizar version.json:

cp node_modules/aiox-core/.aiox-core/install-manifest.yaml .aiox-core/install-manifest.yaml
# Editar manualmente .aiox-core/version.json: "version": "5.0.4" → "5.0.7"

Depois disto:

• aiox --version → 5.0.7 ✓
• aiox info → 22 agents, 205 tasks, 11 templates, 15 workflows ✓
• Hashes dos ficheiros batem com o manifest 5.0.7 ✓

Suggested fixes

Pelo menos uma das opções:

1. Recomendado — publicar .minisig no package npm. Garantir que scripts/generate-install-manifest.js + signing step corre antes do npm publish. Validar que files em package.json inclui .aiox-core/install-manifest.yaml.minisig.

2. Expor --no-signature em aiox validate e em aiox update. Mapear para requireSignature: false. Documentar como "development only, insecure".

3. Detectar ausência do .minisig e degradar para warning em vez de error. Se o package oficial não inclui signature, a validação deve emitir warning (requireSignature: false comportamento) em vez de fail+rollback. Produção podia ser activada via env var AIOX_REQUIRE_SIGNATURE=true.

Referências

• packages/installer/src/installer/post-install-validator.js:334-347 — opção requireSignature
• packages/installer/src/installer/post-install-validator.js:417-432 — bloqueio em requireSignature: true sem .minisig
• .aiox-core/cli/commands/validate/index.js:56-68 — flags expostas na CLI
• docs/security/MANIFEST_SIGNING.md:189-213 — Development Mode documentado mas sem forma de activar via CLI

Impact

Qualquer projecto que tente aiox update para 5.0.7 vai falhar com rollback. Bloqueia adopção do release.

[github-actions]

Welcome to aiox-core! Thanks for opening your first issue.

What happens next?

• A maintainer will triage this and add appropriate labels
• We'll respond as soon as possible
• Feel free to join Community Discussions

Helpful Resources:

• Contributing Guide
• Documentation

Looking to contribute? Check issues labeled community: good first issue.

[ruibrunocunha]

Additional bugs found during manual recovery

Depois de contornar o bug de signature descrito acima, tentei correr aiox install --force em branch isolado (seguindo a recomendação do aiox doctor para corrigir entity-registry stale + .claude/skills/ em falta). Encontrei 2 bugs adicionais relacionados:

---

Bug adicional 2 — --dry-run é silenciosamente ignorado quando combinado com --quiet

Comando:

aiox install --force --dry-run --quiet

Esperado: simular install sem modificar ficheiros.

Observado: o install correu para valer. .aiox-core/version.json foi reescrito com novo installedAt, entity-registry.yaml ficou com hash novo, e 33 ficheiros foram modificados no working tree. A CLI não emitiu nenhum aviso de que --dry-run foi ignorado.

Repro:

git status --short  # antes: clean
aiox install --force --dry-run --quiet
git status --short  # depois: 33 ficheiros modificados ❌

Suspeito que --quiet ativa um caminho não-interativo que salta a verificação do flag --dry-run, ou que os handlers dos dois flags conflituam internamente.

Suggested fix: --dry-run deve ser verificado logo no início do handler, antes de qualquer fs write, independentemente de outros flags. Adicionar teste de integração que valide git status limpo após install --dry-run --quiet --force.

---

Bug adicional 3 — aiox install --force sobrescreve completamente .claude/settings.json em vez de fazer merge

Severidade: CRITICAL (perda de configuração de segurança / Constitution violation)

Esperado (pela própria doc do --help):

Smart Merge (Brownfield):
When installing in a project with existing config files (.env, CLAUDE.md), AIOX can merge new settings while preserving your customizations.

Observado: .claude/settings.json foi totalmente sobrescrito com o template default. Perdi:

• Bloco permissions.allow inteiro (~35 rules customizadas para operações git, npm, ls, etc.)
• Bloco permissions.deny inteiro (~9 rules que bloqueavam:
  • rm -rf /.aiox-core/*, rm -rf /.claude/*
  • git push --force, git push -f
  • --no-verify em qualquer comando (bypass de hooks)
  • git reset --hard, git clean -f, git checkout -- ., git restore .
  • Read(./private/**)
    )
• defaultMode: "acceptEdits"

Isto é uma violação directa da Constitution Article II (Agent Authority): as deny rules que bloqueavam git push --force e --no-verify eram o enforcement mecanismo que garantia que apenas @devops podia fazer push e que nunca se saltavam pre-commit hooks. Remover silenciosamente essas rules é um regressão crítica de segurança.

Outros ficheiros também foram sobrescritos em vez de merged:

Ficheiro	Perdido
.aiox-core/core-config.yaml	Blocos inteiros: pro:, memory:, metrics:, integrations: (~35 linhas removidas)
.aiox-core/core-config.yaml	Flag claude-code: true → false (apesar de eu usar Claude Code como IDE primário)
.aiox-core/development/agents/dev/MEMORY.md	Knowledge acumulado: Epic GEO-LK (LinkedIn carousels), GEO Audit incident learnings, paths de templates/briefs — 23 linhas críticas
.aiox-core/development/agents/devops/MEMORY.md	Knowledge acumulado
.aiox-core/development/agents/po/MEMORY.md	Knowledge acumulado
.env.example	Bloco CIRCLE_* (Circle Community config) removido

O comportamento contradiz directamente o --help:

Smart Merge (Brownfield):
  ...
  - .env files: Adds new variables, preserves existing values
  - CLAUDE.md: Updates AIOX sections, keeps your custom rules

Nem .env.example nem .claude/settings.json estão na lista de "protected", mas .claude/settings.json contém configuração de permissões executivas da CLI / Constitution enforcement — deveria estar.

Suggested fix:

1. .claude/settings.json deve ser tratado como arquivo protegido (merge-only, nunca overwrite), ao mesmo nível de .env e CLAUDE.md.
2. Agent MEMORY.md files deveriam ser L3 protegidos — MEMORY.md é explicitamente documentado em CLAUDE.md como L3 (Project Config mutável) e está listado em .claude/rules/agent-memory-imports.md como propriedade do agente, não do framework. Nunca deveria ser sobrescrito pelo installer.
3. Oferecer --merge como default em brownfield e --force deveria preservar explicitamente rules de segurança. Alternativa: --force pede confirmação interativa "This will overwrite: settings.json, MEMORY.md files, env files. Continue? [y/N]".
4. Detectar brownfield automaticamente (pela existência de .git, .claude/rules/*.md, etc.) e mudar o default para preservação.

---

Recovery action

No meu caso, abortei o branch de upgrade (git checkout . + git clean -fd) e revertit para o estado anterior ao install --force. O framework continua a funcionar correctamente em 5.0.7 (22 agents, 205 tasks, 11 templates, 15 workflows) sem correr o install. Os 2 warnings do doctor (entity-registry 80h old, skills dir em falta) são aceitáveis para operação normal.

Impact

Estes 2 bugs combinados significam que nenhum utilizador brownfield pode actualizar AIOX com segurança:

• Ou o update falha com rollback (bug original)
• Ou o install --force destrói configuração de projecto e segurança

O caminho seguro actual é: npm i -g aiox-core@X.Y.Z, depois substituir install-manifest.yaml + version.json manualmente a partir do node_modules — o que não é um workflow aceitável para release pública.