ganbatte-os 0.2.32 → 0.2.34

package/.gos/skills/execute-plan/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: execute-plan
+description: Executa um plano (PLAN-NNN-<slug>) task-a-task aplicando state machine + visual gate contra Storybook canonico antes de marcar validacao. Comando primario do ambiente Codex IDE.
+argument-hint: "<PLAN-NNN-slug> [--task T-NNN-NN] [--skip-visual-gate]"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, Agent, AskUserQuestion]
+sourceDocs:
+  - templates/taskTemplate.md
+  - playbooks/plan-creation-playbook.md
+  - skills/figma-implement-design/SKILL.md
+  - skills/plan-blueprint/SKILL.md
+use-when:
+  - executar plano ja criado por *plan
+  - rodar tasks de um PLAN-NNN com state machine e visual gate
+  - ambiente Codex IDE Extension (comando primario)
+do-not-use-for:
+  - criar plano novo (use plan-blueprint)
+  - decompor plano em tasks (use plan-to-tasks)
+  - gerenciar progress.txt isoladamente (use progress-tracker)
+metadata:
+  category: execution
+---
+
+Voce esta executando como **Executor de Planos** via skill `execute-plan`. No ambiente Codex IDE Extension este e o comando primario do ciclo `Opus(plan) -> Codex(execute)`.
+
+## Input
+
+$ARGUMENTS
+
+Formato esperado:
+- `<PLAN-NNN-slug>` — id do plano (ex.: `PLAN-001-pagina-projetos-inicial`)
+- `--task T-NNN-NN` — opcional, executa apenas a task especifica
+- `--skip-visual-gate` — opcional, pula visual gate (raro, registra warning)
+
+## Pre-requisitos (gate)
+
+1. Resolver paths via `.gos-local/plan-paths.json`. Se ausente, abortar e instruir o usuario a rodar `*plan` primeiro.
+2. Localizar `<dirs.planos>/<PLAN-NNN-slug>/plan.md`. Se ausente, abortar.
+3. Ler `plan.md` por completo: frontmatter + Componentes mapeados + Componentes ausentes + Aderencia a stack + Plano de execucao + Checklist de aceite.
+4. Validar `stack_ref` do frontmatter contra `<dirs.stack>` (`docs/stack.md`):
+   - Calcular sha-curto atual e comparar.
+   - Drift detectado: ABORTAR e instruir `*stack drift` + replanejar com `*stack refresh`.
+5. Ler `<dirs.progress>` (progress.txt). Se aponta para outro plano ativo, perguntar se troca o foco antes de prosseguir.
+
+## Pre-flight visual
+
+(Pulado quando `--skip-visual-gate` presente — registrar warning em `tasks/T-NNN-NN.notes.md` da primeira task.)
+
+1. Resolver `<dirs.storybook>` via `plan-paths.json`. Path absoluto fora do repo do projeto e valido (ex.: `E:\Github\Ganbatte\tmp\fractus-storybook`).
+2. Indexar todos `.stories.tsx` disponiveis em `<dirs.stories>` ou `<dirs.components>`.
+3. Para cada linha da tabela "Componentes mapeados" do plano:
+   - Confirmar que a coluna `Story (path)` aponta para arquivo existente.
+   - Se ausente: gerar task de criacao do componente ANTES das tasks de implementacao. Renumerar `seq` das tasks restantes.
+4. Output do pre-flight: bloco em `progress.txt` campo `notes=` com numero de stories indexadas e tasks de criacao geradas.
+
+## Loop por task
+
+Iterar tasks em ordem de `seq`. Para cada `tasks/T-NNN-NN-*.md`:
+
+1. **Mover para em-andamento**: `*progress status T-NNN-NN em-andamento`. State machine valida transicao.
+2. **Despachar agent**: ler `labels: [agent:<slug>]` da task. Default: `dev`. Invocar via Agent tool com prompt completo (objetivo, plano de execucao, DoD, paths relevantes).
+3. **Implementacao**: agent edita arquivos seguindo o plano de execucao da task. Stack como contrato — nada fora de `docs/stack.md` salvo se `arch_change=true` no frontmatter do plano pai.
+4. **Visual gate** (antes de propor `validacao`):
+
+   Para cada componente alterado/criado pela task:
+
+   a) Localizar `<Componente>.stories.tsx` em `<dirs.storybook>`.
+   b) Comparar implementacao vs story canonica em 4 dimensoes textuais:
+      - **Anatomia**: ordem de slots/elementos (header -> corpo -> footer; icones esquerda/direita; campos do form na ordem do design).
+      - **Tokens**: classes Tailwind/variaveis CSS batem com DS (cor, raio, espacamento, tipografia).
+      - **Variants**: props expostos cobrem variants da story.
+      - **Densidade**: padding/gap dentro de +-1 step da escala do DS.
+   c) Para a tela como um todo: invocar Figma MCP no `figma_url` do plano e cruzar com o JSX renderizado em arvore (mesmo numero de secoes, mesma hierarquia, mesmas labels).
+   d) Output: relatorio curto em `tasks/T-NNN-NN.notes.md` (4 secoes: anatomia, tokens, variants, densidade + secao "Arvore vs Figma").
+   e) Divergencia >= 1 item critico (anatomia ou tokens) -> falha o gate.
+
+5. **Resultado do gate**:
+   - Sucesso -> `*progress status T-NNN-NN validacao`. Preparar arquivos staged (sem commit).
+   - Falha -> manter em `em-andamento`, gravar diff em `T-NNN-NN.notes.md`, retornar pra etapa 3.
+
+## Fechamento
+
+Quando todas as tasks atingirem `validacao` E o checklist de aceite do plano estiver marcado:
+
+1. Listar arquivos modificados via `git diff --name-only`.
+2. Preparar commit (NAO push). Mensagem segue Conventional Commits + referencia ao `PLAN-NNN-slug`.
+3. Resumo final ao usuario:
+   - Path do plano + numero de tasks concluidas.
+   - Lista de componentes que passaram/falharam o visual gate.
+   - Comando exato para o humano marcar `concluido`: `*progress status T-NNN-NN concluido` (apos validacao humana + smoke E2E).
+
+## Ambiente Codex IDE — observacoes
+
+- O usuario invoca `*execute-plan` direto no Codex. A skill carrega via wrapper em `.codex/skills/gos-execute-plan/SKILL.md`.
+- Toda chamada a outros agents/skills do G-OS dentro do execute-plan deve usar o adapter Codex correspondente (`.codex/agents/`, `.codex/commands/`).
+- Se a chamada cair pra outro adapter (Claude/Qwen/etc) a sessao quebra — abortar com mensagem clara.
+
+## Regras criticas
+
+- **Visual gate nao e opcional** salvo `--skip-visual-gate` explicito. Skill nao silencia o gate.
+- **Sem push automatico**: commit fica preparado. Push e responsabilidade do humano.
+- **State machine inviolavel**: transicao `concluido` so apos humano validar + checklist.
+- **Storybook como contrato**: componente sem `.stories.tsx` em `<dirs.storybook>` bloqueia a task ate ser criado.
+
+## Model guidance
+
+| Escopo | Modelo |
+|--------|--------|
+| Task simples (1 componente, sem novo padrao) | `sonnet` |
+| Task que toca multiplos componentes ou logica de fetching | `opus` |
+| Visual gate / comparacao com Figma | inherit (modelo do agent) |
+
+## Instructions
+
+1. NUNCA pular o pre-flight visual sem flag explicita.
+2. Resolver TODOS os paths via `plan-paths.json`.
+3. Visual gate produz relatorio em `T-NNN-NN.notes.md` mesmo em caso de sucesso.
+4. Status final esperado: todas as tasks em `validacao`, commit preparado, humano notificado.

