up-cc 2.0.3 → 2.2.0

package/up/bin/lib/github.test.cjs

@@ -0,0 +1,161 @@
+/**
+ * github.test.cjs — testes red-green do github.cjs (eixo GitHub vs interacao).
+ * Roda: node up/bin/lib/github.test.cjs
+ * Sem framework. Cria repos git temporarios. Usa remote bare local (push sem rede)
+ * e o seam UP_FORCE_NO_GH=1 pra simular "sem gh CLI, so MCP".
+ */
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+const gh = require('./github.cjs');
+
+process.env.GIT_TERMINAL_PROMPT = '0';
+
+function sh(cmd, cwd) { execSync(cmd, { cwd, stdio: 'pipe' }); }
+
+/** Cria repo git temp. withRemote=true adiciona origin = bare repo local. */
+function mkRepo(withRemote) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'up-gh-'));
+  sh('git init -q', dir);
+  sh('git config user.email t@t.co', dir);
+  sh('git config user.name t', dir);
+  sh('git config commit.gpgsign false', dir);
+  fs.writeFileSync(path.join(dir, 'README.md'), '# t\n');
+  sh('git add -A', dir);
+  sh('git commit -qm init', dir);
+  sh('git branch -M main', dir);
+  fs.mkdirSync(path.join(dir, '.plano'), { recursive: true });
+  let bare = null;
+  if (withRemote) {
+    bare = fs.mkdtempSync(path.join(os.tmpdir(), 'up-gh-bare-'));
+    sh('git init -q --bare', bare);
+    sh(`git remote add origin ${bare}`, dir);
+  }
+  return { dir, bare };
+}
+
+let pass = 0, fail = 0;
+function t(name, fn) {
+  try { fn(); console.log('  ok  -', name); pass++; }
+  catch (e) { console.error('  FAIL -', name, '\n     ', e.message); fail++; }
+}
+
+// 1. local=true -> sem worktree/issue, branch atual, mode local
+t('local: sem worktree/issue, branch atual', () => {
+  const { dir } = mkRepo(false);
+  const r = gh.startPhase({ cwd: dir, phase: 1, slug: 'x', local: true });
+  assert.strictEqual(r.worktree, null);
+  assert.strictEqual(r.issue, null);
+  assert.strictEqual(r.mode, 'local');
+  assert.strictEqual(r.transport, 'none');
+  assert.strictEqual(r.branch, 'main');
+});
+
+// 2. sem remote, nao-local -> worktree criado, git-local, sem issue
+t('sem remote: worktree criado, git-local', () => {
+  const { dir } = mkRepo(false);
+  const r = gh.startPhase({ cwd: dir, phase: 2, slug: 'feat' });
+  assert.ok(r.worktree && fs.existsSync(r.worktree), 'worktree deve existir');
+  assert.strictEqual(r.mode, 'git-local');
+  assert.strictEqual(r.transport, 'none');
+  assert.strictEqual(r.issue, null);
+  assert.strictEqual(r.branch, 'up/fase-02-feat');
+});
+
+// 3. remote + sem gh -> github-mcp, worktree criado, pending.issue, transport mcp
+t('remote sem gh: github-mcp pendente', () => {
+  const { dir } = mkRepo(true);
+  process.env.UP_FORCE_NO_GH = '1';
+  try {
+    const r = gh.startPhase({ cwd: dir, phase: 3, slug: 'mcp' });
+    assert.strictEqual(r.transport, 'mcp');
+    assert.strictEqual(r.mode, 'github-mcp');
+    assert.ok(r.worktree && fs.existsSync(r.worktree), 'worktree deve existir mesmo sem gh');
+    assert.strictEqual(r.issue, null);
+    assert.ok(r.pending && r.pending.issue && r.pending.issue.title, 'deve trazer pending.issue.title');
+  } finally { delete process.env.UP_FORCE_NO_GH; }
+});
+
+// 4. REGRESSAO do bug: solo NAO desliga github
+t('solo nao desliga github (vira github-mcp, nao local)', () => {
+  const { dir } = mkRepo(true);
+  process.env.UP_FORCE_NO_GH = '1';
+  try {
+    const r = gh.startPhase({ cwd: dir, phase: 4, slug: 's', solo: true });
+    assert.notStrictEqual(r.mode, 'local');
+    assert.ok(r.worktree && fs.existsSync(r.worktree), 'solo deve criar worktree');
+    assert.strictEqual(r.transport, 'mcp');
+  } finally { delete process.env.UP_FORCE_NO_GH; }
+});
+
+// 5. recordIssue grava no git-map
+t('recordIssue grava issue no git-map', () => {
+  const { dir } = mkRepo(true);
+  process.env.UP_FORCE_NO_GH = '1';
+  try {
+    gh.startPhase({ cwd: dir, phase: 5, slug: 'r' });
+    const r = gh.recordIssue({ cwd: dir, phase: 5, issue: 42, url: 'https://github.com/x/y/issues/42' });
+    assert.strictEqual(r.issue, 42);
+    const map = gh.readGitMap(dir);
+    assert.strictEqual(map.phases['5'].issue, 42);
+    assert.strictEqual(map.phases['5'].issue_url, 'https://github.com/x/y/issues/42');
+  } finally { delete process.env.UP_FORCE_NO_GH; }
+});
+
+// 6. issueTransport puro
+t('issueTransport: local->none; sem remote->none', () => {
+  const { dir } = mkRepo(false);
+  assert.strictEqual(gh.issueTransport(dir, true), 'none');
+  assert.strictEqual(gh.issueTransport(dir, false), 'none');
+});
+
+// 7. finish mode local -> noop, done
+t('finish local: noop status done', () => {
+  const { dir } = mkRepo(false);
+  gh.startPhase({ cwd: dir, phase: 7, slug: 'l', local: true });
+  const r = gh.finishPhase({ cwd: dir, phase: 7, mode: 'local' });
+  assert.strictEqual(r.status, 'done');
+});
+
+// 8. finish auto sem remote -> merge local fail-open
+t('finish auto sem remote: merge local', () => {
+  const { dir } = mkRepo(false);
+  const s = gh.startPhase({ cwd: dir, phase: 8, slug: 'm' });
+  fs.writeFileSync(path.join(s.worktree, 'f.txt'), 'x');
+  sh('git add -A', s.worktree);
+  sh('git commit -qm w', s.worktree);
+  const r = gh.finishPhase({ cwd: dir, phase: 8, mode: 'auto' });
+  assert.strictEqual(r.status, 'merged');
+});
+
+// 9. finish auto, remote sem gh -> needs-mcp-pr + payload (push pro bare local funciona)
+t('finish auto remote sem gh: sinaliza needs-mcp-pr', () => {
+  const { dir } = mkRepo(true);
+  const s = gh.startPhase({ cwd: dir, phase: 9, slug: 'p' });
+  fs.writeFileSync(path.join(s.worktree, 'f.txt'), 'x');
+  sh('git add -A', s.worktree);
+  sh('git commit -qm w', s.worktree);
+  process.env.UP_FORCE_NO_GH = '1';
+  try {
+    const r = gh.finishPhase({ cwd: dir, phase: 9, mode: 'auto' });
+    assert.strictEqual(r.action, 'needs-mcp-pr');
+    assert.ok(r.pr_payload && r.pr_payload.head, 'deve trazer pr_payload.head');
+    assert.strictEqual(r.pr_payload.head, 'up/fase-09-p');
+  } finally { delete process.env.UP_FORCE_NO_GH; }
+});
+
+// 10. recordPr --merged grava pr e limpa worktree
+t('recordPr merged: grava pr, status merged, limpa worktree', () => {
+  const { dir } = mkRepo(true);
+  const s = gh.startPhase({ cwd: dir, phase: 10, slug: 'pr' });
+  const wt = s.worktree;
+  const r = gh.recordPr({ cwd: dir, phase: 10, pr: 7, url: 'https://github.com/x/y/pull/7', merged: true });
+  assert.strictEqual(r.pr, 7);
+  assert.strictEqual(r.status, 'merged');
+  assert.ok(!fs.existsSync(wt), 'worktree deve ter sido removida');
+});
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/up/bin/up-tools.cjs

