Lab x User surface parity (hygiene)

Objetivo: evitar drift entre o que usamos no laboratório e o que distribuímos aos usuários.

Regra base

• Paridade por padrão: surface usada em operação recorrente no lab deve existir (ou ter equivalente) na distribuição para usuário.
• Exceção temporária: quando algo for lab-only, registrar motivo, prazo e critério de saída.

Inventário mínimo (snapshot)

Distribuído (user-facing)

• Extensões e tools da stack (packages/pi-stack/extensions/*)
• Scripts operacionais em package.json (ex.: ops:*, subagent:*, pi:artifact:*)
• Guias canônicos em docs/guides/*

Lab-only temporário

• Helpers ad-hoc de investigação em .sandbox/tmp (devem ser arquivados/removidos após uso)
• Utilitários de diagnóstico pontual sem contrato estável

Critério de promoção (lab-only -> canônico)

Promover para tool/comando/sinal quando o padrão ocorrer em 2+ ciclos operacionais e atender:

1. Entrada/saída determinística
2. Evidência auditável
3. Valor recorrente para operador

Critério de remoção

Remover/arquivar quando:

• uso foi pontual e não recorrente;
• já existe surface canônica equivalente;
• manutenção supera valor operacional.

Política de artefatos de pesquisa

Dados derivados e pequenos (results.json, scorecards e sínteses) podem ser versionados quando carregam evidência recorrente. Logs brutos, dumps completos e datasets grandes em docs/research/data/** devem ficar locais, externos ou promovidos para artefato de release/CI. O gate pnpm run repo:bloat:audit:strict bloqueia logs brutos versionados e datasets grandes antes que o histórico vire depósito de runtime. Para usuários da stack, o mesmo sinal aparece no comando /stack-quality e na tool stack_quality_audit.

Política de discurso canônico

Termos fortes como fábrica, engine, maturidade e soberania precisam refletir contrato operacional, gate ou roadmap explícito. Use pnpm run repo:discourse:audit como bússola advisory para encontrar linguagem legada (termos antigos para operador) e promessa aspiracional em docs/surfaces canônicas. O audit não bloqueia a release por padrão: ele ajuda a escolher a próxima lane de poda sem apagar pesquisa histórica nem forçar renomeação ampla.

Governança operacional

• Registrar no board (tasks/verification) quando uma exceção lab-only for criada ou encerrada.
• Não manter tool lab-only indefinidamente sem owner e prazo.
• Preferir converter padrão recorrente em sinal de operação (status/audit/tool estável) em vez de script ad-hoc permanente.

Sinal de cobertura first-party

Quando uma capability first-party passa a cobrir parte de uma extensão/skill third-party, isso deve aparecer em packages/pi-stack/extensions/data/capability-owners.json, não em uma memória paralela. O campo curationCoverage registra a superfície coberta, o pacote third-party, os arquivos filtrados e a estratégia: keep, suppress-by-filter, remove-from-profile ou needs-decision.

O sinal é avaliado por stack_sovereignty_status como curationCoverage. Ele deve mostrar:

• filtros aplicados pelo instalador para usuários, como mitsupi pi-extensions/uv.ts;
• overlaps que ainda dependem de decisão, como background process third-party enquanto a versão first-party ainda é planejamento;
• falhas de installability quando uma superfície marcada suppress-by-filter não tem filtro correspondente;
• oportunidades de reduzir dependências quando a cobertura first-party amadurece.

Regra: se a curadoria cobre uma superfície, ela precisa estar filtrada, removida do perfil, ou explicitamente justificada como decisão pendente.

Apresentação do Pi como superfície única

A experiência visível do Pi não deve ser tratada como uma coleção solta de plugins. A capability pi-session-presentation cobre o que o operador percebe como sessão: footer/status, headers, prompts automáticos, comandos, skills expostas, tema, painéis e integrações editor/worktree. Quando uma extensão third-party altera essa apresentação, a decisão deve passar por curationCoverage antes de virar baseline para usuários.

Inventário de slimming da superfície distribuída

Classificação atual da distribuição @aretw0/pi-stack:

Superfície	Classificação	Racional operacional
STRICT_CURATED / curated-default (@aretw0/* + @davidorex/pi-project-workflows)	keep	Uso recorrente, baixo custo cognitivo e contrato canônico para board/workflows/monitors. É o baseline oficial de instalação.
RUNTIME_CAPABILITY_EXTRAS (@ifi/oh-pi-extensions, @ifi/oh-pi-ant-colony, @ifi/pi-web-remote)	keep opt-in	Alto valor para long-run/control-plane, mas exige intenção explícita; não entra no caminho simples por padrão.
stack-full / demais third-party (mitsupi, pi-lens, pi-web-access, @ifi/pi-* auxiliares)	deprecate-by-default	Úteis para laboratório/compatibilidade, mas com maior custo de superfície e risco de overlap; ficam disponíveis apenas por perfil explícito.
Scripts ad-hoc e diagnósticos pontuais (.sandbox/tmp, helpers temporários)	docs-only ou remove/archive	Promover só após 2+ ciclos operacionais com entrada/saída determinística e evidência; caso contrário arquivar/remover e deixar runbook curto.

Política aplicada: o instalador usa strict-curated como default; capacidades avançadas ficam em curated-runtime/stack-full por opt-in. Assim, ferramentas calibradas sem uso recorrente não são removidas do repositório quando ainda servem ao laboratório, mas ficam desligadas da distribuição simples e documentadas como exceção/compatibilidade.

Distribuição outcome-agnostic (simple-first)

Para evitar que a stack pareça “só para operações avançadas”:

• agnóstica de outcome: o pacote distribuído deve servir tanto fluxos simples (manual) quanto fábrica contínua (control-plane + board + intents), sem impor modo único;
• progressive disclosure: default de uso simples primeiro; superfícies avançadas entram por opt-in e com runbook curto;
• mesmo contrato, diferentes níveis: o que habilita fábrica não deve quebrar quem só quer execução direta por prompt/comando básico;
• linguagem de onboarding: docs e status devem explicar “você pode começar simples e evoluir para fábrica quando quiser”, evitando acoplamento mental imediato a governança pesada.