teqo-backup/docs/plans/worktree-modelos-space-bunny-impl.md

Impl: Modelos das flags do worktree: --zen → Space Bunny Free e --free → Space Bunny Alpha

Status: em execução Atualizado em: 2026-09-25 Issue: #1342 Intenção: docs/plans/worktree-modelos-space-bunny.md Appetite restante: herdado (~0,5 dia)

Leitura da intenção

• Outcome: next, plan, new e fix devem abrir Space Bunny Free pelo OpenCode Zen com --zen e Space Bunny Alpha pelo OpenRouter com --free; código, ajuda, comandos, skills e pin unitário que apresentam o mapa exibem a mesma associação.
• O que NÃO negociar: zen: 'opencode/space-bunny-free' e free: 'openrouter/stealth/space-bunny-alpha'; preset sem flag, demais flags, fail-high para múltiplas flags e MODEL_VARIANT = 'max' permanecem intactos. Não criar aliases, fallback, seletor, nova flag, mapa paralelo, persistência, migration, schema, UI ou alterações em registros históricos.
• O que reavaliar: nenhuma hipótese de produto precisa ser reaberta. O owner, o transporte compartilhado por todos os propósitos e a ajuda derivada foram confirmados. Só reavaliar a sincronização manual se uma futura evolução exigir gerar documentação do mapa ou surgir outra superfície viva exibindo seus valores.

Abordagem recomendada

flowchart TD
  A[Pin unitário: trocar os dois literais esperados] --> B[Teste direcionado: RED]
  B --> C[Atualizar os dois valores em WORKTREE_MODEL_MAP]
  C --> D[Atualizar o docblock stale do owner]
  D --> E[Teste direcionado: GREEN]
  E --> F[Sincronizar CLI, shell, comando e skill]
  F --> G[Auditar as superfícies vivas do mapa]
  G --> H[Smoke da ajuda sem provisionamento]
  H --> I[pnpm gate:fast]
  I --> J[Novo changelog OPS129]
  J --> K[pnpm push e gates high-risk completos]

Opções consideradas: A | B | C

• A — Alterar os dois valores no owner, usar o pin unitário existente no fluxo RED/GREEN e sincronizar manualmente as superfícies documentais.
• B — Extrair ou gerar toda a documentação do mapa a partir de WORKTREE_MODEL_MAP.
• C — Introduzir aliases, um segundo mapa ou uma camada de compatibilidade entre os IDs antigos e novos.

Recomendação: A — porque o problema já tem um owner profundo e um pin exato; duas trocas de strings são o tracer bullet completo, preservam o contrato e cabem no appetite sem criar mecanismo novo. A ajuda já deriva do mapa, enquanto shell, comando e skill precisam apenas receber a associação vigente no mesmo lote.

Rejeitadas: B — porque transformaria uma troca values-only em refatoração de geração de documentação, ampliaria o risco de formato e manutenção e violaria o limite de um único mapa owner; C — porque preservaria os IDs antigos como semântica de runtime, criaria uma segunda política de escolha e contrariaria a troca direta aprovada. A decisão de manter sincronização manual só deve ser revista se surgirem novas superfícies vivas ou uma necessidade concreta de gerar documentação do mapa.

Decisões de engenharia

• Ownership: editar WORKTREE_MODEL_MAP; não introduzir constantes por provider, aliases ou exceções por propósito.
• TDD: alterar primeiro apenas o toEqual do pin existente e observar a falha causada pelos valores antigos; só depois mudar o owner.
• Resolução: reutilizar resolveWorktreeModel, WORKTREE_MODEL_FLAGS e o allowlist existentes. next, plan, new e fix já compartilham a resolução e o transporte; fix não ganha caminho especial.
• Documentação viva: sincronizar somente onde os IDs são exibidos. A ajuda de scripts/worktree.mjs:992-996 já deriva do owner e não recebe literal duplicado.
• Transporte: não alterar parseModelRef nem MODEL_VARIANT. O parser divide no primeiro slash, portanto openrouter/stealth/space-bunny-alpha chega como provider openrouter e id stealth/space-bunny-alpha.
• Histórico: acrescentar proveniência da OPS129 onde houver notas vivas, sem reescrever os registros de OPS100/OPS112 ou planos antigos.

Componentes / mudanças