@@ -352,11 +352,14 @@ function main() {
       if (sub === 'start-phase') {
         const phase = getFlag('--phase');
         const slug = getFlag('--slug');
-        if (!phase) error('Usage: github start-phase --phase N --slug S [--solo]');
+        if (!phase) error('Usage: github start-phase --phase N --slug S [--local]');
+        // --local desliga GitHub (commit na branch atual). --solo NAO desliga mais
+        // (so afeta gate visual/merge no build.md); aceito por compat, ignorado aqui.
         const result = github.startPhase({
           cwd,
           phase,
           slug: slug || '',
+          local: hasFlag('--local'),
           solo: hasFlag('--solo'),
         });
         output(result, raw, JSON.stringify(result));
@@ -364,14 +367,28 @@ function main() {
         const phase = getFlag('--phase');
         const mode = getFlag('--mode') || 'menu';
         const strategy = getFlag('--strategy');
-        if (!phase) error('Usage: github finish-phase --phase N --mode menu|auto|solo [--strategy squash|merge|rebase]');
+        if (!phase) error('Usage: github finish-phase --phase N --mode menu|auto|local [--strategy squash|merge|rebase]');
         const result = github.finishPhase({ cwd, phase, mode, strategy });
         output(result, raw, JSON.stringify(result));
+      } else if (sub === 'record-issue') {
+        const phase = getFlag('--phase');
+        const issue = getFlag('--issue');
+        const url = getFlag('--url');
+        if (!phase || !issue) error('Usage: github record-issue --phase N --issue <num> [--url <url>]');
+        const result = github.recordIssue({ cwd, phase, issue, url });
+        output(result, raw, JSON.stringify(result));
+      } else if (sub === 'record-pr') {
+        const phase = getFlag('--phase');
+        const pr = getFlag('--pr');
+        const url = getFlag('--url');
+        if (!phase || !pr) error('Usage: github record-pr --phase N --pr <num> [--url <url>] [--merged]');
+        const result = github.recordPr({ cwd, phase, pr, url, merged: hasFlag('--merged') });
+        output(result, raw, JSON.stringify(result));
       } else if (sub === 'status') {
         const result = github.status({ cwd });
         output(result, raw, JSON.stringify(result));
       } else {
-        error('Unknown github subcommand. Available: start-phase, finish-phase, status');
+        error('Unknown github subcommand. Available: start-phase, finish-phase, record-issue, record-pr, status');
       }
       break;
     }

package/up/commands/build.md

@@ -1,7 +1,7 @@
 ---
 name: up:build
-description: Use quando o usuario quer EXECUTAR um projeto ja planejado (existe .plano/PLAN-READY.md). Default GitHub-nativo por fase (worktree, issue, PR, merge). Flag --solo pula a cerimonia (commit atomico na branch atual); --board espelha no Multica; --auto pula o menu de fim de fase.
-argument-hint: "[--solo] [--board] [--auto]"
+description: Use quando o usuario quer EXECUTAR um projeto ja planejado (existe .plano/PLAN-READY.md). Default GitHub-nativo por fase (worktree, issue, PR, merge) via gh OU MCP. Flag --solo = autonomo total mantendo GitHub (sem menu, sem gate visual); --auto pula so o menu; --local pula o GitHub (commit atomico na branch atual); --board espelha no Multica.
+argument-hint: "[--solo] [--auto] [--local] [--board]"
 allowed-tools:
   - Read
   - Write
@@ -40,11 +40,12 @@ Exemplo: planejou em Claude Code (`/up:plan "X"`), agora roda em OpenCode (`/up-
 <context>
 $ARGUMENTS
 
-**Flags:**
-- (sem flag) = **GitHub-nativo, o DEFAULT** (`config.github_native=true`): cada fase abre worktree + branch `up/fase-NN-slug` + issue, executa, sobe o dev server pra teste visual (se houver UI) e oferece o menu de fim de fase.
-- `--solo` - **ESCAPE HATCH**. Forca `github_native=false` so nesta execucao: commit atomico na branch ATUAL, zero worktree/issue/PR/board.
+**Flags** (GitHub e a interacao humana sao eixos SEPARADOS; as flags so mexem na interacao):
+- (sem flag) = **GitHub-nativo, o DEFAULT** (`config.github_native=true`): cada fase abre worktree + branch `up/fase-NN-slug` + issue (via `gh` OU MCP do GitHub), executa, sobe o dev server pra teste visual (se houver UI) e oferece o menu de fim de fase.
+- `--solo` - **autonomo total**. NAO desliga o GitHub: cria worktree/branch/issue/PR e auto-mergeia, SEM menu e SEM gate visual. Pra loop/headless.
+- `--auto` - pula so o menu de fim de fase (merge automatico). Mantem GitHub. O teste visual ainda roda se `require_visual_test=true`.
+- `--local` - **ESCAPE HATCH sem GitHub**. Commit atomico na branch ATUAL, zero worktree/issue/PR/board. (Mesmo que `/up:rapido`.) Unico jeito de pular o GitHub.
 - `--board` - espelha o progresso das fases no Multica (board opt-in, batched, fail-open).
-- `--auto` - pula o menu de fim de fase (merge automatico). O teste visual ainda roda se `require_visual_test=true`.
 
 O comando le o resto de `.plano/PLAN-READY.md`.
 </context>
@@ -75,23 +76,23 @@ Se algo falta: alertar e oferecer planejamento local OU abortar.
 
 **Sem model routing:** O runtime decide o modelo.
 
-**Parsear flags primeiro:** extrair `--solo`/`--board`/`--auto`. Sem flag = GitHub-nativo (default).
+**Parsear flags primeiro:** extrair `--solo`/`--auto`/`--local`/`--board`. Sem flag = GitHub-nativo (default).
 
 **Modo de orquestracao (resolver antes de comecar):**
-- DEFAULT (sem `--solo`): GitHub-nativo. Por fase: `up-tools.cjs github start-phase` (worktree + branch + issue, fail-open) -> executa as waves -> gate -> teste visual pre-merge (se UI) -> `github finish-phase` (PR -> merge squash -> cleanup) conforme o menu. `--board` adiciona `multica init/sync` (batched). `--auto` pula o menu.
-- `--solo`: executa local, commits atomicos na branch atual. Sem worktree/issue/PR/board.
+- DEFAULT (sem `--local`): GitHub-nativo. Por fase: `up-tools.cjs github start-phase` (worktree + branch + issue via gh OU MCP, fail-open) -> executa as waves -> gate -> teste visual pre-merge (se UI) -> `github finish-phase` (PR -> merge squash -> cleanup) conforme o menu. `--auto` pula o menu (mantem GitHub). `--solo` pula menu E gate visual (autonomo total, mantem GitHub). `--board` adiciona `multica init/sync` (batched).
+- `--local`: executa local, commits atomicos na branch atual. Sem worktree/issue/PR/board.
 
 **Execute the build workflow from @~/.claude/up/workflows/build.md end-to-end.**
 
 Pipeline por fase:
 1. Validacao light
-2. `github start-phase` (worktree + issue; pulado em `--solo`)
+2. `github start-phase` (worktree + issue via gh OU MCP; pulado so em `--local`)
 3. Execucao em WAVES PARALELAS: os planos da mesma wave rodam ao mesmo tempo (varios `up-executor`); waves em sequencia. Re-plan local se algum plano ficar inviavel.
 4. up-verificador emite VERIFICATION.md com evidencia fresca por tipo (TDD-por-tipo: red-green / visual / smoke)
 5. **GATE deterministico** `approvals.log` (governance.md, gate-only; exige `evidence=`)
 6. up-revisor (two-stage: spec-compliance cetico + code-quality) alimenta o gate
 7. **Teste visual pre-merge** (fase de UI e `require_visual_test=true`): sobe o dev server na worktree, "testar primeiro ou pode mergear?", loop de ajuste ate aprovar
-8. **Menu de fim de fase** (GitHub-nativo, fora `--auto`): merge local / abrir PR / deixa a branch / descarta. Em `--solo`, ja committou na branch atual
+8. **Menu de fim de fase** (GitHub-nativo, fora `--auto`/`--solo`): merge local / abrir PR / deixa a branch / descarta. Autonomo (`--solo`/`--auto`) auto-mergeia sem menu. Em `--local`, ja committou na branch atual
 9. Reassessment do roadmap antes da proxima fase
 
 **Re-plan local permitido (max 1 round por fase):**
@@ -102,9 +103,9 @@ Se ficar inviavel, o up-planejador LOCAL refaz a fase. Registrar em `.plano/gove
 
 <success_criteria>
 - [ ] PLAN-READY.md validado
-- [ ] Flags parseadas (default = GitHub-nativo; --solo = escape)
+- [ ] Flags parseadas (default = GitHub-nativo; --solo/--auto = autonomia mantendo GitHub; --local = escape sem GitHub)
 - [ ] Build rodou todas as fases; planos da mesma wave em paralelo
 - [ ] GATE approvals.log respeitado (deterministico, com evidence= por tipo)
-- [ ] Teste visual pre-merge em fase de UI (require_visual_test)
-- [ ] Fechamento por fase: menu (GitHub-nativo) ou commit na branch (--solo)
+- [ ] Teste visual pre-merge em fase de UI (require_visual_test; pulado em --solo)
+- [ ] Fechamento por fase: menu (GitHub-nativo), auto-merge (--solo/--auto) ou commit na branch (--local)
 </success_criteria>

package/up/hooks/up-session-start.js

@@ -53,20 +53,59 @@ function readBootstrap() {
   return FALLBACK_BOOTSTRAP;
 }
 
-function buildContext(bootstrap) {
-  return '<EXTREMELY_IMPORTANT>\n' +
+// Teto do trecho de STATE.md injetado. As secoes uteis (Posicao Atual,
+// Contexto Acumulado, Continuidade de Sessao) vivem no topo do arquivo, entao
+// um head capado retoma a posicao sem estourar o contexto.
+const MAX_STATE_CHARS = 2800;
+
+/**
+ * Le um resumo do estado do projeto em <cwd>/.plano/STATE.md, se existir.
+ * Retorna o trecho capado (string) ou null. PUSH deterministico da posicao:
+ * o agente sempre volta sabendo onde parou, sem depender de escolher ler.
+ * Independe do formato exato (PT/EN) -- e um head bruto, nunca quebra.
+ */
+function readState(cwd) {
+  if (!cwd || typeof cwd !== 'string') return null;
+  try {
+    const statePath = path.join(cwd, '.plano', 'STATE.md');
+    if (!fs.existsSync(statePath)) return null;
+    let content = fs.readFileSync(statePath, 'utf8');
+    if (!content || !content.trim()) return null;
+    content = content.trim();
+    if (content.length > MAX_STATE_CHARS) {
+      content = content.slice(0, MAX_STATE_CHARS).trimEnd() +
+        '\n\n[...truncado -- leia .plano/STATE.md para o resto]';
+    }
+    return content;
+  } catch (e) {
+    return null;
+  }
+}
+
+function buildContext(bootstrap, state) {
+  let ctx = '<EXTREMELY_IMPORTANT>\n' +
     'Voce tem o UP.\n\n' +
     'Abaixo esta o conteudo completo da sua skill \'usando-up\' -- sua introducao a usar ' +
     'as skills do UP. Para todas as outras skills, use a tool Skill:\n\n' +
     bootstrap.trim() + '\n' +
     '</EXTREMELY_IMPORTANT>';
+
+  if (state) {
+    ctx += '\n\n<UP-ESTADO-ATUAL>\n' +
+      'Voce esta retomando um projeto UP em andamento (inicio de sessao ou apos /clear). ' +
+      'NAO comece do zero nem assuma contexto perdido: esta e a posicao atual, lida de ' +
+      '.plano/STATE.md. Continue daqui. Para rotear o proximo passo, use /up sem argumento.\n\n' +
+      state + '\n' +
+      '</UP-ESTADO-ATUAL>';
+  }
+  return ctx;
 }
 
-function emit(bootstrap) {
+function emit(bootstrap, state) {
   const output = {
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
-      additionalContext: buildContext(bootstrap),
+      additionalContext: buildContext(bootstrap, state || null),
     },
   };
   process.stdout.write(JSON.stringify(output));
@@ -74,8 +113,9 @@ function emit(bootstrap) {
 
 let input = '';
 const stdinTimeout = setTimeout(() => {
-  // No stdin within 3s (Windows/Git Bash guard): still inject the bootstrap.
-  try { emit(readBootstrap()); } catch (e) {}
+  // No stdin within 3s (Windows/Git Bash guard): inject the bootstrap.
+  // Sem payload nao ha cwd, entao sem bloco de estado (so a doutrina).
+  try { emit(readBootstrap(), null); } catch (e) {}
   process.exit(0);
 }, 3000);
 
@@ -85,10 +125,13 @@ process.stdin.on('end', () => {
   clearTimeout(stdinTimeout);
   try {
     let source = null;
+    let cwd = null;
     try {
       const data = JSON.parse(input);
-      // SessionStart payload carries the trigger in `source` (startup|clear|compact|resume).
+      // SessionStart payload carries the trigger in `source` (startup|clear|compact|resume)
+      // e o diretorio do projeto em `cwd`.
       source = data && (data.source || data.hook_event_source || null);
+      cwd = (data && data.cwd) || null;
     } catch (e) {
       // No/invalid payload: with no matcher available, inject anyway.
       source = null;
@@ -99,7 +142,9 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
-    emit(readBootstrap());
+    // Sem cwd no payload, cai pro diretorio do processo (o harness roda o hook no cwd da sessao).
+    const projectCwd = cwd || process.cwd();
+    emit(readBootstrap(), readState(projectCwd));
   } catch (e) {
     // Fail-open: never block the session.
   }

package/up/hooks/up-session-start.test.cjs

@@ -0,0 +1,99 @@
+/**
+ * up-session-start.test.cjs - testa a injecao de estado no SessionStart.
+ * Roda: node up/hooks/up-session-start.test.cjs
+ * Invoca o hook como subprocesso (stdin JSON -> stdout JSON), igual o harness faz.
+ */
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const HOOK = path.resolve(__dirname, 'up-session-start.js');
+
+/** Roda o hook com um payload e devolve {additionalContext} ou null. */
+function runHook(payload) {
+  const out = execFileSync('node', [HOOK], {
+    input: JSON.stringify(payload),
+    encoding: 'utf-8',
+    timeout: 8000,
+  });
+  if (!out || !out.trim()) return null;
+  const parsed = JSON.parse(out);
+  return parsed.hookSpecificOutput ? parsed.hookSpecificOutput.additionalContext : null;
+}
+
+function mkProjectWithState(stateBody) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'up-ss-'));
+  fs.mkdirSync(path.join(dir, '.plano'), { recursive: true });
+  fs.writeFileSync(path.join(dir, '.plano', 'STATE.md'), stateBody, 'utf-8');
+  return dir;
+}
+function mkProjectNoPlano() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'up-ss-noplano-'));
+}
+
+let pass = 0, fail = 0;
+function t(name, fn) {
+  try { fn(); console.log('  ok  -', name); pass++; }
+  catch (e) { console.error('  FAIL -', name, '\n     ', e.message); fail++; }
+}
+
+const SAMPLE_STATE = `# Estado do Projeto
+
+## Posicao Atual
+
+Fase: 7 de 10 (Comando /up:melhorias)
+Status: In progress
+Ultima atividade: 2026-06-19 -- T3 do plano 02 concluido
+
+## Continuidade de Sessao
+
+Parou em: implementando o gate de aprovacao visual
+`;
+
+// 1. clear + .plano/STATE.md presente -> injeta bootstrap E o estado
+t('clear com .plano: injeta bootstrap + estado', () => {
+  const dir = mkProjectWithState(SAMPLE_STATE);
+  const ctx = runHook({ source: 'clear', cwd: dir, hook_event_name: 'SessionStart' });
+  assert.ok(ctx, 'deve haver additionalContext');
+  assert.ok(/Voce tem o UP/.test(ctx), 'deve conter a doutrina (bootstrap)');
+  assert.ok(/Fase: 7 de 10/.test(ctx), 'deve conter a posicao do STATE.md');
+  assert.ok(/Parou em: implementando o gate/.test(ctx), 'deve conter onde parou');
+});
+
+// 2. clear SEM .plano -> so bootstrap, sem bloco de estado
+t('clear sem .plano: so bootstrap', () => {
+  const dir = mkProjectNoPlano();
+  const ctx = runHook({ source: 'clear', cwd: dir, hook_event_name: 'SessionStart' });
+  assert.ok(ctx, 'deve haver additionalContext');
+  assert.ok(/Voce tem o UP/.test(ctx), 'deve conter a doutrina');
+  assert.ok(!/UP-ESTADO-ATUAL/.test(ctx), 'NAO deve ter bloco de estado sem .plano');
+});
+
+// 3. startup tambem injeta estado (retomar projeto ao abrir)
+t('startup com .plano: injeta estado', () => {
+  const dir = mkProjectWithState(SAMPLE_STATE);
+  const ctx = runHook({ source: 'startup', cwd: dir, hook_event_name: 'SessionStart' });
+  assert.ok(/Fase: 7 de 10/.test(ctx), 'startup tambem deve trazer o estado');
+});
+
+// 4. source fora dos triggers (resume) -> nada
+t('resume: nenhum output', () => {
+  const dir = mkProjectWithState(SAMPLE_STATE);
+  const ctx = runHook({ source: 'resume', cwd: dir, hook_event_name: 'SessionStart' });
+  assert.strictEqual(ctx, null, 'resume nao deve injetar nada');
+});
+
+// 5. STATE.md gigante -> capado (bloco de estado nao explode o contexto)
+t('STATE.md gigante: capado', () => {
+  const huge = SAMPLE_STATE + '\n' + 'x'.repeat(20000);
+  const dir = mkProjectWithState(huge);
+  const ctx = runHook({ source: 'clear', cwd: dir, hook_event_name: 'SessionStart' });
+  // o bloco de estado deve estar truncado bem abaixo do tamanho do STATE gigante
+  assert.ok(ctx.length < 8000, 'contexto total deve ficar capado (<8000 chars), veio ' + ctx.length);
+  assert.ok(/Fase: 7 de 10/.test(ctx), 'mesmo capado, a posicao do topo deve aparecer');
+});
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/up/skills/usando-up/SKILL.md

@@ -25,7 +25,7 @@ O UP ativa por contexto. Nao precisa decorar comando: a skill certa dispara pelo
 
 **Prova por tipo:** logica/bugfix = teste red-green; UI/CSS = captura visual; glue/integracao = smoke-test. Veja `up-tdd`.
 
-**GitHub-nativo e o padrao em repo colaborativo** (worktree -> issue -> PR -> merge), menu de 4 opcoes no fim. Solo usa `--solo` (commit local) ou `/up:rapido` como escape, sem cerimonia.
+**GitHub-nativo e o padrao** (worktree -> issue -> PR -> merge), via `gh` OU MCP do GitHub, menu de 4 opcoes no fim. `--auto` pula o menu; `--solo` e autonomo total (mantem GitHub, sem menu nem gate visual). Pra pular o GitHub de propósito (commit local puro): `--local` no build ou `/up:rapido`. Atencao: `--solo` NAO desliga mais o GitHub.
 
 **Persistencia:** tudo vive em `.plano/` e sobrevive a `/clear`. Leia `.plano/STATE.md` antes de assumir contexto perdido.