up-cc 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "up-cc",
-  "version": "2.1.0",
+  "version": "2.3.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,52 @@ 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.3.0
+
+> A rodada de perguntas do brainstorm fechava e o agente seguia sozinho pro
+> design. Agora quem fecha a rodada e o usuario, via checkpoint de controle.
+
+### Adicionado
+
+- **Checkpoint de fechamento no `up-brainstorm`.** Toda rodada de perguntas dos
+  tiers Pequena, full e exploracao termina com um AskUserQuestion de 2 opcoes:
+  "Fechar e seguir" (avanca pro proximo passo do tier) ou "Mais perguntas" (abre
+  nova rodada, mais especifica que a anterior, que fecha com o mesmo checkpoint;
+  loop ate o usuario liberar). O "Other" nativo do AskUserQuestion cobre resposta
+  livre. Tier Trivial fica fora (0 perguntas, so anuncia e segue). Os 3 pontos de
+  fluxo (linha Pequena da tabela de profundidade, passo 3 do brainstorm full,
+  passos 4-5 do modo exploracao) referenciam o checkpoint.
+
+## 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

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/up-brainstorm/SKILL.md

@@ -35,7 +35,7 @@ Classifique a tarefa com o `classify-task` do `up-tools.cjs` (tiers: `simple` /
 | Tier | Profundidade |
 |------|--------------|
 | **Trivial** (1 arquivo, sem decisao de arquitetura) | 0 perguntas. Anuncia em 1 linha o que vai fazer e onde. Executa. |
-| **Pequena** (1 subsistema, 1 escolha de design) | 1 pergunta via AskUserQuestion (a decisao-chave) + design em 3 frases. Aprova e segue. |
+| **Pequena** (1 subsistema, 1 escolha de design) | 1 pergunta via AskUserQuestion (a decisao-chave) + checkpoint de fechamento + design em 3 frases. Aprova e segue. |
 | **Media / Grande** (multi-subsistema, toca schema/API/auth) | Brainstorm full. |
 
 O `classify-task` define o PISO (minimo garantido). O usuario sempre pode SUBIR ou DESCER manualmente (override abaixo). Nunca diminua a profundidade por conta propria; so o usuario rebaixa.
@@ -52,6 +52,17 @@ O tier automatico e so o default. O usuario manda na profundidade:
 
 Pressa nunca remove o gate; muda so quantas perguntas.
 
+## Checkpoint de fechamento (toda rodada de perguntas)
+
+Regra transversal aos tiers **Pequena**, **full** e **exploracao**. Tier Trivial fica FORA (0 perguntas, so anuncia e segue).
+
+Toda rodada de perguntas termina com um AskUserQuestion de controle com exatamente 2 opcoes:
+
+- **"Fechar e seguir"**: encerra as perguntas e avanca pro proximo passo do tier (design em 3 frases, propor abordagens ou destilar a ideia).
+- **"Mais perguntas"**: abre nova rodada, mais especifica que a anterior. Essa rodada termina com este mesmo checkpoint. Loop ate o usuario escolher fechar.
+
+Nao adicione opcao de resposta livre: o "Other" nativo do AskUserQuestion ja cobre. Se o usuario responder algo livre, incorpore como novo insumo e feche a rodada seguinte com o mesmo checkpoint.
+
 ## Modo exploracao (ideia crua, acima do full)
 
 Quando o usuario tem so uma SEMENTE e quer DESCOBRIR o que e (nao validar um design ja pronto). Gatilhos: "tenho uma ideia", "to pensando em", "e se", "me ajuda a pensar", "queria explorar", `--deep` numa ideia vaga.
@@ -61,8 +72,8 @@ Diferenca do full: o full valida um design que o usuario ja tem na cabeca; a exp
 1. **Nao pule pra solucao.** Primeiro entenda o PORQUE: que problema/desejo move a ideia, pra quem, por que agora.
 2. **Abra alternativas radicais.** Ofereca 3-5 direcoes bem diferentes (nao variacoes da mesma), incluindo uma obvia, uma ousada e uma "e se fizesse o oposto".
 3. **Provoque com "e se".** Tensione premissas: "e se nao precisasse de X?", "e se o publico fosse outro?", "qual a versao 10x menor que ja entrega valor?".
-4. **Uma pergunta por vez**, multipla escolha quando der. Vai estreitando do amplo pro especifico.
-5. **Destile** a ideia num paragrafo claro: o que e, pra quem, por que, o diferencial. Confirme com o usuario.
+4. **Uma pergunta por vez**, multipla escolha quando der. Vai estreitando do amplo pro especifico. Feche a rodada com o checkpoint de fechamento.
+5. So depois do "Fechar e seguir" do checkpoint, **destile** a ideia num paragrafo claro: o que e, pra quem, por que, o diferencial. Confirme com o usuario.
 6. So ENTAO transicione pro design (full) ou direto pro `BRIEFING.md`, conforme o tamanho do que emergiu.
 
 A exploracao termina numa ideia destilada e aprovada, que vira BRIEFING. Continua valendo o estado terminal: codigo so depois de `/up:plan`.
@@ -83,7 +94,7 @@ Como detectar: pedido fala em "documento, proposta, relatorio, analise, texto, r
 
 1. **Explore o contexto** (arquivos, docs, commits recentes).
 2. **Companion visual:** se o topico tem questao visual (mockup, layout, comparacao), ofereca em mensagem isolada, sozinha. Jonathan e visual: ofereca por default em UI. Metodo de quando/como oferecer e produzir: ver `visual-companion.md` (mesma pasta).
-3. **Perguntas uma por vez.** Multipla escolha preferida. Foco: proposito, restricoes, criterio de sucesso. Se o escopo for multiplos subsistemas independentes, sinalize JA e ajude a decompor em sub-projetos.
+3. **Perguntas uma por vez.** Multipla escolha preferida. Foco: proposito, restricoes, criterio de sucesso. Se o escopo for multiplos subsistemas independentes, sinalize JA e ajude a decompor em sub-projetos. Feche a rodada com o checkpoint de fechamento antes de avancar pro passo 4.
 4. **Proponha 2-3 abordagens** com trade-offs e sua recomendacao.
 5. **Apresente o design por SECAO** (arquitetura / componentes / dados / erros / testes), cada secao escalada a complexidade, aprovacao do usuario apos CADA secao.
 6. **Escreva BRIEFING.md** e commite (`docs(brief): <topico>`).