@spec-wave/cli 1.0.6 → 1.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -104,12 +104,37 @@ Arquivo em `.github/config/tech_context.yml` que descreve a stack tecnológica d
104
104
  ## Pré-requisitos
105
105
 
106
106
  - Node.js >= 20
107
+ - O repositório pertence a uma **organização**, não a uma conta pessoal — o `init` recusa conta
108
+ pessoal, porque a instalação de um GitHub App não alcança Projects v2 fora de uma org e metade do
109
+ fluxo (tudo que move card) morreria em runtime
107
110
  - GitHub CLI (`gh`) autenticado com escopos `project`, `repo` e `workflow`:
108
111
  ```bash
109
112
  gh auth refresh --scopes project,repo,workflow
110
113
  ```
114
+ - **Actions habilitado** no repositório e permitido pela política da organização
111
115
  - Secret no repositório, conforme o provider: `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` (assinatura Claude Pro/Max) ou `OPENROUTER_API_KEY` (Settings → Secrets → Actions)
112
- - Para repositórios em organizações: criar PAT com escopo `project` e adicionar como secret `GH_PROJECT_TOKEN`
116
+
117
+ ### Autenticação dos workflows: GitHub App ou PATs
118
+
119
+ O `GITHUB_TOKEN` do Actions **não** tem escopo de Projects e não alcança outro repositório. Dois
120
+ caminhos preenchem essa lacuna — e `spec-wave doctor` diz qual está valendo:
121
+
122
+ **GitHub App da organização (recomendado).** Crie uma App na org, instale no hub e em cada
123
+ repositório de código, e grave `SPEC_WAVE_APP_ID` + `SPEC_WAVE_APP_PRIVATE_KEY` (o `.pem` completo).
124
+ Cada execução gera o próprio token, sem depender do PAT de uma pessoa. Permissões: Issues RW,
125
+ Contents RW, Pull requests RW, Metadata R, Projects (org) RW — mais Workflows W só se a App também
126
+ for usada para rodar `init`/`update`. Prefira secret de **organização**; se a visibilidade for
127
+ *Selected repositories*, lembre de acrescentar cada repositório novo à lista, senão o workflow dele
128
+ não enxerga o secret e a falha só aparece na primeira execução.
129
+
130
+ **PATs (sem App).** `GH_PROJECT_TOKEN` com escopo `project` (mover cards), `GH_PR_TOKEN` quando a
131
+ organização não permite o Actions abrir PR ou a branch exige status checks, e `SPEC_WAVE_HUB_TOKEN`
132
+ no repositório de código (multi-repo). O PAT é de uma pessoa: quando ela sai da organização — ou o
133
+ token expira — os workflows param em silêncio.
134
+
135
+ Checklist completo, com o sintoma de cada item quando falta, em
136
+ [Configurações do GitHub](https://github.com/astratech-net-br/spec-wave-cli/blob/main/apps/docs/src/content/docs/configuracao/github.md)
137
+ — este README é publicado no npm, então o link é absoluto de propósito.
113
138
 
114
139
  ---
115
140
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spec-wave/cli",
3
- "version": "1.0.6",
3
+ "version": "1.0.8",
4
4
  "description": "Setup spec-driven GitHub workflow with Projects v2, labels, issue templates, and AI-powered Actions",
5
5
  "type": "module",
6
6
  "bin": {
@@ -10,6 +10,7 @@ import { resolveHubContext, resolvePrRepo } from '../lib/project-root.mjs';
10
10
  import { markFeaturePrsReady } from '../lib/pr-ready.mjs';
11
11
  import { codeReposForItems } from '../lib/workspace.mjs';
12
12
  import { extractIssueRefs, hubIssueNumbers, resolveLinkMode, sameRepo } from '../lib/pr-link.mjs';
13
+ import { cliRef } from '../lib/cli-ref.mjs';
13
14
  import {
14
15
  STATUS_OPTIONS, STAGE_ORDER, STAGE_DONE, PROGRESS_TODO, PROGRESS_DONE, isManualStageType,
15
16
  LABEL_DECOMPOSE, LABEL_DECOMPOSE_APPLY, labelNames,
@@ -425,7 +426,7 @@ export async function codeReview({ prNumber, prRepo: prRepoOpt, resolveOnly = fa
425
426
  partes.push(
426
427
  `⏳ **Board não atualizado** para ${[...deferred].map(n => `#${n}`).join(', ')}: ` +
427
428
  'há decomposição em andamento. Depois que ela terminar, rode ' +
428
- `\`npx @spec-wave/cli@latest code-review --pr-number ${prNumber}\`.`
429
+ `\`npx ${cliRef()} code-review --pr-number ${prNumber}\`.`
429
430
  );
430
431
  }
431
432
  await commentOnIssue(token, prRepo.owner, prRepo.repo, prNum, partes.join('\n\n')).catch(() => {});
@@ -45,6 +45,7 @@ import { loadArtifact } from '../lib/doc-source.mjs';
45
45
  import { awaitingMergeBlock } from '../lib/artifact-pr.mjs';
46
46
  import { isAwaitingMerge } from '../lib/doc-source.mjs';
47
47
  import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
48
+ import { cliRef } from '../lib/cli-ref.mjs';
48
49
  import {
49
50
  renderDecompositionDoc, parseDecompositionDoc, DECOMPOSITION_FILE,
50
51
  } from '../lib/decomposition-doc.mjs';
@@ -721,7 +722,7 @@ export function renderBoardFailures(failures) {
721
722
  `${linhas}\n\n` +
722
723
  `Motivo: \`${motivo}\`\n\n` +
723
724
  'Verifique o `GH_PROJECT_TOKEN` (scope `project` e acesso ao Project da organização) e ' +
724
- 'reposicione os itens com `npx @spec-wave/cli@latest repair-stage <issue>`.\n\n' +
725
+ `reposicione os itens com \`npx ${cliRef()} repair-stage <issue>\`.\n\n` +
725
726
  'O run termina em VERMELHO de propósito — a decomposição em si CONCLUIU. ' +
726
727
  `Não reaplique \`${LABEL_DECOMPOSE_APPLY}\`: as issues acima já existem e o apply ` +
727
728
  'recomeça do zero; o que falta é só a Etapa, e quem repara isso é o `repair-stage`.'
@@ -936,7 +937,7 @@ async function createStoriesFromDoc(ctx, doc) {
936
937
 
937
938
  const list = created.map(s => `- ${s.url} — ${s.title}`).join('\n');
938
939
  const posicionamento = boardFailures.length === 0
939
- ? `Tudo posicionado em **✅ Ready**. Inicie o desenvolvimento com \`npx @spec-wave/cli@latest implement ${issueNumber}\` (Stories em ordem de dependência).`
940
+ ? `Tudo posicionado em **✅ Ready**. Inicie o desenvolvimento com \`npx ${cliRef()} implement ${issueNumber}\` (Stories em ordem de dependência).`
940
941
  : renderBoardFailures(boardFailures);
941
942
  await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10),
942
943
  `🔀 **Decomposição aplicada!**\n\n` +
@@ -1031,7 +1032,7 @@ async function createTasksFromDoc(ctx, doc) {
1031
1032
 
1032
1033
  const list = created.map(t => `- ${t.url} — ${t.title}`).join('\n');
1033
1034
  const posicionamento = boardFailures.length === 0
1034
- ? `Tudo posicionado em **✅ Ready**. Inicie o desenvolvimento com \`npx @spec-wave/cli@latest implement <task>\`.`
1035
+ ? `Tudo posicionado em **✅ Ready**. Inicie o desenvolvimento com \`npx ${cliRef()} implement <task>\`.`
1035
1036
  : renderBoardFailures(boardFailures);
1036
1037
  await commentOnIssue(token, owner, repo, parseInt(issueNumber, 10),
1037
1038
  `🔀 **Decomposição do RFC aplicada!**\n\n` +
@@ -39,6 +39,7 @@ import {
39
39
  } from '../lib/claude.mjs';
40
40
  import { CLI_VERSION } from '../lib/templates.mjs';
41
41
  import { parseDecompositionDoc, DECOMPOSITION_FILE } from '../lib/decomposition-doc.mjs';
42
+ import { cliRef } from '../lib/cli-ref.mjs';
42
43
 
43
44
  // Mesmo padrão de instanciação de github-rest.mjs, mas com o logger mudo:
44
45
  // aqui 404/403 são resultados esperados dos checks, não erros a logar.
@@ -306,7 +307,7 @@ async function checkConfig(ctx) {
306
307
  status: 'fail',
307
308
  detail:
308
309
  `${CONFIG_FILE} não encontrado em ${ctx.cwd} nem em nenhum diretório acima. ` +
309
- 'Rode `npx @spec-wave/cli@latest init`.',
310
+ `Rode \`npx ${cliRef()} init\`.`,
310
311
  };
311
312
  }
312
313
  if (ctx.cfgError) {
@@ -326,7 +327,7 @@ async function checkConfig(ctx) {
326
327
  status: 'warn',
327
328
  detail:
328
329
  notes.join('\n') +
329
- `\nproject.fields sem ${missingFields.map((f) => `"${f}"`).join(' e ')} — rode \`npx @spec-wave/cli@latest refresh\`.`,
330
+ `\nproject.fields sem ${missingFields.map((f) => `"${f}"`).join(' e ')} — rode \`npx ${cliRef()} refresh\`.`,
330
331
  };
331
332
  }
332
333
 
@@ -347,7 +348,7 @@ async function checkConfig(ctx) {
347
348
  status: 'warn',
348
349
  detail:
349
350
  notes.join('\n') +
350
- `\nOpções de Etapa do config ausentes no project real: ${diverged.join(', ')} — rode \`npx @spec-wave/cli@latest refresh\`.`,
351
+ `\nOpções de Etapa do config ausentes no project real: ${diverged.join(', ')} — rode \`npx ${cliRef()} refresh\`.`,
351
352
  };
352
353
  }
353
354
  notes.push(`Project "${snapshot.title}" verificado — campos Etapa/Status em sincronia.`);
@@ -619,7 +620,7 @@ async function checkBoardHygiene(ctx) {
619
620
  status = 'warn';
620
621
  notes.push(
621
622
  `Labels \`spec-wave:*\` descontinuadas ainda no repo: ${orphanLabels.join(', ')}. ` +
622
- 'Nenhum comando as honra — rode `npx @spec-wave/cli@latest update` para removê-las.'
623
+ `Nenhum comando as honra — rode \`npx ${cliRef()} update\` para removê-las.`
623
624
  );
624
625
  }
625
626
  if (missingLabels.length > 0) {
@@ -637,7 +638,7 @@ async function checkBoardHygiene(ctx) {
637
638
  `Labels de modelo ausentes no repo: ${missingModelLabels.join(', ')} — o apelido está em ` +
638
639
  '`ai.modelAliases`, mas a label não existe, então não há como aplicá-la numa issue e o ' +
639
640
  'override de modelo por execução fica indisponível. Rode ' +
640
- '`npx @spec-wave/cli@latest update` para criar todas' +
641
+ `\`npx ${cliRef()} update\` para criar todas` +
641
642
  (exemplo
642
643
  ? `, ou uma a uma: \`gh label create "${exemplo.name}" --color ${exemplo.color} ` +
643
644
  `--description "${exemplo.description}"\`.`
@@ -769,7 +770,7 @@ async function checkAi(ctx) {
769
770
  // a label criada no repo o override continua sem existir para quem abre a issue.
770
771
  const howTo = (
771
772
  `Cole no bloco \`ai\` do ${CONFIG_FILE}, commite e rode ` +
772
- '`npx @spec-wave/cli@latest update` para criar as labels correspondentes:'
773
+ `\`npx ${cliRef()} update\` para criar as labels correspondentes:`
773
774
  );
774
775
  if (!aliases) {
775
776
  notes.push(
@@ -1098,7 +1099,11 @@ export function checkSpecKit(ctx) {
1098
1099
  detail:
1099
1100
  'Nenhum comando configurado — `implement` só monta o contexto, sem acionar um agente.\n' +
1100
1101
  `Defina "specKit": { "command": "..." } no ${CONFIG_FILE} (ou a env SPEC_WAVE_IMPLEMENT_CMD).\n` +
1101
- 'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title}. Exemplos por agente:\n' +
1102
+ // A MESMA lista que o implement imprime quando o comando não está
1103
+ // configurado (commands/implement.mjs). Duas listas divergentes fazem o
1104
+ // doctor anunciar menos do que existe — foi o que aconteceu com
1105
+ // {workspaceDir}/{repoDirs}, que nasceram no multi-repo (RFC-005).
1106
+ 'Placeholders: {tasksFile} {specFile} {planFile} {issue} {type} {title} {workspaceDir} {repoDirs}. Exemplos por agente:\n' +
1102
1107
  ' Claude Code: claude -p "Implemente as tasks descritas em {tasksFile}"\n' +
1103
1108
  ' opencode: opencode run "Implemente as tasks descritas em {tasksFile}"\n' +
1104
1109
  ' Codex: codex exec "Implemente as tasks descritas em {tasksFile}"\n' +
@@ -1581,7 +1586,7 @@ async function checkWorkflows(ctx) {
1581
1586
  return {
1582
1587
  name,
1583
1588
  status: 'warn',
1584
- detail: '.github/workflows/ não encontrado — rode `npx @spec-wave/cli@latest init` (ou `update`) para instalar os workflows.',
1589
+ detail: `.github/workflows/ não encontrado — rode \`npx ${cliRef()} init\` (ou \`update\`) para instalar os workflows.`,
1585
1590
  };
1586
1591
  }
1587
1592
  const present = readdirSync(dir);
@@ -1594,7 +1599,7 @@ async function checkWorkflows(ctx) {
1594
1599
  return {
1595
1600
  name,
1596
1601
  status: 'warn',
1597
- detail: `Workflows faltando em .github/workflows/: ${missing.join(', ')} — rode \`npx @spec-wave/cli@latest update\`.`,
1602
+ detail: `Workflows faltando em .github/workflows/: ${missing.join(', ')} — rode \`npx ${cliRef()} update\`.`,
1598
1603
  };
1599
1604
  }
1600
1605
  if (role === 'code') {
@@ -1628,7 +1633,7 @@ async function checkWorkflows(ctx) {
1628
1633
  if (unpinned.length > 0) {
1629
1634
  status = 'warn';
1630
1635
  notes.push(
1631
- `Chamando \`@spec-wave/cli@latest\` (sem versão fixada): ${unpinned.join(', ')}. ` +
1636
+ `Chamando \`${cliRef()}\` (sem versão fixada): ${unpinned.join(', ')}. ` +
1632
1637
  'Uma release da CLI muda o comportamento de pipelines em andamento — rode `update`.'
1633
1638
  );
1634
1639
  }
@@ -1644,7 +1649,7 @@ async function checkWorkflows(ctx) {
1644
1649
  notes.push(
1645
1650
  `Não encaminham \`${provider.secret}\` (secret do provider ${provider.value}): ` +
1646
1651
  `${missingSecret.join(', ')}. Esses workflows vão falhar com "Faltam credenciais" — ` +
1647
- 'rode `npx @spec-wave/cli@latest update`.'
1652
+ `rode \`npx ${cliRef()} update\`.`
1648
1653
  );
1649
1654
  } else {
1650
1655
  notes.push(`Todos encaminham \`${provider.secret}\` (provider ${provider.value}).`);
@@ -33,6 +33,7 @@ import { loadArtifact, isAwaitingMerge } from '../lib/doc-source.mjs';
33
33
  import { awaitingMergeBlock, renderPrLine } from '../lib/artifact-pr.mjs';
34
34
  import { loadPrompt, systemPromptWithTools } from '../lib/prompt-loader.mjs';
35
35
  import { buildTechContext } from '../lib/tech-context.mjs';
36
+ import { cliRef } from '../lib/cli-ref.mjs';
36
37
  import {
37
38
  QA_PLAN_FILE, parseQaPlanDoc, renderQaPlanDoc, validateQaPlan,
38
39
  } from '../lib/qa-plan-doc.mjs';
@@ -88,13 +89,13 @@ export async function generateQaPlan({ issueNumber }) {
88
89
  `cobre esta Story com seções \`## Cenário N — Story #${number}\`.`
89
90
  : 'Não encontrei a Feature-pai desta Story — vincule-a como sub-issue de uma Feature e ' +
90
91
  `aplique \`${LABEL_QA}\` lá.`) +
91
- `\n\nPara **executar** os cenários desta Story: \`npx @spec-wave/cli@latest qa ${number}\`.`
92
+ `\n\nPara **executar** os cenários desta Story: \`npx ${cliRef()} qa ${number}\`.`
92
93
  ).catch(() => {});
93
94
  } else if (type === 'Bug') {
94
95
  await commentOnIssue(token, owner, repo, number,
95
96
  `ℹ️ **Bug não gera plano de QA:** o QA de um Bug usa a seção ` +
96
97
  '`Teste de Regressão` do próprio `bug.md`. ' +
97
- `Execute direto: \`npx @spec-wave/cli@latest qa ${number}\`.`
98
+ `Execute direto: \`npx ${cliRef()} qa ${number}\`.`
98
99
  ).catch(() => {});
99
100
  } else {
100
101
  await commentOnIssue(token, owner, repo, number,
@@ -414,7 +415,7 @@ async function runDraftOrCritique(ctx) {
414
415
  'execução avança a Etapa sozinho, então revise os cenários ANTES de rodar.\n\n' +
415
416
  revisao +
416
417
  'Depois execute localmente:\n' +
417
- `\`\`\`\nnpx @spec-wave/cli@latest qa ${number} --dry-run\nnpx @spec-wave/cli@latest qa ${number}\n\`\`\`\n` +
418
+ `\`\`\`\nnpx ${cliRef()} qa ${number} --dry-run\nnpx ${cliRef()} qa ${number}\n\`\`\`\n` +
418
419
  `Para uma nova crítica depois de editar, reaplique \`${LABEL_QA}\` — o arquivo é ` +
419
420
  'criticado como está, sem ser regerado. Para gerar outro do zero, apague o arquivo.'
420
421
  ).catch(err => console.warn(`Falha ao comentar a liberação: ${err.message}`));
@@ -35,6 +35,7 @@ import {
35
35
  slugsForItem, resolveWorkspaceLayout, readWorkspaceOverride, renderRepoDirs, codeReposForItems,
36
36
  } from '../lib/workspace.mjs';
37
37
  import { repoSlugsFromLabels } from '../lib/repo-role.mjs';
38
+ import { cliRef } from '../lib/cli-ref.mjs';
38
39
 
39
40
  const WORK_DIR = '.spec-wave';
40
41
 
@@ -498,7 +499,7 @@ export function buildFeatureContext({
498
499
  lines.push(
499
500
  '**Ao terminar, informe no relatório final:** os PRs ficam **empilhados** (cada um baseado no anterior) — ' +
500
501
  'o merge é **ordem-dependente**. Depois da revisão humana (marcar cada PR como pronto), o merge é ' +
501
- `\`npx @spec-wave/cli@latest merge ${feature.number}\`: ele mergeia na ordem das dependências, ` +
502
+ `\`npx ${cliRef()} merge ${feature.number}\`: ele mergeia na ordem das dependências, ` +
502
503
  'reaponta as bases, move o board até 🧪 QA e só apaga as branches no fim. ' +
503
504
  '**NUNCA** mergeie um PR da pilha com `--delete-branch` à mão — apagar a branch antes de reapontar o dependente fecha o PR seguinte.'
504
505
  );
@@ -5,6 +5,7 @@ import path from 'node:path';
5
5
  import { CONFIG_FILE, PORTAL_URL } from '../config.mjs';
6
6
  import { findConfigPath } from '../lib/project-root.mjs';
7
7
  import { skillStatus } from './install-skill.mjs';
8
+ import { cliRef } from '../lib/cli-ref.mjs';
8
9
 
9
10
  // Resume o estado da skill para a saída JSON. `null` = não foi possível checar.
10
11
  function skillJson(status) {
@@ -24,7 +25,7 @@ function reportSkill(status) {
24
25
  if (status.agentsDetected.length === 0) {
25
26
  p.log.warn(
26
27
  'Nenhum agente de código detectado neste diretório — a skill spec-wave ' +
27
- 'não parece instalada. Rode `npx @spec-wave/cli@latest install-skill`.'
28
+ `não parece instalada. Rode \`npx ${cliRef()} install-skill\`.`
28
29
  );
29
30
  return;
30
31
  }
@@ -35,7 +36,7 @@ function reportSkill(status) {
35
36
  p.log.warn(
36
37
  'Skill pendente de instalação/atualização:\n' +
37
38
  status.pending.map(s => ` ${chalk.yellow('↻')} ${s.agent} (${s.reason}) — ${chalk.dim(s.path)}`).join('\n') +
38
- '\nRode `npx @spec-wave/cli@latest install-skill` (ou `npx @spec-wave/cli@latest update`).'
39
+ `\nRode \`npx ${cliRef()} install-skill\` (ou \`npx ${cliRef()} update\`).`
39
40
  );
40
41
  }
41
42
 
@@ -56,7 +57,7 @@ export async function info(options = {}) {
56
57
  p.log.warn(`Este repositório ${chalk.bold('não foi inicializado')} (sem ${CONFIG_FILE}).`);
57
58
  reportSkill(skill);
58
59
  p.log.info(`🌐 Acesse o Portal Web da ferramenta em ${chalk.cyan(PORTAL_URL)}`);
59
- p.outro('Execute `npx @spec-wave/cli@latest init` para configurar.');
60
+ p.outro(`Execute \`npx ${cliRef()} init\` para configurar.`);
60
61
  return;
61
62
  }
62
63
 
@@ -18,6 +18,7 @@ import { REPO_ROLES, DEFAULT_REPO_ROLE, parseRepoRef } from '../lib/repo-role.mj
18
18
  // (SPEC_WAVE_CLI_VERSION) — este comando roda dentro de um bundle no init
19
19
  // server-side da UI, onde não existe package.json dois níveis acima.
20
20
  import { CLI_VERSION } from '../lib/templates.mjs';
21
+ import { cliRef } from '../lib/cli-ref.mjs';
21
22
 
22
23
  export async function init(options) {
23
24
  // --- Papel (RFC-005) ---
@@ -314,7 +315,7 @@ export async function init(options) {
314
315
  ` Próximos passos:\n` +
315
316
  (configWritten ? ` 1. Commite o ${CONFIG_FILE} (git add ${CONFIG_FILE} && git commit) — os despachantes o leem em runtime\n` : '') +
316
317
  ` ${configWritten ? '2' : '1'}. Autenticação do despacho para o hub: a GitHub App da org (secrets SPEC_WAVE_APP_ID + SPEC_WAVE_APP_PRIVATE_KEY, App instalada nos dois repos) ou o secret ${HUB_DISPATCH_SECRET} com um token de escrita em Contents no hub\n` +
317
- ` ${configWritten ? '3' : '2'}. No hub, rode \`npx @spec-wave/cli@latest update\` para instalar o pr-events.yml (recebe os despachos)\n` +
318
+ ` ${configWritten ? '3' : '2'}. No hub, rode \`npx ${cliRef()} update\` para instalar o pr-events.yml (recebe os despachos)\n` +
318
319
  ` ${configWritten ? '4' : '3'}. Registre este repo no hub: \`repositories: [{ "slug": "<slug>", "owner": "${owner}", "repo": "${repo}" }]\` no ${CONFIG_FILE} do hub\n` +
319
320
  ` ${chalk.dim('(o slug vai na label repo:<slug> das Stories — minúsculas, [a-z0-9-], até 39 caracteres, e não muda depois)')}\n\n` +
320
321
  ` Nos PRs deste repo, vincule a Story com \`Closes ${hub.owner}/${hub.repo}#<n>\` — a forma qualificada é a que o hub reconhece.`
@@ -350,7 +351,7 @@ export async function init(options) {
350
351
  ` ${configWritten ? '3' : '2'}. Configure o board view para agrupar por "Etapa"\n` +
351
352
  ` ${configWritten ? '4' : '3'}. Crie uma Feature com o prefixo [FEATURE] no título\n` +
352
353
  ` ${configWritten ? '5' : '4'}. Use a skill spec-wave para guiar o fluxo\n\n` +
353
- ` ${chalk.dim('Para instalar a skill no seu agente: npx @spec-wave/cli@latest install-skill')}\n\n` +
354
+ ` ${chalk.dim('Para instalar a skill no seu agente: npx ${cliRef()} install-skill')}\n\n` +
354
355
  ` 🌐 Acesse o Portal Web da ferramenta em ${chalk.cyan(PORTAL_URL)}`
355
356
  );
356
357
  }
@@ -5,6 +5,7 @@ import { homedir } from 'node:os';
5
5
  import path from 'node:path';
6
6
  import { parseSkill } from '../lib/skill-file.mjs';
7
7
  import { listPluginSkills, planPluginSkillFiles } from '../lib/plugin-skills.mjs';
8
+ import { pinCliRefs } from '../lib/cli-ref.mjs';
8
9
  // TEMPLATES_DIR e CLI_VERSION já tratam os escapes de empacotamento
9
10
  // (SPEC_WAVE_TEMPLATES_DIR / SPEC_WAVE_CLI_VERSION) — ver lib/templates.mjs.
10
11
  import { TEMPLATES_DIR, CLI_VERSION } from '../lib/templates.mjs';
@@ -104,6 +105,10 @@ export { parseSkill };
104
105
 
105
106
  // Banner de versão inserido no topo do corpo da skill instalada. O agente lê
106
107
  // esta linha e, se `npx @spec-wave/cli@latest --version` for maior, orienta reinstalar.
108
+ // `@latest` PERMANECE aqui: o banner entra na skill e a saída inteira do
109
+ // render passa por `pinCliRefs`, que o troca pela major de quem instalou.
110
+ // Chamar `cliRef()` daqui leria o config do cwd de quem gera, não de quem
111
+ // recebe a cópia — duas fontes para a mesma decisão.
107
112
  export function versionBanner(version) {
108
113
  return (
109
114
  `> ⚙️ **spec-wave skill v${version}** — esta skill é uma cópia estática. ` +
@@ -114,7 +119,21 @@ export function versionBanner(version) {
114
119
  }
115
120
 
116
121
  // Converte o SKILL.md para o formato exigido por cada agente, carimbando a versão.
122
+ //
123
+ // A saída passa inteira por `pinCliRefs`: o arquivo-fonte guarda
124
+ // `@spec-wave/cli@latest` (legível, sem versão a manter à mão) e a CÓPIA
125
+ // instalada sai presa à MAJOR de quem a instalou — um agente que leia a skill e
126
+ // execute literalmente não atravessa a fronteira 0.x ↔ 1.x (lib/cli-ref.mjs).
127
+ //
128
+ // Inteira, e não só o corpo, por causa do frontmatter: `allowed-tools` traz
129
+ // `Bash(npx @spec-wave/cli@latest *)`, que é uma PERMISSÃO. Pinar os comandos e
130
+ // deixar a permissão em `@latest` faria o agente pedir aprovação a cada chamada
131
+ // — o padrão precisa casar com o que a skill manda rodar.
117
132
  export function renderContent(format, parsed, version) {
133
+ return pinCliRefs(renderContentRaw(format, parsed, version), version);
134
+ }
135
+
136
+ function renderContentRaw(format, parsed, version) {
118
137
  const { meta, frontmatter, body } = parsed;
119
138
  const description = meta.description ?? 'Skill spec-wave.';
120
139
  const banner = versionBanner(version);
@@ -24,6 +24,7 @@ import {
24
24
  configuredMode, variableValueFor, describeModeState, shouldWriteVariable,
25
25
  } from '../lib/execution-mode.mjs';
26
26
  import { loadConfig } from '../lib/project-root.mjs';
27
+ import { cliRef } from '../lib/cli-ref.mjs';
27
28
 
28
29
  /**
29
30
  * Workflows instalados que NÃO carregam a guarda (função quase pura — só lê o fs).
@@ -56,7 +57,7 @@ export async function mode({ target, dryRun = false } = {}) {
56
57
 
57
58
  const { config, root, configPath } = loadConfig();
58
59
  if (!config) {
59
- p.log.error(`${CONFIG_FILE} não encontrado — rode \`npx @spec-wave/cli@latest init\` antes.`);
60
+ p.log.error(`${CONFIG_FILE} não encontrado — rode \`npx ${cliRef()} init\` antes.`);
60
61
  process.exit(1);
61
62
  }
62
63
 
@@ -166,7 +167,7 @@ export async function mode({ target, dryRun = false } = {}) {
166
167
  if (alvo === 'local' && semGuarda.length > 0) {
167
168
  p.log.warn(
168
169
  `Estes workflows instalados ainda não têm a guarda \`${EXECUTION_GUARD}\` e vão rodar mesmo assim: ` +
169
- `${semGuarda.join(', ')}. Rode \`npx @spec-wave/cli@latest update\`.`
170
+ `${semGuarda.join(', ')}. Rode \`npx ${cliRef()} update\`.`
170
171
  );
171
172
  }
172
173
 
@@ -47,6 +47,7 @@ import { createExecutionBackend, containerScript } from '../lib/qa-lead-backend.
47
47
  import { pushWithRebase } from '../lib/git-retry.mjs';
48
48
  import { CLI_VERSION } from '../lib/templates.mjs';
49
49
  import { CONFIG_FILE, LABEL_QA, LABEL_QA_READY, LABEL_CRITIQUE_FAILED, labelNames } from '../config.mjs';
50
+ import { cliRef } from '../lib/cli-ref.mjs';
50
51
 
51
52
  // Intervalo mínimo entre aplicações de label (§6.1): cada uma dispara um run
52
53
  // do Actions, e uma rajada satura a fila.
@@ -79,7 +80,7 @@ async function bootstrap(milestoneArg) {
79
80
  if (!configPath) {
80
81
  throw new QaLeadRefusal(
81
82
  `Repositório não inicializado (sem ${CONFIG_FILE}). ` +
82
- 'Rode `npx @spec-wave/cli@latest init` (ou a skill setup) primeiro.'
83
+ `Rode \`npx ${cliRef()} init\` (ou a skill setup) primeiro.`
83
84
  );
84
85
  }
85
86
  const { config, root } = loadConfig();
@@ -39,6 +39,7 @@ import {
39
39
  resolveQaEvidenceConfig,
40
40
  } from '../lib/qa-exec.mjs';
41
41
  import { pushWithRebase } from '../lib/git-retry.mjs';
42
+ import { cliRef } from '../lib/cli-ref.mjs';
42
43
  import {
43
44
  aggregateVerdict, validateQaResults, combineWithPrevious, parseLastQaReport,
44
45
  renderQaReport, renderQaBugDoc, qaOriginMarker, matchesQaOrigin, shortSha,
@@ -240,7 +241,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
240
241
  if (!configPath) {
241
242
  throw new QaRefusal(
242
243
  `Repositório não inicializado (sem ${CONFIG_FILE}). ` +
243
- 'Rode `npx @spec-wave/cli@latest init` (ou a skill setup) primeiro.'
244
+ `Rode \`npx ${cliRef()} init\` (ou a skill setup) primeiro.`
244
245
  );
245
246
  }
246
247
  const { config, root } = loadConfig();
@@ -649,7 +650,7 @@ export async function qaRun({ issue: issueArg, only: onlyArg, severity: severity
649
650
  ? `❌ **O teste de regressão ainda reprova** — o fix não cobriu o defeito. O Bug permanece ` +
650
651
  `em **${STAGE_QA}** (Status ${PROGRESS_IN_PROGRESS}); nenhum Bug novo foi aberto (é o mesmo defeito).`
651
652
  : `O item permanece em **${STAGE_QA}** (Status ${PROGRESS_IN_PROGRESS}). Corrija o(s) Bug(s) e ` +
652
- `re-teste com \`npx @spec-wave/cli@latest qa <story> --only <cenário>\`.`,
653
+ `re-teste com \`npx ${cliRef()} qa <story> --only <cenário>\`.`,
653
654
  });
654
655
  process.exitCode = 1;
655
656
  return { verdict, bugs };
@@ -860,7 +861,7 @@ async function openBugsForFailures({
860
861
  `📄 \`${fileRel}\` foi escrito, commitado e publicado com as seis seções preenchidas a partir ` +
861
862
  'do cenário e da saída real da execução (exceção documentada à regra do `spec-wave:bug` — ' +
862
863
  'conteúdo determinístico de uma execução observada, sem IA).\n\n' +
863
- `Após o fix, re-teste: \`npx @spec-wave/cli@latest qa ${storyNumber} --only ${scenario.numero}\``
864
+ `Após o fix, re-teste: \`npx ${cliRef()} qa ${storyNumber} --only ${scenario.numero}\``
864
865
  ).catch(() => {});
865
866
 
866
867
  bugs.push({ number: created.number, cenario: scenario.numero, existing: false });
@@ -14,6 +14,7 @@ import {
14
14
  codeRepositories, linkRepository, unlinkRepository, parseRepoRef, repoLabelSpec,
15
15
  } from '../lib/repo-role.mjs';
16
16
  import { CONFIG_FILE } from '../config.mjs';
17
+ import { cliRef } from '../lib/cli-ref.mjs';
17
18
 
18
19
  export async function repoCommand({ action, slug, repo: repoArg, dryRun = false, json = false } = {}) {
19
20
  if (!['link', 'unlink', 'list'].includes(action)) {
@@ -95,7 +96,7 @@ export async function repoCommand({ action, slug, repo: repoArg, dryRun = false,
95
96
 
96
97
  p.note(
97
98
  `1. Commite o ${CONFIG_FILE} (os workflows do hub leem repositories[] da branch default).\n` +
98
- `2. No repositório de código: npx @spec-wave/cli@latest init --role code --repo ${target.owner}/${target.repo} --hub ${ctx.owner}/${ctx.repo}\n` +
99
+ `2. No repositório de código: npx ${cliRef()} init --role code --repo ${target.owner}/${target.repo} --hub ${ctx.owner}/${ctx.repo}\n` +
99
100
  `3. Nas Stories, declare \`**Repos:** ${slug}\` no decomposition.md (vira a label ${spec.name}).`,
100
101
  'Próximos passos'
101
102
  );
@@ -27,6 +27,7 @@ import { planPluginSkillFiles } from '../lib/plugin-skills.mjs';
27
27
  import { findConfigPath } from '../lib/project-root.mjs';
28
28
  import { configuredRole } from '../lib/repo-role.mjs';
29
29
  import { currentGitBranch } from '../lib/repo-links.mjs';
30
+ import { cliRef } from '../lib/cli-ref.mjs';
30
31
 
31
32
  // Arquivos do repo gerenciados pela CLI (comparados com o template empacotado).
32
33
  const REPO_FILES = [
@@ -645,7 +646,7 @@ export async function update(options = {}) {
645
646
  let configContent = null;
646
647
  if (configStale) {
647
648
  if (!configStale.canApply) {
648
- p.log.warn(`${CONFIG_FILE}: sem project.id — pulei. Rode \`npx @spec-wave/cli@latest init\` (sem --skip-project).`);
649
+ p.log.warn(`${CONFIG_FILE}: sem project.id — pulei. Rode \`npx ${cliRef()} init\` (sem --skip-project).`);
649
650
  } else {
650
651
  const tk = role === 'code' ? null : await getToken();
651
652
  if (role !== 'code' && !tk) {
@@ -0,0 +1,75 @@
1
+ // Como a CLI se refere a si mesma quando MANDA alguém executá-la.
2
+ //
3
+ // Duas linhas de release convivem (RFC-005 §8.3): `branch-0.35` (LTS) e a 1.x.
4
+ // **As 0.x são compatíveis entre si; a 1.x NÃO é compatível com a 0.x.** Nesse
5
+ // mundo, `npx @spec-wave/cli@latest` numa instrução é uma armadilha: um
6
+ // repositório da linha 0.35 que segue a própria mensagem — ou um agente que lê
7
+ // a skill instalada e executa literalmente — atravessa a fronteira de major sem
8
+ // ninguém pedir, e o `update` seguinte reescreve os workflows para a outra.
9
+ //
10
+ // A referência sai como a MAJOR em que o repositório está (`@spec-wave/cli@0`,
11
+ // `@spec-wave/cli@1`), não como a versão exata. É o alcance certo para uma
12
+ // instrução: dentro da major, tudo é compatível, então quem segue pega as
13
+ // correções da própria linha; a barreira fica onde de fato existe.
14
+ //
15
+ // Nos WORKFLOWS a regra é outra, e continua sendo a versão exata
16
+ // (`{{CLI_VERSION}}`, ver lib/templates.mjs): ali o que se quer é
17
+ // reprodutibilidade — uma release não pode mudar o comportamento de um pipeline
18
+ // em andamento. Instrução quer compatibilidade; pipeline quer imutabilidade.
19
+
20
+ import { readFileSync } from 'node:fs';
21
+ import { findConfigPath } from './project-root.mjs';
22
+ import { CLI_VERSION } from './templates.mjs';
23
+
24
+ export const PKG = '@spec-wave/cli';
25
+
26
+ /** Major de um semver (`1.0.7` → `1`); null quando não dá para ler. */
27
+ export function majorOf(version) {
28
+ const m = /^\s*v?(\d+)\./.exec(String(version ?? ''));
29
+ return m ? m[1] : null;
30
+ }
31
+
32
+ /**
33
+ * Major da linha em que o repositório está congelado (função PURA — `cwd`
34
+ * injetável). Nunca lança: config ausente, ilegível ou sem `version` cai na
35
+ * major da CLI em execução.
36
+ *
37
+ * @param {string} [cwd]
38
+ * @returns {string}
39
+ */
40
+ export function pinnedMajor(cwd = process.cwd()) {
41
+ const daCli = majorOf(CLI_VERSION) ?? '1';
42
+ try {
43
+ const configPath = findConfigPath(cwd);
44
+ if (!configPath) return daCli;
45
+ return majorOf(JSON.parse(readFileSync(configPath, 'utf-8')).version) ?? daCli;
46
+ } catch {
47
+ return daCli;
48
+ }
49
+ }
50
+
51
+ /**
52
+ * `@spec-wave/cli@<major>` para usar em instruções — no lugar de `@latest`.
53
+ *
54
+ * @param {string} [cwd]
55
+ * @returns {string}
56
+ */
57
+ export function cliRef(cwd = process.cwd()) {
58
+ return `${PKG}@${pinnedMajor(cwd)}`;
59
+ }
60
+
61
+ /**
62
+ * Troca `@spec-wave/cli@latest` pela major dada, em qualquer texto (função
63
+ * PURA). É o que pina as skills instaladas: o arquivo-fonte guarda `@latest`
64
+ * (legível, sem versão a manter à mão) e a CÓPIA gravada no projeto do usuário
65
+ * sai presa à major da CLI que a instalou.
66
+ *
67
+ * @param {string} text
68
+ * @param {string} version versão completa; só a major é usada
69
+ * @returns {string}
70
+ */
71
+ export function pinCliRefs(text, version) {
72
+ const major = majorOf(version);
73
+ if (!major) return String(text ?? '');
74
+ return String(text ?? '').replaceAll(`${PKG}@latest`, `${PKG}@${major}`);
75
+ }
@@ -14,6 +14,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
14
14
 
15
15
  import { CONFIG_FILE } from '../config.mjs';
16
16
  import { findConfigPath } from './project-root.mjs';
17
+ import { cliRef } from './cli-ref.mjs';
17
18
 
18
19
  /**
19
20
  * Serialização canônica do config (função PURA).
@@ -40,7 +41,7 @@ export function updateConfig(mutator, { cwd = process.cwd() } = {}) {
40
41
  const configPath = findConfigPath(cwd);
41
42
  if (!configPath) {
42
43
  throw new Error(
43
- `${CONFIG_FILE} não encontrado — rode \`npx @spec-wave/cli@latest init\` neste repositório.`,
44
+ `${CONFIG_FILE} não encontrado — rode \`npx ${cliRef()} init\` neste repositório.`,
44
45
  );
45
46
  }
46
47
 
@@ -16,6 +16,8 @@
16
16
  // "onde este processo está rodando AGORA" (GITHUB_ACTIONS); este responde "onde
17
17
  // o repositório decidiu que o fluxo roda".
18
18
 
19
+ import { cliRef } from './cli-ref.mjs';
20
+
19
21
  export const EXECUTION_MODES = ['actions', 'local'];
20
22
  export const DEFAULT_EXECUTION_MODE = 'actions';
21
23
 
@@ -105,14 +107,14 @@ export function describeModeState({ configured, variable, unguardedWorkflows = [
105
107
  `Modo local, mas \`${EXECUTION_VARIABLE}\` ${variable === null ? 'não existe' : `vale "${variable}"`} ` +
106
108
  'no repositório — os workflows CONTINUAM disparando e consumindo minutos.'
107
109
  );
108
- fixes.push('Rode `npx @spec-wave/cli@latest mode local` (ou defina a variável em Settings → Actions → Variables).');
110
+ fixes.push(`Rode \`npx ${cliRef()} mode local\` (ou defina a variável em Settings → Actions → Variables).`);
109
111
  } else {
110
112
  status = 'problem';
111
113
  notes.push(
112
114
  `Modo actions, mas \`${EXECUTION_VARIABLE}\`="${variable}" está setada — os workflows ` +
113
115
  'são pulados e nada roda até alguém rodar o comando local.'
114
116
  );
115
- fixes.push('Rode `npx @spec-wave/cli@latest mode actions` para remover a variável.');
117
+ fixes.push(`Rode \`npx ${cliRef()} mode actions\` para remover a variável.`);
116
118
  }
117
119
 
118
120
  if (configured === 'local' && unguardedWorkflows.length > 0) {
@@ -121,7 +123,7 @@ export function describeModeState({ configured, variable, unguardedWorkflows = [
121
123
  `Workflows instalados sem a guarda \`${EXECUTION_GUARD}\`: ${unguardedWorkflows.join(', ')} — ` +
122
124
  'esses vão rodar de qualquer jeito.'
123
125
  );
124
- fixes.push('Rode `npx @spec-wave/cli@latest update` para publicar os workflows com a guarda.');
126
+ fixes.push(`Rode \`npx ${cliRef()} update\` para publicar os workflows com a guarda.`);
125
127
  }
126
128
 
127
129
  const summary = configured === 'local'
@@ -23,6 +23,7 @@
23
23
  import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
24
24
  import path from 'node:path';
25
25
  import { fileURLToPath } from 'node:url';
26
+ import { pinCliRefs } from './cli-ref.mjs';
26
27
 
27
28
  const __dir = path.dirname(fileURLToPath(import.meta.url));
28
29
 
@@ -86,7 +87,16 @@ export function listPluginSkills(skillsDir = PLUGIN_SKILLS_DIR) {
86
87
  * @param {(v: string) => string} banner
87
88
  * @returns {string}
88
89
  */
90
+ // A saída passa inteira por `pinCliRefs` — inclusive frontmatter e banner, pelo
91
+ // mesmo motivo do install-skill: a cópia instalada fica presa à MAJOR de quem a
92
+ // instalou, e o `allowed-tools` casa com os comandos que a skill manda rodar.
93
+ // Vale para TODO arquivo da skill, não só o SKILL.md: os supporting files
94
+ // também trazem comandos.
89
95
  export function renderPluginSkillFile(relPath, raw, version, banner) {
96
+ return pinCliRefs(renderPluginSkillFileRaw(relPath, raw, version, banner), version);
97
+ }
98
+
99
+ function renderPluginSkillFileRaw(relPath, raw, version, banner) {
90
100
  if (relPath !== 'SKILL.md') return raw;
91
101
  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
92
102
  if (!match) return `${banner(version)}\n\n${raw.trim()}\n`;
@@ -8,6 +8,7 @@
8
8
 
9
9
  import { createHash } from 'node:crypto';
10
10
  import { REQUIRED_BUG_SECTIONS, QA_BLOCKED_REASONS } from '../config.mjs';
11
+ import { cliRef } from './cli-ref.mjs';
11
12
 
12
13
  export const QA_REPORT_VERSION = 1;
13
14
 
@@ -551,7 +552,7 @@ export function renderQaBugDoc({
551
552
  `Re-executar o cenário reprovado após o fix:`,
552
553
  '',
553
554
  '```bash',
554
- `npx @spec-wave/cli@latest qa ${scenario.story} --only ${scenario.numero}`,
555
+ `npx ${cliRef()} qa ${scenario.story} --only ${scenario.numero}`,
555
556
  '```',
556
557
  '',
557
558
  `O veredito precisa ser **pass** com o mesmo esperado: ${scenario.esperado || '—'}`,
@@ -167,6 +167,9 @@ export function renderSummarySection(skills) {
167
167
  '',
168
168
  'Cada uma existe como skill dedicada do plugin (`/spec-wave:<nome>`) — e os',
169
169
  'utilitários de board estão flag a flag na *Referência da CLI* acima. Rode',
170
+ // `@latest` PERMANECE aqui: este texto vai para o SKILL.md FONTE, que é
171
+ // commitado. Quem pina é a instalação (install-skill → pinCliRefs), com a
172
+ // major de quem instalou — não a de quem rodou `skill:gen`.
170
173
  '`npx @spec-wave/cli@latest <comando> --help` para os parâmetros.',
171
174
  '',
172
175
  ];
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "spec-wave",
3
3
  "displayName": "Spec Wave",
4
- "version": "1.0.6",
4
+ "version": "1.0.8",
5
5
  "description": "Fluxo spec-driven no GitHub (RFC-001): Projects v2, labels de gatilho, spec/plan gerados por Action, decomposição em duas etapas e implementação orientada a Stories/Tasks.",
6
6
  "author": {
7
7
  "name": "Astratech",
@@ -46,7 +46,7 @@ jobs:
46
46
  owner="$(jq -r '.hub.owner // ""' .spec-wave.json)"
47
47
  name="$(jq -r '.hub.repo // ""' .spec-wave.json)"
48
48
  if [ -z "$owner" ] || [ -z "$name" ]; then
49
- echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@latest init --role code --repo ${{ github.repository }} --hub <owner/repo>"
49
+ echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@{{CLI_VERSION}} init --role code --repo ${{ github.repository }} --hub <owner/repo>"
50
50
  exit 1
51
51
  fi
52
52
  echo "owner=$owner" >> "$GITHUB_OUTPUT"
@@ -45,7 +45,7 @@ jobs:
45
45
  owner="$(jq -r '.hub.owner // ""' .spec-wave.json)"
46
46
  name="$(jq -r '.hub.repo // ""' .spec-wave.json)"
47
47
  if [ -z "$owner" ] || [ -z "$name" ]; then
48
- echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@latest init --role code --repo ${{ github.repository }} --hub <owner/repo>"
48
+ echo "::error::.spec-wave.json sem hub {owner, repo}. Rode: npx @spec-wave/cli@{{CLI_VERSION}} init --role code --repo ${{ github.repository }} --hub <owner/repo>"
49
49
  exit 1
50
50
  fi
51
51
  echo "owner=$owner" >> "$GITHUB_OUTPUT"