package/.gos/skills/plan-blueprint/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plan-blueprint
 description: Cria um plano padronizado para uma tela (1 plano = 1 tela) seguindo a stack-of-record do projeto. Produz {plano, tasks, contexto, entrada-progress.txt} em três fases (Mapeamento → Aderência à stack → Execução). Pré-requisito duro: docs/stack.md existir. Subdivide automaticamente telas com seções autônomas múltiplas.
-argument-hint: "<tela|figma-url|descrição> [--from-figma-mcp] [--allow-arch-change]"
+argument-hint: "<tela> OBJETIVO=<implantacao|correcao|refactor> FIGMA=<url> [FIGMA+=...] [--from-figma-mcp] [--allow-arch-change] [--skip-clickup]"
 allowedTools: [Read, Glob, Grep, Bash, Write, Edit, Agent, AskUserQuestion]
 sourceDocs:
   - templates/planTemplate.md
@@ -25,14 +25,35 @@ Você está executando como **Tech Lead Frontend / Arquiteto Sênior** via skill
 
 $ARGUMENTS
 
-Auto-detecção de input:
-- URL `https://www.figma.com/...` → ativa modo Figma MCP
-- caminho de arquivo `.md`/`.png`/`.jpg` → modo descrição com referência visual
-- texto livre → modo descrição
+Campos obrigatórios no prompt:
+- `OBJETIVO` — `implantacao` | `correcao` | `refactor`
+- `FIGMA` — URL do frame principal (auto-ativa Figma MCP)
+
+Opcionais:
+- `FIGMA+` — lista de URLs de componentes
+- `NOTAS` — prosa livre (comportamento, edge cases, invioláveis)
+- `ASSIGNEE` — override do user_id ClickUp para tasks de backend (default: 112010775)
+
+Auto-resolvido pelo `gos-master` (comprehension gate, NÃO pedir ao usuário):
+- `PROJETO` — `cwd`; ambíguo → `~/.claude/.gos-state/last-project.json`
+- `WORK_BRANCH` — tela em Storybook → `feat/storybook`; senão → `dev`
+- `STORYBOOK_DIR/BRANCH` — `plan-paths.json`
+- `BUSINESS_RULES` — `<PROJETO>/docs/regras-de-negocio/` (indexar e registrar em progress.txt)
+- `POSTMAN` — `<PROJETO>/docs/postman/` (idem)
+- `BACKEND/RLS/SEED/SMOKE_E2E` — derivado de `stack.md` + regras + Postman
+
+OBJETIVO muda postura:
+
+| Valor | Comportamento |
+|-------|---------------|
+| `implantacao` | Cria do zero — Fase 1 → 2 → 3 padrão |
+| `correcao` | Modo cirúrgico — diff vs Storybook canônico, 1 task por componente, sem reescrever |
+| `refactor` | Implica `--allow-arch-change` + ADR obrigatória |
 
 Flags:
