up-cc 2.0.3 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "up-cc",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "description": "Spec-driven development for Claude Code, Gemini, OpenCode and OpenAI Codex. Brainstorm-first, GitHub-native, TDD por tipo.",
   "bin": {
     "up-cc": "up/bin/install.js"

package/up/CHANGELOG.md

@@ -4,6 +4,85 @@ Todas as mudancas relevantes do `up-cc` ficam documentadas aqui. O formato segue
 o espirito de [Keep a Changelog](https://keepachangelog.com/) e o versionamento
 e [SemVer](https://semver.org/). v2.0.0 e um **major** (breaking change).
 
+## 2.2.0
+
+> O `.plano/` sempre sobreviveu ao `/clear` no DISCO, mas a RETOMADA era pull: o
+> hook reinjetava so a doutrina e o agente tinha que escolher ler o STATE.md. Agora
+> e push: o SessionStart injeta a posicao atual sozinho.
+
+### Corrigido
+
+- **SessionStart agora injeta `.plano/STATE.md`, nao so a doutrina.** O hook
+  `up-session-start.js` le `<cwd>/.plano/STATE.md` (cwd do payload, fallback
+  `process.cwd()`) e injeta um trecho capado (2800 chars) num bloco
+  `<UP-ESTADO-ATUAL>` junto do bootstrap. Resultado: a cada `/clear` (e no
+  startup) a posicao do projeto volta pro contexto **deterministicamente**, sem
+  depender do agente escolher ler. Resolve o "as vezes nao sobrevive ao /clear".
+  Fail-open mantido: sem `.plano`, so a doutrina (comportamento anterior). Head
+  bruto, independe do formato PT/EN do STATE.md.
+
+### Testes
+
+- `up/hooks/up-session-start.test.cjs`: 5 casos red-green invocando o hook como
+  subprocesso (stdin->stdout), cobrindo clear/startup com e sem `.plano`, skip de
+  `resume`, e cap de STATE.md gigante.
+
+### Conhecido (nao corrigido aqui)
+
+- `up-tools state-snapshot` parseia rotulos em INGLES e os STATE.md reais sao em
+  PORTUGUES, entao retorna campos null em projeto real. O hook NAO usa
+  state-snapshot (le STATE.md direto), entao a retomada nao e afetada. Fica
+  registrado pra um fix futuro do parser.
+
+## 2.1.0
+
+> GitHub e a interacao humana viram **eixos separados**. Antes, `--solo` desligava o
+> GitHub (zero worktree/issue/PR) E pulava a cerimonia. Num run autonomo/loop isso fazia
+> o projeto inteiro ir pro `main` sem nenhum artefato GitHub, mesmo com remote conectado.
+> Agora `--solo` NAO desliga o GitHub: e so autonomia. Pra pular o GitHub use `--local`.
+
+### Mudado (atencao: semantica de `--solo`)
+
+- **`--solo` agora MANTEM o GitHub-nativo.** Solo virou "autonomo total": cria
+  worktree + branch + issue + PR e auto-mergeia, SEM menu e SEM gate visual (pra
+  loop/headless onde ninguem aprova). Nao desliga mais o GitHub.
+- **`--local` e o novo escape hatch sem GitHub** (o comportamento que `--solo` tinha
+  ate a 2.0.x): commit atomico na branch atual, zero worktree/issue/PR/rede. `/up:rapido`
+  segue como o atalho nomeado pro mesmo modo.
+- **`--auto`** continua igual: pula so o menu de fim de fase, mantem GitHub, e o gate
+  visual ainda roda se `require_visual_test=true`.
+
+### Adicionado
+
+- **Deteccao de GitHub por `gh` CLI OU MCP do GitHub.** O eixo GitHub liga sempre que
+  ha remote + (`gh` autenticado OU MCP do GitHub conectado). Transporte de issue/PR:
+  `gh` (CLI cria direto), `mcp` (o workflow cria via `mcp__...github__*` e grava de
+  volta), `none` (sem remote -> git local). Worktree/branch/push sao git local e
+  acontecem sempre, offline-ok.
+- **Subcomandos `github record-issue` / `github record-pr`** no `up-tools.cjs` pra
+  gravar no `git-map.json` artefatos criados fora do `.cjs` (ex: via MCP). `record-pr
+  --merged` fecha a fase e limpa worktree+branch.
+- **Flag `--local`** no `/up:build` e `start-phase`/`finish-phase` (`--mode local`).
+- **Config builder grava `github_native: true` explicito** (up-arquiteto, workflows/up),
+  deixando a intencao visivel em run autonomo (antes dependia do default implicito).
+- **Testes red-green** do `github.cjs` em `up/bin/lib/github.test.cjs` (10 casos; repo
+  git temp + remote bare local + seam `UP_FORCE_NO_GH`).
+
+### Corrigido
+
+- **Bug de doc em `workflows/up.md`** que dizia `--solo (default, commit na branch atual)`
+  e descrevia `--pr` como o fluxo GitHub (vocabulario v1). Era a unica fonte que podia
+  induzir um agente autonomo a escolher `--solo` e pular o GitHub. Reescrito pro v2.
+- **`--local` numa fase nao polui mais o `github_native` global** do `git-map.json`
+  (poderia degradar fases nao-local seguintes). `finish-phase auto` passou a consultar
+  o config, nao o flag global do mapa.
+
+### Migracao
+
+- Quem usava `--solo` pra **commit local sem GitHub** deve trocar para `--local`.
+- Quem quer **autonomo mantendo GitHub** (loop/headless): use `--solo` (sem gate visual)
+  ou `--auto` (com gate visual se `require_visual_test=true`).
+
 ## 2.0.0
 
 > Redesign completo do UP. **Breaking change.** Os comandos antigos somem (nao ha

package/up/agents/up-arquiteto.md

@@ -305,11 +305,14 @@ Modo builder ativo. Proxima acao: planejar fase 1.
   "granularity": "standard",
   "parallelization": true,
   "commit_docs": true,
-  "builder_mode": true
+  "builder_mode": true,
+  "github_native": true
 }
 ```
 
-Note: `builder_mode: true` sinaliza que o projeto foi criado em modo autonomo.
+Note: `builder_mode: true` sinaliza que o projeto foi criado em modo autonomo. `github_native: true`
+explicito deixa a intencao gravada no arquivo (o build usa true por default; gravar evita ambiguidade
+em run autonomo/loop). So mude pra `false` se o projeto e local sem GitHub.
 </state_and_config>
 
 <brownfield_mode>

package/up/bin/lib/core.cjs

@@ -114,8 +114,9 @@ function loadConfig(cwd) {
     auto_advance: false,
     instrumentation: { enabled: true },
     budget_ceiling: null,
-    // Fase 4: GitHub-native e o PADRAO. --solo no comando forca github_native=false
-    // so na execucao (o build.md le a flag e roteia para o modo solo, sem persistir).
+    // GitHub-native e o PADRAO. So --local (ou este flag = false) desliga. --solo NAO
+    // desliga: solo = autonomia (sem menu/gate visual), GitHub segue ligado. Transporte
+    // de issue/PR: gh CLI OU MCP do GitHub (worktree/branch sao git local, sempre rodam).
     github_native: true,
     merge_strategy: 'squash',
     // Fim de fase: se a fase tem UI, sobe dev server e exige aprovacao visual ANTES do merge.

package/up/bin/lib/github.cjs

@@ -34,8 +34,13 @@ function getRemoteUrl(cwd) {
   return res.exitCode === 0 ? res.stdout.trim() : null;
 }
 
-/** `gh` instalado E autenticado? */
+/**
+ * `gh` instalado E autenticado?
+ * Seam de teste: UP_FORCE_NO_GH=1 forca indisponivel; UP_FORCE_GH=1 forca disponivel.
+ */
 function ghAvailable(cwd) {
+  if (process.env.UP_FORCE_NO_GH === '1') return false;
+  if (process.env.UP_FORCE_GH === '1') return true;
   try {
     execSync('gh auth status', { cwd, stdio: 'pipe' });
     return true;
@@ -69,12 +74,34 @@ function execGh(cwd, args) {
   }
 }
 
-/** github-native ativo? (config.github_native default true) AND gh+remote disponiveis. */
-function githubMode(cwd, solo) {
-  if (solo) return false;
+/**
+ * EIXO A — queremos artefatos GitHub (worktree/branch sempre; issue/PR se remote)?
+ * Ligado a menos que: `--local`, config.github_native=false, ou sem remote origin.
+ * NAO depende de `gh`: gh-vs-MCP e o transporte (eixo separado), nao o liga/desliga.
+ */
+function gitWantsRemote(cwd, local) {
+  if (local) return false;
   const config = loadConfig(cwd);
   if (config.github_native === false) return false;
-  return ghAvailable(cwd) && gitHasRemote(cwd);
+  return gitHasRemote(cwd);
+}
+
+/**
+ * Transporte pra criar issue/PR remoto: 'gh' | 'mcp' | 'none'.
+ * - 'gh':  gh CLI disponivel -> github.cjs cria direto (deterministico).
+ * - 'mcp': remote existe mas sem gh -> o WORKFLOW (LLM) cria via MCP do GitHub,
+ *          porque um subprocesso Node nao chama tools MCP. github.cjs sinaliza e
+ *          grava de volta via recordIssue/recordPr.
+ * - 'none': sem remote (ou --local / config off) -> git local puro, sem issue/PR.
+ */
+function issueTransport(cwd, local) {
+  if (!gitWantsRemote(cwd, local)) return 'none';
+  return ghAvailable(cwd) ? 'gh' : 'mcp';
+}
+
+/** Compat: github-native "classico" = transporte gh disponivel. */
+function githubMode(cwd, local) {
+  return issueTransport(cwd, local) === 'gh';
 }
 
 // =====================================================================
@@ -189,24 +216,27 @@ function phaseKey(phase) {
 // =====================================================================
 
 /**
- * startPhase({cwd, phase, slug, solo})
- * - Cria branch up/fase-NN-slug e worktree FORA do repo.
- * - Se github_native e gh+remote disponiveis: cria gh issue.
- * - Com --solo: degrada (sem worktree, sem issue) — trabalha na branch atual.
- * - Sem gh/remote: cria worktree+branch local, issue=null (fail-open, nunca crasha).
- * - Escreve .plano/git-map.json. Retorna {branch, worktree, issue, issue_url, mode, warnings}.
+ * startPhase({cwd, phase, slug, local, solo})
+ * EIXO A (GitHub) e EIXO B (interacao) sao SEPARADOS:
+ * - `local=true` (flag --local / config off / /up:rapido): SEM worktree/issue, commit
+ *   na branch atual. E o unico jeito de desligar o GitHub aqui.
+ * - `solo` NAO desliga o GitHub: solo so afeta o gate visual e o merge (no build.md).
+ *   Por isso `solo` e aceito mas ignorado neste passo (compat).
+ * - Caso contrario: cria worktree+branch SEMPRE (git local, offline-ok). Issue conforme
+ *   o transporte: 'gh' cria direto; 'mcp' deixa pro workflow criar via MCP (retorna
+ *   `pending.issue` e mode 'github-mcp'); 'none' (sem remote) so git local.
+ * - Escreve .plano/git-map.json. Retorna {branch, worktree, issue, issue_url, mode, transport, warnings, pending?}.
  */
-function startPhase({ cwd, phase, slug, solo = false }) {
+function startPhase({ cwd, phase, slug, local = false, solo = false }) {
+  void solo; // solo nao desliga GitHub (eixo de interacao, tratado no build.md)
   const warnings = [];
   const key = phaseKey(phase);
   const branch = branchName(phase, slug);
-  const ghOn = githubMode(cwd, solo);
 
   const map = readGitMap(cwd);
-  if (solo) map.github_native = false;
 
-  // --- modo SOLO: nada de worktree/issue, trabalha na branch atual ---
-  if (solo) {
+  // --- LOCAL: nada de worktree/issue, trabalha na branch atual ---
+  if (local) {
     const cur = execGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
     const currentBranch = cur.exitCode === 0 ? cur.stdout.trim() : null;
     map.phases[key] = {
@@ -225,22 +255,21 @@ function startPhase({ cwd, phase, slug, solo = false }) {
       worktree: null,
       issue: null,
       issue_url: null,
-      mode: 'solo',
+      mode: 'local',
+      transport: 'none',
       warnings,
     };
   }
 
-  // --- modo GitHub-native ou git-local: criar worktree+branch ---
+  // --- worktree+branch SEMPRE (git local, independe de gh/MCP) ---
   const wt = worktreePath(cwd, phase, slug);
   shieldWorktreeDir(cwd);
 
-  // Worktree e branch existem? (idempotente / recovery)
   const existing = (map.phases[key] && map.phases[key].worktree) || null;
   let worktreeCreated = false;
 
   if (!fs.existsSync(wt)) {
     fs.mkdirSync(path.dirname(wt), { recursive: true });
-    // Branch ja existe? Anexa sem -b. Senao cria com -b.
     const branchExists = execGit(cwd, ['rev-parse', '--verify', '--quiet', branch]).exitCode === 0;
     const wtArgs = branchExists
       ? ['worktree', 'add', wt, branch]
@@ -248,7 +277,6 @@ function startPhase({ cwd, phase, slug, solo = false }) {
     const wtRes = execGit(cwd, wtArgs);
     if (wtRes.exitCode !== 0) {
       warnings.push('worktree_failed: ' + (wtRes.stderr || wtRes.stdout));
-      // FAIL-OPEN: cai pra branch local sem worktree
       const co = execGit(cwd, branchExists ? ['checkout', branch] : ['checkout', '-b', branch]);
       if (co.exitCode !== 0) warnings.push('branch_checkout_failed: ' + (co.stderr || co.stdout));
     } else {
@@ -259,13 +287,16 @@ function startPhase({ cwd, phase, slug, solo = false }) {
   }
   const worktree = worktreeCreated || existing ? wt : null;
 
-  // --- issue (so em github-native) ---
+  // --- issue: depende do transporte (gh | mcp | none) ---
+  const transport = issueTransport(cwd, local);
   let issue = null;
   let issueUrl = null;
-  if (ghOn) {
-    const title = `[fase ${padPhase(phase)}] ${slug || branch}`;
-    const body = buildIssueBody(cwd, phase, slug);
-    const res = execGh(cwd, ['issue', 'create', '--title', title, '--body', body]);
+  let pending = null;
+  const issueTitle = `[fase ${padPhase(phase)}] ${slug || branch}`;
+  const issueBody = buildIssueBody(cwd, phase, slug);
+
+  if (transport === 'gh') {
+    const res = execGh(cwd, ['issue', 'create', '--title', issueTitle, '--body', issueBody]);
     if (res.exitCode === 0) {
       issueUrl = res.stdout.trim().split('\n').pop().trim() || null;
       const m = issueUrl && issueUrl.match(/\/issues\/(\d+)/);
@@ -273,9 +304,13 @@ function startPhase({ cwd, phase, slug, solo = false }) {
     } else {
       warnings.push('issue_create_failed: ' + (res.stderr || res.stdout));
     }
-  } else if (!solo) {
-    if (!ghAvailable(cwd)) warnings.push('gh indisponivel ou nao autenticado: degradando para git local (sem issue/PR)');
-    else if (!gitHasRemote(cwd)) warnings.push('sem remote origin: degradando para git local (sem issue/PR)');
+  } else if (transport === 'mcp') {
+    // Node nao chama MCP: o workflow cria a issue via mcp__...github__issue_write
+    // e grava de volta com `up-tools github record-issue`. Worktree/branch ja existem.
+    pending = { issue: { title: issueTitle, body: issueBody } };
+    warnings.push('gh indisponivel: criar issue via MCP (github-mcp) e gravar com record-issue. worktree/branch ja prontos.');
+  } else {
+    warnings.push('sem remote origin: git local (sem issue/PR).');
   }
 
   map.phases[key] = {
@@ -290,14 +325,10 @@ function startPhase({ cwd, phase, slug, solo = false }) {
   };
   writeGitMap(cwd, map);
 
-  return {
-    branch,
-    worktree,
-    issue,
-    issue_url: issueUrl,
-    mode: ghOn ? 'github' : 'git-local',
-    warnings,
-  };
+  const mode = transport === 'gh' ? 'github' : transport === 'mcp' ? 'github-mcp' : 'git-local';
+  const ret = { branch, worktree, issue, issue_url: issueUrl, mode, transport, warnings };
+  if (pending) ret.pending = pending;
+  return ret;
 }
 
 /** Body da issue: goal + criterios do ROADMAP, se disponiveis. */
@@ -317,12 +348,34 @@ function buildIssueBody(cwd, phase, slug) {
 // finishPhase — solo | menu | auto/pr
 // =====================================================================
 
+/** Remove worktree + branch local (best-effort). Usado por finishPhase e recordPr. */
+function cleanupWorktreeBranch(cwd, worktree, branch, warnings) {
+  if (worktree && fs.existsSync(worktree)) {
+    const rm = execGit(cwd, ['worktree', 'remove', worktree]);
+    if (rm.exitCode !== 0) {
+      const rmF = execGit(cwd, ['worktree', 'remove', '--force', worktree]);
+      if (rmF.exitCode !== 0) warnings.push('worktree_remove_failed: ' + (rmF.stderr || rmF.stdout));
+    }
+    try { if (fs.existsSync(worktree)) fs.rmdirSync(worktree); } catch (e) { /* nao-vazio: ignora */ }
+    try {
+      const parent = path.dirname(worktree);
+      if (fs.existsSync(parent) && fs.readdirSync(parent).length === 0) fs.rmdirSync(parent);
+    } catch (e) { /* ignora */ }
+  }
+  if (branch) {
+    execGit(cwd, ['branch', '-D', branch]); // silencioso: gh/merge ja pode ter removido
+  }
+}
+
 /**
  * finishPhase({cwd, phase, mode, strategy})
- * - solo: nao faz nada (ja committado na branch atual). Marca status=done.
+ * - local (alias 'solo'): nao faz nada (ja committado na branch atual). status=done.
  * - menu: imprime as 4 opcoes pro orquestrador perguntar (nao age).
- * - auto (a.k.a. pr): gh pr create (body "Closes #<issue>") -> merge (squash default)
- *   -> cleanup worktree+branch. Sem remote: merge LOCAL da branch na base, cleanup.
+ * - auto (a.k.a. pr): conforme o transporte ('gh' | 'mcp' | 'none'):
+ *     'gh'   -> push + gh pr create (Closes #issue) + merge + cleanup.
+ *     'mcp'  -> push e PARA: retorna action 'needs-mcp-pr' + pr_payload pro workflow
+ *               criar/mergear o PR via MCP e fechar com `record-pr --merged` (que limpa).
+ *     'none' -> merge LOCAL fail-open + cleanup.
  * Atualiza git-map.json. Retorna estado da operacao.
  */
 function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
@@ -332,12 +385,12 @@ function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
   const entry = map.phases[key] || {};
   const mergeStrategy = strategy || map.merge_strategy || loadConfig(cwd).merge_strategy || 'squash';
 
-  // --- SOLO: nada a fazer, ja committado ---
-  if (mode === 'solo') {
+  // --- LOCAL / SOLO: nada a fazer, ja committado ---
+  if (mode === 'local' || mode === 'solo') {
     entry.status = 'done';
     map.phases[key] = entry;
     writeGitMap(cwd, map);
-    return { mode: 'solo', action: 'none', status: 'done', warnings };
+    return { mode, action: 'none', status: 'done', warnings };
   }
 
   // --- MENU: imprime as 4 opcoes, nao age ---
@@ -361,7 +414,10 @@ function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
   if (mode === 'auto' || mode === 'pr') {
     const branch = entry.branch || branchName(phase, '');
     const worktree = entry.worktree || null;
-    const ghOn = ghAvailable(cwd) && gitHasRemote(cwd) && map.github_native !== false;
+    // mode 'auto' ja significa "quero GitHub": consulta o config (intencao do projeto),
+    // nao o flag global do git-map (que uma fase --local anterior poderia ter mexido).
+    const wants = gitHasRemote(cwd) && loadConfig(cwd).github_native !== false;
+    const transport = wants ? (ghAvailable(cwd) ? 'gh' : 'mcp') : 'none';
 
     // Base de merge (default: branch ativa na main do repo)
     const baseRes = execGit(cwd, ['symbolic-ref', '--short', 'HEAD']);
@@ -370,16 +426,41 @@ function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
     let pr = entry.pr || null;
     let prUrl = entry.pr_url || null;
 
-    if (ghOn) {
-      // push da branch (necessario pro PR). Worktree ja tem a branch checada.
+    const issueRef = entry.issue ? `\n\nCloses #${entry.issue}` : '';
+    const prTitle = `Fase ${padPhase(phase)}` + (entry.branch ? `: ${entry.branch.replace(/^up\/fase-\d+-?/, '')}` : '');
+    const prBody = `Entrega da fase ${padPhase(phase)} (UP github-native).${issueRef}`;
+
+    // push da branch (necessario pro PR, gh OU MCP). Worktree tem a branch checada.
+    if (transport === 'gh' || transport === 'mcp') {
       const pushCwd = worktree && fs.existsSync(worktree) ? worktree : cwd;
       const push = execGit(pushCwd, ['push', '-u', 'origin', branch]);
       if (push.exitCode !== 0) warnings.push('push_failed: ' + (push.stderr || push.stdout));
+    }
 
-      // gh pr create (Closes #issue no body)
-      const issueRef = entry.issue ? `\n\nCloses #${entry.issue}` : '';
-      const prTitle = `Fase ${padPhase(phase)}` + (entry.branch ? `: ${entry.branch.replace(/^up\/fase-\d+-?/, '')}` : '');
-      const prBody = `Entrega da fase ${padPhase(phase)} (UP github-native).${issueRef}`;
+    // --- transporte MCP: push feito, PR fica pro workflow (LLM) via MCP ---
+    if (transport === 'mcp') {
+      map.phases[key] = entry; // status segue in_progress ate record-pr
+      writeGitMap(cwd, map);
+      return {
+        mode,
+        action: 'needs-mcp-pr',
+        transport: 'mcp',
+        pr_payload: {
+          base,
+          head: branch,
+          title: prTitle,
+          body: prBody,
+          issue: entry.issue || null,
+          strategy: mergeStrategy,
+          worktree,
+        },
+        branch,
+        status: entry.status || 'in_progress',
+        warnings,
+      };
+    }
+
+    if (transport === 'gh') {
       const create = execGh(cwd, ['pr', 'create', '--base', base, '--head', branch, '--title', prTitle, '--body', prBody]);
       if (create.exitCode === 0) {
         prUrl = create.stdout.trim().split('\n').pop().trim() || null;
@@ -389,7 +470,6 @@ function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
         warnings.push('pr_create_failed: ' + (create.stderr || create.stdout));
       }
 
-      // merge via gh
       const stratFlag = mergeStrategy === 'merge' ? '--merge' : mergeStrategy === 'rebase' ? '--rebase' : '--squash';
       const mergeTarget = pr ? String(pr) : branch;
       const merge = execGh(cwd, ['pr', 'merge', mergeTarget, stratFlag, '--delete-branch']);
@@ -401,7 +481,6 @@ function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
     } else {
       // FAIL-OPEN: merge LOCAL (sem remote/gh)
       warnings.push('sem gh/remote: merge local da branch ' + branch + ' em ' + base);
-      // Garante base checada no repo principal
       const co = execGit(cwd, ['checkout', base]);
       if (co.exitCode !== 0) warnings.push('checkout_base_failed: ' + (co.stderr || co.stdout));
       const stratArgs = mergeStrategy === 'squash'
@@ -421,35 +500,19 @@ function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
       }
     }
 
-    // cleanup: remove worktree e branch local
-    if (worktree && fs.existsSync(worktree)) {
-      const rm = execGit(cwd, ['worktree', 'remove', worktree]);
-      if (rm.exitCode !== 0) {
-        const rmF = execGit(cwd, ['worktree', 'remove', '--force', worktree]);
-        if (rmF.exitCode !== 0) warnings.push('worktree_remove_failed: ' + (rmF.stderr || rmF.stdout));
-      }
-      // best-effort: remove a casca vazia que git deixa, e o dir-pai .up-worktrees/<repo> se vazio
-      try { if (fs.existsSync(worktree)) fs.rmdirSync(worktree); } catch (e) { /* nao-vazio: ignora */ }
-      try {
-        const parent = path.dirname(worktree);
-        if (fs.existsSync(parent) && fs.readdirSync(parent).length === 0) fs.rmdirSync(parent);
-      } catch (e) { /* ignora */ }
-    }
-    // remove branch local (se ainda existir e nao for a branch ativa)
-    const delBranch = execGit(cwd, ['branch', '-D', branch]);
-    if (delBranch.exitCode !== 0 && !/not found|não encontrad/i.test(delBranch.stderr)) {
-      // silencioso: gh --delete-branch ja pode ter removido
-    }
+    cleanupWorktreeBranch(cwd, worktree, branch, warnings);
 
     entry.pr = pr;
     entry.pr_url = prUrl;
-    if (!entry.status || entry.status === 'in_progress') entry.status = ghOn ? 'merged' : entry.status;
+    entry.worktree = null;
+    if (!entry.status || entry.status === 'in_progress') entry.status = transport === 'gh' ? 'merged' : entry.status;
     map.phases[key] = entry;
     writeGitMap(cwd, map);
 
     return {
-      mode: mode,
+      mode,
       action: 'merged',
+      transport,
       pr,
       pr_url: prUrl,
       branch,
@@ -459,10 +522,47 @@ function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
     };
   }
 
-  warnings.push('modo desconhecido: ' + mode + ' (use solo|menu|auto)');
+  warnings.push('modo desconhecido: ' + mode + ' (use local|menu|auto)');
   return { mode, action: 'noop', warnings };
 }
 