• WORKTREE_MODEL_MAP (scripts/lib/worktree.mjs:43-63): trocar somente os valores zen e free; atualizar o docblock stale que ainda identifica --zen como Muse Spark 1.3 Free. Chaves, ordem, WORKTREE_MODEL_FLAGS, resolveWorktreeModel, preset e demais modelos permanecem iguais.
• Docblock e ajuda do CLI (scripts/worktree.mjs:22-30, scripts/worktree.mjs:973-1003): atualizar os dois IDs no docblock e a proveniência viva. Não editar a interpolação da ajuda, que já mostra WORKTREE_MODEL_MAP automaticamente.
• Launcher shell (.agents/shell/worktree.sh:23-28): atualizar a associação de --zen e --free; preservar as linhas de uso que já listam apenas as flags. Acrescentar OPS129 à nota de proveniência sem apagar OPS100/OPS112.
• Comando /worktree (.opencode/commands/worktree.md:7): atualizar os dois IDs e manter at-most-one e os contratos de cd/launch intactos.
• Skill do worktree (.agents/skills/worktree-next-issue/SKILL.md:32-34): atualizar apenas os IDs e a proveniência na linha 34. A linha 32, que lista flags sem IDs, não precisa mudar.
• Pin unitário (tests/unit/worktree.unit.spec.ts:469-523): primeiro mudar os dois valores esperados; manter intactas as provas de flag set, preset, resolução individual, fail-high e diretivas de next/plan/new.
• Registro da entrega (docs/changelog/2026-09-25-ops129.md): criar uma entrada curta nova com os dois remaps e as invariantes preservadas; não alterar changelogs anteriores nem o agregado gerado.
• Transporte fora da mudança (scripts/lib/agent-session.mjs, tests/unit/agentSession.unit.spec.ts): não editar. Os exemplos genéricos de ref com slash e a cobertura de parseModelRef não apresentam o mapa; MODEL_VARIANT continua max.
• Migration: sem migration; não há schema ou Payload.
• Access / Consent: N/A; não há collection, write path, role, helper ou chave LGPD.
• UI: Impeccable A — N/A, sem UI; nenhum designer, shell visual, shape, craft ou polish.
• Codebase map: sem mudança; nenhum módulo muda de camada ou de owner.

Dados → forma

• N/A como visualização: não há métrica, série ou comparação para o usuário.
• A forma técnica escolhida é o dicionário fixo flag → model reference já existente. Os valores novos são configuração executável, não conteúdo duplicado de catálogo; somente as superfícies vivas que exibem o mapa recebem a nova associação textual.

Fases verificáveis

1. TDD RED — 20 min

   • Em tests/unit/worktree.unit.spec.ts, alterar primeiro apenas WORKTREE_MODEL_MAP.zen e WORKTREE_MODEL_MAP.free no toEqual para os literais novos.
   • Executar pnpm test:unit tests/unit/worktree.unit.spec.ts.
   • Confirmar RED por divergência entre os literais esperados e os antigos no owner. Não alterar owner nem documentação antes de registrar essa falha.

2. Owner e GREEN — 30 min

   • Trocar em scripts/lib/worktree.mjs somente os dois valores do mapa.
   • Atualizar o comentário stale imediatamente acima do mapa para Space Bunny Free e Space Bunny Alpha, preservando a proveniência histórica relevante.
   • Não modificar WORKTREE_MODEL_FLAGS, resolveWorktreeModel, as outras cinco entradas, o preset ou MODEL_VARIANT.
   • Reexecutar pnpm test:unit tests/unit/worktree.unit.spec.ts e confirmar GREEN, incluindo as invariantes existentes de preset, fail-high e transporte.

3. Sincronização das superfícies vivas — 45 min

   • Atualizar os IDs no docblock de scripts/worktree.mjs, shell, comando e skill.
   • Manter a ajuda de runtime derivada do mapa; confirmar por inspeção que ela não contém literal próprio.
   • Fazer busca exata dos IDs antigos apenas nos seis arquivos vivos que apresentam o mapa, confirmando que não sobrou associação antiga.
   • Permitir IDs antigos apenas onde são semanticamente corretos: registro histórico, intenção atual, exemplos genéricos de parser e este plano. Não editar agent-session.mjs, seu teste, codebase-map, local-database ou documentos históricos.

4. Smoke e gates — 1 h 15 min

   • Reexecutar pnpm test:unit tests/unit/worktree.unit.spec.ts.
   • Executar node scripts/worktree.mjs sem subcomando e validar a saída de uso, conferindo --zen=opencode/space-bunny-free e --free=openrouter/stealth/space-bunny-alpha sem provisionar worktree ou banco.
   • Executar pnpm gate:fast para lint, typecheck e unit completo.
   • Não criar teste e2e: a mudança não introduz fluxo visual nem integração de aplicação. Os arquivos scripts/worktree.mjs e scripts/lib/worktree.mjs são high-risk; o push deve respeitar a expansão automática para unit/int full e e2e curado, sem editar manifest nem tentar seleção vazia.

5. Changelog e push — 1 h

   • Criar somente docs/changelog/2026-09-25-ops129.md; não rodar pnpm changelog:build nem commitar o agregado.
   • Rodar pnpm changelog:check e revisar o diff para confirmar que contém apenas o plano, o pin, o owner, as superfícies vivas, a nova entrada e os ajustes documentais necessários.
   • Entregar com pnpm push -u origin HEAD; registrar o resultado dos gates high-risk completos.
   • Abrir PR Ready para main com Closes #1342 e deixar o auto-merge nativo aguardar CI (PR) / checks.

