Impl: Corrigir mapa de modelos e launch do worktree CLI (follow-up OPS93)

Status: rascunho Atualizado em: 2026-08-24 Issue: #876 Intenção: docs/plans/worktree-flags-modelo-correcao.md Appetite restante: ~0,5 dia (herdado)

Leitura da intenção

Outcome: pnpm worktree next/plan/new volta a abrir o TUI sozinho (--variant sai da diretiva — o yargs do TUI rejeita o flag desconhecido) e as 5 flags apontam para o mapa de modelos corrigido; as superfícies que citam o mapa/diretiva saem sincronizadas na mesma entrega; sem flag, preset deepseek/deepseek-v4-flash intacto.
O que NÃO negociar: cardápio fechado de 5 flags (--cheap|--pro|--zen|--go|--alibaba, mesmas chaves); preset sem flag; sem persistência de preferência; sem tocar /work-issue/plan-issue; sem editar config global de variantes da máquina via repo; fora do terminal interativo (TEQO_WORKTREE_TERMINAL≠1) as flags continuam irrelevantes.
O que reavaliar: hipótese de direção confirmada linha a linha pelo explorador (ver abaixo). O mapa-alvo não estava registrado por escrito em nenhum artefato acessível (#876/#859, planos OPS93) — foi fornecido e travado pelo humano no GATE desta entrega; tabela na decisão 2 abaixo.

Estado atual verificado (explorador)

scripts/lib/worktree.mjs: mapa L43-49 (cheap=cheapestinference/deepseek-v4-flash, pro=opencode-go/qwen3.7-max, zen=opencode-go/ox-alpha-free, go=opencode-go/mimo-v2.5, alibaba=alibaba-token-plan/qwen3.7-max); WORKTREE_VARIANT='max' L54-55; docblocks L40-41 e L171-177 citam --variant max; erro de conflito lista flags L66; diretiva monta [dir,'--model',selectedModel,'--variant',WORKTREE_VARIANT,'--auto'] em L198; preset L34-35 (deepseek/deepseek-v4-flash, override OPENCODE_WORKTREE_MODEL).
scripts/worktree.mjs: importa WORKTREE_VARIANT (bloco L147-156); consumo via resolveLaunchModel L169-176 → printLaunchDirective L178-189; docblock/help citam mapa+variant em L22-29, L33-34, L39, L73, L88, L809, L811, L821, L824, L830, L842, L850; resquício: help L101 ainda diz "--go é no-op" (OPS24 — stale desde o remapeamento do OPS93).
.agents/shell/worktree.sh: L10, L15-19 (mapa + --variant max), L50 (--go mimo-v2.5).
.opencode/commands/worktree.md: L7 (mapa + "--variant max sempre"), L12 (diretiva com variant).
.agents/skills/worktree-next-issue/SKILL.md: L32, L34. .agents/skills/local-database/SKILL.md: L29.
tests/unit/worktree.unit.spec.ts: pins L160-218 (~10 expects com '--variant ${WORKTREE_VARIANT}' embutido), L195-204 (expect(WORKTREE_VARIANT).toBe('max')), L234-241 (toEqual do mapa), L251-256 (flags), L267-282 (diretiva por flag).
Consumidores do mapa: único resolveWorktreeModel (lib L62-71) ← scripts/worktree.mjs:172. Nada exporta WORKTREE_VARIANT para env/shell. tests/unit/opencodeCommands.unit.spec.ts não é afetado (anti-goal — não mexer).
Blast radius: scripts/worktree.mjs está em HIGH_RISK_EXACT (scripts/lib/test-affected-core.mjs:36; pin espelho tests/unit/testAffected.unit.spec.ts:28) → diff nele = unit/int full + e2e curado no PR. scripts/lib/worktree.mjs NÃO é high-risk.
Catálogo local (explorador): opencode-go tem ox-alpha-free ✓ qwen3.7-max ✓ mimo-v2.5 ✓; alibaba-token-plan tem qwen3.7-max ✓; cheapestinference serve modelos pela config da máquina (deepseek-v4-flash, mimo-v2.5); não existe provider opencode-zen (gate da intenção confirmou --zen → opencode-go/ox-alpha-free — igual ao atual).

Abordagem recomendada

flowchart LR
  PINS["tests/unit/worktree.unit.spec.ts\npins novos (sem variant, mapa GATE)"] --> LIB["scripts/lib/worktree.mjs\nmapa values + remove WORKTREE_VARIANT\ndiretiva L198 sem --variant"]  LIB --> CLI["scripts/worktree.mjs\nimport/help/docblock"]
  CLI --> SURF[".agents/shell/worktree.sh\n.opencode/commands/worktree.md\n2 skills"]
  SURF --> GATES["pnpm test:unit -t worktree\npnpm gate:fast\nsmoke terminal"]

Opções consideradas: A | B | C Recomendação: A — remoção incondicional de --variant/WORKTREE_VARIANT + troca dos values do mapa existente; assinaturas (resolveWorktreeModel, opencodeLaunchDirective({dir,purpose,terminal,issueNumber,model})), chaves de flags e preset intactos; 7 superfícies de texto sincronizadas num único lote. Cabe no appetite (~2 arquivos de lógica + 5 de doc/skill + 1 spec), não cria módulo novo (depth check: o dono do concern já existe), e a diretiva volta ao formato que o TUI aceita.

Rejeitadas:

B — emitir --variant condicionalmente (só quando o modelo expuser variante): reintroduz o conceito que caiu com a premissa falsa do OPS93; exigiria catálogo de variants no repo (anti-goal: config global é assunto da máquina, OPS78/OPS89) e complexidade sem pedido. O "effort max" morre junto com a premissão — variantes seguem selecionáveis via Ctrl+T no TUI e --variant max segue vivo só no opencode run headless.
C — reescrever a resolução de modelo (nova função/módulo para o mapa): twinning do resolveWorktreeModel/WORKTREE_MODEL_MAP existentes; rejeitada — editar o dono do concern, não criar paralelo.

Decisões de engenharia (com rejeitadas)

Remoção incondicional do --variant na diretiva do TUI
- Opções: A) remover sempre | B) condicional ao modelo | C) mover variante para config do repo.
- Recomendação: A — a quebra é incondicional (o TUI nunca aceita --variant); B/C reabrem o laboratório de variantes cortado pela intenção (rabbit hole nomeado).
- Forma: args volta a [dir,'--model',selectedModel,'--auto'] (+ --prompt quando houver); constante WORKTREE_VARIANT eliminada (export + import em scripts/worktree.mjs + todos os pins).