-- `--from-figma-mcp` — força leitura via Figma MCP
-- `--allow-arch-change` — libera Fase 2 propositiva (gera ADR)
+- `--from-figma-mcp` — força leitura via Figma MCP (default quando `FIGMA=` é Figma URL)
+- `--allow-arch-change` — libera Fase 2 propositiva (gera ADR); implícito em `OBJETIVO=refactor`
+- `--skip-clickup` — não cria tasks de backend automaticamente
 
 ## Pré-requisitos (gate)
 
@@ -41,6 +62,9 @@ Flags:
    - Se ausente: ABORTAR. Despachar `stack-profiler refresh` e instruir o usuário a re-executar.
    - Se presente: ler integralmente. Verificar drift via `*stack drift` antes de prosseguir.
 3. Ler `progress.txt` se existir (memória L1).
+4. **Verificar `dirs.storybook`** (caminho do `plan-paths.json`):
+   - Se ausente OU diretório não existe: ABORTAR. Pedir caminho ao usuário (path absoluto fora do repo é válido, ex.: `E:\Github\Ganbatte\tmp\fractus-storybook`) e gravar em `plan-paths.json`.
+   - Se presente: indexar `.stories.tsx` disponíveis (lista usada na Fase 1.3).
 
 ## Fase 1 — Mapeamento Visual & Componentização
 