Rabbit holes / Não escopo (engenharia)

• Não criar WORKTREE_MODEL_MAP paralelo, mapa por provider, aliases, fallback, seletor, variável de ambiente nova ou persistência da escolha.
• Não renomear --zen/--free, adicionar flag, alterar precedência, allowlist ou comportamento para múltiplas flags.
• Não alterar cheap, pro, go, alibaba ou glm, nem revisar o restante do catálogo.
• Não alterar MODEL_VARIANT, parseModelRef, buildCreateSessionBody, ciclo de sessão ou o transporte de headless.
• Não criar caminho especial para fix; allowlist e cmdNamespaceBranch já o levam ao mesmo launchModel.
• Não substituir exemplos genéricos de slash em agent-session.mjs; eles não exibem o mapa e sua troca seria ruído documental.
• Não reescrever docs/plans/worktree-modelos-go-zen.md, docs/plans/worktree-launch-honra-flags.md, docs/changelog/2026-09-15-ops112.md, docs/changelog/2026-08-27-ops100.md ou a intenção desta Issue.
• Não adicionar migration, schema, access, Consent, UI, componente, utility, módulo ou abstração.
• Não atualizar codebase-map, manifests de risco ou skills que apenas enumeram flags sem IDs.
• Não provisionar worktrees reais para o smoke; isso criaria branch, bancos e efeitos externos sem benefício para uma troca de constantes.
• Não adicionar e2e específico; unit puro, ajuda e gates existentes cobrem a mudança com menor acoplamento.

Riscos e mitigação

• Documentação viva divergir: limitar a edição às quatro superfícies listadas, atualizar a ajuda por derivação e fazer busca exata nos arquivos-alvo após o lote.
• Busca ampla sinalizar falsos positivos: IDs antigos continuarão legitimamente em histórico, intenção e exemplos genéricos de parser; avaliar o contexto, não exigir zero ocorrências no repositório inteiro.
• Ref com slash adicional em --free: parseModelRef divide no primeiro slash e preserva stealth/space-bunny-alpha como id; o pin e a cobertura genérica existente verificam a associação e a capacidade do parser.
• Regressão em max ou demais flags: não tocar no transporte e preservar o toEqual completo das sete entradas e as asserções existentes de preset/fail-high.
• fix ficar sem prova direta no pin de diretiva: a allowlist já inclui fix, e plan/new/fix usam o mesmo cmdNamespaceBranch, resolveLaunchModel e printLaunchDirective; não criar branch de código apenas para duplicar essa prova.
• Classificação high-risk ampliar tempo ou suites: aceitar o cascade oficial, sem bypass, seleção vazia ou alteração do manifest; o push deve produzir full unit/int e e2e curado.
• Mudança parecer maior que values-only: limitar o diff aos literais e à sincronização documental; qualquer novo mecanismo exige revisão da decisão e não cabe nesta entrega.

Aceite de engenharia

• WORKTREE_MODEL_MAP.zen === 'opencode/space-bunny-free'.
• WORKTREE_MODEL_MAP.free === 'openrouter/stealth/space-bunny-alpha'.
• next, plan, new e fix aceitam --zen e --free pelo mesmo resolveWorktreeModel e transportam o valor resolvido.
• Space Bunny Free é associado ao provider opencode/OpenCode Zen e Space Bunny Alpha ao provider openrouter/OpenRouter.
• A ajuda de node scripts/worktree.mjs mostra os dois novos valores sem provisionamento.
• Docblock do CLI, shell, comando e skill não exibem os IDs antigos como associação vigente.
• O pin unitário foi alterado primeiro, houve RED e depois GREEN.
• Preset sem flag, outras cinco flags e a lista de flags permanecem idênticos.
• Múltiplas flags continuam falhando alto sem adivinhação.
• MODEL_VARIANT continua max; nenhum transporte foi alterado.
• Planos, changelogs antigos e exemplos genéricos de parser não foram reescritos.
• Nenhum mapa paralelo, alias, fallback, seletor, flag, persistência, migration, schema, access, Consent ou UI foi criado.
• pnpm test:unit tests/unit/worktree.unit.spec.ts e pnpm gate:fast estão verdes.
• O smoke da ajuda confirma os dois valores sem efeitos externos.
• O push respeita a classificação high-risk e registra unit/int full e e2e curado.
• A nova entrada docs/changelog/2026-09-25-ops129.md está incluída sem modificar o agregado.
• Nenhum manifest ou codebase map foi alterado sem necessidade arquitetural.

Self-score decision-quality: 5/5 — as alternativas e rejeições preservam o owner único, a escolha cabe no appetite values-only, os rabbit holes e a busca distinguem superfície viva de histórico, o mecanismo profundo existente é reutilizado e o aceite mantém literalmente as duas associações e todas as invariantes para os quatro comandos.