@spec-wave/cli 0.14.0 → 0.15.0

package/bin/spec-wave.mjs

@@ -93,6 +93,9 @@ program
   .option('--skip-skill', 'Não verifica/atualiza a skill instalada')
   .option('--skip-config', 'Não verifica/atualiza o .spec-wave.json local')
   .option('--skip-repo', 'Não verifica/atualiza workflows e labels do repo')
+  .option('--branch [nome]', 'Envia os arquivos do repo como Pull Request numa branch, em um único commit (sem valor: spec-wave/update-v<versão>)')
+  .option('--config-in-pr', 'Força incluir o .spec-wave.json no Pull Request')
+  .option('--no-config-in-pr', 'Força manter o .spec-wave.json fora do Pull Request')
   .option('--dry-run', 'Mostra o que seria atualizado sem alterar nada')
   .option('--yes', 'Aplica sem pedir confirmação')
   .action(async (options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-wave/cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
   "type": "module",
   "bin": {

package/src/api/github-rest.mjs

@@ -4,6 +4,15 @@ function makeOctokit(token) {
   return new Octokit({ auth: token });
 }
 
+// Para as consultas em que 404 é um RESULTADO ESPERADO ("a branch ainda não
+// existe", "não há o que comparar") e não um erro: o logger padrão do Octokit
+// imprime a linha `GET ... - 404` no stderr, que no meio de um spinner parece
+// falha. Mesmo padrão do doctor.mjs, onde 404/403 também são respostas válidas.
+const silentLog = { debug() {}, info() {}, warn() {}, error() {} };
+function makeQuietOctokit(token) {
+  return new Octokit({ auth: token, log: silentLog });
+}
+
 export async function getOwnerNodeId(token, owner) {
   const octokit = makeOctokit(token);
   try {
@@ -87,6 +96,189 @@ export async function upsertFile(token, owner, repo, path, content, message) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Git Data API — commit ATÔMICO + Pull Request
+//
+// O upsertFile acima faz UM COMMIT POR ARQUIVO direto na branch default: oito
+// arquivos = oito commits, e uma falha no quinto deixa o repositório num estado
+// intermediário que ninguém pediu. Aqui a árvore inteira é montada primeiro e só
+// então nascem o commit e a ref — antes da createRef/updateRef nada é
+// ALCANÇÁVEL (os objetos existem no banco, mas nenhuma ref aponta para eles),
+// então uma falha no meio não muda o repositório observável.
+//
+// Três pegadinhas da API, todas documentadas porque custam tempo de depuração:
+//  • createTree SEM `base_tree` produz uma árvore com SÓ os arquivos enviados —
+//    o commit resultante APAGA todo o resto do repositório, e a API responde 201.
+//  • getRef/getCommit/updateRef querem o ref SEM o prefixo `refs/`
+//    ('heads/main'); createRef quer COM ('refs/heads/x'). Trocar dá 404/422 sem
+//    explicação.
+//  • pulls.list exige `head` qualificado com o owner ('owner:branch'): sem o
+//    prefixo a API IGNORA o filtro e devolve todos os PRs abertos.
+// ---------------------------------------------------------------------------
+
+/**
+ * Lê a ponta de uma branch: sha do commit e sha da ÁRVORE desse commit.
+ *
+ * A árvore é o que interessa para o `base_tree` e para detectar "nada mudou":
+ * git é endereçado por conteúdo, então árvore igual = conteúdo igual, sem
+ * precisar pedir diff.
+ *
+ * @returns {Promise<{commitSha: string, treeSha: string}|null>} null quando a
+ *          branch não existe (404) — o chamador decide criar vs. atualizar a ref.
+ */
+export async function getBranchHead(token, owner, repo, branch) {
+  const octokit = makeQuietOctokit(token); // 404 = branch inexistente, não erro
+  let commitSha;
+  try {
+    const ref = await octokit.rest.git.getRef({ owner, repo, ref: `heads/${branch}` });
+    commitSha = ref.data.object.sha;
+  } catch (err) {
+    if (err.status === 404) return null;
+    throw err;
+  }
+  const commit = await octokit.rest.git.getCommit({ owner, repo, commit_sha: commitSha });
+  return { commitSha, treeSha: commit.data.tree.sha };
+}
+
+/**
+ * Compara `base...branch`.
+ *
+ * 'behind'/'identical' significa que a branch não tem nenhum commit que a base
+ * já não tenha — sinal típico de branch de um PR já mergeado com squash. Serve
+ * só para AVISAR antes de empilhar um commit numa branch obsoleta; nunca para
+ * decidir um force-push.
+ *
+ * @returns {Promise<'identical'|'ahead'|'behind'|'diverged'|null>} null se a
+ *          branch não existe ou a comparação falha (é só um aviso — não pode
+ *          derrubar o fluxo).
+ */
+export async function compareBranches(token, owner, repo, base, branch) {
+  const octokit = makeQuietOctokit(token); // 404 = branch inexistente, não erro
+  try {
+    const res = await octokit.rest.repos.compareCommitsWithBasehead({
+      owner, repo, basehead: `${base}...${branch}`,
+    });
+    return res.data.status;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Grava N arquivos em UM único commit numa branch (criando-a a partir de `base`
+ * quando ainda não existe).
+ *
+ * Idempotente de propósito: rodar `update --branch fix/x` duas vezes não gera um
+ * segundo commit. Quando a branch já existe o pai é a PONTA DELA — não a base —
+ * então a atualização da ref é sempre fast-forward e `force` fica em false (uma
+ * corrida com outro push falha em vez de sobrescrever trabalho alheio).
+ *
+ * Se a árvore montada tiver o MESMO sha da árvore do pai, nada mudou de fato e o
+ * commit é pulado: commit vazio num PR só confunde quem revisa.
+ *
+ * @param {object} opts
+ * @param {string} opts.branch branch de trabalho (head do PR)
+ * @param {string} opts.base branch de partida quando `branch` ainda não existe
+ * @param {Array<{path: string, content: string}>} opts.files conteúdo FINAL de cada arquivo
+ * @param {string} opts.message mensagem do commit único
+ * @returns {Promise<{branch, base, commitSha, createdBranch, unchanged, baseSha}>}
+ */
+export async function commitFilesToBranch(token, owner, repo, { branch, base, files, message }) {
+  const octokit = makeOctokit(token);
+  if (!files?.length) throw new Error('commitFilesToBranch: nenhum arquivo a enviar.');
+
+  const baseHead = await getBranchHead(token, owner, repo, base);
+  if (!baseHead) throw new Error(`Branch base "${base}" não encontrada em ${owner}/${repo}.`);
+
+  const head = await getBranchHead(token, owner, repo, branch);
+  const parent = head ?? baseHead;
+
+  // `content` inline: a própria API cria o blob, poupando um createBlob por
+  // arquivo. Vale só para texto UTF-8 — todos os nossos templates são.
+  // mode: 100644 = arquivo comum (100755 executável, 040000 subárvore).
+  const tree = await octokit.rest.git.createTree({
+    owner,
+    repo,
+    base_tree: parent.treeSha, // SEM isto o commit apagaria o repositório inteiro
+    tree: files.map(f => ({ path: f.path, mode: '100644', type: 'blob', content: f.content })),
+  });
+
+  if (tree.data.sha === parent.treeSha) {
+    return {
+      branch, base, commitSha: parent.commitSha,
+      createdBranch: false, unchanged: true, baseSha: baseHead.commitSha,
+    };
+  }
+
+  const commit = await octokit.rest.git.createCommit({
+    owner, repo, message, tree: tree.data.sha, parents: [parent.commitSha],
+  });
+
+  if (head) {
+    await octokit.rest.git.updateRef({
+      owner, repo, ref: `heads/${branch}`, sha: commit.data.sha, force: false,
+    });
+  } else {
+    await octokit.rest.git.createRef({
+      owner, repo, ref: `refs/heads/${branch}`, sha: commit.data.sha,
+    });
+  }
+
+  return {
+    branch, base, commitSha: commit.data.sha,
+    createdBranch: !head, unchanged: false, baseSha: baseHead.commitSha,
+  };
+}
+
+/**
+ * PR ABERTO cuja head é `branch` neste mesmo repositório.
+ *
+ * @returns {Promise<{number, url, title, base}|null>}
+ */
+export async function findOpenPR(token, owner, repo, branch) {
+  const octokit = makeOctokit(token);
+  const res = await octokit.rest.pulls.list({
+    owner, repo, state: 'open', head: `${owner}:${branch}`, per_page: 1,
+  });
+  const pr = res.data[0];
+  return pr
+    ? { number: pr.number, url: pr.html_url, title: pr.title, base: pr.base.ref }
+    : null;
+}
+
+/**
+ * Abre o PR da branch — ou devolve o que já está aberto para ela.
+ *
+ * Rodar o update duas vezes não pode virar dois PRs. O findOpenPR cobre o caso
+ * normal; o catch do 422 cobre a corrida e o "No commits between base and head"
+ * (branch sem nada novo em relação à base → não existe PR a abrir → null).
+ * Qualquer outro 422 propaga com a mensagem real da API, senão uma base inválida
+ * viraria um silencioso "nada a revisar".
+ *
+ * @returns {Promise<{number, url, created}|null>}
+ */
+export async function ensurePullRequest(
+  token, owner, repo, { branch, base, title, body, draft = false }
+) {
+  const octokit = makeOctokit(token);
+  const existing = await findOpenPR(token, owner, repo, branch);
+  if (existing) return { ...existing, created: false };
+  try {
+    const res = await octokit.rest.pulls.create({
+      owner, repo, title, body, head: branch, base, draft,
+    });
+    return { number: res.data.number, url: res.data.html_url, created: true };
+  } catch (err) {
+    if (err.status !== 422) throw err;
+    const again = await findOpenPR(token, owner, repo, branch);
+    if (again) return { ...again, created: false };
+    const detail = err.response?.data?.errors?.map(e => e.message).filter(Boolean).join('; ')
+      || err.message;
+    if (/No commits between/i.test(detail)) return null;
+    throw new Error(detail);
+  }
+}
+
 // `id` é o database id da issue — exigido pela API de dependências
 // (blocked_by), que não aceita number nem node id.
 export async function createIssue(token, owner, repo, title, body, labels) {
@@ -235,10 +427,14 @@ export async function getPR(token, owner, repo, prNumber) {
   return res.data;
 }
 
-export async function getFileContent(token, owner, repo, path) {
+// `ref` é opcional (compatível com os chamadores de 4 argumentos): o modo PR do
+// `update` precisa ler o .spec-wave.json na BASE, não no que a API escolher.
+export async function getFileContent(token, owner, repo, path, ref) {
   const octokit = makeOctokit(token);
   try {
-    const res = await octokit.rest.repos.getContent({ owner, repo, path });
+    const res = await octokit.rest.repos.getContent({
+      owner, repo, path, ...(ref ? { ref } : {}),
+    });
     return Buffer.from(res.data.content, 'base64').toString('utf-8');
   } catch (err) {
     if (err.status === 404) return null;

package/src/commands/update.mjs

@@ -8,7 +8,12 @@ import { CONFIG_FILE, WORKFLOW_FILES, ISSUE_TEMPLATE_FILES, ALL_LABELS } from '.
 import { getProjectSnapshot } from '../api/github-graphql.mjs';
 import {
   getFileContent, upsertFile, listLabels, createLabel, updateLabel, deleteLabel,
+  getRepoDefaultBranch, compareBranches, commitFilesToBranch, ensurePullRequest,
 } from '../api/github-rest.mjs';
+import {
+  resolveBranchName, composePrTitle, composePrBody, buildCommitMessage,
+  decideConfigInPr, explainGitWriteError,
+} from '../lib/pr-branch.mjs';
 // MESMO readTemplate do init: resolve {{CLI_VERSION}} antes da comparação byte a
 // byte com o remoto. Se só o init resolvesse, todo update veria os workflows
 // como desatualizados para sempre.
@@ -85,12 +90,102 @@ export function diffLabels(existing) {
   return { missing, changed, orphan };
 }
 
+/**
+ * Regenera o conteúdo do .spec-wave.json a partir do Project remoto SEM GRAVAR.
+ *
+ * A geração foi separada da gravação porque no modo --branch esse conteúdo pode
+ * precisar entrar na árvore do commit — e a árvore é montada antes de QUALQUER
+ * escrita, para que uma falha no caminho não deixe nada aplicado, nem local nem
+ * remoto.
+ *
+ * @returns {Promise<{ content: string|null, error: string|null }>}
+ */
+async function buildConfigContent(token, config) {
+  const snapshot = await getProjectSnapshot(token, config.project.id);
+  if (!snapshot) return { content: null, error: 'Project não encontrado' };
+  const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
+  const updated = {
+    ...config,
+    version: CLI_VERSION,
+    project: {
+      ...projectRest,
+      title: snapshot.title,
+      url: snapshot.url,
+      id: snapshot.id,
+      number: snapshot.number,
+      fields: snapshot.fields,
+    },
+    refreshedAt: new Date().toISOString(),
+  };
+  // MESMA serialização do init (2 espaços + \n final): este texto é comparado
+  // byte a byte com o remoto em decideConfigInPr, e um \n de diferença faria o
+  // config entrar no PR em toda execução.
+  return { content: `${JSON.stringify(updated, null, 2)}\n`, error: null };
+}
+
+/**
+ * Aplica o diff de labels direto na base.
+ *
+ * Label NUNCA entra num PR: é metadado do repositório, não arquivo versionado —
+ * não existe forma de propor a mudança para revisão.
+ *
+ * @returns {Promise<{created: string[], updated: string[], removed: string[]}>}
+ *          só o que REALMENTE passou — é o que o corpo do PR vai afirmar a quem
+ *          revisa, e ele não pode prometer o que falhou.
+ */
+async function applyLabels(token, owner, repo, labelDiff) {
+  const done = { created: [], updated: [], removed: [] };
+  for (const label of labelDiff.missing) {
+    try {
+      await createLabel(token, owner, repo, label);
+      done.created.push(label.name);
+      p.log.success(`Label criada: ${label.name}`);
+    } catch (err) {
+      p.log.error(`Falha ao criar label ${label.name}: ${err.message}`);
+    }
+  }
+  for (const label of labelDiff.changed) {
+    try {
+      await updateLabel(token, owner, repo, label);
+      done.updated.push(label.name);
+      p.log.success(`Label atualizada: ${label.name}`);
+    } catch (err) {
+      p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
+    }
+  }
+  for (const label of labelDiff.orphan) {
+    try {
+      await deleteLabel(token, owner, repo, label.name);
+      done.removed.push(label.name);
+      p.log.success(`Label descontinuada removida: ${label.name}`);
+    } catch (err) {
+      p.log.error(`Falha ao remover label ${label.name}: ${err.message}`);
+    }
+  }
+  return done;
+}
+
 export async function update(options = {}) {
   p.intro(chalk.bold(`spec-wave update (CLI v${CLI_VERSION})`));
 
   const isGlobal = !!options.global;
   const baseDir = isGlobal ? homedir() : process.cwd();
 
+  // --branch: valida o nome ANTES de qualquer rede. Descobrir um espaço no nome
+  // só no createRef, depois de meia dúzia de requisições, é o pior desperdício
+  // possível — e a mensagem crua da API não aponta a causa.
+  const prRequested = options.branch !== undefined && options.branch !== false;
+  let branch = null;
+  if (prRequested) {
+    const r = resolveBranchName(options.branch, { version: CLI_VERSION });
+    if (r.error) {
+      p.log.error(r.error);
+      p.cancel('Update cancelado.');
+      return;
+    }
+    branch = r.branch;
+  }
+
   // ---------- Detecção ----------
   // 1) Skill (por agente detectado).
   const parsed = parseSkill(readFileSync(SKILL_SOURCE, 'utf-8'));
@@ -99,9 +194,11 @@ export async function update(options = {}) {
   // 2) Config + repo dependem do .spec-wave.json local do repo atual.
   const configPath = findConfigPath();
   let config = null;
+  let rawConfig = null; // texto cru: comparado com o remoto em decideConfigInPr
   if (configPath) {
     try {
-      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      rawConfig = readFileSync(configPath, 'utf-8');
+      config = JSON.parse(rawConfig);
     } catch (err) {
       p.log.warn(`${CONFIG_FILE} corrompido (${err.message}); pulando config/repo.`);
     }
@@ -136,6 +233,8 @@ export async function update(options = {}) {
   }
 
   // 2b) Arquivos do repo e labels divergentes (exige token + rede).
+  const owner = config?.owner;
+  const repo = config?.repo;
   let repoFiles = [];
   let labelDiff = { missing: [], changed: [], orphan: [] };
   let repoChecked = false;
@@ -147,7 +246,6 @@ export async function update(options = {}) {
       s.stop('');
       p.log.warn(`Sem token do GitHub (${tokenError?.message ?? 'indisponível'}); pulando verificação do repo.`);
     } else {
-      const { owner, repo } = config;
       try {
         for (const f of REPO_FILES) {
           const remote = await getFileContent(tk, owner, repo, f.repoPath);
@@ -165,9 +263,67 @@ export async function update(options = {}) {
     }
   }
 
+  // 2c) Modo PR: base remota, estado do config na base e situação da branch.
+  // TUDO leitura — precisa acontecer aqui porque o resumo e o --dry-run já
+  // mostram a branch, a base e se o config vai no PR.
+  let prMode = prRequested && doRepo && repoChecked;
+  let base = null;
+  let remoteConfigRaw = null;
+  let branchExists = false;
+  if (prMode) {
+    const tk = await getToken();
+    try {
+      base = await getRepoDefaultBranch(tk, owner, repo);
+      if (branch === base) {
+        p.log.error(
+          `--branch "${branch}" é a própria branch default do repositório; ` +
+          'um Pull Request precisa de uma branch diferente da base.'
+        );
+        p.cancel('Update cancelado.');
+        return;
+      }
+      remoteConfigRaw = await getFileContent(tk, owner, repo, CONFIG_FILE, base);
+      const status = await compareBranches(tk, owner, repo, base, branch);
+      branchExists = status !== null;
+      if (status === 'behind' || status === 'identical') {
+        // Não fazemos force-push: só avisamos. Empilhar um commit numa branch já
+        // mergeada funciona, mas o diff do PR pode reexibir arquivos que já estão
+        // na base (caso do squash merge).
+        p.log.warn(
+          `A branch "${branch}" já existe e não tem nenhum commit além de "${base}" ` +
+          '(provavelmente de um PR já mergeado). O commit novo seria empilhado nela — ' +
+          'use `--branch <outro-nome>` para começar do zero.'
+        );
+      }
+    } catch (err) {
+      p.log.warn(
+        `Não foi possível preparar o modo PR: ${err.message} — ` +
+        'os arquivos seguiriam por commit direto.'
+      );
+      prMode = false;
+    }
+  }
+
+  // Decisão preliminar sobre o config. O conteúdo regenerado ainda não existe;
+  // `willRegenerate` cobre isso, porque o regenerado SEMPRE difere do remoto
+  // (refreshedAt muda a cada execução). Na aplicação a decisão é recalculada com
+  // o conteúdo real.
+  const configDecision = prMode && doConfig
+    ? decideConfigInPr({
+        remote: remoteConfigRaw,
+        desired: rawConfig,
+        willRegenerate: !!configStale?.canApply,
+        force: options.configInPr,
+      })
+    : { included: false, reason: '' };
+
   // ---------- Resumo ----------
   const labelTotal = labelDiff.missing.length + labelDiff.changed.length + labelDiff.orphan.length;
-  const total = skillJobs.length + (configStale ? 1 : 0) + repoFiles.length + labelTotal;
+  // Config em dia pela versão, mas divergente do que está na base: antes isso dava
+  // "tudo atualizado" e o repositório ficava com um config velho indefinidamente.
+  const configOnlyPr = configDecision.included && !configStale;
+  const total = skillJobs.length + (configStale ? 1 : 0) + repoFiles.length + labelTotal
+    + (configOnlyPr ? 1 : 0);
 
   if (total === 0) {
     p.log.success('Tudo já está atualizado para a versão atual da CLI.');
@@ -186,11 +342,22 @@ export async function update(options = {}) {
       (configStale.canApply ? '' : chalk.dim(' (sem project.id — rode `init` sem --skip-project)')));
   }
   if (repoFiles.length) {
-    lines.push(chalk.bold('Arquivos do repo:'));
+    lines.push(prMode
+      ? chalk.bold(`Arquivos do repo → Pull Request (${branch} → ${base}):`)
+      : chalk.bold('Arquivos do repo:'));
     for (const f of repoFiles) lines.push(`  ${chalk.yellow('↻')} ${f.repoPath} (${f.reason})`);
   }
+  if (prMode && configDecision.included) {
+    if (!repoFiles.length) lines.push(chalk.bold(`Pull Request (${branch} → ${base}):`));
+    lines.push(`  ${chalk.yellow('↻')} ${CONFIG_FILE} (${configDecision.reason})`);
+  }
+  if (prMode && doConfig && !configDecision.included && configDecision.reason) {
+    lines.push(chalk.dim(`  · ${CONFIG_FILE} fora do PR — ${configDecision.reason}`));
+  }
   if (labelTotal) {
-    lines.push(chalk.bold('Labels:'));
+    lines.push(prMode
+      ? chalk.bold(`Labels (direto em ${base} — metadado do repo, não versionável):`)
+      : chalk.bold('Labels:'));
     if (labelDiff.missing.length) lines.push(`  ${chalk.yellow('+')} criar: ${labelDiff.missing.map(l => l.name).join(', ')}`);
     if (labelDiff.changed.length) lines.push(`  ${chalk.yellow('↻')} atualizar: ${labelDiff.changed.map(l => l.name).join(', ')}`);
     if (labelDiff.orphan.length) {
@@ -199,13 +366,48 @@ export async function update(options = {}) {
   }
   p.note(lines.join('\n'), `${total} item(ns) desatualizado(s)`);
 
+  // --branch sem efeito: melhor dizer POR QUE do que criar uma branch inútil.
+  const prHasPayload = prMode && (repoFiles.length > 0 || configDecision.included);
+  if (prRequested && options.skipRepo) {
+    p.log.warn(
+      '--branch ignorado junto com --skip-repo: o Pull Request existe justamente para ' +
+      'levar os arquivos do repo.'
+    );
+  } else if (prRequested && !prMode) {
+    p.log.warn(
+      '--branch ignorado: sem token, sem owner/repo no .spec-wave.json ou a comparação com ' +
+      'o repositório falhou — não há como abrir o Pull Request.'
+    );
+  } else if (prMode && !prHasPayload) {
+    p.log.warn(
+      '--branch sem efeito: nenhum arquivo do repositório para enviar (as mudanças são ' +
+      'locais e/ou de labels). Nenhuma branch será criada.'
+    );
+  }
+
   if (options.dryRun) {
+    if (prHasPayload) {
+      const n = repoFiles.length + (configDecision.included ? 1 : 0);
+      p.note(
+        `Branch:    ${branch}${branchExists ? ' (já existe — o commit seria empilhado nela)' : ' (seria criada)'}\n` +
+        `Base:      ${base}\n` +
+        `Título:    ${composePrTitle({ version: CLI_VERSION })}\n` +
+        `Arquivos:  ${n} em 1 commit único\n\n` +
+        'Nada foi criado: nem branch, nem commit, nem Pull Request.',
+        'Dry-run: modo Pull Request'
+      );
+    }
     p.outro('Dry-run: nada foi alterado.');
     return;
   }
 
   if (!options.yes) {
-    const ok = await p.confirm({ message: `Aplicar as ${total} atualização(ões)?`, initialValue: true });
+    const ok = await p.confirm({
+      message: prHasPayload
+        ? `Aplicar as ${total} atualização(ões) e abrir um Pull Request em "${branch}"?`
+        : `Aplicar as ${total} atualização(ões)?`,
+      initialValue: true,
+    });
     if (p.isCancel(ok) || !ok) {
       p.cancel('Update cancelado.');
       return;
@@ -213,6 +415,14 @@ export async function update(options = {}) {
   }
 
   // ---------- Aplicação ----------
+  // Ordem: skill (local) → config GERADO em memória → labels (sempre direto) →
+  // arquivos do repo (PR ou commits diretos) → gravação local do config.
+  //
+  // As labels vêm ANTES dos arquivos porque o corpo do PR precisa dizer quais
+  // labels JÁ mudaram na base — é a única coisa que o update faz e o diff do PR
+  // não mostra. (Isso muda a ordem dos logs também no modo direto; os dois blocos
+  // são independentes.)
+
   // Skill
   for (const job of skillJobs) {
     try {
@@ -223,7 +433,8 @@ export async function update(options = {}) {
     }
   }
 
-  // Config (.spec-wave.json) — reconsulta o Project e reescreve local.
+  // Config (.spec-wave.json) — regenera o conteúdo, ainda sem tocar o disco.
+  let configContent = null;
   if (configStale) {
     if (!configStale.canApply) {
       p.log.warn(`${CONFIG_FILE}: sem project.id — pulei. Rode \`npx @spec-wave/cli@latest init\` (sem --skip-project).`);
@@ -233,83 +444,149 @@ export async function update(options = {}) {
         p.log.warn(`${CONFIG_FILE}: sem token — pulei. (${tokenError?.message ?? ''})`);
       } else {
         const s = p.spinner();
-        s.start('Atualizando .spec-wave.json...');
+        s.start('Consultando o Project para atualizar o .spec-wave.json...');
         try {
-          const snapshot = await getProjectSnapshot(tk, config.project.id);
-          if (!snapshot) throw new Error('Project não encontrado');
-          const { etapaFieldId: _e, stageOptions: _s, ...projectRest } = config.project;
-          const updated = {
-            ...config,
-            version: CLI_VERSION,
-            project: {
-              ...projectRest,
-              title: snapshot.title,
-              url: snapshot.url,
-              id: snapshot.id,
-              number: snapshot.number,
-              fields: snapshot.fields,
-            },
-            refreshedAt: new Date().toISOString(),
-          };
-          writeFileSync(configPath, JSON.stringify(updated, null, 2) + '\n');
-          s.stop(`${CONFIG_FILE} atualizado (v${CLI_VERSION}).`);
+          const { content, error } = await buildConfigContent(tk, config);
+          if (error) throw new Error(error);
+          configContent = content;
+          s.stop(`${CONFIG_FILE} regenerado (v${CLI_VERSION}).`);
         } catch (err) {
           s.stop('');
-          p.log.error(`Falha ao atualizar ${CONFIG_FILE}: ${err.message}`);
+          p.log.error(`Falha ao regerar ${CONFIG_FILE}: ${err.message}`);
         }
       }
     }
   }
 
-  // Arquivos do repo
-  if (repoFiles.length) {
-    const tk = await getToken();
-    const { owner, repo } = config;
-    for (const f of repoFiles) {
-      try {
-        await upsertFile(tk, owner, repo, f.repoPath, f.local, `chore: update ${path.basename(f.repoPath)} [spec-wave]`);
-        p.log.success(`Arquivo atualizado no repo: ${f.repoPath}`);
-      } catch (err) {
-        p.log.error(`Falha ao atualizar ${f.repoPath}: ${err.message}`);
-      }
+  // Recalcula a decisão com o conteúdo REAL (a preliminar usava willRegenerate).
+  const finalConfigDecision = prMode && doConfig
+    ? decideConfigInPr({
+        remote: remoteConfigRaw,
+        desired: configContent ?? rawConfig,
+        force: options.configInPr,
+      })
+    : { included: false, reason: '' };
+
+  // Gravação local do config, feita UMA vez só. No modo PR com o config a bordo
+  // ela é adiada para depois do commit remoto: assim uma falha no envio não deixa
+  // o arquivo local adiantado em relação ao repositório.
+  let configFlushed = false;
+  const flushConfig = () => {
+    if (configFlushed || !configContent) return;
+    try {
+      writeFileSync(configPath, configContent);
+      configFlushed = true;
+      p.log.success(`${CONFIG_FILE} atualizado localmente (v${CLI_VERSION}).`);
+    } catch (err) {
+      p.log.error(`Falha ao gravar ${CONFIG_FILE}: ${err.message}`);
     }
-  }
+  };
+  if (!finalConfigDecision.included) flushConfig();
 
-  // Labels
+  // Labels — sempre direto na base (metadado do repo, não versionável).
+  let labelResult = { created: [], updated: [], removed: [] };
   if (labelTotal) {
+    labelResult = await applyLabels(await getToken(), owner, repo, labelDiff);
+  }
+
+  // Arquivos do repo
+  let prUrl = null;
+  if (prMode) {
     const tk = await getToken();
-    const { owner, repo } = config;
-    for (const label of labelDiff.missing) {
+    const treeFiles = [
+      ...repoFiles.map(f => ({ path: f.repoPath, reason: f.reason, content: f.local })),
+      ...(finalConfigDecision.included
+        ? [{
+            path: CONFIG_FILE,
+            reason: finalConfigDecision.reason,
+            content: configContent ?? rawConfig,
+          }]
+        : []),
+    ];
+    if (!treeFiles.length) {
+      p.log.warn('Nada para enviar em um Pull Request: nenhum arquivo do repositório mudou.');
+    } else {
+      const s = p.spinner();
+      s.start(`Enviando ${treeFiles.length} arquivo(s) em um único commit para "${branch}"...`);
+      let commitOk = false;
       try {
-        await createLabel(tk, owner, repo, label);
-        p.log.success(`Label criada: ${label.name}`);
+        const res = await commitFilesToBranch(tk, owner, repo, {
+          branch,
+          base,
+          files: treeFiles.map(f => ({ path: f.path, content: f.content })),
+          message: buildCommitMessage({ version: CLI_VERSION, files: treeFiles }),
+        });
+        commitOk = true;
+        s.stop(res.unchanged
+          ? `"${branch}" já contém estas alterações — nenhum commit novo.`
+          : `Commit ${res.commitSha.slice(0, 7)} enviado para "${branch}" (${treeFiles.length} arquivo(s)).`);
       } catch (err) {
-        p.log.error(`Falha ao criar label ${label.name}: ${err.message}`);
+        s.stop('');
+        p.log.error(`Falha ao enviar os arquivos para "${branch}": ${explainGitWriteError(err)}`);
       }
-    }
-    for (const label of labelDiff.changed) {
-      try {
-        await updateLabel(tk, owner, repo, label);
-        p.log.success(`Label atualizada: ${label.name}`);
-      } catch (err) {
-        p.log.error(`Falha ao atualizar label ${label.name}: ${err.message}`);
+
+      // O PR fica num try SEPARADO: a falha aqui não invalida o commit, e a
+      // mensagem precisa dizer que a branch existe. Um token com "Contents:
+      // write" pode não ter "Pull requests: write" — permissão NOVA neste modo.
+      if (commitOk) {
+        try {
+          const pr = await ensurePullRequest(tk, owner, repo, {
+            branch,
+            base,
+            title: composePrTitle({ version: CLI_VERSION }),
+            body: composePrBody({
+              version: CLI_VERSION,
+              base,
+              branch,
+              files: treeFiles,
+              config: doConfig ? finalConfigDecision : null,
+              labels: labelResult,
+              skill: skillJobs.map(j => j.target.name),
+            }),
+          });
+          if (!pr) {
+            p.log.warn(
+              `A branch "${branch}" está em dia com "${base}" e não há PR aberto para ela — ` +
+              'nada a revisar.'
+            );
+          } else {
+            prUrl = pr.url;
+            p.log.success(pr.created
+              ? `Pull Request aberto: #${pr.number} — ${pr.url}`
+              : `Pull Request já aberto para "${branch}": #${pr.number} — ${pr.url}`);
+          }
+          flushConfig();
+        } catch (err) {
+          p.log.error(`Commit enviado, mas não foi possível abrir o PR: ${explainGitWriteError(err)}`);
+          p.log.info(
+            'Abra manualmente: ' +
+            `https://github.com/${owner}/${repo}/compare/${base}...${encodeURIComponent(branch)}?expand=1`
+          );
+        }
       }
     }
-    for (const label of labelDiff.orphan) {
+  } else if (repoFiles.length) {
+    const tk = await getToken();
+    for (const f of repoFiles) {
       try {
-        await deleteLabel(tk, owner, repo, label.name);
-        p.log.success(`Label descontinuada removida: ${label.name}`);
+        await upsertFile(tk, owner, repo, f.repoPath, f.local, `chore: update ${path.basename(f.repoPath)} [spec-wave]`);
+        p.log.success(`Arquivo atualizado no repo: ${f.repoPath}`);
       } catch (err) {
-        p.log.error(`Falha ao remover label ${label.name}: ${err.message}`);
+        p.log.error(`Falha ao atualizar ${f.repoPath}: ${err.message}`);
       }
     }
   }
 
-  const committedRepo = repoFiles.length > 0;
+  const configPending = configFlushed && !finalConfigDecision.included;
   p.outro(
     'Update concluído.' +
     (skillJobs.length ? ' Recarregue o agente para pegar a skill nova.' : '') +
-    (configStale?.canApply ? ` Faça commit do ${CONFIG_FILE}.` : '') +
-    (committedRepo ? ' Arquivos do repo foram commitados no remoto.' : '')
+    (prUrl ? ` Revise e faça o merge do Pull Request: ${prUrl}` : '') +
+    (!prMode && repoFiles.length ? ' Arquivos do repo foram commitados no remoto.' : '') +
+    (configPending ? ` Faça commit do ${CONFIG_FILE}.` : '') +
+    (finalConfigDecision.included
+      ? ` O ${CONFIG_FILE} local ficou igual ao do PR — depois do merge, descarte a cópia ` +
+        `local com \`git checkout -- ${CONFIG_FILE}\`.`
+      : '')
   );
 }

package/src/lib/pr-branch.mjs

@@ -0,0 +1,267 @@
+// Regras PURAS do modo `--branch` do update (arquivos do repo via Pull Request).
+//
+// Até aqui o `update` era a única exceção ao fluxo de PR: commitava os arquivos
+// do repo direto na branch default, um commit por arquivo. Em repositório com
+// proteção de branch isso falha no meio da execução e deixa parte aplicada; e
+// mesmo sem proteção, contorna a revisão que todo o resto do fluxo tem.
+//
+// Tudo aqui é puro de propósito. A suíte não tem nenhuma infraestrutura de mock
+// de HTTP, então a única forma de testar o modo PR é manter as DECISÕES (nome da
+// branch, o que entra no PR, o que o corpo do PR conta a quem revisa) separadas
+// das chamadas de rede, que ficam em api/github-rest.mjs.
+
+import { CLI_VERSION } from './templates.mjs';
+import { CONFIG_FILE } from '../config.mjs';
+
+/**
+ * Nome automático da branch quando `--branch` vem sem valor.
+ *
+ * Deliberadamente SEM timestamp: rodar o update duas vezes para a MESMA versão
+ * da CLI tem que reaproveitar o mesmo PR, não espalhar uma branch nova por
+ * tentativa. O bump de versão é o que separa uma atualização da próxima, e ele
+ * já está no nome.
+ *
+ * @param {string} [version]
+ * @returns {string}
+ */
+export function autoBranchName(version = CLI_VERSION) {
+  return `spec-wave/update-v${version}`;
+}
+
+// Proibições de `git check-ref-format` para refs/heads/<nome>: caractere
+// de controle e espaço (\u0000-\u0020), DEL (\u007f) e os
+// metacaracteres de revisão. Escapes explícitos de propósito: caractere de
+// controle literal no fonte é invisível e não sobrevive a copiar/colar.
+const REF_FORBIDDEN = /[\u0000-\u0020\u007f~^:?*[\\]/;
+
+const MAX_BRANCH_LENGTH = 200;
+
+/**
+ * Resolve e VALIDA o nome da branch (função PURA).
+ *
+ * Validar aqui, antes de qualquer chamada de rede, evita o pior desperdício
+ * possível: gastar meia dúzia de requisições de comparação e só descobrir no
+ * `createRef` que o nome tinha um espaço — com a mensagem crua da API, longe da
+ * causa.
+ *
+ * Mesmo contrato de `resolveStageName` em lib/board.mjs: `{valor, error}`.
+ *
+ * @param {string|boolean|undefined|null} value valor de `options.branch` — o
+ *        commander entrega `true` para `--branch` sem valor
+ * @param {object} [opts]
+ * @param {string} [opts.version] versão usada no nome automático
+ * @returns {{ branch: string|null, error: string|null }}
+ */
+export function resolveBranchName(value, { version = CLI_VERSION } = {}) {
+  if (value === true || value === undefined || value === null || String(value).trim() === '') {
+    return { branch: autoBranchName(version), error: null };
+  }
+
+  let branch = String(value).trim();
+  // Erro comum: colar o ref completo em vez do nome. Corrigir é mais útil que recusar.
+  if (branch.startsWith('refs/heads/')) branch = branch.slice('refs/heads/'.length);
+
+  const bad = (why) => ({ branch: null, error: `Nome de branch inválido ("${branch}"): ${why}.` });
+
+  if (!branch) return bad('nome vazio');
+  if (branch.length > MAX_BRANCH_LENGTH) {
+    return bad(`nome longo demais (máximo ${MAX_BRANCH_LENGTH} caracteres)`);
+  }
+  if (REF_FORBIDDEN.test(branch)) {
+    return bad('não pode conter espaço, caractere de controle ou ~ ^ : ? * [ \\');
+  }
+  if (branch.includes('..')) return bad('não pode conter ".."');
+  if (branch.includes('@{')) return bad('não pode conter "@{"');
+  if (branch === '@') return bad('não pode ser apenas "@"');
+  if (branch.startsWith('/') || branch.endsWith('/')) return bad('não pode começar nem terminar com "/"');
+  if (branch.includes('//')) return bad('não pode conter "//"');
+  if (branch.startsWith('-')) return bad('não pode começar com "-"');
+  if (branch.endsWith('.')) return bad('não pode terminar com "."');
+  if (branch.toUpperCase() === 'HEAD') return bad('"HEAD" é reservado');
+  for (const part of branch.split('/')) {
+    if (part.startsWith('.')) return bad('nenhum componente pode começar com "."');
+    if (part.endsWith('.lock')) return bad('nenhum componente pode terminar com ".lock"');
+  }
+  return { branch, error: null };
+}
+
+/**
+ * Título do PR — e assunto do commit único (função PURA).
+ *
+ * A mesma frase nos dois lugares de propósito: no modo PR existe um commit só, e
+ * ver textos diferentes para a mesma mudança na lista de commits e no título do
+ * PR só gera dúvida.
+ */
+export function composePrTitle({ version = CLI_VERSION } = {}) {
+  return `chore(spec-wave): atualiza arquivos do repo para v${version}`;
+}
+
+/**
+ * Mensagem do commit ÚNICO (função PURA).
+ *
+ * O corpo lista arquivo + motivo porque este é o único commit da branch: ele
+ * precisa se explicar sozinho num `git log` feito seis meses depois, sem o PR
+ * aberto ao lado.
+ *
+ * @param {object} [a]
+ * @param {string} [a.version]
+ * @param {Array<{path: string, reason: string}>} [a.files]
+ * @returns {string}
+ */
+export function buildCommitMessage({ version = CLI_VERSION, files = [] } = {}) {
+  const subject = composePrTitle({ version });
+  if (!files.length) return `${subject}\n`;
+  return `${subject}\n\n${files.map(f => `- ${f.path} (${f.reason})`).join('\n')}\n`;
+}
+
+/**
+ * Corpo do PR (função PURA).
+ *
+ * Quem revisa precisa saber DUAS coisas que o diff não mostra:
+ *  • as labels já foram aplicadas direto na base — label é metadado do
+ *    repositório, não existe forma de versioná-la num PR, então ela mudou ANTES
+ *    de alguém revisar isto;
+ *  • a skill dos agentes foi atualizada em máquina local, fora do repositório.
+ * Sem esses dois blocos o PR parece ser a totalidade do que o update fez — e não é.
+ *
+ * @param {object} [a]
+ * @param {Array<{path: string, reason: string}>} [a.files] arquivos que ENTRARAM no commit
+ * @param {{included: boolean, reason: string}|null} [a.config] decisão sobre o .spec-wave.json
+ * @param {{created: string[], updated: string[], removed: string[]}|null} [a.labels]
+ *        labels EFETIVAMENTE aplicadas (não o diff detectado — o corpo não pode
+ *        prometer o que falhou)
+ * @param {string[]} [a.skill] nomes dos agentes cuja skill foi atualizada localmente
+ * @returns {string} markdown
+ */
+export function composePrBody({
+  version = CLI_VERSION, base = '?', branch = '?',
+  files = [], config = null, labels = null, skill = [],
+} = {}) {
+  const l = [];
+  l.push(`Atualização gerada por \`spec-wave update\` (CLI v${version}).`);
+  l.push('');
+  l.push(`Base: \`${base}\` · Branch: \`${branch}\``);
+  l.push('');
+  l.push('## Arquivos do repositório');
+  l.push('');
+  if (files.length) for (const f of files) l.push(`- \`${f.path}\` — ${f.reason}`);
+  else l.push('_Nenhum._');
+
+  if (config) {
+    l.push('');
+    l.push(`## ${CONFIG_FILE}`);
+    l.push('');
+    l.push(config.included
+      ? `Incluído neste PR — ${config.reason}.`
+      : `**Fora** deste PR — ${config.reason}.`);
+  }
+
+  const labelTotal = labels
+    ? labels.created.length + labels.updated.length + labels.removed.length
+    : 0;
+  if (labelTotal) {
+    l.push('');
+    l.push(`## Labels — JÁ aplicadas em \`${base}\`, fora deste PR`);
+    l.push('');
+    l.push(
+      'Label é metadado do repositório e não pode ser versionada: estas mudanças já ' +
+      'valem, com ou sem o merge deste PR.'
+    );
+    l.push('');
+    if (labels.created.length) l.push(`- criadas: ${labels.created.map(n => `\`${n}\``).join(', ')}`);
+    if (labels.updated.length) l.push(`- atualizadas: ${labels.updated.map(n => `\`${n}\``).join(', ')}`);
+    if (labels.removed.length) l.push(`- removidas (descontinuadas): ${labels.removed.map(n => `\`${n}\``).join(', ')}`);
+  }
+
+  if (skill.length) {
+    l.push('');
+    l.push('## Skill dos agentes — fora deste PR');
+    l.push('');
+    l.push(
+      `Atualizada localmente em: ${skill.map(n => `\`${n}\``).join(', ')}. ` +
+      'Não faz parte do repositório.'
+    );
+  }
+
+  l.push('');
+  l.push('---');
+  l.push(`Depois do merge, \`npx @spec-wave/cli@${version} update --dry-run\` deve reportar tudo em dia.`);
+  return `${l.join('\n')}\n`;
+}
+
+/**
+ * O .spec-wave.json entra no PR? (função PURA)
+ *
+ * Política herdada do init (ver o comentário em commands/init.mjs): o config é
+ * gravado LOCAL de propósito. Quem não o commitou escolheu mantê-lo fora do
+ * versionamento, e passar a versioná-lo é decisão de projeto — não pode ser
+ * efeito colateral de um `update`. Logo: só entra se JÁ estiver versionado na
+ * base. `--config-in-pr` / `--no-config-in-pr` forçam os dois lados.
+ *
+ * Cobre também o caso em que o config NÃO está desatualizado pela versão mas o
+ * arquivo local difere do que está na base (alguém regenerou e esqueceu de
+ * commitar): entra igual, porque é exatamente para isso que o PR serve.
+ *
+ * @param {object} [a]
+ * @param {string|null|undefined} [a.remote] conteúdo do config na base (null/undefined = não versionado)
+ * @param {string|null} [a.desired] conteúdo que deveria estar lá
+ * @param {boolean} [a.willRegenerate] o conteúdo ainda vai ser regenerado (no
+ *        resumo e no dry-run ele não existe); o regenerado SEMPRE difere do
+ *        remoto, porque `refreshedAt` muda a cada execução
+ * @param {boolean|undefined} [a.force] undefined | true (--config-in-pr) | false (--no-config-in-pr)
+ * @returns {{ included: boolean, reason: string }}
+ */
+export function decideConfigInPr({ remote, desired, willRegenerate = false, force } = {}) {
+  const versioned = remote !== null && remote !== undefined;
+  if (force === false) return { included: false, reason: '--no-config-in-pr' };
+  if (!desired && !willRegenerate) {
+    return { included: false, reason: 'sem conteúdo local para enviar' };
+  }
+  if (force === true) {
+    return versioned
+      ? { included: true, reason: '--config-in-pr' }
+      : { included: true, reason: `--config-in-pr (passa a versionar o ${CONFIG_FILE})` };
+  }
+  if (!versioned) {
+    return {
+      included: false,
+      reason: 'não está versionado na base, segue apenas local ' +
+        '(use --config-in-pr para versioná-lo)',
+    };
+  }
+  if (!willRegenerate && remote === desired) {
+    return { included: false, reason: 'já idêntico na base' };
+  }
+  return { included: true, reason: 'versionado na base e divergente do local' };
+}
+
+/**
+ * Traduz o erro cru da Git Data API para uma dica acionável (função PURA).
+ *
+ * Sem isto o usuário vê "Not Found" num POST e conclui que o repositório não
+ * existe, quando o problema é um token sem escrita em Contents — e "Resource not
+ * accessible" não diz QUAL permissão falta.
+ *
+ * @param {{status?: number, message?: string}} err
+ * @returns {string}
+ */
+export function explainGitWriteError(err) {
+  const msg = err?.message || 'erro desconhecido';
+  switch (err?.status) {
+    case 401:
+      return `${msg} — token inválido ou expirado.`;
+    case 403:
+      return `${msg} — o token não tem permissão de escrita. Precisa de "Contents: write" e ` +
+        '"Pull requests: write" (fine-grained) ou do escopo `repo` (classic).';
+    case 404:
+      return `${msg} — repositório ou branch inexistente, OU token sem acesso a este ` +
+        'repositório (o GitHub responde 404 em vez de 403 para não revelar repos privados).';
+    case 409:
+      return `${msg} — repositório vazio (sem nenhum commit): rode \`spec-wave init\` antes.`;
+    case 422:
+      return `${msg} — o GitHub recusou a operação. Causas comuns: regra de proteção/ruleset ` +
+        'na branch (commits da API não são assinados) ou branch já em dia.';
+    default:
+      return msg;
+  }
+}

package/src/templates/skill/SKILL.md

@@ -180,11 +180,19 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 |------|------|-----------|
 | `--global` | flag | Verifica a skill no escopo do usuário (padrão: projeto). |
 | `--skip-skill` / `--skip-config` / `--skip-repo` | flag | Pula a categoria correspondente. |
+| `--branch [nome]` | flag/string | Envia os arquivos do repo como **Pull Request** numa branch, em **um único commit**, em vez de commitar direto na branch default. Sem valor, usa `spec-wave/update-v<versão>`. |
+| `--config-in-pr` / `--no-config-in-pr` | flag | Força incluir/excluir o `.spec-wave.json` do PR (o default decide sozinho — veja abaixo). |
 | `--dry-run` | flag | Mostra o que seria atualizado sem alterar nada. |
 | `--yes` | flag | Aplica sem pedir confirmação. |
 
 > Detecta e atualiza **somente o que divergiu** da versão atual da CLI: a **skill** instalada (por agente), o **`.spec-wave.json`** local (se versão/formato divergir) e os **workflows/labels** do repo (compara com os templates empacotados). Interativo por padrão (mostra o plano e confirma). É o atalho recomendado após atualizar a CLI.
 
+> **`--branch` (modo Pull Request).** Sem a flag, os arquivos do repo vão em **commits diretos na branch default** — o que falha no meio da execução em repositório com proteção de branch, deixando parte aplicada, e contorna a revisão. Com a flag, todos os arquivos vão em **um commit atômico** numa branch nova e um PR é aberto: se algo falhar antes da criação da branch, **nada** é alterado no repositório. É **idempotente** — rodar duas vezes não gera um segundo commit nem um segundo PR.
+>
+> Duas coisas **não** entram no PR, porque não são versionáveis: as **labels** (metadado do repositório — já valem na base, com ou sem merge) e a **skill** (arquivo em máquina local). O corpo do PR diz isso explicitamente a quem revisa.
+>
+> ⚠️ O modo PR exige **`pull_requests: write`** além de `contents: write` (ou o escopo `repo` num PAT classic). Sem essa permissão, a branch é criada e o PR falha — a mensagem oferece a URL de `compare` para abrir à mão.
+
 ### `@spec-wave/cli generate-plan` · `generate-spec` · `validate` · `decompose`
 | Flag | Tipo | Descrição |
 |------|------|-----------|
@@ -417,12 +425,16 @@ Traz tudo para a versão atual da CLI, atualizando **só o que mudou**: a skill
    npx @spec-wave/cli@latest update --dry-run
    ```
 2. Mostre ao usuário o resumo (skill / config / arquivos do repo / labels que divergiram). Se **nada** estiver desatualizado, informe que já está tudo na versão atual e encerre.
-3. Se o usuário aprovar, aplique:
+3. **Pergunte como os arquivos do repo devem sair** — e prefira o Pull Request:
    ```bash
-   npx @spec-wave/cli@latest update --yes
+   npx @spec-wave/cli@latest update --yes --branch     # 1 commit atômico + PR (recomendado)
+   npx @spec-wave/cli@latest update --yes              # commits diretos na branch default
    ```
    - Escopos podem ser limitados com `--skip-skill`, `--skip-config`, `--skip-repo`.
-   - Atualizações de **arquivos do repo** são commitadas no remoto; o **`.spec-wave.json`** é local (lembre o usuário de commitá-lo).
+   - **Com `--branch`:** os arquivos do repo vão em **um único commit** numa branch nova e um PR é aberto — nada é escrito na branch default. Passe o link do PR ao usuário e lembre que o merge é dele. Exige `pull_requests: write` no token.
+   - **Sem `--branch`:** cada arquivo é um commit direto na branch default. Em repositório com **proteção de branch** isso falha no meio e deixa parte aplicada — nesses casos use `--branch`.
+   - **Nos dois modos**, as **labels** são aplicadas direto na base (metadado do repositório, não versionável) e a **skill** é gravada em máquina local. Nenhuma das duas entra no PR.
+   - **`.spec-wave.json`:** com `--branch`, ele entra no PR se o repositório **já o versiona**; se não versiona, segue apenas local e o usuário precisa commitá-lo (ou use `--config-in-pr` para passar a versioná-lo). Sem `--branch`, é sempre só local.
 4. Se a skill foi atualizada, oriente recarregar/reiniciar o agente para pegar a nova versão.
 
 ---