Mapa-alvo (confirmado pelo humano no GATE de 2026-08-24; IDs validados contra o catálogo local)

Flag	Valor atual (OPS93 entregue)	Alvo (GATE)
`--cheap`	`cheapestinference/deepseek-v4-flash`	`cheapestinference/deepseek-v4-flash` (mantém)
`--pro`	`opencode-go/qwen3.7-max`	`deepseek/deepseek-v4-pro`
`--zen`	`opencode-go/ox-alpha-free`	`opencode-go/ox-alpha-free` (mantém)
`--go`	`opencode-go/mimo-v2.5`	`opencode-go/hy3`
`--alibaba`	`alibaba-token-plan/qwen3.7-max`	`alibaba-token-plan/deepseek-v4-flash`

Fecha a conta da intenção: três modelos corrigidos (--pro, --go, --alibaba) e um provider questionado (--pro: sai de opencode-go, vai ao provider deepseek); --cheap/--zen permanecem.
Restrição estrutural: só values mudam; chaves, WORKTREE_MODEL_FLAGS derivado e preset ficam intactos.
Validação de catálogo (feita): deepseek/deepseek-v4-pro ✓, opencode-go/hy3 ✓, alibaba-token-plan/deepseek-v4-flash ✓, cheapestinference/deepseek-v4-flash ✓ (config da máquina), opencode-go/ox-alpha-free ✓.

Sincronização das 7 superfícies + resquício do help
- As 7 da intenção: docblocks/mapa em scripts/lib/worktree.mjs, docblock/help em scripts/worktree.mjs, .agents/shell/worktree.sh, .opencode/commands/worktree.md, .agents/skills/worktree-next-issue/SKILL.md, .agents/skills/local-database/SKILL.md, pins de teste.
- Inclui também o help L101 de scripts/worktree.mjs ("--go é no-op" — stale do OPS24 dentro do bloco de ajuda do kill): sai na mesma entrega porque é o mesmo contrato de mapa/divergência documental que a intenção manda encerrar (precedente OPS24: contrato documentado em todas as superfícies na mesma entrega). Textos citando --variant max/effort viram descrição do mapa sem variant; menção a variantes passa a apontar Ctrl+T/config global (fora do repo).
- .opencode/agent/designer-campanha-solla.md:64 e design-vision.md:15 citam opencode-go/mimo-v2.5 como fallback de visão — fora do escopo (não são parte do mapa/diretiva; nada quebra).

Componentes / mudanças