@@ -60,8 +84,10 @@ Caso contrário: trabalhar pela descrição/screenshot fornecido.
 
 Produzir tabela:
 
-| Elemento (Figma/descrição) | Componente do DS | Variant | Props relevantes |
-|----------------------------|------------------|---------|-------------------|
+| Elemento (Figma/descrição) | Componente do DS | Story (path) | Variant | Props relevantes |
+|----------------------------|------------------|--------------|---------|-------------------|
+
+A coluna `Story (path)` aponta para `.stories.tsx` indexado no gate. Componente sem story correspondente NÃO entra na tabela — vai pra "Componentes ausentes" e gera task de criação.
 
 Listar **componentes ausentes** separadamente — sinalizar como bloqueio ou candidato a criação (vai virar task própria).
 
@@ -77,6 +103,22 @@ Saída desta fase é uma seção **"Aderência à Stack"** no plano — não red
 
 **Modo `--allow-arch-change`**: pode propor alteração. Gerar ADR em `dirs.adr` (template `templates/adr-tmpl.yaml`) ANTES de prosseguir. Plano referencia o ADR e marca `arch_change: true` no frontmatter.
 
+### 2.5 Backend gaps → ClickUp automático
+
+Postman é o **contrato backend**. Para cada dado/ação da tela:
+
+1. Confrontar com `<PROJETO>/docs/postman/` (já indexado no comprehension gate).
+2. Se o endpoint não existir, ou existir com shape divergente, ou faltar RLS/migration para suportar a tela → registrar como **backend pending**.
+3. Para cada pending, criar task ClickUp via `mcp__clickup__clickup_create_task`:
+   - **Assignee**: `ASSIGNEE` do prompt OU default `112010775` (Douglas Oliveira).
+   - **List**: `clickup.backend_list_id` de `plan-paths.json`. Ausente → registrar pending no plano com `clickup: pending` e seguir.
+   - **Título**: `[Backend] PLAN-NNN: <gap em uma linha>`
+   - **Descrição**: o que a tela precisa, qual coleção/endpoint do Postman cobre (ou não), referência ao plano (`docs/plans/PLAN-NNN/plan.md`), shape esperado.
+4. Registrar IDs criados em:
+   - `plan.md` → seção `## Backend pendings` (lista com `clickup_id`, status, link).
+   - `progress.txt` → bloco `## Backend pendings — PLAN-NNN`.
+5. Flag `--skip-clickup` desliga a criação (pending fica registrado apenas no plano).
+
 ## Fase 3 — Plano de Execução
 
 Para cada elemento mapeado:
@@ -127,6 +169,7 @@ Próximos passos:
 - **Backend read-only respeitado**: se `stack.md` declara backend read-only, plano NUNCA propõe schema novo.
 - **Next.js App Router**: decisão server vs client é explícita por elemento.
 - **Sem prosa decorativa**: plano deve ser executável, denso, com critérios mensuráveis.
+- **Storybook como contrato**: cada componente do DS na tabela DEVE apontar `.stories.tsx` existente em `dirs.storybook`. Sem story → componente vai pra "Componentes ausentes" e gera task de criação. Sem essa disciplina, o visual gate do `*execute-plan` quebra.
 
 ## Model guidance
 
@@ -139,6 +182,7 @@ Próximos passos:
 ## Instructions
 
 1. NUNCA prosseguir sem `stack.md` válido.
-2. Resolver TODOS os paths via `plan-paths.json`.
+2. Resolver TODOS os paths via `plan-paths.json`. PROJETO/WORK_BRANCH são auto-resolvidos pelo `gos-master` — não perguntar ao usuário.
 3. Status inicial do plano e tasks: `pendente`.
 4. Não pushar nada — apenas escrever arquivos locais.
+5. Backend pendings só criam tasks ClickUp se o `mcp__clickup__*` estiver disponível na sessão E `--skip-clickup` não for passado. Caso contrário, registrar apenas no plano.

package/.gos/skills/registry.json