+// =====================================================================
+// recordIssue / recordPr — gravam artefatos criados FORA (via MCP no workflow)
+// =====================================================================
+
+/** Grava no git-map a issue criada externamente (ex: via MCP). */
+function recordIssue({ cwd, phase, issue, url }) {
+  const key = phaseKey(phase);
+  const map = readGitMap(cwd);
+  const entry = map.phases[key] || {};
+  if (issue != null && issue !== '') entry.issue = parseInt(issue, 10);
+  if (url) entry.issue_url = url;
+  map.phases[key] = entry;
+  writeGitMap(cwd, map);
+  return { recorded: true, phase: key, issue: entry.issue ?? null, issue_url: entry.issue_url || null };
+}
+
+/**
+ * Grava no git-map o PR criado externamente (ex: via MCP).
+ * Com `merged=true`: marca status=merged e limpa worktree+branch local.
+ */
+function recordPr({ cwd, phase, pr, url, merged = false }) {
+  const warnings = [];
+  const key = phaseKey(phase);
+  const map = readGitMap(cwd);
+  const entry = map.phases[key] || {};
+  if (pr != null && pr !== '') entry.pr = parseInt(pr, 10);
+  if (url) entry.pr_url = url;
+  if (merged) {
+    entry.status = 'merged';
+    cleanupWorktreeBranch(cwd, entry.worktree, entry.branch, warnings);
+    entry.worktree = null;
+  }
+  map.phases[key] = entry;
+  writeGitMap(cwd, map);
+  return { recorded: true, phase: key, pr: entry.pr ?? null, pr_url: entry.pr_url || null, status: entry.status || null, merged: !!merged, warnings };
+}
+
 // =====================================================================
 // status — mostra git-map.json
 // =====================================================================
