ganbatte-os 0.2.31 → 0.2.33

package/.gos/scripts/cli/gos-cli.js

@@ -30,9 +30,74 @@ function readPackageVersion() {
 
 const VERSION = readPackageVersion();
 const UPSTREAM_REMOTE = 'upstream';
-const UPSTREAM_BRANCH = 'main';
+const DEFAULT_UPSTREAM_BRANCH = 'main';
 const LOCAL_DIR = '.gos-local';
 const MANIFEST_PATH = '.gos/manifests/gos-install-manifest.json';
+const CONFIG_PATH = '.gos/config.json';
+const CORRECT_UPSTREAM_URL = 'git@github-adriano:adrianomorais-ganbatte/g-os.git';
+const CORRECT_UPSTREAM_URL_HTTPS = 'https://github.com/adrianomorais-ganbatte/g-os.git';
+const STASH_LABEL = 'gos-update-auto-stash';
+
+/**
+ * Resolve a development branch a partir de .gos/config.json.
+ * Fallback: 'main'. Permite override via env GOS_UPSTREAM_BRANCH.
+ */
+function resolveUpstreamBranch(root) {
+  if (process.env.GOS_UPSTREAM_BRANCH) return process.env.GOS_UPSTREAM_BRANCH;
+  const cfg = readJson(path.join(root, CONFIG_PATH));
+  return cfg?.defaultBranches?.development || cfg?.defaultBranches?.production || DEFAULT_UPSTREAM_BRANCH;
+}
+
+/**
+ * Detecta se este workspace é o framework G-OS em si (fork/clone) ou um projeto
+ * consumidor que apenas instalou o framework via `gos install`.
+ *  - 'framework': package.json#name === 'ganbatte-os' AND .git no root
+ *  - 'consumer':  qualquer outro caso
+ */
+function detectMode(root) {
+  const pkg = readJson(path.join(root, 'package.json'), {});
+  const isGosPackage = pkg.name === 'ganbatte-os';
+  const hasGit = pathExists(path.join(root, '.git'));
+  return isGosPackage && hasGit ? 'framework' : 'consumer';
+}
+
+/**
+ * Valida que o remote upstream existe E responde. Não modifica nada.
+ * Retorna { ok, remoteUrl, error }.
+ */
+function validateUpstream(root) {
+  const remotes = gitCapture(['remote'], { cwd: root });
+  if (!remotes.split(/\r?\n/).includes(UPSTREAM_REMOTE)) {
+    return { ok: false, error: `remote "${UPSTREAM_REMOTE}" não configurado` };
+  }
+  const url = gitCapture(['remote', 'get-url', UPSTREAM_REMOTE], { cwd: root });
+  // Detecta URL antiga incorreta (ganbatte-os.git em vez de g-os.git)
+  if (/ganbatte-os\.git/.test(url) && !/g-os\.git/.test(url)) {
+    return { ok: false, remoteUrl: url, error: 'URL do upstream parece estar com nome antigo (ganbatte-os.git)' };
+  }
+  // Ping no remoto sem stashar nada
+  try {
+    execFileSync('git', ['ls-remote', '--quiet', '--exit-code', UPSTREAM_REMOTE, 'HEAD'], {
+      cwd: root, stdio: 'pipe', encoding: 'utf8',
+    });
+    return { ok: true, remoteUrl: url };
+  } catch (e) {
+    return { ok: false, remoteUrl: url, error: `não foi possível alcançar ${url}` };
+  }
+}
+
+/**
+ * Lista todos stashes auto-criados pelo gos-update.
+ * Retorna [{ ref, branch, label, dateIso }].
+ */
+function listGosStashes(root) {
+  const out = gitCapture(['stash', 'list', '--format=%gd|%gs|%ci'], { cwd: root });
+  if (!out) return [];
+  return out.split(/\r?\n/).filter(Boolean).map(line => {
+    const [ref, subject, dateIso] = line.split('|');
+    return { ref, subject, dateIso };
+  }).filter(s => s.subject && s.subject.includes(STASH_LABEL));
+}
 
 // ---------------------------------------------------------------------------
 // Utilitarios
@@ -347,57 +412,219 @@ function cmdInstall(args) {
 
 function cmdUpdate(root, args) {
   const skipStash = args.includes('--no-stash');
+  const branch = resolveUpstreamBranch(root);
+  const mode = detectMode(root);
 
   log('Atualizando workspace ganbatte-os...');
 
-  // 1. Verificar remote upstream
-  const remotes = gitCapture(['remote'], { cwd: root });
-  if (!remotes.includes(UPSTREAM_REMOTE)) {
-    fail(`Remote "${UPSTREAM_REMOTE}" nao encontrado.`);
-    info(`Adicione com: git remote add ${UPSTREAM_REMOTE} https://github.com/adrianomorais-ganbatte/ganbatte-os.git`);
+  // 0. Modo: bloquear se for projeto consumidor (não fork do framework).
+  if (mode === 'consumer') {
+    fail('Este workspace é um projeto consumidor, não o repositório do framework G-OS.');
+    info('Para atualizar o framework dentro do seu projeto, use:');
+    info('  gos install --force');
+    info('Ou (se você instalou via npm install):');
+    info('  npm install ganbatte-os@latest');
+    info('');
+    info('`gos update` é apenas para forks/clones do repositório g-os.');
     process.exit(1);
   }
 
-  // 2. Checar se ha mudancas locais e fazer stash
-  const status = gitCapture(['status', '--porcelain'], { cwd: root });
-  let didStash = false;
-  if (status && !skipStash) {
-    log('Mudancas locais detectadas. Fazendo stash...');
-    git(['stash', 'push', '-m', 'gos-update-auto-stash'], { cwd: root });
-    didStash = true;
-    ok('Stash criado.');
+  // 1. Validar upstream ANTES de qualquer modificação local (stash, etc).
+  const upstream = validateUpstream(root);
+  if (!upstream.ok) {
+    fail(`Upstream inválido: ${upstream.error}`);
+    if (upstream.remoteUrl) info(`URL atual: ${upstream.remoteUrl}`);
+    info('Corrija com:');
+    info(`  git remote set-url ${UPSTREAM_REMOTE} ${CORRECT_UPSTREAM_URL}`);
+    info(`  (ou via HTTPS: ${CORRECT_UPSTREAM_URL_HTTPS})`);
+    info('');
+    info(`Depois rode: npm run gos:update`);
+    process.exit(1);
   }
 
-  // 3. Fetch upstream
-  log(`Buscando atualizacoes de ${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH}...`);
-  git(['fetch', UPSTREAM_REMOTE, UPSTREAM_BRANCH], { cwd: root });
+  // 2. Dry-run fetch (sem stashar): se nada mudou, sai cedo.
+  log(`Verificando ${UPSTREAM_REMOTE}/${branch}...`);
+  try {
+    git(['fetch', UPSTREAM_REMOTE, branch], { cwd: root, quiet: true });
+  } catch (e) {
+    fail(`Fetch de ${UPSTREAM_REMOTE}/${branch} falhou.`);
+    info('Verifique sua conexão e credenciais SSH/HTTPS. Nada foi modificado localmente.');
+    process.exit(1);
+  }
 
-  // 4. Checar se ha commits novos
   const behind = gitCapture(
-    ['rev-list', '--count', `HEAD..${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH}`],
+    ['rev-list', '--count', `HEAD..${UPSTREAM_REMOTE}/${branch}`],
     { cwd: root }
   );
-  if (behind === '0') {
-    ok('Workspace ja esta atualizado.');
-    if (didStash) git(['stash', 'pop'], { cwd: root });
+  if (behind === '0' || behind === '') {
+    ok(`Workspace ja esta atualizado com ${UPSTREAM_REMOTE}/${branch}.`);
     return;
   }
 
+  // 3. AGORA é seguro stashar (upstream validado + commits novos confirmados).
+  // Importante: stash deve EXCLUIR paths do framework — eles serão sobrescritos
+  // pelo merge de qualquer forma, e stashar a si próprio (gos-cli.js) cria um
+  // loop em que o stash reverte a versão atualizada do CLI no working tree.
+  const status = gitCapture(['status', '--porcelain'], { cwd: root });
+  // Detectar se há mudanças além dos paths framework
+  const userModifiedLines = status
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .filter(line => {
+      const file = line.slice(3); // 2-char status flag + space
+      // Exclui paths gerados/managed pelo framework
+      const FRAMEWORK_PREFIXES = [
+        '.gos/', '.claude/', '.qwen/', '.gemini/', '.cursor/', '.agents/',
+        '.kilocode/', '.antigravity/', '.opencode/', '.codex/',
+      ];
+      return !FRAMEWORK_PREFIXES.some(p => file.startsWith(p));
+    });
+  let didStash = false;
+  if (userModifiedLines.length > 0 && !skipStash) {
+    log(`Mudancas locais do usuario detectadas (${userModifiedLines.length}). Fazendo stash...`);
+    const stashLabel = `${STASH_LABEL} ${new Date().toISOString()}`;
+    // Stash com pathspec excluindo paths do framework — assim o stash captura
+    // apenas mudanças do usuário, e o working tree mantém a versão atualizada
+    // dos arquivos do framework (incluindo este próprio CLI).
+    const stashArgs = [
+      'stash', 'push', '-m', stashLabel, '--',
+      ':(exclude,top).gos',
+      ':(exclude,top).claude',
+      ':(exclude,top).qwen',
+      ':(exclude,top).gemini',
+      ':(exclude,top).cursor',
+      ':(exclude,top).agents',
+      ':(exclude,top).kilocode',
+      ':(exclude,top).antigravity',
+      ':(exclude,top).opencode',
+      ':(exclude,top).codex',
+      '.',
+    ];
+    git(stashArgs, { cwd: root });
+    didStash = true;
+    ok(`Stash criado (apenas mudancas do usuario): ${stashLabel}`);
+  } else if (status) {
+    info(`Mudancas locais detectadas apenas em paths do framework — serao sobrescritas pelo merge.`);
+  }
+
   const commitBefore = gitCapture(['rev-parse', '--short', 'HEAD'], { cwd: root });
 
   // 5. Merge
   log(`${behind} commit(s) novo(s). Fazendo merge...`);
   const manifest = getManifest(root);
   const frameworkPaths = manifest.frameworkManaged || [];
+  const allowUnrelated = args.includes('--allow-unrelated');
+  const clobberUntracked = args.includes('--clobber-untracked');
+
+  // Paths que podemos clobberar com segurança:
+  //  - IDE adapters: regenerados por sync:ides
+  //  - .gos/: framework directory, sempre vem do upstream
+  const FRAMEWORK_GENERATED_PREFIXES = [
+    '.claude/', '.qwen/', '.gemini/', '.cursor/', '.agents/',
+    '.kilocode/', '.antigravity/', '.opencode/', '.codex/',
+    '.gos/',
+  ];
+  const isGenerated = (p) => FRAMEWORK_GENERATED_PREFIXES.some(prefix => p.startsWith(prefix));
+
+  const mergeArgs = ['merge', `${UPSTREAM_REMOTE}/${branch}`, '--no-edit'];
+  if (allowUnrelated) mergeArgs.push('--allow-unrelated-histories');
+
+  // Função tentando o merge, capturando stderr — chamada mais de uma vez se houver retry
+  function tryMerge() {
+    try {
+      execFileSync('git', mergeArgs, { cwd: root, stdio: 'pipe', encoding: 'utf8' });
+      return { ok: true };
+    } catch (e) {
+      return { ok: false, err: ((e.stderr || '') + (e.stdout || '')).toString() };
+    }
+  }
 
-  try {
-    git(['merge', `${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH}`, '--no-edit'], { cwd: root, quiet: true });
+  let mergeErr = '';
+  let attempt = tryMerge();
+  if (attempt.ok) {
     ok('Merge concluido sem conflitos.');
-  } catch {
-    // Checar conflitos
+  } else {
+    mergeErr = attempt.err;
+
+    // Auto-resolução: untracked files que upstream quer escrever, mas só se
+    // todos forem paths gerados pelo framework (sync:ides regenera).
+    const untrackedMatch = mergeErr.match(/untracked working tree files would be overwritten by merge:\s*([\s\S]+?)(?:Please move or remove|$)/i);
+    if (untrackedMatch) {
+      const conflictingPaths = untrackedMatch[1]
+        .split(/\r?\n/)
+        .map(s => s.trim())
+        .filter(Boolean)
+        // git termina com "Aborting", "Merge with strategy ort failed.", "Please move or remove..."
+        // Caminhos reais sempre contêm "." (extensão ou dotfile) OU "/" (subdir).
+        .filter(s => (s.includes('.') || s.includes('/')) && !/^(Aborting|Merge with|Please move)/i.test(s));
+      const generated = conflictingPaths.filter(isGenerated);
+      const userOwned = conflictingPaths.filter(p => !isGenerated(p));
+
+      if (clobberUntracked && userOwned.length === 0) {
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        log(`${generated.length} arquivo(s) untracked em paths regenerados — movendo para .bak.${ts}/`);
+        for (const file of generated) {
+          const src = path.join(root, file);
+          const dst = path.join(root, `${file}.bak.${ts}`);
+          if (pathExists(src)) {
+            ensureDir(path.dirname(dst));
+            fs.renameSync(src, dst);
+          }
+        }
+        ok(`Movidos ${generated.length} arquivo(s). Retentando merge...`);
+        attempt = tryMerge();
+        if (attempt.ok) {
+          ok('Merge concluido apos clobber.');
+          mergeErr = '';
+        } else {
+          mergeErr = attempt.err;
+        }
+      } else if (userOwned.length === 0 && !clobberUntracked) {
+        fail(`Merge abortou: ${conflictingPaths.length} arquivo(s) untracked seriam sobrescritos.`);
+        info('Todos os arquivos afetados estão em paths gerados pelo framework (regenerados por sync:ides):');
+        for (const p of generated.slice(0, 10)) info(`  - ${p}`);
+        if (generated.length > 10) info(`  ... mais ${generated.length - 10}`);
+        info('');
+        info('Para auto-mover esses arquivos para .bak.<timestamp> antes do merge:');
+        info(`  npm run gos:update -- --clobber-untracked${allowUnrelated ? ' --allow-unrelated' : ''}`);
+        if (didStash) info('Stash preservado. Rode: git stash pop quando terminar.');
+        process.exit(1);
+      } else {
+        // Misto — tem arquivos do usuário também → não clobberamos nada
+        fail(`Merge abortou: arquivos untracked seriam sobrescritos.`);
+        info(`${userOwned.length} arquivo(s) NÃO gerados pelo framework (revisar antes):`);
+        for (const p of userOwned.slice(0, 10)) info(`  - ${p}`);
+        info('Mova ou versione esses arquivos manualmente; depois retente.');
+        if (didStash) info('Stash preservado.');
+        process.exit(1);
+      }
+    }
+  }
+
+  if (!attempt.ok) {
+
+    // Detecta histórias não relacionadas (comum em workspaces criados via `gos install`)
+    if (/unrelated histories/i.test(mergeErr) && !allowUnrelated) {
+      fail('Merge abortou: histórias não relacionadas entre HEAD e upstream.');
+      info('Isto é comum quando o workspace foi bootstrappado via `gos install`');
+      info('e nunca compartilhou commits com o repositório do framework.');
+      info('');
+      info('Para forçar o merge unindo as histórias (recomendado neste caso):');
+      info(`  npm run gos:update -- --allow-unrelated`);
+      info('');
+      info('Alternativa segura (sobrescreve apenas .gos/ preservando seus arquivos):');
+      info('  gos install --force');
+      if (didStash) info('Stash preservado. Rode: git stash pop quando resolver.');
+      process.exit(1);
+    }
+
+    // Checar conflitos de arquivo
     const conflictFiles = gitCapture(['diff', '--name-only', '--diff-filter=U'], { cwd: root });
     if (!conflictFiles) {
-      fail('Merge falhou por motivo desconhecido.');
+      fail('Merge falhou. Erro do git:');
+      for (const line of mergeErr.split(/\r?\n/).filter(Boolean).slice(0, 6)) {
+        console.log(`    ${line}`);
+      }
       if (didStash) info('Stash preservado. Rode: git stash pop');
       process.exit(1);
     }
@@ -600,12 +827,46 @@ function cmdDoctor(root) {
     check(`Diretorio ${LOCAL_DIR}/ existe`, hasLocalDir);
   }
 
-  // 10. Report
+  // 10. Mode + upstream sanity (warnings, não falhas)
+  const mode = detectMode(root);
+  const branch = resolveUpstreamBranch(root);
+  const isCi = Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
+  if (mode === 'framework') {
+    if (isCi) {
+      info('Upstream check ignorado em CI (sem credenciais para git ls-remote)');
+    } else {
+      const upstream = validateUpstream(root);
+      if (upstream.ok) {
+        ok(`Upstream alcançável (branch: ${branch})`);
+      } else {
+        warn(`Upstream inválido: ${upstream.error}`);
+        if (upstream.remoteUrl) info(`URL atual: ${upstream.remoteUrl}`);
+        info(`Corrija com: git remote set-url ${UPSTREAM_REMOTE} ${CORRECT_UPSTREAM_URL}`);
+        issues++;
+      }
+    }
+    checks++;
+  }
+
+  // 11. Stashes acumulados de updates falhos
+  const goshStashes = listGosStashes(root);
+  if (goshStashes.length > 1) {
+    warn(`${goshStashes.length} stashes do gos-update acumulados (sintoma de updates falhos).`);
+    info('Resgate com: npm run gos:rescue');
+    issues++;
+  } else if (goshStashes.length === 1) {
+    info(`1 stash do gos-update presente: ${goshStashes[0].ref}`);
+  }
+  checks++;
+
+  // 12. Report
   const updateLog = readJson(path.join(root, LOCAL_DIR, 'update-log.json'));
   const installLogData = readJson(path.join(root, LOCAL_DIR, 'install-log.json'));
 
   console.log('');
   console.log(`  Versao:         ${pkg ? pkg.version || VERSION : VERSION}`);
+  console.log(`  Modo:           ${mode === 'framework' ? 'framework workspace' : 'projeto consumidor'}`);
+  console.log(`  Branch dev:     ${branch}`);
   console.log(`  Inicializado:   ${installLogData ? installLogData.initializedAt : 'N/A'}`);
   console.log(`  Ultimo update:  ${updateLog ? updateLog.lastUpdate : 'N/A'}`);
   console.log(`  Node.js:        ${process.version}`);
@@ -620,6 +881,60 @@ function cmdDoctor(root) {
   process.exit(issues > 0 ? 1 : 0);
 }
 
+// ---------------------------------------------------------------------------
+// gos rescue — recuperar stashes acumulados de updates falhos
+// ---------------------------------------------------------------------------
+
+function cmdRescue(root, args) {
+  log('Buscando stashes do gos-update...');
+  const stashes = listGosStashes(root);
+  if (stashes.length === 0) {
+    ok('Nenhum stash do gos-update encontrado.');
+    return;
+  }
+
+  console.log('');
+  console.log(`  ${stashes.length} stash(es) auto-criado(s) pelo gos-update:`);
+  console.log('');
+  for (const s of stashes) {
+    console.log(`    ${s.ref}  (${s.dateIso})`);
+    const stat = gitCapture(['stash', 'show', '--stat', s.ref], { cwd: root });
+    if (stat) {
+      for (const line of stat.split(/\r?\n/).slice(0, 5)) {
+        if (line.trim()) console.log(`      ${line}`);
+      }
+    }
+    console.log('');
+  }
+
+  if (args.includes('--drop-all')) {
+    warn(`Removendo todos os ${stashes.length} stashes...`);
+    // Remove em ordem reversa porque os índices mudam
+    for (let i = stashes.length - 1; i >= 0; i--) {
+      git(['stash', 'drop', stashes[i].ref], { cwd: root, quiet: true });
+    }
+    ok('Todos os stashes do gos-update foram removidos.');
+    return;
+  }
+
+  if (args.includes('--pop-latest')) {
+    log(`Aplicando ${stashes[0].ref}...`);
+    try {
+      git(['stash', 'pop', stashes[0].ref], { cwd: root });
+      ok('Stash aplicado.');
+    } catch {
+      warn('Conflito ao aplicar. Resolva manualmente e rode `git stash drop` quando terminar.');
+    }
+    return;
+  }
+
+  info('Comandos disponíveis:');
+  info('  npm run gos:rescue -- --pop-latest    # aplica o stash mais recente');
+  info('  npm run gos:rescue -- --drop-all      # remove todos (após revisão)');
+  info('  git stash pop <ref>                   # aplica stash específico');
+  info('  git stash drop <ref>                  # remove stash específico');
+}
+
 // ---------------------------------------------------------------------------
 // gos version
 // ---------------------------------------------------------------------------
@@ -627,30 +942,43 @@ function cmdDoctor(root) {
 function cmdVersion(root) {
   const pkg = readJson(path.join(root, 'package.json'), {});
   const localVersion = pkg.version || VERSION;
+  const mode = detectMode(root);
+  const branch = resolveUpstreamBranch(root);
 
   console.log(`ganbatte-os v${localVersion}`);
+  console.log(`  modo: ${mode === 'framework' ? 'framework workspace (fork/clone do g-os)' : 'projeto consumidor'}`);
 
-  // Checar se ha commits novos no upstream
-  const remotes = gitCapture(['remote'], { cwd: root });
-  if (!remotes.includes(UPSTREAM_REMOTE)) {
-    info(`Remote "${UPSTREAM_REMOTE}" nao configurado. Nao foi possivel checar atualizacoes.`);
+  if (mode === 'consumer') {
+    info('Para checar a última versão publicada do framework:');
+    info('  npm view ganbatte-os version');
+    info('Para atualizar o framework dentro do seu projeto:');
+    info('  gos install --force');
+    return;
+  }
+
+  // Modo framework: checar commits novos no upstream
+  const upstream = validateUpstream(root);
+  if (!upstream.ok) {
+    warn(`Upstream inválido: ${upstream.error}`);
+    if (upstream.remoteUrl) info(`URL atual: ${upstream.remoteUrl}`);
+    info(`Corrija com: git remote set-url ${UPSTREAM_REMOTE} ${CORRECT_UPSTREAM_URL}`);
     return;
   }
 
   try {
-    execFileSync('git', ['fetch', UPSTREAM_REMOTE, UPSTREAM_BRANCH], {
+    execFileSync('git', ['fetch', UPSTREAM_REMOTE, branch], {
       encoding: 'utf8', stdio: 'pipe', cwd: root
     });
     const behind = gitCapture(
-      ['rev-list', '--count', `HEAD..${UPSTREAM_REMOTE}/${UPSTREAM_BRANCH}`],
+      ['rev-list', '--count', `HEAD..${UPSTREAM_REMOTE}/${branch}`],
       { cwd: root }
     );
 
     if (behind && behind !== '0') {
-      console.log(`\n  ${behind} commit(s) novo(s) disponivel(is).`);
+      console.log(`\n  ${behind} commit(s) novo(s) em ${UPSTREAM_REMOTE}/${branch}.`);
       console.log('  Atualize com: npm run gos:update\n');
     } else {
-      ok('Voce esta na versao mais recente.');
+      ok(`Voce esta na versao mais recente de ${UPSTREAM_REMOTE}/${branch}.`);
     }
   } catch {
     warn('Nao foi possivel checar atualizacoes (sem conexao?).');
@@ -683,6 +1011,10 @@ function main() {
       cmdDoctor(root);
       break;
 
+    case 'rescue':
+      cmdRescue(root, args.slice(1));
+      break;
+
     case 'version':
     case '-v':
     case '--version':
@@ -698,14 +1030,24 @@ ganbatte-os CLI v${VERSION}
 Comandos:
   gos install   Instalar G-OS no diretorio atual (via npx ou global)
   gos init      Setup pos-clone (remote, dirs, IDEs)
-  gos update    Atualizar do upstream/main
+  gos update    Atualizar do upstream (apenas em fork/clone do g-os)
+  gos rescue    Listar/recuperar stashes acumulados de updates falhos
   gos doctor    Validar integridade do workspace
-  gos version   Mostrar versao e checar atualizacoes
+  gos version   Mostrar versao, modo (framework/consumer) e atualizacoes
   gos help      Exibir esta ajuda
 
 Flags:
-  --force       Sobrescrever arquivos existentes (install/init)
-  --no-stash    Nao fazer stash automatico (update)
+  --force               Sobrescrever arquivos existentes (install/init)
+  --no-stash            Nao fazer stash automatico (update)
+  --allow-unrelated     Permitir merge de histórias não relacionadas (update)
+  --clobber-untracked   Mover untracked files (em paths regenerados) para
+                        .bak.<timestamp> antes do merge (update)
+  --pop-latest          Aplicar stash mais recente (rescue)
+  --drop-all            Remover todos os stashes do gos-update (rescue)
+
+Env:
+  GOS_UPSTREAM_BRANCH   Override da branch a ser pulled (default lê de
+                        .gos/config.json#defaultBranches.development)
 
 Exemplos:
   npx -p ganbatte-os gos install

package/README.md

@@ -43,30 +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, você pode gerenciar o framework:
-
-| Comando | O que faz |
-|---------|-----------|
-| `npm run gos:init` | Setup pos-clone (remote, dirs, IDEs, sync framework pai) |
-| `npm run gos:update` | Fetch upstream + merge + re-sync IDEs + sync framework pai |
-| `npm run gos:doctor` | Valida integridade do workspace e IDEs |
-| `npm run gos:version` | Mostra versao e checa atualizacoes |
-| `npm run sync:ides` | Regenera adapters para Claude, Gemini, Cursor e outras |
-| `npm run check:ides` | Valida compatibilidade dos IDE adapters |
-| `npm run clickup` | CLI ClickUp (tarefas, sprints, status) |
-| `npm run doctor` | Alias direto para gos:doctor |
-
-### Via CLI global (`gos`)
-
-Apos `npm install -g ganbatte-os`:
-
-| Comando | O que faz |
-|---------|-----------|
-| `gos install` | Instala framework em diretorio novo |
-| `gos init` | Inicializa workspace existente |
-| `gos update` | Atualiza framework |
-| `gos doctor` | Health-check |
-| `gos version` | Versao instalada |
+| Comando | Equivalente CLI | O que faz |
+|---------|-----------------|-----------|
+| `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 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` |
+
+### 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
+```
+
+`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:update -- --clobber-untracked
+```
+
+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:update -- --allow-unrelated --clobber-untracked
+```
+
+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)
+```
+
+### Resumo (qual comando para qual cenário)
+
+| 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.
@@ -136,7 +255,7 @@ O `ganbatte-os` utiliza uma estrutura **encapsulada** para manter seu projeto li
 
 ## Plan Pipeline (stack-aware)
 
-Pipeline padronizado para criacao de planos por tela. Toda tela vira um plano + tasks + contexto, com status auditavel e contrato de stack.
+Pipeline padronizado para criacao de planos por tela. **Toda tela = 1 plano**. Toda execucao gera plano + tasks + contexto, com status auditavel e contrato de stack.
 
 ### Fluxo
 
@@ -161,31 +280,206 @@ Pipeline padronizado para criacao de planos por tela. Toda tela vira um plano +
 
 ### Configuracao por workspace
 
-`.gos-local/plan-paths.json` define onde cada projeto guarda seus artefatos. Cada projeto/dev pode organizar diferente:
+`.gos-local/plan-paths.json` define onde cada projeto guarda seus artefatos. Cada projeto/dev pode organizar diferente.
+
+**Inicializar com defaults** (helper):
+
+```bash
+node .gos/scripts/tools/plan-paths.js init     # cria .gos-local/plan-paths.json se nao existir
+node .gos/scripts/tools/plan-paths.js show     # imprime config atual
+node .gos/scripts/tools/plan-paths.js get planos   # imprime path resolvido para "planos"
+```
+
+**Exemplo de config** (caso real do `packages/fractus`):
 
 ```json
 {
   "schema": "gos.plan-paths.v1",
   "dirs": {
-    "planos": "docs/plans/",
-    "tasks": "docs/plans/{plan}/tasks/",
-    "contexto": "docs/plans/{plan}/context.md",
-    "progress": "progress.txt",
-    "stack": "docs/stack.md",
-    "postman": "docs/postman/",
-    "regras_negocio": "docs/regras-de-negocio/"
+    "projeto":            "src/",
+    "storybook":          ".referencia-storybook/",
+    "design_system_doc":  ".referencia-storybook/docs/DESIGN_SYSTEM_REFERENCE.md",
+    "components":         ".referencia-storybook/components/",
+    "stories":            ".referencia-storybook/stories/",
+    "planos":             "docs/plans/",
+    "tasks":              "docs/plans/{plan}/tasks/",
+    "contexto":           "docs/plans/{plan}/context.md",
+    "progress":           "progress.txt",
+    "stack":              "docs/stack.md",
+    "adr":                "docs/adr/",
+    "postman":            "docs/postman/",
+    "regras_negocio":     "docs/regras-de-negocio/"
   },
   "knowledge_sources": [
     { "kind": "postman",        "path": "docs/postman/",            "required": false },
     { "kind": "business-rules", "path": "docs/regras-de-negocio/",  "required": false },
+    { "kind": "adr",            "path": "docs/adr/",                "required": false },
     { "kind": "design-system",  "path": ".referencia-storybook/docs/DESIGN_SYSTEM_REFERENCE.md", "required": true }
-  ]
+  ],
+  "naming": { "plan_prefix": "PLAN", "task_prefix": "T", "seq_padding": 3 },
+  "figma":  { "mcp_enabled": true, "default_file_url": null }
 }
 ```
 
-Helpers: `scripts/tools/plan-paths.js`, `scripts/tools/plan-status.js`, `scripts/tools/stack-scan.js`.
+Helpers em `.gos/scripts/tools/`:
+- `plan-paths.js` — resolve caminhos do projeto-cliente
+- `plan-status.js` — valida transicoes de status (state machine)
+- `stack-scan.js` — infere stack lendo `package.json`, configs e `knowledge_sources`
+
+### Exemplos de uso (end-to-end)
+
+Todos os comandos abaixo sao invocados via slash command no `gos-master` (Claude Code, Gemini, Cursor, etc).
+
+#### 1. Bootstrap do workspace (uma vez por projeto)
+
+```bash
+/gos:agents:gos-master
+```
+
+Em seguida, no chat:
+
+```
+*stack refresh
+```
+
+Saida esperada:
+
+```
+## Stack profilada — packages/fractus
+
+- Framework: Next.js 15 (App Router)
+- DB: Supabase (read-only)
+- Design System: .referencia-storybook
+- Knowledge sources: 4 (postman, business-rules, adr, design-system)
+
+stack.md: docs/stack.md
+lock:     .gos-local/stack.lock.json
+hashes:   12 arquivos
+```
+
+Verifique sempre que algo na stack mudar (lib, framework, ORM):
+
+```
+*stack drift
+```
+
+#### 2. Criar plano para uma tela
+
+A partir de URL Figma (autodetecta e usa Figma MCP):
+
+```
+*plan https://www.figma.com/design/kXd8uP6dgeSuQypFnPmuQP/FRACTUS?node-id=9140-25387
+```
+
+A partir de descricao livre:
+
+```
+*plan tela de checkout com formulario de pagamento e resumo do pedido
+```
+
+Saida:
+
+```
+## Plano criado: PLAN-042-checkout
+
+- plan.md:    docs/plans/PLAN-042-checkout/plan.md
+- context.md: docs/plans/PLAN-042-checkout/context.md
+- tasks/:     docs/plans/PLAN-042-checkout/tasks/ (5 tasks: T-042-001 ... T-042-005)
+- progress:   atualizado (status=pendente)
+- stack_ref:  docs/stack.md@a1b2c3d
+
+Proximos passos:
+1. Revisar plan.md e checklist de aceite
+2. *progress status T-042-001 em-andamento
+3. Executar
+```
+
+Telas complexas (modal + drawer + sub-rotas) sao **subdivididas automaticamente** em planos filhos:
+
+```
+PLAN-042-checkout            (pai, checklist consolidado)
+├── PLAN-042.1-payment-modal (filho)
+├── PLAN-042.2-summary-drawer
+└── PLAN-042.3-confirm-page
+```
+
+#### 3. Executar tasks
+
+```
+*progress show                              # mostra progress.txt atual
+*progress status T-042-001 em-andamento     # iniciar task
+# ... dev implementa ...
+*progress status T-042-001 validacao        # task pronta para revisao (commit preparado, nao pushado)
+```
+
+Tentar pular validacao falha:
+
+```
+*progress status T-042-001 concluido
+> erro: transicao invalida: em-andamento → concluido
+> use --rollback para voltar para pendente
+```
+
+#### 4. Fechar o plano
+
+Quando todas as tasks estao em `validacao` e o checklist do plano esta completo:
+
+```
+*progress status PLAN-042-checkout validacao    # validacao humana + QA
+*progress status PLAN-042-checkout concluido    # SOMENTE apos aprovacao
+```
+
+`progress-tracker compact` periodicamente reescreve `progress.txt` removendo tasks `concluido` antigas para manter o arquivo < 4kB (otimizado para LLM).
+
+#### 5. Mudanca de arquitetura (excecao)
+
+Se a tela exigir alteracao da stack (nova lib, novo padrao de fetching, schema novo):
+
+```
+*plan tela-relatorios --allow-arch-change
+```
+
+Isso forca a Fase 2 propositiva e gera um ADR em `docs/adr/ADR-NNNN-<slug>.md` antes de prosseguir. O plano resultante referencia o ADR no frontmatter (`arch_change: true`).
+
+### Estrutura de saida
+
+Apos `*plan tela-checkout`:
+
+```
+docs/plans/PLAN-042-checkout/
+├── plan.md          # frontmatter (id, tela, figma_url, status, stack_ref) + secoes fixas
+├── context.md       # denso, indice de arquivos, decisoes, riscos
+└── tasks/
+    ├── T-042-001-criar-rota-checkout.md
+    ├── T-042-002-fetching-supabase.md
+    ├── T-042-003-form-pagamento.md
+    ├── T-042-004-resumo-pedido.md
+    └── T-042-005-estados-erro-loading.md
+```
+
+`progress.txt` na raiz do projeto fica:
+
+```
+# progress.l1
+ts=2026-05-01T18:22:00-03:00
+project=fractus
+plan_active=docs/plans/PLAN-042-checkout/plan.md
+tasks_dir=docs/plans/PLAN-042-checkout/tasks/
+context=docs/plans/PLAN-042-checkout/context.md
+stack_ref=docs/stack.md@a1b2c3d
+status=em-andamento
+
+last_done=T-042-002 fetching-supabase
+current=T-042-003 form-pagamento
+next=T-042-004 resumo-pedido
+
+blockers=
+notes=fetch usa server component em app/checkout/page.tsx
+```
+
+### Playbook completo
 
-Playbook completo: [`.gos/playbooks/plan-creation-playbook.md`](./.gos/playbooks/plan-creation-playbook.md).
+[`.gos/playbooks/plan-creation-playbook.md`](./.gos/playbooks/plan-creation-playbook.md) — documenta o fluxo end-to-end com troubleshooting.
 
 ## Documentacao
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ganbatte-os",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "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",