@@ -22,6 +22,7 @@
     { "slug": "slack-review", "path": "skills/slack-review/SKILL.md" },
     { "slug": "stack-profiler", "path": "skills/stack-profiler/SKILL.md" },
     { "slug": "plan-blueprint", "path": "skills/plan-blueprint/SKILL.md" },
-    { "slug": "progress-tracker", "path": "skills/progress-tracker/SKILL.md" }
+    { "slug": "progress-tracker", "path": "skills/progress-tracker/SKILL.md" },
+    { "slug": "execute-plan", "path": "skills/execute-plan/SKILL.md" }
   ]
 }

package/.gos/templates/planTemplate.md

@@ -1,12 +1,14 @@
 ---
 id: PLAN-<NNN>-<slug>
 tela: <nome da tela>
+objetivo: <implantacao | correcao | refactor>
 figma_url: <url ou null>
 status: pendente
 parent_plan: <PLAN-NNN ou null>
 children_plans: []
 stack_ref: docs/stack.md@<sha-curto>
 arch_change: false
+work_branch: <dev | feat/storybook>
 created_at: <iso>
 validated_at: null
 ---
@@ -19,9 +21,9 @@ validated_at: null
 
 ## Componentes mapeados
 
-| Elemento | Componente do DS | Variant | Props |
-|----------|------------------|---------|-------|
-|          |                  |         |       |
+| Elemento | Componente do DS | Story (path) | Variant | Props |
+|----------|------------------|--------------|---------|-------|
+|          |                  |              |         |       |
 
 ## Componentes ausentes
 
@@ -68,9 +70,28 @@ validated_at: null
 - [ ] Sem console errors/warnings
 - [ ] TypeScript válido (`tsc --noEmit`)
 - [ ] Reutilização ≥ X% de componentes do DS
+- [ ] **Visual gate**: cada componente mapeado tem story em `dirs.stories/`
+- [ ] **Visual gate**: anatomia, tokens e densidade batem com a story canônica (≤ 1 desvio menor documentado em `T-NNN-NN.notes.md`)
+- [ ] **Visual gate**: árvore JSX da tela espelha hierarquia do Figma (mesmas seções, mesma ordem)
 - [ ] <critério específico da tela 1>
 - [ ] <critério específico da tela 2>
 
+## Backend pendings
+
+> Gaps detectados confrontando Postman/regras-de-negocio com a necessidade da tela. Cada item vira task ClickUp atribuída ao Douglas (default) ou ao `ASSIGNEE` informado. Vazio = backend completo para esta tela.
+
+| Gap | Endpoint/Coleção esperada | ClickUp ID | Status |
+|-----|---------------------------|------------|--------|
+|     |                           |            |        |
+
+## Knowledge mapped
+
+> Inventário denso do que foi indexado no comprehension gate (regras-de-negocio + Postman).
+
+- **Regras de negócio**: `<lista de arquivos relevantes em docs/regras-de-negocio/>`
+- **Postman**: `<lista de coleções/endpoints relevantes em docs/postman/>`
+- **Stack ref**: `<sha de stack.md>`
+
 ## Riscos & Rollback
 
 - <risco>

package/.gos/templates/taskTemplate.md

@@ -30,6 +30,7 @@ links: []
 ## Critérios de aceitação (DoD)
 
 - [ ] Implementação atende `valida_em` do plano
+- [ ] **Visual gate aprovado** (relatório em `T-NNN-NN.notes.md` com 4 seções: anatomia, tokens, variants, densidade)
 - [ ] Tests/CI verdes
 - [ ] Sem regressões
 - [ ] <métrica específica>

package/CLAUDE.md

@@ -48,17 +48,21 @@ Todo texto gerado deve passar por correcao ortografica e remocao de padroes de I
 gos-master | architect | dev | devops | po | qa | sm | squad-creator | ux-design-expert
 
 ### Skills (invoke via /gos:skills:{slug})
