quality

quality é o bundle para times que enviam código para produção. Ele adiciona gates de auditoria pré-merge sobre o workflow de implementação do starter: auditorias separadas para security, money handling, escopo multi-tenant, contratos cross-stack, profundidade arquitetural e atualização de configuração — compostas em paralelo pelo audit-all.

Por que isso existe

O starter codifica como escrever bom código. O quality codifica como verificar se o código está seguro para o merge. As duas coisas são preocupações diferentes: implementação é um workflow, auditorias são gates. Misturar tudo em um único bundle significaria que times que não precisam de auditorias (um projeto hobby, um repo de prototipagem) pagariam o custo do ruído mesmo assim; times que de fato precisam delas perderiam a visibilidade que vem de tê-las como add-ons deliberados.

As auditorias deste bundle miram modos de falha específicos com custo real em produção: um cálculo monetário que arredonda para o lado errado, uma query multi-tenant sem o filtro de tenant, um contrato de API que diverge entre frontend e backend.

Arquétipo de time

Isto é para times que:

• enviam para usuários pagantes (money-handling, billing, subscriptions)
• rodam um SaaS multi-tenant (regras de data-scope, filtros de ownership)
• têm separação entre frontend e backend (contratos de API, alinhamento de DTOs)
• têm superfície de segurança não-trivial (auth, secrets, endpoints públicos)
• querem higiene trimestral sobre a própria configuração do agent

Se seu repo é uma ferramenta single-tenant sem money / auth / contratos de API, o quality é, em grande parte, exagero. Fique com o starter e adicione o quality depois, se a superfície crescer.

O que inclui

skills:
  - audit-all         # parallel composer of the four audits
  - audit-contracts  # API-vs-frontend contract drift
  - refactor-deepen   # find shallow modules, propose deepening
  - audit-config      # configuration freshness (rules, skills, hooks)
  - audit-grounding   # signal-only divergence from the source of truth
  - audit-verification # completion-verification signal
  - audit-style        # design-rules/over-engineering style signal
  - code-metrics       # leitura de medição PR-time com delta duplo (incorporada ao quality; desmarque no picker se não precisar)
roles:
  - architect         # senior reviewer with BLOCKING/ADVISORY/QUESTION discipline
  - security          # security specialist — audit-security checklist + threat modeling

Mais as skills de auditoria que o audit-all compõe — audit-security, audit-money, audit-tenant, audit-contracts — que são instaladas como dependências transitivas.

Fonte: bundles/quality.yml

Por que cada uma está aqui

• audit-all — o composer que roda as quatro auditorias em paralelo contra uma branch ou PR, produzindo um relatório consolidado com severidades em camadas e hotspots cross-audit. É o ponto de entrada que a maioria dos times usa.
• audit-contracts — separada do audit-all porque atua em um escopo diferente (drift de contrato cross-stack detectado no diff, não auditorias de conteúdo de arquivo).
• refactor-deepen — auditorias de profundidade arquitetural não se encaixam no formato de gate pré-merge, mas pertencem à mesma preocupação de “esse código está limpo?” das auditorias de security e money. A skill encontra oportunidades de aprofundamento de módulos rasos via teste de deleção e um vocabulário canônico.
• audit-config — adicionada na v1.50.0 para capturar o problema de drift de configuração apontado no artigo da Anthropic sobre large-codebases: rules calibradas para modelos mais antigos podem limitar modelos mais novos. Audita rules/, skills/, hooks/, commands/, bundles/ em busca de datas obsoletas, skills fantasmas e referências a paths deprecados.
• audit-grounding — adicionada na v1.69.0 para pegar o modo de falha semântico que as outras auditorias não veem: um agent inventando uma convenção do time ou afirmando um fato de domínio que contradiz a fonte de verdade (CONTEXT.md, docs/adr/, knowledge/). Signal-only — reporta divergências e deixa a decisão com o humano. Seu Stop hook grounding-check a dispara ao fim de toda tarefa com um diff.
• role architect — o quality inclui a persona de senior-reviewer porque achados de auditoria muitas vezes precisam de uma classificação de nível humano: blocking vs advisory vs needs-discussion. A role formaliza isso.
• role security — a persona especialista em segurança. Roda o checklist audit-security como baseline e adiciona threat modeling sobre o diff (superfície de ataque, fluxos de auth/dados). O router do codereview a despacha em diffs de auth/secret, em dual gate com o architect — o mesmo padrão que o dba segue em diffs da camada de dados.

Por que cada uma está aqui (continuação)

• code-metrics — o eixo quantitativo de medição: uma leitura local e não-bloqueante com delta duplo de cobertura, complexidade ciclomática, tamanho de módulo e ciclos de dependência no PR-open. Incorporada ao quality (era um bundle standalone) porque medição e gates pertencem à mesma preocupação de qualidade de código. Desmarque no seletor interativo (exclude: [code-metrics]) se não precisar.

Por que algumas coisas não estão aqui

• debug, implement, respond-to-review — estão no starter. O quality audita resultados; o starter os produz.
• audit-pii — caberia, mas ainda não existe como skill. Uma adição futura potencial se o tratamento de PII virar um alvo de auditoria frequente.

Workflow que isso habilita

Um PR típico pronto para merge:

1. Você termina uma feature e dá push na sua branch.
2. Antes de abrir o PR, você roda /octopus:audit-all localmente. A skill dispara as quatro auditorias em paralelo contra o diff e então produz um relatório consolidado com severidades: ⛔ block, ⚠ warn, ℹ info. Hotspots cross-audit (arquivos que dispararam achados em múltiplas auditorias) são destacados.
3. Se a mudança toca contratos de API, o audit-contracts inspeciona o diff em busca de drift de DTO / endpoint / enum / status-code entre o backend e o frontend, indo além do que as auditorias por stack cobrem.
4. Periodicamente (trimestralmente), você roda /octopus:audit-config para capturar drift de configuração — suposições de modelo obsoletas, skills fantasmas, paths deprecados.
5. Quando a superfície de auditoria exigir julgamento humano, você usa /octopus:delegate @architect para percorrer os achados e classificá-los — ou /octopus:delegate @security para um passe de threat model quando o diff toca auth ou secrets.

Ajuste fino do quality

quality é o bundle completo de qualidade de código. Se você quiser apenas um subconjunto, use o seletor interativo (desmarque membros → exclude:) em vez de escolher um sub-bundle. Por exemplo, para rodar apenas os gates bloqueantes, mantenha audit-all e audit-contracts e desmarque as skills signal-only.

Operações de knowledge base (knowledge-hygiene/synthesize/briefing) ficam no bundle separado knowledge. Auditoria cross-repo + fleet bootstrap ficam no tech-lead.

Compõe com

• starter — fundação obrigatória (provê implement, debug, respond-to-review que produzem o código a ser auditado).
• docs — combina naturalmente. Achados de auditoria muitas vezes viram ADRs (decisões registradas para a próxima vez) ou itens de backlog.
• backend — combina naturalmente. A maior parte do código auditável (money, multi-tenant, auth) vive em repos de backend.