@@ -470,12 +570,16 @@ function finishPhase({ cwd, phase, mode = 'menu', strategy }) {
 /** status({cwd}) — retorna o git-map.json atual (ou defaults se nao existir). Nunca crasha. */
 function status({ cwd }) {
   const map = readGitMap(cwd);
+  const hasRemote = gitHasRemote(cwd);
+  const ghOk = ghAvailable(cwd);
   return {
     github_native: map.github_native,
     merge_strategy: map.merge_strategy,
-    gh_available: ghAvailable(cwd),
-    has_remote: gitHasRemote(cwd),
+    gh_available: ghOk,
+    has_remote: hasRemote,
     remote: getRemoteUrl(cwd),
+    // transporte efetivo pra issue/PR: 'gh' | 'mcp' | 'none' (assumindo nao-local)
+    transport: hasRemote && map.github_native !== false ? (ghOk ? 'gh' : 'mcp') : 'none',
     phases: map.phases,
   };
 }
@@ -483,13 +587,18 @@ function status({ cwd }) {
 module.exports = {
   startPhase,
   finishPhase,
+  recordIssue,
+  recordPr,
   status,
   // helpers expostos para teste/reuso
   branchName,
   worktreePath,
   gitHasRemote,
   ghAvailable,
+  gitWantsRemote,
+  issueTransport,
   githubMode,
+  cleanupWorktreeBranch,
   readGitMap,
   writeGitMap,
 };