-design-to-code | figma-implement-design | figma-make-analyzer | make-code-triage | make-version-diff | component-dedup | frontend-dev | interface-design | react-best-practices | react-doctor | sprint-planner | clickup | plan-to-tasks | agent-teams | git-ssh-setup | stack-profiler | plan-blueprint | progress-tracker
+design-to-code | figma-implement-design | figma-make-analyzer | make-code-triage | make-version-diff | component-dedup | frontend-dev | interface-design | react-best-practices | react-doctor | sprint-planner | clickup | plan-to-tasks | agent-teams | git-ssh-setup | stack-profiler | plan-blueprint | progress-tracker | execute-plan
+
+### IDEs suportadas (npm run sync:ides gera adapters)
+Claude Code | Cursor | Gemini CLI | Qwen Code | Antigravity | Opencode | Kilo Code | **Codex IDE Extension** (ambiente de execucao, comando primario `*execute-plan`)
 
 ## Plan Pipeline (stack-aware)
 
-Pipeline padronizado para criacao de planos por tela. Toda tela = 1 plano. Stack-of-record (`docs/stack.md`) e contrato — alteracoes de stack exigem ADR.
+Pipeline padronizado para criacao de planos por tela. Toda tela = 1 plano. Stack-of-record (`docs/stack.md`) e contrato — alteracoes de stack exigem ADR. Divisao de trabalho: **Opus 4.7 planeja, Codex IDE executa**.
 
-| Comando | Skill | Funcao |
-|---------|-------|--------|
-| `*stack [refresh|show|drift]` | `stack-profiler` | Mantem `docs/stack.md` (canonico do projeto) |
-| `*plan <tela>` | `plan-blueprint` | Cria plano + tasks + context + atualiza `progress.txt` |
-| `*progress [show|set|status]` | `progress-tracker` | Memoria L1 + state machine de status |
+| Comando | Skill | IDE / Modelo | Funcao |
+|---------|-------|--------------|--------|
+| `*stack [refresh|show|drift]` | `stack-profiler` | qualquer | Mantem `docs/stack.md` (canonico do projeto) |
+| `*plan <tela>` | `plan-blueprint` | Opus 4.7 (planejador) | Cria plano + tasks + context + atualiza `progress.txt` |
+| `*execute-plan <PLAN-NNN>` | `execute-plan` | **Codex IDE Extension** (executor) | Executa task-a-task com visual gate vs Storybook canonico |
+| `*progress [show|set|status]` | `progress-tracker` | qualquer | Memoria L1 + state machine de status |
 
 State machine: `pendente -> em-andamento -> validacao -> concluido` (concluido somente apos validacao humana).
 

package/README.md

@@ -43,50 +43,149 @@ Após rodar o install, o framework criará uma estrutura limpa na sua raiz:
 
 ### 3. Comandos do Workspace
 
-A partir da raiz do seu projeto:
-
 | Comando | Equivalente CLI | O que faz |
 |---------|-----------------|-----------|
-| `npm run gos:init` | `gos init` | Setup pos-clone: configura `upstream`, cria dirs (`.gos-local/`), gera IDE adapters, sincroniza com framework pai |
-| `npm run gos:update` | `gos update` | `git fetch upstream` + merge `upstream/main` + `npm install` + re-sync IDE adapters |
-| `npm run gos:doctor` | `gos doctor` | Valida integridade do workspace, registry de skills, IDE adapters, presenca de Git remote |
-| `npm run gos:version` | `gos version` | Mostra versao instalada e checa se ha atualizacoes pendentes em `upstream/main` |
+| `npm run gos:init` | `gos init` | Setup pos-clone: configura `upstream`, cria `.gos-local/`, gera IDE adapters |
+| `npm run gos:update` | `gos update` | Fetch + merge do upstream (**apenas em fork/clone do g-os**) |
+| `npm run gos:doctor` | `gos doctor` | Health-check (42+ checks: skills, agents, IDE adapters, upstream alcançável, stashes acumulados, modo workspace) |
+| `npm run gos:version` | `gos version` | Versão instalada, modo do workspace e atualizações pendentes |
+| `npm run gos:rescue` | `gos rescue` | Lista/recupera stashes acumulados de updates falhos |
 | `npm run sync:ides` | — | Regenera apenas os IDE adapters (`.claude/`, `.qwen/`, `.gemini/`, `.cursor/`, `.agents/`) |