scripts/lib/worktree.mjs: values do WORKTREE_MODEL_MAP (tabela GATE); delete WORKTREE_VARIANT (L54-55); opencodeLaunchDirective L198 sem --variant; docblocks L40-41/L171-177 descrevendo o mapa novo e sem variant.
scripts/worktree.mjs: remover import/usos de WORKTREE_VARIANT; docblock (L22-39, L73, L88) e help (L809-850, incl. L101 do kill) atualizados.
.agents/shell/worktree.sh, .opencode/commands/worktree.md, 2 skills: textos espelhos do mesmo contrato.
tests/unit/worktree.unit.spec.ts: remover pins de WORKTREE_VARIANT/'--variant'; nova pinagem da diretiva (--model X --auto [--prompt …]) e do mapa GATE; suite de flags/exclusividade intacta em estrutura.
Migration: sem migration — tooling pura. Access/Consent: N/A. UI: Impeccable A — sem superfície de produto.

Fases verificáveis

Pins primeiro (TDD) — atualizar tests/unit/worktree.unit.spec.ts para o contrato-alvo (diretiva sem --variant, mapa GATE confirmado); rodar e ver vermelho. Quota ~25%.
Lib — scripts/lib/worktree.mjs: mapa + remoção do variant + docblocks; unit verde. Quota ~25%.
CLI + superfícies — scripts/worktree.mjs (import/help/docblock/incl. L101) + shell + command + 2 skills, num único lote de sincronização. Quota ~30%.
Gates + entrega — pnpm test:unit -t worktree; pnpm gate:fast; smoke TEQO_WORKTREE_TERMINAL=1 node scripts/worktree.mjs next --stay (diretiva impressa sem --variant, modelo do flag escolhido; múltiplas flags continua falhando alto); changelog NOVA entrada docs/changelog/<data>-ops95.md; pnpm push → PR Closes #876 (HIGH_RISK_EXACT dispara unit/int full + e2e curado no CI). Quota ~20%.

Rabbit holes / Não escopo (engenharia)

Reabrir o mapa além da tabela GATE (trocar --cheap/--zen, aceitar provider/model livre, cardápio novo).
Reintroduzir effort/variante por outra via (env por worktree, opencode.json do repo, config global via commit) — variantes vivem na máquina (Ctrl+T; opencode run --variant max para headless).
Mudar preset, chaves de flags, prompts ou pins de tests/unit/opencodeCommands.unit.spec.ts.
Editar planos/changelog históricos (OPS93 imutável; entrada nova em docs/changelog/).
Estender o cardápio ou aceitar provider/model livre.
.opencode/agent/designer-campanha-solla.md e design-vision.md citam opencode-go/mimo-v2.5 como fallback de visão (fora do mapa/diretiva; nada quebra). Deferido com gatilho: atualizar na próxima troca de mapa de modelos ou edição desses docs (mesma classe de drift texto↔código desta entrega).

Riscos e mitigação

HIGH_RISK_EXACT (scripts/worktree.mjs) → PR roda unit/int full + e2e curado; mitigação: tocar só import/docblock/help, sem provision/claim/PORT/env.
Divergência de contrato nas 7 superfícies de texto (+ resquício do help do kill) → mitigação: lote único (Fase 3) + grep final por --variant/WORKTREE_VARIANT/valores antigos do mapa zerando fora de histórico imutável.
Suíte herdar OPENCODE_WORKTREE_MODEL (presetInEffect() lê env) → mitigação: manter padrão existente do spec; rodar unit no ambiente limpo do gate.
ID do mapa GATE sumir do catálogo da máquina no futuro → mitigação: IDs validados hoje; smoke imprime a diretiva e o uso real falha alto/visível — se um provider mudar, vira correção futura, não commit de catálogo.

Aceite de engenharia

Aceite de produto coberto: TUI abre sozinho nas invocações com/sem flag; 5 flags → mapa corrigido; sem flag → preset; fora do terminal inalterado; 7 superfícies sincronizadas.
Invariantes: sem collection/migration/PII/Consent; identificadores em inglês; sem ciclo; editado o dono do concern (sem twin).
Testes: unit pins do mapa + diretiva (TDD); pnpm gate:fast verde; smoke de terminal registrado no PR.

Self-score decision-quality: 5/5 — decisões caras com rejeitadas (remoção incondicional; values-only; sync única); cabe no appetite; rabbit holes nomeados (inventar mapa é bloqueado pelo GATE); reusa WORKTREE_MODEL_MAP/resolveWorktreeModel/opencodeLaunchDirective sem twinning; outcome da intenção preservado.

12 KiB Raw Blame History