-| `npm run check:ides` | — | Valida que todos os adapters estao consistentes com `.gos/skills/registry.json` |
-| `npm run clickup` | — | CLI ClickUp (tarefas, sprints, status) |
+| `npm run check:ides` | — | Valida que adapters estão consistentes com `.gos/skills/registry.json` |
+| `npm run clickup` | — | CLI ClickUp |
+
+## Atualizar o ganbatte-os
+
+Existem **três níveis distintos** de versão. Saiba qual atualizar antes de rodar qualquer comando.
+
+### Descobrir em que cenário você está
+
+```bash
+npm run gos:version
+# imprime: versão local + modo (framework workspace | projeto consumidor)
+```
+
+| Modo detectado | Significa | Como atualizar |
+|----------------|-----------|----------------|
+| `framework workspace` | Você clonou/forkou o repo `g-os` para contribuir | `npm run gos:update` |
+| `projeto consumidor` | Seu projeto usa o G-OS (rodou `gos install` aqui) | `gos install --force` |
+| (CLI global) | O comando `gos` instalado via `npm install -g` | `npm install -g ganbatte-os@latest` |
 
-**Atualizar o G-OS no seu workspace:**
+### Nível 1 — CLI global (`gos`)
 
 ```bash
+# Versão atual instalada vs publicada no registry:
+npm list -g ganbatte-os
+npm view ganbatte-os version
+
+# Atualizar:
+npm install -g ganbatte-os@latest
+```
+
+### Nível 2 — Projeto consumidor
+
+Seu projeto NÃO é fork do G-OS, mas usa o framework via `gos install`. O `.gos/` mora dentro do seu repo.
+
+```bash
+# Pré-checagem (uma vez):
+git remote -v
+# Se houver "upstream" apontando para g-os.git, REMOVA: 
+#   git remote remove upstream
+# (essa configuração só faz sentido em fork do framework)
+
+# Atualizar o framework dentro do seu projeto:
+gos install --force
+# Sobrescreve .gos/ com a última versão do pacote ganbatte-os global,
+# preservando seus arquivos (packages/, docs/, .gos-local/).
+```
+
+> [!WARNING]
+> NÃO use `npm run gos:update` em projeto consumidor. O CLI agora detecta esse cenário e aborta com instruções, mas em versões antigas ele tentava `git fetch upstream main` e quebrava de forma confusa.
+
+### Nível 3 — Framework workspace (fork/clone do g-os)
+
+Você está contribuindo com o próprio framework.
+
+```bash
+# Pré-checagem (sempre antes de update):
+npm run gos:doctor
+# Valida 42+ pontos. Aborta se upstream estiver com URL quebrada
+# ou se houver stashes acumulados de updates anteriores falhos.
+
+# Ver quantos commits faltam:
+npm run gos:version
+
+# Aplicar (lê dev branch do .gos/config.json#defaultBranches.development):
 npm run gos:update
-# equivalente a: git fetch upstream && git merge upstream/main && npm install && npm run sync:ides
 ```
 
-Em caso de divergencia local nao resolvivel automaticamente, o comando aborta e instrui resolucao manual. Se quiser inspecionar antes:
+`gos:update` agora é **fail-safe**:
+
+1. Bloqueia se modo for `consumer`
+2. Valida `upstream` reachable (`git ls-remote`) ANTES de stashar
+3. Lê branch de desenvolvimento do `.gos/config.json` (não hardcoded)
+4. Faz fetch primeiro; se nada mudou, sai sem stash
+5. Stash recebe label timestamped único
+6. Auto-resolve conflitos em arquivos do framework (`frameworkManaged` no manifest); aborta em conflitos do usuário
+
+Override de branch (debug):
+
+```bash
+GOS_UPSTREAM_BRANCH=beta npm run gos:update
+```
+
+#### Caso especial: "histórias não relacionadas"
+
+Workspaces criados via `gos install` no passado podem ter `.git` próprio sem ancestor comum com o repo do framework. Nesse caso o merge falha com `fatal: refusing to merge unrelated histories`. O CLI detecta e instrui:
+
+```bash
+npm run gos:update -- --allow-unrelated
+```
+
+Isso une as duas histórias num commit de merge único. Faça uma vez; depois disso updates normais funcionam.
+
+#### Caso especial: untracked files que conflitam com o merge
+
+Se você tem arquivos não-versionados em paths que o framework gera (`.claude/`, `.qwen/`, `.gemini/`, `.cursor/`, `.agents/`, etc), o git recusa o merge para evitar perda. O CLI detecta e oferece:
 
 ```bash
-npm run gos:version   # mostra versao atual + commits pendentes em upstream
-git fetch upstream    # ver mudancas sem aplicar
-git log HEAD..upstream/main --oneline
+npm run gos:update -- --clobber-untracked
 ```
 
-**Health-check apos qualquer mudanca:**
+Isso renomeia os arquivos conflitantes para `.bak.<timestamp>` antes do merge. Como esses paths são **sempre regenerados** por `npm run sync:ides`, o backup é só por garantia — você pode deletar depois.
+
+Combinar com `--allow-unrelated` quando ambos os casos ocorrerem (típico de workspaces antigos):
 
 ```bash
-npm run gos:doctor    # 40+ checks (skills, agents, IDE adapters, git remote)
+npm run gos:update -- --allow-unrelated --clobber-untracked
 ```
 
-### Via CLI global (`gos`)
+Alternativa segura (não toca seu git, apenas atualiza `.gos/`):
+
+```bash
+gos install --force
+```
+
+### Resgate de stashes presos
+
+Se você teve falhas anteriores que deixaram stashes:
+
+```bash
+npm run gos:rescue                          # lista todos com stat
+npm run gos:rescue -- --pop-latest          # aplica o mais recente
+npm run gos:rescue -- --drop-all            # remove todos (após revisão)
+```
 
-Apos `npm install -g ganbatte-os`:
+### Resumo (qual comando para qual cenário)
 
-| Comando | O que faz |
-|---------|-----------|
-| `gos install` | Instala framework em diretorio novo |
-| `gos init` | Inicializa workspace existente |
-| `gos update` | Atualiza framework (mesma logica de `npm run gos:update`) |
-| `gos doctor` | Health-check |
-| `gos version` | Versao instalada |
+| Cenário | Comando |
+|---------|---------|
+| Atualizar CLI `gos` global | `npm install -g ganbatte-os@latest` |
+| Atualizar G-OS num projeto consumidor | `gos install --force` |
+| Atualizar G-OS num fork/clone do repo | `npm run gos:update` |
+| Stashes presos de updates falhos | `npm run gos:rescue` |
+| Saber em qual cenário você está | `npm run gos:version` |
+| Validar tudo de uma vez | `npm run gos:doctor` |
 
 > [!NOTE]
 > A pasta `.agent/` que pode aparecer na raiz do workspace e criada pela IDE Google Antigravity / Gemini Code Assist — nao faz parte do setup padrao do ganbatte-os.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ganbatte-os",
-  "version": "0.2.32",
+  "version": "0.2.34",
   "description": "Framework operacional para design-to-code, squads de entrega e sprint sync com ClickUp.",
   "bin": {
     "gos": ".gos/scripts/cli/gos-cli.js"
@@ -10,6 +10,7 @@
     "gos:update": "node .gos/scripts/cli/gos-cli.js update",
     "gos:doctor": "node .gos/scripts/cli/gos-cli.js doctor",
     "gos:version": "node .gos/scripts/cli/gos-cli.js version",
+    "gos:rescue": "node .gos/scripts/cli/gos-cli.js rescue",
     "clickup": "node .gos/scripts/tools/clickup.js",
     "sync:ides": "node .gos/scripts/integrations/setup-ide-adapters.js",
     "check:ides": "node .gos/scripts/integrations/check-ide-compat.js",